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

[アーティクル]
04/05/2023

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 を参照してください

作業の開始

前提条件

このパッケージを使用するには、Python 3.6 以降が必要です。
このパッケージを使用するには、 Azure サブスクリプションと Translator リソースが必要です。

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

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

ドキュメントAzure Blob Storageコンテナーを設定する
必要に応じて、用語集またはカスタムモデルを翻訳に適用する
次のいずれかのオプションを使用して、ストレージアカウントへのアクセスを許可します。
- 適切なアクセス許可を使用してコンテナー (またはファイル) に SAS トークンを生成する
- マネージド ID を作成して使用してストレージアカウントへのアクセスを許可する

DocumentTranslationClient

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

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

翻訳入力

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

ドキュメントを含む単一のソースコンテナーは、別の言語に翻訳できます。

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>")

または、複数の異なるソースにそれぞれ独自のターゲットを指定できます。

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 クライアントライブラリを使用した一般的なシナリオ操作を示しています。

クライアント認証: sample_authentication.py
ドキュメントの翻訳を開始する: sample_begin_translation.py
複数の入力で翻訳する: sample_translate_multiple_inputs.py
ドキュメントの状態を確認する: sample_check_document_statuses.py
送信されたすべての翻訳操作を一覧表示する: sample_list_translations.py
翻訳にカスタム用語集を適用する: sample_translation_with_glossaries.py
Azure Blob Storageを使用して翻訳リソースを設定する: sample_translation_with_azure_blob.py

非同期サンプル

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

クライアント認証: sample_authentication_async.py
ドキュメントの翻訳を開始する: sample_begin_translation_async.py
複数の入力で翻訳する: sample_translate_multiple_inputs_async.py
ドキュメントの状態を確認する: sample_check_document_statuses_async.py
送信されたすべての翻訳操作を一覧表示する: sample_list_translations_async.py
翻訳にカスタム用語集を適用する: sample_translation_with_glossaries_async.py
Azure Blob Storageを使用して翻訳リソースを設定する: sample_translation_with_azure_blob_async.py

その他のドキュメント

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

次の方法で共有

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

免責事項

作業の開始

前提条件

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

Translator リソースを作成する

クライアントを認証する

エンドポイントの参照

API キーを取得する

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

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

主要な概念

DocumentTranslationClient

翻訳入力

Long-Running操作

例

ドキュメントを翻訳する

複数の入力を翻訳する

翻訳操作を一覧表示する

高度なトピック

用語集

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

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

カスタム翻訳モデル

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

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

トラブルシューティング

全般

ログの記録

オプションの構成

次のステップ

その他のサンプルコード

非同期サンプル

その他のドキュメント

共同作成

その他のリソース

次の方法で共有

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

免責事項

作業の開始

前提条件

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

Translator リソースを作成する

クライアントを認証する

エンドポイントの参照

API キーを取得する

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

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

主要な概念

DocumentTranslationClient

翻訳入力

Long-Running操作

例

ドキュメントを翻訳する

複数の入力を翻訳する

翻訳操作を一覧表示する

高度なトピック

用語集

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

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

カスタム翻訳モデル

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

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

トラブルシューティング

全般

ログの記録

オプションの構成

次のステップ

その他のサンプル コード

非同期サンプル

その他のドキュメント

共同作成

その他のリソース

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

その他のサンプルコード