SamplerConfig 字段全景

SamplerConfig 字段全景

本节摘要:每一次模型调用都带着一组参数——用哪个模型、温度多少、top_p 多少、走哪个 API 后端、用什么认证方案、最多生成多少 token。这些参数集中在一个叫 SamplerConfig 的结构里(源码在 xai-grok-sampler/src/config.rs)。它是 sampler 层的「请求规格说明书」,既决定了一次请求的具体形态,也承载了 sampler 的行为策略(重试、超时、能力开关)。本节会按功能分组讲解 SamplerConfig 的主要字段,让你看清「一次模型调用到底带了多少信息」,以及这些信息如何影响 Agent 的行为。

一、SamplerConfig 的定位

在讲字段之前,先理解 SamplerConfig 在系统里的定位。

SessionActor 组装请求时:
    从 ChatStateActor 取历史与采样参数
    构造一个 SamplerConfig(或更新现有的)
    通过 sampler_handle.submit(request, config) 提交

SamplerActor 收到 Submit:
    把 config 传给 request_task
    request_task 用 config 决定:
        - 调哪个端点、用什么认证
        - 请求体里带什么参数(temperature 等)
        - 重试策略、超时、能力开关
​

SamplerConfig 是「请求的元数据」——它不直接是对话内容(那在 request 里),而是「这次对话要怎么被处理」的说明。

需要注意:SamplerConfig 与「请求体」不是一回事。请求体是发给模型 API 的 JSON,包含历史、工具定义、采样参数;SamplerConfig 是 sampler 内部的配置,有些字段会进请求体(如 temperature),有些只影响 sampler 行为(如 max_retries),有些是运行期注入的回调(如 bearer_resolver)。

二、字段分组

SamplerConfig 的字段较多,按功能分组讲解更清晰:

SamplerConfig
├── ① 采样核心(model、temperature、top_p、max_completion_tokens、api_backend)
├── ② HTTP 与传输(base_url、force_http1、extra_headers、idle_timeout)
├── ③ 认证(api_key、auth_scheme、bearer_resolver)
├── ④ 客户端身份(origin_client、client_identifier、deployment_id、user_id、client_version)
├── ⑤ 后端能力与策略(supports_backend_search、stream_tool_calls、doom_loop_recovery)
├── ⑥ 上下文与压缩(context_window、compactions_remaining)
├── ⑦ 运行期注入(serde skip,代码里设)
└── ⑧ 重试策略(RetryPolicy,常作为伴生字段)
​

下面逐组看。

三、采样核心字段

这一组字段直接决定「模型怎么生成」:

model(模型 ID)

字符串,指定用哪个模型,如 "grok-build"、"grok-4.20-multiagent"。这个 ID 是模型 API 端认识的标识,sampler 会原样放进请求体。默认值来自 default_models.json(下一节详谈)。

temperature(温度)

浮点数,控制生成的随机性。较高的温度(如 1.0)让输出更多样、更有创意;较低的温度(如 0.2)让输出更确定、更聚焦。Grok Build 默认是 0.7,在「有创意」与「可预测」之间取平衡。

top_p(核采样概率)

浮点数,另一种控制采样的方式。模型在每一步只从「累计概率不超过 top_p」的候选 token 里采样。top_p = 0.95(默认)意味着忽略概率尾部那些极不可能的 token,避免偶尔的「胡说八道」。

max_completion_tokens(最大生成 token 数)

可选整数,限制模型本次最多生成多少 token。这是防止「跑飞」的保护——如果模型因为某种原因无限生成,这个上限会强制截断。

api_backend(API 后端类型)

枚举,指定走哪种 API 协议:

• Responses:OpenAI 风格的 Responses API(Grok Build 默认)
• ChatCompletions:OpenAI 风格的 Chat Completions API
• Messages:Anthropic 风格的 Messages API

这个字段决定了 sampler 用哪个 L2 transform 解析响应(第 04 节详谈),也让 Grok Build 能兼容多种模型后端。

reasoning_effort(推理强度)

可选枚举,控制模型的「思考深度」。较高的推理强度让模型花更多「内部推理」再回答,适合复杂任务;较低则更快但可能不够深入。这是新一代「会思考的模型」的常见参数。

关键概念:采样核心字段是「模型生成行为」的旋钮。temperature 与 top_p 控制随机性,max_completion_tokens 控制长度,reasoning_effort 控制深度。Grok Build 的默认值(0.7 / 0.95)是在「编程任务」场景下平衡稳定性与灵活性的选择。

四、HTTP 与传输字段

这一组决定「请求怎么发」:

base_url(基础 URL)

字符串,模型 API 的基础地址,如 "https://api.x.ai/v1"。具体的端点路径(如 /responses、/chat/completions)由 api_backend 决定,拼接到 base_url 之后。

force_http1(强制 HTTP/1)

布尔值。某些网络环境(如部分代理)对 HTTP/2 支持不好,这个开关让 sampler 强制用 HTTP/1.1,提升兼容性。

extra_headers(额外请求头)

字符串映射,允许向请求注入额外的 HTTP 头。典型用途:

• 代理认证头
• 自定义追踪头(如 OpenTelemetry 的 traceparent)
• 企业网关要求的特殊头

注意:sampler 不查 URL,只把 extra_headers 原样加入请求。具体注入什么由 session 决定。

idle_timeout_secs(空闲超时)

可选整数。流式响应建立后,如果超过这个时间没有任何数据,认为连接「卡死」,触发超时错误(可重试)。这防止「请求挂起永远不返回」的情况。

五、认证字段

这一组决定「怎么证明身份」:

api_key(API 密钥)

可选字符串。若提供,sampler 用它作为 Bearer token 或 API Key 认证。这是最直接的认证方式,常用于 CI/脚本(通过 XAI_API_KEY 环境变量)。

auth_scheme(认证方案)

枚举,指定用什么认证方案。不同方案对应不同的请求头构造方式。

bearer_resolver(Bearer 解析器,运行期注入)

这是一个回调函数,在每次请求时动态解析 Bearer token。为什么需要动态解析?因为 token 会过期——解析器可以在每次请求时检查 token 是否快过期,必要时刷新。这实现了第 3 章讲的「认证失效自动刷新」。

注意 bearer_resolver 是运行期注入的(serde skip),不进配置文件,由 session 在构造 SamplerConfig 时设上。

六、客户端身份字段

这一组字段是「遥测与归属」用的,告诉服务端「这次调用来自哪个客户端」:

origin_client / client_identifier(客户端标识)

标识调用方是 GrokPager(交互 TUI)、Generic(通用)、还是其他。服务端可能据此提供不同体验或统计。

deployment_id(部署 ID)

企业部署的标识,用于多租户场景下的归属与配额。

user_id(用户 ID)

调用方的用户标识(通常从 OAuth2 凭据提取)。

client_version(客户端版本)

Grok Build 自身的版本号,用于服务端做版本兼容处理与统计。

这些字段不直接影响模型生成,但影响服务端如何处理请求(如限流策略、特性开关、计费归属)。

七、后端能力与策略字段

这一组反映「当前后端支持什么、sampler 该如何应对」:

supports_backend_search(支持后端搜索)

布尔值。某些后端支持「服务端托管的网络搜索」(模型在生成时可以联网查资料)。这个开关让 sampler 知道要不要处理 BackendToolCall 事件(后端托管的工具调用,如 web search)。

stream_tool_calls(流式工具调用)

布尔值。控制工具调用的参数是否流式增量返回。开启时,模型边生成边吐出工具参数片段(ToolCallDelta);关闭时,等工具调用完整再一次性返回。Grok Build 默认开启,以获得更流畅的体验。

doom_loop_recovery(死循环恢复策略)

可选策略,配置 doom-loop 检测的参数(如连续重复多少次触发、恢复动作是什么)。第 06 节详谈。

八、上下文与压缩字段

这一组与上下文窗口、压缩相关:

context_window(上下文窗口大小)

整数,模型的上下文窗口(如 500000)。sampler 本身不强制这个限制(那是服务端的事),但 session 用它做压缩决策——当历史接近这个窗口的一定比例,触发压缩。这个字段是「信息性」的,告诉 session「这个模型能装多少」。

compactions_remaining / compaction_at_tokens(压缩相关)

服务端有时会在响应头里返回「还能压缩多少次」「在多少 token 时建议压缩」之类的提示。这些字段记录这些服务端建议,sampler 转发给 session 参考。

九、运行期注入字段(serde skip)

有些字段不进配置文件,也不序列化,只在运行时由代码注入:

• attribution_callback(归因回调):401 错误时,回调让上层判断「这个 401 是不是认证问题」
• bearer_resolver(已提):每请求动态解析 token
• header_injector(头注入器):每请求动态注入头(如 OTel traceparent)

这些回调让 sampler 能与上层(session、遥测系统)协作,而不必把上层逻辑硬编码进 sampler。

十、RetryPolicy(重试策略)

SamplerConfig 通常伴生一个 RetryPolicy(有时作为 config 的一部分,有时单独传):

RetryPolicy {
    max_retries: u32,           # 最大重试次数
    backoff: BackoffStrategy,   # 退避策略(固定、线性、指数)
    retryable_errors: set,      # 哪些错误可重试
}
​

它决定 sampler 遇到错误时怎么重试。第 06 节详谈。

十一、把 SamplerConfig 放回流程

最后,把 SamplerConfig 放回一次完整请求的流程里,看它在哪里起作用:

SessionActor:
    构造/更新 SamplerConfig(model、temperature、认证、客户端身份...)
    submit(request, config) → SamplerActor

SamplerActor.handle_command(Submit):
    注册请求,派生 request_task,把 config 传过去

request_task:
    根据 config.api_backend 选 client 方法
    用 config.base_url + 认证构造 HTTP 请求
    把 config.model、temperature、top_p、max_completion_tokens 放进请求体
    注入 config.extra_headers + bearer_resolver 解析的 token
    发起请求,用 config.idle_timeout 监测
    遇到错误按 config.retry_policy 重试
    流结束后聚合响应
​

config 贯穿整个 request_task 的生命周期,每一个字段都在某个环节起作用。理解了 SamplerConfig,你就理解了「一次模型调用有多少旋钮可调」。

十二、配置来源与优先级

最后讲一下 SamplerConfig 的字段值从哪里来。这是一个分层优先级(第 7 章配置体系会详谈):

字段值来源(高 → 低):
1. CLI flag(如 -m/--model 显式指定)
2. 环境变量(如 XAI_API_KEY)
3. config.toml(用户配置)
4. RemoteSettings(远端下发的设置)
5. default_models.json(内置默认)
6. 代码硬编码的兜底默认
​

例如 model 字段,如果你在命令行用 -m grok-4.20-multiagent,它优先;否则看 config.toml 里有没有设;再否则用 default_models.json 的 "default": "grok-build"。

这种分层让默认值合理、用户可覆盖、企业可集中管理,是配置体系的常见模式。

本节要点回顾

1. SamplerConfig 是请求的元数据:决定「这次对话怎么被处理」,包含采样、传输、认证、身份、策略等。
2. 采样核心:model、temperature(默认 0.7)、top_p(默认 0.95)、max_completion_tokens、api_backend(responses/chat_completions/messages)、reasoning_effort。
3. HTTP 与传输:base_url、force_http1、extra_headers(代理/追踪头)、idle_timeout_secs。
4. 认证:api_key、auth_scheme、bearer_resolver(运行期注入,支持 token 动态刷新)。
5. 客户端身份:origin_client、deployment_id、user_id、client_version——遥测与归属用,不直接影响生成。
6. 后端能力策略:supports_backend_search、stream_tool_calls、doom_loop_recovery。
7. 上下文与压缩:context_window(信息性,session 据此决策压缩)、compactions_remaining。
8. 运行期注入:attribution_callback、bearer_resolver、header_injector(serde skip,代码设)。
9. RetryPolicy:max_retries、backoff、retryable_errors。
10. 配置来源分层:CLI > ENV > config.toml > RemoteSettings > default_models.json > 硬编码。

下一节,我们认识 sampler 对外的统一语言——SamplingEvent 事件枚举,看它有哪些变体,以及桥如何消费它们。