Vertex AI Search API の叩き方

AI にドキュメントを参照させる際、「必要な情報だけを検索で取り出して使う」RAG（検索拡張生成） の考え方が有効です。Vertex AI Search（Discovery Engine）を使えば検索部分を任せられます。

ただし、チャットボットや自社アプリに RAG を組み込む場合、コンソールの UI だけでは足りません。ユーザーの質問に応じて検索 API を呼び出し、得た結果を LLM に渡す……といった形で、プログラムから API で呼び出す必要があります。
Python や Node.js 用の SDK も提供されていますが、まずは curl で HTTP レベルから叩ける状態にしておくと、権限・URL・JSON 構造の切り分けが速くなります。SDK を導入する前の動作確認としても有効です。

この記事では、API で検索できる状態までを最短で整える手順をまとめます。

1. コンソール生成 curl から URL と Body を抜き出す

Vertex AI Search のアプリ画面で「統合」→「API」を開き、検索語句を入力します。生成された curl コマンドから、次の2点を抜き出します。

• URL
• -d 以降の JSON body

2. Bearer Token を取得する

API 呼び出しでは アクセストークンが必要です。次のいずれか一つの方法を採用すれば足ります。

2.1 ユーザー認証で発行する（簡単、最短）

Cloud Shell で gcloud auth print-access-token を実行するだけです。サービスアカウントの作成が不要で、最短で試せます。トークンの有効期限はおよそ1時間です。

gcloud auth print-access-token

2.2 サービスアカウントで発行する（本導入用）

運用時やプログラムから呼び出す場合は、サービスアカウントを使います。Cloud Shell で発行する方法と、プログラム（Python）の中で発行する方法があります。

2.2.1 （共通/事前準備）サービスアカウントの作成と権限付与

サービスアカウントを作成し、Discovery Engine を呼び出せるロールを付与します。検索 API を呼び出すだけであれば、最低限次のロールで足ります。

• roles/discoveryengine.viewer（Discovery Engine 閲覧者）

インデックス管理なども行う場合は、用途に応じて上位ロールを検討します。

サービスアカウント作成後、「鍵を追加」から JSON 鍵を生成して取得します。

2.2.2 Cloud Shell で発行する

生成した鍵（json）を Cloud Shell にアップロードし、次を実行します。

gcloud auth activate-service-account --key-file=/path/to/service-account.json
gcloud auth print-access-token

2.2.3 プログラム（Python）の中で発行する

生成した鍵（json）を使用して、プログラムでBearer Tokenを取得することも可能です。

• ライブラリ

  pip install google-auth requests
  

• トークン再発行プログラム

  from google.oauth2 import service_account
  from google.auth.transport.requests import Request
  
  KEY_FILE = "service-account.json"
  SCOPES = ["https://www.googleapis.com/auth/cloud-platform"]
  
  creds = service_account.Credentials.from_service_account_file(KEY_FILE, scopes=SCOPES)
  creds.refresh(Request())
  print(creds.token)
  

3. Vertex AI Search を API で呼び出す

ここまでで揃ったものは次です。

• 検索 API の URL（コンソールの curl から抽出）
• Bearer Token（Cloud Shell / サービスアカウント / Python で取得）
• JSON body（コンソールの curl から抽出）

Vertex AI Search の検索 API は、Summary と CHUNKS の2種類の結果を返せます。

• Summary：検索でヒットした複数文書の「要約」をまとめて返す。後続の AI へ渡したり、そのまま表示する用途に向く。
• CHUNKS：検索結果を文書の一部（チャンク）として返す。「出典のどこに書いてあるか」を出したいときに使う。

どちらか一方だけを指定することも、同じリクエストで両方取得することもできます。いずれにするかで contentSearchSpec の設定が変わり、返ってくるレスポンスの形も異なります。

以下、それぞれの呼び出し方を見ていきます。

3.1 Summary を返す：複数文書の要約をまとめて取得する

Summary は、検索でヒットした複数文書を材料にして「要約」をまとめて返してくれます。

リクエスト例（Summary）

Summary を取得する場合は コンソールの curl から抽出した JSON body に contentSearchSpec の中に summarySpec を定義します。

※ < > で囲まれている箇所（<PROJECT_ID> や <ENGINE_ID> など）は環境に合わせて置き換えます。
※ <PROJECT_ID> は GCP のプロジェクトID、<ENGINE_ID> は作成した検索エンジンIDです。

curl -X POST \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/<PROJECT_ID>/locations/global/collections/default_collection/engines/<ENGINE_ID>/servingConfigs/default_search:search" \
  -d '{
    "query": "UIのレビュー規約から画面構成に関するルールを取得して",
    "pageSize": 10,
    "languageCode": "ja",
    "contentSearchSpec": {
      "summarySpec": {
        "summaryResultCount": 3,
        "includeCitations": true,
        "ignoreAdversarialQuery": true
      }
    },
    "userInfo": { "timeZone": "Asia/Tokyo" }
  }'

レスポンス例（Summary）

上記のリクエストで得られる「要約のまとめ」は、レスポンスの summary.summaryText に格納されています。動作確認時はここに期待どおりの内容が返っているか確認してください。

3.2 CHUNKS を返す：根拠箇所（本文）を取得する

「出典のどこに書いてあるか」を提示したい場合は CHUNKS を使います。
CHUNKS は、検索結果を文書の一部（チャンク）として返し、必要に応じて前後の文脈も含めて取得できます。

リクエスト例（CHUNKS）

curl -X POST \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/<PROJECT_ID>/locations/global/collections/default_collection/engines/<ENGINE_ID>/servingConfigs/default_search:search" \
  -d '{
    "query": "UIのレビュー規約から画面構成に関するルールを取得して",
    "pageSize": 10,
    "languageCode": "ja",
    "contentSearchSpec": {
      "searchResultMode": "CHUNKS",
      "chunkSpec": { "numPreviousChunks": 1, "numNextChunks": 1 }
    },
    "userInfo": { "timeZone": "Asia/Tokyo" }
  }'

• searchResultMode: "CHUNKS"：チャンク単位で返す
• chunkSpec：前後の文脈を含めて取得する

レスポンス例（CHUNKS）

上記のリクエストで得られる「チャンク」は、レスポンスの chunk に格納されています。

よくあるトラブル

• 401：Bearer Token 期限切れ、Bearer の設定ミス
• 403：サービスアカウントの権限不足（roles/discoveryengine.viewer が付与されているか確認）
• 400：リクエスト JSON の構造ミス（特に contentSearchSpec 周り）

まとめ

• Vertex AI Search は、まず APIで叩ける状態 を最短で作ると導入が進む
• Summary は複数文書の要約をまとめる用途に向く
• CHUNKS は本文根拠を取る用途に向く