5分钟跑通Piccolo-27B:新手完全安装与首次推理快速开始指南
5分钟跑通Piccolo-27B:新手完全安装与首次推理快速开始指南
Piccolo-27B 是 AgentScope 开源的 27B 参数决策模型(decision model),专门用于工具审查与上下文选择(tool review and context selection)。本教程带你完成 Piccolo-27B 安装、环境配置与首次推理,5 分钟即可在自己的机器上跑出第一个候选概率结果。
30秒认识Piccolo-27B:它和普通大模型有什么不同?
普通大模型(如 Qwen 系列)按"逐字生成"方式输出文本,而 Piccolo-27B 的定位是做选择题:你给它一段上下文(state)和若干候选项,它在一次前向传播中读出每个候选项的单 token 概率,直接告诉你"哪个选项最可能正确"。
它的几个关键特性(来自仓库配置):
| 特性 | 说明 | 出处 |
|---|---|---|
| 双向注意力 | 完整 prompt 内所有 token 互相可见(bidirectional_prompt) | decision-inference.json |
| 基座架构 | 基于 Qwen3.5-27B,64 层、hidden_size 5120,最长支持 262144 token | config.json |
| 推理上下文上限 | 65536 token,超出直接报错、不做截断 | decision-inference.json |
| 概率读取 | single_token_logits,温度固定 1.0,确定性输出 |
decision-inference.json |
| 支持的问题类型 | choice(2~255 选项多选一)、noul(yes/no 判断)、score(有序档位打分) |
piccolo_layout.py |
官方基准测试成绩(完整 checkpoint):
| HarnessJevBench Hard ↑ | DataJevBench ↑ | JevBench Public ↑ | Decision Index Public ↑ |
|---|---|---|---|
| 84.41% | 82.60% | 92.21% | 68.59 |
💡 简单说:Piccolo-27B 不是用来"聊天"的,而是给 AI Agent 当"决策官"的——审查工具调用是否合理、为下一步挑选最合适的上下文。
跑通Piccolo-27B前的环境检查:硬件与软件要求
硬件要求(重点看显存)
模型权重以 bfloat16 存储,12 个分片合计约 55GB(见 model.safetensors.index.json)。因此:
- 推荐:单卡 ≥ 64GB 显存(如 A100/H100),直接跑
--device cuda:0 - 显存不足时脚本会直接 OOM——参考实现只支持单设备加载,多卡并行需自行扩展
device_map
软件依赖(4 个包,全部来自 requirements.txt)
requirements.txt 只有 4 行依赖,版本约束很重要:
torch>=2.11
transformers>=5.8.1,<6
accelerate>=1.15.0
safetensors>=0.8
⚠️ 推理脚本 piccolo_inference.py 内部直接 import 了 transformers.models.qwen3_5 模块,transformers 必须装到 5.8.1 及以上,否则会报 ModuleNotFoundError。
下载Piccolo-27B模型权重:两种方式任选
仓库是一个完整的 Safetensors checkpoint,约 55GB。两种方式任选其一:
方式一:用 hf CLI 下载(官方推荐)
hf download agentscope-ai/Piccolo-27B --local-dir Piccolo-27B
方式二:git clone 镜像仓库
git clone https://gitcode.com/hf_mirrors/agentscope-ai/Piccolo-27B
下载完成后核对文件
正常应看到以下关键文件(每个文件的 sha256 都在 release-manifest.json 中,可校验完整性):
Piccolo-27B/
├── model-00001-of-00012.safetensors ~ model-00012-of-00012.safetensors # 权重分片
├── model-frozen-mtp.safetensors # 冻结的 MTP 层
├── model.safetensors.index.json # 权重索引
├── config.json / tokenizer.json / chat_template.jinja
├── decision-inference.json # 推理契约(注意力模式等)
├── piccolo_inference.py # 官方参考推理脚本
├── piccolo_layout.py # 提问布局与候选打分实现
└── requirements.txt
5分钟首次推理:安装依赖 → 写请求 → 出结果
第一步:安装依赖
python -m pip install -r Piccolo-27B/requirements.txt
第二步:准备请求文件 request.json
推理输入是一个 JSON 文件,核心字段有三个:state(上下文)、questions(问题字典)、enable_thinking(必须为 false,概率读取不支持思考模式)。下面是一个"工具选择"小例子:
{
"enable_thinking": false,
"state": "用户正在部署一个 Python 服务。可选工具:\n- 工具A:docker compose up(启动容器)\n- 工具B:pip install(安装依赖)",
"questions": {
"q1": {
"type": "choice",
"instructions": "根据上下文,下一步应该调用哪个工具?",
"criteria": {
"A": "docker compose up",
"B": "pip install"
}
}
}
}
type 还支持 noul(输出 yes/no 概率)和 score(有序档位,见 piccolo_layout.py 中 render_question 的定义)。
第三步:运行官方参考脚本
python Piccolo-27B/piccolo_inference.py \
--model Piccolo-27B \
--request request.json \
--device cuda:0
常用参数速查:
| 参数 | 作用 | 默认值 |
|---|---|---|
--model |
模型目录(必须含 decision-inference.json) | 必填 |
--request |
请求 JSON 文件路径 | 必填 |
--device |
推理设备,如 cuda:0 |
cuda:0 |
--dtype |
权重精度 bfloat16 / float32 |
bfloat16 |
--output |
把结果写入文件而非打印 | 无 |
--compare-causal |
同时跑因果注意力,对比双向 vs 单向 | 关闭 |
第四步:读懂输出
输出是一个 JSON,results 数组中每个问题包含各候选项的 candidate_logits 与归一化 probabilities:
{
"attention_mode": "bidirectional_prompt",
"probability_temperature": 1.0,
"results": [
{
"question_id": "q1",
"kind": "choice",
"option_keys": ["A", "B"],
"bidirectional_prompt": {
"probabilities": [0.87, 0.13]
}
}
]
}
概率最大的一项(本例是 A)就是模型的决策结果。加 --output result.json 可以把结果落盘。
常见报错速查表:安装与推理避坑指南
| 报错信息 | 原因 | 解决办法 |
|---|---|---|
ModuleNotFoundError: ... qwen3_5 |
transformers 版本过低 | 升级到 >=5.8.1,<6:pip install -U "transformers>=5.8.1,<6" |
CUDA out of memory |
显存不足 55GB 权重 | 换更大显存显卡,或改多卡方案 |
Supervision is not an inference input |
请求里带了 gold/answers/expected/labels 等"答案"字段 |
删掉这些字段,它们是评测用的,不是推理输入 |
FlexDM probability readout requires thinking=false |
enable_thinking 不是 false |
在请求中显式写 "enable_thinking": false |
Complete prompt exceeds context; no truncation permitted |
上下文超过 65536 token | 精简 state,模型拒绝截断以保证决策质量 |
score requires an ordered list of 2..255 described levels |
score 类型的 criteria 写错 |
score 必须是 2~255 个非空档位描述组成的有序列表 |
下一步:把Piccolo-27B接入Agent工作流
- 接入 QwenPaw:AgentScope 的 QwenPaw 支持把 Piccolo 用于本地的工具审查与上下文选择,完整配置思路见 README.md 的 "QwenPaw" 章节
- 查看推理契约:decision-inference.json 定义了注意力模式、prompt 变体(
flex_twice)等推理约定,脚本启动时会严格校验 - 第三方许可:piccolo_layout.py 采用 FlexDM v1.0 布局,MIT 许可,详见 THIRD_PARTY_LICENSES.md
- 模型协议:整体遵循 Apache 2.0(LICENSE),可自由商用与二次分发
🎉 恭喜!到这里你已经完成了 Piccolo-27B 的安装与首次推理。接下来可以试试把
choice换成noul类型,体验 yes/no 二分类的概率输出。