agent-platform-inference

Agent Platform GenAI 推理技能

此技能提供使用生成式 AI 模型时，对 Google Cloud Agent Platform 进行身份验证和连接的说明。涵盖：

• 第一方发布商模型（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）
   • 代表用户执行模型推理之前，必须通过交互方式提供“是”/“否”选项以供确认， 防止产生意外费用或消耗配额。
   • 确认卡片中的必填字段：确认提示必须清楚说明计划执行的推理，并明确列出以下所有参数：
     • 项目 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）。 未明确列出这些参数的自然语言转述是不够的。
   • 同轮限制：在展示确认提示的同一轮中，不得执行推理脚本或命令。停止并等待用户回复；只有在用户明确回复“是”/表示同意后才可执行。
   • 黄金标准示例：

     我将使用以下参数执行模型推理。请在我继续之前确认这些信息：

     • 项目 ID：my-project
     • 区域：us-central1
     • 模型 ID：gemini-2.5-pro
     • SDK：Google GenAI SDK（google-genai）
     • 输入提示词：“用 3 句话概述《哈姆雷特》的情节”

     是否确认？[是/否]

   • 执行后的响应依据（关键）： 收到用户明确批准并通过 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 凭据进行身份验证，并配置有效的 Application Default Credentials（ADC），以便访问 Agent Platform：

   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 模型：请参阅 [Gemini 模型][gemini-models-docs]，了解有效的模型 ID 和区域。 * 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 运行 Python 代码（例如，编写并运行使用 google-genai、openai 或 vertexai 的 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 模型]。
   • OpenMaaS（例如，deepseek-ai/*、meta/llama-*、qwen/*）-> 首选：OpenAI SDK（openai）。转到 [2. OpenMaaS 模型]。
   • 自定义端点（数字端点 ID projects/.../endpoints/<id>）-> 转到 [4. 自定义端点]。

3. 故障排除：用户是否报告了错误（429 Resource Exhausted、 400 User Validation、404 Not Found、因令牌限制导致响应为空等）？

   • 是 -> 转到 [5. 故障排除和常见错误代码]。
   • 否 -> 提供包含所有必填字段（项目 ID、区域、模型 ID、SDK、输入提示词）的 Tier R 确认提示，等待用户 确认，然后通过 Python SDK 执行。

0.5 发布方端点的区域可用性检查（Gemini + LoRA 基础模型）

说明

如果符合以下任一情况，请跳过本节：

• 用户调用的是自定义端点（§4）——在数字型 projects/.../endpoints/<id> 上提供服务的调优 Gemini 模型、自行部署的 OSS 大模型（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 搜索、训练语料中的知识或发布方文档来判断可用性——区域可用性经常变化，有依据的文本也可能过时或不准确。

只探测用户指定的确切模型和区域。不要探测其他模型作为“对照”——你无法根据模型 B 的状态推断模型 A 是否可用，因为另一个模型本身可能由于无关原因而无法在参考区域使用。

对于一方 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）

使用标准 OpenAI SDK 和 Agent Platform 端点。此方案非常适合跨平台兼容。

完整代码请参阅 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（模型即服务）模型，强烈推荐使用标准 OpenAI SDK 和专用的 Vertex AI 端点。

警告

GenerativeModel 可以支持部分 OpenMaaS 模型，但不建议这样做。为获得最佳兼容性（尤其是使用 Chat Completions 时），请使用 OpenAI SDK。

安装

pip install openai google-auth

OpenAI SDK 身份验证

必须使用 Google Cloud OAuth 访问令牌作为 OpenAI SDK 的 API 密钥。

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。

提示

替代方案：环境变量 可以在 Shell 中设置环境变量，而不必修改代码。

替代方案：环境变量 可以在 Shell 中设置环境变量，而不必修改代码。

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 格式：对于使用 OpenMaaS 的 GenAI SDK，必须使用完整路径：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 Endpoints。在 Model Garden 中搜索模型并点击“Deploy”以选择 机器类型。有关部署工作流，请参见 agent-platform-deploy 技能；有关如何调用由此生成的 自行部署端点，请参见本技能的第 4 节（在专用端点 DNS 上使用 /chat/completions，而不是上方的 OpenMaaS 发布方 URL）。

重要

查找推理示例：上方列表仅供参考。要获取权威的推理代码片段（尤其是 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	仅限美国西部 2 区域
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 大模型、旧版自定义模型）

本节介绍如何调用属于你项目的 Agent Platform Endpoint 上的模型，即资源名称为数字形式，例如 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 确认提示的情况下，悄悄改用基础模型。

重要

两个相互独立的维度决定调用形式：

维度 1 — 模型系列决定 RPC 方法和载荷：

端点提供的模型	方法	载荷
微调后的 Gemini 模型（Gemini 微调的产物——端点已为你部署）	:generateContent	contents / generationConfig
自行部署的 OSS 大模型（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 大模型； 否则 → 可能是旧版自定义模型。

**维度 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："Once you enabled dedicated endpoint, you won't be able to send request to the shared DNS"）。务必检查 describe 输出中的 dedicatedEndpointDns：如果已设置，就将其用作主机；否则使用共享主机。

路径始终为 /v1/projects/.../locations/.../endpoints/<id>/...，两个主机均如此。 /v1/（GA）和 /v1beta1/（beta）都会路由到同一后端；本技能中的示例使用 /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。如果看到 finishReason: "MAX_TOKENS" 且响应中没有 text 内容，说明上限太低。

4b. REST 配方 — 自行部署的 OSS 大模型（Llama、DeepSeek、Qwen、Gemma 等）

自行部署的 OSS 大模型可能使用共享或专用端点，具体取决于部署配置（创建时的 dedicated_endpoint_enabled）。下面的配方会检查描述输出中的 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）——这是 OpenAI 兼容的参数名称，并非 Vertex 的名称。完全省略该参数可让模型按需输出；仅在需要限制输出时才显式设置。
• 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 模型使用动态共享配额（DSQ）。 资源会根据可用情况动态汇集和分配。429 错误表示共享资源池暂时耗尽，并不一定意味着你的特定项目配额已用尽（但也有这种可能）。
• 解决方案：实施严格的指数退避与重试策略。
• 高吞吐量：对于需要高吞吐量或保证容量的生产工作负载，请考虑使用预配吞吐量（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 的流量；只有在 dedicatedEndpointEnabled 为 true 时，才会存在专用 DNS （*.prediction.vertexai.goog）。
  • 操作：重新检查 gcloud ai endpoints describe ... --format=json 中的 dedicatedEndpointDns 字段；仅当该字段非空时使用其值（参见 第 4b/4c 节中的主机发现代码片段）。

Gemini 部署端点返回空响应文本

• 原因：maxOutputTokens 设置过低。Gemini 2.5 Pro 和其他 思考模型会生成计入预算的“思考”令牌，且这些令牌会在任何用户可见文本生成 之前消耗预算。上限较低时（例如 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”），然后点击 启用。之后才能发送推理请求。