Gemini API (Vertex AI)

解決する課題

• 自前で大規模言語モデルを学習・運用せずに、高品質な生成 AI をアプリへ組み込みたい
• テキストだけでなく画像・音声・動画・PDF などを混在させた入力を一つの API でまとめて処理したい
• モデルの出力を外部システムやツール呼び出しにつなぎ、検索・計算・データ取得などの処理を実行させたい
• 生成結果を Google 検索や自社データに根拠付けして、ハルシネーション（もっともらしい誤り）を抑えたい
• 企業利用に必要なIAM・データ境界・監査ログを備えた基盤の上で生成 AI を安全に動かしたい

主要概念と用語

• Gemini: テキスト・画像・音声・動画などを扱えるマルチモーダルな基盤モデル群。用途や速度・コストに応じて複数のモデルバリエーションが提供される
• Gemini API: Vertex AI 上で Gemini を呼び出すためのインターフェース。リクエストにプロンプトとパラメータを渡し、生成結果を受け取る
• マルチモーダル: テキストに加えて画像・音声・動画・ファイルなど複数の種類の入力を同時に与えられる性質
• プロンプト: モデルへの指示・入力。役割を与えるシステム指示と、利用者からの入力を分けて設計できる
• トークン: モデルが処理する入出力の最小単位。課金やコンテキスト長の上限はトークン数で数える
• コンテキストウィンドウ: 1 回のリクエストでモデルが扱える入力＋出力トークンの上限
• Function Calling（関数呼び出し）: モデルが必要なツールや関数を判断し、呼び出すべき関数名と引数を構造化して返す仕組み。外部 API 連携やエージェント構築に使う
• Grounding（グラウンディング）: 生成結果を Google 検索や自社データに根拠付けし、出典付き・検証可能な回答に近づける機能
• Structured Output（構造化出力）: 出力を指定したスキーマに沿った形式で返させ、後続処理で扱いやすくする仕組み
• Safety 設定（セーフティ）: 有害カテゴリごとに出力をフィルタリングする安全フィルタの調整

仕様・制限・クォータ

• モデルは提供リージョンが限られることがあり、利用したいモデルが目的のリージョンにあるかを設計初期に確認する必要がある
• 入力・出力には**トークン上限（コンテキストウィンドウ）**があり、扱える画像枚数・音声や動画の長さ・ファイルサイズにも上限がある
• プロジェクト単位で1 分あたりのリクエスト数・トークン数などのレート制限がある。これらは定性的に「上限がある」と捉え、最新値はコンソールのクォータ画面で確認する
• モデルは継続的に更新・追加され、安定版とプレビュー版が並行して提供されることがある。バージョン指定の方針を決めておくと挙動の再現性を保ちやすい
• 具体的な上限値・対応モデル・コンテキスト長は更新が頻繁なため、断定せず公式ドキュメントとクォータ画面で都度確認する

内部の仕組み

Gemini モデルは Google 側のマネージドな計算基盤でホストされ、利用者は Vertex AI の API 経由で呼び出します。リクエストには、プロンプト（システム指示と入力）、温度や最大出力トークンなどの生成パラメータ、安全フィルタの設定などを含めます。マルチモーダル入力は、テキストと画像・音声・動画・ファイルを一つのリクエスト内のパートとして並べ、モデルがまとめて解釈します。

応答は一括で受け取るほか、トークンを逐次返すストリーミングでも受け取れます。Function Calling を使う場合、モデルは「どの関数をどの引数で呼ぶべきか」を構造化して返し、アプリ側が実際の処理を実行して結果を再びモデルへ渡す、という往復でエージェント的な動作を組み立てます。Grounding を有効にすると、生成前に検索や自社データソースを参照し、その情報を踏まえた回答と出典を返します。すべての呼び出しは Vertex AI の IAM・監査ログ・データ境界の枠組みの中で行われます。

設計パターン / ベストプラクティス

• 役割と入力を分離する: システム指示で振る舞いを固定し、利用者入力と区別することで、意図しない指示の上書きを防ぐ
• 構造化出力でつなぐ: 後続処理に渡す結果は Structured Output でスキーマを指定し、自由文の解析を避ける
• ツール連携は Function Calling で: 検索・計算・DB 参照などはモデルに直接やらせず、関数呼び出しでアプリ側の処理に委譲する
• 根拠付けを前提にする: 事実回答が必要な業務では Grounding や検索拡張（自社データ参照）で出力を検証可能にする
• モデルを使い分ける: 低レイテンシ・低コストが要る用途と、高度な推論が要る用途で適切なモデルを選ぶ
• 再試行とタイムアウトを設計する: レート制限や一時エラーに備え、指数バックオフ付きのリトライとタイムアウトを実装する

運用・監視

• Cloud Monitoring / Cloud Logging でリクエスト数・レイテンシ・エラー率を監視し、レート制限への到達状況を把握する
• トークン消費量を継続的に計測し、コストとクォータの両面から異常な増加を検知する
• プロンプトとモデルバージョンを構成として管理し、変更履歴を残して出力品質の回帰を追えるようにする
• 安全フィルタによるブロックや関数呼び出しの失敗をログに残し、ユーザー体験への影響を運用で監視する
• 監査要件がある場合はCloud Audit Logs で誰がどのモデルを呼び出したかを記録する

コスト

セキュリティ

• IAM でモデル呼び出し権限を最小権限に分離し、サービスアカウント単位でアクセスを制御する（AWS の IAM ロール相当）
• ワークロードにはサービスアカウントを割り当て、APIキーやサービスアカウントキーのハードコードを避ける
• VPC Service Controls でデータ境界を作り、機微なプロンプトやデータの外部流出を防ぐ
• プロンプトインジェクションに備え、利用者入力を信頼境界として扱い、システム指示と分離し、出力を検証してから後続処理に渡す
• 安全フィルタ（Safety 設定）で有害な出力を抑制しつつ、ログに機微情報をそのまま残さない取り扱いを設計する

関連サービス・比較

生成 AI の入口は Gemini API ですが、検索・配信・運用まで含めた全体は Vertex AI が担います。狭義の「モデル呼び出し」と、広義の「ML/生成 AI 基盤」を区別すると役割が整理できます。

ハンズオン / CLI例

# 1) 認証とプロジェクト・リージョンの設定
gcloud auth application-default login
gcloud config set project MY_PROJECT
LOCATION=us-central1
MODEL=gemini-2.0-flash

# 2) アクセストークンを取得
TOKEN=$(gcloud auth print-access-token)

# 3) Gemini API にテキスト生成をリクエスト
curl -s -X POST \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  "https://${LOCATION}-aiplatform.googleapis.com/v1/projects/MY_PROJECT/locations/${LOCATION}/publishers/google/models/${MODEL}:generateContent" \
  -d '{
    "contents": [
      { "role": "user", "parts": [ { "text": "Vertex AI の Gemini API を一言で説明して" } ] }
    ]
  }'