基于Hy4-preview-FP8开发AI Agent:工具调用(Tool Call)与hy_v4解析器完整指南
基于Hy4-preview-FP8开发AI Agent:工具调用(Tool Call)与hy_v4解析器完整指南
Hy4-preview-FP8 是腾讯混元(Tencent Hy)团队开源的 770B MoE 旗舰模型 Hy4 preview 的 FP8 量化版。本文是一份面向初学者的完整指南,带你基于 Hy4-preview-FP8 开发 AI Agent:从服务部署、工具调用(Tool Call),到 hy_v4 解析器 配置,一步步把模型接入你的智能体应用,让你用最低的成本跑出一个能自主调用工具的 Agent。
一、为什么选择 Hy4-preview-FP8 开发 AI Agent 🤖
在写第一行 Agent 代码之前,先搞清楚我们手上这把"枪"是什么。理解模型特性,能让后面的部署和调参少走弯路。
Hy4 preview 是腾讯混元团队的新一代混合专家(MoE)旗舰模型:总参数 770B,每个 token 激活 49B,主干共 78 层(首层为标准 FFN,其余 77 层为 MoE,每层含 256 个路由专家 + 1 个共享专家,单 token 激活 top-8 路由专家)。它在软件工程、办公分析、游戏开发、科学研究等长程任务上做了重点强化——这些恰恰是 AI Agent 最常干活的地方。
1.1 FP8 量化:更大模型、更低成本
Hy4-preview-FP8 相比原始 BF16 版本的最大区别,就是量化方式。从 config.json 可以看到量化配置:
"quantization_config": {
"quant_method": "modelopt",
"quantization": { "quant_algo": "MXFP8" }
}
- 量化算法:
MXFP8(config.json中quant_algo字段) - 量化器:
modelopt(config.json中quant_method字段)
💡 对新手意味着什么? 量化让权重占用更少的显存,原本需要多张卡才能加载的模型,现在可以用更少的资源部署。对想做 AI Agent 的个人和小团队,FP8 版本是"够用到能落地"的甜点选择。
1.2 关键模型规格速览
下表仅列主干网络参数,不含 MTP 层(来源:config.json)
| 属性 | 值 |
|---|---|
| 架构 | 混合专家(MoE) |
| 总参数 / 激活参数 | 770B / 49B |
| 层数 / 隐藏层维度 | 78 / 6144 |
| 注意力类型 | Gated DSA(稀疏注意力) |
| 路由专家 / 激活数 | 256 / top-8 |
| 上下文长度 | 1M |
| 词表大小 | 120832 |
长上下文 + 强推理 对 AI Agent 很关键:Agent 常常要在多轮对话中记住大量工具返回结果,1M 的上下文窗口意味着你的 Agent 可以处理很长的会话历史而不会"忘事"。
二、先搞懂 AI Agent 与工具调用(Tool Call)🧠
很多新手会把"让模型回答问题"和"让模型干活"混为一谈,这正是 AI Agent 的核心差异。
普通对话:你问,模型答。模型只输出文字。 AI Agent:你给目标,模型自己决定"要调用什么工具"、"传什么参数"、"根据结果再做什么",循环往复直到完成目标。
工具调用是怎么发生的?
在 OpenAI 兼容的 API 里,Agent 的"调用工具"分三步走:
- 你在请求里带上
tools:用 JSON 声明有哪些函数(名称、说明、参数结构)。 - 模型"说"出调用意图:模型不直接执行,而是在回复里返回一个结构化的
tool_calls,描述"我要调用哪个函数、参数是什么"。 - 你的代码执行工具,把结果回填:你运行对应函数,把输出作为
role: "tool"的消息塞回对话,模型据此给出最终答案。
用户提问
│
▼
[模型] → tool_calls: {name: get_weather, args: {city: 北京}}
│
▼
[你的代码执行 get_weather("北京")]
│
▼
回填 role=tool 的结果
│
▼
[模型] → 最终自然语言回答
⚠️ 关键点:模型本身不执行任何工具,它只负责"决定调用什么"。真正执行工具的是你的运行环境(一段 Python 代码)。理解这一点,就理解了 Agent 编程的骨架。
三、快速部署 Hy4-preview-FP8 服务 🚀
要开发 AI Agent,第一步是把模型跑成一个 OpenAI 兼容的 API 服务。生产环境推荐使用 vLLM 或 SGLang。下面给出两种部署方式,并重点标出与"工具调用"相关的参数。
3.1 vLLM 部署(推荐 ⭐)
使用官方预构建镜像 vllm/vllm-openai:hy4-preview:
docker run --gpus all \
-p 8000:8000 \
--ipc=host \
-v ~/.cache/huggingface:/root/.cache/huggingface \
vllm/vllm-openai:hy4-preview tencent/Hy4-preview-FP8 \
--tensor-parallel-size 8 \
--speculative-config '{"num_speculative_tokens":3,"method":"mtp"}' \
--attention-backend FLASHMLA_SPARSE \
--tool-call-parser hy_v4 \
--reasoning-parser hy_v4 \
--enable-auto-tool-choice \
--port 8000 \
--served-model-name hy4-preview
与 AI Agent 直接相关的三个参数(务必记住):
| 参数 | 作用 |
|---|---|
--tool-call-parser hy_v4 |
指定用 hy_v4 解析器 把模型输出解析成标准 tool_calls |
--reasoning-parser hy_v4 |
解析模型内部的推理(思维链)内容 |
--enable-auto-tool-choice |
开启自动工具选择,让模型能自主决定是否调用工具 |
⚠️ 如果漏掉
--enable-auto-tool-choice,模型即使"想"调用工具,API 也不会把它组织成结构化的tool_calls,你的 Agent 循环就转不起来。这是新手最常踩的坑。
3.2 SGLang 部署
使用社区官方镜像 lmsysorg/sglang:hy4-preview(同时支持 x86 与 Arm):
docker pull lmsysorg/sglang:hy4-preview
docker run --gpus all --ipc=host -p 8000:8000 lmsysorg/sglang:hy4-preview \
python3 -m sglang.launch_server \
--model tencent/Hy4-preview-FP8 \
--tp-size 8 \
--reasoning-parser auto \
--tool-call-parser auto \
--speculative-algorithm NEXTN \
--speculative-num-steps 3 \
--speculative-eagle-topk 1 \
--speculative-num-draft-tokens 4 \
--port 8000 \
--served-model-name hy4-preview
💡 SGLang 里解析器写
auto即可——框架会自动识别hy_v4模板;vLLM 则需显式指定hy_v4。两者最终效果一致,都是让服务端替你完成"模型原始输出 → 结构化 tool_calls"的解析。
四、深入 hy_v4 解析器:模型是怎么"说"出工具调用的 🔍
前面部署时反复出现的 hy_v4,到底在做什么?这一节帮你彻底看懂它。
4.1 hy_v4 是什么
hy_v4 是 Hy4 preview 的对话模板(chat template)+ 解析器 的统一名称。它定义了:
- 消息如何拼成模型能理解的文本;
- 模型的工具调用、推理过程分别用什么特殊标记包裹;
- 服务端如何把这些标记反向解析回标准的
tool_calls和reasoning字段。
模板的完整逻辑在 chat_template.jinja 中。模型配置 config.json 里的 "model_type": "hy_v4",正是和它对应的。
4.2 核心特殊 token 一览
Hy4 使用了一组带 :opensource 后缀的特殊标记(定义见 chat_template.jinja)。对 AI Agent 最重要的几个:
特殊标记(省略 :opensource 后缀) |
用途 |
|---|---|
<tool_calls> / </tool_calls> |
包裹一次回复里的所有工具调用(容器) |
<tool_call> / </tool_call> |
包裹单个工具调用 |
<arg_key> / </arg_key> |
包裹参数名 |
<arg_value> / </arg_value> |
包裹参数值 |
<tool_response> / </tool_response> |
包裹工具执行结果 |
<think> / </think> |
包裹推理/思维链内容 |
4.3 模型输出长什么样?
当模型决定调用 get_weather 时,它内部生成的是这样一段结构化文本(由 render_tools_prompt 与工具渲染逻辑决定,见 chat_template.jinja):
<tool_calls:opensource>
<tool_call:opensource>get_weather
<arg_key:opensource>city</arg_key:opensource>
<arg_value:opensource>北京</arg_value:opensource>
</tool_call:opensource>
</tool_calls:opensource>
而真正的 assistant 消息体(含工具调用与参数)由模板的渲染段生成,参考 chat_template.jinja。hy_v4 解析器 的工作,就是把上面这种"模型方言"翻译回你 API 里能直接读到的 message.tool_calls 列表——这一步在服务端自动完成,你拿到的就是干净的 JSON。
✅ 一句话总结:你写
tools声明,模型用hy_v4标记"说"出调用,hy_v4 解析器负责把它变回标准结构。三者的名字一致(都叫 hy_v4)不是巧合,而是同一套协议的两端。
4.4 推理模式:reasoning_effort
Hy4 同时支持"慢思考"和"快思考",通过 reasoning_effort 参数控制(合法值见 chat_template.jinja):
| 取值 | 行为 | 适用场景 |
|---|---|---|
high(默认) |
深度思维链,先思考再行动 | 复杂任务、多步工具编排 |
no_think |
跳过深度思考,直接回复 | 简单问答、低延迟场景 |
对 AI Agent 而言,涉及工具调用的多步任务建议保持默认 high——更充分的思考能提升工具选择的准确性。切换方式:
extra_body={"chat_template_kwargs": {"reasoning_effort": "no_think"}}
五、写出你的第一个 AI Agent 🛠️
现在把所有零件组装起来。下面是一个最小可运行的 Agent 循环,完整演示"模型 → 调用工具 → 回填结果 → 得到答案"的闭环。
from openai import OpenAI
import json
client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="EMPTY")
# 1) 声明工具(函数)
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的实时天气",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名称"}
},
"required": ["city"]
}
}
}]
# 2) 一个真正执行工具的"后端"(这里用假数据演示)
def run_tool(name, args_json):
if name == "get_weather":
args = json.loads(args_json)
return f"{args['city']}:晴,26℃"
return "未知工具"
# 3) Agent 主循环
messages = [{"role": "user", "content": "北京今天天气怎么样?"}]
while True:
resp = client.chat.completions.create(
model="hy4-preview",
messages=messages,
tools=tools,
temperature=0.9, # 推荐参数(见 generation_config.json)
top_p=1.0,
)
msg = resp.choices[0].message
messages.append(msg) # 把带 tool_calls 的 assistant 消息放回对话
if not msg.tool_calls: # 模型不再调用工具 → 输出最终答案
print("最终回答:", msg.content)
break
# 有工具调用:逐个执行并回填 role=tool 的结果
for call in msg.tool_calls:
result = run_tool(call.function.name, call.function.arguments)
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": result,
})
代码逐段解读(重点看逻辑,不是语法):
tools=传参:告诉模型"你有这些函数可用"。模型不会执行,只决定"用哪个、传什么"。msg.tool_calls判空:这是 Agent 循环的"开关"——有tool_calls就去执行工具;没有了,说明模型给出最终答案,跳出循环。role: "tool"回填:把执行结果带tool_call_id塞回对话,模型据此继续推理。while True:Agent 本质是一个循环,直到模型认为"任务完成、不再调用工具"为止。
💡 你可以把
run_tool换成任意真实函数(查数据库、调 HTTP、读写文件……),Agent 的能力就由你提供的工具集合决定。这就是 AI Agent 最迷人的地方:模型的"决策力" + 你的"执行力" = 一个能干活的智能体。
六、推荐生成参数与调优清单 ⚙️
为了让 Agent 表现稳定,建议遵循 generation_config.json 给出的官方推荐值:
| 参数 | 推荐值 | 说明 |
|---|---|---|
temperature |
0.9 |
官方推荐,兼顾创意与稳定 |
top_p |
1.0 |
配合 temperature 使用 |
reasoning_effort |
high(默认) |
Agent 任务建议开启深度思考 |
--tool-call-parser |
hy_v4(vLLM)/ auto(SGLang) |
解析工具调用 |
--reasoning-parser |
hy_v4 / auto |
解析推理内容 |
--enable-auto-tool-choice |
开启 | vLLM 必须显式开启 |
调优小贴士:
- 🔁 工具编排复杂时:保持
reasoning_effort: high,让模型充分思考再决定调用顺序。 - ⚡ 追求低延迟:简单任务可切
no_think,减少思考开销。 - 🎯 工具描述写清楚:
description和参数说明越准确,模型选错工具的概率越低。这是"零成本"提升 Agent 可靠性的最好办法。
七、进阶:微调定制你的 Agent 工具能力 📚
如果你的 Agent 要长期服务某个垂直场景(比如客服、运维),可以考虑用官方微调管线进一步打磨工具调用行为。
- 微调总览:finetune/README_CN.md
- 示例数据:finetune/data/example_data.jsonl
- 对话模板:Hy4 preview 统一使用
hy_v4(见 finetune/README_CN.md) - ms-swift 配置:finetune/ms_swift_support/hy_v4_lora_sft.yaml、finetune/ms_swift_support/hy_v4_full_sft.yaml
- LoRA / 全量微调脚本:finetune/ms_swift_support/sft_train_lora.sh、finetune/ms_swift_support/sft_train.sh
- DeepSpeed 方案:finetune/deepspeed_support/train.sh
💡 对绝大多数新手,先不用急着微调。FP8 版本本身的工具调用能力已经很强,先跑通 Agent 循环、把工具集设计好,再考虑是否需要针对你的场景做 LoRA 精调。
八、常见问题 FAQ ❓
Q1:为什么模型不返回结构化的 tool_calls,只输出文字?
最可能是没开自动工具选择。vLLM 务必加上 --enable-auto-tool-choice;同时确认 --tool-call-parser hy_v4 已正确设置,且请求里确实传了 tools。
Q2:解析器填 hy_v4 还是 auto?
vLLM 需要显式填 hy_v4;SGLang 填 auto 会自动识别。两者最终解析结果一致,别混用框架的写法即可。
Q3:FP8 和原始 BF16 版本我该选哪个? 显存紧张、想低成本落地 AI Agent,选 FP8;有充足显存、追求极限精度,可选原始 Hy4 preview。对 Agent 场景,FP8 的精度损失通常可忽略。
Q4:Agent 调用了工具,但结果没被用上?
检查是否把执行结果以 role: "tool" 且带上对应的 tool_call_id 回填进了 messages。缺了 id,模型可能无法把结果和那次调用对应起来。
Q5:会话越来越长,上下文会爆吗? Hy4 支持 1M 上下文,空间充足。但 Agent 多轮工具调用确实会累积长度,生产环境可对过长的历史做摘要或截断。
写在最后 ✨
回顾一下这条主线:部署带 hy_v4 解析器的服务 → 用 tools 声明能力 → Agent 循环里执行工具并回填结果。当你跑通第一个能自主调用工具的 Agent,就已经跨过了 AI Agent 开发最关键的门槛。
Hy4-preview-FP8 用 FP8 量化把 770B 旗舰模型的部署门槛打了下来,配合 1M 长上下文 和 hy_v4 工具调用协议,是一个非常适合起步开发 AI Agent 的底座。现在,去定义你的第一个 tools 吧——让模型开始替你"干活"。🚀
