拆解 Bosun v3.1 0.6B 源码:modeling_bosun.py 的 prompt 编译器与 decision_logits 逐行剖析

原创2026-11-14 10:54:55705 阅读

拆解 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)把四样东西组装在一起,顺序非常讲究:

  1. 加载锁定版本的基座:从 Qwen/Qwen3-0.6B 的固定 revision c1899de2 加载,保证任何人复现出的模型完全一致;
  2. 扩词表并写入决策嵌入:先 resize_token_embeddings 扩到 151925,再把 decision_embeddings.safetensors 中的 256 行嵌入,用 index_copy_ 精准写回词表的第 151669–151924 位(输入侧和输出侧各写一次,见 modeling_bosun.py#L150-L163);
  3. 挂 LoRA 适配器:PeftModel.from_pretrained(..., is_trainable=False) 只读加载 adapter/ 目录;
  4. 校验词表一致性:加载 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)把前面所有环节串起来,最后三步值得注意:

  1. 只取前 len(candidates) 个槽位的 logits(其余槽位相当于被 mask 掉);
  2. 对这 N 个槽位单独做 softmax,得到归一化概率;
  3. 按 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 到概率」的全链路 🚀

登录后查看全文
bosun-v3.1-0.6b