azure-ai-textanalytics-py

Python 用 Azure AI Text Analytics SDK

感情分析、エンティティ、キーフレーズなど、Azure AI Language サービスの NLP 機能を利用するクライアントライブラリです。

インストール

pip install azure-ai-textanalytics

環境変数

AZURE_LANGUAGE_ENDPOINT=https://<resource>.cognitiveservices.azure.com
AZURE_LANGUAGE_KEY=<your-api-key>  # If using API key

認証

API キー

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics import TextAnalyticsClient

endpoint = os.environ["AZURE_LANGUAGE_ENDPOINT"]
key = os.environ["AZURE_LANGUAGE_KEY"]

client = TextAnalyticsClient(endpoint, AzureKeyCredential(key))

Entra ID（推奨）

from azure.ai.textanalytics import TextAnalyticsClient
from azure.identity import DefaultAzureCredential

client = TextAnalyticsClient(
    endpoint=os.environ["AZURE_LANGUAGE_ENDPOINT"],
    credential=DefaultAzureCredential()
)

データの取り扱い

呼び出しでは、ドキュメントのテキストが Azure に送信されます。プライベートデータ、PII、または健康情報を扱う場合は、許可を取得し、リージョン、保持期間、許可された用途を確認してください。レダクションは確率的な処理であり、匿名化を保証するものではありません。医療情報の抽出は診断ではありません。サンプルはそれぞれ独立した断片です。結果フィールドを使用する前に、ドキュメントごとのエラーを確認してください。

感情分析

documents = [
    "I had a wonderful trip to Seattle last week!",
    "The food was terrible and the service was slow."
]

result = client.analyze_sentiment(documents, show_opinion_mining=True)

for doc in result:
    if not doc.is_error:
        print(f"Sentiment: {doc.sentiment}")
        print(f"Scores: pos={doc.confidence_scores.positive:.2f}, "
              f"neg={doc.confidence_scores.negative:.2f}, "
              f"neu={doc.confidence_scores.neutral:.2f}")
        
        # Opinion mining (aspect-based sentiment)
        for sentence in doc.sentences:
            for opinion in sentence.mined_opinions:
                target = opinion.target
                print(f"  Target: '{target.text}' - {target.sentiment}")
                for assessment in opinion.assessments:
                    print(f"    Assessment: '{assessment.text}' - {assessment.sentiment}")

エンティティ認識

documents = ["Microsoft was founded by Bill Gates and Paul Allen in Albuquerque."]

result = client.recognize_entities(documents)

for doc in result:
    if not doc.is_error:
        for entity in doc.entities:
            print(f"Entity: {entity.text}")
            print(f"  Category: {entity.category}")
            print(f"  Subcategory: {entity.subcategory}")
            print(f"  Confidence: {entity.confidence_score:.2f}")

PII の検出

documents = ["My SSN is 123-45-6789 and my email is [email protected]"]

result = client.recognize_pii_entities(documents)

for doc in result:
    if not doc.is_error:
        print(f"Redacted: {doc.redacted_text}")
        for entity in doc.entities:
            print(f"PII category: {entity.category}")  # Do not log detected sensitive values.

キーフレーズの抽出

documents = ["Azure AI provides powerful machine learning capabilities for developers."]

result = client.extract_key_phrases(documents)

for doc in result:
    if not doc.is_error:
        print(f"Key phrases: {doc.key_phrases}")

言語検出

documents = ["Ce document est en francais.", "This is written in English."]

result = client.detect_language(documents)

for doc in result:
    if not doc.is_error:
        print(f"Language: {doc.primary_language.name} ({doc.primary_language.iso6391_name})")
        print(f"Confidence: {doc.primary_language.confidence_score:.2f}")

医療テキスト分析

documents = ["Patient has diabetes and was prescribed metformin 500mg twice daily."]

poller = client.begin_analyze_healthcare_entities(documents)
result = poller.result()

for doc in result:
    if not doc.is_error:
        for entity in doc.entities:
            print(f"Entity: {entity.text}")
            print(f"  Category: {entity.category}")
            print(f"  Normalized: {entity.normalized_text}")
            
            # Entity links (UMLS, etc.)
            for link in entity.data_sources:
                print(f"  Link: {link.name} - {link.entity_id}")

複数の分析（バッチ）

from azure.ai.textanalytics import (
    RecognizeEntitiesAction,
    ExtractKeyPhrasesAction,
    AnalyzeSentimentAction
)

documents = ["Microsoft announced new Azure AI features at Build conference."]

poller = client.begin_analyze_actions(
    documents,
    actions=[
        RecognizeEntitiesAction(),
        ExtractKeyPhrasesAction(),
        AnalyzeSentimentAction()
    ]
)

results = poller.result()
for doc_results in results:
    for result in doc_results:
        if result.kind == "EntityRecognition":
            print(f"Entities: {[e.text for e in result.entities]}")
        elif result.kind == "KeyPhraseExtraction":
            print(f"Key phrases: {result.key_phrases}")
        elif result.kind == "SentimentAnalysis":
            print(f"Sentiment: {result.sentiment}")

非同期クライアント

from azure.ai.textanalytics.aio import TextAnalyticsClient
from azure.identity.aio import DefaultAzureCredential

async def analyze():
    async with TextAnalyticsClient(
        endpoint=endpoint,
        credential=DefaultAzureCredential()
    ) as client:
        result = await client.analyze_sentiment(documents)
        # Process results...

クライアントの種類

クライアント	用途
TextAnalyticsClient	すべてのテキスト分析操作
TextAnalyticsClient (aio)	非同期バージョン

利用可能な操作

メソッド	説明
analyze_sentiment	オピニオンマイニングを含む感情分析
recognize_entities	固有表現認識
recognize_pii_entities	PII の検出とレダクション
recognize_linked_entities	Wikipedia へのエンティティのリンク
extract_key_phrases	キーフレーズの抽出
detect_language	言語検出
begin_analyze_healthcare_entities	医療 NLP（長時間実行）
begin_analyze_actions	バッチでの複数分析

ベストプラクティス

1. 複数のドキュメントにはバッチ操作を使用してください（1 リクエストあたり最大 10 件）。
2. アスペクトベースの感情分析を詳細に行うには、オピニオンマイニングを有効にしてください。
3. スループットの高いシナリオでは、非同期クライアントを使用してください。
4. ドキュメントのエラーを処理してください。結果リストには、一部のドキュメントのエラーが含まれる場合があります。
5. 言語がわかっている場合は、精度を高めるために言語を指定してください。
6. コンテキストマネージャーを使用するか、クライアントを明示的に閉じてください。

使用する場面

このスキルは、概要で説明されているワークフローまたはアクションを実行する場合に適用できます。

制限事項

• タスクが上記で説明されている範囲に明確に一致する場合にのみ、このスキルを使用してください。
• 環境固有の検証、テスト、または専門家によるレビューの代替として、出力を扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中止して確認を求めてください。