打造能干活的 AI Agent:gemma-4-26B-A4B-it-qat-AWQ-INT4 原生函数调用(Function Calling)实战教程
打造能干活的 AI Agent:gemma-4-26B-A4B-it-qat-AWQ-INT4 原生函数调用(Function Calling)实战教程
gemma-4-26B-A4B-it-qat-AWQ-INT4 是 Google Gemma 4 开源多模态大模型的 QAT 4-bit 量化版本,原生支持 Function Calling(函数调用),能让本地 AI Agent 自主决策并调用外部工具。本文带你三步跑通"工具声明 → 模型调用 → 结果回填"的完整闭环,打造真正能干活的智能体 🛠️。
一、30 秒认识 gemma-4-26B-A4B-it-qat-AWQ-INT4
在动手之前,先搞清楚这个模型"身材"如何。核心参数来自 config.json 与 README.md:
| 项目 | 说明 |
|---|---|
| 架构 | MoE(混合专家):总参数 25.2B,每次推理仅激活 3.8B(128 个专家取 8 个 + 1 共享) |
| 量化方案 | QAT(量化感知训练)+ AWQ INT4,compressed-tensors 格式,4bit / group_size=32,MSE 观测器 |
| 上下文窗口 | 256K tokens(Agent 多轮工具历史装得下) |
| 支持模态 | 文本 + 图像 |
| 文件体积 | 17.19 GB(相比 bf16 精度版本大幅缩小显存占用) |
| 授权 | Apache 2.0,可商用、可本地私有化部署 |
💡 "A4B" 中的 A 指 Active 4B:虽然总参数 26B,但推理速度接近 4B 小模型——这正是它适合做"干活 Agent"的原因:能力强、响应快。
相比后训练量化(PTQ),QAT(Quantization-Aware Training) 在训练阶段就模拟了量化误差,因此 4-bit 权重仍能保持接近原始 bf16 模型的质量,且该量化版本专门在 STEM 与 Agentic(智能体)数据集上做校准,工具调用场景表现更稳。
二、为什么选它做本地 AI Agent?
| 能力 | 对 Agent 的意义 |
|---|---|
| 原生 Function Calling | 无需微调或"提示词黑魔法",声明工具即可规范调用 |
| 256K 上下文 | 长流程任务、多轮工具调用历史不丢失 |
| 可配置思维模式(Thinking) | 复杂决策前先"想一步",再决定调用哪个工具 |
| 智能体基准 Tau2 得分 68.2%、LiveCodeBench 77.1% | 官方基准数据(见 README.md),明显强于上一代 Gemma 3 27B |
| Apache 2.0 开源 + 本地部署 | 数据不出内网,适合企业私有 Agent 场景 |
三、Function Calling 原理:一次工具调用的完整生命周期
打开 chat_template.jinja 可以看到,Gemma 4 用三种特殊标记承载函数调用全流程:
① 工具声明(Tool Declaration)
调用前,你把工具列表通过 tools 参数传入,模板会把 OpenAI 风格的标准 JSON Schema 渲染成模型专属格式(宏定义见 chat_template.jinja):
<|tool>declaration:get_weather{description:<|"|>查询城市天气<|"|>, parameters:{...}}<tool|>
② 模型发起工具调用(Tool Call)
模型决定调用工具时,输出如下结构(渲染逻辑见 chat_template.jinja):
<|tool_call>call:get_weather{city:Beijing}<tool_call|>
解析后你会拿到标准的 tool_calls:函数名 + JSON 参数,可直接交给代码执行。
③ 工具结果回填(Tool Response)
你的代码执行完函数后,把结果以 <|tool_response>response:get_weather{...}<tool_response|> 形式写回对话(块格式见 chat_template.jinja),模型读到结果后继续生成最终回答。
整个闭环如下:
用户提问 → 模型决策 → 输出工具调用(函数名+JSON参数)
↑ ↓
最终回答 ← 模型续写 ← 你的代码执行工具函数,结果回填
值得一提的是,该模板同时兼容 Google 原生 tool_responses 格式和 OpenAI role:"tool" + tool_call_id 格式(自动把 tool_call_id 映射回函数名,见 chat_template.jinja),无论用哪种生态的 Agent 框架都能无缝接入。
四、快速上手:三步跑通第一个函数调用
第 1 步:安装依赖
pip install -U transformers torch accelerate
第 2 步:加载模型
from transformers import AutoProcessor, AutoModelForMultimodalLM
MODEL_ID = "cyankiwi/gemma-4-26B-A4B-it-qat-AWQ-INT4"
processor = AutoProcessor.from_pretrained(MODEL_ID)
model = AutoModelForMultimodalLM.from_pretrained(MODEL_ID, dtype="auto", device_map="auto")
第 3 步:声明工具并生成
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的当前天气",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名,如 Beijing"}
},
"required": ["city"]
}
}
}]
messages = [
{"role": "system", "content": "你是天气助手,回答前必须先调用工具获取数据。"},
{"role": "user", "content": "北京今天天气怎么样?"}
]
inputs = processor.apply_chat_template(
messages, tools=tools, tokenize=True, return_dict=True,
return_tensors="pt", add_generation_prompt=True, enable_thinking=False
).to(model.device)
outputs = model.generate(**inputs, max_new_tokens=512, temperature=1.0, top_p=0.95, top_k=64)
response = processor.decode(outputs[0][inputs["input_ids"].shape[-1]:], skip_special_tokens=False)
result = processor.parse_response(response, prefix=inputs["input_ids"])
当 result 中出现 tool_calls 字段(包含函数名和 JSON 参数)时,说明模型已经"想要"调用你的工具了 ✅
五、实战:构建天气助手 Agent 的完整调用闭环
单轮调用只是开始,真正的 Agent 需要一个循环:只要模型返回 tool_calls,就执行函数、回填结果、再次生成,直到模型给出自然语言回答:
import json
your_tools = {"get_weather": lambda city: {"temp": 26, "weather": "晴", "city": city}}
while "tool_calls" in result:
for call in result["tool_calls"]:
messages.append({"role": "assistant", "content": "", "tool_calls": [call]})
args = json.loads(call["function"]["arguments"])
messages.append({
"role": "tool",
"tool_call_id": call["id"],
"content": str(your_tools[call["function"]["name"]](**args))
})
# 重新走一遍 apply_chat_template + generate,得到下一轮 result
role:"tool" 消息会自动按 tool_call_id 匹配到对应函数名并渲染为工具响应块,这个细节由 chat_template.jinja 处理好了,你不需要手写任何特殊标记。
六、关键配置与最佳实践清单 📋
官方推荐参数(与 generation_config.json 完全一致):
| 参数 | 推荐值 |
|---|---|
temperature |
1.0 |
top_p |
0.95 |
top_k |
64 |
其他实践要点(摘自 README.md Best Practices):
- 思维模式:
enable_thinking=True可让模型先推理再答;parse_response会自动分离思考内容与最终答案 - 多轮历史管理:历史消息中只保留每轮的最终回答;但工具调用轮次的思考内容应保留(模板会自动处理)
- System Prompt 写法:明确列出"什么场景该调用哪个工具、禁止凭空编造数据",能显著提升调用准确率
- 图像输入:图片放在文本之前效果更佳(26B A4B 支持文本+图像)
七、常见问题 FAQ:显存、参数与踩坑指南
Q1:需要多大显存? 权重 17.19 GB,加上 KV Cache 与激活开销,建议 24GB 及以上 显存(如 RTX 4090 / A5000)。得益于 MoE 仅激活 3.8B 参数,生成速度依然很快。
Q2:模型输出的参数 JSON 偶尔不规范怎么办?
在 parameters 中把每个字段的 type、取值范围、单位都写进 description,Schema 越具体,模型遵循度越高。
Q3:模型总是"答而不调"(不调用工具)?
检查两点:① 是否通过 tools 参数声明了工具;② system prompt 是否明确要求"必须先调用工具,禁止凭记忆回答"。
Q4:4-bit 量化会拖累函数调用能力吗? 不会明显。该版本采用 QAT 而非普通后量化,并用智能体场景数据校准,质量接近未量化版本,这是它与普通 GGUF/AWQ 模型的核心区别。
八、仓库文件资料速查
| 文件 | 用途 |
|---|---|
| README.md | 模型卡片:能力清单、基准数据、最佳实践 |
| config.json | 架构与量化参数(MoE 专家数、256K 上下文、INT4 配置等,量化配置见 config.json) |
| chat_template.jinja | 聊天模板:Function Calling 的声明/调用/响应格式全在这里 |
| generation_config.json | 官方推荐采样参数(temperature / top_p / top_k) |
| processor_config.json | 图像/视频/音频处理器配置 |
| tokenizer.json · tokenizer_config.json | 词表与分词器配置(262K 词表) |
从"能聊天"到"能干活",只差一层函数调用。把工具声明给 gemma-4-26B-A4B-it-qat-AWQ-INT4,它就能像员工一样:接需求、调工具、给结果 ⚡