Grok Build · Sampler 采样层 —— HTTP 流式调用的幕后

Grok Build · Sampler 采样层 —— HTTP 流式调用的幕后

章节摘要:第三章结尾我们停在 shell 与 sampler 之间的那座桥上,看到了 sampler 吐出的统一事件如何被桥消费。本章我们跨过桥,深入 sampler 层的内部。Sampler 是 Grok Build 三层架构里最底层、离网络最近的一层,它的使命是:把一次模型推理请求的整个生命周期管理起来——发起 HTTPS 流式调用、把不同后端的原始响应格式统一成一套事件、处理重试与取消、维护配置的热更新。Sampler 这个名字容易让人误以为是「模型内部的采样解码」,其实它指的是「调用 API 完成一次采样」。本章会拆解 SamplerActor 的单线程命令循环加每请求并发 task 架构、SamplerConfig 的字段全景、SamplingEvent 这个统一事件枚举、三种 API 后端的 L2 transform、模型切换机制,以及重试、取消与 doom-loop 检测。

学习目标

阅读完本章,你应当能够:

1. 说明 SamplerActor 的「单线程命令循环 + 每请求并发 task」架构,理解这种取舍的动机。
2. 复述 SamplerConfig 的核心字段(model、temperature、top_p、context_window、api_backend 等)及其作用。
3. 列举 SamplingEvent 这个统一事件枚举的主要变体,说明它们如何被桥消费。
4. 说明三种 API 后端(responses、chat_completions、messages)的 L2 transform 如何把不同格式统一。
5. 理解模型切换机制(default_models.json、UpdateConfig 命令、models_manager 广播)。
6. 复述重试(RetryPolicy)、取消(CancellationToken)与 doom-loop 检测的原理。

核心概念速览

整章逻辑可浓缩为一句话:Sampler 把「网络与协议的复杂性」全部封装在底层,对上层只暴露一套统一的命令与事件,让 shell 不必关心用的是哪个模型后端、不必关心 HTTP 细节。

子章节导航

01 SamplerActor 架构

讲清 sampler 为何用「单线程命令循环 + 每请求并发 task」这种混合架构——命令处理串行化避免共享状态,实际请求并发跑支持多请求在飞。

02 SamplerConfig 字段全景

逐组讲解 SamplerConfig 的字段:采样核心(model、temperature、top_p、max_completion_tokens)、HTTP 传输、客户端身份、运行期注入、后端能力策略。

03 SamplingEvent 事件枚举

列出主要事件变体(StreamStarted、ChannelToken、ToolCallDelta、Completed、Failed、Retrying 等),说明每个的含义与桥如何消费。

04 三种 API 后端的 L2 transform

讲清 responses、chat_completions、messages 三种后端的原始格式差异,以及 L2 transform 如何把它们统一成 SamplingEvent。

05 默认模型与模型切换

讲清默认模型来源(default_models.json)、运行中切换模型的机制(UpdateConfig 命令、models_manager 广播)。

06 重试、取消与 doom-loop

拆解 RetryPolicy 的退避策略、CancellationToken 的协作式取消、doom-loop 检测如何防止 Agent 死循环。

子章节之间的逻辑关系

本章遵循「理解容器 → 看清配置 → 认识事件 → 理解适配 → 模型管理 → 可靠性」的认知路径:

Actor 架构 (01)  ──sampler 的状态容器与并发模型
   │
   ▼
配置字段 (02)   ──一次请求带什么参数
   │
   ▼
事件枚举 (03)   ──sampler 对外说什么
   │
   ▼
后端适配 (04)   ──如何统一不同后端
   │
   ▼
模型管理 (05)   ──默认模型与切换
   │
   ▼
可靠性 (06)     ──重试、取消、防死循环
   │
   ▼
第 5 章:工具系统,Agent 的双手
​

每一节都为下一节铺垫:不理解 Actor 架构,就看不懂配置如何被串行化更新;不看清配置,事件就缺乏语境;不认识事件,后端适配就无从挂靠;不理解后端适配,模型切换的多后端支持就难以理解;而可靠性机制建立在前面所有之上。

前置知识与后续延伸

前置知识:

• 第 3 章的 Agent 运行时,特别是 run_turn_via_sampler 桥
• 第 1 章的三层架构与端到端旅程
• 对 HTTP 流式响应(SSE、chunked transfer)的基本了解

本章为后续章节奠定的基础:

• SamplerConfig 的理解,是第 8 章 Headless 模式配置采样参数的基础
• SamplingEvent 的理解,让第 5 章工具调用的流式输出有完整语境
• 多后端支持,让第 6 章自定义模型集成(Bring-your-own-key、OpenAI 兼容端点)顺理成章
• doom-loop 检测,与第 7 章上下文压缩共同构成 Agent 的「自我保护」

若希望进一步了解 HTTP 流式响应与 SSE 协议,可参考 WHATWG 的 Fetch 标准与 SSE 规范;Rust 异步生态里,reqwest、tokio、futures 是理解 sampler 实现的相关依赖。