本指南汇集了在 xAI API 上使用 Grok 文本和推理模型取得最佳结果的实践，涵盖 API 选择、跨轮次保留推理、使用提示词缓存降低成本、请求配置，以及如何开展评测。

建议从以下设置开始：

设置	建议
API	使用 Responses API。Chat Completions 已弃用。
多轮历史	每轮都将加密推理内容传回 API。
提示词缓存	为每段对话使用独立的 `prompt_cache_key`，并且只在对话末尾追加内容。
推理强度	在每个请求中显式设置，并随每条结果记录。
流式传输与超时	优先使用流式传输。每个请求至少允许 900 秒；耗时较长的评测至少允许 1800 秒。
输出长度	将 `max_output_tokens` 设得高于预期最长回答，或保留默认的 128,000 token。
采样	将 `temperature` 设为 0.7、`top_p` 设为 0.95，避免偏离太多。

使用 Responses API

使用 Grok 推理模型时，请调用 Responses API（POST /v1/responses）。Chat Completions API 已弃用，而且没有传递模型加密推理的字段；经由它进行的多轮对话或工具调用都会丢失模型之前的推理。新能力也会先在 Responses API 上提供。

如果代码仍使用 Chat Completions，对照指南列出了各参数和响应字段在 Responses API 中的对应项。

每轮都传回加密推理

Grok 推理模型在回答前会先进行推理。Responses API 将推理内容作为加密的 reasoning 项，与消息和函数调用一起放在响应的 output 数组中返回。下一次请求将这些项原样放入 input，模型便能延续先前的推理过程。这会显著改善多轮对话与 Agent 循环的表现，因为每一步都建立在模型已经推导出的决策之上。

有两种方式在对话中保留推理：

通过 previous_response_id 串联请求，并保持 store 开启（默认设置）。SpaceXAI 会把推理随响应存储，并在后续请求中自动恢复。
设置 store: false，自行管理历史记录。用 include: ["reasoning.encrypted_content"] 请求推理内容，并把每个输出项追加到下一次请求的 input。这样每个请求都包含完整对话，可供记录和重放。

grok-4.7 的每次 Responses API 响应都会返回 reasoning.encrypted_content，无论 include 是否列出它。你的代码仍须在后续请求中传回该内容。完整说明见添加加密思考内容。

以下循环运行一段预设的多轮对话。它对每轮使用流式传输，保留加密推理，在整段对话中复用同一个 prompt_cache_key，并输出从缓存读取的输入 token 数量：

import os
import uuid

import httpx
from openai import OpenAI

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

conversation_id = str(uuid.uuid4())
history = [{"role": "system", "content": "You are a careful analyst. Answer concisely."}]

turns = [
    "A train leaves at 9:40 and arrives at 13:05. How long is the trip?",
    "The return trip is 20% faster. When does it arrive if it leaves at 15:00?",
]

for turn in turns:
    history.append({"role": "user", "content": turn})
    stream = client.responses.create(
        model="grok-4.7",
        input=history,
        reasoning={"effort": "high"},
        temperature=0.7,
        top_p=0.95,
        include=["reasoning.encrypted_content"],
        store=False,
        stream=True,
        extra_body={"prompt_cache_key": conversation_id},
    )
    response = None
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
        elif event.type in ("response.completed", "response.incomplete"):
            response = event.response
    print()
    # Append every output item, including reasoning items with encrypted_content.
    history.extend(response.output)
    print(f"Cached tokens: {response.usage.input_tokens_details.cached_tokens}")

import { randomUUID } from "node:crypto";
import OpenAI from "openai";

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

const conversationId = randomUUID();
const history = [
    { role: "system", content: "You are a careful analyst. Answer concisely." },
];

const turns = [
    "A train leaves at 9:40 and arrives at 13:05. How long is the trip?",
    "The return trip is 20% faster. When does it arrive if it leaves at 15:00?",
];

for (const turn of turns) {
    history.push({ role: "user", content: turn });
    const stream = await client.responses.create({
        model: "grok-4.7",
        input: history,
        reasoning: { effort: "high" },
        temperature: 0.7,
        top_p: 0.95,
        include: ["reasoning.encrypted_content"],
        store: false,
        stream: true,
        prompt_cache_key: conversationId,
    });
    let response;
    for await (const event of stream) {
        if (event.type === "response.output_text.delta") {
            process.stdout.write(event.delta);
        } else if (event.type === "response.completed" || event.type === "response.incomplete") {
            response = event.response;
        }
    }
    console.log();
    // Append every output item, including reasoning items with encrypted_content.
    history.push(...response.output);
    console.log(`Cached tokens: ${response.usage.input_tokens_details.cached_tokens}`);
}

import os
import uuid

from xai_sdk import Client
from xai_sdk.chat import system, user

conversation_id = str(uuid.uuid4())

client = Client(
    api_key=os.getenv("XAI_API_KEY"),
    timeout=900,
    # Routes every turn of this conversation to the same server for cache reuse.
    metadata=(("x-grok-conv-id", conversation_id),),
)

chat = client.chat.create(
    model="grok-4.7",
    reasoning_effort="high",
    temperature=0.7,
    top_p=0.95,
    store_messages=False,
    use_encrypted_content=True,
)
chat.append(system("You are a careful analyst. Answer concisely."))

turns = [
    "A train leaves at 9:40 and arrives at 13:05. How long is the trip?",
    "The return trip is 20% faster. When does it arrive if it leaves at 15:00?",
]

for turn in turns:
    chat.append(user(turn))
    for response, chunk in chat.stream():
        print(chunk.content, end="", flush=True)
    print()
    # Appending the response also appends its encrypted reasoning.
    chat.append(response)
    print(f"Cached tokens: {response.usage.cached_prompt_text_tokens}")

通过 previousResponseId 串联请求时，Vercel AI SDK 会自动携带加密推理；参见推理。

在 Agent 循环中保留推理

工具调用任务也需如此处理。模型调用函数时，推理项会出现在 output 数组中，与 function_call 并列。先追加整个数组，再追加你的 function_call_output 项，这样模型读取工具结果时就能沿着原有计划继续执行：

import json

# client, tools, task_prompt, run_tool, and conversation_id come from your code.
def stream_turn(input_items):
    stream = client.responses.create(
        model="grok-4.7",
        input=input_items,
        tools=tools,
        reasoning={"effort": "high"},
        temperature=0.7,
        top_p=0.95,
        include=["reasoning.encrypted_content"],
        store=False,
        stream=True,
        extra_body={"prompt_cache_key": conversation_id},
    )
    for event in stream:
        if event.type in ("response.completed", "response.incomplete"):
            return event.response

input_items = [{"role": "user", "content": task_prompt}]

while True:
    response = stream_turn(input_items)
    # Reasoning, messages, and function calls all go back in order.
    input_items.extend(response.output)

    calls = [item for item in response.output if item.type == "function_call"]
    if not calls:
        break

    for call in calls:
        result = run_tool(call.name, json.loads(call.arguments))
        input_items.append({
            "type": "function_call_output",
            "call_id": call.call_id,
            "output": json.dumps(result),
        })

print(response.output_text)

代码通常因以下做法丢失推理：

只提取 output_text 并作为普通 assistant 消息追加，丢弃其余推理和函数调用项。
在传回输出项之前修改、重排或过滤它们。应将其原样传回。
在轮次之间从另一种格式的记录重建对话，例如 Chat Completions 的 messages 数组。

对于较长的 Agent 循环，WebSocket 模式可降低每轮延迟，上下文压缩可使长对话保持在上下文窗口以内。

使用提示词缓存降低成本

xAI API 会自动缓存提示词，缓存命中的输入 token 费率低于普通输入 token；各模型缓存费率见价格。缓存从输入开头开始匹配：若一个请求以与先前请求完全相同的项目开头，匹配的前缀将由缓存提供，只需处理新增项目。多轮对话和 Agent 循环受益最大，因为每轮都会重新发送之前的全部内容。

为尽量提高缓存命中率：

为每段对话分配独立的 prompt_cache_key，并在每轮复用。缓存条目保存在各个服务器上，这个 key 可将整段对话的每轮请求路由到同一服务器。UUID 或应用的会话 ID 都适合。使用 xAI SDK 时，将相同值作为 x-grok-conv-id gRPC 元数据发送。
只在对话末尾追加内容。编辑、删除或重排之前的项目会破坏共同前缀，改动后的全部内容都按完整价格处理。
原样传回加密推理。对于推理模型，遗漏加密推理是缓存未命中的最常见原因。通过 previous_response_id 串联请求也能保持前缀不变。
把静态内容放在前面。输入开头的系统提示词、少样本示例和参考文档会形成每轮都能复用的稳定前缀。

检查每个响应中的 usage.input_tokens_details.cached_tokens。该值应随对话轮次增加；如果始终为 0，请确认每轮都发送相同的 prompt_cache_key，且之前的项目未变。缓存适用于流式传输和工具调用，但负载较高时条目可能被清除，因此不能保证命中。示例见哪些情况会破坏缓存。

配置推理模型请求

推理模型在响应前需要花费 token 和时间思考，因此推理强度、流式传输与超时、输出限制及采样参数都会影响结果。

在 Responses API 中，reasoning.effort 控制模型的推理量。支持的取值和默认值因模型而异：grok-4.7 默认为 "high"，grok-4.3 默认为 "low"，且还接受 "none"。每次请求都显式设置推理强度，避免默认值影响结果，并选用计划在生产环境使用的强度。如果成本或延迟重要，应比较不同强度，并权衡质量、token 用量和时间。各模型支持的值见 reasoning_effort 参数。

流式传输与超时

优先使用流式传输（stream: true）。流式响应会在模型工作时持续发送事件，避免长时间生成期间连接中断；最终的 response.completed 事件包含完整响应，包括需要传回的加密推理项。

按照本指南的示例，将客户端超时至少设为 900 秒。复杂问题下的高强度推理可能持续数分钟；Humanity's Last Exam（HLE）等耗时评测的单个请求可能超过 1800 秒。将超时设得高于预期最长请求时长，避免把慢请求记为失败。

输出长度

max_output_tokens 仅限制可见回答；推理和函数调用 token 不计入其中。未设置时默认为 128,000 token。上限过低会截断回答，因此应高于预期最长回答，并将 status: "incomplete" 的响应视为已截断。

采样参数

对于 POST /v1/chat/completions 和 POST /v1/responses，采样时的 temperature 最高按 1 处理，top_p 最高按模型默认值处理。当前 Grok 文本模型的默认 top_p 为 0.95。API 接受 0 到 2 的 temperature 和最高为 1 的 top_p；超过有效上限的值会按上限采样。Responses API 在响应中仍回显你发送的数值，包括超出上限的值。省略字段则使用模型对该字段的默认值。

在每个请求中显式设置这两个值，避免结果依赖服务器默认值；比较模型时，对每个模型使用相同的值。

错误、重试与速率限制

区分基础设施故障与模型失败。对 429 和 5xx 响应采用指数退避重试；对仍失败的请求继续重跑，直到获得响应。大规模任务应遵守团队的速率限制。

评测 Grok 模型

好的评测应告诉你模型在自身任务中的表现，而这种表现通常不同于公开排行榜上的分数。应用上述设置后，按以下实践设计并运行评测。

设计评测

先用可衡量的指标定义应用中的成功。“很好地回答支持问题”过于模糊，无法测试。可测试的定义是：“在 500 张工单样本中，至少解决 85%，不编造政策，中位延迟低于 20 秒。”大多数应用需要同时考量任务准确率、指令遵循、格式合规、安全性、延迟和成本等多个指标。

根据模型实际要处理的任务构建数据集。去除个人数据的生产日志最有代表性；再加入人工编写的边界案例、对抗性输入以及长篇或多轮示例。检查公开基准测试题是否可能出现在训练数据中；若问题依赖近期事件，还需考虑各模型的知识截止日期（grok-4.7 为 2026 年 5 月）。如果任务需要实时信息，启用网页搜索并直接评测该配置。

为每项指标选择成本最低且可靠的评分方式：

评分方式	适用场景	注意事项
代码	精确答案、单元测试、schema 验证、工具调用参数	因格式不符合预期而误拒正确答案
模型评判	开放式质量、评分标准、两两比较	位置偏差、偏好较长回答、与人工判断偏离
人工审查	校准其他评分方式、高风险或主观任务	成本、速度和审查者之间的分歧

使用模型评判时，提供包含各分数示例的具体评分标准，要求它先推理再评分，并在两两比较中随机排列回答顺序。大规模使用前，先在样本上测量它与人工标签的一致性。

公平地为各模型编写提示词。Grok 推理模型会先推理再回答，因此请直接说明任务、约束和输出格式。如果你曾针对其他模型调优提示词，在比较分数前，也应投入相近精力为 Grok 调优。

运行、测量与比较

推理模型并非确定性的，单次运行可能产生误导。每个测试项运行多次，报告均值和离散程度，并使用只要一次尝试正确就计为通过的 pass@k。模型之间的微小差异，只有在多次运行中稳定出现才值得采信。

如果必须排除持续失败的测试项，就要对所有被比较模型都排除该项，使它们在同一数据集上评分，并报告排除数量；只排除某一个模型的失败项会虚增其分数。

记录每个请求的完整响应，包括其 usage 对象。usage.output_tokens_details.reasoning_tokens 表示模型用于推理的 token 数；usage.input_tokens_details.cached_tokens 表示多少输入来自缓存；usage.cost_in_usd_ticks 给出每个请求的精确计费成本。结合实际耗时，可以比较每美元和每秒的质量。将 ticks 换算成美元的方法见成本追踪。每条结果都应记录模型名称、推理强度、采样参数、日期和评测框架版本，因为模型与框架都会变化。

报告结果前，请确认：

每个请求都使用 Responses API。
多轮和工具调用测试项原样延续加密推理。
已记录推理强度、采样参数、模型名称和评测框架版本，且被比较模型之间的设置一致。
失败请求已重试，排除项对所有模型一视同仁，截断响应已标记。

文本生成：Responses API、已存储的对话和加密思考内容
推理：推理强度、加密推理与推理摘要
流式传输：通过 Server-Sent Events 返回流式响应
提示词缓存：缓存工作原理及如何提高命中率
函数调用：定义工具和处理工具调用
与 Chat Completions 对比：从 Chat Completions 迁移

最后更新：2026 年 10 月 20 日

从写代码，到创作下一幕

Agent Plan & Coding Plan

Seedance 2.5

模型能力

最佳实践指南

使用 Responses API

每轮都传回加密推理

在 Agent 循环中保留推理

使用提示词缓存降低成本

配置推理模型请求

推理强度

流式传输与超时

输出长度

采样参数

错误、重试与速率限制

评测 Grok 模型

设计评测

运行、测量与比较