如何以异步方式使用语言服务功能
语言服务允许使用 REST API 或客户端库以异步方式发送 API 请求。 你还可以在请求中包含要同时对数据执行的多个不同语言服务功能。
目前,可以异步方式使用以下功能:
- 实体链接
- 文档摘要
- 对话摘要
- 关键短语提取
- 语言检测
- 命名实体识别 (NER)
- 客户内容检测
- 情绪分析和观点挖掘
- 运行状况文本分析
- 个人身份信息 (PII)
发送异步请求时,你将根据请求中包含的文本记录数支付每个功能的费用。 例如,如果为情绪分析和 NER 发送了一条文本记录,则会算作发送了两条文本记录,因此你将根据定价层支付这两条记录的费用。
使用 REST API 提交异步作业
若要提交异步作业,请查看要在请求中发送的 JSON 正文的参考文档。
- 将文档添加到
analysisInput
对象。 - 在
tasks
对象中,包括要对数据执行的操作。 例如,若要执行情绪分析,请包含SentimentAnalysisLROTask
对象。 - 可以选择:
- 选择用于数据的特定模型版本。
- 在
tasks
对象中包含要同时对数据执行的其他语言服务功能。
为请求创建 JSON 正文后,将密钥添加到 Ocp-Apim-Subscription-Key
头。 然后将 API 请求发送到作业创建终结点。 例如:
POST https://your-endpoint.cognitiveservices.azure.cn/language/analyze-text/jobs?api-version=2022-05-01
成功的调用将返回 202 响应代码。 响应头中的 operation-location
是用于检索 API 结果的 URL。 值将如下 URL 所示:
GET {Endpoint}/language/analyze-text/jobs/12345678-1234-1234-1234-12345678?api-version=2022-05-01
若要获取状态并检索请求的结果,请将 GET 请求发送到在先前 API 响应的 operation-location
头中收到的 URL。 请记得将密钥包含在 Ocp-Apim-Subscription-Key
中。 响应将包含 API 调用结果。
使用客户端库发送异步 API 请求
首先,确保为所选的语言安装了客户端库。 有关安装客户端库的步骤,请参阅要使用的功能的快速入门文章。
然后,使用客户端对象向 API 发送异步调用。 要使用的方法调用根据语言而异。 请使用可用的示例和参考文档来帮助自己入门。
结果可用性
以异步方式使用此功能时,API 结果在引入请求时的 24 小时内可用,并在响应中指示。 在此时间段后,结果将被清除,并且不再可用于检索。
自动语言检测
从 REST API 版本 2022-07-01-preview
开始,可以请求对文档执行自动语言检测。 通过将 language
参数设置为 auto
,检测到的文本语言代码将作为响应中的语言值返回。 此语言检测不会对语言资源产生额外费用。
数据限制
注意
- 如果需要分析的文档的大小超出限制,则可将文本拆分成较小的文本块,然后再将其发送到 API。
- 文档是由文本字符构成的单个字符串。
在异步请求包含的所有文档中最多可以发送 125,000 个字符,发送的字符数由 StringInfo.LengthInTextElements 度量。 此字符数限制高于同步请求数限制,目的是实现更高的吞吐量。
如果文档超过字符数限制,则 API 将拒绝整个请求并返回 400 bad request
错误。