Azure AI 翻訳コンテナーをインストールして実行する
コンテナーを使うと、独自のインフラストラクチャで Azure AI Translator API をホストすることができます。 コンテナー イメージには、プライベート、パブリック、またはパーソナル コンピューティング環境でアプリケーションを一貫して実行するために必要なすべてのライブラリ、ツール、依存関係が含まれています。 Azure AI Translator API をリモートで呼び出すことでは満たすことができないセキュリティまたはデータ ガバナンスの要件がある場合は、コンテナーが適しています。
この記事では、Docker API を使用した翻訳コンテナー オンラインをインストールして実行する方法について学習します。 Azure AI 翻訳コンテナーでは、次の操作がサポートされています。
テキスト翻訳。 サポート対象の
source言語からサポート対象のtarget言語へ、単語やフレーズのコンテクストに応じた意味をリアルタイムで翻訳します。 詳細については、コンテナー: テキストの翻訳に関するページを参照してください。🆕 テキスト音訳。 ある言語スクリプトまたは記述システムから別の言語スクリプトまたは記述システムにリアルタイムでテキストを変換します。 詳細については、コンテナー: テキストの音訳に関するページを参照してください。
🆕 ドキュメント翻訳。 リアルタイムで構造と形式を保持しながらドキュメントを同期して翻訳します。 詳細については、コンテナー: ドキュメントの翻訳に関するページを参照してください。
前提条件
作業を開始するには、次のリソース、限定的アクセス承認、ツールが必要です。
管理
アクティブな Azure サブスクリプション。 ない場合は、12 か月間無料のアカウントを作成できます
接続された翻訳コンテナーまたは切断された翻訳コンテナーのいずれかへの承認されたアクセス要求。
承認済みサブスクリプション ID の下で作成された Azure AI 翻訳リソース (マルチサービス Azure AI サービス リソースではありません)。 API キーとリソースに関連付けられたエンドポイント URI が必要です。 コンテナーを開始するには両方の値が必要であり、Azure portal のリソースの概要ページで確認できます。
接続された翻訳コンテナーの場合は、
S1価格レベルを選択します。
切断された翻訳コンテナーの場合は、価格レベルとして
Commitment tier disconnected containersを選択します。 切断されたコンテナー アクセス要求が承認されている場合にのみ、コミットメント レベルを購入するオプションが表示されます。
Docker ツール
レジストリ、リポジトリ、コンテナー、コンテナー イメージなど、Docker の概念の基本的な理解に加えて、基本的なdocker 用語とコマンドの知識が必要です。 Docker やコンテナーの基礎に関する入門情報については、「Docker overview」(Docker の概要) を参照してください。
ヒント
コンピューティング環境に Docker Desktop を追加することを検討してください。 Docker Desktop は、コンテナー化されたアプリケーションをデスクトップから直接ビルドし、実行し、共有できるグラフィカル ユーザー インターフェイス (GUI) です。
DockerDesktop には、Docker Engine、Docker CLI クライアント、Docker Compose が含まれており、次のお好みのオペレーティング システム用に Docker を構成するパッケージが提供されています。
| ツール | 説明 | 条件 |
|---|---|---|
| Docker Engine | Docker Engine は、Docker コンテナー化プラットフォームのコア コンポーネントです。 コンテナーをビルドし、実行し、管理するには、ホスト コンピューターにインストールする必要があります。 | すべての操作に必要です。 |
| Docker Compose | Docker Compose ツールは、マルチコンテナー アプリケーションを定義して実行するために使用されます。 | サポート コンテナーに必要です。 |
| Docker CLI | Docker コマンドライン インターフェイスを使用すると、ローカル マシンから直接 Docker Engine と対話し、Docker コンテナーを管理できます。 | 推奨 |
ホスト コンピューターの要件
ホストとは、Docker コンテナーを実行する x64 ベースのコンピューターのことです。 お客様のオンプレミス上のコンピューターを使用できるほか、次のような Azure 内のこれらの Docker ホスティング サービスのいずれかを使用することもできます。
- Azure Kubernetes Service。
- Azure Container Instances。
- Azure Stack にデプロイされた Kubernetes クラスター。 詳しくは、「Kubernetes を Azure Stack にデプロイする」をご覧ください。
| オペレーティング システム | システム要件 |
|---|---|
| Windows | • Windows 10 または Windows 11 がインストールされていること • 64 ビット プロセッサ • 最低 4 GB の RAM • Windows Hyper-V、コンテナー機能、BIOS レベルのハードウェア仮想化 • 詳細については、「Windows で Docker Desktop をインストールする」を参照してください |
| Mac | • 2010 コンピューター モデル以降 • OS 10.13 以降 • 最低 4 GB の RAM • 詳細については、「Mac で Docker Desktop をインストールする」を参照してください |
| Linux | • 64 ビット バージョンの Ubuntu (最新の長期サポート (LTS) バージョンまたは LTS 以外の現行バージョン)、Debian 12、Fedora 38、または Fedora 39 • 仮想化の CPU サポート • 最低 4 GB の RAM • 詳細については、「Linux で Docker Desktop をインストールする」を参照してください |
推奨される CPU コア数とメモリ
Note
最小仕様と推奨仕様は、Docker の制限に基づくもので、ホスト マシンのリソースに基づくものではありません。
次の表では、各コンテナーで許可される 1 秒あたりのトランザクション数 (TPS) の最小仕様と推奨される仕様について説明します。
| 機能 | 推奨される最小仕様 | メモ |
|---|---|---|
| テキストの変換 | 4 コア、4 GB のメモリ | |
| テキスト音訳 | 4 コア、2 GB のメモリ | |
| ドキュメント翻訳 | 4 コア、6 GB のメモリ | 同時に処理できるドキュメント数は、次の式を用いて計算できます: [(n-2) の最小値, (m-6)/4)]。 • n は CPU コアの数です。• m はメモリの GB です。• 例: 8コア、32 GB のメモリでは、6 つのドキュメント [( 8-2) の最小値, (36-6)/4)] を同時に処理できます。 |
各コアは少なくとも 2.6 ギガヘルツ (GHz) 以上にする必要があります。
すべての言語ペアについて、2 GB のメモリを使用することをお勧めします。
ベースライン要件に加え、同時ドキュメント処理ごとに 4GB のメモリが必要です。
ヒント
docker images コマンドを使用して、ダウンロードしたコンテナー イメージを一覧表示できます。 たとえば、次のコマンドは、ダウンロードした各コンテナー イメージの ID、リポジトリ、およびタグが表として書式設定されて表示されます。
docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}" IMAGE ID REPOSITORY TAG <image-id> <repository-path/name> <tag-name>
必要な入力
すべての Azure AI コンテナーには、次の入力値が必要です。
EULA の同意設定。
Eula=acceptの値で設定されたエンドユーザー使用許諾契約書 (EULA) が必要です。API キーとエンドポイント URL。 この API キーは、コンテナーを開始するために使用されます。 API キーとエンドポイント URL の値を取得するには、Azure AI 翻訳リソースの [キーとエンドポイント] ページに移動し、
Copy to clipboardアイコンを選択します。ドキュメントを翻訳しようとしている場合は、ドキュメント翻訳エンドポイントを使用してください。
重要
キーは、Azure AI リソースへのアクセスに使用されます。 キーを共有しないでください。 Azure Key Vault を使用するなどして、安全に保管してください。
これらのキーを定期的に再生成することもお勧めします。 API 呼び出しを行うために必要なキーは 1 つだけです。 最初のキーを再生成するときに、2 番目のキーを使用してサービスに継続的にアクセスすることができます。
請求
コンテナーへのクエリは、API
Keyに使われる Azure リソースの価格レベルで課金されます。ドキュメントとイメージの処理に使用されるコンテナー インスタンスごとに課金されます。
docker run コマンドは、Microsoft アーティファクト レジストリからイメージをダウンロードし、次の 3 つのオプションのすべてで有効な値が指定されると、コンテナーを起動します。
| オプション | 説明 |
|---|---|
ApiKey |
課金情報を追跡するために使われる Azure AI サービス リソースのキー。 このオプションの値には、 Billing に指定されたプロビジョニング済みのリソースのキーが設定されている必要があります。 |
Billing |
課金情報を追跡するために使われる Azure AI サービス リソースのエンドポイント。 このオプションの値には、プロビジョニング済みの Azure リソースのエンドポイント URI が設定されている必要があります。 |
Eula |
お客様がコンテナーのライセンスに同意したことを示します。 このオプションの値は accept に設定する必要があります。 |
Azure への接続
コンテナー課金引数の値により、コンテナーは課金エンドポイントに接続し、実行することができます。
コンテナーから、約 10 ～ 15 分ごとに使用状況が報告されます。 許可された時間枠内でコンテナーが Azure に接続しなかった場合、コンテナーは引き続き実行されますが、課金エンドポイントが復元されるまでクエリには対応しません。
接続は、10 ～15 分の同じ時間間隔で、10 回試行されます。 10 回以内に課金エンドポイントに接続できなかった場合、コンテナーによる要求の処理は停止されます。 課金のために Microsoft に送信される情報の例については、Azure AI コンテナーに関する FAQ を参照してください。
コンテナー イメージとタグ
Azure AI サービスのコンテナー イメージは、Microsoft アーティファクト レジストリ カタログで見つけることができます。 Azure AI 翻訳コンテナーは azure-cognitive-services/translator リポジトリ内に存在し、text-translation という名前が付けられています。 完全修飾コンテナー イメージ名は mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest です。
最新バージョンのコンテナーを使用するには、最新のタグを使用します。 MCR の Azure AI サービス テキスト翻訳バージョン タグの完全な一覧を表示できます。
コンテナーの使用
タブを選択し、Azure AI 翻訳コンテナー環境を選びます:
Azure AI 翻訳コンテナーを使用すると、独自の環境で Azure AI 翻訳サービス on-premise のいくつかの機能を実行できます。 接続されたコンテナーはローカルに実行され、課金のために使用状況情報をクラウドに送信します。
コンテナー イメージのダウンロードと実行
docker run コマンドは、Microsoft アーティファクト レジストリからイメージをダウンロードし、コンテナーを起動します。
重要
- 以降のセクションの Docker コマンドには、行連結文字としてバック スラッシュ (
\) が使用されています。 お客様のホスト オペレーティング システムの要件に応じて、置換または削除してください。 - コンテナーを実行するには、
EULA、Billing、ApiKeyの各オプションを指定する必要があります。そうしないと、コンテナーが起動しません。 - ドキュメントを翻訳しようとしている場合は、ドキュメント翻訳エンドポイントを使用してください。
docker run --rm -it -p 5000:5000 --memory 12g --cpus 4 \
-v /mnt/d/TranslatorContainer:/usr/local/models \
-e apikey={API_KEY} \
-e eula=accept \
-e billing={ENDPOINT_URI} \
-e Languages=en,fr,es,ar,ru \
mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest
Docker コマンド:
- ダウンロードしたコンテナー イメージから実行中の翻訳コンテナーを作成します。
- 12 ギガバイト (GB) のメモリと 4 つの CPU コアを割り当てます。
- 伝送制御プロトコル (TCP) ポート 5000 を公開し、コンテナー用に擬似 TTY を割り当てます。 ここで、
localhostアドレスはホスト マシンではなく、コンテナー自体を指しています。 - 使用許諾契約書 (EULA) に同意します。
- 課金エンドポイントを構成します。
- 英語、フランス語、スペイン語、アラビア語、ロシア語の翻訳モデルをダウンロードします。
- コンテナーの終了後にそれを自動的に削除します。 ホスト コンピューター上のコンテナー イメージは引き続き利用できます。
ヒント
追加の Docker Compose:
docker psは実行中のコンテナーを一覧表示します。docker pause {your-container name}は実行中のコンテナーを一時停止します。docker unpause {your-container-name}は一時停止したコンテナーを再開します。docker restart {your-container-name}は実行中のコンテナーを再開します。docker execにより、実行中のコンテナーで lto detach コマンドまたは set 環境変数コマンドを実行できます。
詳細については、Docker CLI リファレンスを参照してください。
同じホスト上で複数のコンテナーを実行する
公開されているポートを使って複数のコンテナーを実行する予定の場合、必ず各コンテナーを別の公開されているポートで実行してください。 たとえば、最初のコンテナーをポート 5000 上で、2 番目のコンテナーを 5001 上で実行します。
このコンテナーと、別の Azure AI コンテナーを HOST 上で同時に実行することができます。 同じ Azure AI コンテナーの複数のコンテナーを実行することもできます。
翻訳コンテナー エンドポイントに対するクエリを実行する
コンテナーには、REST ベースの Translator エンドポイント API が用意されています。 ソース言語 (from=en) を指定した要求の例を次に示します。
curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-HANS" -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"
Note
ソース言語検出には、追加のコンテナーが必要です。 詳細については、「サポート コンテナー」を参照してください
cURL POST 要求が
Service is temporarily unavailable応答を返した場合は、コンテナーの準備が完了していません。 数分後にもう一度お試しください。
![Azure portal の [キーとエンドポイント] ページのスクリーンショット。](media/keys-endpoint-container.png)
コンテナーが実行されていることを検証する
コンテナーが実行されていることを検証する方法は複数あります。
コンテナーでは、コンテナーが実行されていることを視覚的に検証するために、
/にホームページを用意しています。使い慣れた Web ブラウザーを開いて、問題のコンテナーの外部 IP アドレスと公開ポートに移動できます。 次に示されている要求 URL を使って、コンテナーが実行中であることを確認します。 一覧に示した例の要求 URL は
http://localhost:5000を指していますが、実際のコンテナーは異なる可能性があります。 実際のコンテナーの外部 IP アドレスと公開ポートに移動していることに注意してください。
| 要求 URL | 目的 |
|---|---|
http://localhost:5000/ |
コンテナーには、ホーム ページが用意されています。 |
http://localhost:5000/ready |
GET で要求します。 これにより、コンテナーがモデルに対するクエリを受け取る準備ができていることを確認できます。 この要求は Kubernetes の liveness probe と readiness probe に対して使用できます。 |
http://localhost:5000/status |
GET で要求します。 これにより、コンテナーを開始するために使用された API キーが有効であるかどうかを、エンドポイント クエリを発生させずに確認できます。 この要求は Kubernetes の liveness probe と readiness probe に対して使用できます。 |
http://localhost:5000/swagger |
コンテナーには、エンドポイントの完全なドキュメント一式と、 [Try it out](試してみる) の機能が用意されています。 この機能を使用すると、コードを一切記述することなく、お客様の設定を Web ベースの HTML フォームに入力したりクエリを実行したりできます。 クエリから戻ると、必要な HTTP のヘッダーと本文の形式を示すサンプル CURL コマンドが得られます。 |
Azure AI サービス コンテナーの実行で問題が発生している場合は、Microsoft 診断コンテナーを使用してみることができます。 このコンテナーを使用して、Azure AI コンテナーが想定どおりに機能しなくなる可能性がある、展開環境での一般的なエラーを診断します。
コンテナーを取得するには、次の docker pull コマンドを使用します。
docker pull mcr.microsoft.com/azure-cognitive-services/diagnostic
その後で、コンテナーを実行します。 {ENDPOINT_URI} をエンドポイントに置き換え、{API_KEY} をリソースへのキーに置き換えます。
docker run --rm mcr.microsoft.com/azure-cognitive-services/diagnostic \
eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}
課金エンドポイントへのネットワーク接続がコンテナーでテストされます。
コンテナーの停止
コンテナーをシャットダウンするには、コンテナーが実行されているコマンドライン環境で、Ctrl + C キーを押します。
サポート コンテナーのユース ケース
翻訳クエリの中には、操作を正常に完了するためにサポート コンテナーが必要なものがあります。 Office ドキュメントを使用し、ソース言語の検出が必要ない場合は、翻訳コンテナーのみ必要です。 ただし、ソース言語の検出が必要な場合や、スキャンした PDF ドキュメントを使用する場合は、次のサポート コンテナーが必要です。
次の表に、テキスト翻訳やドキュメント翻訳の操作に必要なサポート コンテナーを一覧表示します。 翻訳コンテナーは、Azure アカウント上の Azure AI 翻訳リソースを介して、Azure に課金情報を送信します。
| 操作 | クエリの要求 | ドキュメント型 | サポート コンテナー |
|---|---|---|---|
| • テキスト翻訳 • ドキュメント翻訳 |
from が指定されています。 |
Office ドキュメント | なし |
| • テキスト翻訳 • ドキュメント翻訳 |
from は指定されていません。 ソース言語を特定するための自動言語検出が必要です。 |
Office ドキュメント | ✔️ テキスト分析: 言語コンテナー |
| • テキスト翻訳 • ドキュメント翻訳 |
from が指定されています。 |
スキャンされた PDF ドキュメント | ✔️ ビジョン: 読み取りコンテナー |
| • テキスト翻訳 • ドキュメント翻訳 |
ソース言語を特定するための自動言語検出が必要な from は指定されていません。 |
スキャンされた PDF ドキュメント | ✔️ テキスト分析: 言語コンテナー ✔️ ビジョン: 読み取りコンテナー |
docker compose を使用したサポート コンテナーを操作する
Docker Compose は、通常、compose.yaml という名前の単一の YAML ファイルを使用して、複数のコンテナー アプリケーションを構成できるツールです。 docker compose up コマンドを使用してコンテナー アプリケーションを起動し、docker compose down コマンドを使用してコンテナーを停止および削除します。
Docker Desktop CLI をインストールした場合は、Docker Compose とその前提条件が含まれます。 Docker Desktop がない場合は、Docker Compose のインストールに関する概要を参照してください。
アプリケーションを作成する
任意のエディターまたは IDE を使用して、
container-environmentまたは希望の名前のアプリ用の新しいディレクトリを作成します。compose.yamlという名前の新しい YAML ファイルを作成します。composeファイルには .yml または .yml 拡張子を使用できます。次の YAML コード サンプルをコピーして、
compose.yamlファイルに貼り付けます。{TRANSLATOR_KEY}と{TRANSLATOR_ENDPOINT_URI}を Azure portal Translator インスタンスの値からキー値とエンドポイント値に置き換えます。 ドキュメントを翻訳しようとしている場合は、document translation endpointを使用してください。上位レベル名 (
azure-ai-translator、azure-ai-language、azure-ai-read) は、指定したパラメーターです。container_nameはオプションのパラメーターで、docker composeに名前を生成させるのではなく、実行時にコンテナーの名前を設定します。services: azure-ai-translator: container_name: azure-ai-translator image: mcr.microsoft.com/azure-cognitive-services/translator/text-translation::latest environment: - EULA=accept - billing={TRANSLATOR_ENDPOINT_URI} - apiKey={TRANSLATOR_KEY} - ladurl=http://azure-ai-language:5000 - VISIONURL=http://azure-ai-read:5000 ports: - "5000:5000" volumes: - {your local folder}:/usr/local/models azure-ai-language: container_name: azure-ai-language image: mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest environment: - EULA=accept - billing={LANGUAGE_RESOURCE_ENDPOINT_URI} - apiKey={LANGUAGE_RESOURCE_KEY} - Languages=en,es - LADINCLUSTER=true azure-ai-read: container_name: azure-ai-read image: mcr.microsoft.com/azure-cognitive-services/vision/read:latest environment: - EULA=accept - billing={COMPUTER_VISION_ENDPOINT_URI} - apiKey={COMPUTER_VISION_KEY}ターミナルを開いて
container-environmentフォルダーに移動し、次のdocker-composeコ マンドを使用してコンテナーを起動します。docker compose upコンテナーを停止するには、次のコマンドを使用します。
docker compose downヒント
役立つ Docker コマンド
docker compose pauseは実行中のコンテナーを一時停止します。docker compose unpause {your-container-name}は一時停止したコンテナーを再開します。docker compose restartは、以前の変更はすべてそのままに、停止中および実行中のすべてのコンテナーを再起動します。compose.yaml構成を変更しても、その変更はdocker compose restartコマンドでは更新されません。compose.yamlファイルの更新や変更を反映するには、docker compose upコマンドを使用する必要があります。docker compose ps -aは、停止中のものも含めて、すべてのコンテナーを一覧表示します。docker compose execにより、実行中のコンテナーで lto detach コマンドまたは set 環境変数コマンドを実行できます。
詳細については、Docker CLI リファレンスを参照してください。
翻訳コンテナーおよびサポート コンテナーのイメージとタグ
Azure AI サービスのコンテナー イメージは、Microsoft アーティファクト レジストリ カタログで見つけることができます。 次の表に、テキスト翻訳やドキュメント翻訳用の完全修飾イメージの場所を一覧表示します。
| コンテナー | 画像の場所 | メモ |
|---|---|---|
| 翻訳: テキスト翻訳とドキュメント翻訳 | mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest |
MCR の Azure AI サービス テキスト翻訳バージョン タグの完全な一覧を表示できます。 |
| テキスト分析: 言語 | mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest |
MCR の Azure AI サービス Text Analytics Language バージョン タグの完全な一覧を表示できます。 |
| Vision: 読み取り | mcr.microsoft.com/azure-cognitive-services/vision/read:latest |
MCR の Azure AI サービス Computer Vision Read の OCR バージョン タグの完全な一覧を表示できます。 |
その他のパラメーターとコマンド
コンテナーを実行するために使用できる他のパラメーターとコマンドを次に示します。
使用状況レコード
切断された環境で Docker コンテナーを運用する場合、コンテナーは、使用状況レコードをボリュームに書き込んで、時間をかけて収集されるようにします。 REST API エンドポイントを呼び出して、サービス使用状況に関するレポートを生成することもできます。
ログを格納するための引数
切断された環境で実行する場合は、使用状況ログを格納するために、コンテナーで出力マウントを利用できる必要があります。 たとえば、{OUTPUT_PATH} をログの格納場所のパスに置き換えて、-v /host/output:{OUTPUT_PATH} と Mounts:Output={OUTPUT_PATH} を次の例に含めます。
docker run コマンドの例
docker run -v /host/output:{OUTPUT_PATH} ... <image> ... Mounts:Output={OUTPUT_PATH}
Kubernetes デプロイの環境変数名
Translator など、一部の Azure AI コンテナーでは、コンテナーの実行時にコロン (
:) を含む環境変数の名前を渡す必要があります。Kubernetes では環境変数の名前にコロンを使用できません。 解決するには、Kubernetes にデプロイするときに、コロンを 2 つのアンダースコア文字 (
__) に置き換えます。 環境変数名に使用できる形式の例を次に示します:
env:
- name: Mounts__License
value: "/license"
- name: Mounts__Output
value: "/output"
この例では、docker run コマンドの Mounts:License と Mounts:Output の環境変数の既定の形式を置き換えます。
コンテナー エンドポイントを使用して使用状況レコードを取得する
コンテナーには、その使用状況に関するレコードを返すための 2 つのエンドポイントが用意されています。
すべてのレコードを取得する
次のエンドポイントは、マウントされた課金レコード ディレクトリに収集されたすべての使用状況を要約するレポートを提供します。
https://<service>/records/usage-logs/
すべてのレコードを取得するための HTTPS エンドポイントの例
http://localhost:5000/records/usage-logs
特定の月のレコードを取得する
次のエンドポイントは、特定の月と年の使用状況を要約したレポートを提供します。
https://<service>/records/usage-logs/{MONTH}/{YEAR}
特定の月および年のレコードを取得するための HTTPS エンドポイントの例
http://localhost:5000/records/usage-logs/03/2024
この使用状況ログ エンドポイントからは、次の例のような JSON 応答が返されます。
接続済みコンテナー
使用料金は、quantity 値に基づいて計算されます。
{
"apiType": "string",
"serviceName": "string",
"meters": [
{
"name": "string",
"quantity": 256345435
}
]
}
まとめ
この記事では、Azure AI 翻訳コンテナーの概念とそのダウンロード、インストール、および実行のワークフローについて説明しました。
Azure AI 翻訳コンテナーは、テキスト翻訳、同期ドキュメント翻訳、テキスト音訳をサポートしています。
コンテナー イメージは、Docker のコンテナー レジストリからダウンロードされて、実行されます。
コンテナーをインスタンス化するときには、課金情報を指定する必要があります。