カスタム固有表現認識コンテナーをインストールして実行する
コンテナーを使うと、独自のトレーニング済みモデルを使用して、独自のインフラストラクチャでカスタム固有表現認識 API をホストすることができます。 カスタム固有表現認識をリモートで呼び出すことでは満たすことができないセキュリティまたはデータ ガバナンスの要件がある場合は、コンテナーが適している可能性があります。
Note
- 無料アカウントは 1 か月あたり 5,000 テキスト レコードに制限されており、Free および Standard価格レベルだけがコンテナーに対して有効です。 トランザクションの要求レートの詳細については、「データとサービスの制限」を参照してください。
前提条件
- Azure サブスクリプションをお持ちでない場合は、無料アカウントを作成してください。
- ホスト コンピューターに Docker がインストールされていること。 コンテナーが Azure に接続して課金データを送信できるように、Docker を構成する必要があります。
- Windows では、Linux コンテナーをサポートするように Docker を構成することも必要です。
- Docker の概念に関する基本的な知識が必要です。
- Free (F0) または Standard (S) 価格レベルの言語リソース。
- トレーニングしてデプロイされたカスタム固有表現認識モデル
必須パラメーターの収集
すべての Azure AI コンテナーに対して 3 つの主要なパラメーターが必須です。 Microsoft ソフトウェア ライセンス条項について、値 accept が示される必要があります。 エンドポイント URI と API キーも必要です。
エンドポイント URL
{ENDPOINT_URI} の値は、対応する Azure AI サービス リソースの Azure portal の[概要] ページで入手できます。 [概要] ページに移動し、エンドポイントの上にマウスを合わせると、[クリップボードにコピー] アイコンが表示されます。 必要に応じて、エンドポイントをコピーして使用します。
キー
{API_KEY} の値はコンテナーを起動するために使用され、Azure portal で、対応する Azure AI サービス リソースの [キー] ページで入手できます。 [キー] ページに移動し、[クリップボードにコピー] アイコンを選択します。
重要
これらのサブスクリプション キーは、Azure AI サービス API にアクセスするために使用されます。 キーを共有しないでください。 安全に保管してください。 たとえば、Azure Key Vault を使用します。 また、これらのキーを定期的に再生成することをお勧めします。 API 呼び出しを行うために必要なキーは 1 つだけです。 最初のキーを再生成するときに、2 番目のキーを使用してサービスに継続的にアクセスすることができます。
ホスト コンピューターの要件と推奨事項
ホストとは、Docker コンテナーを実行する x64 ベースのコンピューターのことです。 お客様のオンプレミス上のコンピューターを使用できるほか、次のような Azure 内の Docker ホスティング サービスを使用することもできます。
- Azure Kubernetes Service。
- Azure Container Instances。
- Azure Stack にデプロイされた Kubernetes クラスター。 詳しくは、「Kubernetes を Azure Stack にデプロイする」をご覧ください。
次の表では、カスタム固有表現認識コンテナーの最小仕様と推奨仕様を説明します。 各 CPU コアは、少なくとも 2.6 ギガヘルツ (GHz) 以上である必要があります。 許容される 1 秒あたりのトランザクション数 (TPS) も示されています。
| 最小ホスト仕様 | 推奨されるホスト仕様 | 最小 TPS | 最大 TPS | |
|---|---|---|---|---|
| カスタム固有表現認識 | 1 コア、2 GB メモリ | 1 コア、4 GB メモリ | 15 | 30 |
CPU コアとメモリは、docker run コマンドの一部として使用される --cpus と --memory の設定に対応します。
カスタム固有表現認識モデルをエクスポートする
Docker イメージの実行を続行する前に、独自のトレーニング済みモデルをエクスポートしてコンテナーに公開する必要があります。 次のコマンドを使用してモデルを抽出し、以下のプレースホルダーを独自の値に置き換えます。
| プレースホルダー | 値 | 形式または例 |
|---|---|---|
| {API_KEY} | カスタム固有表現認識リソースのキー。 それは、Azure portal で、お使いのリソースの [キーとエンドポイント] ページで見つけることができます。 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
| {ENDPOINT_URI} | カスタム固有表現認識 API にアクセスするためのエンドポイント。 それは、Azure portal で、お使いのリソースの [キーとエンドポイント] ページで見つけることができます。 | https://<your-custom-subdomain>.cognitiveservices.azure.com |
| {PROJECT_NAME} | エクスポートするモデルを含むプロジェクトの名前。 これは Language Studio ポータルのプロジェクト タブで確認できます。 | myProject |
| {TRAINED_MODEL_NAME} | エクスポートするトレーニング済みモデルの名前。 トレーニング済みのモデルは、Language Studio ポータルのプロジェクトの下にあるモデルの評価タブで確認できます。 | myTrainedModel |
curl --location --request PUT '{ENDPOINT_URI}/language/authoring/analyze-text/projects/{PROJECT_NAME}/exported-models/{TRAINED_MODEL_NAME}?api-version=2023-04-15-preview' \
--header 'Ocp-Apim-Subscription-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"TrainedmodelLabel": "{TRAINED_MODEL_NAME}"
}'
docker pull によるコンテナー イメージの取得
カスタム固有表現認識コンテナー イメージは mcr.microsoft.com コンテナー レジストリ シンジケートにあります。 azure-cognitive-services/textanalytics/ リポジトリ内にあり、customner という名前が付いています。 完全修飾コンテナー イメージ名は mcr.microsoft.com/azure-cognitive-services/textanalytics/customner です。
最新バージョンのコンテナーを使用するには、latest タグを使用できます。 また、MCR でタグの完全な一覧を確認することもできます。
docker pull コマンドを使用して Microsoft Container Registry からコンテナー イメージをダウンロードします。
docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/customner:latest
ヒント
docker images コマンドを使用して、ダウンロードしたコンテナー イメージを一覧表示できます。 たとえば、次のコマンドは、ダウンロードした各コンテナー イメージの ID、リポジトリ、およびタグが表として書式設定されて表示されます。
docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
IMAGE ID REPOSITORY TAG
<image-id> <repository-path/name> <tag-name>
docker run によるコンテナーの実行
コンテナーをホスト コンピューター上に準備できたら、docker run コマンドを使用してコンテナーを実行します。 コンテナーは一度実行すると、お客様が停止するまで動作し続けます。
重要
- 以降のセクションの Docker コマンドには、行連結文字としてバック スラッシュ (
\) が使用されています。 お客様のホスト オペレーティング システムの要件に応じて、置換または削除してください。 - コンテナーを実行するには、
Eula、Billing、ApiKeyの各オプションを指定する必要があります。そうしないと、コンテナーが起動しません。 詳細については、「課金」を参照してください。
カスタム固有表現認識コンテナーを実行するには、次の docker run コマンドを実行します。 次のプレースホルダーを実際の値に置き換えてください。
| プレースホルダー | 値 | 形式または例 |
|---|---|---|
| {API_KEY} | カスタム固有表現認識リソースのキー。 それは、Azure portal で、お使いのリソースの [キーとエンドポイント] ページで見つけることができます。 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
| {ENDPOINT_URI} | カスタム固有表現認識 API にアクセスするためのエンドポイント。 それは、Azure portal で、お使いのリソースの [キーとエンドポイント] ページで見つけることができます。 | https://<your-custom-subdomain>.cognitiveservices.azure.com |
| {PROJECT_NAME} | エクスポートするモデルを含むプロジェクトの名前。 これは Language Studio ポータルのプロジェクト タブで確認できます。 | myProject |
| {LOCAL_PATH} | 前の手順でエクスポートしたモデルがダウンロードされるパス。 好きなパスを選択できます。 | C:/custom-ner-model |
| {TRAINED_MODEL_NAME} | エクスポートするトレーニング済みモデルの名前。 トレーニング済みのモデルは、Language Studio ポータルのプロジェクトの下にあるモデルの評価タブで確認できます。 | myTrainedModel |
docker run --rm -it -p5000:5000 --memory 4g --cpus 1 \
-v {LOCAL_PATH}:/modelPath \
mcr.microsoft.com/azure-cognitive-services/textanalytics/customner:latest \
EULA=accept \
BILLING={ENDPOINT_URI} \
APIKEY={API_KEY} \
projectName={PROJECT_NAME}
exportedModelName={TRAINED_MODEL_NAME}
このコマンドは、次の操作を行います。
- カスタム固有表現認識コンテナーを実行し、エクスポートしたモデルを指定されたローカル パスにダウンロードします。
- 1 つの CPU コアと 4 ギガバイト (GB) のメモリを割り当てます
- TCP ポート 5000 を公開し、コンテナーに pseudo-TTY を割り当てます
- コンテナーの終了後にそれを自動的に削除します。 ホスト コンピューター上のコンテナー イメージは引き続き利用できます。
同じホスト上で複数のコンテナーを実行する
公開されているポートを使って複数のコンテナーを実行する予定の場合、必ず各コンテナーを別の公開されているポートで実行してください。 たとえば、最初のコンテナーをポート 5000 上で、2 番目のコンテナーを 5001 上で実行します。
このコンテナーと、別の Azure AI サービス コンテナーを HOST 上で一緒に実行することができます。 同じ Azure AI サービス コンテナーの複数のコンテナーを実行することもできます。
コンテナーの予測エンドポイントに対するクエリの実行
コンテナーには、REST ベースのクエリ予測エンドポイント API が用意されています。
コンテナー API には、ホストの http://localhost:5000 を使用します。
コンテナーが実行されていることを検証する
コンテナーが実行されていることを検証する方法は複数あります。 問題になっているコンテナーの "外部 IP" アドレスと公開ポートを特定し、任意の Web ブラウザーを開きます。 次の各種の要求 URL を使用して、コンテナーが実行中であることを確認します。 ここに示す要求例の URL は http://localhost:5000 ですが、実際のコンテナーは異なる可能性があります。 使用するコンテナーの外部 IP アドレスと公開ポートを基にしてください。
| 要求 URL | 目的 |
|---|---|
http://localhost:5000/ |
コンテナーには、ホーム ページが用意されています。 |
http://localhost:5000/ready |
GET で要求することで、この URL により、コンテナーがモデルに対するクエリを受け取る準備ができていることを確認できます。 この要求は Kubernetes の liveness probe と readiness probe に対して使用できます。 |
http://localhost:5000/status |
これも GET で要求することで、この URL により、コンテナーを起動するために使用された API キーが有効であるかどうかを、エンドポイント クエリを発生させずに確認できます。 この要求は Kubernetes の liveness probe と readiness probe に対して使用できます。 |
http://localhost:5000/swagger |
コンテナーには、エンドポイントの完全なドキュメント一式と、 [Try it out](試してみる) の機能が用意されています。 この機能を使用すると、コードを一切記述することなく、お客様の設定を Web ベースの HTML フォームに入力したりクエリを実行したりできます。 クエリから戻った後、HTTP ヘッダーと HTTP 本文の必要な形式を示すサンプル CURL コマンドが得られます。 |
コンテナーの停止
コンテナーをシャットダウンするには、コンテナーが実行されているコマンドライン環境で、Ctrl + C キーを押します。
トラブルシューティング
出力マウントとログを有効にした状態でコンテナーを実行すると、コンテナーによってログ ファイルが生成されます。これらはコンテナーの起動時または実行時に発生した問題のトラブルシューティングに役立ちます。
ヒント
トラブルシューティング情報とガイダンスの詳細については、Azure AI コンテナーについてよくあるご質問 (FAQ) に関するページを参照してください。
課金
カスタム固有表現認識コンテナーは、Azure アカウントのカスタム固有表現認識リソースを使用して、Azure に課金情報を送信します。
コンテナーへのクエリは、 ApiKeyパラメーターに使用される Azure リソースの価格レベルで課金 されます。
Azure AI サービス コンテナーは、計測または課金エンドポイントに接続していないと、実行のライセンスが許可されません。 お客様は、コンテナーが常に課金エンドポイントに課金情報を伝えられるようにする必要があります。 Azure AI サービス コンテナーによって、お客様のデータ (解析対象の画像やテキストなど) が Microsoft に送信されることはありません。
Azure に接続する
コンテナーには、実行する課金引数の値が必要です。 これらの値により、コンテナーは課金エンドポイントに接続することができます。 コンテナーから、約 10 ～ 15 分ごとに使用状況が報告されます。 許可された時間枠内でコンテナーが Azure に接続しなかった場合、コンテナーは引き続き実行されますが、課金エンドポイントが復元されるまでクエリには対応しません。 接続は、10 ～15 分の同じ時間間隔で、10 回試行されます。 10 回以内に課金エンドポイントに接続できなかった場合、コンテナーによる要求の処理は停止されます。 課金のために Microsoft に送信される情報の例については、Azure AI サービス コンテナーについてよく寄せられる質問 を参照してください。
課金引数
docker run コマンドは、次の 3 つのオプションのすべてに有効な値が指定された場合にコンテナーを起動します。
| オプション | 説明 |
|---|---|
ApiKey |
課金情報を追跡するために使用される Azure AI サービス リソースの API キー。 このオプションの値には、 Billing に指定されたプロビジョニング済みのリソースの API キーが設定されている必要があります。 |
Billing |
課金情報を追跡するために使用される Azure AI サービス リソースのエンドポイント。 このオプションの値には、プロビジョニング済みの Azure リソースのエンドポイント URI が設定されている必要があります。 |
Eula |
お客様がコンテナーのライセンスに同意したことを示します。 このオプションの値は accept に設定する必要があります。 |
まとめ
この記事では、カスタム固有表現認識コンテナーの概念と、そのダウンロード、インストール、実行のワークフローについて説明しました。 要約すると:
- カスタム固有表現認識により、Docker 用の Linux コンテナーが提供されます。
- コンテナー イメージは Microsoft Container Registry (MCR) からダウンロードされます。
- コンテナー イメージを Docker で実行します。
- REST API または SDK を使用して、コンテナーのホスト URI を指定することによって、カスタム固有表現認識コンテナーの操作を呼び出すことができます。
- コンテナーをインスタンス化するときは、課金情報を指定する必要があります。
重要
Azure AI コンテナーは、計測のために Azure に接続していないと、実行のライセンスが許可されません。 お客様は、コンテナーが常に計測サービスに課金情報を伝えられるようにする必要があります。 お客様のデータ (解析対象のテキストなど) が Azure AI コンテナーによって Microsoft に送信されることはありません。
次のステップ
- 構成設定については、コンテナーの構成に関するページを参照してください。