如何配置 API 密钥、选择模型端点并使用 xAI Grok API 实现函数调用

软件开发者将 xAI 的 Grok 模型接入应用程序的过程非常平滑，因为 xAI 平台不仅提供原生 SDK 与现代化 REST 端点，还完全兼容 OpenAI SDK 规范。Grok API 统一运行在 https://api.x.ai/v1 基础地址上，开发者只需配置标准的 Bearer Token 鉴权，即可自由调度旗舰级推理模型（如 grok-4.7）或低延迟代码模型（如 grok-build-0.1），并通过多轮函数调用（Function Calling）将 Grok 与本地数据库、企业微服务以及第三方 API 紧密结合。

本文为开发者提供从 API 密钥配置、模型与端点选型，到完整函数调用实现的操作指南。

一、配置 API 密钥与基础鉴权

调用 Grok API 的所有凭据均通过 xAI 控制台（https://console.x.ai）集中管理。

1. 生成 API 密钥

1. 访问并登录 xAI Console。
2. 在 Billing（账单）页面完成账户充值，确保账户内有可用 API 点数。
3. 进入 API Keys 管理页面（https://console.x.ai/team/default/api-keys），点击 Create API Key。
4. 立即复制生成的密钥字符串并妥善保存；控制台在关闭弹窗后将不再完整展示。

2. 配置环境变量

建议通过环境变量注入密钥，变量名通常约定为 XAI_API_KEY：

export XAI_API_KEY="xai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

在 Node.js 或 Python 项目中，可将其保存在根目录的 .env 文件内：

XAI_API_KEY=xai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3. 初始化客户端 SDK

由于 xAI 兼容 OpenAI 协议标准，开发者可直接使用熟悉的官方 xai-sdk、社区主流的 openai 客户端库，或前端领域的 Vercel AI SDK。

Python（使用 openai 官方库）：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

Python（使用原生 xai-sdk）：

import os
from xai_sdk import Client

client = Client(api_key=os.getenv("XAI_API_KEY"))

Node.js / TypeScript（使用 openai 库）：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
});

二、模型端点与架构选型

在构建实际系统时，开发者需要明确 HTTP 端点协议与具体模型代号之间的对应关系。

接口协议：/v1/responses 与 /v1/chat/completions

• https://api.x.ai/v1/responses（官方推荐现代化端点）： 专为智能体（Agent）工作流设计，原生支持复杂输入数组、基于 previous_response_id 的状态追踪、结构化输出以及与服务端搜索工具的联动。
• https://api.x.ai/v1/chat/completions（OpenAI 兼容端点）： 与业界通用 Chat Completions 规范完全对齐，现有项目仅需调整 baseURL 与 apiKey 即可实现无缝迁移。

文本与推理模型对比

补充说明：除上述语言模型外，xAI 还提供了多模态专用能力，包括实时双向语音 grok-voice-think-fast-2.0（Voice API）以及图像与视频生成模型 grok-imagine-image-2.0（Imagine API）。

三、实现函数调用（Function Calling / Tool Calling）

函数调用允许 Grok 在推理过程中按需调用外部服务，使模型从单纯的“回答者”转变为能够“操作工具”的智能体。

核心工作链路

1. 定义工具： 开发者在请求中声明包含 JSON Schema 规范的工具数组（包括 name、description 和 parameters）。
2. 模型决策： Grok 接收用户提问，判定是否需要调取外部数据或执行动作。
3. 返回调用请求： Grok 返回包含函数名和参数 JSON 的 tool_calls 对象，暂停生成。
4. 本地执行： 应用程序提取参数并在本地或服务端执行业务代码。
5. 回传结果并汇总： 将执行结果回传给 Grok，模型综合工具输出生成最终的用户回复。

端到端实现代码（Python + OpenAI 客户端）

以下示例演示如何在 responses 端点中定义一个账户查询工具，捕获 Grok 的调用指令，执行业务逻辑并回传数据：

import os
import json
from openai import OpenAI

# 1. 初始化客户端
client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

# 2. 声明工具定义（必须严格使用 JSON Schema 规范）
tools = [
    {
        "type": "function",
        "name": "fetch_user_account",
        "description": "根据用户账户 ID 查询客户资料、订阅套餐等级和当前账户状态。",
        "parameters": {
            "type": "object",
            "properties": {
                "account_id": {
                    "type": "string",
                    "description": "用户唯一识别码，例如 'usr_10294'"
                },
                "include_usage_stats": {
                    "type": "boolean",
                    "description": "是否同时拉取当前计费周期的用量数据",
                    "default": False
                }
            },
            "required": ["account_id"]
        }
    }
]

# 本地业务函数模拟
def execute_fetch_user_account(account_id: str, include_usage_stats: bool = False):
    return {
        "account_id": account_id,
        "name": "Alex Mercer",
        "tier": "Enterprise",
        "status": "Active",
        "usage_tokens": 1420500 if include_usage_stats else None
    }

# 3. 发送包含工具定义的用户提问
user_query = "请帮我查一下 usr_10294 用户的账户信息，看看他们是否处于有效的 Enterprise 套餐状态？"

response = client.responses.create(
    model="grok-4.7",
    input=[{"role": "user", "content": user_query}],
    tools=tools,
)

# 4. 解析响应并分发工具调用
for item in response.output:
    if item.type == "function_call":
        func_name = item.name
        func_args = json.loads(item.arguments)
        call_id = item.call_id
        
        print(f"模型触发了工具调用: {func_name}，参数为: {func_args}")
        
        if func_name == "fetch_user_account":
            tool_result = execute_fetch_user_account(**func_args)
            
            # 5. 将执行结果回传给模型继续推理
            followup = client.responses.create(
                model="grok-4.7",
                input=[{
                    "type": "function_call_output",
                    "call_id": call_id,
                    "output": json.dumps(tool_result)
                }],
                tools=tools,
                previous_response_id=response.id,
            )
            
            # 输出模型根据工具结果整合的最终回答
            for followup_item in followup.output:
                if followup_item.type == "message":
                    print("\n模型最终回复:\n", followup_item.content[0].text)

四、工程落地的关键限制与高级特性

在生产环境中落地 Grok 工具调用时，开发者需重点关注以下技术细节：

• 根节点对象限制： 在工具参数的 JSON Schema 中，根节点必须为 "type": "object"（或分支均为 object 的 oneOf/anyOf）。若根节点直接声明为基本标量或数组，API 将直接拒绝并抛出 HTTP 400 校验错误。
• 并行函数调用（Parallel Function Calling）： Grok 默认开启并行工具调用。面对复合问题时，模型可在单个响应中并发发起多个函数调用。如需串行控制，可在请求载荷中设置 parallel_tool_calls: false。
• 工具调用控制策略（tool_choice）：
  • "auto"（默认）：由模型自主决定回复文本还是调用工具。
  • "required"：强制模型必须至少触发一个工具。
  • "none"：临时禁用工具调用。
  • {"type": "function", "function": {"name": "fetch_user_account"}}：强制指定调用特定函数。
• 混合编排内置工具与自定义函数： Grok 支持混合工具流。开发者可以将客户端自定义函数与 xAI 托管的服务端内置工具（如 {"type": "web_search"} 网页搜索、{"type": "x_search"} X平台信息检索）同时声明。服务端内置工具由 xAI 基础设施自动执行，而自定义函数则平滑交由客户端本地代码处理。
• 完整块流式传输： 在启用流式响应（Streaming）时，Grok 的函数调用元数据在单一切片（Chunk）中完整返回，避免了跨切片拼接 JSON 字符串带来的解析复杂性与脆弱性。

参考资料

• Grok API Quickstart: Get Your API Key | SpaceXAI Docs
• Grok Models & Pricing | SpaceXAI Docs
• API Pricing | SpaceXAI Docs
• Function Calling | SpaceXAI Docs
• API Reference - REST API Reference | SpaceXAI Docs