agent-platform-inference

Agent Platform GenAI Inference Skill

このスキルでは、Google Cloud Agent Platform に認証して接続し、生成 AI モデルを使用する方法を説明します。以下を対象としています。

• ファーストパーティのパブリッシャーモデル（Gemini）— セクション 2。
• サードパーティのパブリッシャーモデル（OpenMaaS：Llama、DeepSeek、Qwen など） — セクション 3。
• カスタムエンドポイント（数値の projects/.../endpoints/<id> リソース上の任意のモデル。チューニング済み Gemini モデル、agent-platform-deploy スキルで Model Garden からセルフデプロイした OSS LLM、従来のカスタムモデルなど） — セクション 4。

安全性と確認のティア（重大）

ユーザーに代わってコマンドやスクリプトを実行する前に、要求された操作に応じた以下の安全性ティアを遵守する必要があります。（このスキルは読み取り専用のため、その他の安全性ティアは省略されています。）

1. ティア R：読み取り専用／推論（client.models.generate_content、client.chat.completions.create、client.completions.create、client.embeddings.create）
   • 予期しない費用やクォータの消費を防ぐため、ユーザーに代わってモデル推論を実行する前に、「Yes」／「No」の選択肢を含む対話形式の確認が必要です。
   • 確認カードに必須の項目：確認プロンプトでは、実行予定の推論を明確に説明し、以下のパラメーターをすべて明示する必要があります。
     • プロジェクト ID：Google Cloud のプロジェクト ID または番号（例：123456789012、my-project）。
     • リージョン／ロケーション：対象リージョン（例：us-central1、global）。
     • モデル ID：正確なモデル ID（例：gemini-2.5-flash、deepseek-ai/deepseek-v3.2-maas）。
     • SDK：使用する SDK（例：Google GenAI SDK (google-genai)、OpenAI SDK）。
     • 入力プロンプト（または入力画像／入力メディア）：プロンプトのテキストまたはメディア URI。
     • 指定されている場合は、追加の生成パラメーター（例：max_output_tokens、response_schema）。 これらのパラメーターを明示せずに自然言語で言い換えるだけでは不十分です。
   • 同一ターンでの実行禁止：確認プロンプトを提示したターン内に、推論スクリプトやコマンドを実行してはいけません。処理を停止してユーザーの返答を待ち、「Yes」／承認を明示的に得てから実行してください。
   • 模範例：

     以下のパラメーターでモデル推論を実行します。続行する前に、この内容をご確認ください。

     • プロジェクト ID：my-project
     • リージョン：us-central1
     • モデル ID：gemini-2.5-pro
     • SDK：Google GenAI SDK（google-genai）
     • 入力プロンプト：「Hamlet のあらすじを 3 文で要約してください」

     承認しますか？ [Yes/No]

   • 実行後の応答での根拠提示（重大）： ユーザーから明示的な承認を得て、SDK 経由で推論呼び出しを実行した後、生成テキストを返す応答では、モデルの出力とともに、実行パラメーターを明示的に確認する必要があります。モデルの応答だけを単独で返してはいけません。必ず以下を含めてください。
     • モデル ID：使用した正確なモデル ID（例：gemini-2.5-pro または <MODEL_ID>）。
     • SDK：使用した SDK（例：Google GenAI SDK (google-genai) または OpenAI SDK）。
     • プロジェクト ID：使用した Google Cloud のプロジェクト ID／番号。
     • リージョン：使用したリージョンまたはエンドポイントのロケーション（例：global または us-central1）。
     • 生成された出力：モデルが生成した回答の全文。

フェーズ 0：環境のセットアップ

重要：scripts/ ディレクトリ内の Python サンプルスクリプト（例：scripts/openmaas_openai_sdk.py）を実行する前に、以下の手順に従って環境が正しく初期化されていることを必ず確認してください。

1. Google Cloud 認証：Google Cloud の認証情報で認証し、Agent Platform にアクセスするための有効な Application Default Credentials（ADC）を設定します。

   gcloud auth login
   gcloud auth application-default login
   

2. API の有効化（まだ有効になっていない場合）：

   gcloud services enable aiplatform.googleapis.com
   

3. Python の依存関係：スクリプトでは vertexai（google-cloud-aiplatform から）、google-genai、openai をインポートします。仮想環境は作成しないでください。仮想環境は空の状態で始まり、環境にすでに用意されているパッケージを隠してしまうため、重複したインストールが必要になります。まず確認し、不足しているものだけをインストールしてください。

   python3 -c "import vertexai, google.genai, openai" \
     || pip install -r scripts/requirements.txt
   

   scripts/requirements.txt は、これらの SDK が環境に用意されていない場合の代替手段です。動作中の環境に対してインストールしないでください。

4. セットアップの確認（任意）：すべてのサンプルスクリプトを一度に実行し、環境がエンドツーエンドで動作することを確認します。

   ./scripts/verify_all.sh
   

5. 実行：スクリプトは通常どおり python3 scripts/... で実行してください。事前に有効化する環境はありません。

重要

重要：モデル ID と利用可能状況 * Gemini モデル：有効なモデル ID とリージョンについては、[Gemini モデル][gemini-models-docs]をご覧ください。 * OpenMaaS モデル：Llama、DeepSeek、Qwen などについては、Agent Platform でオープンモデルを使用するをご覧ください。 * 不完全なリスト：このスキルに記載されているモデル ID は例にすぎず、不完全または古い可能性があります。 * 対応：コードを生成する前に、必ず上記のリンクを使ってモデル ID とリージョンを確認してください。

[gemini-models-docs]: https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/migrate

パラメーターの確認と明確化プロトコル（重要）

コードを準備する前、または Tier R の確認カードを提示する前に、必要なすべてのパラメーターが確認できていることを必ず確かめてください。

1. モデル ID、モデルファミリー、または SDK が指定されていない場合（重要）：

   • ユーザーが使用するモデルまたはモデルファミリーを指定していない場合（例：「テストプロンプトを実行して」「生成 AI モデルに……と尋ねて」「モデルのバージョンを指定せずに DeepSeek に質問して」）、または SDK の希望を指定していない場合：
   • モデル（gemini-2.5-flash、gemini-2.5-pro、deepseek-v3.2-maas など）を決して推測したり、自発的に提案したり、デフォルトとして選んだりしないでください。確認を求めずにデフォルトのモデルを確認カードで提案すると、パラメーターの確認に違反します。
   • 必ず処理を止めて、ユーザーに尋ねてください：「どのモデル（または Gemini、Llama、DeepSeek、Qwen などのモデルファミリー）と、どの SDK（Google GenAI SDK、OpenAI SDK など）を使用しますか？」また、指定されていない場合は、対象のリージョンとプロジェクト ID も尋ねてください。
   • ユーザーがモデル（および未指定の SDK の希望）を指定してから、実行の準備を進め、Tier R の確認プロンプトを提示してください。

2. プロジェクト ID またはリージョンが指定されていない場合：

   • ユーザーのプロジェクト ID またはリージョンがプロンプトや会話の文脈で指定されていない場合は、プロジェクト ID とリージョンを尋ねてください（例：「どのプロジェクト ID とリージョンを使用しますか？」）。プロジェクトやリージョンを暗黙に決めつけないでください。

   • OpenMaaS のロケーション：OpenMaaS のパブリッシャーモデルは global（例：deepseek-ai/deepseek-v3.2-maas、meta/llama-3.3-70b-instruct-maas）または us-central1 などのリージョナルエンドポイント（例：deepseek-ai/deepseek-r1-0528-maas）でホストされています。OpenMaaS モデルの推論を設定するときは、適切なエンドポイントを使用してください。

     • グローバル：https://aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/global/endpoints/openapi
     • リージョナル：https://{REGION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{REGION}/endpoints/openapi

     また、確認カードと最終応答にリージョンを明示してください。

3. SDK の選択：

   • ユーザーがモデルを指定していて SDK を指定していない場合は、そのモデルファミリーに適した SDK を使用してください（Gemini には GenAI SDK の google-genai、OpenMaaS には OpenAI SDK の openai）。

4. Python によるサンドボックス実行（重要）：

   • run_command を使ってサンドボックスでモデル推論を実行する場合は、必ず公式 SDK（google-genai、openai、vertexai など）を使って Python コードを実行してください（例：Python スクリプトを作成して実行します）。最終的な推論の実行に、生の curl コマンドを使用しないでください。

ワークフロー決定ツリー

1. モデルは指定されていますか？

   • いいえ（ユーザーがモデル名またはファミリーを省略した場合）-> ユーザーに確認し、使用したいモデルまたはモデルファミリー、対象リージョン、SDK の希望を尋ねます。
   • 指定が不十分（例：「DeepSeek」や「Llama」とだけ指定され、バージョンがない場合）-> ユーザーに確認し、希望する具体的なモデルバージョンを尋ねます （例：deepseek-ai/deepseek-r1-0528-maas、 deepseek-ai/deepseek-v3.2-maas、meta/llama-3.3-70b-instruct-maas）。
   • はい -> ステップ 2 に進みます。

2. モデルファミリーと SDK の選択：

   • Gemini（例：gemini-2.5-pro、gemini-2.5-flash）-> 推奨： GenAI SDK（google-genai）。[1. Gemini Models] に進みます。
   • OpenMaaS（例：deepseek-ai/*、meta/llama-*、qwen/*）-> 推奨：OpenAI SDK（openai）。[2. OpenMaaS Models] に進みます。
   • カスタムエンドポイント（数値のエンドポイント ID projects/.../endpoints/<id>）-> [4. Custom Endpoints] に進みます。

3. トラブルシューティング：ユーザーはエラー（429 Resource Exhausted、 400 User Validation、404 Not Found、トークン制限による空の応答など）を報告していますか？

   • はい -> [5. Troubleshooting & Common Error Codes] に進みます。
   • いいえ -> 必須項目（Project ID、Region、Model ID、SDK、Input Prompt）をすべて含む Tier R の確認プロンプトを提示し、ユーザーの確認を待ってから、Python SDK を使って実行します。

0.5 パブリッシャーエンドポイントのリージョン可用性チェック（Gemini + LoRA のベースモデル）

メモ

次のいずれかに該当する場合は、このセクションをスキップしてください。

• ユーザーがカスタムエンドポイント（§4）を呼び出している場合 — 数値の projects/.../endpoints/<id> で提供されるチューニング済み Gemini モデル、セルフデプロイされた OSS LLM（Llama、DeepSeek、Qwen、Gemma など）、またはレガシーなカスタムモデルです。これらのリクエストは、デプロイ時にリージョンが固定される特定のエンドポイントリソースに送信されます。呼び出し元側のリージョンが一致しない場合、エンドポイントの検索は推論コストを発生させず、通常の 404 を返します。§4 に進んでください。
• ユーザーが OpenMaaS パブリッシャーモデル（§2）を呼び出している場合 — グローバルな openapi ベース URL 経由で提供される Llama、DeepSeek、Qwen などです。これらには、ファーストパーティの Gemini と同様のリージョンごとの可用性制限はありません。§2 に進んでください。

このセクションを適用するのは、ユーザーがファーストパーティのマネージド Gemini モデル（gemini-*、§1 経由）を呼び出している場合に限ります。Gemini 上のファインチューニング済み LoRA アダプターも含みます。これらはリージョンごとに可用性が実際に異なるパブリッシャーエンドポイント経由でルーティングされます。

ファーストパーティのマネージド Gemini モデル（gemini-*）またはファインチューニング済み Gemini LoRA アダプター（数値のエンドポイント ID とユーザーが指定したベースモデルで特定）について、特定のリージョンを指定した推論リクエストに回答する前に、必ずライブ API 呼び出しを行い、そのモデルがそのリージョンで実際に利用可能か確認してください。可用性の判断に Google 検索、学習コーパスの知識、パブリッシャーのドキュメントを頼りにしないでください。リージョンごとの可用性は頻繁に変わるため、根拠となるテキストが古くなっていたり、誤っていたりする可能性があります。

ユーザーが指定したモデルとリージョンだけをプローブしてください。「対照」として他のモデルをプローブしないでください。モデル A の可用性はモデル B の状態から推測できません。別のモデル自体が、無関係な理由で参照リージョンで利用できない場合があるためです。

ファーストパーティの Gemini モデルの場合、最小限の有効なペイロードを使って実際の :generateContent 呼び出しでプローブしてください。

curl -sS -o /dev/null -w "%{http_code}\n" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://${LOCATION_ID}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION_ID}/publishers/google/${MODEL_ID}:generateContent" \
    -d "{\"contents\":{\"role\":\"user\",\"parts\":{\"text\":\"${PROBE_TEXT:-hi}\"}}}"

ファインチューニング済み Gemini LoRA アダプターを推論に使用する場合は、対象リージョンのベースモデルを、上記と同じ :generateContent 呼び出しでプローブしてください。このとき、${MODEL_ID} にはベースモデルを設定します（たとえば、gemini-2.5-flash でアダプターをチューニングした場合は gemini-2.5-flash を指定します）。LoRA アダプターは、ベースモデルが利用できないリージョンでは提供できません。

プローブ結果を解釈し、次のように対応してください。

• 200 — そのリージョンでモデルを利用できます。§1 の SDK セットアップに進んでください。
• 404 — そのリージョンでモデルを利用できません。停止してください。そのリージョンではモデルが提供されていないことをユーザーにはっきり伝え、利用可能なリージョンを [Gemini モデル][gemini-models-docs] または gcloud ai model-garden models list --filter="name~$MODEL_NAME"（--region を指定せずに実行）から示してください。リージョンを黙って切り替えないでください。サポートされていないリージョン向けの推論コードや SDK の初期化処理を書き進めないでください。404 を再確認するための「対照」プローブを追加で実行しないでください。対象リージョンでのプローブ結果が確定的なものです。
• その他の結果（権限拒否、クォータ、一時的な障害など） — モデルが利用可能とも利用不可とも結論付けないでください。根本原因を平易な言葉で説明し（例：「このプロジェクトの Vertex AI API にアクセスする権限がアカウントにありません。コンソールで API を有効にするか、プロジェクトを切り替えてください」）、具体的な次の手順を示してください。

1. Gemini モデル

Gemini モデル（例：gemini-2.5-pro、gemini-3-flash-preview）には、GenAI SDK（google-genai）が推奨される方法です。レガシーな vertexai SDK も引き続きサポートされていますが、新しいプロジェクトでは GenAI SDK が推奨されます。

重要

Gemini 3.1 を含むプレビューモデルは、多くの場合、global リージョンでのみ利用できます。安定版モデルは、us-central1 やその他のリージョンで利用できます。

適切な SDK の選択

• Gemini モデル：GenAI SDK（google-genai）を推奨します。互換性のために OpenAI SDK を使用するか、必要に応じてレガシー SDK（vertexai）を使用してください。
• OpenMaaS モデル：OpenAI SDK を強く推奨します。特定のインフラ要件がある場合は、GenAI SDK またはレガシー SDK を使用してください。

インストール

pip install google-genai

Python の例（GenAI SDK — 推奨）

完全なコードについては、scripts/gemini_genai_sdk.py を参照してください。

代替：OpenAI SDK（Chat Completions）

Agent Platform エンドポイントで標準の OpenAI SDK を使用します。幅広い互換性が必要な場合に最適です。

完全なコードについては、scripts/gemini_openai_sdk.py を参照してください。

レガシー：Agent Platform SDK

レガシーの vertexai SDK は現在も広く使用されていますが、新しい Gemini プロジェクトでは google-genai を推奨します。

完全なコードについては、scripts/gemini_vertexai_sdk.py を参照してください。

ドキュメント： Google GenAI SDK

ドキュメント： Agent Platform Gemini Models

2. OpenMaaS モデル（Llama、DeepSeek、Qwen など）

OpenMaaS（Model-as-a-Service）モデルでは、特定の Vertex AI エンドポイントと標準の OpenAI SDK を使用する方法を強く推奨します。

警告

GenerativeModel は一部の OpenMaaS モデルをサポートする場合がありますが、推奨されません。互換性を最大限に高めるため（特に Chat Completions）、OpenAI SDK を使用してください。

インストール

pip install openai google-auth

OpenAI SDK の認証

OpenAI SDK の API キーとして、Google Cloud OAuth アクセストークンを必ず使用してください。

import subprocess

def get_gcp_access_token():
    return subprocess.check_output(
        ["gcloud", "auth", "print-access-token"]
    ).decode("utf-8").strip()

メモ

Google Cloud アクセストークンは通常、1 時間後に期限切れになります。上記の get_gcp_access_token() 関数は、呼び出された時点で新しいトークンを取得します。長時間実行するアプリケーションでは、更新メカニズムを実装してください。詳しくは、アクセストークンの更新を参照してください。

設定（ベース URL）

• グローバルエンドポイント（グローバルな利用可能性が必要なほとんどのモデルで推奨）： https://aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/global/endpoints/openapi
• リージョナルエンドポイント： https://{REGION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{REGION}/endpoints/openapi

Python の例（OpenMaaS — Chat Completions）

完全なコードについては、scripts/openmaas_openai_sdk.py を参照してください。

ヒント

代替：環境変数 コードを更新する代わりに、シェルで環境変数を設定できます。

代替：環境変数 コードを更新する代わりに、シェルで環境変数を設定できます。

export OPENAI_BASE_URL="https://aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/global/endpoints/openapi"
export OPENAI_API_KEY="$(gcloud auth application-default print-access-token)"

次に、引数を指定せずにクライアントを初期化します：client = OpenAI()

Python の例（OpenMaaS — Completions API）

次のモデルは、レガシーの Completions API をサポートしています：zai-org/glm-5-maas、moonshotai/kimi-k2-thinking-maas、minimaxai/minimax-m2-maas、deepseek-ai/deepseek-v3.1-maas、および deepseek-ai/deepseek-v3.2-maas。

response = client.completions.create(
    model="deepseek-ai/deepseek-v3.2-maas",
    prompt="Once upon a time",
    max_tokens=100
)
print(response.choices[0].text)

Python の例（OpenMaaS — Embeddings）

# Verify specific Embedding Model ID on Model Garden (e.g., intfloat/multilingual-e5-small)
response = client.embeddings.create(
    model="intfloat/multilingual-e5-large-maas",
    input="The quick brown fox jumps over the lazy dog",
)
print(response.data[0].embedding)

代替：GenAI SDK

google-genai SDK は、vertexai バックエンド経由でも OpenMaaS モデルにアクセスできます。

完全なコードについては、scripts/openmaas_genai_sdk.py を参照してください。

重要

モデル ID の形式：GenAI SDK で OpenMaaS を使用する場合は、完全なパス publishers/PUBLISHER/models/MODEL（例：publishers/zai-org/models/glm-5-maas）を必ず使用してください。

レガシー：Agent Platform SDK（OpenMaaS）

OpenMaaS では、サポートされている場合、GenerativeModel も使用できます。

完全なコードについては、scripts/openmaas_vertexai_sdk.py を参照してください。

重要

モデル ID の形式：OpenMaaS で Agent Platform SDK を使用する場合は、 必ず完全なパスを指定してください：publishers/PUBLISHER/models/MODEL。

モデルのリファレンスと利用可能状況

ドキュメント： Agent Platform でオープンモデルを使用する

ヒント

制御性を高めるためのセルフデプロイ：MaaS で提供されていない専用ハードウェア （GPU／TPU）、保証された容量、または特定のリージョンへの配置が必要な場合は、 これらのモデルを Agent Platform エンドポイントにセルフデプロイできます。Model Garden でモデルを検索し、「Deploy」をクリックして マシンタイプを選択してください。デプロイのワークフローについては、agent-platform-deploy スキルを参照してください。また、セルフデプロイしたエンドポイントの呼び出し方については、 このスキルのセクション 4 を参照してください（上記の OpenMaaS パブリッシャー URL ではなく、専用エンドポイントの DNS で /chat/completions を使用してください）。

重要

推論のサンプルを探す：上記の一覧は出発点です。推論コードの確定版（特に Chat Completions のペイロード構造）については、以下の手順に従ってください。1. Agent Platform でオープンモデルを使用する の一覧を確認します。2. 使用するモデル（例：「DeepSeek-V3」）のリンクをクリックして、 Model Garden のページに移動します。3. Model Garden のページで**「Sample Code」または「Use this model」**ボタンを探し、そのモデルのバージョンに対応する正確な curl または Python コードを取得します。

メモ

この一覧は不完全です。サポートされているモデルの全一覧については、 Agent Platform でオープンモデルを使用する を参照してください。

モデルファミリー	モデル ID の例	ロケーション	備考
Llama 4	meta/llama-4-maverick-17b-128e-instruct-maas	us-east5
Llama 4	meta/llama-4-scout-17b-16e-instruct-maas	us-east5
Llama 3.3	meta/llama-3.3-70b-instruct-maas	us-central1
DeepSeek	deepseek-ai/deepseek-v3.2-maas	global	グローバルのみ
DeepSeek	deepseek-ai/deepseek-v3.1-maas	us-west2	US-West2 のみ
DeepSeek	deepseek-ai/deepseek-r1-0528-maas	us-central1
Qwen 3	qwen/qwen3-coder-480b-a35b-instruct-maas	global
Qwen 3	qwen/qwen3-next-80b-a3b-instruct-maas	global
Kimi	moonshotai/kimi-k2-thinking-maas	global
MiniMax	minimaxai/minimax-m2-maas	global
GLM	zai-org/glm-4.7-maas, zai-org/glm-5-maas	global

4. カスタムエンドポイント（調整済み Gemini、セルフデプロイした OSS LLM、従来のカスタムモデル）

このセクションでは、プロジェクトに属する Agent Platform エンドポイント上のモデルを呼び出す方法を説明します。つまり、 projects/.../endpoints/5875254126916403200 のような数値のリソース名を持つエンドポイントです。セクション 2 と 3 のパブリッシャー MaaS サーフェス（publishers/.../models/... または endpoints/openapi を呼び出すものであり、お客様のエンドポイント ID は使用しません）への呼び出しとは異なります。

重要

パブリッシャー MaaS とお客様のエンドポイントを混同しないでください。 セクション 3 の OpenMaaS の例（例：meta/llama-3.3-70b-instruct-maas）は、 /v1/projects/.../locations/.../endpoints/openapi にある共有パブリッパー URLを呼び出します。このセクションの手順では、/v1/projects/.../endpoints/<id> にあるお客様のエンドポイントを呼び出します。 Model Garden の「Deploy」で Llama／Gemma などのモデルをデプロイした場合（MaaS パブリッシャー製品ではありません）は、セクション 3 ではなく、このセクションに従ってください。 [!IMPORTANT]

アクティブなエンドポイントの検出と唯一の情報源：

• モデルまたはファインチューニング済み Gemini アダプターがデプロイされ、推論に利用できる状態かどうかを確認するには、次を実行します。

  gcloud ai endpoints list --project=<PROJECT_ID> --region=<REGION> --format=json.

• アクティブなサービングエンドポイントの唯一の正式な情報源は、gcloud ai endpoints list です。

• 過去の gcloud ai tuning-jobs list レコードにある履歴上の job.tunedModel.endpoint 識別子を当てにしないでください。これらのレコードが示すのは、チューニング中にエンドポイントが最初に作成された場所です。その後にエンドポイントが削除、デプロイ解除、または期限切れになった場合、アクティブではなくなっています。

• gcloud ai endpoints list が空の [] を返す場合、または要求されたファインチューニング済みモデルが一覧表示されたエンドポイントのいずれにもデプロイされていない場合は、そのリージョンでアクティブなエンドポイントが見つからなかったことをユーザーに直接伝え、処理を停止してください。履歴上のエンドポイントや削除済みのエンドポイントが利用可能だと決して捏造せず、ユーザーからの明示的な指示と新たな Tier R 確認プロンプトなしに、ベースモデルへ決して黙って切り替えないでください。

重要

呼び出し形式は、互いに独立した 2 つの軸で決まります。

軸 1 — モデルファミリーによって RPC メソッドとペイロードが決まります。

エンドポイントが提供するもの	メソッド	ペイロード
ファインチューニング済み Gemini モデル（Gemini のチューニング結果 — エンドポイントはすでにデプロイ済みです）	:generateContent	contents / generationConfig
セルフデプロイした OSS LLM（Llama、DeepSeek、Qwen、Gemma、Mistral など、Model Garden 経由でデプロイされたもの）	/chat/completions	OpenAI 互換の messages
レガシーのカスタムモデル（分類、回帰、カスタム学習、埋め込み）	:predict	instances / parameters

gcloud ai endpoints describe <ENDPOINT_ID> --region=<REGION> --format=json を実行し、deployedModels[].model を調べて判定します。 gemini を含む場合 → ファインチューニング済み Gemini、OSS のパブリッシャーに一致する場合 （meta/、google/gemma-、deepseek-ai/、qwen/ など）→ OSS LLM、 それ以外 → レガシーのカスタムモデルである可能性が高いです。

**軸 2 — エンドポイントの種類（共有か専用か）**によって URL のホストが決まります。

dedicatedEndpointEnabled	ホスト
false（デフォルト — 共有エンドポイント）	<REGION>-aiplatform.googleapis.com
true（専用エンドポイント。独自の DNS があります）	dedicatedEndpointDns の値（形式：<ENDPOINT_ID>.<REGION>-<PROJECT_NUM>.prediction.vertexai.goog）

専用エンドポイントには、共有の <REGION>-aiplatform.googleapis.com ホスト経由ではアクセスできません（Endpoint.dedicated_endpoint_enabled proto によれば、"専用エンドポイントを有効にすると、共有 DNS にリクエストを送信できなくなります"）。describe の出力で dedicatedEndpointDns を必ず確認してください。設定されている場合はそれをホストとして使用し、そうでない場合は共有ホストを使用します。

両方のホストで、パスは常に /v1/projects/.../locations/.../endpoints/<id>/... です。 /v1/（GA）と /v1beta1/（ベータ）はどちらも同じバックエンドにルーティングされます。このスキルのレシピでは /v1/ を使用します。公開されている Gemma デプロイメントノートブック では引き続き /v1beta1/ が使われていますが、こちらも機能します。

4a. REST のレシピ — 調整済み Gemini モデル

Gemini のチューニング結果は、常にデプロイ済みのエンドポイントです。 共有ホスト上で :generateContent にアクセスできます。

PROJECT_ID=my-project
ENDPOINT_ID=5875254126916403200
REGION=us-central1
TOKEN=$(gcloud auth application-default print-access-token)

curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/endpoints/${ENDPOINT_ID}:generateContent" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Hello! Introduce yourself briefly."}]}
    ],
    "generationConfig": {
      "temperature": 0.2
    }
  }'

警告

maxOutputTokens を設定する場合は、思考モデルに十分な値を設定してください。 Gemini 2.5 Pro（および思考機能を備えたその他のモデル）は「思考」トークンを出力し、ユーザーに表示されるテキストよりも前に maxOutputTokens の上限にカウントされます。上限が小さい場合（例：100）、予算が思考トークンだけで消費され、レスポンスの text パーツが空でも、usageMetadata.candidatesTokenCount はゼロ以外になります。

出力の長さを制限する必要がない場合は、maxOutputTokens を完全に省略し、モデルが必要なだけ出力できるようにしてください。設定する場合は、チャットのような用途では >= 512、段落の出力では >= 1024 にしてください。レスポンスに text コンテンツがなく、finishReason: "MAX_TOKENS" が表示される場合は、上限が低すぎます。

4b. REST のレシピ — セルフデプロイした OSS LLM（Llama、DeepSeek、Qwen、Gemma など）

セルフデプロイした OSS LLM は、デプロイの設定（作成時の dedicated_endpoint_enabled）に応じて、共有エンドポイントまたは専用エンドポイントで稼働します。以下のレシピでは、describe の出力にある dedicatedEndpointDns を確認することで、どちらの場合にも対応します。

PROJECT_ID=my-project
ENDPOINT_ID=5875254126916403200
REGION=us-central1
TOKEN=$(gcloud auth application-default print-access-token)

# Step 1: discover host. dedicatedEndpointDns is empty for shared endpoints.
DEDICATED_DNS=$(gcloud ai endpoints describe "$ENDPOINT_ID" \
  --project="$PROJECT_ID" --region="$REGION" \
  --format="value(dedicatedEndpointDns)")

if [ -n "$DEDICATED_DNS" ]; then
  HOST="$DEDICATED_DNS"
else
  HOST="${REGION}-aiplatform.googleapis.com"
fi

# Step 2: call /chat/completions. Path is identical for both hosts.
curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://${HOST}/v1/projects/${PROJECT_ID}/locations/${REGION}/endpoints/${ENDPOINT_ID}/chat/completions" \
  -d '{
    "messages": [
      {"role": "user", "content": "Hello! Introduce yourself briefly."}
    ]
  }'

メモ

• max_tokens（maxOutputTokens ではありません）を使用します。これは Vertex ではなく OpenAI 互換の用語です。モデルが必要なだけ出力できるようにするには省略し、出力を制限する必要がある場合にのみ明示的に設定してください。
• OpenAI 形式のペイロードにある "model" フィールドは、エンドポイントへのデプロイでは省略するか、"" に設定できます。リクエストを処理するモデルは、エンドポイントによってすでに決まっています。
• 同じエンドポイントでは、/completions（従来のテキスト補完）と、埋め込みモデル用の /embeddings も利用できます。
• 推論モデル（DeepSeek-R1、Kimi-K2-Thinking、GLM-5 の各種モデルなど）は、最終回答よりも前に思考トークンを出力し、これらも max_tokens の上限にカウントされます。これはセクション 4a の Gemini 2.5 Pro と同じ問題です。max_tokens を設定して choices[0].message.content が空、または finish_reason: "length" になる場合は、値を大きくする（チャットでは >= 1024、より長い思考の連鎖では >= 2048）か、省略してください。

Python での同等の例（OpenAI SDK） — 公開されている Gemma のデプロイ用ノートブックと同じパターンです。

import google.auth
from google.auth.transport.requests import Request
import openai

from google.cloud import aiplatform

PROJECT_ID = "my-project"
ENDPOINT_ID = "5875254126916403200"
REGION = "us-central1"

aiplatform.init(project=PROJECT_ID, location=REGION)
endpoint = aiplatform.Endpoint(
    f"projects/{PROJECT_ID}/locations/{REGION}/endpoints/{ENDPOINT_ID}"
)
endpoint_resource_name = endpoint.resource_name  # full projects/.../endpoints/<id>
dedicated_dns = endpoint.gca_resource.dedicated_endpoint_dns  # empty if shared

host = dedicated_dns if dedicated_dns else f"{REGION}-aiplatform.googleapis.com"
base_url = f"https://{host}/v1/{endpoint_resource_name}"

import subprocess

token = subprocess.check_output(
    ["gcloud", "auth", "print-access-token"]
).decode("utf-8").strip()

client = openai.OpenAI(base_url=base_url, api_key=token)
response = client.chat.completions.create(
    model="",  # endpoint determines the served model
    messages=[{"role": "user", "content": "Hello! Introduce yourself briefly."}],
    # Omit max_tokens to let the model emit as much as it wants. Set it
    # only if you need to cap output length (see notes above).
)
print(response.choices[0].message.content)

デプロイ後にも同じパターンを使用する agent-platform-deploy スキルのセクション 4「デプロイの確認」も参照してください。

4c. REST のレシピ — 従来の :predict（カスタムモデル／分類／埋め込み）

4b と同じホストの検出ロジックを使用します（dedicatedEndpointDns に基づき、共有または専用）。

DEDICATED_DNS=$(gcloud ai endpoints describe "$ENDPOINT_ID" \
  --project="$PROJECT_ID" --region="$REGION" \
  --format="value(dedicatedEndpointDns)")
HOST=${DEDICATED_DNS:-${REGION}-aiplatform.googleapis.com}

curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://${HOST}/v1/projects/${PROJECT_ID}/locations/${REGION}/endpoints/${ENDPOINT_ID}:predict" \
  -d '{
    "instances": [{"key": "value"}],
    "parameters": {}
  }'

instances の正確な形式はモデルによって異なります。デプロイしたモデルのドキュメント、またはそのモデルのデプロイ元である Model Garden のカードを参照してください。

4d. Python（Vertex AI SDK）— 調整済み Gemini モデル

from google import genai
import google.auth

_, project_id = google.auth.default()
client = genai.Client(vertexai=True, project=project_id, location="us-central1")

ENDPOINT_ID = "5875254126916403200"
response = client.models.generate_content(
    model=f"projects/{project_id}/locations/us-central1/endpoints/{ENDPOINT_ID}",
    contents="Hello! Introduce yourself briefly.",
    config={"temperature": 0.2},  # add max_output_tokens only if you need a cap
)
print(response.text)

5. トラブルシューティングと一般的なエラーコード

429：リソース枯渇

• 原因：OpenMaaS と Gemini の各モデルは、**Dynamic Shared Quota（DSQ）**を使用します。リソースはプールされ、利用状況に応じて動的に割り当てられます。429 エラーは共有プールが一時的に枯渇していることを示します。必ずしもお客様のプロジェクト固有の割り当て上限に達したことを意味するわけではありません（ただし、その可能性もあります）。
• 解決策：厳密な指数バックオフと再試行の戦略を実装してください。
• 高スループット：高スループットまたは確実な容量が必要な本番ワークロードには、**Provisioned Throughput（PT）**を検討してください。
• 重要：通常のクラウドの手続き（Cloud Console）による割り当て上限の引き上げは、DSQ の制約には適用されません。
• ドキュメント： 割り当て上限と制限（DSQ）

400：ユーザー検証エラー

• 原因：リクエスト形式が無効、サポートされていないパラメーター、または Model ID が正しくありません。
• 対応：リクエストのペイロードとパラメーターを再確認してください。Model ID と Region が正しいことを確認してください。
• カスタムエンドポイント：セクション 4 の判断表に従って、適切なメソッドとホストを選択してください。
  • チューニング済み Gemini に対して :predict を呼び出した場合 → :generateContent に切り替えてください （セクション 4a）。エラーには「Required instances format mismatch」と表示されます。
  • OSS LLM（Llama／DeepSeek／Qwen／Gemma など）に対して :generateContent または :predict を呼び出した場合 → /chat/completions に切り替えてください （セクション 4b）。エラーは 404、405、または「method not allowed」の場合があります。
  • レガシーまたはカスタムトレーニング済みモデルに対して :generateContent または /chat/completions を呼び出した場合 → :predict に切り替えてください（セクション 4c）。
• 共有ホストで専用エンドポイントに接続した（またはその逆）場合：
  • 症状：DNS 解決エラー（Could not resolve host）または 404。
  • 原因：専用エンドポイントは <REGION>-aiplatform.googleapis.com でトラフィックを受け付けません。また、専用 DNS（*.prediction.vertexai.goog）は dedicatedEndpointEnabled が true の場合にのみ存在します。
  • 対応：gcloud ai endpoints describe ... --format=json を再確認し、 dedicatedEndpointDns フィールドを確認してください。値が空でない場合に限り、その値を使用してください（セクション 4b／4c のホスト検出スニペットに従ってください）。

Gemini デプロイ済みエンドポイントで応答テキストが空になる

• 原因：maxOutputTokens の値が低すぎます。Gemini 2.5 Pro などの思考モデルは「thoughts」トークンを出力し、これらはユーザーに表示されるテキストよりも先に予算にカウントされます。上限が小さい（例：100）と、予算全体が思考に使われ、応答の text パーツは空になりますが、usageMetadata.candidatesTokenCount はゼロ以外で、finishReason: "MAX_TOKENS" になります。
• 対応：maxOutputTokens を省略して（モデルが必要なだけ出力できるようにする）、またはチャット用途では 512 以上、長めの出力では 1024 以上に増やしてください。詳細はセクション 4「カスタムエンドポイント」を参照してください。

404：見つかりません／モデルを利用できません

• 原因：モデルが有効になっていないか、指定されたプロジェクトまたはリージョンでは利用できません。
• 対応：
  1. ロケーションの利用可否を確認する：
     • OpenMaaS：モデルがお使いのリージョンで利用できることを確認してください。ロケーション別モデルの利用可否を参照してください。
     • Gemini：
       • 信頼できる情報源：正式な一覧については、必ず Gemini モデルのロケーション を確認してください。
       • プレビュー版モデル：プレビュー版モデル（例：Gemini 3.1、実験版）は、多くの場合 us-central1 または global リージョンでのみ利用できます。
       • 安定版モデル：（例：Gemini 2.5 Pro）は us-central1、europe-west4、およびその他多数のリージョンで利用できます。
       • 重要：404／400 エラーが発生した場合は、クライアントのロケーションを us-central1 または global に切り替えてみてください。
  2. Llama モデルを有効にする：Llama 3.3 と Llama 4 は、使用前に Model Garden でモデルを有効にする必要があります。Model Garden に移動し、モデルカード（例：「Llama 3.3 API Service」）を検索して、有効にするをクリックしてください。その後にのみ、推論リクエストを送信できます。