展開とトラブルシューティング ── Azure OpenAI リファレンスアーキテクチャ「企業内向けチャットと社内文章検索」

この記事の内容

  • Azure OpenAI サービスの公開リファレンスアーキテクチャ（第5章：企業内向けチャットと社内文章検索）を実際に展開する手順を紹介します
  • Windows 10 のまっさらな環境から必要なツールをすべてインストールする方法を解説します
  • azd（Azure Developer CLI）を使ったデプロイ方法と、よく発生するエラーへの対処法を説明します
  • Azure OpenAI サービスの「論理削除」によるキャパシティ不足エラーなど、実際に遭遇したトラブルと解決策を共有します
  • Azure App Service・Azure OpenAI・Azure Cognitive Search・Blob Storage を組み合わせたアーキテクチャの概要を理解できます

アーキテクチャの概要

今回展開するサンプルは、GitHub 上で公開されている azure-samples/jp-azureopenai-samples リポジトリの 5.internal-document-search です。エンタープライズ向けとして需要が高いシナリオとして位置づけられています。

アーキテクチャの全体像は以下のとおりです。

  1. ユーザーは Web ブラウザからチャット UI にアクセスします
  2. バックエンドは Azure App Service でホストされています
  3. ユーザーの質問は Azure OpenAI Service に送られ、検索クエリが生成されます
  4. 生成された検索クエリで Azure Cognitive Search が Blob Storage 内のドキュメント群を検索します
  5. 検索で見つかったドキュメントの内容と元の質問を組み合わせて、再度 Azure OpenAI Service に問い合わせ、最終的な回答を返します

重要なのは、モデルがあらかじめ PDF の内容を学習しているわけではないという点です。都度、Cognitive Search で検索した内容をクエリに含めて問い合わせる仕組みになっています。

前提条件

このサンプルを展開するには、Azure OpenAI Service が有効化されたサブスクリプションが必要です。Azure OpenAI Service の利用には事前申請と承認が必要ですので、あらかじめ申請を済ませておいてください。

ローカル開発環境のセットアップ

まっさらな Windows 10 環境を想定して、必要なツールをすべてインストールします。

1. Azure Developer CLI（azd）のインストール

winget が利用できる場合はそのまま使えますが、入っていない場合は PowerShell（管理者）からスクリプトでインストールします。

# PowerShell（管理者）で実行
winget install microsoft.azd

winget が未インストールの場合は、公式ドキュメントにある PowerShell スクリプトを利用してください。Successfully installed と表示されれば完了です。

2. Azure CLI のインストール

azd と似ていますが、別ツールです。MSI インストーラーをダウンロードして実行します。

https://aka.ms/installazurecliwindows

ウィザードに従って Next → Install → Finish で完了します。

3. Python のインストール

バージョン 3.11 以降が推奨です。インストール時に重要な注意点があります。

⚠️ インストーラーの最初の画面で 「Add Python.exe to PATH」のチェックを必ず入れてください。これを忘れると後の手順で失敗します。

チェックを入れたら「Install Now」をクリックします。

4. Node.js のインストール

バージョン 14.18 以降が推奨です。LTS（長期サポート）の最新版をダウンロードして使用します。

Windows 用インストーラーをダウンロードし、Next → Accept → Next と進めます。「Tools for Native Modules」のチェックを入れておくと後々便利です。ただしこの場合、インストール後に追加のコマンドプロンプトが開いて関連ツールのインストールが走ります。

5. Git のインストール

Git for Windows をダウンロードしてインストールします。設定はほぼデフォルトのまま Next を押し続けて問題ありません。

https://git-scm.com/download/win

6. PowerShell 7 以降のインストール

PowerShell 7 は Windows 標準のものとは別に提供されています。GitHub の Releases ページから PowerShell-X.X.X-win-x64.msi をダウンロードしてインストールします。Next → Next → Install → Finish で完了です。

リポジトリのクローンと初期設定

リポジトリのクローン

インストールが完了したら PowerShell 7 を起動し、リポジトリをクローンします。

git clone https://github.com/azure-samples/jp-azureopenai-samples.git
cd jp-azureopenai-samples
cd 5.internal-document-search

azd のログイン

azd auth login

ブラウザが開きますので、Azure OpenAI Service が有効なサブスクリプションへのアクセス権を持つアカウントでサインインします。「Authentication complete」と表示されれば成功です。

azd の初期化

azd init

新しい環境名を聞かれます。デフォルトのまま Enter を押せば 5.internal-document-search が設定されます。

Azure へのデプロイ

Azure CLI でのログインとサブスクリプション設定

azd とは別に Azure CLI でもログインが必要です。

az login

複数のサブスクリプションがある場合は、使用するものを明示的に選択します。

az account set -s <サブスクリプションID>
# 確認
az account show

テナントの切り替えが必要な場合は、テナント ID を指定してログインします。

az login --tenant <テナントID>

azd のログインも同様にテナント指定が必要な場合があります。

azd auth login --tenant-id <テナントID>

Azure AD オブジェクト ID の取得と環境変数への設定

デプロイには操作ユーザーの Azure AD オブジェクト ID が必要です。

az ad user show --id <UPN> --query id --output tsv

Microsoft アカウントで招待されているなど、UPN での取得が難しい場合は Azure ポータルの「ユーザー」画面からオブジェクト ID を確認できます。

取得したオブジェクト ID を環境変数にセットします。

$env:AZURE_PRINCIPAL_ID = "<オブジェクトID>"

デプロイの実行

azd up

対象のサブスクリプションとリージョンを選択します。Azure OpenAI Service が利用可能なリージョンを選ぶ必要があります（例：japaneast、eastus など）。

デプロイの進捗は、コマンドの出力に表示される URL から Azure ポータル上で確認できます。

トラブルシューティング

エラー1：Azure OpenAI Service のキャパシティ不足

症状： azd up 実行後に Azure OpenAI Service の作成に失敗する。

原因： Azure OpenAI Service は削除しても即座には消えず、「論理削除」状態になります。論理削除状態のままではクォータが消費され、新しいリソースを作れません。

対処法：

  1. Azure ポータルで Azure OpenAI Service の画面を開きます
  2. 「削除されたリソースの管理」を開きます
  3. 残っているリソースをすべて選択し、「完全に削除」します
  4. 削除完了後、再度 azd up を実行します

エラー2：Form Recognizer（Document Intelligence）の重複

症状： 再デプロイ時に Form Recognizer が「すでに存在する」エラーで失敗する。

原因： 1回目の展開で作成されたリソースが論理削除状態で残っており、同じ名前では作成できません。

対処法：

  1. Azure ポータルの Form Recognizer（Document Intelligence）画面を開きます
  2. 「削除されたリソースの管理」からリソースを完全削除します
  3. 再度 azd up を実行します

エラー3：Azure OpenAI のモデルデプロイが重複する

症状： azd up を複数回実行すると、Azure OpenAI のモデルデプロイが重複して作成される。

対処法：

  1. Azure ポータルで Azure OpenAI Service を開きます
  2. 「モデルのデプロイ」→「展開の管理」から重複しているデプロイを削除します
  3. 元のリソース自体も削除してから azd up を再実行します

一般的な再試行のアプローチ

azd はべき等（idempotent）な動作をするため、失敗してもリソースを削除してやり直す必要は基本的にありません。問題を解消した後、azd up を再実行するだけで続きから展開を再開できます。

Cognitive Search はリソースの作成・削除に特に時間がかかるサービスです。タイムアウトや待機が発生しても焦らず待つようにしましょう。

デプロイ完了後の確認

デプロイが成功すると、PowerShell の出力に Web アプリケーションの URL が表示されます。その URL をブラウザで開くと、企業内向けチャット UI が表示されます。

バックエンドでは以下の処理が自動的に行われています。

  • Blob Storage へのサンプル PDF のアップロード
  • Form Recognizer を使ったテキスト抽出
  • Cognitive Search によるインデックス作成

これらがすべて完了した状態でチャット UI が利用可能になります。

まとめ

Azure OpenAI リファレンスアーキテクチャ「企業内向けチャットと社内文章検索」は、azd up 一コマンドで必要なリソースをまとめてデプロイできる非常に便利なサンプルです。

初回セットアップ時の主なポイントは以下のとおりです。

  • Python インストール時に「Add Python.exe to PATH」を必ずチェックする
  • azd と az（Azure CLI）は別ツールであり、それぞれログインが必要
  • テナントが複数ある場合は --tenant オプションで明示的に指定する
  • 論理削除されたリソースがキャパシティを占有してエラーになる場合は、完全削除してから再実行する

再デプロイ時のエラーの多くは「論理削除されたリソースが残っている」ことが原因です。Azure ポータルの「削除されたリソースの管理」を確認する習慣をつけておくと、トラブルシューティングがスムーズになります。