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

适用于 Java 的 Azure 文本分析客户端库 - 版本 5.4.0

适用于语言的 Azure 认知服务是基于云的服务，提供自然语言处理 (NLP) 功能，用于理解和分析文本，并包含以下main功能：

• 情绪分析
• 实体识别 (命名、链接和个人身份信息 (PII) 实体)
• 语言检测
• 关键短语提取
• 每个文档的多个操作分析
• 医疗保健实体分析
• 抽象文本摘要
• 提取文本摘要
• 自定义命名实体识别
• 自定义文本分类

源代码 | 包 (Maven) | API 参考文档 | 产品文档 | 样品

入门

先决条件

• Java 开发工具包 (JDK) 8 或更高版本。
• Azure 订阅
• 使用此包的认知服务或语言服务帐户 。

包括包

包括 BOM 文件

请将 azure-sdk-bom 包含在项目中，以依赖于库的 GA 版本。 在以下代码段中，将 {bom_version_to_target} 占位符替换为版本号。 若要详细了解 BOM，请参阅 AZURE SDK BOM 自述文件。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然后在没有版本标记的依赖项部分中包含直接依赖项。

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-textanalytics</artifactId>
  </dependency>
</dependencies>

包括直接依赖项

如果要依赖于 BOM 中不存在的特定库版本，请将直接依赖项添加到项目，如下所示。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-textanalytics</artifactId>
    <version>5.4.0</version>
</dependency>

注意： 此版本的客户端库默认为 2023-04-01 服务版本。 它是比 3_0、 3_1 和 2022-05-01的更新版本。

下表显示了 SDK 服务与该服务支持的 API 版本之间的关系：

SDK 版本	服务支持的 API 版本
5.3.x	3.0、3.1、2022-05-01、2023-04-01 (默认)
5.2.x	3.0, 3.1, 2022-05-01
5.1.x	3.0, 3.1
5.0.x	3.0

创建认知服务或语言服务资源

语言服务支持 多服务和单服务访问。 如果计划通过一个终结点/密钥访问多个认知服务，请创建认知服务资源。 对于“仅限语言服务访问”，请创建语言服务资源。

可以按照本文档中的步骤，使用 Azure 门户或 Azure CLI 创建资源。

验证客户端

为了与语言服务交互，需要创建文本分析客户端的实例，异步客户端和同步客户端都可以通过使用TextAnalyticsClientBuilder调用buildClient()创建同步客户端来创建同步客户端，同时buildAsyncClient()创建其异步对应客户端。

需要 终结点 和 密钥 或 AAD TokenCredential 来实例化客户端对象。

查找终结点

可以在 Azure 门户的“密钥和终结点”或 Azure CLI 下找到语言服务资源的终结点。

# Get the endpoint for the Language service resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "endpoint"

使用密钥凭据创建文本分析客户端

获得 密钥的值后，将其作为 字符串提供给 AzureKeyCredential。 可以在 Azure 门户 的“密钥和终结点”部分（位于所创建语言服务资源中的“密钥和终结点”部分）中找到，也可以通过运行以下 Azure CLI 命令找到：

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

使用密钥作为凭据参数对客户端进行身份验证：

TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
    .credential(new AzureKeyCredential("{key}"))
    .endpoint("{endpoint}")
    .buildClient();

Azure 文本分析客户端库提供了一种轮换现有密钥的方法。

AzureKeyCredential credential = new AzureKeyCredential("{key}");
TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
    .credential(credential)
    .endpoint("{endpoint}")
    .buildClient();

credential.update("{new_key}");

使用 Azure Active Directory 凭据创建文本分析客户端

适用于 Java 的 Azure SDK 支持 Azure 标识包，因此可以轻松地从Microsoft 标识平台获取凭据。

使用 AAD 进行身份验证需要一些初始设置：

• 添加 Azure 标识包

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.10.4</version>
</dependency>

• 注册新的 Azure Active Directory 应用程序
• 通过将角色分配给服务主体来"Cognitive Services User"授予对语言服务的访问权限。

设置后，可以从 azure.identity 中选择要使用的 凭据 类型。 例如， 可以使用 DefaultAzureCredential 对客户端进行身份验证：将 AAD 应用程序的客户端 ID、租户 ID 和客户端密码的值设置为环境变量：AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET。

使用 DefaultAzureCredential 进行授权最简单。 它会找到在其运行环境中使用的最佳凭据。 有关将 Azure Active Directory 授权与语言服务配合使用的详细信息，请参阅 相关文档。

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
TextAnalyticsAsyncClient textAnalyticsAsyncClient = new TextAnalyticsClientBuilder()
    .endpoint("{endpoint}")
    .credential(defaultCredential)
    .buildAsyncClient();

关键概念

文本分析 客户端

文本分析客户端库提供 TextAnalyticsClient 和 TextAnalyticsAsyncClient，用于对文档批处理进行分析。 它提供同步和异步操作来访问语言服务的特定用途，例如语言检测或关键短语提取。

输入

文本输入（也称为文档）是语言服务中的预测模型要分析的单个文档单元。 文本分析客户端上的操作可能会将单个文档或文档集合作为批处理进行分析。 请参阅文档 的服务限制 ，包括文档长度限制、最大批大小和支持的文本编码。

对多个文档执行的操作

对于每个受支持的操作，文本分析客户端提供方法重载，以采用单个文档、一批文档作为字符串或一批 TextDocumentInput 或 DetectLanguageInput 对象。 采用 或 DetectLanguageInput 批处理的TextDocumentInput重载允许调用方为每个文档提供唯一 ID、指示批中的文档是用不同语言编写的，或者提供有关文档语言的国家/地区提示。

返回值

操作结果（如 AnalyzeSentimentResult）是语言服务操作的结果，其中包含有关单个文档的预测或预测以及其中警告列表。 操作的结果类型还可以选择性地包含有关输入文档及其处理方式的信息。 操作结果包含一个 isError 属性，该属性允许确定执行的操作对给定文档是成功还是不成功。 当操作导致错误时，只需调用 getError() 获取 TextAnalyticsError ，其中包含失败的原因。 如果对文档中的字符数或经过的操作事务数感兴趣，只需调用 getStatistics() 以获取 TextDocumentStatistics 包含这两种信息的 。

返回值集合

操作结果集合，例如 AnalyzeSentimentResultCollection，它是分析情绪操作的结果的集合。 它还包括操作的模型版本和批处理文档的统计信息。

注意：建议在处理生产环境时使用批处理方法，因为它们允许你发送包含多个文档的一个请求。 这比为每个文档发送请求更有性能。

示例

以下部分提供了几个代码片段，涵盖了一些最常见的语言服务任务，包括：

• 分析情绪
• 检测语言
• 提取关键短语
• 识别命名实体
• 识别个人身份信息实体
• 识别链接实体
• 分析医疗保健实体
• 分析多个操作
• 自定义实体识别
• 自定义文本分类
• 抽象文本摘要
• 提取文本摘要

文本分析客户端

语言服务支持使用 TextAnalyticsClientBuilder创建同步和异步客户端。

TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
    .credential(new AzureKeyCredential("{key}"))
    .endpoint("{endpoint}")
    .buildClient();

或

TextAnalyticsAsyncClient textAnalyticsAsyncClient = new TextAnalyticsClientBuilder()
    .credential(new AzureKeyCredential("{key}"))
    .endpoint("{endpoint}")
    .buildAsyncClient();

分析情绪

运行预测模型以识别所提供的文档或一批文档中包含的积极、消极、中性或混合情绪。

String document = "The hotel was dark and unclean. I like microsoft.";
DocumentSentiment documentSentiment = textAnalyticsClient.analyzeSentiment(document);
System.out.printf("Analyzed document sentiment: %s.%n", documentSentiment.getSentiment());
documentSentiment.getSentences().forEach(sentenceSentiment ->
    System.out.printf("Analyzed sentence sentiment: %s.%n", sentenceSentiment.getSentiment()));

有关使用生产推荐选项 AnalyzeSentimentBatch 的示例，请参阅 此处。

若要获取有关与产品/服务方面相关的观点的更精细的信息，还了解自然语言处理中的基于方面的情绪分析 (NLP) ，请参阅 此处有关使用观点挖掘进行情绪分析的示例。

有关 情绪分析的概念性讨论，请参阅服务文档。

检测语言

运行预测模型以确定所提供文档或一批文档所使用的语言。

String document = "Bonjour tout le monde";
DetectedLanguage detectedLanguage = textAnalyticsClient.detectLanguage(document);
System.out.printf("Detected language name: %s, ISO 6391 name: %s, confidence score: %f.%n",
    detectedLanguage.getName(), detectedLanguage.getIso6391Name(), detectedLanguage.getConfidenceScore());

有关使用生产推荐选项 DetectLanguageBatch 的示例，请参阅 此处。 有关 语言检测的概念性讨论，请参阅服务文档。

提取关键短语

运行模型以识别在提供的文档或一批文档中找到的重要短语集合。

String document = "My cat might need to see a veterinarian.";
System.out.println("Extracted phrases:");
textAnalyticsClient.extractKeyPhrases(document).forEach(keyPhrase -> System.out.printf("%s.%n", keyPhrase));

有关使用生产推荐选项 ExtractKeyPhrasesBatch 的示例，请参阅 此处。 有关 关键短语提取的概念性讨论，请参阅服务文档。

识别命名实体

运行预测模型以识别所提供的文档或一批文档中的命名实体集合，并将这些实体分类为人员、位置或组织等类别。 有关可用类别的详细信息，请参阅 命名实体类别。

String document = "Satya Nadella is the CEO of Microsoft";
textAnalyticsClient.recognizeEntities(document).forEach(entity ->
    System.out.printf("Recognized entity: %s, category: %s, subcategory: %s, confidence score: %f.%n",
        entity.getText(), entity.getCategory(), entity.getSubcategory(), entity.getConfidenceScore()));

有关使用生产推荐选项 RecognizeEntitiesBatch 的示例，请参阅 此处。 有关 命名实体识别的概念性讨论，请参阅服务文档。

识别个人身份信息实体

运行预测模型，以在提供的文档中识别个人身份信息 (PII) 实体的集合。 它识别并分类输入文本中的 PII 实体，例如社会保险号、银行帐户信息、信用卡号码等。 仅 API 版本 v3.1-preview.1 及更高版本支持此终结点。

String document = "My SSN is 859-98-0987";
PiiEntityCollection piiEntityCollection = textAnalyticsClient.recognizePiiEntities(document);
System.out.printf("Redacted Text: %s%n", piiEntityCollection.getRedactedText());
piiEntityCollection.forEach(entity -> System.out.printf(
    "Recognized Personally Identifiable Information entity: %s, entity category: %s, entity subcategory: %s,"
        + " confidence score: %f.%n",
    entity.getText(), entity.getCategory(), entity.getSubcategory(), entity.getConfidenceScore()));

有关使用生产推荐选项 RecognizePiiEntitiesBatch 的示例，请参阅 此处。 有关 支持的 PII 实体类型，请参阅服务文档。

识别链接的实体

运行预测模型以识别在提供的文档或一批文档中找到的实体集合，并包含将实体链接到已知知识库中的相应条目的信息。

String document = "Old Faithful is a geyser at Yellowstone Park.";
textAnalyticsClient.recognizeLinkedEntities(document).forEach(linkedEntity -> {
    System.out.println("Linked Entities:");
    System.out.printf("Name: %s, entity ID in data source: %s, URL: %s, data source: %s.%n",
        linkedEntity.getName(), linkedEntity.getDataSourceEntityId(), linkedEntity.getUrl(), linkedEntity.getDataSource());
    linkedEntity.getMatches().forEach(match ->
        System.out.printf("Text: %s, confidence score: %f.%n", match.getText(), match.getConfidenceScore()));
});

有关使用生产推荐选项 RecognizeLinkedEntitiesBatch 的示例，请参阅 此处。 有关 实体链接的概念性讨论，请参阅服务文档。

分析医疗保健实体

健康状况文本分析是一种容器化服务，它从非结构化文本（如医生的备注、出院摘要、临床文档和电子健康状况记录）中提取和标记相关医疗信息。

• 医疗保健实体识别

有关详细信息，请参阅如何：使用文本分析实现健康。

自定义实体识别

自定义 NER 是适用于语言的 Azure 认知服务提供的自定义功能之一。 它是一种基于云的 API 服务，应用机器学习智能，使你能够生成用于自定义命名实体识别任务的自定义模型。

• 自定义实体识别

有关详细信息 ，请参阅如何使用：自定义实体识别。

自定义文本分类

自定义文本分类是适用于语言的 Azure 认知服务提供的自定义功能之一。 它是一种基于云的 API 服务，应用机器学习智能，让你能够生成用于文本分类任务的自定义模型。

• 单标签分类

• 多标签分类

有关详细信息，请参阅 如何使用：自定义文本分类。

分析多个操作

该功能 Analyze 允许选择要在同一组文档中执行哪些受支持的语言服务功能。 目前，支持的功能包括：

• 命名实体识别
• PII 实体识别
• 链接实体识别
• 关键短语提取
• 情绪分析
• 医疗保健分析
• 自定义实体识别 (API 版本 2022-05-01 及更新)
• 自定义 Single-Label 分类 (API 版本 2022-05-01 及更新)
• 自定义多标签分类 (API 版本 2022-05-01 及更新)
• 抽象文本摘要 (API 版本 2023-04-01 及更新)
• 提取文本摘要 (API 版本 2023-04-01 及更新)

示例： 多个操作分析

有关更多示例（例如异步示例），请参阅 此处。

疑难解答

常规

文本分析客户端引发异常。 例如，如果尝试检测具有相同文档 ID 的一批文本的语言， 400 则返回指示错误请求。 在以下代码片段中，通过捕获异常并显示有关错误的其他信息来妥善处理该错误。

List<DetectLanguageInput> documents = Arrays.asList(
    new DetectLanguageInput("1", "This is written in English.", "us"),
    new DetectLanguageInput("1", "Este es un documento  escrito en Español.", "es")
);

try {
    textAnalyticsClient.detectLanguageBatchWithResponse(documents, null, Context.NONE);
} catch (HttpResponseException e) {
    System.out.println(e.getMessage());
}

启用客户端日志记录

可以设置 AZURE_LOG_LEVEL 环境变量，以便查看在客户端库中生成的日志记录语句。 例如，设置 AZURE_LOG_LEVEL=2 会显示所有信息性消息、警告消息和错误日志消息。 日志级别可在此处找到：日志级别。

默认的 HTTP 客户端

默认情况下，所有客户端库都使用 Netty HTTP 客户端。 添加上述依赖项会自动将客户端库配置为使用 Netty HTTP 客户端。 HTTP 客户端 Wiki 中详述了如何配置或更改 HTTP 客户端。

默认 SSL 库

默认情况下，所有客户端库均使用 Tomcat 原生 Boring SSL 库来为 SSL 操作启用原生级别性能。 Boring SSL 库是一个 uber jar，其中包含适用于 Linux/macOS/Windows 的原生库。与 JDK 内的默认 SSL 实现相比，它提供更好的性能。 有关详细信息（包括如何减小依赖项大小），请参阅 Wiki 的性能优化部分。

后续步骤

• 此处详细介绍了示例。

贡献

本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。