Python 用 Azure Document Translation クライアント ライブラリ - バージョン 1.0.0

  • [アーティクル]

Azure Cognitive Services Document Translation は、元のドキュメント構造とデータ形式を維持しながら、複数の複雑なドキュメントを言語や言語間で翻訳するために使用できるクラウド サービスです。 ドキュメント翻訳用のクライアント ライブラリを使用して、次の作業を行います。

  • 多数の大きなファイルをAzure Blob Storageコンテナーから、選択した言語のターゲット コンテナーに変換します。
  • 翻訳操作で各ドキュメントの翻訳状態と進行状況を確認します。
  • カスタム翻訳モデルまたは用語集を適用して、特定のケースに合わせて翻訳を調整します。

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

免責事項

Python 2.7 の Azure SDK Python パッケージのサポートは、2022 年 1 月 1 日に終了しました。 詳細と質問については、https://github.com/Azure/azure-sdk-for-python/issues/20691 を参照してください

作業の開始

前提条件

パッケージをインストールする

pip を使用して Python 用 Azure Document Translation クライアント ライブラリをインストールします。

pip install azure-ai-translation-document

注: このバージョンのクライアント ライブラリの既定値は、サービスの v1.0 バージョンです

Translator リソースを作成する

ドキュメント翻訳機能では、 単一サービス アクセス のみがサポートされます。 サービスにアクセスするには、Translator リソースを作成します。

を使用してリソースを作成できます。

オプション 1:Azure Portal

オプション 2:Azure CLI。 CLI を使用して Translator リソースを作成する方法の例を次に示します。

# Create a new resource group to hold the Translator resource -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create document translation
az cognitiveservices account create \
    --name document-translation-resource \
    --custom-domain document-translation-resource \
    --resource-group my-resource-group \
    --kind TextTranslation \
    --sku S1 \
    --location westus2 \
    --yes

クライアントを認証する

ドキュメント翻訳機能サービスを操作するには、クライアントのインスタンスを作成する必要があります。 クライアント オブジェクトをインスタンス化するには、 エンドポイント と 資格情報 が必要です。

エンドポイントの参照

Translator リソースのエンドポイントは、 Azure Portal を使用して見つけることができます。

サービスにはカスタム ドメイン エンドポイントが必要であることに注意してください。 上記のリンクの指示に従って、エンドポイントの形式を設定します:https://{NAME-OF-YOUR-RESOURCE}.cognitiveservices.azure.com/

API キーを取得する

API キーは、Azure Portal で、または次の Azure CLI コマンドを実行して見つけることができます。

az cognitiveservices account keys list --name "resource-name" --resource-group "resource-group-name"

AzureKeyCredential を使用してクライアントを作成する

API キーをパラメーターとしてcredential使用するには、キーを文字列として AzureKeyCredential のインスタンスに渡します。

from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

endpoint = "https://<resource-name>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")
document_translation_client = DocumentTranslationClient(endpoint, credential)

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

AzureKeyCredential 認証は、このファースト ステップ ガイドの例で使用しますが、 azure-identity ライブラリを使用して Azure Active Directory で認証することもできます。

次に示す DefaultAzureCredential 型、または Azure SDK で提供されているその他の資格情報の種類を使用するには、パッケージを azure-identity インストールしてください。

pip install azure-identity

また、 新しい AAD アプリケーションを登録し、 サービス プリンシパルにロールを割り当てて "Cognitive Services User" Translator リソースへのアクセス権を付与する必要もあります。

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

from azure.identity import DefaultAzureCredential
from azure.ai.translation.document import DocumentTranslationClient
credential = DefaultAzureCredential()

document_translation_client = DocumentTranslationClient(
    endpoint="https://<resource-name>.cognitiveservices.azure.com/",
    credential=credential
)

主要な概念

ドキュメント翻訳サービスでは、ファイルをAzure Blob Storageソース コンテナーにアップロードし、翻訳されたドキュメントを書き込むことができるターゲット コンテナーを指定する必要があります。 この設定に関する追加情報については、サービス ドキュメントを参照してください。

DocumentTranslationClient

Document Translation クライアント ライブラリとの対話は、 の DocumentTranslationClientインスタンスで始まります。 クライアントは、次の操作を提供します。

  • 変換操作を作成して、ソース コンテナー内のドキュメントを翻訳し、結果をターゲット コンテナーに書き込みます。
  • 翻訳操作で個々のドキュメントの状態を確認し、各ドキュメントの進行状況を監視します。
  • 過去と現在のすべての翻訳操作を列挙します。
  • サポートされている用語集とドキュメントの形式を特定する。

翻訳入力

クライアント メソッドへの begin_translation 入力は、次の 2 つの異なる方法で提供できます。

  1. ドキュメントを含む単一のソース コンテナーは、別の言語に翻訳できます。
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

document_translation_client = DocumentTranslationClient("<endpoint>", AzureKeyCredential("<api_key>"))
poller = document_translation_client.begin_translation("<sas_url_to_source>", "<sas_url_to_target>", "<target_language>")
  1. または、複数の異なるソースにそれぞれ独自のターゲットを指定できます。
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient, DocumentTranslationInput, TranslationTarget

my_input = [
    DocumentTranslationInput(
        source_url="<sas_url_to_source_A>",
        targets=[
            TranslationTarget(target_url="<sas_url_to_target_fr>", language="fr"),
            TranslationTarget(target_url="<sas_url_to_target_de>", language="de")
        ]
    ),
    DocumentTranslationInput(
        source_url="<sas_url_to_source_B>",
        targets=[
            TranslationTarget(target_url="<sas_url_to_target_fr>", language="fr"),
            TranslationTarget(target_url="<sas_url_to_target_de>", language="de")
        ]
    ),
    DocumentTranslationInput(
        source_url="<sas_url_to_source_C>",
        targets=[
            TranslationTarget(target_url="<sas_url_to_target_fr>", language="fr"),
            TranslationTarget(target_url="<sas_url_to_target_de>", language="de")
        ]
    )
]

document_translation_client = DocumentTranslationClient("<endpoint>", AzureKeyCredential("<api_key>"))
poller = document_translation_client.begin_translation(my_input)

注: 各ターゲット言語のtarget_urlは一意である必要があります。

フォルダーの下にあるドキュメントを翻訳する場合、または特定のドキュメントのみを翻訳する場合は、「 sample_begin_translation_with_filters.py」を参照してください。 サポートされているすべての言語については、サービスのドキュメント を参照してください。

Long-Running操作

実行時間の長い操作は、操作を開始するためにサービスに送信された最初の要求で構成される操作です。その後、間隔を指定してサービスをポーリングして、操作が完了したか失敗したか、成功したかどうかを判断して結果を取得します。

ドキュメントを翻訳するメソッドは、実行時間の長い操作としてモデル化されます。 クライアントは、 または AsyncDocumentTranslationLROPollerをbegin_<method-name>返すメソッドをDocumentTranslationLROPoller公開します。 呼び出し元は、 メソッドから返された poller オブジェクトを呼び出 result() して、操作が完了するまで待機する begin_<method-name> 必要があります。 実行時間の長い操作の使用例を示すサンプル コード スニペット 用意されています。

例

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

ドキュメントを翻訳する

ソース コンテナー内のすべてのドキュメントをターゲット コンテナーに変換します。 フォルダーの下にあるドキュメントを翻訳する場合、または特定のドキュメントのみを翻訳する場合は、「 sample_begin_translation_with_filters.py」を参照してください。

from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

endpoint = "https://<resource-name>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")
source_container_sas_url_en = "<sas-url-en>"
target_container_sas_url_es = "<sas-url-es>"

document_translation_client = DocumentTranslationClient(endpoint, credential)

poller = document_translation_client.begin_translation(source_container_sas_url_en, target_container_sas_url_es, "es")

result = poller.result()

print(f"Status: {poller.status()}")
print(f"Created on: {poller.details.created_on}")
print(f"Last updated on: {poller.details.last_updated_on}")
print(f"Total number of translations on documents: {poller.details.documents_total_count}")

print("\nOf total documents...")
print(f"{poller.details.documents_failed_count} failed")
print(f"{poller.details.documents_succeeded_count} succeeded")

for document in result:
    print(f"Document ID: {document.id}")
    print(f"Document status: {document.status}")
    if document.status == "Succeeded":
        print(f"Source document location: {document.source_document_url}")
        print(f"Translated document location: {document.translated_document_url}")
        print(f"Translated to language: {document.translated_to}\n")
    else:
        print(f"Error Code: {document.error.code}, Message: {document.error.message}\n")

複数の入力を翻訳する

複数のソース コンテナー内のドキュメントを使用して、異なる言語の複数のターゲット コンテナーへの翻訳を開始します。

from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient, DocumentTranslationInput, TranslationTarget

endpoint = "https://<resource-name>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")
source_container_sas_url_de = "<sas-url-de>"
source_container_sas_url_en = "<sas-url-en>"
target_container_sas_url_es = "<sas-url-es>"
target_container_sas_url_fr = "<sas-url-fr>"
target_container_sas_url_ar = "<sas-url-ar>"

document_translation_client = DocumentTranslationClient(endpoint, credential)

poller = document_translation_client.begin_translation(
    [
        DocumentTranslationInput(
            source_url=source_container_sas_url_en,
            targets=[
                TranslationTarget(target_url=target_container_sas_url_es, language="es"),
                TranslationTarget(target_url=target_container_sas_url_fr, language="fr"),
            ],
        ),
        DocumentTranslationInput(
            source_url=source_container_sas_url_de,
            targets=[
                TranslationTarget(target_url=target_container_sas_url_ar, language="ar"),
            ],
        )
    ]
)

result = poller.result()

for document in result:
    print(f"Document ID: {document.id}")
    print(f"Document status: {document.status}")
    if document.status == "Succeeded":
        print(f"Source document location: {document.source_document_url}")
        print(f"Translated document location: {document.translated_document_url}")
        print(f"Translated to language: {document.translated_to}\n")
    else:
        print(f"Error Code: {document.error.code}, Message: {document.error.message}\n")

翻訳操作を一覧表示する

リソースに対して送信された翻訳操作を列挙します。

from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

endpoint = "https://<resource-name>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")

document_translation_client = DocumentTranslationClient(endpoint, credential)

operations = document_translation_client.list_translation_statuses()  # type: ItemPaged[TranslationStatus]

for operation in operations:
    print(f"\nID: {operation.id}")
    print(f"Status: {operation.status}")
    print(f"Created on: {operation.created_on}")
    print(f"Last updated on: {operation.last_updated_on}")
    print(f"Total number of translations on documents: {operation.documents_total_count}")
    print(f"Total number of characters charged: {operation.total_characters_charged}")

    print("Of total documents...")
    print(f"{operation.documents_failed_count} failed")
    print(f"{operation.documents_succeeded_count} succeeded")
    print(f"{operation.documents_canceled_count} canceled")

ドキュメント翻訳クライアント ライブラリと Azure Storage BLOB を使用してドキュメントをアップロードし、コンテナーの SAS トークンを作成し、完成した翻訳済みドキュメントをダウンロードする方法については、この サンプルを参照してください。 このサンプルを実行するには、 azure-storage-BLOB ライブラリをインストールする必要があることに注意してください。

高度なトピック

次のセクションでは、用語集やカスタム翻訳モデルなどの高度な翻訳機能に関するいくつかの分析情報を提供します。

用語集

用語集はドメイン固有の辞書です。 たとえば、医療関連のドキュメントを翻訳する場合は、標準翻訳辞書で見つからない医療分野の多くの単語、用語、イディオムのサポートが必要な場合や、特定の翻訳が必要な場合があります。 ドキュメント翻訳が用語集のサポートを提供するのはこのためです。

用語集ファイルを作成する方法

ドキュメント翻訳では、次の形式の用語集がサポートされています。

ファイルの種類 拡張子 説明 サンプル
タブ区切りの値/TAB .tsv、.tab ウィキペディアで もっと読む glossary_sample.tsv
コンマ区切りの値 .csv ウィキペディアで詳細を読む glossary_sample.csv
Localization Interchange File Format .xlf、.xliff ウィキペディアで詳細を読む glossary_sample.xlf

サポートされているすべての形式 については、こちらを参照してください。

ドキュメント翻訳で用語集を使用する方法

ドキュメント翻訳で用語集を使用するには、最初に用語集ファイルを BLOB コンテナーにアップロードしてから、コード サンプル sample_translation_with_glossaries.py のようにファイルへの SAS URL を指定する必要があります。

カスタム翻訳モデル

ドキュメント翻訳のエンジンを翻訳に使用する代わりに、独自のカスタム Azure マシン/ディープ ラーニング モデルを使用できます。

カスタム翻訳モデルを作成する方法

独自のカスタム Azure 翻訳モデルを作成、プロビジョニング、デプロイする方法の詳細については、次の手順に従 ってください。

ドキュメント翻訳でカスタム翻訳モデルを使用する方法

ドキュメント翻訳でカスタム翻訳モデルを使用するには、まずモデルを作成してデプロイし、次にドキュメント翻訳で使用するコード サンプル sample_translation_with_custom_model.py に従う必要があります。

トラブルシューティング

全般

ドキュメント翻訳クライアント ライブラリでは、 Azure Core で定義されている例外が発生します。

ログの記録

このライブラリでは、標準の ログ記録 ライブラリを使用してログを記録します。

HTTP セッション (URL、ヘッダーなど) に関する基本情報は、レベルで INFO ログに記録されます。

要求/応答本文や未作成のヘッダーなど、詳細なDEBUGレベルのログ記録は、クライアントで有効にすることも、キーワード引数を使用してlogging_enable操作ごとに有効にすることもできます。

SDK のログ記録に関する完全なドキュメントと例 については、こちらを参照してください。

オプションの構成

省略可能なキーワード引数は、クライアントレベルおよび操作ごとのレベルで渡すことができます。 azure-core リファレンス ドキュメント では、再試行、ログ記録、トランスポート プロトコルなどの使用可能な構成について説明しています。

次のステップ

次のセクションでは、Document Translation Python クライアント ライブラリで使用される一般的なパターンを示すコード スニペットをいくつか示します。 その他のサンプルは、 samples ディレクトリにあります。

その他のサンプル コード

これらのコード サンプルは、Azure Document Translation クライアント ライブラリを使用した一般的なシナリオ操作を示しています。

非同期サンプル

このライブラリには、非同期 API の完全なセットも含まれています。 それらを使用するには、まず、 aiohttp などの非同期トランスポートをインストールする必要があります。 非同期クライアントは 名前空間の下にあります azure.ai.translation.document.aio 。

その他のドキュメント

Azure Cognitive Services ドキュメント翻訳に関するより広範なドキュメントについては、docs.microsoft.com に関する ドキュメント翻訳のドキュメント を参照してください。

共同作成

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

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

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