JavaScript 用 Azure Text Analysis クライアント ライブラリ - バージョン 1.1.0

  • [アーティクル]

Azure Cognitive Service for Language は、生テキストに対する高度な自然言語処理を提供するクラウドベースのサービスであり、次のメイン機能が含まれています。

メモ： この SDK は、Azure Cognitive Service for Language API バージョン 2023-04-01 を対象とします。

  • 言語検出
  • 感情分析
  • キー フレーズ抽出
  • 名前付きエンティティの認識
  • 個人を特定できる情報の認識
  • Entity Linking
  • 医療分析
  • 抽出要約
  • 抽象要約
  • カスタム エンティティ認識
  • カスタム ドキュメント分類
  • ドキュメントごとに複数のアクションをサポートする

以下の場合にクライアント ライブラリを使用します。

  • 書き込まれる言語入力テキストを検出します。
  • 肯定的または否定的な感情に関する手がかりを得るための生テキストを分析して、顧客がブランドやトピックに対して何を考えているかを判断します。
  • 重要なフレーズを自動的に抽出し、重要な点を迅速に特定します。
  • テキスト内のエンティティを、ユーザー、場所、組織、日付/時刻、数量、パーセンテージ、通貨、医療固有などとして識別して分類します。
  • 上記のタスクの複数を一度に実行します。

主要リンク:

アドバイザリからの@azure/ai-text-analytics移行️ ⚠

AI Text Analytics クライアント ライブラリのバージョン 5.x から新しい AI 言語テキスト クライアント ライブラリにアプリケーション コードを更新する方法の詳細については、移行ガイドを参照してください。

新着記事

はじめに

現在サポートされている環境

詳細については、Microsoft のサポート ポリシーを参照してください。

前提条件

Azure CLI を使用する場合は、 と <your-resource-name> を独自の一意の名前に置き換えます<your-resource-group-name>。

az cognitiveservices account create --kind TextAnalytics --resource-group <your-resource-group-name> --name <your-resource-name> --sku <your-sku-name> --location <your-location>

@azure/ai-language-text パッケージのインストール

を使用して JavaScript 用の Azure Text Analysis クライアント ライブラリを npmインストールします。

npm install @azure/ai-language-text

TextAnalysisClient を作成して認証する

言語 API にアクセスするためのクライアント オブジェクトを作成するには、言語リソースの と credentialが必要endpointです。 Text Analysis クライアントは、認証に Azure Active Directory 資格情報または API キー資格情報のいずれかを使用できます。

言語リソースのエンドポイントは、 Azure Portal または以下の Azure CLI スニペットを使用して確認できます。

az cognitiveservices account show --name <your-resource-name> --resource-group <your-resource-group-name> --query "properties.endpoint"

API キーの使用

Azure Portal を使用して言語リソースを参照し、API キーを取得するか、次の Azure CLI スニペットを使用します。

メモ： API キーは、"サブスクリプション キー" または "サブスクリプション API キー" と呼ばれる場合があります。

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

API キーとエンドポイントを取得したら、 クラスを AzureKeyCredential 使用して、次のようにクライアントを認証できます。

const { TextAnalysisClient, AzureKeyCredential } = require("@azure/ai-language-text");

const client = new TextAnalysisClient("<endpoint>", new AzureKeyCredential("<API key>"));

Azure Active Directory 資格情報の使用

クライアント API キー認証はほとんどの例で使用されますが、Azure Id ライブラリを使用して Azure Active Directory で認証することもできます。 下に示した DefaultAzureCredential プロバイダーか、Azure SDK で提供されている他の資格情報プロバイダーを使用するには、@azure/identity パッケージをインストールしてください。

npm install @azure/identity

また、 新しい AAD アプリケーションを登録 し、サービス プリンシパルにロールを "Cognitive Services User" 割り当てることで言語へのアクセス権を付与する必要があります (注: などの "Owner" 他のロールは必要なアクセス許可を付与せず、例とサンプル コードを実行するだけで "Cognitive Services User" 十分です)。

AAD アプリケーションのクライアント ID、テナント ID、およびクライアント シークレットの値を、環境変数 AZURE_CLIENT_IDAZURE_TENANT_ID、、AZURE_CLIENT_SECRET、 として設定します。

const { TextAnalysisClient } = require("@azure/ai-language-text");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new TextAnalysisClient("<endpoint>", new DefaultAzureCredential());

主要な概念

TextAnalysisClient

TextAnalysisClient は、Text Analysis クライアント ライブラリを使用する開発者向けの主要なインターフェイスです。 このクライアント オブジェクトのメソッドを調べて、アクセスできる言語サービスのさまざまな機能を理解します。

入力

ドキュメントは、言語サービスの予測モデルによって分析される 1 つの入力単位を表します。 に対する TextAnalysisClient 操作は、バッチとして分析される入力のコレクションを受け取ります。 操作メソッドには、入力を文字列として、または添付されたメタデータを持つオブジェクトとして表すオーバーロードがあります。

たとえば、各ドキュメントを配列内の文字列として渡すことができます(例: )。

const documents = [
  "I hated the movie. It was so slow!",
  "The movie made it into my top ten favorites.",
  "What a great movie!",
];

または、アイテムごとのドキュメントidまたは を渡す場合は、 の一覧TextDocumentInputとして、またはcountryHintlanguage/DetectLanguageInput操作に応じて指定できます。

const textDocumentInputs = [
  { id: "1", language: "en", text: "I hated the movie. It was so slow!" },
  { id: "2", language: "en", text: "The movie made it into my top ten favorites." },
  { id: "3", language: "en", text: "What a great movie!" },
];

ドキュメントの長さの制限、最大バッチ サイズ、サポートされているテキスト エンコードなど、入力の サービス 制限に関するページを参照してください。

戻り値

1 つのドキュメントに対応する戻り値は、成功した結果またはエラー オブジェクトです。 各メソッドは TextAnalysisClient 、インデックスによる入力に対応する結果とエラーの異種配列を返します。 テキスト入力とその結果は、入力コレクションと結果コレクション内で同じインデックスを持ちます。

などのSentimentAnalysisResult結果は、1 つのテキスト入力に関する予測または予測を含む Language 操作の結果です。 操作の結果の種類には、必要に応じて、入力ドキュメントとその処理方法に関する情報を含めることもできます。

error オブジェクト は、TextAnalysisErrorResultドキュメントの処理中にサービスでエラーが発生し、エラーに関する情報が含まれていることを示します。

ドキュメント エラー処理

操作によって返されるコレクションでは、エラーは、エラーが発生した場合に内部TextAnalysisErrorオブジェクトをerror含む プロパティが存在することで、成功した応答と区別されます。 成功した結果オブジェクトの場合、このプロパティは 常にundefined です。

たとえば、すべてのエラーを除外するには、次を使用できます filter。

const results = await client.analyze("SentimentAnalysis", documents);
const onlySuccessful = results.filter((result) => result.error === undefined);

注: TypeScript ユーザーは、構成で が にtrue設定されている場合compilerOptions.strictNullChecks、結果オブジェクトとエラー オブジェクトの型チェックの方が優れた利点がありますtsconfig.json。 次に例を示します。

const [result] = await client.analyze("SentimentAnalysis", ["Hello world!"]);

if (result.error !== undefined) {
  // In this if block, TypeScript will be sure that the type of `result` is
  // `TextAnalysisError` if compilerOptions.strictNullChecks is enabled in
  // the tsconfig.json

  console.log(result.error);
}

サンプル

クライアントの使用状況

事前構築済みタスク

カスタム タスク

トラブルシューティング

ログの記録

ログの記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、環境変数 AZURE_LOG_LEVEL を info に設定します。 または、@azure/logger で setLogLevel を呼び出して、実行時にログ記録を有効にすることもできます。

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

ログを有効にする方法の詳細については、@azure/logger パッケージに関するドキュメントを参照してください。

次のステップ

このライブラリの使用方法の詳細な例については、 samples ディレクトリを参照してください。

共同作成

このライブラリに投稿する場合、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

インプレッション数