agent-platform-inference

Agent Platform GenAI 推理技能

本技能提供身份验证和连接到 Google Cloud Agent Platform 以使用生成式 AI 模型的说明。涵盖第一方（Gemini）和第三方（OpenMaaS）模型。

安全与确认层级（关键）

在执行任何命令或脚本之前，必须根据请求的操作遵守以下安全层级。（本技能为只读；其他安全层级已省略）：

1. 层级 R：只读/推理（client.models.generate_content、client.chat.completions.create、client.completions.create、client.embeddings.create）
   • 在代表用户执行模型推理之前，需要交互式确认，提供“是”/“否”选项，以防止意外消耗费用或配额。确认提示必须清晰说明提议的推理执行及其关键参数（例如，目标模型 ID、SDK 选择、输入提示）。仅用自然语言复述而不指定参数是不够的。
   • 同轮限制：不要在呈现确认提示的同一轮中执行推理脚本或命令。停止并等待用户回复；仅在用户明确回复“是”/批准后执行。
   • 黄金标准示例：

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

     • 模型 ID：deepseek-ai/deepseek-v3.2-maas
     • SDK：OpenAI SDK（通过 Vertex AI 端点）
     • 输入提示：“解释量子计算的概念...”
       您确认吗？[是/否]

阶段 0：环境设置

关键：在运行 scripts/ 目录中的任何 Python 示例脚本（例如 scripts/openmaas_openai_sdk.py）之前，必须按照以下步骤确保环境正确初始化：

1. Google Cloud 身份验证：使用您的 Google Cloud 凭据进行身份验证，并配置活动的应用程序默认凭据（ADC）以访问 Agent Platform：

   gcloud auth login
   gcloud auth application-default login
   

2. 启用 API（如果尚未启用）：

   gcloud services enable aiplatform.googleapis.com
   

3. 虚拟环境：创建并激活专用的本地虚拟环境：

   python3 -m venv .venv
   source .venv/bin/activate
   

4. 安装依赖：安装所需的 SDK：

   pip install -r scripts/requirements.txt
   

5. 验证设置（可选）：一次性运行所有示例脚本以验证环境是否端到端正常工作：

   ./scripts/verify_all.sh
   

6. 执行：建议用户每次执行本技能的 Python 代码片段时，必须确保此虚拟环境已激活。

<!-- disableFinding(LINE_OVER_80) -->

[!IMPORTANT]
关键：模型 ID 和可用性

• Gemini 模型：请参阅 Gemini 模型 获取有效的模型 ID 和区域。
• OpenMaaS 模型：请参阅 在 Agent Platform 上使用开放模型 了解 Llama、DeepSeek、Qwen 等。
• 不完整列表：本技能中列出的模型 ID 仅为示例，可能不完整或已过时。
• 操作：在生成代码之前，始终使用上述链接验证模型 ID 和区域。

<!-- enableFinding(LINE_OVER_80) -->

工作流决策树

1. 模型系列识别：用户是否指定了要调用 Gemini（第一方）模型还是 OpenMaaS（第三方，例如 Llama、DeepSeek、Qwen）模型？

   • 否 -> 询问用户想要使用哪个模型系列。如果他们提供了具体的模型名称，则从名称推断系列。
   • 是 -> 进入步骤 2。

2. SDK 选择：用户想要使用哪个 SDK？

   • Gemini + GenAI SDK（Gemini 首选） -> 转到 [1. Gemini 模型]。
   • Gemini + 旧版 Vertex AI SDK -> 转到 [1. Gemini 模型]。
   • OpenMaaS + OpenAI SDK（OpenMaaS 首选） -> 转到 [2. OpenMaaS 模型]。
   • OpenMaaS + GenAI SDK -> 转到 [2. OpenMaaS 模型]。
   • 不确定 -> 默认使用所选系列的首选 SDK。

3. 故障排除：用户是否报告了错误（429 Resource Exhausted、400 User Validation、404 Not Found 等）？

   • 是 -> 转到 [3. 故障排除与常见错误代码]。
   • 否 -> 继续执行步骤 2 中的 SDK 选择。

1. Gemini 模型

对于 Gemini 模型（例如 gemini-2.5-pro、gemini-3-flash-preview），GenAI SDK（google-genai）是首选方法。旧版 vertexai SDK 仍受支持，但新项目推荐使用 GenAI SDK。

[!IMPORTANT]
预览模型（包括 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（聊天补全）

使用标准的 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 模型

2. OpenMaaS 模型（Llama、DeepSeek、Qwen 等）

对于 OpenMaaS（模型即服务）模型，强烈推荐的方法是使用标准的 OpenAI SDK 配合特定的 Vertex AI 端点。

[!WARNING]
虽然 GenerativeModel 可以支持某些 OpenMaaS 模型，但不鼓励这样做。为了获得最佳兼容性（尤其是聊天补全），请使用 OpenAI SDK。

安装

pip install openai google-auth

OpenAI SDK 的身份验证

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

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

def get_gcp_access_token():
    creds, _ = google.auth.default()
    creds.refresh(Request())
    return creds.token

[!NOTE]
Google Cloud 访问令牌通常在一小时后过期。上面的 get_gcp_access_token() 函数在调用时获取一个新的令牌。
<!-- disableFinding(LINE_OVER_80) -->
对于长时间运行的应用程序，您需要实现刷新机制。详情请参阅刷新访问令牌。
<!-- enableFinding(LINE_OVER_80) -->

配置（基础 URL）

<!-- disableFinding(LINE_OVER_80) -->

• 全局端点（推荐用于需要全局可用性的模型）：
  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
  <!-- enableFinding(LINE_OVER_80) -->

Python 示例（OpenMaaS - 聊天补全）

完整代码请参见 scripts/openmaas_openai_sdk.py。

[!TIP]
替代方案：环境变量
您可以在 shell 中设置环境变量，而不是更新代码。

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

然后无需参数即可初始化客户端：client = OpenAI()

Python 示例（OpenMaaS - 补全 API）

以下模型支持旧版补全 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 - 嵌入）

# 在 Model Garden 中验证具体的嵌入模型 ID（例如 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。

[!IMPORTANT]
模型 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。

[!IMPORTANT]
模型 ID 格式：对于使用 Agent Platform SDK 的 OpenMaaS，您必须使用完整路径：publishers/PUBLISHER/models/MODEL。

模型参考与可用性

文档：在 Agent Platform 上使用开放模型

[!TIP]
自行部署以控制：如果您需要专用硬件（GPU/TPU）、保证容量或 MaaS 未提供的特定区域部署，您可以将这些模型自行部署到 Agent Platform 端点。在 Model Garden 中搜索模型并点击“部署”以选择您的机器类型。

[!IMPORTANT]
查找推理示例：以上列表是起点。对于权威的推理代码片段（尤其是聊天补全负载结构）：

1. 查阅在 Agent Platform 上使用开放模型列表。
2. 点击您特定模型的链接（例如“DeepSeek-V3”）以访问其 Model Garden 页面。
3. 在 Model Garden 页面上查找 “示例代码” 或 “使用此模型” 按钮，以获取该特定模型版本的精确 curl 或 Python 代码。

[!NOTE]
此列表不完整。请参阅在 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

3. 故障排除与常见错误代码

429：资源耗尽

• 原因：OpenMaaS 和 Gemini 模型使用动态共享配额（DSQ）。资源被池化并根据可用性动态分配。429 错误表示共享池暂时耗尽，不一定表示您的特定项目配额已用尽（尽管也可能）。
• 解决方案：实施严格的指数退避和重试策略。
• 高吞吐量：对于需要高吞吐量或保证容量的生产工作负载，请考虑预配吞吐量（PT）。
• 重要提示：通过正常云流程（Cloud Console）增加配额不适用于 DSQ 限制。
• 文档：配额和限制（DSQ）

400：用户验证错误

• 原因：请求格式无效、不支持的参数或模型 ID 不正确。
• 操作：仔细检查您的请求负载和参数。验证模型 ID 和区域是否正确。

404：未找到/模型不可用

• 原因：模型未启用，或在指定的项目或区域中不可用。
• 操作：
  1. 检查位置可用性：
     • OpenMaaS：验证模型在您的区域中是否可用。请参阅按位置划分的模型可用性。
     • Gemini：
       <!-- disableFinding(LINE_OVER_80) -->
       • 权威来源：始终查看 Gemini 模型位置 以获取权威列表。
         <!-- enableFinding(LINE_OVER_80) -->
       • 预览模型：所有预览模型（例如 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”），然后点击启用。之后才能进行推理请求。