掌握 Granite-3.1-1B-A400M-Instruct 对话格式:<|start_of_role|> 特殊 token 与 Chat Template 实战指南

原创2026-11-05 12:17:281,420 阅读

掌握 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 应用的全部基础。🚀

登录后查看全文
granite-3.1-1b-a400m-instruct