Java 用 Azure Text Analytics クライアントライブラリ - バージョン 5.4.0

[アーティクル]
10/25/2023

Azure Cognitive Service for Language は、テキストを理解および分析するための自然言語処理 (NLP) 機能を提供するクラウドベースのサービスであり、次のメイン機能が含まれています。

感情分析
エンティティ認識 (名前付き、リンク済み、個人を特定できる情報 (PII) エンティティ)
言語検出
キーフレーズ抽出
ドキュメントごとに複数のアクション分析
医療エンティティの分析
抽象テキストの要約
抽出テキストの要約
カスタム固有表現認識
カスタムテキスト分類

ソースコード | パッケージ (Maven) | API リファレンスドキュメント | 製品ドキュメント | サンプル

作業の開始

前提条件

Java Development Kit (JDK) バージョン 8 以降。
Azure サブスクリプション
このパッケージを使用する Cognitive Services または言語サービスアカウント。

パッケージをインクルードする

BOM ファイルを含める

ライブラリの GA バージョンに依存するには、azure-sdk-bom をプロジェクトに含めてください。次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 BOM の詳細については、 AZURE SDK BOM README に関するページを参照してください。

<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 バージョンになります。これは、および 2022-05-01よりも3_03_1新しいバージョンです。

次の表は、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

Cognitive Services または Language Service リソースを作成する

言語サービスでは、マルチサービスアクセスとシングルサービスアクセスの両方がサポートされています。 1 つのエンドポイント/キーで複数の Cognitive Services にアクセスする予定の場合は、Cognitive Services リソースを作成します。言語サービスへのアクセスのみの場合は、言語サービスリソースを作成します。

このドキュメントの手順に従って、Azure Portal または Azure CLI を使用してリソースを作成できます。

クライアントを認証する

言語サービスと対話するには、Text Analytics クライアントのインスタンスを作成する必要があります。呼び出しを使用TextAnalyticsClientBuilderして非同期クライアントと同期クライアントの両方を作成し、非同期クライアントに対応するクライアントbuildAsyncClient()をbuildClient()作成します。

クライアントオブジェクトをインスタンス化するには、 エンドポイント とキーまたは AAD TokenCredential が必要です。

エンドポイントの参照

言語サービスリソースの エンドポイント は、 Azure Portal の "キーとエンドポイント" または Azure CLI で確認できます。

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

キー資格情報を使用してText Analytics クライアントを作成する

キーの値を取得したら、それを AzureKeyCredential に文字列として指定します。これは、作成した言語サービスリソースの [キーとエンドポイント] セクションの Azure Portal で、または次の 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 Text Analytics クライアントライブラリは、既存のキーをローテーションする方法を提供します。

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

credential.update("{new_key}");

Azure Active Directory 資格情報を使用してText Analytics クライアントを作成する

Azure SDK for Java では Azure Identity パッケージがサポートされているため、Microsoft ID プラットフォームから資格情報を簡単に取得できます。

AAD を使用した認証には、いくつかの初期セットアップが必要です。

Azure Identity パッケージを追加する

<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();

主要な概念

Text Analytics クライアント

Text Analytics クライアントライブラリには、ドキュメントのバッチで分析を行うための TextAnalyticsClient と TextAnalyticsAsyncClient が用意されています。言語検出やキーフレーズ抽出など、言語サービスの特定の使用にアクセスするための同期操作と非同期操作の両方が提供されます。

入力

テキスト入力 (ドキュメントとも呼ばれます) は、言語サービスの予測モデルによって分析される 1 つのドキュメント単位です。 Text Analytics クライアントに対する操作では、1 つのドキュメントまたはドキュメントのコレクションをバッチとして分析できます。ドキュメントの長さの制限、最大バッチサイズ、サポートされているテキストエンコードなど、ドキュメントのサービス制限に関するページを参照してください。

複数のドキュメントに対する操作

サポートされている操作ごとに、Text Analytics クライアントは、1 つのドキュメント、ドキュメントのバッチを文字列として、またはオブジェクトのTextDocumentInputDetectLanguageInputバッチを取得するためのメソッドオーバーロードを提供します。または DetectLanguageInput バッチをTextDocumentInput受け取るオーバーロードを使用すると、呼び出し元は各ドキュメントに一意の ID を付与したり、バッチ内のドキュメントが異なる言語で書き込まれたり、ドキュメントの言語に関する国ヒントを提供したりできます。

戻り値

などの AnalyzeSentimentResult操作の結果は、言語サービス操作の結果であり、1 つのドキュメントに関する予測または予測と、その中の警告の一覧が含まれます。操作の結果の種類には、必要に応じて、入力ドキュメントとその処理方法に関する情報を含めることもできます。操作の結果には、実行された操作が特定のドキュメントに対して成功したか失敗したかを識別できるプロパティが含 isError まれています。操作でエラーが発生した場合は、を呼び出 getError() すだけで、失敗した理由を含むを取得 TextAnalyticsError できます。ドキュメント内の文字数、または実行された操作トランザクションの数に関心がある場合は、を呼び出 getStatistics() して、両方の情報を含むを TextDocumentStatistics 取得します。

戻り値のコレクション

センチメント操作を分析した結果のコレクションであるなどの AnalyzeSentimentResultCollection操作結果コレクション。また、バッチドキュメントの操作と統計のモデルバージョンも含まれます。

注: 運用環境で作業する場合は、複数のドキュメントで 1 つの要求を送信できるため、バッチメソッドを使用することをお勧めします。これは、各ドキュメントごとに要求を送信するよりもパフォーマンスが高くなります。

例

次のセクションでは、次のような最も一般的な言語サービスタスクの一部をカバーするいくつかのコードスニペットを示します。

感情の分析
言語の検出
キーフレーズの抽出
名前付きエンティティを認識する
個人を特定できる情報エンティティを認識する
リンクされたエンティティを認識する
医療エンティティの分析
複数のアクションを分析する
カスタムエンティティ認識
カスタムテキスト分類
抽象テキストの要約
抽出テキストの要約

Text Analytics クライアント

言語サービスでは、を使用 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 の使用に関するサンプルについては、こちらを参照してください。キーフレーズ抽出の概念的な説明については、サービスドキュメントを参照してください。

名前付きエンティティを認識する

予測モデルを実行して、指定されたドキュメントまたはドキュメントのバッチ内の名前付きエンティティのコレクションを識別し、それらのエンティティを人物、場所、organizationなどのカテゴリに分類します。使用可能なカテゴリの詳細については、「名前付きエンティティカテゴリ」を参照してください。

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 の使用に関するサンプルについては、こちらを参照してください。エンティティリンクの概念的な説明については、サービスドキュメントを参照してください。

医療エンティティを分析する

Text Analytics for Health は、医師のメモ、退院要約、臨床ドキュメント、電子健康記録などの非構造化テキストから関連する医療情報を抽出してラベル付けする、コンテナー化されたサービスです。

医療機関の認識

詳細については、「方法: Text Analyticsを正常性に使用する」を参照してください。

カスタムエンティティ認識

カスタム NER は、Azure Cognitive Service for Language で提供されているカスタム機能の 1 つです。これは、機械学習インテリジェンスを適用してカスタム固有表現認識タスク用のカスタムモデルを構築できるようにする、クラウドベースの API サービスです。

カスタムエンティティ認識

詳細については、「使用方法: カスタムエンティティ認識」を参照してください。

カスタムテキスト分類

カスタムテキスト分類は、Azure Cognitive Service for Language で提供されているカスタム機能の 1 つです。これは、機械学習インテリジェンスを適用して、テキスト分類タスク用のカスタムモデルを構築できるようにするクラウドベースの 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 以降)

サンプル: 複数のアクション分析

非同期サンプルなどのその他の例については、こちらを参照してください。

トラブルシューティング

全般

クライアントText Analytics例外が発生します。たとえば、同じドキュメント 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 クライアントの構成と変更については、HTTP クライアントの Wiki で詳しく説明されています。

既定の SSL ライブラリ

すべてのクライアントライブラリは、Tomcat ネイティブの Boring SSL ライブラリを既定で使用して、SSL 操作にネイティブレベルのパフォーマンスを実現しています。 Boring SSL ライブラリは、Linux、macOS、Windows のネイティブライブラリを含んだ uber jar であり、JDK 内の既定の SSL 実装よりも優れたパフォーマンスを備えています。依存関係のサイズを縮小する方法など、詳細については、Wiki の「パフォーマンスチューニング」セクションを参照してください。

次の手順

サンプルについては、こちらを参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

インプレッション数

次の方法で共有

Java 用 Azure Text Analytics クライアントライブラリ - バージョン 5.4.0

作業の開始

前提条件

パッケージをインクルードする

BOM ファイルを含める

直接依存関係を含める

Cognitive Services または Language Service リソースを作成する

クライアントを認証する

エンドポイントの参照

キー資格情報を使用してText Analytics クライアントを作成する

Azure Active Directory 資格情報を使用してText Analytics クライアントを作成する

主要な概念

Text Analytics クライアント

入力

複数のドキュメントに対する操作

戻り値

戻り値のコレクション

例

Text Analytics クライアント

感情を分析する

言語検出

キーフレーズ抽出

名前付きエンティティを認識する

個人を特定できる情報エンティティを認識する

リンクされたエンティティを認識する

医療エンティティを分析する

カスタムエンティティ認識

カスタムテキスト分類

複数のアクションを分析する

トラブルシューティング

全般

クライアントのログ記録を有効にする

既定の HTTP クライアント

既定の SSL ライブラリ

次の手順

共同作成

フィードバック

その他のリソース

次の方法で共有

Java 用 Azure Text Analytics クライアント ライブラリ - バージョン 5.4.0

作業の開始

前提条件

パッケージをインクルードする

BOM ファイルを含める

直接依存関係を含める

Cognitive Services または Language Service リソースを作成する

クライアントを認証する

エンドポイントの参照

キー資格情報を使用してText Analytics クライアントを作成する

Azure Active Directory 資格情報を使用してText Analytics クライアントを作成する

主要な概念

Text Analytics クライアント

入力

複数のドキュメントに対する操作

戻り値

戻り値のコレクション

例

Text Analytics クライアント

感情を分析する

言語検出

キー フレーズ抽出

名前付きエンティティを認識する

個人を特定できる情報エンティティを認識する

リンクされたエンティティを認識する

医療エンティティを分析する

カスタム エンティティ認識

カスタム テキスト分類

複数のアクションを分析する

トラブルシューティング

全般

クライアントのログ記録を有効にする

既定の HTTP クライアント

既定の SSL ライブラリ

次の手順

共同作成

フィードバック

その他のリソース

Java 用 Azure Text Analytics クライアントライブラリ - バージョン 5.4.0

キーフレーズ抽出

カスタムエンティティ認識

カスタムテキスト分類