固定Grok模型快照版本指南

grok-latest 是 xAI 发布周期的一个订阅。如果一个调优过的 prompt 挂在它后面，你需要的是一个带日期的快照，并确认你实际拿到的是快照。

xAI 在其模型列表上记录了这个方案。有些模型带有别名，这样用户会自动迁移到下一个版本，形式如下：

<modelname> — 别名指向最新稳定版本。

<modelname>-latest — 别名指向最新版本，文档说明适合想要最新功能的用户。

<modelname>-<date> — 特定模型版本，文档说明不会更新，适用于要求一致性的工作流。

xAI 建议大多数用户使用别名形式，这对于探索性工作是坦诚的建议，但对于一个输出会喂给解析器的生产 prompt 来说是错误的建议。带日期的形式是本文要讨论的。当前的模型列表上的例子包括 grok-4.20-0309-reasoning、grok-4.20-0309-non-reasoning 和 grok-4.20-multi-agent-0309 — 一个家族名、一个日期、以及相关的模式。

本文中的模型 slug 是写作时从 xAI 模型列表中摘录的例子。请阅读最新的列表而不是从任何文章（包括本文）中复制 slug — 原因之一是 2026 年 5 月 15 日有八个 slug 被废弃。

确认你实际在调用什么

搜索你的代码库中的别名，包括在配置和基础设施中，而不仅仅是应用代码。

rg -n "grok-latest|grok-4\.5-latest|grok-build-latest" \
   --glob '!node_modules'

列出密钥能访问的模型

models 端点是 OpenAI 风格的，它反映的是你的账户和区域，而不是文档。

curl -s https://api.x.ai/v1/models \
  -H "Authorization: Bearer $XAI_API_KEY" | jq -r '.data[].id' | sort

记录别名当前解析到哪个模型

这是你已验证过的版本，也是你要固定的版本。请求别名并读取响应内容。

curl -s https://api.x.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{"model":"grok-latest",
       "messages":[{"role":"user","content":"ping"}],
       "max_completion_tokens":5}' | jq -r '.model'

将带日期的 slug 放在唯一的地方

一个常量或一个环境变量。下一次迁移的成本与持有字面值的调用点数量成正比。

# .env
XAI_MODEL=grok-4.20-0309-reasoning

GROK_MODEL = os.environ["XAI_MODEL"]   # no default; fail loudly if unset

用固定版本发送一个请求并读取整个响应

确认它有回答，确认 model 字段，确认 usage 对象看起来符合预期。

curl -s https://api.x.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d "{\"model\":\"$XAI_MODEL\",
       \"messages\":[{\"role\":\"user\",\"content\":\"Reply with the single word: ok\"}],
       \"max_completion_tokens\":10}" \
  | jq '{requested: env.XAI_MODEL, served: .model, usage}'

重新检查固定版本可能改变过的参数

带日期的快照在上下文窗口、是否推理、以及它接受哪些参数方面都可能与别名不同 — stop 被推理模型拒绝，而非推理快照会忽略你原本依赖的 reasoning_effort。

用固定版本运行你的评估集一次

二十个保存好的 prompt 及预期输出形状足以捕捉格式契约被破坏的情况。保留结果；它们是你下一次对比模型的基准。

验证固定版本是否成立

一个不检查的固定版本只是一行注释。每个响应都带有一个 model 字段，说明实际是什么模型服务的，将其与你请求的内容比较就是全部的验证。

import os, logging
from openai import OpenAI

client = OpenAI(api_key=os.environ["XAI_API_KEY"],
                base_url="https://api.x.ai/v1")
MODEL = os.environ["XAI_MODEL"]

def complete(messages, **kwargs):
    r = client.chat.completions.create(
        model=MODEL, messages=messages,
        max_completion_tokens=kwargs.pop("max_completion_tokens", 1024),
        **kwargs)
    if r.model != MODEL:
        logging.warning("model substituted: requested=%s served=%s", MODEL, r.model)
    return r

这个警告是你和静默替换之间唯一的东西。xAI 文档化的废弃行为是将废弃的 slug 重定向到当前模型而不是让其失败，所以没有错误并不代表你的固定版本被正确使用了。

固定版本不冻结什么

带日期的 slug 固定的是权重。但它不能固定决定返回内容的所有因素，明确这两者的区别才能避免把固定版本误认为可复现性。

采样。 同一个固定模型配合同一个 prompt 仍然是从一个分布中采样。seed 文档说明用于确定性采样，附带说明重复请求应产生相似结果 — 相似，不是相同。如果需要字节级完全相同的输出，答案是缓存，而不是固定版本。

服务端工具。 如果你的请求启用了 web 或 X 搜索，检索到的内容每天按设计变化。模型被固定了；但它读取的内容没有被固定，而且通常对答案的影响更大。

注入的安全前缀。 xAI 发布的附加在 API 模型 slug 上的前缀，如默认 system prompt 页面中所述。那些在 xAI 那一侧的边界上，可以在没有新模型 id 的情况下被修订。

服务基础设施。 区域可用性因模型而异且可能变化，延迟、批处理行为和缓存命中率是服务本身的属性，而不是检查点的属性。

价格。 带日期的 slug 没有任何东西能固定它的成本。固定版本保护的是你的输出契约，而不是你的单位经济学。

这些都不是反对固定版本的理由。而是支持了解你买的是什么：固定版本消除了一大来源的无公告变更，而其他变更来源仍然存在 — 这正是为什么第七步的评估集不是可选的。

固定版本不是永久的

文档说明带日期的版本不会被更新。它没有说它会永远存在，而 2026 年 5 月的废弃包含了 grok-4-0709 — 一个带日期的快照。固定版本买来的是迁移之间的稳定性，而不是免于迁移。

所以把固定版本和两个习惯配对。关注 xAI 的开发者文档以获取废弃通知，因为日期在那里发布。还要保持上述替换警告连接到能够真正 page 人的东西，因为当固定版本到期时，那条日志行是你唯一的通知。

在固定版本旁边写下你固定它的原因也很有价值。六个月后常量只是一个字符串，而迁移时的问题不是"有没有更新的模型" — 总是有的 — 而是"这个版本做了什么我们依赖的事情"。一行注释说明原因（一个格式契约、一个调优的 prompt、一个审计要求）将下一次迁移从考古练习变成一个决策。

固定版本有真实的成本：你停止接收改进，且承担起主动迁移的工作量。当输出形状是负载关键时 — 下游解析器、模式契约、用户可见格式 — 或当一个 prompt 针对特定模型的特征进行过调优时，或当受监管的流程要求你说明哪个模型产生了输出时，这是值得的。

对于探索性工作、内部工具（答案改变只是被注意到）、或你宁愿让它自然改进的任何东西，这不值得。在这些情况下 xAI 的建议成立，别名是正确的选择。要避免的失败是：没有人决定过却对别名有生产依赖。每个提供商都存在同样的权衡 — OpenAI 的快照方案和 Anthropic 的带日期模型 id 用不同的命名回答同样的问题。