拆解 Bosun v3.1 0.6B 源码:modeling_bosun.py 的 prompt 编译器与 decision_logits 逐行剖析
拆解 Bosun v3.1 0.6B 源码:modeling_bosun.py 的 prompt 编译器与 decision_logits 逐行剖析
Bosun v3.1 0.6B 是一款面向「结构化决策」的小型模型:它基于 Qwen3-0.6B + LoRA 适配器,把分类、路由、打分、弃权等决策任务变成一次前向推理,直接输出候选项上的归一化概率分布,而不需要生成和解析 JSON。本文带你逐行拆解核心源码 modeling_bosun.py,看懂它的 prompt 编译器 render_decision_prompt 与决策读取函数 decision_logits 是如何协同工作的 🧭
Bosun 决策模型是什么:一次前向推理拿到概率分布
和普通聊天模型「生成文字」不同,Bosun 的输出是原生概率。你可以把它理解为一个「选择题考试器」:
- 输入:一段共享状态
state+ 一条指令instructions+ 一组候选项candidates - 输出:每个候选项上校准好的概率(
probabilities),最高者即为模型的选择
它的三个决策类型覆盖了绝大多数 agent 决策点:
| 决策类型 | 典型场景 | 例子 |
|---|---|---|
choice |
路由、分类 | 工单该转 Billing 还是 Access? |
score |
打分、优先级 | 紧急程度是 Low / Medium / High? |
noul |
是/否判断、策略检查 | 重复扣款是否已被确认? |
整个推理包的关键文件如下,建议对照阅读源码:
| 文件 | 作用 |
|---|---|
| modeling_bosun.py | BosunForDecision 加载器、prompt 编译器与 decision 读取逻辑(本文主角) |
| configuration_bosun.py | BosunConfig 配置类,定义决策 token 数量与槽位契约 |
| config.json | Transformers 注册信息与不可变加载配置 |
| serving.json | 权威契约:256 个决策 token、稳定槽位映射、评估指标 |
| decision_embeddings.safetensors | 训练好的 256 行决策 token 嵌入(输入 + 输出两套) |
| adapter/adapter_config.json | LoRA 适配器配置(r=16、lora_alpha=32,覆盖全部注意力与 MLP 投影) |
| tokenizer/chat_template.jinja | 对话模板,含 enable_thinking 开关 |
加载契约:四步拼出一个完整的决策模型
BosunForDecision.from_pretrained(见 modeling_bosun.py#L52-L191)把四样东西组装在一起,顺序非常讲究:
- 加载锁定版本的基座:从
Qwen/Qwen3-0.6B的固定 revisionc1899de2加载,保证任何人复现出的模型完全一致; - 扩词表并写入决策嵌入:先
resize_token_embeddings扩到 151925,再把 decision_embeddings.safetensors 中的 256 行嵌入,用index_copy_精准写回词表的第 151669–151924 位(输入侧和输出侧各写一次,见 modeling_bosun.py#L150-L163); - 挂 LoRA 适配器:
PeftModel.from_pretrained(..., is_trainable=False)只读加载 adapter/ 目录; - 校验词表一致性:加载 tokenizer 后逐个比对
<|decision_000|>等 256 个 token 的实际 ID 与config.json是否一致,不一致直接抛错。
💡 为什么要写死这些校验?因为 Bosun 的契约是「槽位即答案」:第 0 个候选永远对应决策 token 0,第 255 号是固定留给 null(弃权)槽的。任何一位错位都会静默产生错误答案,所以宁可在加载时爆炸。
prompt 编译器:render_decision_prompt 逐行剖析
这是全文最值得细读的一段(modeling_bosun.py#L303-L354)。它的工作是把你传入的 state / instructions / candidates 编译成训练时见过的稳定槽位 JSON 契约。
第一步:入口校验
if not 2 <= candidate_count <= 255:
raise ValueError("Bosun supports 2 to 255 candidates")
- 候选数必须在 2 到 255 之间:256 个决策 token 里第 255 号被 config.json 的
null_token_index预留给弃权,所以运行时最多 255 个候选; decision_type只允许choice、score、noul三种,与模块顶部的_DECISION_TYPES常量一一对应。
第二步:确定性乱序,消除位置偏见
digest = hashlib.sha256(f"{seed}:{row_id}:candidate-order".encode()).digest()
random.Random(int.from_bytes(digest[:8], "big")).shuffle(presentation_order)
这段是整个设计里最巧的一步 ⚡ 模型在 prompt 里看到的候选顺序,是对调用方传入顺序做一次可复现的洗牌:
- 用
seed + row_id + "candidate-order"做 SHA-256,取前 8 字节生成随机种子; - 同一个
seed和row_id永远得到同一个乱序——保证推理结果可复现; - 不同
row_id会得到不同乱序——训练时模型就见过大量乱序,因此不会「偏爱第一个选项」。
洗牌结果同时产出 presentation_order(槽位 → 候选下标)和 candidate_to_slot(候选 id → 槽位号)两张映射表,供最后把概率「翻译回」调用方的原始顺序。
第三步:压缩 criteria 结构
每个候选被映射成 {t, o, n, d} 四个短字段:决策 token、原始下标、label、description。_compact_criteria(modeling_bosun.py#L357-L393)还会做一次「表头压缩」:如果所有 description 都是结构相同的 JSON 字典,就把重复的键名提到 criteria_fields 表头里,正文只留值数组,显著省 token。
第四步:规范化 JSON 输出
def _canonical_json(value):
return json.dumps(value, ensure_ascii=False, separators=(",", ":"), sort_keys=True)
键排序 + 紧凑分隔符,保证同一输入永远生成字节级一致的 prompt 字符串——这正是 prompt_schema: bosun-decision-prompt-v3-stable-slots 中 stable 二字的含义。
系统提示与思考开关
编译出的正文之后,predict 会用 tokenizer/chat_template.jinja 套上对话模板,系统提示只有一句话(modeling_bosun.py#L21-L24):
"Choose exactly one supplied decision token. Return only that token. Do not explain the answer."
同时 enable_thinking=False(来自 config.json 的 decision_prompt_enable_thinking)会让模板追加一个空 块,明确告诉模型:不要思考,直接给决策 token。
decision_logits:从 256 个 token 里读出稳定槽位
这是读取概率的入口(modeling_bosun.py#L216-L236),逐行看:
if attention_mask is not None and not bool(torch.all(attention_mask[:, -1] == 1)):
raise ValueError("decision_logits requires left-padded inputs")
model_kwargs.setdefault("use_cache", False)
model_kwargs.setdefault("logits_to_keep", 1)
- 左填充校验:决策只发生在 prompt 的最后一个位置,所以 batch 内所有行必须以真实 token 结尾。发现右填充直接报错,避免把概率读在 padding 上——这是决策模型最常见的坑;
logits_to_keep=1:只保留最后一个位置的 logits,整条序列只需 1 行词表输出,显存和速度都占优;use_cache=False:单次推理不需要 KV 缓存。
然后核心只有两行:
return outputs.logits[:, -1, :].index_select(
-1, self.decision_token_ids.to(outputs.logits.device)
)
取最后一位置的全词表 logits,再按 256 个决策 token 的 ID 一次 index_select 抽出 256 维向量——每个维度就是对应稳定槽位的得分。词表里其他 15 万个普通 token 的得分在这里被直接丢弃,模型「被强制」只从这 256 个槽位中作答。
注意 configuration_bosun.py#L45-L54:decision_token_ids 就是 range(151669, 151925),与 tokenizer/added_tokens.json 中 <|decision_000|> 到 <|decision_255|> 的定义严格对齐。
predict:softmax 之后把概率翻译回你的顺序
predict(modeling_bosun.py#L238-L293)把前面所有环节串起来,最后三步值得注意:
- 只取前
len(candidates)个槽位的 logits(其余槽位相当于被 mask 掉); - 对这 N 个槽位单独做
softmax,得到归一化概率; - 按
presentation_order反向搬运,把概率写回调用方传入的原始候选顺序。
返回的字典同时给出 slot_logits、slot_probabilities 和 probabilities 三套数据,前者便于调试槽位映射,后者可直接用于业务决策。最小用法如下(完整版见 README.md):
choice = model.predict(
state={"request": "Customer cannot access their account."},
instructions="Choose the best support route.",
decision_type="choice",
row_id="example-1",
candidates=[
{"id": "billing", "label": "Billing"},
{"id": "access", "label": "Account access"},
],
)
print(choice["probabilities"])
加载入口一行即可:AutoModelForCausalLM.from_pretrained(..., trust_remote_code=True),trust_remote_code=True 是必需的,因为这套 typed-decision 读取逻辑不在标准 Transformers 里。而 forward、generate 等方法全部透传给底层因果语言模型(modeling_bosun.py#L193-L214),意味着 Bosun 依然可以当普通对话模型用,决策能力是「叠加」上去的。
这套设计解决了什么问题
用一张表总结 v3.1 相对「让大模型生成 JSON 再解析」方案的优势:
| 维度 | 生成 JSON 再解析 | Bosun 稳定槽位读取 |
|---|---|---|
| 输出可靠性 | 可能出现格式错误、多输出、幻觉选项 | 输出只能是 256 个决策 token 之一,天然合法 |
| 延迟 | 逐 token 自回归 | 单次前向 + logits_to_keep=1 |
| 概率含义 | 依赖采样温度,未校准 | 槽位 logits 直接 softmax,可校准 |
| 位置偏见 | 模型常偏爱列在前面的选项 | 训练期强制乱序,推理期按 seed:row_id 确定性洗牌 |
| 弃权处理 | 需额外约定 | 第 255 号 null 槽位原生支持 |
评估数据也印证了这一点:选中的第 2 个 epoch 在冻结训练留出集上达到 88.39% 准确率,在 23,900 行 DecisionBench 上取得 81.18% 准确率、ECE 仅 0.0659(概率校准误差很低,详见 serving.json 的 metrics 字段)。
总结
Bosun v3.1 0.6B 源码最值得学习的三点:
- prompt 编译器是契约的一部分:确定性洗牌 + 规范化 JSON,让 255 个候选的选择题在任何机器上都得到字节一致的 prompt;
- decision_logits 只做一件事:校验左填充 → 取最后一位置 → 抽出 256 个稳定槽位,简单到没有失败的空间;
- 槽位语义与 token 顺序解耦:
candidate_to_slot映射保证无论模型内部如何乱序,你拿到的概率永远对齐自己传入的候选顺序。
如果你想继续深挖,建议从 modeling_bosun.py 的 render_decision_prompt 读起,配合 serving.json 里的 256 个决策 token 清单,半小时就能完整跑通一次「从 prompt 到概率」的全链路 🚀