Azure × RAGシステムの概念検証（PoC）を1-2時間で完了させる、IaC（Infrastructure as Code）を活用した最速デプロイ手法を紹介します。

TL;DR(要約)

1-2時間でAzure × RAGシステムをデプロイ。手動構築（数日）に比べ、IaCテンプレート活用により時間を大幅に短縮できます。

この記事で得られる価値:

✅ Azure Portal操作不要（すべてCLI完結）
✅ 再現性の高いデプロイ（何度でも同じ環境を構築）
✅ 本番移行を想定したPoC基盤（Chat with your data = カスタマイズ前提設計）

すぐに実践したい方:
→ Section 3: デプロイガイドへジャンプ

IaCとは何か知りたい方:
→ Section 1: IaCによる課題解決を参照

なぜ他のリポジトリではなくChat with your dataを選んだか知りたい方:
→ Section 2: リポジトリ選定理由を参照

1. Azure × RAG概念検証の課題と解決アプローチ

1-1. Azure Portal手動構築での課題

Azure上でRAGシステムを構築する際、Azure Portalから手動でリソースを作成・設定する従来のアプローチでは、以下のような課題に直面します。

手動リソース作成の繰り返し

RAGシステムに必要なリソースを一つ一つ作成する必要があります：

Azure OpenAI Serviceの作成とモデルデプロイ
Azure AI Searchの作成とインデックス設定
App Serviceの作成とランタイム設定
PostgreSQLまたはCosmos DBの作成

さらに、開発環境・検証環境・本番環境でそれぞれ手動構築作業を繰り返す必要があり、大きな時間コストとなります。要件変更や設定調整が発生するたびに、複数の環境で同じUI操作を繰り返し、その都度設定値を確認・入力する必要があります。

設定値の手入力によるミス

各サービス間の接続には、エンドポイントURL、APIキー、接続文字列などを手動でコピー&ペーストする必要があります。この過程で以下のリスクが発生します：

設定漏れ
タイポによるエラー
セキュリティ情報の誤った管理

環境差異（Configuration Drift）の発生

Microsoft公式ドキュメントでは、手動構築における本質的な問題を次のように指摘しています：

"Without IaC, teams must maintain deployment environment settings individually. Over time, each environment becomes a snowflake, a unique configuration that can't be reproduced automatically."

— What is infrastructure as code (IaC)?

各環境で微妙に設定が異なる結果、「開発環境では動作したが本番環境では動作しない」という問題が発生します。これはPoCから本番移行を困難にする主要因の一つです。

ドキュメント化の困難と陳腐化

手動構築の手順をドキュメント化しても、以下の問題があります：

手順書が長大になり、メンテナンスが困難
Azure PortalのUI変更により、手順書がすぐに陳腐化
チームメンバー間での手順の共有と同期が難しい

時間コストとPoC貧乏のリスク

手動構築では：

初回構築: 数日〜1週間
環境追加: 同じ時間が必要
再構築: トラブル時にさらに時間

この結果、PoCで実証できても本番環境への移行時に再構築が必要となり、いわゆる「PoC貧乏」（PoCを繰り返すが開発フェーズに進めず、コストと時間だけが増大する状態）に陥るリスクがあります。

参考: PoC貧乏のメカニズムと対処法
参考: デジタル活用を阻む「PoC貧乏」、脱出の鍵はアジャイル

1-2. IaCテンプレート活用による解決

これらの課題に対し、動作保証済みのIaCテンプレートリポジトリを活用することで、劇的な改善が可能です。

動作保証済み構成の活用

Microsoft公式リポジトリやコミュニティで検証済みのIaCテンプレートを利用することで：

ベストプラクティスが組み込み済み: セキュリティ設定、リソース構成、接続設定などが最適化
コミュニティで検証済み: 実際に動作する構成が保証されている
継続的な更新: Azureサービスのアップデートに追従

ワンコマンドデプロイ

IaCテンプレートを使用することで、複雑なRAGシステム全体を1つのコマンドでデプロイ可能：

azd up

azd up実行時間: 30-45分
作業内容: パラメータ設定とコマンド実行のみ
エラー対応: テンプレートが依存関係を自動解決

再現性の確保

Microsoft公式ドキュメントでは、IaCの本質的な価値を次のように説明しています：

"An IaC model generates the same environment every time it deploys."

— What is infrastructure as code (IaC)?

これにより：

環境差異の排除: 開発・検証・本番で完全に同一の構成
何度でも再現可能: 削除と再作成が容易
PoCから本番へのスムーズな移行: 同じコードで本番環境を構築

コードベースでの設定管理

インフラ構成がコードとして管理されることで：

パラメータファイルでの調整: 構成をテキストファイルで宣言的に管理
- 手動構築との違い: Azure PortalではUI画面を開いて現在の設定を確認する必要があるが、パラメータファイルでは設定値がすべて可視化されている
- 設定値の変更が容易（ファイル編集のみ）
- 同じパラメータセットを複数環境に適用可能
Gitによるバージョン管理: インフラ構成全体がコードとして記録される
- 手動構築との違い: Azure Portalでの操作は記録に残らないが、IaCではすべての構成がコードとして保存される
- インフラの「あるべき姿」が明確（どのリソースが、どう接続され、どう設定されているか）
- 誰が、いつ、なぜ変更したかが履歴として残る（コミットメッセージで変更理由も記録可能）
- 問題発生時に過去の動作していた構成に戻すことが可能
- チームメンバー間で構成を共有・レビュー可能（Pull Request によるレビュープロセス）
チーム共有の容易さ: リポジトリをクローンするだけで同じ環境を構築可能

本記事のアプローチ：Azure Portal不要のCLI実装

上記のIaCの利点を最大限に活用するため、本記事ではすべてコマンドラインで完結する手順を採用します。

IaCテンプレート（Bicep）を使用しつつ、デプロイ操作はすべてazdとazコマンドで実行することで、以下を実現します：

アカウント・サブスクリプション準備後、すべてCLIで完結：

Azure Portal操作不要: リソースグループ作成から確認まで、すべてコマンドで実行
完全な再現性: 手順をシェルスクリプト化すれば、何度でも同じ環境を構築可能
ドキュメント化の容易さ: コマンド履歴がそのまま手順書になる
チーム共有の簡素化: コマンド一覧を共有するだけで、誰でも同じ環境を構築可能

IaCとCLI-firstの相乗効果：

IaC（Bicep）: リソースの構成定義をコードで管理
CLI: デプロイ操作をコマンドで記録・自動化
結果: インフラの定義から構築まで、すべてコードで管理・再現可能

UI操作と異なり、コマンドラインベースでは：

画面キャプチャが不要（コマンドをテキストで記録）
Azure PortalのUI変更による手順書の陳腐化がない
CI/CDパイプラインへの組み込みが容易

次のセクションでは、複数の動作保証済みリポジトリの中から、概念検証に最適なものを選定します。

2. 動作保証済みリポジトリの選定

2-1. 検討したRAGリポジトリ候補

Azure上でRAGシステムを構築する際、Microsoft公式やコミュニティから複数の選択肢が提供されています。2025年10月時点での主要な候補は以下の3つです：

1. azure-search-openai-demo

GitHub: https://github.com/Azure-Samples/azure-search-openai-demo
スター数: 7.3k
フォーク数: 5k
特徴: 最も人気のあるRAGデモアプリケーション
用途: RAGパターンの学習・デモ、異なる実装アプローチの理解
強み:
- 圧倒的な知名度と豊富な解説記事
- UI/UXが洗練されており、デモ・プレゼンテーションに最適
- 多様な検索モードとプロンプトの実験が容易
注意点: 本番移行を前提としたPoCには推奨されない（公式見解）

2. Chat with your data Solution Accelerator (CWYD)

GitHub: https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator
スター数: 1.1k
フォーク数: 594
特徴: エンドツーエンドのベースラインRAG実装
用途: Azure OpenAI標準機能で満たせない要件のカスタマイズ、PoC/実証実験の基盤
強み:
- カスタマイズ前提の設計（フォーク数がGPT-RAGの約2倍）
- async API使用により5人以上の同時利用環境でスケール可能
- PostgreSQL/Cosmos DB選択、複数オーケストレーション対応（Semantic Kernel/LangChain/OpenAI Functions/Prompt Flow）
- 管理サイト・バッチ処理など実用機能が充実
- azure-search-openai-demoと異なりPoC→本番移行を想定した設計
公式推奨: 「Azure提供のRAG実装では要件を満たせない場合に使用」（README比較表より）

3. GPT-RAG

GitHub: https://github.com/Azure/GPT-RAG
スター数: 1.1k
フォーク数: 271
特徴: エンタープライズグレードのRAGリファレンスアーキテクチャ
用途: プロトタイプからMVP・本番環境への移行、Zero-Trust要件がある場合
強み:
- Zero-Trust Architecture（Azure VNet、WAF、Bastionによるセキュア設計）
- Data Ingestionコンポーネントによるチャンク化・インデックス最適化
- 4つの主要コンポーネント（Orchestrator/Web UI/Data Ingestion/MCP）の分離設計
- 自動スケーリング、Azure Application Insightsによる監視・分析
- Responsible AI機能と監査機能を標準装備
- 技術記事・解説が豊富（Medium等で詳細なアーキテクチャ解説あり）

各リポジトリは異なる強みを持ち、用途によって最適な選択が変わります。次のセクションでは、概念検証という観点からの評価基準を整理します。

2-2. 評価基準と比較マトリックス

概念検証（PoC）において、リポジトリを選定する際の重要な評価軸を5つ定義します。

評価軸の定義

1. カスタマイズ性

業務要件に合わせた柔軟な変更が可能か
オーケストレーション、データベース、処理ロジックの選択肢の豊富さ

2. デプロイ速度・再現性

環境構築の所要時間
IaCによる再現可能性（何度でも同じ環境を構築できるか）

3. 本番移行のしやすさ

PoC成功後に本番環境へスムーズに移行できるか
同時利用者数への対応（スケーラビリティ）
async APIによるパフォーマンス最適化

4. セキュリティ・エンタープライズ機能

Managed Identity、Zero-Trust対応
監査、Responsible AI機能の有無

5. コスト効率

PoC段階での初期投資額
本番移行時のコスト見通しの立てやすさ

比較マトリックス

評価軸	azure-search-openai-demo	CWYD	GPT-RAG
カスタマイズ性	△ デモ用途のため限定的	◎ 複数DB・オーケストレーション選択可	○ エンタープライズ向けカスタマイズ
デプロイ速度・再現性	○ azd対応、比較的簡単	◎ azd + 詳細ドキュメント	○ azd対応、構成が複雑
本番移行のしやすさ	× 公式に非推奨	◎ async API、本番想定設計	◎ MVP・本番環境特化
セキュリティ	△ デモレベル	○ Managed Identity対応	◎ Zero-Trust、監査機能
コスト効率	○ 学習用途で最小構成	◎ PoC→本番で段階的投資	△ エンタープライズ機能で高め

記号の意味:

◎: 非常に優れている（公式ドキュメント・調査で明確に確認）
○: 優れている（機能として存在）
△: 制限あり（公式の注意点あり）
×: 不適（公式に非推奨）

評価の根拠

azure-search-openai-demo:

学習・デモ用途に特化しており、プロンプトや検索モードの実験に最適（公式README）
本番移行を前提としたPoCには推奨されない（GitHub Issue #849の公式コメント）
UI/UXが洗練されており、プレゼンテーション・デモンストレーションに優れる
5人以下の同時利用を想定した設計

CWYD:

複数のオーケストレーション選択可（Semantic Kernel/LangChain/OpenAI Functions/Prompt Flow）
PostgreSQL/Cosmos DBから選択でき、ベクトル検索とスケーラビリティを調整可能
PoC→本番移行を想定した設計で、カスタマイズ前提のベースライン実装（README比較表）
Azure OpenAI標準機能で満たせない要件がある場合の公式推奨ソリューション

GPT-RAG:

Zero-Trust Architecture標準装備（Azure VNet、WAF、Bastion）
プロトタイプからMVP・本番環境への移行に特化した設計
Responsible AI機能と監査機能を標準装備
4つの主要コンポーネント分離によりエンタープライズ運用に最適化
エンタープライズ機能充実により初期投資は高めだが、本番運用の安定性が高い

2-3. Chat with your dataを選定した決定的理由

2-2の評価マトリックスを踏まえ、今回の概念検証ではCWYDを選定しました。3つのリポジトリの特性を比較して説明します。

3つのリポジトリの特性比較

azure-search-openai-demo: 学習コストは低いが本番PoCには制約

特徴:

RAGパターンの学習・理解に最適化
デフォルトで認証なし（公式: "no authentication or access restrictions enabled"）
セキュリティ機能はオプションとして存在（Azure AD認証、ACL、Private Endpoint）

本番PoCへの制約:

公式READMEの警告:

"We strongly advise our customers not to make this code part of their production environments without implementing or enabling additional security features."

オプション機能の手動設定が必要
デモ・プレゼンテーション用途に特化し、本番移行を前提としたPoCには推奨されない（コミュニティ認識）

判断: セキュリティ機能自体は存在するが、デフォルトで無効。本番を想定したPoCでは追加設定の手間がかかる。GitHub Issue #849での議論で、FlaskからQuartへの移行でスケーラビリティが改善されたものの、デモ用途に特化した設計

GPT-RAG: エンタープライズ機能充実だが学習コストと維持費が高い

特徴:

Zero-Trust Architecture、Responsible AI、監査機能を標準装備
4つの独立リポジトリで構成:
1. GPT-RAG（インフラプロビジョニング）
2. gpt-rag-ingestion（データ取り込み）
3. gpt-rag-orchestrator（オーケストレーション）
4. gpt-rag-ui（ユーザーインターフェース）

学習コストと維持費:

各リポジトリを個別に理解・管理が必要
公式: "If you prefer to deploy a single service, navigate to the corresponding service repository"
複数リポジトリの環境設定とデプロイの整合性維持が必要
Zero-Trust構成による初期コスト増

判断: 本番環境には最適だが、概念検証段階では4リポジトリ管理と高度なセキュリティ機能は過剰

CWYD: GPT-RAGほどエンタープライズ向けではないが、それ以外は全てにおいて優秀

特徴:

単一リポジトリで管理が容易
最小限のコンポーネント（"minimum components needed"）
デフォルトで認証機能をサポート（AZURE_AUTH_TYPE設定）
Managed Identity対応
PostgreSQL/Cosmos DB選択可能
複数オーケストレーション選択（Semantic Kernel/LangChain/OpenAI Functions/Prompt Flow）

エンタープライズ機能の位置づけ:

❌ GPT-RAGのようなZero-Trust Architecture標準装備ではない
⭕ 基本的なセキュリティ機能（認証、Managed Identity）は装備
⭕ 必要に応じて段階的にセキュリティを強化可能

他と比較した優位性:

項目	azure-search-openai-demo	CWYD	GPT-RAG
学習コスト	低（デモ特化）	中（単一リポジトリ）	高（4リポジトリ）
デフォルト認証	なし（手動設定必要）	あり	あり
本番PoC適性	低（公式警告あり）	高	高（過剰）
スケーラビリティ	低（5人想定）	中	高（エンタープライズ）
エンタープライズ機能	オプション	基本装備	完全装備
維持費	低	中	高
管理の複雑さ	低	低（単一リポジトリ）	高（4リポジトリ）

選定の決定的理由

概念検証に必要な要素:

素早い検証開始（学習コストが低い）
本番を想定した設計（セキュリティ、スケーラビリティ）
段階的な機能拡張の可能性

CWYDがこれらを満たす理由:

単一リポジトリで学習コストを抑制（GPT-RAGの4リポジトリ管理を回避）
デフォルトで認証機能装備（azure-search-openai-demoの手動設定を回避）
PostgreSQL/Cosmos DB選択により要件に応じたスケーラビリティ調整が可能
最小限から始めて必要に応じてGPT-RAGレベルのセキュリティへ拡張可能

バランスの良さ:

azure-search-openai-demo: 学習コスト◎ / 本番PoC適性×
GPT-RAG: エンタープライズ機能◎ / 学習コスト× / 維持費×
CWYD: すべて○ のバランス型

次のセクションでは、選定したCWYDを使った実践的なデプロイ手順を説明します。

3. 実践：Chat with your dataデプロイガイド

事前確認：前提条件（初回のみ）

デプロイ前に、以下の前提条件を満たしていることを確認してください。

1. Azureサブスクリプション（owner権限）

Azure上にリソースをデプロイするため、owner権限を持つAzureサブスクリプションが必要です。

!

重要：無料試用版ではデプロイに失敗します
無料試用版（Free Trial）サブスクリプションでは、Azure OpenAIのクォータ制限により、一部リソースが作成できずデプロイに失敗します。
必須の対応：

無料アカウント作成後、従量課金（Pay-As-You-Go）へのアップグレードが必要です。
アップグレード手順：

Azure Portal → Subscriptions
無料試用版サブスクリプションを選択
「Upgrade your subscription」をクリック
Pay-As-You-Go への変更を完了
数時間後に azd up を実行
注意：
アップグレードは無料で実施可能
アップグレード後も$200の無料クレジットは継続利用可能
従量課金に移行しても、クレジット内であれば課金されません

お持ちでない場合：

まず無料アカウントを作成: Azure無料アカウント作成
作成後、上記の手順で従量課金へアップグレード

2. Azure OpenAI サービスの利用承認

3. クォータの確認（推奨）

デプロイ失敗のリスクを減らすため、Azure OpenAIのクォータ（利用枠）を事前に確認することを推奨します。

詳細手順: QuotaCheck.md
所要時間: 5-10分
クォータ確認スクリプト（quota_check_params.sh）を使用

クォータ不足でデプロイに失敗した場合の対処法は、Section 4のFAQで説明します。

3-1. ローカル環境のセットアップ

デプロイに必要なローカル環境のセットアップは、以下の4ステップで完了します。

1. Azure Developer CLI (azd) のインストール

Azure Developer CLI (azd) は、Azureアプリケーションのデプロイに特化した開発者向けCLIツールです。

公式インストールガイド: Install azd

各OS向けの詳細なインストール手順は上記公式ドキュメントを参照してください。主なインストール方法：

Windows: winget install microsoft.azd
macOS: brew tap azure/azd && brew install azd
Linux: curl -fsSL https://aka.ms/install-azd.sh | bash

2. Azure CLI (az) のインストール

Azure CLI (az) は、Azureリソースの管理・操作に使用する汎用CLIツールです。Azure Developer CLI (azd) とは別のツールで、両方のインストールが必須です。

基本デプロイ手順でazを使用:

azd: メインのデプロイ処理（azd up）に使用
az: リソースグループの作成（az group create）に使用

本記事ではリソースグループを事前に作成する手順（3-2の手順2）でaz group createを使用するため、Azure CLIは必須です。

トラブルシューティングでもazを使用:

デプロイ失敗時のエラー詳細確認
ソフトデリートされたリソースのパージ（Key Vault、Cognitive Servicesなど）
デプロイ状態の確認

公式インストールガイド: Install the Azure CLI

各OS向けの詳細なインストール手順は上記公式ドキュメントを参照してください。主なインストール方法：

Windows: winget install -e --id Microsoft.AzureCLI
macOS: brew update && brew install azure-cli
Linux: curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

3. Azureへの認証

ターミナルで以下のコマンドを実行し、Azureにサインインします：

azd auth login

Webブラウザが起動し、Azureアカウントでの認証画面が表示されます。認証完了後、ターミナルに戻ります。

4. リポジトリの取得

ソリューションを取得する方法は、用途に応じて2つの選択肢があります。

オプションA（推奨）: GitHubでフォーク → clone する方法

コードのバージョン管理と公式リポジトリとの同期を行う方法です。本記事ではこの方法を推奨します。

推奨する理由：

公式リポジトリとの同期が容易: デプロイ前に最新版に更新できる（PR #1894のような重要な修正を反映）
バージョン管理: 自分の変更履歴をGitで管理できる
再現性: チーム内で同じリポジトリを共有し、同じ環境を構築できる
カスタマイズ対応: 将来的にカスタマイズする場合もスムーズに移行可能

公式リポジトリをフォーク

GitHubで Azure-Samples/chat-with-your-data-solution-accelerator にアクセスし、右上の「Fork」ボタンをクリックして自分のアカウントにフォークします。

フォークしたリポジトリをクローン

git clone https://github.com/<your-account>/chat-with-your-data-solution-accelerator.git
cd chat-with-your-data-solution-accelerator

upstreamリモートを追加

公式リポジトリの更新を取り込めるようにします：

git remote add upstream https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator.git

フォーク後の同期（重要）:

公式リポジトリは頻繁に更新されます。フォークしたリポジトリを最新状態に保つため、定期的に同期してください：

# 公式リポジトリの最新変更を取得
git fetch upstream main

# 自分のブランチにマージ
git merge upstream/main

オプションB（簡易版）: azd init を使う方法

Azure公式リポジトリ（Azure-Samples/chat-with-your-data-solution-accelerator）からテンプレートをローカルにコピーする方法です：

azd init -t chat-with-your-data-solution-accelerator

詳細な手順はAzure Developer CLI公式ドキュメントを参照してください。

この方法を選択した場合も、3-2 パラメータ設定とデプロイ実行に進んでください。

!

推奨：AIエージェントでデプロイを効率化
Claude CodeなどのターミナルAIエージェント（Claude Code、Cursor、GitHub Copilot等）を活用することで、以降のデプロイ作業を大幅に効率化できます。
活用方法：
この記事全体をAIエージェントに読み込ませる
「Section 3-2の手順を実行してください」と指示

環境変数設定、コマンド実行、エラー解析・対応を自動化
メリット：

環境変数の自動設定: azd env setコマンドを記事に基づいて自動実行

エラーの自動解析・対応: ログを読み取り、FAQ参照や修正コマンド実行

デプロイ監視の自動化: 30-45分のデプロイ状況を逐次確認

並行作業: デプロイ中も他の作業に集中でき、時間を有効活用
筆者の実例：
筆者もClaude Codeを活用してデプロイを実施しました。環境変数設定からデプロイ実行まで、記事を読み込ませて指示するだけで自動化。azd up実行後もAIエージェントがデプロイ状況を逐次確認してくれるため、その間に他の作業を進めることができ、作業時間を大幅に削減できました。
特に、エラー発生時にログを解析してFAQから対処法を見つけ出し、修正コマンドを実行してくれる点が非常に便利でした。

3-2. パラメータ設定とデプロイ実行

このセクションでは、実際に成功したデプロイ手順を記載します。すべてコマンドラインで完結するため、Azure Portalでリソースを作成・設定する必要がありません。非対話モード（azd env setによる環境変数設定）を使用することで、高い再現性を実現します。

本手順の特徴:

CLI-only: リソースグループ作成から確認まで、すべてazd/azコマンドで実行
Azure Portal不要: リソース作成・設定・確認すべてコマンドで完結
スクリプト化可能: 手順をそのままシェルスクリプトにできる
再現性: 同じコマンドで何度でも同じ環境を構築可能

前提条件

Azure CLIとAzure Developer CLIがインストール済み
Azureサブスクリプションへのログイン済み
リポジトリをクローンまたはフォーク済み（公式との同期完了）

手順1: azd環境の初期化

azd環境を作成します。この環境名はリソース名の生成に使用されます。

!

環境名の文字数制限
azd で使用する環境名（AZURE_ENV_NAME）は最大16文字です。これはBicepテンプレートの solutionName パラメータ制約によるものです。
推奨環境名の例:
✅ ragpoc（6文字）
✅ cwyd-test-01（11文字）
❌ my-project-default（18文字・長すぎる）
環境名が17文字以上の場合、デプロイ時に以下のエラーが発生します：
InvalidTemplate: The provided value for the template parameter 'solutionName' is not valid. Length of the value should be less than or equal to '16'.

以下のコマンドで環境を初期化します：

# 環境名は16文字以内で指定（例: ragpoc = 6文字）
azd env new ragpoc

環境名の決定基準:

プロジェクト名やPoC名をベースに命名
わかりやすく、チームで共有しやすい名前を推奨

手順2: リソースグループの作成

Azureリソースを格納するリソースグループを作成します。

リソースグループ名の命名規則:

rg- はリソースグループを示す一般的な接頭辞（Azureの命名規則ベストプラクティス）
環境名と合わせて命名すると管理しやすい（例: 環境名 ragpoc → リソースグループ名 rg-ragpoc）

# リソースグループを事前に作成
az group create --name rg-ragpoc --location eastus2

ロケーション選択のポイント:

Azure OpenAI Service が利用可能なリージョンを選択
推奨（初めての場合）: eastus2 を使用
- 本記事で動作確認済みのリージョン
- Azure OpenAI Serviceの容量が比較的安定
その他の選択肢: westeurope, japaneast（容量状況により使用を検討）

手順3: 環境変数の設定

サブスクリプションIDの設定

現在使用中のサブスクリプションIDを確認します：

# 現在のサブスクリプションIDを取得
az account show --query id -o tsv

複数のサブスクリプションがある場合は、一覧を確認してから使用するサブスクリプションを選択します：

# すべてのサブスクリプションを表示
az account list -o table

複数サブスクリプションがある場合（重要）:

デフォルトのサブスクリプションが意図したものではない場合、以下のコマンドで明示的に選択してください：

# 使用するサブスクリプションを設定（subscription-idを実際のIDに置き換える）
az account set --subscription <your-subscription-id>

# 設定を確認
az account show --query "{Name:name, ID:id, State:state}" -o table

取得したIDをメモしておき、次のいずれかの方法でサブスクリプションIDを環境変数に設定します。

方法A: 手動で設定する場合（推奨）

取得したサブスクリプションIDを直接指定します：

# サブスクリプションID（上記で取得したIDを直接記載）
azd env set AZURE_SUBSCRIPTION_ID "12345678-1234-5678-90ab-cdef12345678" -e ragpoc

方法B: 自動取得する場合

現在選択中のサブスクリプションを自動取得して設定します：

# サブスクリプションID（現在選択中のサブスクリプションを自動取得）
# まずサブスクリプションIDを変数に格納
SUBSCRIPTION_ID=$(az account show --query id -o tsv)

# 取得したIDを環境変数に設定
azd env set AZURE_SUBSCRIPTION_ID "$SUBSCRIPTION_ID" -e ragpoc

その他の必須パラメータ設定

サブスクリプションID以外の必須パラメータを設定します：

# 必須パラメータ
azd env set AZURE_RESOURCE_GROUP "rg-ragpoc" -e ragpoc
azd env set AZURE_LOCATION "eastus2" -e ragpoc
azd env set AZURE_APP_SERVICE_HOSTING_MODEL "code" -e ragpoc

# OpenAIクォータ調整（サブスクリプション上限が150未満の場合）
azd env set AZURE_OPENAI_MODEL_CAPACITY "50" -e ragpoc
azd env set AZURE_OPENAI_EMBEDDING_MODEL_CAPACITY "50" -e ragpoc

手順4: 設定確認

# 環境変数が正しく設定されているか確認
azd env get-values -e ragpoc | grep -E "(AZURE_SUBSCRIPTION_ID|AZURE_RESOURCE_GROUP|AZURE_LOCATION|AZURE_APP_SERVICE_HOSTING_MODEL|AZURE_OPENAI)"

期待される出力:

AZURE_APP_SERVICE_HOSTING_MODEL="code"
AZURE_LOCATION="eastus2"
AZURE_OPENAI_EMBEDDING_MODEL_CAPACITY=50
AZURE_OPENAI_MODEL_CAPACITY=50
AZURE_RESOURCE_GROUP="rg-ragpoc"
AZURE_SUBSCRIPTION_ID="12345678-1234-5678-90ab-cdef12345678"

手順5: デプロイ実行

# 非対話モードでデプロイ実行
azd up -e ragpoc

デプロイ時間の目安:

パッケージング: 2-3分（frontend, backend, function）
プロビジョニング: 15-25分
- PostgreSQL Flexible Server作成: 約10-15分（最長）
- その他リソース（App Service, Function, OpenAI等）: 約5-10分
- PostgreSQLテーブル作成スクリプト実行: 約1分
デプロイメント: 10-15分（App Serviceへのデプロイ）
合計: 30-45分

手順6: デプロイ結果の確認

デプロイ完了後、以下を確認します：

# デプロイ状態の確認
az deployment group list --resource-group rg-ragpoc \
  --query "[?contains(name, 'ragpoc')].{Name:name, State:properties.provisioningState}" \
  -o table

期待される出力:

Name                              State
--------------------------------  ---------
ragpoc-1234567890                Succeeded
avm.res.resources.deployment...  Succeeded

主要リソースの確認:

Azure OpenAI: oai-ragpocxxxxx
PostgreSQL: psql-ragpocxxxxx-postgres
App Service (Web): app-ragpocxxxxx
App Service (Admin): app-ragpocxxxxx-admin
Function App: func-ragpocxxxxx

手順7: 認証設定（必須）

デプロイ完了後、Web App（app-ragpocxxxxx）とAdmin Web App（app-ragpocxxxxx-admin）に認証を設定します。

公式ドキュメント参照:

Set Up Authentication in Azure App Service（公式リポジトリ）

7-1. Azure Portalで認証設定

Azure Portalにアクセス: https://portal.azure.com
App Serviceを選択: app-ragpocxxxxx
左メニューから**「認証」**をクリック
**「+ IDプロバイダーの追加」**をクリック
IDプロバイダーのドロップダウンから**「Microsoft」**（Microsoft Entra ID）を選択
クライアントシークレットの有効期限を選択（必須）
その他の設定項目は公式ドキュメントを参照して適宜設定してください
- 詳細: Azure App Service認証設定
**「追加」**ボタンをクリック

7-2. Admin Web Appにも同様の設定

上記手順をapp-ragpocxxxxx-adminに対しても実施します。

7-3. 認証設定の確認

リソース名がわかっている場合:

# Web Appの認証設定確認
az webapp auth show --name app-ragpocxxxxx --resource-group rg-ragpoc \
  --query "{Enabled: enabled, Provider: unauthenticatedClientAction}" -o table

# 期待される出力:
# Enabled    Provider
# ---------  ------------------------
# True       RedirectToLoginPage

Web App名を動的に取得する場合:

# Web App名を取得
WEBAPP_NAME=$(az webapp list --resource-group rg-ragpoc \
  --query "[?contains(name, 'app-')].name" -o tsv | grep -v "\-admin" | head -1)

# 認証設定を確認
az webapp auth show --name "$WEBAPP_NAME" --resource-group rg-ragpoc \
  --query "{Enabled: enabled, Provider: unauthenticatedClientAction}" -o table

# 期待される出力:
# Enabled    Provider
# ---------  ------------------------
# True       RedirectToLoginPage

認証設定後の動作:

アプリケーションにアクセスすると、Microsoftアカウントでのサインインが要求されます
サインイン後、チャットアプリケーションが正常に表示されます

トラブルシューティング

デプロイ中にエラーが発生した場合:

OpenAIクォータ不足: FAQ Q1
コードデプロイ未実行: FAQ Q2
認証未設定エラー: FAQ Q3
環境名の文字数制限: 3-1セクションの環境名制約を参照
PostgreSQLテーブル作成失敗: 公式リポジトリとの同期を確認（PR #1894対応）
Azure 500エラー（一時的な障害）: 稀にAzure基盤の一時的な問題により500エラーでデプロイが失敗することがあります。これはAzure側の問題のため、以下を試してください：
- 数分待ってから azd up -e ragpoc を再実行（環境名は自分の環境名に読み替える）
- それでも解決しない場合は時間を置いて再試行
- 繰り返し発生する場合はAzureサポートに問い合わせ

デプロイログの確認:

エラーの詳細を確認したい場合、以下の方法でデプロイログを確認できます。

Azure Portalで確認:

Azure Portal にアクセス
左メニューから「リソースグループ」をクリック
該当のリソースグループ（例: rg-ragpoc）を選択
「デプロイ」タブをクリック
失敗したデプロイをクリックして詳細を確認

Azure CLIで確認:

# デプロイ名を取得
DEPLOY_NAME=$(az deployment group list --resource-group rg-ragpoc \
  --query "[?contains(name, 'ragpoc')].name | [0]" -o tsv)

# エラー詳細を表示
az deployment group show --resource-group rg-ragpoc \
  --name "$DEPLOY_NAME" \
  --query "properties.error" -o json

3-3. デプロイ完了の確認

`azd up` 完了の確認

デプロイが正常に完了すると、azd upの出力に以下のメッセージが表示されます：

SUCCESS: Your application was provisioned and deployed to Azure

また、エンドポイントURLが表示されます：

- Web App: https://app-ragpocxxxxx.azurewebsites.net/
- Admin Web App: https://app-ragpocxxxxx-admin.azurewebsites.net/

エンドポイントURLの確認方法

azd up のログでURLを見逃した場合や、別のターミナルセッションから確認したい場合は、以下の方法でURLを確認できます。

Azure Portalで確認:

Azure Portalにアクセス: https://portal.azure.com
左メニューから**「リソースグループ」**をクリック
デプロイしたリソースグループ（例: rg-ragpoc）を選択
リソース一覧からApp Serviceを探す:
- Web App: app-ragpocxxxxx
- Admin Web App: app-ragpocxxxxx-admin
それぞれのApp Serviceをクリックし、「概要」タブでURLを確認

CLIで確認:

リソース名がわかっている場合:

# Web AppのURLを取得
az webapp show --name app-ragpocxxxxx --resource-group rg-ragpoc \
  --query "defaultHostName" -o tsv

# Admin Web AppのURLを取得
az webapp show --name app-ragpocxxxxx-admin --resource-group rg-ragpoc \
  --query "defaultHostName" -o tsv

Web App名を動的に取得する場合:

# Web App名を取得
WEBAPP_NAME=$(az webapp list --resource-group rg-ragpoc \
  --query "[?contains(name, 'app-')].name" -o tsv | grep -v "\-admin" | head -1)

# Web AppのURLを表示
echo "https://$WEBAPP_NAME.azurewebsites.net/"

# Admin Web App名を取得
ADMIN_WEBAPP_NAME=$(az webapp list --resource-group rg-ragpoc \
  --query "[?contains(name, 'app-')&&contains(name, '-admin')].name | [0]" -o tsv)

# Admin Web AppのURLを表示
echo "https://$ADMIN_WEBAPP_NAME.azurewebsites.net/"

出力例:

app-ragpocxxxxx.azurewebsites.net
app-ragpocxxxxx-admin.azurewebsites.net

ブラウザでアクセスする際は、先頭に https:// を付けてください。

ブラウザでの動作確認

Web Appへのアクセス:

ブラウザで https://app-ragpocxxxxx.azurewebsites.net/ にアクセス
Microsoftアカウントでのサインインが要求されます（認証設定済みの場合）
「要求されているアクセス許可」画面で**「承諾」**をクリック
チャット画面が表示されることを確認

Admin Web Appへのアクセス:

ブラウザで https://app-ragpocxxxxx-admin.azurewebsites.net/ にアクセス
同様にサインイン
管理画面（Admin Site）が表示されることを確認

デプロイ完了

これで、Azure × RAGシステムの概念検証環境の構築が完了しました。IaCテンプレートを使用することで、手動構築では数日かかる作業を1-2時間で完了できました。

次のステップ

データのアップロードや詳細な利用方法については、公式ドキュメントを参照してください：

データアップロード: Admin Siteの使い方
詳細な取り込み設定: Integrated Vectorization ガイド

4. FAQ

Q1. 「InsufficientQuota」エラー: Azure OpenAIのクォータ不足

エラーメッセージ

InsufficientQuota: This operation require 150 new capacity in quota Tokens Per Minute (thousands) - 4.1 - GlobalStandard, which is bigger than the current available capacity 50.

原因

Azure OpenAI モデルのデプロイに必要なクォータ（Tokens Per Minute: TPM）が、サブスクリプションの利用可能枠を超えています。

デフォルト設定: 150 TPM
サブスクリプション上限: 50 TPM（例）

解決方法

環境変数でOpenAIモデルのキャパシティを調整します：

# 環境変数を設定（例: 50 TPMに調整）
azd env set AZURE_OPENAI_MODEL_CAPACITY "50" -e ragpoc
azd env set AZURE_OPENAI_EMBEDDING_MODEL_CAPACITY "50" -e ragpoc

# 再デプロイ
azd up -e ragpoc

パラメータの決め方:

エラーメッセージの「current available capacity」の値を確認
その値以下に設定（例: 利用可能50の場合、50または40に設定）

注意:

キャパシティを下げると、同時リクエスト処理能力が低下します
PoC段階では問題ありませんが、本番移行時はクォータ引き上げ申請を検討してください
クォータ引き上げ申請: Azure Portal → Azure OpenAI Service → Quotas

Q2. 「Webアプリは実行中で、お客様のコンテンツを待機しています」エラー

症状

デプロイ完了後、WebアプリのURLにアクセスすると、以下のデフォルトページが表示される：

Webアプリは実行中で、お客様のコンテンツを待機しています

原因

AZURE_APP_SERVICE_HOSTING_MODEL環境変数が設定されていないため、azdがコードデプロイフェーズをスキップしています。

infra/main.bicepのデフォルト値: container（Dockerコンテナ想定）
必要な値: code（Pythonコードベースデプロイ）

解決方法

# 環境変数を設定
azd env set AZURE_APP_SERVICE_HOSTING_MODEL "code" -e ragpoc

# 再デプロイ（デプロイフェーズのみ実行される）
azd up -e ragpoc

確認方法:

デプロイ後、ブラウザでWebアプリにアクセスし、「Chat with your data」というタイトルのReactアプリケーションが表示されることを確認します。

リソース名がわかっている場合:

# Webアプリの状態確認
curl -s https://app-ragpocxxxxx.azurewebsites.net/ | grep -i "chat with your data"

Web App名を動的に取得する場合:

# Web App名を取得
WEBAPP_NAME=$(az webapp list --resource-group rg-ragpoc \
  --query "[?contains(name, 'app-')].name" -o tsv | grep -v "\-admin" | head -1)

# Webアプリの状態確認
curl -s "https://$WEBAPP_NAME.azurewebsites.net/" | grep -i "chat with your data"

参考: docs/LOCAL_DEPLOYMENT.md（公式リポジトリ）

Q3. 「Authentication Not Configured」エラー

症状

デプロイ完了後、Webアプリにアクセスすると以下のメッセージが表示される：

Authentication Not Configured

This app does not have authentication configured. Please add an identity provider...

原因

Azure App Serviceに認証設定がされていません。

アプリケーションのデフォルト設定ではENFORCE_AUTH=Trueとなっており、認証プロバイダーが設定されていない場合にこのエラーが表示されます。

解決方法

手順7: 認証設定（必須）に従って、Azure App Serviceに認証を設定してください。

参考リンク:

公式ドキュメント: Set Up Authentication in Azure App Service
Microsoft公式: Azure App Service での認証と承認

確認方法

認証設定後、以下のコマンドで設定を確認できます：

リソース名がわかっている場合:

# 認証が有効化されていることを確認
az webapp auth show --name app-ragpocxxxxx --resource-group rg-ragpoc \
  --query "enabled" -o tsv

# 期待される出力:
# true

Web App名を動的に取得する場合:

# Web App名を取得
WEBAPP_NAME=$(az webapp list --resource-group rg-ragpoc \
  --query "[?contains(name, 'app-')].name" -o tsv | grep -v "\-admin" | head -1)

# 認証状態を確認
az webapp auth show --name "$WEBAPP_NAME" --resource-group rg-ragpoc \
  --query "enabled" -o tsv

# 期待される出力:
# true

認証設定の反映時間とトラブルシューティング

現象: 認証設定後も「Authentication Not Configured」が表示される

認証設定を完了しても、反映まで2-5分程度かかります。以下は正常な動作です：

✅ 認証設定を完了（Azure Portal）
❌ すぐにアクセス → 「Authentication Not Configured」が表示される
❌ 何度再読み込みしても同じエラー
⏰ 2-5分待つ
✅ 再読み込み → Microsoftログイン画面にリダイレクト
- URL例: https://login.microsoftonline.com/.../oauth2/v2.0/authorize...
✅ 「要求されているアクセス許可」画面で**「承諾」**をクリック
✅ アプリケーションにアクセス可能

推奨手順:

リソース名がわかっている場合:

# 認証設定完了後、5分待ってから確認
sleep 300

# 認証状態を確認
az webapp auth show --name app-ragpocxxxxx --resource-group rg-ragpoc \
  --query "{Enabled: enabled, Provider: unauthenticatedClientAction}" -o table

# ブラウザでアクセス（Microsoftログインにリダイレクトされることを確認）
# https://app-ragpocxxxxx.azurewebsites.net/

Web App名を動的に取得する場合:

# 認証設定完了後、5分待ってから確認
sleep 300

# Web App名を取得
WEBAPP_NAME=$(az webapp list --resource-group rg-ragpoc \
  --query "[?contains(name, 'app-')].name" -o tsv | grep -v "\-admin" | head -1)

# 認証状態を確認
az webapp auth show --name "$WEBAPP_NAME" --resource-group rg-ragpoc \
  --query "{Enabled: enabled, Provider: unauthenticatedClientAction}" -o table

# ブラウザでアクセス（Microsoftログインにリダイレクトされることを確認）
echo "https://$WEBAPP_NAME.azurewebsites.net/"

重要な注意:

Web App（app-ragpocxxxxx）とAdmin Web App（app-ragpocxxxxx-admin）の両方で認証設定が必要です
各アプリで初回アクセス時にアクセス許可の承諾が必要です
承諾は一度のみ（以降は自動的にサインイン）

参考: アプリケーション自体も反映遅延を想定しており、エラー画面に「Authentication configuration takes a few minutes to apply.」と表示されます（code/frontend/src/pages/layout/Layout.tsx:148）。

ブラウザでアプリにアクセスし、Microsoftアカウントでのサインインが要求されることを確認してください。

Q4. 「Quota exceeded for : 0 VMs allowed」エラーが発生する

症状

azd upのプロビジョニングフェーズで以下のエラーが発生する：

SubscriptionIsOverQuotaForSku: Quota exceeded for : 0 VMs allowed, 1 VMs requested

原因

このエラーメッセージは誤解を招きやすいです。調査事例では、VMクォータ不足ではなく別の原因であることが判明しました。

調査で判明した原因:

App Service Planのリージョン別キャパシティ制限
特定のリージョン（特にjapaneast）でFree/Basic App Service Planの新規作成が制限されている
キャパシティ管理により制限が設定されている可能性がある

重要な事実:

✅ F1 Free Tierは共有インフラで動作し、専用VMを使用しない
✅ 従量課金プランでも影響を受ける（サブスクリプションの問題ではない）
❌ エラーメッセージに「VM quota」とあるが、調査事例ではVMクォータとは無関係だった

リージョン別の制限状況:

リージョン	制限状況	備考
japaneast	❌ 制限あり	Free/Basic App Service Planの新規作成が制限される
eastus2	制限の報告なし	実証済み（推奨リージョン）
westus2	制限の報告なし	実証済み（代替リージョン）

解決方法

リージョン設定の確認

このエラーが発生した場合、リージョン設定が本記事の推奨設定（eastus2）になっているか確認してください。別のリージョンを設定している場合は、以下のコマンドで推奨設定に変更してください：

# リージョン設定を確認
azd env get-values -e ragpoc | grep AZURE_LOCATION

# eastus2以外の場合、推奨設定に変更
azd env set AZURE_LOCATION "eastus2" -e ragpoc
azd env set AZURE_OPENAI_RESOURCE_LOCATION "eastus2" -e ragpoc

# リソースグループ名も変更する場合
azd env set AZURE_RESOURCE_GROUP "rg-ragpoc-eastus2" -e ragpoc

# 再デプロイ
azd up -e ragpoc

確認方法

設定変更後、以下のコマンドでデプロイが成功することを確認：

# デプロイ実行
azd up -e ragpoc

# 成功後、App Serviceの確認
az webapp list --resource-group rg-ragpoc --query "[].{name:name, state:state, location:location}" -o table

# 期待される出力:
# Name                        State      Location
# --------------------------  ---------  ----------
# app-ragpocxxxxx             Running    eastus2

重要: 調査事例では、このエラーは従量課金プランでも発生しました。サブスクリプションの種類だけでは解決しない可能性があります。

Q5. .envファイルに多数の環境変数が追加されているのはなぜ？

質問

.azure/ragpoc/.envファイルを確認すると、手動で設定した環境変数以外にも多数の値が追加されています。これはいつ、誰が追加したのでしょうか？

例:

# 手動設定した値（7個）
AZURE_SUBSCRIPTION_ID="..."
AZURE_RESOURCE_GROUP="..."
AZURE_LOCATION="..."
AZURE_APP_SERVICE_HOSTING_MODEL="code"
...

# 自動追加された値（50個以上）
ADMIN_WEBSITE_NAME="https://app-ragpocxxxxx-admin.azurewebsites.net"
AZURE_POSTGRESQL_HOST_NAME="psql-ragpocxxxxx-postgres.postgres.database.azure.com"
BACKEND_URL="https://func-ragpocxxxxx.azurewebsites.net"
...

回答

これらの環境変数は、azd upコマンドのプロビジョニングフェーズ完了時に自動的に追加されます。

追加タイミング:

azd up実行
パッケージング完了
プロビジョニング完了 ← このタイミングで.envファイルが更新される
デプロイフェーズ開始（更新された環境変数を使用）

追加される内容:

作成されたリソースの名前（App Service, Function App, PostgreSQL等）
エンドポイントURL
データベース接続情報
アプリケーション設定値
システムプロンプト

なぜ自動追加されるのか:

azdは、Bicepテンプレート（infra/main.bicep）の出力値（outputs）を自動的に収集し、.envファイルに書き込みます。これにより：

手動設定不要: リソース名やエンドポイントを手動でコピーする必要がない
設定ミス防止: 自動収集により、タイプミスや設定漏れを防止
即座に利用可能: デプロイフェーズでアプリケーションが必要とする環境変数が揃っている

確認方法:

# .envファイルの更新時刻を確認
ls -l .azure/ragpoc/.env

# プロビジョニング完了時刻と一致していることを確認

注意:

これらの値は自動生成されるため、手動で編集する必要はありません
再デプロイ時に上書きされる可能性があるため、カスタム設定はazd env setコマンドで行ってください

参考:

Bicep outputs: infra/main.bicepのoutputセクション
azd環境変数管理: Azure Developer CLI 環境変数

まとめ

IaCを活用したAzure × RAGシステムの概念検証により、以下の価値を実現できます：

実現した3つの価値

1. 時間の大幅削減

手動構築（数日）→ IaCデプロイ（1-2時間）
環境差異の排除により、トラブルシューティング時間も削減

2. 再現性の確保

同じコマンドで何度でも同じ環境を構築
チームメンバー間で環境を共有・再現可能
PoCから本番へのスムーズな移行

3. カスタマイズ基盤の獲得

ベースライン実装でカスタマイズが容易
フォーク＆クローンで独自要件への対応が可能
公式更新との同期により最新機能を取り込み可能

この手法が適している方

PoCを急ぎたい方: デプロイ時間を最小化
カスタマイズを前提とする方: Azure OpenAI標準機能では要件を満たせない場合
再現性を重視する方: 環境差異を排除し、チーム共有を容易に

次のステップ

デプロイ後のデータアップロード:

Azure × RAGの概念検証を、IaCとCLI-firstアプローチで効率的に実現しましょう。

Discussion