逐行解读Nex-N2.5-Pro的chat_template.jinja工具调用XML格式与推理链模板实现原理【免费下载链接】Nex-N2.5-Pro项目地址: https://ai.gitcode.com/hf_mirrors/nex-agi/Nex-N2.5-ProNex-N2.5-Pro 是 Nex-AGI 开源的新一代多模态 Agent 模型其 chat_template.jinja 对话模板定义了模型如何处理工具调用 XML 格式与推理链thinking输出。本文逐行解读这份 154 行的 Jinja2 模板帮你彻底理解函数调用协议、思维链结构与思考模式切换的实现原理。一、先搞懂对话模板是模型的对话协议大模型本身只认识 token 序列。你传入的messagessystem / user / assistant / tool要变成模型能理解的结构化文本全靠对话模板完成翻译。对 Nex-N2.5-Pro 而言模型架构见 config.jsonQwen3.5-MoE、60 层、512 专家、256K 上下文这份模板承担四大职责行号区间模块职责L1–L41render_content宏统一渲染文本、图片、视频内容L45–L66工具注入把函数清单和 XML 调用约定写进 system 消息L67–L80多轮校验检查工具调用循环是否结构合法L81–L142角色渲染输出每轮消息、推理链与 XML 调用块 | | L143–L154 | 生成提示 | 按reasoning_effort 决定思考模式 |二、逐行解读多模态内容渲染L1–L41chat_template.jinja#L3-L41 定义了一个render_content宏它是整个模板的原子渲染器字符串内容直接输出列表内容逐项判断——图片项含image/image_url字段→ 渲染为特殊视觉 token 并递增图片计数器视频项 → 渲染为 同理计数文本项 → 输出item.text若传入add_vision_idtrue由 tokenizer_config.json 配置还会自动加上Picture 1:、Video 2:这样的编号前缀方便模型指代多张图防御性校验system 消息里出现图片/视频会直接raise_exceptionL10、L21避免渲染出训练分布之外的输入。 这些视觉 token 的 id 定义在 config.json 中如image_token_id: 248056与模板严格对齐。三、工具调用 XML 格式系统提示如何注入L45–L66当你通过 API 传入tools参数时模板会生成一段固定的系统提示chat_template.jinja#L45-L60 # Tools You have access to the following functions: tools 每个函数定义以 JSON 独占一行 /tools紧接着L53 用一整段自然语言把调用格式契约写给模型看核心规则有 4 条函数调用只能用 包裹 的格式回复后面不能有多余内容必填参数必须给出可以在调用前用自然语言说明理由不能在调用后补充没有可用工具时正常作答不要向用户提及函数调用这个概念。你的自定义 system 消息会被追加在这段工具协议之后L54–L58两者共用同一个 块。模型实际产出的调用长这样 20°C晴 为什么用 XML 而不是 JSONXML 标签边界清晰、嵌套简单服务端SGLang 的 qwen3_coder 解析器可以流式地边生成边逐标签解析无需等待整段 JSON 闭合延迟更低、容错更好。四、多轮工具调用的合法性校验L67–L80Agent 场景下对话尾部往往是一串工具结果消息。模板在 L67–L77 反向遍历 messages如果所有user 消息都被 包裹即全是工具回传结果说明缺少真正的用户提问L78–L80 直接抛出No user query found in messages.异常。这是一个典型的渲染期防御把非法输入挡在模型推理之前而不是让模型硬答。五、推理链模板实现原理L89–L126assistant 消息的渲染是整份模板最精巧的部分chat_template.jinja#L89-L126固定输出三段式结构 /think 正文回答之后可紧跟工具调用块 关键实现细节推理链提取L90–L99优先读取消息自带的reasoning_content字段服务端从 中解析出来的若没有、但content里混有 则按 位置把思考部分与正文切开——防止客户端误传导致推理链被二次嵌套工具调用块拼接L101–L125若正文非空第一个调用块用空行衔接正文一次响应调用多个函数时每个调用块以 开头依次排列参数值序列化L118标量参数直接转字符串对象/数组参数则转 JSON。即 里简单值保持可读复合值保证可解析——这是可读性与机器可解析性的平衡点。六、生成提示reasoning_effort 切换思考模式L143–L154模板最后一行add_generation_prompttrue时补上 开头并按reasoning_effort参数分四档收尾chat_template.jinja#L143-L154reasoning_effort取值模板末尾追加行为未传 / null| 自适应思考默认 | |none|| 空思考块直接闭合模型跳过思考直接作答 | |high|| 强制深度思考 | | 其他如medium | | 同默认自适应 |注意none分支的巧思用预闭合的空思考块在模板层面阻止模型继续思考无需任何额外 prompt 工程。这与 README.md 中 Thinking Modes 官方说明完全一致。七、部署速查让模板正确生效使用 SGLang 部署时两个解析参数与模板形成闭环详见 README.md--reasoning-parser qwen3把 内容抽取到reasoning_content字段正好对应模板 L91 的读取逻辑--tool-call-parser qwen3_coder流式解析上文所述 XML 调用块官方推荐采样参数temperature0.7、top_p0.95、top_k40。单节点 8×H100 的最小启动示例python -m sglang.launch_server --model-path /path/to/Nex-N2.5-Pro \ --tp 8 --reasoning-parser qwen3 --tool-call-parser qwen3_coder八、常见问题 FAQQ1我需要修改模板吗不需要。模板已内置在 chat_template.jinja加载模型时自动生效。除非你要定制工具协议或思考行为否则保持原样即可。Q2非思考模式none会省多少 token思考块被跳过每轮响应减少整段 内容短问答场景延迟和成本下降明显适合高并发、低延迟业务。Q3为什么工具结果要用 user 消息而不是独立角色渲染模板把role: tool的消息包进 并挂到 user 侧L127–L138模型将其视为环境反馈。这种结构是多轮工具循环模型 → 工具 → 模型能稳定收敛的关键。九、相关文件清单文件作用chat_template.jinja本文逐行解读的对话模板154 行tokenizer_config.json特殊 token、 等与词表配置 | | config.json | 模型结构MoE 架构、256K 上下文、视觉编码器 | | processor_config.json | 图像/视频预处理参数patch 16、2fps 抽帧 | | README.md | 部署命令、思考模式与 Function Calling 官方说明 |总结Nex-N2.5-Pro 的对话模板 工具注入L45→ 合法性校验L67→ 三段式推理链 XML 调用块L89→ 思考模式收尾L143。理解这套协议你就掌握了与 Nex 系列 Agent 模型协作的全部底层规则——工具调用格式、思维链结构与思考开关正是它在 OSWorld、SWE-Bench Pro 等长程任务上稳定表现的底层保障。【免费下载链接】Nex-N2.5-Pro项目地址: https://ai.gitcode.com/hf_mirrors/nex-agi/Nex-N2.5-Pro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 逐行解读Nex-N2.5-Pro的chat_template.jinja：工具调用XML格式与推理链模板实现原理
逐行解读Nex-N2.5-Pro的chat_template.jinja工具调用XML格式与推理链模板实现原理【免费下载链接】Nex-N2.5-Pro项目地址: https://ai.gitcode.com/hf_mirrors/nex-agi/Nex-N2.5-ProNex-N2.5-Pro 是 Nex-AGI 开源的新一代多模态 Agent 模型其 chat_template.jinja 对话模板定义了模型如何处理工具调用 XML 格式与推理链thinking输出。本文逐行解读这份 154 行的 Jinja2 模板帮你彻底理解函数调用协议、思维链结构与思考模式切换的实现原理。一、先搞懂对话模板是模型的对话协议大模型本身只认识 token 序列。你传入的messagessystem / user / assistant / tool要变成模型能理解的结构化文本全靠对话模板完成翻译。对 Nex-N2.5-Pro 而言模型架构见 config.jsonQwen3.5-MoE、60 层、512 专家、256K 上下文这份模板承担四大职责行号区间模块职责L1–L41render_content宏统一渲染文本、图片、视频内容L45–L66工具注入把函数清单和 XML 调用约定写进 system 消息L67–L80多轮校验检查工具调用循环是否结构合法L81–L142角色渲染输出每轮消息、推理链与 XML 调用块 | | L143–L154 | 生成提示 | 按reasoning_effort 决定思考模式 |二、逐行解读多模态内容渲染L1–L41chat_template.jinja#L3-L41 定义了一个render_content宏它是整个模板的原子渲染器字符串内容直接输出列表内容逐项判断——图片项含image/image_url字段→ 渲染为特殊视觉 token 并递增图片计数器视频项 → 渲染为 同理计数文本项 → 输出item.text若传入add_vision_idtrue由 tokenizer_config.json 配置还会自动加上Picture 1:、Video 2:这样的编号前缀方便模型指代多张图防御性校验system 消息里出现图片/视频会直接raise_exceptionL10、L21避免渲染出训练分布之外的输入。 这些视觉 token 的 id 定义在 config.json 中如image_token_id: 248056与模板严格对齐。三、工具调用 XML 格式系统提示如何注入L45–L66当你通过 API 传入tools参数时模板会生成一段固定的系统提示chat_template.jinja#L45-L60 # Tools You have access to the following functions: tools 每个函数定义以 JSON 独占一行 /tools紧接着L53 用一整段自然语言把调用格式契约写给模型看核心规则有 4 条函数调用只能用 包裹 的格式回复后面不能有多余内容必填参数必须给出可以在调用前用自然语言说明理由不能在调用后补充没有可用工具时正常作答不要向用户提及函数调用这个概念。你的自定义 system 消息会被追加在这段工具协议之后L54–L58两者共用同一个 块。模型实际产出的调用长这样 20°C晴 为什么用 XML 而不是 JSONXML 标签边界清晰、嵌套简单服务端SGLang 的 qwen3_coder 解析器可以流式地边生成边逐标签解析无需等待整段 JSON 闭合延迟更低、容错更好。四、多轮工具调用的合法性校验L67–L80Agent 场景下对话尾部往往是一串工具结果消息。模板在 L67–L77 反向遍历 messages如果所有user 消息都被 包裹即全是工具回传结果说明缺少真正的用户提问L78–L80 直接抛出No user query found in messages.异常。这是一个典型的渲染期防御把非法输入挡在模型推理之前而不是让模型硬答。五、推理链模板实现原理L89–L126assistant 消息的渲染是整份模板最精巧的部分chat_template.jinja#L89-L126固定输出三段式结构 /think 正文回答之后可紧跟工具调用块 关键实现细节推理链提取L90–L99优先读取消息自带的reasoning_content字段服务端从 中解析出来的若没有、但content里混有 则按 位置把思考部分与正文切开——防止客户端误传导致推理链被二次嵌套工具调用块拼接L101–L125若正文非空第一个调用块用空行衔接正文一次响应调用多个函数时每个调用块以 开头依次排列参数值序列化L118标量参数直接转字符串对象/数组参数则转 JSON。即 里简单值保持可读复合值保证可解析——这是可读性与机器可解析性的平衡点。六、生成提示reasoning_effort 切换思考模式L143–L154模板最后一行add_generation_prompttrue时补上 开头并按reasoning_effort参数分四档收尾chat_template.jinja#L143-L154reasoning_effort取值模板末尾追加行为未传 / null| 自适应思考默认 | |none|| 空思考块直接闭合模型跳过思考直接作答 | |high|| 强制深度思考 | | 其他如medium | | 同默认自适应 |注意none分支的巧思用预闭合的空思考块在模板层面阻止模型继续思考无需任何额外 prompt 工程。这与 README.md 中 Thinking Modes 官方说明完全一致。七、部署速查让模板正确生效使用 SGLang 部署时两个解析参数与模板形成闭环详见 README.md--reasoning-parser qwen3把 内容抽取到reasoning_content字段正好对应模板 L91 的读取逻辑--tool-call-parser qwen3_coder流式解析上文所述 XML 调用块官方推荐采样参数temperature0.7、top_p0.95、top_k40。单节点 8×H100 的最小启动示例python -m sglang.launch_server --model-path /path/to/Nex-N2.5-Pro \ --tp 8 --reasoning-parser qwen3 --tool-call-parser qwen3_coder八、常见问题 FAQQ1我需要修改模板吗不需要。模板已内置在 chat_template.jinja加载模型时自动生效。除非你要定制工具协议或思考行为否则保持原样即可。Q2非思考模式none会省多少 token思考块被跳过每轮响应减少整段 内容短问答场景延迟和成本下降明显适合高并发、低延迟业务。Q3为什么工具结果要用 user 消息而不是独立角色渲染模板把role: tool的消息包进 并挂到 user 侧L127–L138模型将其视为环境反馈。这种结构是多轮工具循环模型 → 工具 → 模型能稳定收敛的关键。九、相关文件清单文件作用chat_template.jinja本文逐行解读的对话模板154 行tokenizer_config.json特殊 token、 等与词表配置 | | config.json | 模型结构MoE 架构、256K 上下文、视觉编码器 | | processor_config.json | 图像/视频预处理参数patch 16、2fps 抽帧 | | README.md | 部署命令、思考模式与 Function Calling 官方说明 |总结Nex-N2.5-Pro 的对话模板 工具注入L45→ 合法性校验L67→ 三段式推理链 XML 调用块L89→ 思考模式收尾L143。理解这套协议你就掌握了与 Nex 系列 Agent 模型协作的全部底层规则——工具调用格式、思维链结构与思考开关正是它在 OSWorld、SWE-Bench Pro 等长程任务上稳定表现的底层保障。【免费下载链接】Nex-N2.5-Pro项目地址: https://ai.gitcode.com/hf_mirrors/nex-agi/Nex-N2.5-Pro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考