genai-ai-api（源内RAG API）をAWSにCDKでデプロイする手順

「genai-webはデプロイできた。でも、RAG機能を使うにはgenai-ai-apiという別リポジトリが要ることを知らなかった」

前回の記事で源内（genai-web）のポータルをデプロイした後、こう思う方は少なくないはずです。genai-webはあくまでチャットポータルの実装で、社内文書を検索して回答するRAG（検索拡張生成）機能は、genai-ai-apiという別のリポジトリが担っています。実際、genai-web単体のデプロイ手順を扱った前回の記事でも、genai-ai-apiのデプロイは対象外としていました。

この記事では、genai-ai-api（正確にはその中のAWS向け実装query-expansion-rag）を、実際にAWS CDKでデプロイする手順を整理します。

この記事でわかること

• genai-webとgenai-ai-apiの役割の違い
• CMEK暗号化方式（個別/共通）の選び方
• 4つの設定ファイルの役割と関係性
• 実際のデプロイ手順
• デプロイ後の動作確認方法（curlでのAPI呼び出し）

前提知識

• 源内PoCの始め方 で、AWSアカウント・Bedrockモデルアクセス・CDK bootstrapなどの事前準備を確認しておいてください
• 源内（genai-web）をAWSにCDKでデプロイする手順とハマりやすい注意点 で、genai-web単体のデプロイ手順を解説しています。本記事はその続きとして、RAG機能を担うgenai-ai-api側を扱います
• genai-ai-apiのRAGアーキテクチャ（クエリ拡張・Knowledge Base検索・回答生成の流れ）自体は、源内AIのコードをGitHubから読む で詳しく解説済みです。本記事では重複を避け、デプロイの実務（設定ファイル・コマンド・動作確認）に絞ります

genai-ai-apiの全体像（おさらい）

genai-ai-apiは、源内のRAG機能を実装したリポジトリです。AWS向けの実装はaws/query-expansion-ragというディレクトリにまとまっています。デプロイ単位で見ると、構成はシンプルです。

API Gatewayが受けたリクエストをLambdaが処理し、Bedrock Knowledge Base（OpenSearch Serverlessでベクトル検索）を使って回答を生成する、という流れです。

この処理フローの詳細（クエリ拡張・関連性評価・回答生成の4ステップ）は、前述のアーキテクチャ解説記事で扱っているので、ここでは繰り返しません。この記事が扱うのは、「実際にこれをどうAWSへデプロイするか」という手を動かす部分です。

もう一つ押さえておきたいのは、この実装が1つのコードベースから複数のRAGアプリケーションを並行デプロイできる設計になっている点です。部署ごとに別々のRAG APIを立てたい、といったケースに対応しやすくなっています。

全体像を思い出したところで、デプロイ前に決めておくべき暗号化方式の選択に進みます。

CMEK方式（個別か共通か）を先に決めておく

genai-ai-apiは、Knowledge Baseのデータを暗号化するためにKMSのカスタマー管理キー（CMEK）を使います。デプロイするアプリケーションごとに、2つの方式のどちらかを選びます。

• 個別CMEK方式では、各RAG APIが独自のKMSキーを持ちます。API単位でキーを削除・管理できるため、部署やプロジェクトごとにデータを厳密に分離したい場合に向いています
• 共通CMEK方式では、複数のAPIが1つのKMSキーを共有します。OpenSearch ServerlessのOCU（処理容量）を複数アプリで効率的に共有できるのが利点です

正直なところ、小規模なPoCや、まず1つのRAG APIを試したいだけの段階では、共通CMEK方式で始めるのもありです。OpenSearch ServerlessのOCUには最小構成でも一定の固定費がかかるため、個別CMEK方式でアプリごとにOCUを持つと、その固定費がアプリの数だけ積み上がってしまいます。共通CMEK方式ならOCUを複数アプリで共有できるため、この重複を避けられます。複数部署に展開する段階になったら、個別CMEK方式への切り替えを検討する、という進め方が現実的です。

方式を決めたら、次はその設定をどのファイルに書くのかを整理します。

設定ファイルの役割

genai-ai-apiのデプロイでは、以下の4つの設定ファイルがそれぞれ異なる役割を持ちます。genai-web（パラメータファイル1つで完結）と比べると、ここが一番戸惑いやすいポイントです。

ファイル	役割
cdk.json	デプロイ対象のアプリ一覧を定義する最上位の設定。個別CMEK方式ならqeRagAppNames配列、共通CMEK方式ならqeRagAppNamesWithSharedCmek配列にアプリ名を追加する
parameter.ts	環境（-dev/-stg/-prd）ごとの差分設定を管理する。IPアドレス制限（allowedIpV4AddressRanges等）もここに記述する
config/apps/*.toml	アプリケーションごとの個別パラメータ。デフォルト設定から変更したい項目だけを書けばよく、書かなかった項目は自動的にデフォルト値が適用される
lib/switch-role-stack.ts	Bedrock Flows開発者向けの限定的なIAMロール（SwitchRole）を定義するスタックファイル

なお、アプリ名をcdk.jsonの配列に重複して登録すると、デプロイ前にエラーになります（設定を一通り書き終えた後に気づくと地味に大変です）。新しいアプリを追加する際は、既存の名前と被っていないか先に確認しておくと手戻りがありません。

設定ファイルの役割が分かったところで、実際のデプロイコマンドに進みます。

デプロイ手順

前提条件は以下の3つです。

• AWS CLI
• Node.js（v22.x）
• AWS CDK

準備ができたら、以下の順でコマンドを実行します。

# 依存関係のインストール（npm workspacesによりcustom-resourcesの依存も自動解決される）
npm ci

# CDK bootstrap（このAWS環境で初めてデプロイする場合のみ、1回実行）
cdk bootstrap

# デプロイ実行（環境名を指定）
cdk deploy --all -c env=-dev    # 開発環境
cdk deploy --all -c env=-stg    # ステージング環境
cdk deploy --all -c env=-prd    # 本番環境

npm ciの時点でcustom-resourcesワークスペースの依存関係もまとめてインストールされるので、個別にインストールし直す必要はありません（npm workspacesの標準的な挙動です）。

関連記事 源内（genai-web）をAWSにCDKでデプロイする手順とハマりやすい注意点 genai-web側のデプロイ前提（Bedrockモデルアクセス・CDK bootstrapのリージョン）も合わせて確認しておくと安心です。

デプロイが終わったら、実際にAPIが正しく動いているかを確認します。

デプロイ後の動作確認

デプロイが完了すると、CDKの出力にApiEndpointとApiKeyIdが表示されます。まずAPIキーの値を取得します。

aws apigateway get-api-key --api-key <ApiKeyId> --include-value --query value --output text

取得したAPIキーとエンドポイントを使って、実際にRAGへ質問を投げてみます（x-api-keyヘッダーを付け忘れてForbiddenが返ってくるのはよくある話です）。

API_ENDPOINT="<CDK出力のApiEndpoint>"
API_KEY="<取得したAPIキー>"

curl -X POST "$API_ENDPOINT" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d '{
    "inputs": {
      "question": "フレックスタイム制について教えてください。",
      "n_queries": 3,
      "output_in_detail": false
    }
  }'

inputs.questionが必須項目で、実際に投げたい質問文を入れます。n_queriesはクエリ拡張の数（デフォルト3）、output_in_detailは詳細な回答モードのオン/オフです（デフォルトfalse）。Knowledge Baseに登録した文書の内容に沿った回答が返ってくれば、デプロイは成功です。

まとめ

genai-ai-apiは、genai-webとは別リポジトリで、源内のRAG機能を担うAPIです。CMEK暗号化方式を個別・共通のどちらにするか決め、cdk.json・parameter.ts・config/apps/*.toml・switch-role-stack.tsの4つの設定ファイルにそれぞれ必要な設定を反映します。あとはcdk deploy --all -c env=のコマンド1つでデプロイでき、APIキーを取得してcurlで質問を投げてみれば動作確認も完結します。

まずは共通CMEK方式・1アプリ構成から試してみて、複数部署への展開が視野に入った段階で個別CMEK方式への切り替えを検討するのがおすすめです。genai-web・genai-ai-apiを実際に構築した際の実測コストなどは、源内AIシリーズの別記事で追って扱う予定です。

参考文献

• GitHub: digital-go-jp/genai-ai-api — 源内RAG API公式リポジトリ
• query-expansion-rag README — CDKデプロイ手順・設定ファイルの詳細
• 源内（genai-web）をAWSにCDKでデプロイする手順とハマりやすい注意点 — genai-web単体のデプロイ手順
• 源内AIのコードをGitHubから読む——genai-webとgenai-ai-apiのAWS構成 — RAGアーキテクチャの詳細解説
• 源内PoCの始め方——最小構成で2週間・月$10から試す方法 — 事前準備の詳細