快速入门：自定义文本分类

Prerequisites

• Azure 订阅 - 免费创建订阅。

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

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

从 Azure 门户创建新资源

1. 转到 Azure 门户以创建新的 Azure AI 语言资源。

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

   

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

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

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

   可以通过搜索你的资源组并单击其关联订阅的链接来确定你的 Azure 订阅所有者。 然后：

   1. 选择“访问控制(IAM)”选项卡
   2. 选择“角色分配”
   3. 按“角色：所有者”筛选。

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

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

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

将示例数据上传到 Blob 容器

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

2. 在 Azure 门户中，导航到你创建的存储帐户，然后选择它。 为此，你可以单击“存储帐户”，并在任意字段的“筛选器”中键入你的存储帐户名称。

   如果你的资源组未显示，请确保将“订阅等于”筛选器设置为“全部”。

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

   

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

   

创建自定义文本分类项目

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

1. 登录到 Language Studio。 此时将出现一个窗口，用于选择订阅和语言资源。 选择语言资源。

2. 在 Language Studio 的“对文本进行分类”部分下，选择“自定义文本分类”。

   

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

   

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

   注意

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

   

5. 选择项目类型。 可以创建“多标签分类”项目，其中每个文档可以属于一个或多个类；也可以创建“单标签分类”项目，其中每个文档只能属于一个类。 所选类型在以后无法更改。 了解有关项目类型的详细信息

   

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

   提示

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

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

   注意

   如果已标记了数据，请确保它遵循支持的格式，并且选择“是，我的文档已标记，并且我已设置 JSON 标签文件的格式”，然后从下面的下拉菜单中选择标签文件。

   如果你使用示例数据集之一，请使用包括的 webOfScience_labelsFile 或 movieLabels json 文件。 然后，选择“下一步”。

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

训练模型

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

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

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

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

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

   

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

5. 选择“训练”按钮。

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

   注意

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

部署模型

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

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

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

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

   

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

   注意

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

   

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

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

测试模型

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

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

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

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

3. 对于多语言项目，请使用语言下拉列表选择你要测试的文本的语言。

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

5. 输入要在请求中提交的文本，或上传要使用的 .txt 文档。 如果你使用示例数据集之一，则可以使用包含的 .txt 文件之一。

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

7. 在“结果”选项卡中，可以看到预测的文本类别。 还可以在“JSON”选项卡下查看 JSON 响应。以下示例适用于单标签分类项目。 多标签分类项目可以在结果中返回多个类。

   

清理项目

如果不再需要项目，可以使用 Language Studio 删除项目。 选择上方的“自定义文本分类”，然后选择要删除的项目。 选择顶部菜单中的“删除”以删除项目。

Prerequisites

• Azure 订阅 - 免费创建订阅。

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

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

从 Azure 门户创建新资源

1. 转到 Azure 门户以创建新的 Azure AI 语言资源。

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

   

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

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

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

   可以通过搜索你的资源组并单击其关联订阅的链接来确定你的 Azure 订阅所有者。 然后：

   1. 选择“访问控制(IAM)”选项卡
   2. 选择“角色分配”
   3. 按“角色：所有者”筛选。

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

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

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

将示例数据上传到 Blob 容器

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

2. 在 Azure 门户中，导航到你创建的存储帐户，然后选择它。 为此，你可以单击“存储帐户”，并在任意字段的“筛选器”中键入你的存储帐户名称。

   如果你的资源组未显示，请确保将“订阅等于”筛选器设置为“全部”。

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

   

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

   

获取资源密钥和终结点

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

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

创建自定义文本分类项目

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

触发导入项目作业

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

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

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/:import?api-version={API-VERSION}

头文件

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

身体

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

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectName": "{PROJECT-NAME}",
    "storageInputContainerName": "{CONTAINER-NAME}",
    "projectKind": "customMultiLabelClassification",
    "description": "Trying out custom multi label text classification",
    "language": "{LANGUAGE-CODE}",
    "multilingual": true,
    "settings": {}
  },
  "assets": {
    "projectKind": "customMultiLabelClassification",
    "classes": [
      {
        "category": "Class1"
      },
      {
        "category": "Class2"
      }
    ],
    "documents": [
      {
        "location": "{DOCUMENT-NAME}",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "classes": [
          {
            "category": "Class1"
          },
          {
            "category": "Class2"
          }
        ]
      },
      {
        "location": "{DOCUMENT-NAME}",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "classes": [
          {
            "category": "Class2"
          }
        ]
      }
    ]
  }
}

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectName": "{PROJECT-NAME}",
    "storageInputContainerName": "{CONTAINER-NAME}",
    "projectKind": "customSingleLabelClassification",
    "description": "Trying out custom multi label text classification",
    "language": "{LANGUAGE-CODE}",
    "multilingual": true,
    "settings": {}
  },
  "assets": {
    "projectKind": "customSingleLabelClassification",
        "classes": [
            {
                "category": "Class1"
            },
            {
                "category": "Class2"
            }
        ],
        "documents": [
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "class": {
                    "category": "Class2"
                }
            },
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "class": {
                    "category": "Class1"
                }
            }
        ]
    }
}

发送 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}

头文件

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

训练模型

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

开始训练模型

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

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

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

头文件

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

请求正文

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

{
	"modelLabel": "{MODEL-NAME}",
	"trainingConfigVersion": "{CONFIG-VERSION}",
	"evaluationOptions": {
		"kind": "percentage",
		"trainingSplitPercentage": 80,
		"testingSplitPercentage": 20
	}
}

发送 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}

头文件

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

响应正文

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

{
  "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}

头文件

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

请求正文

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

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

发送 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}

头文件

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

响应正文

发送请求后，你将获得以下响应。 继续轮询此终结点，直到“status”参数变为“succeeded”。 应获取一个 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}

头文件

身体

{
  "displayName": "Classifying documents",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
     {
      "kind": "CustomMultiLabelClassification",
      "taskName": "Multi Label Classification",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

{
  "displayName": "Classifying documents",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
    {
      "kind": "CustomSingleLabelClassification",
      "taskName": "Single Classification Label",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

响应

你将收到 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}

头文件

响应正文

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

{
  "createdDateTime": "2021-05-19T14:32:25.578Z",
  "displayName": "MyJobName",
  "expirationDateTime": "2021-05-19T14:32:25.578Z",
  "jobId": "xxxx-xxxxxx-xxxxx-xxxx",
  "lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "customMultiClassificationTasks",
        "taskName": "Classify documents",
        "lastUpdateDateTime": "2020-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "{DOC-ID}",
              "classes": [
                  {
                      "category": "Class_1",
                      "confidenceScore": 0.0551877357
                  }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2020-04-01"
        }
      }
    ]
  }
}

{
  "createdDateTime": "2021-05-19T14:32:25.578Z",
  "displayName": "MyJobName",
  "expirationDateTime": "2021-05-19T14:32:25.578Z",
  "jobId": "xxxx-xxxxxx-xxxxx-xxxx",
  "lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "customSingleClassificationTasks",
        "taskName": "Classify documents",
        "lastUpdateDateTime": "2020-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "{DOC-ID}",
              "class": [
                  {
                      "category": "Class_1",
                      "confidenceScore": 0.0551877357
                  }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2020-04-01"
        }
      }
    ]
  }
}

清理资源

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

{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}

头文件

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

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