Transformers chat template 保留工具调用字段的输入方案

在 Transformers 里接入工具调用时，最容易被忽略的不是函数本身，而是消息字段在进入 chat template 前是否完整。可靠的输入分成两部分：工具定义通过 tools 传给 apply_chat_template，历史消息则保留 assistant.tool_calls 和后续 tool 结果。只把每条消息压缩成 role 与 content，会让模板失去调用名称和参数。

官方地址：https://huggingface.co/docs/transformers/

本文只讨论 Transformers chat template 保留工具调用字段的输入方案，不讨论具体模型的工具调用训练效果。不同模型使用的控制标记可能不同，最后仍要以模型自带的模板为准。

先把 tools 和 messages 分成两条输入边界

messages 描述对话历史，通常包含 system、user 和 assistant 角色；tools 描述模型可调用的函数。Transformers 会把传入的 Python 函数或 JSON Schema 转换、渲染到 chat template 中，模型看到的是工具的名称、用途和参数定义，而不是函数的实际执行代码。

# 工具定义只描述模型可以怎样调用，不在模板里执行函数体
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查询指定城市的天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "城市名称"
                    }
                },
                "required": ["city"]
            }
        }
    }
]

# 消息历史保留模型已经产生的普通文本字段
messages = [
    {"role": "user", "content": "北京今天的天气怎么样？"}
]

这一步的判断标准很简单：工具的 schema 放在 tools，用户问题放在 messages。不要把工具 schema 拼接成一段普通用户文本，也不要假设所有模型都接受同一套控制标记。

assistant.tool_calls 要保留列表和嵌套对象

模型请求调用工具后，应把请求追加为 assistant 消息，并把调用放在 tool_calls 列表中。即使当前模型通常一次只生成一个调用，字段仍建议保持列表结构；调用名称放在 function.name，参数放在 function.arguments。

# 这是模型请求工具时的结构化记录，不是最终答案文本
tool_call = {
    "type": "function",
    "function": {
        "name": "get_weather",
        "arguments": {"city": "北京"}
    }
}

# 保留 assistant 角色和 tool_calls 层级，模板才有机会渲染它
messages.append({
    "role": "assistant",
    "tool_calls": [tool_call]
})

# 工具执行后的结果使用 tool 角色；content 按 Transformers 约定传字符串
messages.append({
    "role": "tool",
    "name": "get_weather",
    "content": "北京：晴，25 摄氏度"
})

这里有一个常见差异：某些 OpenAI 接口会把 arguments 表示成 JSON 字符串，而 Transformers 的常见 chat template 期待字典形式。不要在没有查看目标模型模板的情况下，把一种接口的序列化格式直接搬过来。工具返回值则应放在 content，并保持字符串类型。

用 apply_chat_template 统一渲染，再交给生成接口

消息历史准备好后，把同一份 messages 和工具定义一起交给 tokenizer。需要模型继续生成新 assistant 消息时，通常使用 add_generation_prompt=True；但并非每个模型都需要这个标记，是否启用要看模板实现。

# 让模板同时读取消息历史和工具 schema，并返回可直接生成的输入字典
model_inputs = tokenizer.apply_chat_template(
    messages,
    tools=tools,
    add_generation_prompt=True,
    return_dict=True,
    return_tensors="pt"
)

# 生成前把输入移动到模型所在设备；长度参数只控制本次新增输出
outputs = model.generate(
    **model_inputs.to(model.device),
    max_new_tokens=128
)

# 只解码新生成部分，避免把原始 prompt 一起当成模型回复
new_tokens = outputs[0][model_inputs["input_ids"].shape[1]:]
text = tokenizer.decode(new_tokens, skip_special_tokens=False)

如果只是想查看渲染后的文本，可以先使用 tokenize=False。如果之后再自行 tokenize，注意不要重复添加特殊 token。完成一次工具调用后，实际应用仍需解析模型输出、执行函数、把结果追加到消息历史，再次调用模板；模板本身不会替你执行工具。

字段丢失时按四个症状定位

实用的最小排查顺序是：先打印或查看 tokenizer.chat_template，再确认消息中是否真的存在 tool_calls，最后检查工具结果是否以字符串写入 content。这样可以把“字段没有传入”和“模板没有渲染”区分开。

常见问题

工具调用一定要放在 assistant 的 content 里吗？

不建议这样做。通用约定是放在 assistant 消息的 tool_calls 字段中；具体输出标记仍由模型模板决定。

一次只能保留一个 tool_call 吗？

字段结构应使用列表，因此可以表达多个调用；但很多模型通常一次只发一个，多个调用的执行顺序、ID 和结果配对要按模型卡片与模板约定处理。

为什么传了 tools 仍然没有工具描述？

可能是当前模板没有实现工具渲染，或者工具 schema 复杂到超出模型训练格式。先用简单函数签名和小 schema 排除问题，再按目标模型的模板格式调整。

总结来说，保留工具调用字段的关键不是把更多文本塞进 prompt，而是保持三层结构：tools 描述可用能力，assistant.tool_calls 描述模型请求，tool.content 描述外部结果。只要这三层在进入 apply_chat_template 前没有被扁平化，后续生成和多轮工具交互就有稳定的输入基础。