Rizzo Flow原原理析:为什么只读一个字母的logits,LLM就能输出类型化决策
Rizzo Flow原原理析:为什么只读一个字母的logits,LLM就能输出类型化决策
Rizzo Flow 是一个 100% 本地运行的开源项目:它把非结构化状态(工单、JSON、日志)交给 LLM,不生成任何文本 token,而是在一次前向传播后只读取"答案字母"的 logits,直接输出带概率的类型化决策——是/否、多选一、量表评分、数值。本文完整解析这套"零生成"原理:每个问题如何变成单选题、KV 缓存如何被所有问题共享、logits 如何变成严格符合 schema 的 JSON,以及概率为什么还要微调和校准。
它解决什么问题:别再"生成 JSON 再祈祷"
传统做法是:让 LLM 分类,它逐 token 写出答案,速度慢,格式是你希望有效的 JSON——然后你还要解析、修复、处理类型错误。
但对一个"决策"来说,你根本不需要文本,你只需要两样东西:哪个选项(which option)和有多确定(how sure)。
关键洞察是:这个信息在模型完成一次前向传播后就已经存在——就是它分配给每个候选答案的概率。Rizzo Flow 读取的正是这个,而且只读这个。
📌 项目口号:"Unstructured state in → typed, probabilistic decisions out. On your own machine."
原理四步走:从状态到类型化 JSON
第一步:把每个问题变成单选题
这是整个原理的地基。任何类型的问题——布尔、选择、评分、数值——都被编译成一道字母单选题:
- 每个候选答案映射到一个大写字母(A、B、C…),比如布尔题
A. false 描述 / B. true 描述 - 请求时会用分词器逐字母校验:每个字母必须在上下文中恰好是 1 个 token,否则直接报错拒绝
- 26 个字母 → 每题最多 26 个答案槽位("无法判断"等弃权选项也占槽位)
这一步的代码在 src/rizzo_flow/prompts.py 的 compile_request 中:它把 state 和问题渲染成 prompt,验证每个字母的"单 token 答案槽",并切出所有问题共享的状态前缀。
第二步:状态只 prefill 一次,所有问题共享 KV 缓存
state 放在 prompt 开头,因此只被 prefill 一次,结果存入 KV 缓存。之后每个问题从同一前缀**分支(branch)**出去:各分支共享 state 的 KV 缓存单元而不是复制它,问题尾部文本则首尾相接、无 padding 地组成一个微批次一起前向。
这就是"一次请求问多个问题"为什么便宜:8 个是非题配 218 token 的合同文本,只需 1 次 prefill + 2 个微批次,共 136 ms——而不是 8 次完整前向传播。2000 token 状态 + 21 个问题也只要约 1 秒(Q8_0,RTX 5060 Ti)。
核心实现在 src/rizzo_flow/backend_llama.py 的 score():先用 llama_memory_seq_cp 把前缀序列复制成分支序列(不拷数据、只共享缓存),再按微批次解码,算完即 drop 分支、前缀原封不动留给下一批。
第三步:只读"答案字母"的 logits
这是标题中"只读一个字母"的准确含义:
- 前向传播只在每个问题的最后一个位置产出 logits(运行时对不需要 logits 的位置干脆不算)
- 然后从这一行 logits 里只取出被允许字母对应的槽位——
A是几号词元,就取第几号,别的什么都不要 - 没有任何采样:没有解码循环、没有 autoregressive 生成、没有输出文本
对应代码是 src/rizzo_flow/llama_cpp.py:llama_decode 跑前向,llama_get_logits_ith 取指定位置的一整行 logits,再按 slots(答案字母的 token id 列表)只取其中几个数。score() 里对应的一行是 session.logits(row, job.slots)(backend_llama.py)。
所以"0 生成 token"是字面意义上的:响应里的 usage.output_tokens 永远是 0。
第四步:纯 Python 把 logits 变成类型化 JSON
拿到几个 logits 数字之后,剩下全是确定性的数学,不碰模型:
- 对答案字母做 softmax → 每个选项的概率(可选温度系数)
- 按问题类型聚合:布尔取 P(true);选择取 argmax 并附全部概率;评分/数值做概率加权的期望值、中位数、离散度
- 弃权策略:
__insufficient__(证据不足)、__below_range__/__above_range__胜出时主值为null并给出status - 最后通过 schema 严格校验输出 JSON——按构造不存在类型错误
这一步在 src/rizzo_flow/decisions.py 的 decode(),输入输出由 request.schema.json 和 response.schema.json 定义。四种决策原语:
| 类型 | 你提供 | 你得到 |
|---|---|---|
boolean |
true / false 描述 | value + P(true) |
choice |
选项(最多 26 个) | choice + 每个选项的概率 |
score |
有序等级(低→高) | 加权 score、归一化分、离散度 |
numeric |
递增锚点值 + 单位 | 加权 value、中位数、超范围概率 |
整个流程的编排(编译 → 推理 → 解码 → 计时)在 src/rizzo_flow/engine.py 的 Engine.decide() 中,一眼可读完。
⚡ "0 生成 token" ≠ "0 延迟"
必须说清楚:"零生成 token"省掉的是解码循环(逐 token 采样 + 输出解析 + JSON 修复),不是省掉计算本身——prefill 和每个问题的前向仍然要花算力:
- 单个短决策约 50 ms(Q8_0,RTX 5060 Ti)
- 2000 token 状态 + 21 个问题约 1 秒
- 实测贪吃蛇演示里每步约 150 ms(含 HTTP 往返),可以以真实速度玩起来
另外一条诚实的工程备注:量化会移动 logits,共享前缀打分在 Q8_0 下偶尔会翻转接近打平的答案(777 次决策中 13 次的 argmax 变化,全部 margin < 0.24)——所以不要把你的业务阈值放在 0.5 附近。
📈 概率的形状:LoRA 微调 + 温度校准
"读概率"的前提是概率形状靠谱。原始基座模型有个毛病:即便答案错了,也会把 0.9999 压在它选的那个字母上。
Rizzo Flow 的默认权重是 Spark-X2.5 加一个专为类型化决策做的 LoRA 微调——训练用的就是和推理完全相同的机制:同样 prompt、同样一次前向、对答案字母的 softmax 与目标分布做软交叉熵,没有任何文本目标(细节见 docs/training.md,脚本在 training/)。在 typed-decisions 基准上(4B、Q8_0):
| 指标 | 原始权重 | Rizzo Flow 微调 |
|---|---|---|
| Accuracy ↑ | 0.574 | 0.648 |
| KL from gold ↓ | 2.899 | 0.452 |
| Brier ↓ | 0.480 | 0.205 |
| ECE ↓ | 0.349 | 0.112 |
微调解决"概率整体形状",校准解决"你的领域":内置的逐类型温度缩放(temperature scaling)与权重、精度、运行时、后端、prompt 版本的指纹绑定——在 CUDA 上拟合的 calibration 不会加载到 Vulkan 上。在你自己的标注数据上跑一次 rizzo calibrate 再 rizzo serve --calibration ... 即可。
🚀 快速上手:4 条命令
git clone https://gitcode.com/gh_mirrors/ri/rizzo-flow && cd rizzo-flow
uv sync --locked
uv run rizzo download # 下载 llama.cpp + Rizzo Flow 4B Q8_0(约 4.4 GB)
uv run rizzo serve # → http://127.0.0.1:8017/playground
打开 playground,从 Examples 菜单选一个例子(或写自己的 state 和 questions),点 Run;没有服务器也可以一次性运行 uv run rizzo decide examples/ticket.json。示例请求见 examples/ticket.json、examples/house.json、examples/numeric.json。
代码地图:想深入原理,按这个顺序读
| 文件 | 看什么 |
|---|---|
| src/rizzo_flow/prompts.py | 问题编译:选项→字母、单 token 槽位校验、共享前缀切分 |
| src/rizzo_flow/backend_llama.py | score():KV 分支、无 padding 微批、逐环节计时 |
| src/rizzo_flow/llama_cpp.py | ctypes 封装:llama_decode 按需产出 logits、llama_get_logits_ith 取行 |
| src/rizzo_flow/decisions.py | 纯 Python 解码:softmax、期望值、弃权策略 |
| src/rizzo_flow/engine.py | 编排全流程:编译→打分→解码→校验→计时 |
| src/rizzo_flow/api.py | 原生 /v1/decisions 与 Jev 兼容的 /v1/systemone 接口 |
一句话总结:Rizzo Flow 把"让 LLM 写答案"换成了"读 LLM 对答案字母的信念"——没有解码循环、没有解析、没有格式错误,只有前向传播加一次 softmax。这就是"只读一个字母的 logits,就能输出类型化决策"的全部秘密。


