Rizzo Flow校准指南：用温度缩放让LLM输出的概率真正可信

Rizzo Flow 是一个 100% 本地运行的开源 LLM 决策框架：它不生成任何文本，而是读取一次前向传播后候选答案上的概率，直接返回带概率的类型化决策。概率可信是它最有价值的输出，而概率校准（Calibration）正是 Rizzo Flow 内置的关键一步：用温度缩放（temperature scaling）在你的自有数据上拟合参数，让"模型说 80% 把握"真的意味着约 80% 的正确率。

先认识 Rizzo Flow：零生成 Token 的概率决策

普通 LLM 应用是"让模型写答案"，而 Rizzo Flow 把每个问题变成单选题：候选答案各映射一个大写字母，模型只需输出这些字母上的 logits，本地 Python 完成 softmax 后就得到概率分布（实现见 decisions.py）。

这意味着：

• 输出天然是结构化 JSON，不存在解析失败、类型错误；
• 概率是原始输出，而不是事后估算——所以校准它才有意义；
• 四种题型：boolean、choice、score、numeric，全部支持弃权（abstain）策略。

为什么概率需要校准：温度缩放解决什么问题

未经处理的模型概率往往"形状不对"。Rizzo Flow 文档给出了一个典型例子：微调前的基座模型对错误答案也敢给出 p ≈ 0.9999（见 docs/training.md）。如果你的系统按阈值 0.8 触发自动审核，这种过度自信会让自动决策大量误放行。

温度缩放是最简单可靠的修正方法：把 logits 除以一个温度 T 再 softmax。

• T > 1：分布变"平"，压过度自信；
• T < 1：分布变"尖"，放大区分度；
• 只引入一个标量参数（每题型一个），不会过拟合，也不改变 argmax 决策本身。

准备工作：三份数据，各司其职

这是校准中最重要、也最容易被跳过的原则，源码注释写得很直白（calibration.py）："never claim validation from fit loss"——校准集上的拟合损失不能当验证用。

仓库自带的 benchmarks/smoke-v1.jsonl、benchmarks/perturbations-v1.jsonl 等标注数据集展示了 JSONL 的格式，可直接参考。

三步校准流程：从收集数据到加载服务

第 1 步：收集带标签的 logits 行

校准输入是 JSONL，每行包含题型、原始 logits 和正确答案下标：

{ "type": "choice", "logits": [2.1, 3.4, 0.8, 0.1], "label_index": 1 }

每行对应一个真实决策：把该问题各候选项的 logit 记下，并标出哪个是正确答案。logits 长度必须在 2–26 之间（LabeledLogits约束，calibration.py）。

第 2 步：拟合温度

先复制指纹：任意一次响应的元数据里都有fingerprint（Jev 兼容端点在x_rizzo扩展字段中）。然后运行：

uv run rizzo calibrate calibration.jsonl \ --fingerprint MODEL_HASH \ --output calibration-fit.json

fit_temperature()（calibration.py）会为每种题型独立拟合一个温度：在 log 尺度上以 241 个网格点搜索使 NLL 最小的 T（搜索范围 0.05–800，且包含 T=1）。输出的fit_metrics记录拟合前后的 NLL 供你参考。产出的calibration-fit.json关键字段：

第 3 步：加载校准并验证

uv run rizzo serve --calibration calibration-fit.json # 或单次决策 uv run rizzo decide examples/ticket.json --calibration calibration-fit.json

运行时（engine.py）每次请求都会按题型查表取温度，再对 logits 做温度缩放的 softmax；响应中probability_status会从uncalibrated_conditional_option_scores变为temperature_scaled_requires_held_out_validation，并附带完整校准记录——透明可审计。

最后，务必在留出测试集上验证（实现见 evaluation.py）：

uv run rizzo evaluate heldout.jsonl --output results/calibrated-report.json

报告包含 accuracy、NLL、Brier、ECE（期望校准误差）与 10 分箱的可靠性曲线。ECE 显著下降、Brier 改善，才算校准成功。

指纹锁：防止校准被"错配"的最后一道防线

引擎启动时会校验：calibration.fingerprint必须等于当前运行的backend.metadata["fingerprint"]，否则直接拒绝启动（engine.py）。

指纹由以下要素哈希而成（backend_llama.py）：

• 模型权重（含微调标识）
• 量化精度（Q8_0 / Q4_K_M / BF16…）
• 运行时版本（llama.cpp 发布号）
• 计算后端（CUDA / Vulkan / Metal…）
• prompt 版本
• KV cache 类型（如启用量化 KV）

实际含义：base 权重上拟合的校准加载不到微调权重上；CUDA 上的加载不到 Vulkan 上；换了量化、换了 prompt 也要重新拟合。这不是限制，而是保护——因为量化与硬件都会改变概率的微小细节（README 的 Known limitations 有明确说明）。

校准在整个链路中的位置

Rizzo Flow 认为有两层"让概率变好"的手段，且可以叠加：

1. LoRA 微调（基础）：重塑概率的"形状"。官方基准上，4B 模型的 ECE 从 0.349 降到 0.112，Brier 从 0.480 降到 0.205，"错误答案上 0.9999"的现象基本消失（见 README.md 与 docs/training.md）。
2. 温度缩放（适配你的领域）：微调再好，也没见过你的业务数据。Jev 生态里设计的置信度阈值不能直接照搬，校准就是让它们适配你的分布。

一句话概括：微调是出厂校准，温度缩放是你的本地校准。

常见问题速查

结语：让"80% 把握"真的值 80%

Rizzo Flow 把 LLM 从"写答案"变成"读概率"，而校准让这份概率可以被阈值、可以被审计、可以被信任。整个流程只有三步：

1. 准备校准集 + 留出集两份自有领域数据；
2. rizzo calibrate拟合每题型的温度；
3. rizzo serve --calibration加载，并在留出集上确认 ECE 下降。

配合 examples/ticket.json 等示例与内置 playground，你可以从零搭起一条"输入状态 → 输出可信概率"的本地决策链路——不联网、不生成一个 token，概率却真正可信。