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

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 宛てに質問またはコメントをお送りください。