5分钟跑通Piccolo-27B:新手完全安装与首次推理快速开始指南

原创2026-11-14 17:13:491,431 阅读
文章标签:人工智能大模型工具调用本地部署

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 二分类的概率输出。

登录后查看全文
Piccolo-27B