如何以异步方式使用语言服务功能

  • 项目

语言服务允许使用 REST API 或客户端库以异步方式发送 API 请求。 你还可以在请求中包含要同时对数据执行的多个不同语言服务功能。

目前，可以异步方式使用以下功能：

  • 实体链接
  • 文档摘要
  • 对话摘要
  • 关键短语提取
  • 语言检测
  • 命名实体识别 (NER)
  • 客户内容检测
  • 情绪分析和观点挖掘
  • 运行状况文本分析
  • 个人身份信息 (PII)

发送异步请求时，你将根据请求中包含的文本记录数支付每个功能的费用。 例如，如果为情绪分析和 NER 发送了一条文本记录，则会算作发送了两条文本记录，因此你将根据定价层支付这两条记录的费用。

使用 REST API 提交异步作业

若要提交异步作业，请查看要在请求中发送的 JSON 正文的参考文档。

  1. 将文档添加到 analysisInput 对象。
  2. 在 tasks 对象中，包括要对数据执行的操作。 例如，若要执行情绪分析，请包含 SentimentAnalysisLROTask 对象。
  3. 可以选择：
    1. 选择用于数据的特定模型版本。
    2. 在 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 错误。

请参阅