掌握 Granite-3.1-1B-A400M-Instruct 对话格式:<|start_of_role|> 特殊 token 与 Chat Template 实战指南
掌握 Granite-3.1-1B-A400M-Instruct 对话格式:<|start_of_role|> 特殊 token 与 Chat Template 实战指南
Granite-3.1-1B-A400M-Instruct 是 IBM 开源的 1B 参数 MoE 长上下文指令模型,其对话能力建立在 <|start_of_role|> 等特殊 token 与一套精心设计的 Chat Template 之上。本文带你完整理解这套对话格式的每个组成部分,并给出从基础对话、函数调用到 RAG 引用检索的实战方法,帮你快速玩转这个模型的 Prompt 工程。
一、模型速览:为什么值得关注 Granite-3.1-1B-A400M-Instruct
这是一个"小身材、大能力"的指令模型,核心参数一览:
| 特性 | 说明 |
|---|---|
| 📦 架构 | GraniteMoeForCausalLM(MoE,32 个专家,每 token 激活 8 个) |
| ⚡ 参数规模 | 1.3B 总参数 / 400M 激活参数,推理成本低 |
| 📏 上下文长度 | 128K(max_position_embeddings: 131072) |
| 🌍 支持语言 | 中文、英文等 12 种语言 |
| 📄 许可证 | Apache 2.0,可自由商用 |
相关配置可查看 config.json 与 README.md。
模型基于结构化对话格式训练(SFT + RLHF 对齐),因此对话时严格遵循其 Chat Template 至关重要——格式错了,效果会大打折扣。
二、3 个角色特殊 token + 1 个终止符:对话格式的"骨架"
Granite-3.1-1B-A400M-Instruct 在词表中额外扩展了 3 个角色专用 token(基础词表 49152,扩展后 49155),定义见 added_tokens.json 和 special_tokens_map.json:
| Token | ID | 作用 |
|---|---|---|
<|start_of_role|> |
49152 | 标记一段角色内容的开始 |
<|end_of_role|> |
49153 | 标记角色名(system/user/assistant)的结束 |
<|tool_call|> |
49154 | 触发**函数调用(Function Calling)**的信号 |
<|end_of_text|> |
0 | 消息结束符,同时兼任 eos/pad/bos/unk token |
💡 记忆口诀:每条消息 = 开始符 + 角色名 + 结束符 + 内容 + 文本结束符。<|end_of_text|>(ID 为 0)既是消息的"句号",也是生成停止的信号(见 generation_config.json)。
三、拆解 Chat Template:最终 Prompt 到底长什么样
模型完整的 Jinja 对话模板定义在 tokenizer_config.json 的 chat_template 字段中。它的核心规则如下:
1️⃣ 每条消息的固定包裹格式
<|start_of_role|>角色名<|end_of_role|>消息内容<|end_of_text|>
(后跟换行符)
2️⃣ 没有 system 消息时,自动生成默认系统提示
模板会自动插入:知识截止日期(2024 年 4 月)+ 当天日期(由 strftime_now 实时生成)+ "You are Granite, developed by IBM." + "You are a helpful AI assistant.",无需你手动编写。
3️⃣ 生成提示(Generation Prompt)
当 add_generation_prompt=True 时,末尾追加 <|start_of_role|>assistant<|end_of_role|>,告诉模型"该你回答了"。
4️⃣ 一次真实对话渲染后的样子
假设用户提问"请列出美国的一个 IBM 研究实验室",apply_chat_template 渲染结果是:
<|start_of_role|>system<|end_of_role|>Knowledge Cutoff Date: April 2024.
Today's Date: November 05, 2026.
You are Granite, developed by IBM. You are a helpful AI assistant.<|end_of_text|>
<|start_of_role|>user<|end_of_role|>请列出美国的一个IBM研究实验室。<|end_of_text|>
<|start_of_role|>assistant<|end_of_role|>
四、实战一步:用 apply_chat_template 跑通首次对话
只需两步加载模型和分词器(要求 transformers ≥ 4.47.0,示例代码完整见 README.md):
from transformers import AutoModelForCausalLM, AutoTokenizer
model_path = "ibm-granite/granite-3.1-1b-a400m-instruct"
tokenizer = AutoTokenizer.from_pretrained(model_path)
model = AutoModelForCausalLM.from_pretrained(model_path, device_map="auto")
chat = [{"role": "user", "content": "用一句话介绍 Granite 模型。"}]
prompt = tokenizer.apply_chat_template(
chat, tokenize=False, add_generation_prompt=True
)
inputs = tokenizer(prompt, return_tensors="pt").to("auto")
output = model.generate(**inputs, max_new_tokens=100)
print(tokenizer.decode(output[0], skip_special_tokens=True))
🔑 关键点:始终用 apply_chat_template 渲染 Prompt,不要手动拼接 token 字符串,避免漏掉换行符或 <|end_of_text|>。
五、实战二步:函数调用(Function Calling)
当传入 tools 参数时,Chat Template 会自动完成两件事:
- 在 system 消息后追加工具使用指令("需要调用工具时,以
<|tool_call|>开头并输出 JSON") - 插入独立的
tools角色块:<|start_of_role|>tools<|end_of_role|>+ 工具 JSON 定义 +<|end_of_text|>
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的天气",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}
]
prompt = tokenizer.apply_chat_template(
chat, tools=tools, add_generation_prompt=True, tokenize=False
)
模型需要调用工具时,输出会以 <|tool_call|>(ID 49154)开头,后跟 JSON 工具列表——你的推理代码只要检测这个前缀即可解析(token 定义见 special_tokens_map.json)。
六、实战三步:RAG 检索增强 + 引用标注
传入 documents 参数时,模板会生成 documents 角色块(Document 0、Document 1 依次编号),并注入"严格依据文档作答"的指令。若再叠加 controls=["citations"],模型还会在引用事实处插入 <co>0</co> 样式的引用标记,并在文末列出引用文档列表;controls=["hallucinations"] 则要求模型列出"可能是幻觉的句子",方便做 RAG 质量校验。
prompt = tokenizer.apply_chat_template(
chat,
documents=[{"text": "Granite 3.1 由 IBM 开发,支持 128K 上下文。"}],
controls=["citations"],
add_generation_prompt=True,
tokenize=False,
)
这一能力组合正是该模型官方定位的长上下文 RAG 场景的核心支撑。
七、常见坑点排查清单
| ❌ 常见问题 | ✅ 正确做法 |
|---|---|
| 手动拼接 `< | start_of_role |
忘记 add_generation_prompt=True |
模型不知道该输出,务必开启 |
| 多轮对话时漏传历史消息 | messages 需包含完整的 system/user/assistant 轮次 |
| 生成结果提前截断或不停止 | 确认 eos_token 为 <|end_of_text|>,pad 侧为 left(tokenizer_config.json) |
| 函数调用解析失败 | 检查输出是否以 <|tool_call|> 开头 |
八、关键文件速查表
| 文件 | 内容 |
|---|---|
| config.json | 模型架构:MoE 专家数、128K 上下文等 |
| tokenizer_config.json | 完整 chat_template 与分词配置 |
| added_tokens.json | 3 个角色 token 与 ID 映射 |
| special_tokens_map.json | bos/eos/pad 均为 <|end_of_text|> |
| generation_config.json | 生成参数(eos/pad ID 为 0) |
| README.md | 官方生成示例与评测结果 |
总结:Granite-3.1-1B-A400M-Instruct 的对话格式 = <|start_of_role|> + 角色名 + <|end_of_role|> + 内容 + <|end_of_text|> 的循环,加上模板自动生成的系统提示、tools 块与 documents 块。掌握这套 Chat Template,再配合 apply_chat_template 一行渲染,你已具备开发对话、函数调用与 RAG 应用的全部基础。🚀