Bosun v3.1 0.6B 入门避坑指南:10 个常见问题,从 trust_remote_code 报错到概率对齐
Bosun v3.1 0.6B 入门避坑指南:10 个常见问题,从 trust_remote_code 报错到概率对齐
Bosun v3.1 0.6B(仓库名 bosun-v3.1-0.6b)是一个专为结构化决策设计的小型模型:基于 Qwen3-0.6B + LoRA 适配器,它不生成散文,而是针对一组候选项直接输出校准过的概率分布,适合分类、路由、评分、弃权、策略检查等决策点。本文面向第一次使用 Bosun 的开发者,汇总了从环境配置、trust_remote_code 报错,到候选槽位映射与概率对齐的 10 个高频问题,并附速查表,帮你快速跑通、少走弯路。
快速上手:3 步跑通 Bosun 的第一个决策 🚀
第一步:安装依赖
pip install transformers peft safetensors accelerate
第二步:加载完整运行时
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained(
"Hanno-Labs/bosun-v3.1-0.6b",
trust_remote_code=True,
dtype="auto",
device_map="auto",
)
第三步:调用 model.predict(...) 拿概率
predict 接收 state(共享状态)、instructions(指令)、decision_type(决策类型)和 candidates(候选列表),返回与你传入顺序对齐的概率分布。三种决策类型(choice / score / noul)的完整调用示例可参考 README.md。
⚠️ 先建立一个关键认知:这个仓库是**"适配器包"而不是完整权重包**,后面好几个"坑"都源于此。
10 个高频问题逐个拆解 🔍
问题 1:为什么必须 trust_remote_code=True?不开会怎样?
Bosun 的决策读取头 BosunForDecision 是自定义模型类(定义在 modeling_bosun.py),并不在 Transformers 的内置模型列表里。config.json 通过 auto_map 字段把 AutoConfig 和 AutoModelForCausalLM 指到仓库自带的 .py 文件。
不开 trust_remote_code=True 时,Transformers 拒绝执行仓库代码,你会得到"checkpoint 不是原生架构"之类的报错,加载直接失败。README 明确标注:trust_remote_code=True is required,因为 Bosun 的 typed-decision 读取不在标准 Transformers 中。
✅ 一句话解法:加载 Bosun 时始终带上 trust_remote_code=True。
问题 2:装了 transformers 还是加载失败,还缺什么依赖?
官方要求 4 个依赖:transformers、peft、safetensors、accelerate。Bosun 的加载器在初始化时会一次性组装 5 样东西:
- 固定 revision 的 Qwen3-0.6B 底座
adapter/里的 PEFT 适配器tokenizer/里的 tokenizer 快照decision_embeddings.safetensors的决策 token 嵌入- serving.json 记录的提示、候选掩码与稳定槽位契约
少装任何一个库(尤其是 peft 和 safetensors),都会在对应组装步骤抛 ImportError。
问题 3:仓库里没有底座大权重文件,加载时会下载什么?
Bosun 采用"底座 + 适配器"结构:config.json 中 base_model_name_or_path 指向 Qwen/Qwen3-0.6B,且 revision 被钉死为 c1899de289a04d12100db370d81485cdf75e47ca。首次加载时会自动联网下载底座权重,再叠加 LoRA 与 256 行决策嵌入。
避坑要点:
- 离线环境请先把底座模型缓存到本机,否则加载卡住或失败;
- 底座版本是 pinned 的,不要假设"任意一个 Qwen3-0.6B 都能用";
- 0.6B 体量对显存非常友好,消费级显卡甚至 CPU 都能跑。
问题 4:能用 generate() 让它输出 JSON 再解析吗?
不建议,也不需要。Bosun v3.1 的核心设计就是**"不通过自回归生成 JSON 再解析"**,而是读取决策 token 的原生 logits:
model.predict(...):渲染校验过的提示契约、屏蔽未使用的槽位,把概率映射回你的候选顺序后返回;model.decision_logits(...):返回全部 256 个稳定槽位的 logits;model.forward(...):保留与底层因果语言模型兼容,方便调试。
如果改用 generate() 输出散文再解析 JSON,等于同时放弃了概率校准和解析稳定性——这正是 Bosun 要消灭的老路。
问题 5:候选项有数量限制吗?
有:2 到 255 个。模型共有 256 个学习得到的决策 token(ID 从 151669 开始,见 config.json),其中第 255 号被保留为 null 槽位,因此运行时最多支持 255 个候选。少于 2 个或超过 255 个会直接抛出 ValueError: Bosun supports 2 to 255 candidates。
问题 6:decision_type 可以随便填吗?
只能填三种:
| 类型 | 语义 | 典型场景 |
|---|---|---|
choice |
多选一 | 客服路由、技能分发 |
score |
分级评分 | 紧急度打分、优先级 |
noul |
是否判断 | 事实确认、合规检查 |
填错会报 decision_type must be one of: choice, score, noul。三种类型走同一套概率读取路径,差别主要在提示契约中的语义描述。
问题 7:candidates 的写法有讲究吗?
每个候选是一个 {"id", "label", "description"} 字典:id 和 label 必填,description 可选。
小技巧:如果所有 description 都是"字段结构一致的 JSON 对象",提示编译器会自动启用紧凑表格格式来节省 token;只要有一个结构不一致,就整体退回普通的 t/o/n/d 格式(实现见 modeling_bosun.py 的 _compact_criteria)。候选较多时,统一结构能明显压缩提示长度。
问题 8:为什么不能按 token 序号猜"第 1 个候选 = decision_000"?
这是概率对齐里最容易踩的坑。Bosun 使用"稳定展示槽位"(stable presented slots)机制:每次 predict 会根据 seed 和 row_id 对候选做确定性打乱,再把候选分配到展示槽位(modeling_bosun.py)。因此:
- 提示里"第几个候选" ≠ 决策 token 的"第几个";
- 如果你绕过
predict直接读decision_logits,必须用 serving.json 中的presented_slot映射把概率对齐回你的候选顺序。README 专门强调:不要从 token 顺序推断语义,presented_slot映射才是权威; - 走
predict的用户无需操心:返回的probabilities已自动映射回传入顺序,candidate_to_slot字段保留了内部映射,方便排查。
问题 9:返回的概率可以直接用来设阈值吗?(概率校准)
可以。Bosun 的定位就是"输出校准过的决策,而不是生成文本"。官方在 DecisionBench(23,900 条冻结评测,零行错误)上的整体结果是:
| 指标 | 数值 | 含义 |
|---|---|---|
| accuracy | 81.1841% | 决策准确率 |
| ECE | 0.0659 | 期望校准误差,越小越好 |
| NLL | 0.6491 | 负对数似然 |
ECE 很小,说明"模型说 80%"时大约真有 80% 是对的,可以放心拿概率做路由和弃权策略。两点提醒:
- Reasoning 切片准确率仅 43.08%,复杂多步推理是短板,别超纲使用;
- 训练 held-out 上 88.39% 的准确率不等于新任务水平,它只覆盖训练中出现过的任务族,不是未见任务的泛化证据。
问题 10:离线部署或换 tokenizer 时,为什么报 decision-token ID 不匹配?
加载时会做一致性校验:tokenizer 中 256 个 <|decision_000|> … <|decision_255|> 的 ID 必须与 config.json 的 decision_token_ids 完全一致,否则抛出 RuntimeError: tokenizer decision-token IDs do not match config.json。
原因是决策嵌入按行号回填到底座词表的输入/输出矩阵中(modeling_bosun.py),ID 一旦错位,概率就全错位。
✅ 对策:始终使用仓库自带的 tokenizer/ 快照,不要替换成底座原版 tokenizer——原版里没有这 256 个决策 token。
仓库结构速览:每个文件负责什么 📁
| 文件 | 作用 |
|---|---|
| config.json | Transformers 注册信息与不可变的 Bosun 加载配置 |
| configuration_bosun.py | AutoConfig 对应的 BosunConfig |
| modeling_bosun.py | 加载器、提示编译器、决策读取 |
| adapter/ | LoRA 适配器权重与 PEFT 配置 |
| decision_embeddings.safetensors | 256 行学到的决策 token 嵌入 |
| tokenizer/ | 训练使用的精确 tokenizer 与决策词表 |
| serving.json | 提示、稳定槽位、底座 revision 的权威契约 |
| manifest.json | 内容寻址的文件哈希清单 |
10 个问题速查表 ⚡
| # | 问题 | 一句话解法 |
|---|---|---|
| 1 | trust_remote_code 报错 |
加载时始终带 trust_remote_code=True |
| 2 | 缺依赖加载失败 | 装齐 transformers + peft + safetensors + accelerate |
| 3 | 仓库里没有底座权重 | 正常:首次加载自动拉取 pinned 版 Qwen3-0.6B |
| 4 | 想用 generate 输出 JSON |
改用 model.predict(...) 直接拿概率 |
| 5 | 候选数量报错 | 保持 2~255 个候选 |
| 6 | decision_type 报错 |
只用 choice / score / noul 三种 |
| 7 | description 写法 |
统一用同字段 JSON 对象,可触发紧凑格式 |
| 8 | 概率和候选对不上 | 用 presented_slot 映射对齐,别按 token 序号猜 |
| 9 | 概率能否设阈值 | 可以:ECE 0.0659,概率是校准过的 |
| 10 | decision-token ID 不匹配 | 用仓库自带 tokenizer 快照,勿替换 |
写在最后 🎯
Bosun v3.1 0.6B 的价值不在"能聊天",而在把分类、路由、评分、弃权这类决策点变成一次带概率的前向计算:无自回归、无 JSON 解析、概率可校准。把它放进 Agent 的决策节点,0.6B 的体量也能跑得飞快。
📌 想深入机制,建议按顺序读三份文件:README.md(加载契约与示例)、serving.json(槽位契约)、modeling_bosun.py(提示编译与概率回映射实现)。