Google Cloud Vertex AI

本指南介绍如何在 Google Cloud Vertex AI / Gemini Enterprise Agent Platform 上设置和使用 Grok 模型。Vertex AI 中的 Grok 作为合作伙伴模型，可通过兼容 OpenAI 的 API（包括 Responses API 和 Chat Completions）访问。模型通过 Model Garden 启用。

前置条件

开始前，请确保具备：

• 已启用计费的有效 Google Cloud Platform（GCP）项目。

• 启用 API 和访问 Model Garden 的权限，例如 Vertex AI User 或 Project Editor 角色。

• 已在项目中启用 aiplatform.googleapis.com API 或等效的 Agent Platform API。

• 已安装 Google Cloud CLI（gcloud），并完成 Application Default Credentials（ADC）身份验证。

设置 ADC 和项目：

gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID

如果尚未启用所需 API，请执行：

gcloud services enable aiplatform.googleapis.com

安装所需软件包

pip install -U openai google-cloud-aiplatform

在 Model Garden 中启用 Grok 模型

1. 前往 Google Cloud Console 中的 Model Garden，或在控制台中搜索“Model Garden”。

2. 搜索“Grok”，或按发布者 xAI 浏览。

3. 选择所需的 Grok 模型，例如 Grok 4.2 或 Grok 4.3。

4. 查看模型卡中的能力、配额、价格和区域信息。

5. 点击 Enable 或 Deploy / request access（如果出现提示）。

6. 启用后，即可通过 API 调用该模型。

请使用 Model Garden 中显示的模型 ID。Vertex 模型名称可能包含发布者前缀，例如：

• xai/grok-4.7

模型可用性通常与 xAI API 一致，但受 Google Cloud 区域可用性和配额限制。

发起首次 API 调用

Vertex 上的 Grok 使用兼容 OpenAI 的接口，可以使用标准 openai Python 库。

身份验证

使用 Application Default Credentials。客户端可以读取 gcloud 身份验证或服务账号凭据。

你可能需要通过环境变量或直接在客户端中设置兼容 Vertex/OpenAI 的 base URL 或 endpoint。请使用模型卡或 Google Agent Platform 文档提供的精确 endpoint。

export OPENAI_BASE_URL="https://YOUR_VERTEX_ENDPOINT"

Responses API 示例

from openai import OpenAI

client = OpenAI()  # Uses ADC / env vars automatically

response = client.responses.create(
    model="xai/grok-4.7",
    input="Explain the advantages of using Grok for agentic workflows with parallel tool calling.",
    max_output_tokens=800,
)

print(response.output_text)

Chat Completions 示例

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="xai/grok-4.7",
    messages=[
        {
            "role": "user",
            "content": "Which city has a higher temperature right now, Boston or New Delhi, and by how much in Fahrenheit?",
        }
    ],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g., San Francisco, CA",
                        },
                        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                    },
                    "required": ["location"],
                },
            },
        }
    ],
    tool_choice="auto",
)

print(response.choices[0].message.content)

两个接口均支持流式传输，可获得更低延迟的体验。

函数调用与工具使用

Grok 在 Responses API 和 Chat Completions 接口中都擅长工具使用和并行函数调用。请为 tool 定义清晰、严格的 schema，使模型能够可靠地选择和调用它们。

数据保留与合规

Google Cloud 上 Grok 模型的数据保留和处理受 Google Cloud Vertex AI 政策约束。

• 许多部署支持 Zero Data Retention（ZDR）选项。

• 请查看具体模型卡和组织的 Google Cloud 数据治理设置。

• 可启用 Vertex AI 请求-响应日志，用于审计和调试。

详情请参阅 Google Cloud 关于 Vertex AI 数据治理和日志记录的文档。

功能支持

支持的能力包括：

• Responses API 和 Chat Completions。

• Function calling 和 tool 使用，包括并行 function calling。

• 推理模式 / 扩展思考。

• 结构化输出 / JSON 模式。

• 流式传输。

• 通过 Google Cloud 提供固定配额和承诺用量折扣。

上下文窗口因模型而异。请在 Model Garden 中查看具体 Grok 模型卡以了解当前限制。

全局、多区域和区域 endpoint

Vertex AI / Gemini Enterprise Agent Platform 提供灵活的 endpoint 路由：

• 全局 endpoint：通过动态路由实现最高可用性；推荐用于大多数场景。

• 区域 endpoint：通过指定区域路由，以满足严格的合规要求。

最佳实践

• 选择与延迟、吞吐量和推理要求匹配的 Grok 模型及 endpoint 配置。

• 优先使用 Application Default Credentials 和 IAM role，而不是长期有效的密钥。生产工作负载应使用服务账号。

• 在 Google Cloud Billing 和 Quotas 页面监控用量，并按需申请提高配额。

• 使用清晰的 tool schema 和明确的输出格式。

• 启用请求日志，并与 Google Cloud Monitoring / Logging 集成。

• 从直接调用 xAI API 迁移时，请更新 base URL、客户端配置和模型前缀。大多数 prompt 和 tool 定义只需少量更改即可迁移。

故障排查

如果可用，请先在 Google Cloud Console Playground / Model Garden interface 中开始，再转到代码。

后续步骤

• 在 Model Garden 中探索已启用的模型。

• 利用 Grok 的工具调用优势构建智能体应用。

• 与 Cloud Functions、Vertex AI Pipelines 等谷歌云服务集成。

• 查看完整的 xAI Grok 文档和 Model Card，了解 prompting 技巧与能力。