了解用于生成对话语言理解模型的资源

9 分钟

若要使用语言理解服务开发 NLP 解决方案，需要在 Azure 中创建语言资源。该资源将用于创作模型和处理来自客户端应用程序的预测请求。

提示

本模块的实验室介绍如何构建用于对话语言理解的模型。有关自定义文本分类和自定义命名实体识别的更多重点模块，请参阅开发自然语言解决方案学习路径中的自定义解决方案模块。

构建你的模型

对于需要模型进行预测的功能，需要先生成、训练并部署模型，才能将其用于预测。通过生成和训练让 Azure AI 语言服务学习要查找的内容。

首先，需要在 Azure 门户中创建 Azure AI 语言资源。然后：

搜索 Azure AI 服务。
查找并选择“语言服务”。
选择“语言服务”下的“创建”。
填写必要的详细信息，选择在地理位置上最靠近的区域（以获得最佳性能），并为其提供唯一的名称。

创建该资源后，需要密钥和终结点。可以在资源概述页的“密钥和终结点”下的左侧找到该信息。

使用语言工作室

若要更直观地生成、训练和部署模型，可以使用 Language Studio 来实现上述每个步骤。在主页上，可以选择创建对话语言理解项目。创建项目后，请完成与上述内容相同的过程来生成、训练和部署模型。

本模块中的实验室将逐步讲解如何使用 Language Studio 生成模型。若要了解详细信息，请参阅 Language Studio 快速入门

使用 REST API

生成模型的一种方法是通过 REST API 生成。该模式是创建项目、导入数据、训练、部署，然后使用模型。

这些任务以异步方式完成；需要向每个步骤的相应 URI 提交请求，然后发送另一个请求以获取该作业的状态。

例如，如果要为对话语言理解项目部署模型，则需要提交部署作业，然后检查部署作业状态。

身份验证

对于对 Azure AI 语言资源的每个调用，可以通过提供以下标头对请求进行身份验证。

密钥	值
`Ocp-Apim-Subscription-Key`	资源密钥

请求部署

将 POST 请求提交到以下终结点。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}?api-version={API-VERSION}

占位符	值	示例
`{ENDPOINT}`	Azure AI 语言资源的终结点	`https://<your-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	项目名称。此值区分大小写	`myProject`
`{DEPLOYMENT-NAME}`	部署名称。此值区分大小写	`staging`
`{API-VERSION}`	要调用的 API 版本	`2022-05-01`

请在请求中包括以下 body。

{
  "trainedModelLabel": "{MODEL-NAME}",
}

占位符	值
`{MODEL-NAME}`	将要分配给部署的模型名称。此值区分大小写。

若成功提交请求，将收到 202 响应，并带有响应标头 operation-location。此标头将具有一个 URL，用于请求状态，格式如下所示：

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

获取部署状态

将 GET 请求提交到上述响应标头中的 URL。这些值已根据初始部署请求填写。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

占位符	值
`{ENDPOINT}`	用于对 API 请求进行身份验证的终结点
`{PROJECT-NAME}`	项目名称（值区分大小写）
`{DEPLOYMENT-NAME}`	部署名称（值区分大小写）
`{JOB-ID}`	用于查找模型训练状态的 ID，可在上文部署请求中详述的标头值中找到
`{API-VERSION}`	要调用的 API 版本

响应正文将提供部署状态详细信息。当部署完成时，status 字段的值会为“已成功”。

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"String",
    "lastUpdatedDateTime":"String",
    "expirationDateTime":"String",
    "status":"running"
}

若要查看示例请求的每个步骤的完整演练，请参阅对话理解快速入门。

查询你的模型

若要查询模型以进行预测，可以使用 C# 或 Python 中的 SDK，也可以使用 REST AP。

使用 SDK 进行查询

若要使用 SDK 查询你的模型，你首先需要创建客户端。具有客户端后，即可使用它来调用相应的终结点。

var languageClient = new TextAnalyticsClient(endpoint, credentials);
var response = languageClient.ExtractKeyPhrases(document);

language_client = TextAnalyticsClient(
            endpoint=endpoint, 
            credential=credentials)
response = language_client.extract_key_phrases(documents = documents)[0]

其他语言功能（例如对话语言理解）要求以不同的方式构建和发送请求。

var data = new
{
    analysisInput = new
    {
        conversationItem = new
        {
            text = userText,
            id = "1",
            participantId = "1",
        }
    },
    parameters = new
    {
        projectName,
        deploymentName,
        // Use Utf16CodeUnit for strings in .NET.
        stringIndexType = "Utf16CodeUnit",
    },
    kind = "Conversation",
};
Response response = await client.AnalyzeConversationAsync(RequestContent.Create(data));

result = client.analyze_conversation(
    task={
        "kind": "Conversation",
        "analysisInput": {
            "conversationItem": {
                "participantId": "1",
                "id": "1",
                "modality": "text",
                "language": "en",
                "text": query
            },
            "isLoggingEnabled": False
        },
        "parameters": {
            "projectName": cls_project,
            "deploymentName": deployment_slot,
            "verbose": True
        }
    }
)

使用 REST API 进行查询

若要使用 REST 查询你的模型，请使用指定的相应正文创建对相应 URL 的 POST 请求。对于内置功能（如语言检测或情绪分析），你将查询 analyze-text 终结点。

提示

请记住，每个请求都需要使用 Ocp-Apim-Subscription-Key 标头中的 Azure AI 语言资源密钥进行身份验证

{ENDPOINT}/language/:analyze-text?api-version={API-VERSION}

占位符	值
`{ENDPOINT}`	用于对 API 请求进行身份验证的终结点
`{API-VERSION}`	要调用的 API 版本

在该请求的正文中，必须指定 kind 参数，该参数告知服务你所请求的语言理解类型。

例如，如果想要检测语言，则 JSON 正文将如下所示。

{
    "kind": "LanguageDetection",
    "parameters": {
        "modelVersion": "latest"
    },
    "analysisInput":{
        "documents":[
            {
                "id":"1",
                "text": "This is a document written in English."
            }
        ]
    }
}

其他语言功能（例如对话语言理解）要求将请求路由到其他终结点。例如，对话语言理解请求将被发送到以下位置。

{ENDPOINT}/language/:analyze-conversations?api-version={API-VERSION}

占位符	值
`{ENDPOINT}`	用于对 API 请求进行身份验证的终结点
`{API-VERSION}`	要调用的 API 版本

该请求将包含类似于以下内容的 JSON 正文。

{
  "kind": "Conversation",
  "analysisInput": {
    "conversationItem": {
      "id": "1",
      "participantId": "1",
      "text": "Sample text"
    }
  },
  "parameters": {
    "projectName": "{PROJECT-NAME}",
    "deploymentName": "{DEPLOYMENT-NAME}",
    "stringIndexType": "TextElement_V8"
  }
}

占位符	值
`{PROJECT-NAME}`	生成模型的项目的名称
`{DEPLOYMENT-NAME}`	部署的名称

示例响应

来自 SDK 的查询响应将出现在返回的对象中，具体取决于功能（例如在 response.key_phrases 或 response.Value 中）。 REST API 将返回类似于以下内容的 JSON。

{
    "kind": "KeyPhraseExtractionResults",
    "results": {
        "documents": [{
            "id": "1",
            "keyPhrases": ["modern medical office", "Dr. Smith", "great staff"],
            "warnings": []
        }],
        "errors": [],
        "modelVersion": "{VERSION}"
    }
}

对于对话语言理解等其他模型，对查询的示例响应将类似于以下内容。

{
  "kind": "ConversationResult",
  "result": {
    "query": "String",
    "prediction": {
      "topIntent": "intent1",
      "projectKind": "Conversation",
      "intents": [
        {
          "category": "intent1",
          "confidenceScore": 1
        },
        {
          "category": "intent2",
          "confidenceScore": 0
        }
      ],
      "entities": [
        {
          "category": "entity1",
          "text": "text",
          "offset": 7,
          "length": 4,
          "confidenceScore": 1
        }
      ]
    }
  }
}

Python 和 C# 的 SDK 返回与 REST 响应非常相似的 JSON。

有关功能的完整文档（包括示例和操作指南），请参阅 Azure AI 语言文档的文档页。