Bosun v3.1 0.6B 入门避坑指南:10 个常见问题,从 trust_remote_code 报错到概率对齐

原创2026-11-14 13:13:241,408 阅读

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 样东西:

  1. 固定 revision 的 Qwen3-0.6B 底座
  2. adapter/ 里的 PEFT 适配器
  3. tokenizer/ 里的 tokenizer 快照
  4. decision_embeddings.safetensors 的决策 token 嵌入
  5. 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(提示编译与概率回映射实现)。

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