通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：自定义健康状况文本分析

  • 项目

注意

运行状况自定义文本分析（预览版）将于 2025 年 1 月 10 日停用，请迁移到其他自定义模型训练服务，例如 Azure AI 语言中的自定义命名实体识别。 从现在到 2025 年 1 月 10 日，可以在现有项目中继续使用自定义文本分析（预览版），而不会中断。 你无法创建新项目。 在 2025 年 1 月 10 日，在运行状况自定义文本分析上运行的工作负荷（预览版）将被删除，关联的项目数据将丢失。

使用本文开始创建自定义健康状况文本分析项目，在该项目中，可在健康状况文本分析的基础上训练自定义模型来进行自定义实体识别。 模型是经过训练可以完成特定任务的人工智能软件。 对于该系统，模型提取与医疗相关的命名实体并通过学习带标签的数据进行训练。

本文使用 Language Studio 来演示自定义健康状况文本分析的关键概念。 例如，我们将构建一个自定义健康状况文本分析模型来从简短的出院记录中提取设施或治疗地点。

先决条件

我遇到了问题

创建新的 Azure AI 语言资源和 Azure 存储帐户

需要先创建 Azure AI 语言资源（该资源将提供创建项目和开始训练模型所需的凭据），然后才能使用自定义健康状况文本分析。 此外，还需要一个 Azure 存储帐户，使用该帐户，可以上传用于生成模型的数据集。

重要

要快速开始，建议使用本文中提供的步骤新建 Azure AI 语言资源。 使用本文中的步骤可同时创建语言资源和存储帐户，这比以后再做更容易。

如果想要使用预先存在的资源，则需要将其连接到存储帐户。 有关信息，请参阅预先存在的资源的使用指南。

从 Azure 门户创建新资源

  1. 若要创建新的 Azure AI 语言资源，请登录 Azure 门户。

  2. 在出现的窗口中，从自定义功能中选择“自定义文本分类和自定义命名实体识别”。 单击屏幕底部的“继续创建资源”。

    显示 Azure 门户中的自定义文本分类和自定义命名实体识别的屏幕截图。

  3. 创建包含以下详细信息的语言资源。

    名称 说明
    订阅 Azure 订阅。
    资源组 将包含资源的资源组。 可以使用现有资源组，也可以新建一个。
    区域 语言资源的区域。 例如，“美国西部 2”。
    名称 资源的名称。
    定价层 语言资源的定价层。 可以使用免费 (F0) 定价层试用该服务。

    注意

    如果收到一条消息“登录帐户不是所选存储帐户资源组的所有者”，则帐户需要在资源组上分配一个所有者角色，然后才能创建语言资源。 请联系 Azure 订阅所有者寻求帮助。

  4. 在“自定义文本分类和自定义命名实体识别”部分，选择现有存储帐户或选择“新建存储帐户”。 这些值用于帮助你快速入门，不一定是你希望在生产环境中使用的存储帐户值。 为避免在生成项目时出现延迟，请连接到与语言资源位于同一区域的存储帐户。

    存储帐户值 建议的值
    存储帐户名称 任何名称
    存储帐户类型 标准 LRS

  5. 确保选中“负责任的 AI 通知”。 在页面底部选择“查看 + 创建”，然后选择“创建”。

我遇到了问题

将示例数据上传到 Blob 容器

创建 Azure 存储帐户并将其连接到语言资源后，需要将示例数据集中的文档上传到容器的根目录。 稍后将使用这些文档来训练模型。

  1. 从 GitHub 下载示例数据集。

  2. 打开 .zip 文件，然后解压缩包含文档的文件夹。

  3. 在 Azure 门户中，导航到你创建的存储帐户，然后选择它。

  4. 在存储帐户中，从位于“数据存储”下方的左侧菜单中选择“容器”。 在出现的屏幕上，选择“+ 容器”。 将容器命名为“example-data”并保留默认的“公共访问级别”。

    显示存储帐户主页的屏幕截图。

  5. 创建容器后，选择该容器。 然后选择“上传”按钮以选择之前下载的 .txt 和 .json 文件。

    显示用于将文件上传到存储帐户的按钮的屏幕截图。

提供的样本数据集包含 12 份临床记录。 每份临床记录都包含几个医疗实体和治疗地点。 我们将使用预生成的实体来提取医疗实体，并训练自定义模型，以使用实体的习得组件和列表组件提取治疗地点。

我遇到了问题

创建自定义健康状况文本分析项目

配置资源和存储帐户后，创建新的自定义健康状况文本分析项目。 项目是一个基于数据构建自定义 ML 模型的工作区。 只有你和对所使用的语言资源具有访问权限的其他人才能访问你的项目。

  1. 登录到 Language Studio。 随即将出现一个窗口，供你选择订阅和语言资源。 选择在上一步中创建的语言资源。

  2. 在 Language Studio 的“提取信息”部分下，选择“自定义健康状况文本分析”。

  3. 从项目页的顶部菜单中选择“创建新项目”。 创建项目后，可以标记数据，训练、评估、改进和部署模型。

    项目创建页的屏幕截图。

  4. 输入项目信息，包括名称、说明和项目中文件的语言。 如果使用示例数据集，请选择“英语”。 以后无法更改项目名称。 选择“下一步”

    提示

    你的数据集无须完全使用同一语言。 你可以有多个文档，每个文档都支持不同的语言。 如果数据集包含不同语言的文档，或者你在运行时需要不同语言的文本，请在输入项目基本信息时选择“启用多语言数据集”选项。 稍后可以从“项目设置”页面启用此选项。

  5. 选择“创建新项目”后，将会显示用于连接存储帐户的屏幕。 如果已连接了存储帐户，将看到该存储帐户已连接。 如果未显示，请从显示的下拉列表中选择你的存储帐户，然后选择“连接存储帐户”；这将为你的存储帐户设置所需的角色。 如果你没有被指定为存储帐户的“所有者”，此步骤可能会返回错误。

    注意

    • 只需为使用的每个新资源执行一次此步骤。
    • 此过程是不可逆的，如果将一个存储帐户连接到你的语言资源，以后将无法断开其连接。
    • 只能将你的语言资源连接到一个存储帐户。

    显示存储连接屏幕的屏幕截图。

  6. 选择你上传数据集的容器。

  7. 如果已标记数据，请确保它遵循支持的格式，并选择“是，我的文件已标记，并且我已设置 JSON 标签文件的格式”，然后从下拉菜单中选择标签文件。 选择“下一页”。 如果你使用的是快速入门中的数据集，则无需查看 JSON 标签文件的格式设置。

  8. 查看输入的数据，并选择“创建项目”。

我遇到了问题

训练模型

通常，在创建项目后，将继续开始标记连接到项目的容器中的文档。 在本快速入门中，你已导入示例标记数据集并使用示例 JSON 标签文件对项目进行了初始化，因此无需添加其他标签。

若要在 Language Studio 中开始训练模型，请执行以下操作：

  1. 在左侧菜单中，选择“训练作业”。

  2. 从顶部菜单中选择“启动训练作业”。

  3. 然后选择“训练新模型”并在文本框中键入模型名称。 还可以通过选择“覆盖现有模型”选项并从下拉菜单中选择要覆盖的模型来覆盖现有模型。 覆盖已训练的模型是不可逆的，但这在部署新模型之前不会影响已部署的模型。

    显示 Language Studio 中的训练作业创建屏幕的屏幕截图。

  4. 选择数据拆分方法。 可以选择“从训练数据中自动拆分测试集”，系统将根据指定的百分比在训练集和测试集之间拆分标记数据。 也可以选择“使用手动拆分训练和测试数据”，仅当已将文档添加到测试集时才会启用此选项。 有关数据拆分的信息，请参阅数据标签和如何训练模型。

  5. 选择“训练”按钮。

  6. 如果从列表中选择训练作业 ID，则会显示一个侧窗格，可在其中检查此作业的“训练进度”、“作业状态”和其他详细信息。

    注意

    • 只有成功完成的训练作业才会生成模型。
    • 训练可能需要几分钟到几个小时，具体取决于已标记数据的大小。
    • 一次只能运行一个训练作业。 在运行的作业完成之前，无法在同一项目中启动其他训练作业。

我遇到了问题

部署模型

通常，训练模型后，你会查看其评估详细信息，并在必要时进行改进。 在本快速入门中，你只需部署模型，使其在 Language Studio 中可供试用，你也可以调用预测 API。

若要要从 Language Studio 中部署模型，请执行以下操作：

  1. 在左侧菜单中，选择“部署模型”。

  2. 选择“添加部署”，以开始新部署作业。

    显示 Language Studio 中的部署按钮的屏幕截图。

  3. 选择“创建新部署”以创建新的部署，并从下面的下拉列表中分配已训练的模型。 还可以通过选择“覆盖现有部署”选项来覆盖现有部署，然后从下面的下拉列表中选择要为其分配的已训练的模型。

    注意

    覆盖现有部署不需要更改预测 API 调用，但产生的结果将基于新分配的模型。

    显示 Language Studio 中的模型部署选项的屏幕截图。

  4. 选择“部署”以启动部署作业。

  5. 部署成功后，旁边将显示到期日期。 部署到期是指已部署的模型将无法用于预测，这通常发生在训练配置到期后的 12 个月。

我遇到了问题

测试模型

部署模型后，可以开始使用模型通过预测 API 从文本中提取实体。 在本快速入门中，将使用 Language Studio 提交自定义健康状况文本分析任务并直观呈现结果。 在之前下载的示例数据集中，可以找到一些可在此步骤中使用的测试文档。

若要在 Language Studio 中测试已部署的模型，请执行以下操作：

  1. 在左侧菜单中，选择“测试部署”。

  2. 选择要测试的部署。 只能测试分配给部署的模型。

  3. 从下拉列表中选择要查询/测试的部署。

  4. 可以输入要提交到请求的文本，或上传要使用的 .txt 文件。

  5. 选择顶部菜单中的“运行测试”。

  6. 在“结果”选项卡中，可以看到从文本中提取的实体及其类型。 还可以在“JSON”选项卡下查看 JSON 响应。

    显示 Language Studio 中部署测试屏幕的屏幕截图。

我遇到了问题

清理资源

如果不再需要项目，可以使用 Language Studio 删除项目。

  1. 在页面顶部选择你在使用的语言服务功能，
  2. 选择要删除的项目
  3. 从顶部菜单中选择“删除”。

我遇到了问题

先决条件

我遇到了问题

创建新的 Azure AI 语言资源和 Azure 存储帐户

需要先创建 Azure AI 语言资源（该资源将提供创建项目和开始训练模型所需的凭据），然后才能使用自定义健康状况文本分析。 此外，还需要一个 Azure 存储帐户，你在该帐户中可以上传要用于生成模型的数据集。

重要

要快速开始，建议使用本文提供的步骤创建新的 Azure AI 语言资源，以支持你在创建语言资源的同时创建和/或连接存储帐户，这比以后再执行该操作要更容易。

如果想要使用预先存在的资源，则需要将其连接到存储帐户。 有关详细信息，请参阅创建项目。

从 Azure 门户创建新资源

  1. 若要创建新的 Azure AI 语言资源，请登录 Azure 门户。

  2. 在出现的窗口中，从自定义功能中选择“自定义文本分类和自定义命名实体识别”。 单击屏幕底部的“继续创建资源”。

    显示 Azure 门户中的自定义文本分类和自定义命名实体识别的屏幕截图。

  3. 创建包含以下详细信息的语言资源。

    名称 说明
    订阅 Azure 订阅。
    资源组 将包含资源的资源组。 可以使用现有资源组，也可以新建一个。
    区域 语言资源的区域。 例如，“美国西部 2”。
    名称 资源的名称。
    定价层 语言资源的定价层。 可以使用免费 (F0) 定价层试用该服务。

    注意

    如果收到一条消息“登录帐户不是所选存储帐户资源组的所有者”，则帐户需要在资源组上分配一个所有者角色，然后才能创建语言资源。 请联系 Azure 订阅所有者寻求帮助。

  4. 在“自定义文本分类和自定义命名实体识别”部分，选择现有存储帐户或选择“新建存储帐户”。 这些值用于帮助你快速入门，不一定是你希望在生产环境中使用的存储帐户值。 为避免在生成项目时出现延迟，请连接到与语言资源位于同一区域的存储帐户。

    存储帐户值 建议的值
    存储帐户名称 任何名称
    存储帐户类型 标准 LRS

  5. 确保选中“负责任的 AI 通知”。 在页面底部选择“查看 + 创建”，然后选择“创建”。

我遇到了问题

将示例数据上传到 Blob 容器

创建 Azure 存储帐户并将其连接到语言资源后，需要将示例数据集中的文档上传到容器的根目录。 稍后将使用这些文档来训练模型。

  1. 从 GitHub 下载示例数据集。

  2. 打开 .zip 文件，然后解压缩包含文档的文件夹。

  3. 在 Azure 门户中，导航到你创建的存储帐户，然后选择它。

  4. 在存储帐户中，从位于“数据存储”下方的左侧菜单中选择“容器”。 在出现的屏幕上，选择“+ 容器”。 将容器命名为“example-data”并保留默认的“公共访问级别”。

    显示存储帐户主页的屏幕截图。

  5. 创建容器后，选择该容器。 然后选择“上传”按钮以选择之前下载的 .txt 和 .json 文件。

    显示用于将文件上传到存储帐户的按钮的屏幕截图。

提供的样本数据集包含 12 份临床记录。 每份临床记录都包含几个医疗实体和治疗地点。 我们将使用预生成的实体来提取医疗实体，并训练自定义模型，以使用实体的习得组件和列表组件提取治疗地点。

我遇到了问题

获取资源密钥和终结点

  1. 在 Azure 门户中，转到资源概述页

  2. 在左侧菜单中，选择“密钥和终结点”。 你将为 API 请求使用终结点和密钥

    显示 Azure 门户中的“密钥和终结点”页的屏幕截图

我遇到了问题

创建自定义健康状况文本分析项目

配置资源和存储帐户后，创建新的自定义健康状况文本分析项目。 项目是一个基于数据构建自定义 ML 模型的工作区。 只有你和对所使用的语言资源具有访问权限的其他人才能访问你的项目。

使用在上一步中从示例数据下载的标签文件，并将其添加到以下请求的正文中。

触发导入项目作业

使用以下 URL、标头和 JSON 正文提交 POST 请求，以导入标签文件。 请确保标签文件遵循接受的格式。

如果已存在同名的项目，则替换该项目的数据。

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/:import?api-version={API-VERSION}
占位符 值 示例
{ENDPOINT} 用于对 API 请求进行身份验证的终结点。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 项目名称。 此值区分大小写。 myProject
{API-VERSION} 要调用的 API 版本。 此处引用的值适用于最新发布的版本。 请参阅模型生命周期，了解有关其他可用 API 版本的详细信息。 2022-05-01

头文件

使用以下标头对请求进行身份验证。

键 值
Ocp-Apim-Subscription-Key 资源密钥。 用于对 API 请求进行身份验证。

Body

在请求中使用以下 JSON。 请将以下占位符值替换为你自己的值。

{
	"projectFileVersion": "{API-VERSION}",
	"stringIndexType": "Utf16CodeUnit",
	"metadata": {
		"projectName": "{PROJECT-NAME}",
		"projectKind": "CustomHealthcare",
		"description": "Trying out custom Text Analytics for health",
		"language": "{LANGUAGE-CODE}",
		"multilingual": true,
		"storageInputContainerName": "{CONTAINER-NAME}",
		"settings": {}
	},
	"assets": {
		"projectKind": "CustomHealthcare",
		"entities": [
			{
				"category": "Entity1",
				"compositionSetting": "{COMPOSITION-SETTING}",
				"list": {
					"sublists": [
						{
							"listKey": "One",
							"synonyms": [
								{
									"language": "en",
									"values": [
										"EntityNumberOne",
										"FirstEntity"
									]
								}
							]
						}
					]
				}
			},
			{
				"category": "Entity2"
			},
			{
				"category": "MedicationName",
				"list": {
					"sublists": [
						{
							"listKey": "research drugs",
							"synonyms": [
								{
									"language": "en",
									"values": [
										"rdrug a",
										"rdrug b"
									]
								}
							]

						}
					]
				}
				"prebuilts": "MedicationName"
			}
		],
		"documents": [
			{
				"location": "{DOCUMENT-NAME}",
				"language": "{LANGUAGE-CODE}",
				"dataset": "{DATASET}",
				"entities": [
					{
						"regionOffset": 0,
						"regionLength": 500,
						"labels": [
							{
								"category": "Entity1",
								"offset": 25,
								"length": 10
							},
							{
								"category": "Entity2",
								"offset": 120,
								"length": 8
							}
						]
					}
				]
			},
			{
				"location": "{DOCUMENT-NAME}",
				"language": "{LANGUAGE-CODE}",
				"dataset": "{DATASET}",
				"entities": [
					{
						"regionOffset": 0,
						"regionLength": 100,
						"labels": [
							{
								"category": "Entity2",
								"offset": 20,
								"length": 5
							}
						]
					}
				]
			}
		]
	}
}
密钥 占位符 值 示例
multilingual true 通过布尔值，你可以在数据集中有多种语言的文档，并且在部署模型时可以使用任何支持的语言（不一定包含在训练文档中）查询模型。 请参阅语言支持，了解有关多语言支持的详细信息。 true
projectName {PROJECT-NAME} 项目名称 myproject
storageInputContainerName {CONTAINER-NAME} 容器名称 mycontainer
entities 一个数组，其中包含项目中的所有实体类型。 这些是将从文档提取到的实体类型。
category 实体类型的名称，可以是用户为新实体定义所定义的名称，也可以是预生成实体的预定义名称。
compositionSetting {COMPOSITION-SETTING} 定义如何在实体中管理多个组件的规则。 选项是 combineComponents 或 separateComponents。 combineComponents
list 包含项目中特定实体的所有子列表的数组。 可以将列表添加到预生成实体或具有已学习组件的新实体。
sublists [] 包含子列表的数组。 每个子列表都包含一个键及其关联的值。 []
listKey One 在预测中要映射回的同义词列表的规范化值。 One
synonyms [] 包含所有同义词的数组 同义词 (synonym)
language {LANGUAGE-CODE} 指定子列表中同义词语言代码的字符串。 如果项目是多语言项目，并且你希望支持项目中所有语言的同义词列表，则必须将同义词显式添加到每种语言。 有关受支持的语言代码的详细信息，请参阅语言支持。 en
values "EntityNumberone"、"FirstEntity" 将完全匹配的逗号分隔字符串的列表，用于提取并映射到列表键。 "EntityNumberone"、"FirstEntity"
prebuilts MedicationName 填充预生成实体的预生成组件的名称。 默认情况下，预生成的实体会自动加载到项目中，但你可以使用标签文件中的列表组件扩展它们。 MedicationName
documents 一个数组，其中包含项目中的所有文档和每个文档中标记的实体列表。 []
location {DOCUMENT-NAME} 存储容器中文档的位置。 由于所有文档都位于容器的根目录中，因此这应为文档名称。 doc1.txt
dataset {DATASET} 此文件在训练前拆分时将归类到的测试集。 此字段的可能值为 Train 和 Test。 Train
regionOffset 文本开头的非独占字符位置。 0
regionLength 以 UTF16 字符表示的边界框长度。 训练仅考虑此区域的数据。 500
category 与指定文本跨度关联的实体类型。 Entity1
offset 实体文本的起始位置。 25
length 以 UTF16 字符表示的实体长度。 20
language {LANGUAGE-CODE} 指定项目中所使用文档的语言代码的字符串。 如果项目是多语言项目，请选择大多数文档的语言代码。 有关受支持的语言代码的详细信息，请参阅语言支持。 en

发送 API 请求后，你将收到 202 响应，这表明作业已正确提交。 在响应头中，提取 operation-location 值。 其格式如下：

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

{JOB-ID} 用于标识请求，因为此操作是异步操作。 你将使用此 URL 获取导入作业状态。

此请求可能出现的错误情况：

  • 所选资源不具有该存储帐户的适当权限。
  • 指定的 storageInputContainerName 不存在。
  • 使用了无效的语言代码，或者语言代码类型不是字符串。
  • multilingual 值是一个字符串，而不是布尔值。

我遇到了问题

获取导入作业状态

使用以下 GET 请求获取导入项目的状态。 请将以下占位符值替换为你自己的值。

请求 URL

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}
占位符 值 示例
{ENDPOINT} 用于对 API 请求进行身份验证的终结点。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 项目名称。 此值区分大小写。 myProject
{JOB-ID} 用于查找模型训练状态的 ID。 该值包含在上一步骤中收到的 location 标头值中。 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} 要调用的 API 版本。 此处引用的值适用于最新发布的版本。 请参阅模型生命周期，了解有关其他可用 API 版本的详细信息。 2022-05-01

头文件

使用以下标头对请求进行身份验证。

键 值
Ocp-Apim-Subscription-Key 资源密钥。 用于对 API 请求进行身份验证。

我遇到了问题

训练模型

通常，在创建项目后，将继续开始标记连接到项目的容器中的文档。 对于本快速入门，你已导入示例标记数据集并使用示例 JSON 标记文件对项目进行了初始化。

启动训练作业

导入项目后，就可以开始训练模型了。

使用以下 URL、标头和 JSON 正文提交 POST 请求以提交训练作业。 将占位符值替换为你自己的值。

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/:train?api-version={API-VERSION}
占位符 值 示例
{ENDPOINT} 用于对 API 请求进行身份验证的终结点。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 项目名称。 此值区分大小写。 myProject
{API-VERSION} 要调用的 API 版本。 此处引用的值适用于最新发布的版本。 请参阅模型生命周期，了解有关其他可用 API 版本的详细信息。 2022-05-01

头文件

使用以下标头对请求进行身份验证。

键 值
Ocp-Apim-Subscription-Key 资源密钥。 用于对 API 请求进行身份验证。

请求正文

在请求正文中使用以下 JSON。 完成训练后，该模型将命名为 {MODEL-NAME}。 只有成功的训练作业才会生成模型。

{
	"modelLabel": "{MODEL-NAME}",
	"trainingConfigVersion": "{CONFIG-VERSION}",
	"evaluationOptions": {
		"kind": "percentage",
		"trainingSplitPercentage": 80,
		"testingSplitPercentage": 20
	}
}
密钥 占位符 值 示例
modelLabel {MODEL-NAME} 成功训练后，将会分配给模型的模型名称。 myModel
trainingConfigVersion {CONFIG-VERSION} 这是用于训练模型的模型版本。 2022-05-01
evaluationOptions 用于将数据拆分为训练集和测试集的选项。 {}
kind percentage 拆分方法。 可能的值为 percentage 或 manual。 有关详细信息，请参阅如何训练模型。 percentage
trainingSplitPercentage 80 要包含在训练集中的已标记数据的百分比。 建议的值为 80。 80
testingSplitPercentage 20 要包含在测试集中的已标记数据的百分比。 建议的值为 20。 20

注意

仅当 Kind 设置为 percentage 时 trainingSplitPercentage 和 testingSplitPercentage 才是必需的，并且两个百分比的总和应等于 100。

发送 API 请求后，你将收到 202 响应，这表明作业已正确提交。 在响应头中，提取 location 值。 它的格式如下：

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

{JOB-ID} 用于标识请求，因为此操作是异步操作。 可以使用此 URL 获取训练状态。

我遇到了问题

获取训练作业状态

对于该示例数据集，训练可能需要 10 - 30 分钟。 可以使用以下请求持续轮询训练作业的状态，直到成功完成训练作业。

使用以下 GET 请求来获取模型在训练过程中的状态。 请将以下占位符值替换为你自己的值。

请求 URL

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}
占位符 值 示例
{ENDPOINT} 用于对 API 请求进行身份验证的终结点。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 项目名称。 此值区分大小写。 myProject
{JOB-ID} 用于查找模型训练状态的 ID。 该值包含在上一步骤中收到的 location 标头值中。 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} 要调用的 API 版本。 此处引用的值适用于最新发布的版本。 请参阅模型生命周期，了解有关其他可用 API 版本的详细信息。 2022-05-01

头文件

使用以下标头对请求进行身份验证。

键 值
Ocp-Apim-Subscription-Key 资源密钥。 用于对 API 请求进行身份验证。

响应正文

发送请求后，你将获得以下响应。

{
  "result": {
    "modelLabel": "{MODEL-NAME}",
    "trainingConfigVersion": "{CONFIG-VERSION}",
    "estimatedEndDateTime": "2022-04-18T15:47:58.8190649Z",
    "trainingStatus": {
      "percentComplete": 3,
      "startDateTime": "2022-04-18T15:45:06.8190649Z",
      "status": "running"
    },
    "evaluationStatus": {
      "percentComplete": 0,
      "status": "notStarted"
    }
  },
  "jobId": "{JOB-ID}",
  "createdDateTime": "2022-04-18T15:44:44Z",
  "lastUpdatedDateTime": "2022-04-18T15:45:48Z",
  "expirationDateTime": "2022-04-25T15:44:44Z",
  "status": "running"
}

我遇到了问题

部署模型

通常，训练模型后，你会查看其评估详细信息，并在必要时进行改进。 在本快速入门中，你只需部署模型，使其在 Language Studio 中可供试用，你也可以调用预测 API。

启动部署作业

使用以下 URL、标头和 JSON 正文提交 PUT 请求，以提交部署作业。 请将以下占位符值替换为你自己的值。

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/deployments/{deploymentName}?api-version={API-VERSION}
占位符 值 示例
{ENDPOINT} 用于对 API 请求进行身份验证的终结点。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 项目名称。 此值区分大小写。 myProject
{DEPLOYMENT-NAME} 部署的名称。 此值区分大小写。 staging
{API-VERSION} 要调用的 API 版本。 此处引用的值适用于最新发布的版本。 请参阅模型生命周期，了解有关其他可用 API 版本的详细信息。 2022-05-01

头文件

使用以下标头对请求进行身份验证。

键 值
Ocp-Apim-Subscription-Key 资源密钥。 用于对 API 请求进行身份验证。

请求正文

在请求正文中使用以下 JSON。 使用要分配给部署的模型名称。

{
  "trainedModelLabel": "{MODEL-NAME}"
}
密钥 占位符 值 示例
trainedModelLabel {MODEL-NAME} 将要分配给部署的模型名称。 只能分配已成功训练的模型。 此值区分大小写。 myModel

发送 API 请求后，你将收到 202 响应，这表明作业已正确提交。 在响应头中，提取 operation-location 值。 其格式如下：

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

{JOB-ID} 用于标识请求，因为此操作是异步操作。 你可使用此 URL 获取部署状态。

我遇到了问题

获取部署作业状态

使用以下 GET 请求来查询部署作业的状态。 可以使用在上一步中收到的 URL，或者将下面的占位符值替换为你自己的值。

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}
占位符 值 示例
{ENDPOINT} 用于对 API 请求进行身份验证的终结点。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 项目名称。 此值区分大小写。 myProject
{DEPLOYMENT-NAME} 部署的名称。 此值区分大小写。 staging
{JOB-ID} 用于查找模型训练状态的 ID。 这是在上一步骤中收到的 location 标头值。 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} 要调用的 API 版本。 此处引用的值适用于最新发布的版本。 请参阅模型生命周期，了解有关其他可用 API 版本的详细信息。 2022-05-01

头文件

使用以下标头对请求进行身份验证。

键 值
Ocp-Apim-Subscription-Key 资源密钥。 用于对 API 请求进行身份验证。

响应正文

发送请求后，将会收到以下请求。 继续轮询此终结点，直到“状态”参数变为“已成功”。 应获取一个 200 代码来指示请求的成功。

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

我遇到了问题

使用已训练的模型进行预测

部署模型后，可以开始使用模型通过预测 API 从文本中提取实体。 在之前下载的示例数据集中，可以找到一些可在此步骤中使用的测试文档。

提交自定义健康状况文本分析任务

使用此 POST 请求启动健康状况自定义文本分析提取任务。

{ENDPOINT}/language/analyze-text/jobs?api-version={API-VERSION}
占位符 值 示例
{ENDPOINT} 用于对 API 请求进行身份验证的终结点。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{API-VERSION} 要调用的 API 版本。 此处引用的值适用于最新发布的版本。 请参阅模型生命周期，了解有关其他可用 API 版本的详细信息。 2022-05-01

头文件

键 价值
Ocp-Apim-Subscription-Key 你的密钥，用于提供对此 API 的访问权限。

Body

{
  "displayName": "Extracting entities",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
     {
      "kind": "CustomHealthcare",
      "taskName": "Custom TextAnalytics for Health Test",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}
键 占位符 值 示例
displayName {JOB-NAME} 作业名称。 MyJobName
documents [{},{}] 要对其运行任务的文档列表。 [{},{}]
id {DOC-ID} 文档名称或 ID。 doc1
language {LANGUAGE-CODE} 指定文档语言代码的字符串。 如果未指定此密钥，该服务将假定在项目创建时选择项目的默认语言。 有关支持语言代码的列表，请参阅语言支持。 en-us
text {DOC-TEXT} 要对其运行任务的文档任务。 Lorem ipsum dolor sit amet
tasks 要执行的任务列表。 []
taskName Custom Text Analytics for Health Test 任务名称 Custom Text Analytics for Health Test
kind CustomHealthcare 我们尝试执行的项目或任务类型 CustomHealthcare
parameters 要传递给任务的参数列表。
project-name {PROJECT-NAME} 项目名称。 此值区分大小写。 myProject
deployment-name {DEPLOYMENT-NAME} 部署的名称。 此值区分大小写。 prod

响应

你将收到 202 响应，它指示任务已成功提交。 在响应头中，提取 operation-location。 operation-location 的格式如下：

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}

可以使用此 URL 查询任务完成状态，并在任务完成时获取结果。

我遇到了问题

获取任务结果

使用以下 GET 请求查询自定义实体识别任务的状态/结果。

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}
占位符 值 示例
{ENDPOINT} 用于对 API 请求进行身份验证的终结点。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{API-VERSION} 要调用的 API 版本。 此处引用的值适用于最新发布的版本。 请参阅模型生命周期，了解有关其他可用 API 版本的详细信息。 2022-05-01

头文件

键 价值
Ocp-Apim-Subscription-Key 你的密钥，用于提供对此 API 的访问权限。

响应正文

响应是具有以下参数的 JSON 文档

{
	"createdDateTime": "2021-05-19T14:32:25.578Z",
	"displayName": "MyJobName",
	"expirationDateTime": "2021-05-19T14:32:25.578Z",
	"jobId": "xxxx-xxxx-xxxxx-xxxxx",
	"lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
	"status": "succeeded",
	"tasks": {
		"completed": 1,
		"failed": 0,
		"inProgress": 0,
		"total": 1,
		"items": [
			{
				"kind": "CustomHealthcareLROResults",
				"taskName": "Custom Text Analytics for Health Test",
				"lastUpdateDateTime": "2020-10-01T15:01:03Z",
				"status": "succeeded",
				"results": {
					"documents": [
						{
							"entities": [
								{
									"entityComponentInformation": [
										{
											"entityComponentKind": "learnedComponent"
										}
									],
									"offset": 0,
									"length": 11,
									"text": "first entity",
									"category": "Entity1",
									"confidenceScore": 0.98
								},
								{
									"entityComponentInformation": [
										{
											"entityComponentKind": "listComponent"
										}
									],
									"offset": 0,
									"length": 11,
									"text": "first entity",
									"category": "Entity1.Dictionary",
									"confidenceScore": 1.0
								},
								{
									"entityComponentInformation": [
										{
											"entityComponentKind": "learnedComponent"
										}
									],
									"offset": 16,
									"length": 9,
									"text": "entity two",
									"category": "Entity2",
									"confidenceScore": 1.0
								},
								{
									"entityComponentInformation": [
										{
											"entityComponentKind": "prebuiltComponent"
										}
									],
									"offset": 37,
									"length": 9,
									"text": "ibuprofen",
									"category": "MedicationName",
									"confidenceScore": 1,
									"assertion": {
										"certainty": "negative"
									},
									"name": "ibuprofen",
									"links": [
										{
											"dataSource": "UMLS",
											"id": "C0020740"
										},
										{
											"dataSource": "AOD",
											"id": "0000019879"
										},
										{
											"dataSource": "ATC",
											"id": "M01AE01"
										},
										{
											"dataSource": "CCPSS",
											"id": "0046165"
										},
										{
											"dataSource": "CHV",
											"id": "0000006519"
										},
										{
											"dataSource": "CSP",
											"id": "2270-2077"
										},
										{
											"dataSource": "DRUGBANK",
											"id": "DB01050"
										},
										{
											"dataSource": "GS",
											"id": "1611"
										},
										{
											"dataSource": "LCH_NW",
											"id": "sh97005926"
										},
										{
											"dataSource": "LNC",
											"id": "LP16165-0"
										},
										{
											"dataSource": "MEDCIN",
											"id": "40458"
										},
										{
											"dataSource": "MMSL",
											"id": "d00015"
										},
										{
											"dataSource": "MSH",
											"id": "D007052"
										},
										{
											"dataSource": "MTHSPL",
											"id": "WK2XYI10QM"
										},
										{
											"dataSource": "NCI",
											"id": "C561"
										},
										{
											"dataSource": "NCI_CTRP",
											"id": "C561"
										},
										{
											"dataSource": "NCI_DCP",
											"id": "00803"
										},
										{
											"dataSource": "NCI_DTP",
											"id": "NSC0256857"
										},
										{
											"dataSource": "NCI_FDA",
											"id": "WK2XYI10QM"
										},
										{
											"dataSource": "NCI_NCI-GLOSS",
											"id": "CDR0000613511"
										},
										{
											"dataSource": "NDDF",
											"id": "002377"
										},
										{
											"dataSource": "PDQ",
											"id": "CDR0000040475"
										},
										{
											"dataSource": "RCD",
											"id": "x02MO"
										},
										{
											"dataSource": "RXNORM",
											"id": "5640"
										},
										{
											"dataSource": "SNM",
											"id": "E-7772"
										},
										{
											"dataSource": "SNMI",
											"id": "C-603C0"
										},
										{
											"dataSource": "SNOMEDCT_US",
											"id": "387207008"
										},
										{
											"dataSource": "USP",
											"id": "m39860"
										},
										{
											"dataSource": "USPMG",
											"id": "MTHU000060"
										},
										{
											"dataSource": "VANDF",
											"id": "4017840"
										}
									]
								},
								{
									"entityComponentInformation": [
										{
											"entityComponentKind": "prebuiltComponent"
										}
									],
									"offset": 30,
									"length": 6,
									"text": "100 mg",
									"category": "Dosage",
									"confidenceScore": 0.98
								}
							],
							"relations": [
								{
									"confidenceScore": 1,
									"relationType": "DosageOfMedication",
									"entities": [
										{
											"ref": "#/documents/0/entities/1",
											"role": "Dosage"
										},
										{
											"ref": "#/documents/0/entities/0",
											"role": "Medication"
										}
									]
								}
							],
							"id": "1",
							"warnings": []
						}
					],
					"errors": [],
					"modelVersion": "2020-04-01"
				}
			}
		]
	}
}
键 示例值 说明
实体 [] 包含所有已提取实体的数组。
entityComponentKind prebuiltComponent 一个变量，用于指示哪个组件返回了特定实体。 可能的值：prebuiltComponent、learnedComponent、listComponent
offset 0 一个数字，通过对字符编制索引表示已提取实体的起点
length 10 一个数字，用于表示已提取实体的长度（以字符数为单位）。
text first entity 为特定实体提取的文本。
category MedicationName 与提取的文本对应的实体类型或类别的名称。
confidenceScore 0.9 一个数字，表示模型对已提取实体的确定性级别，范围从 0 到 1，数字越大表示确定性越高。
assertion certainty 与提取的实体关联的断言。 断言仅支持用于预生成的健康状况文本分析实体。
name Ibuprofen 与提取的实体关联的实体链接的规范化名称。 实体链接仅支持用于预生成的健康状况文本分析实体。
链接 [] 一个数组，其中包含与提取的实体关联的实体链接的所有结果。 实体链接仅支持用于预生成的健康状况文本分析实体。
dataSource UMLS 与提取的实体关联的实体链接生成的引用标准。 实体链接仅支持用于预生成的健康状况文本分析实体。
ID C0020740 与提取的实体（属于提取的数据源）关联的实体链接生成的引用代码。 实体链接仅支持用于预生成的健康状况文本分析实体。
关系 [] 包含所有提取的关系的数组。 关系提取仅支持用于预生成的健康状况文本分析实体。
relationType DosageOfMedication 提取的关系的类别。 关系提取仅支持用于预生成的健康状况文本分析实体。
实体 "Dosage", "Medication" 与提取的关系关联的实体。 关系提取仅支持用于预生成的健康状况文本分析实体。

我遇到了问题

清理资源

不再需要项目时，可以使用以下 DELETE 请求将其删除。 将占位符值替换为你自己的值。

{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}
占位符 值 示例
{ENDPOINT} 用于对 API 请求进行身份验证的终结点。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 项目名称。 此值区分大小写。 myProject
{API-VERSION} 要调用的 API 版本。 此处引用的值适用于最新发布的版本。 请参阅模型生命周期，了解有关其他可用 API 版本的详细信息。 2022-05-01

头文件

使用以下标头对请求进行身份验证。

键 价值
Ocp-Apim-Subscription-Key 资源密钥。 用于对 API 请求进行身份验证。

发送 API 请求后，将收到一个指示成功的 202 响应，这意味着项目已被删除。 带有用于检查作业状态的 Operation-Location 标头的成功调用结果。

我遇到了问题

后续步骤

创建实体提取模型后，可以：

当你开始创建自己的自定义健康状况文本分析项目时，请通过操作说明文章更详细地了解如何为数据加标签，如何训练和使用你的模型：