1. 先说说我为什么盯着1.7B小模型的tools调用不放之前在做本地自动化助手的时候我被 qwen3 1.7b 的 tools调用能力救了一命。项目需求不复杂用户问天气我就去查天气接口问新闻我就去抓新闻源问待办我就写进本地文件但麻烦的地方在于每个回复背后都对应一次真实的外部工具调用。这要求模型在只有十几亿参数的情况下依然能把意图识别—工具选择—参数填充—结果理解—组织回答这一整条链路走通而不是像很多小模型那样遇到超出训练数据的问题就只会说我无法访问实时信息。刚开始周围的人都劝我直接用大模型的函数调用接口效果确实好但问题也摆在那里每次请求都要把内容传到外部数据隐私过不去按 token 计费长期跑自动化脚本成本吃不消再加上网络往返延迟放在本地工具链里非常膈应。所以我想找一个本地能跑、工具调用又靠谱的小模型。Qwen3 1.7B 就是在这个背景下进入我视野的FP16 权重大约 3.5GB量化后 1GB 出头一张普通消费级显卡甚至纯 CPU 都能跑官方仓库明确标注支持 function calling。单看纸面参数这几乎是本地 Agent 入门最友好的选择之一。这篇文章会把我从零到一跑通 Qwen3 1.7B tools 调用的完整过程原样记录下来包括最小可用代码、多轮调用循环、多工具并行时的真实表现、三种部署方式的差异以及我在实测里踩过的各种坑。如果你也在做本地 Agent、个人助理、自动化脚本这类项目想用一个小模型扛下工具调用这摊事这篇文章应该能帮你省下好几个晚上的调试时间。2. 环境准备与最小代码先把单工具调用跑通2.1 依赖、显存和模型权重先说环境。我用的是一套非常常规的组合Python 3.10 PyTorch 2.x transformers版本建议直接用最新的因为 Qwen 的工具调用依赖较新的 chat template 实现版本太老会不认识tools参数甚至直接忽略掉。硬件方面我主力测试机是一张 8GB 显存的消费级显卡跑 FP16 的 1.7B 毫无压力显存占用大概 4GB 左右。我也在一台 16GB 内存的纯 CPU 笔记本上用 GGUF 量化版验证过能跑通就是生成速度差不少这个后面部署章节会细说。模型权重从模型仓库直接下载就可以了模型 ID 是Qwen/Qwen3-1.7B不需要额外申请权限。需要注意的一点是一定要确认你下载的权重是带 chat 模板的对话版本而不是纯基座版本。判断方法很简单加载 tokenizer 后打印tokenizer.chat_template里面有内容就说明支持对话和工具调用。2.2 工具定义用官方统一的 JSON Schema 格式工具定义是整个链路的第一道关卡。Qwen 系列在训练时用的就是一套固定的 JSON Schema 风格你不需要发明新格式照着官方示例写就行。我之前犯过一个错误自己设计了一个简化的工具描述格式结果模型完全不理睬因为它的训练数据里没见过那种写法。TOOLS [ { type: function, function: { name: get_weather, description: 查询指定城市当天的天气情况, parameters: { type: object, properties: { city: {type: string, description: 城市名称例如北京、上海} }, required: [city] } } } ]这里的关键点有两个。第一description一定要写清楚参数的含义最好带具体示例。小模型理解自然语言描述的能力有限你写城市名称和城市名称例如北京、上海对 1.7B 来说完全是两个难度级别。实测中带示例的描述能明显提高参数填充的准确率。第二required列表不要漏。漏掉之后模型可能不填某个必填参数到执行工具时才发现缺字段又要多一轮纠错。2.3 消息组装apply_chat_template 是成败关键工具定义好了怎么把用户消息和工具描述一起喂给模型核心就一行代码prompt tokenizer.apply_chat_template( messages, toolsTOOLS, tokenizeFalse, add_generation_promptTrue )apply_chat_template会把工具描述、系统提示、对话历史全部按照模型训练时的格式拼成一个完整字符串不需要你手动去拼那些特殊标记。很多人在这一步翻车是因为只顾着传messages忘了传tools参数。少了这个参数模板就不知道要注入工具调用指令模型根本不会往工具调用的方向生成。另外add_generation_promptTrue必须带上否则模板末尾没有接上 assistant 的起始标记生成结果会带上奇怪的前缀。2.4 生成响应并解析工具调用消息组装好之后就是常规的model.generate但生成参数要稍微控制一下。工具调用本质上是结构化输出任务温度我建议压在 0.1 到 0.3 之间太高了容易吐出格式残缺的 JSON。max_new_tokens也要给足128 不够我习惯用 256不然工具调用的 JSON 可能被截断在中间。inputs tokenizer([prompt], return_tensorspt).to(model.device) outputs model.generate( **inputs, max_new_tokens256, temperature0.2, do_sampleTrue ) response tokenizer.decode( outputs[0][inputs.input_ids.shape[1]:], skip_special_tokensFalse )生成出来的原始响应里工具调用会以特殊标记包裹的 JSON 形式出现。不同版本标记名可能略有差异但整体结构类似|tool_call|{name: get_weather, arguments: {city: 北京}}|/tool_call|我一般用正则把中间这段抽出来再解析这样比依赖特定解析函数更稳import json import re def parse_tool_calls(text): calls [] pattern r\|tool_call\|(.*?)\|/tool_call\| for block in re.findall(pattern, text, re.DOTALL): try: obj json.loads(block.strip()) except json.JSONDecodeError: continue if arguments in obj and isinstance(obj[arguments], str): try: obj[arguments] json.loads(obj[arguments]) except json.JSONDecodeError: pass calls.append(obj) return calls这段解析里我特意兼容了arguments是字符串的情况后面避坑章节会详细说为什么必须做这层兼容。2.5 一段可复制的完整单调用代码把上面的内容串起来就是一个最小可用版本from transformers import AutoModelForCausalLM, AutoTokenizer MODEL_ID Qwen/Qwen3-1.7B tokenizer AutoTokenizer.from_pretrained(MODEL_ID) model AutoModelForCausalLM.from_pretrained( MODEL_ID, torch_dtypeauto, device_mapauto ) TOOLS [ { type: function, function: { name: get_weather, description: 查询指定城市当天的天气情况, parameters: { type: object, properties: { city: {type: string, description: 城市名称例如北京、上海} }, required: [city] } } } ] messages [{role: user, content: 北京今天天气怎么样}] prompt tokenizer.apply_chat_template( messages, toolsTOOLS, tokenizeFalse, add_generation_promptTrue ) inputs tokenizer([prompt], return_tensorspt).to(model.device) outputs model.generate(**inputs, max_new_tokens256, temperature0.2) response tokenizer.decode( outputs[0][inputs.input_ids.shape[1]:], skip_special_tokensFalse ) calls parse_tool_calls(response) print(calls) # 预期输出[{name: get_weather, arguments: {city: 北京}}]跑通这一步你就完成了 tools 调用的最核心闭环模型理解了用户问题选择了正确的工具填好了参数。剩下的事情都是在这个基础上扩展。3. 把单次调用改成多轮循环Agent 的雏形3.1 循环的四个步骤单次工具调用跑通之后你会发现现实场景永远不是调一次就结束。用户问北京今天天气怎么样顺便提醒我明天带伞你需要模型第一次调用天气工具拿到天气数据把结果回填给模型模型再基于这个结果组织最终回复甚至可能再调一次别的工具。这就是多轮工具调用循环也是 Agent 最基础的骨架。整个循环只有四步但每一步都有讲究把最新的对话历史连同工具定义组装成 prompt生成模型响应解析是否包含工具调用如果有执行工具并把结果以 tool 角色消息回填回到第一步继续直到模型不再输出工具调用。3.2 执行结果怎么回填回填的格式直接决定了后续轮次模型能不能读懂。我用的是下面这种标准结构messages.append({ role: tool, name: call[name], content: json.dumps(result, ensure_asciiFalse) })这里content我建议统一用json.dumps序列化并且设置ensure_asciiFalse保证中文可读。模型看到的就是一段结构化的工具返回结果它需要从中提取信息来组织回答。如果你把结果包成纯文本描述模型的提取效果会差不少。另外一个很容易忽略的点模型上一轮输出工具调用时那段包含|tool_call|标记的原始响应也要以role: assistant的身份追加到对话历史里而不是只追加最终回复。因为对话模板需要看到完整的模型说了什么才能正确续接下一轮漏掉这一步第二轮组装出来的 prompt 会缺上下文模型表现断崖式下跌。3.3 终止条件与轮数保护循环什么时候该停我总结了三个条件满足任何一个就退出模型本轮输出里没有工具调用说明它已经准备直接回答用户了工具执行抛出错误且把错误信息回填之后模型连续两轮仍然调用同一个工具说明它陷入了死循环达到了我预设的最大轮数上限。轮数保护一定要加。我在调试早期遇到过模型反复调用同一个工具、完全无视错误信息的死循环如果没有轮数上限它会一直生成下去直到把上下文撑爆。一般助理类场景 3 到 5 轮就足够了。下面是完整的多轮循环代码可以直接当模板用def run_agent(user_query, max_rounds3): messages [{role: user, content: user_query}] for _ in range(max_rounds): prompt tokenizer.apply_chat_template( messages, toolsTOOLS, tokenizeFalse, add_generation_promptTrue ) inputs tokenizer([prompt], return_tensorspt).to(model.device) outputs model.generate( **inputs, max_new_tokens256, temperature0.2, do_sampleTrue ) response tokenizer.decode( outputs[0][inputs.input_ids.shape[1]:], skip_special_tokensFalse ) calls parse_tool_calls(response) if not calls: clean re.sub(r\|im_end\||/?\|im_start\|, , response) return clean.strip() messages.append({role: assistant, content: response}) for call in calls: if call[name] not in TOOL_REGISTRY: result {error: funknown tool: {call[name]}} else: result TOOL_REGISTRY[call[name]](call[arguments]) messages.append({ role: tool, name: call[name], content: json.dumps(result, ensure_asciiFalse) }) return 达到最大轮数对话未完成TOOL_REGISTRY是一个把工具名映射到实际执行函数的字典比如{get_weather: get_weather_func}。用注册表方式管理工具后面加新工具只需要往字典里塞一个函数不用改循环逻辑。4. 多工具与并行调用1.7B 的实际表现4.1 并行工具调用的返回格式真实场景很少只有一个工具。我的实际项目里有天气、新闻搜索、待办写入三个工具用户可能一句话里同时问到天气和新闻。Qwen 的工具调用模板支持并行调用也就是一次生成里输出多个|tool_call|块模型按顺序把它们列出来并不会等第一个工具执行完再想第二个。解析代码不用改parse_tool_calls用re.findall本身就支持一次找出所有工具调用块。真正需要关注的是模型在并行场景下能不能每个工具都填对参数。4.2 实测单工具稳定并行偶发翻车我在多工具场景下做了大量测试结论可以分成两层说。单工具场景1.7B 的表现是相当可用的。天气查询、新闻搜索这类职责边界清晰的工具基本能做到稳定选中正确工具并填充参数我测试几十次只有零星几次参数格式出错。多工具并行场景就要打折扣了。我常用的一句话是查一下北京的天气和今天的科技新闻模型应该输出两个工具调用。实测中它有时只输出一个漏掉新闻搜索有时两个工具都输出了但第一个工具的参数被填到了第二个工具里还有比较少见的情况它自己编造了一个不存在的工具名。对于这种小模型并行调用本身就是高难度动作原因也很好理解并行工具调用要求模型在同一个上下文窗口里完成两次独立的意图→工具→参数映射而且这两个映射之间还要保持互不干扰。参数只有 1.7B认知负荷一上去出错概率自然就上来了。4.3 用提示词和工具排序降低漏调概率我实践下来有几个行之有效的办法。第一个办法是工具排序。把用户最常问的工具放在TOOLS列表的前面模型在决策时对靠前的工具注意力更强。我的项目里天气查询使用频率最高就放在第一位命中率明显好于把它放在末尾的配置。第二个办法是系统提示词里点明并行要求。我在系统消息里加了一句如果用户的请求包含多个独立任务请一次性调用多个工具来满足用户需求效果虽然不完美但漏调概率确实有所下降。第三个办法是兜底纠错。模型漏调了工具用户追问新闻呢模型在下一轮对话中通常会补调。所以我在 Agent 层面对漏调不做过度的自动化重试而是让用户反馈来驱动这样既简单又符合直觉。5. 上生产前的部署选择transformers、vLLM、Ollama 怎么选代码在本地跑通了接下来就是部署形态的问题。同一个模型三种常见姿势适合的场景完全不同。5.1 transformers 适合离线批处理直接用 transformers 加载模型优点是无额外依赖、和实验代码完全一致适合离线批处理任务比如每天定时跑一批文本分析、批量生成工具调用请求。缺点也明显每次推理都要进程内加载模型单请求延迟受 Python 层影响高并发扛不住。如果只是自己脚本里用这个方案足够了。我的自动化助手早期版本就是这种形态一个常驻 Python 进程循环读取任务队列逐个推理完全不追求并发。5.2 vLLM 提供标准接口需要对外提供服务、或者要支撑多个客户端并发请求时我建议直接用 vLLM 起一个兼容/v1/chat/completions格式的服务端口。启动命令很简单vllm serve Qwen/Qwen3-1.7B --port 8000启动之后客户端通过标准接口调用工具定义直接放在请求体里import requests resp requests.post( http://localhost:8000/v1/chat/completions, json{ model: Qwen/Qwen3-1.7B, messages: [{role: user, content: 北京今天天气怎么样}], tools: TOOLS, temperature: 0.2, max_tokens: 256, }, ) data resp.json() msg data[choices][0][message] if msg.get(tool_calls): for tc in msg[tool_calls]: func tc[function] print(func[name], json.loads(func[arguments])) else: print(msg[content])vLLM 的好处是服务端已经把模型原始输出里的特殊标记转换成了标准的tool_calls结构客户端不用再写正则解析直接读message.tool_calls就能拿到工具名和参数省掉了我前面写的那一整套parse_tool_calls。5.3 Ollama 适合个人电脑轻量使用如果你不想折腾 Python 环境或者想在一台普通电脑上把模型当本地服务用Ollama 是最省事的。拉取模型运行之后Python 里直接调import ollama res ollama.chat( modelqwen3:1.7b, messages[{role: user, content: 北京今天天气怎么样}], toolsTOOLS, ) print(res.message.tool_calls)Ollama 对工具调用的支持依赖模型自身的 chat template所以有一个隐藏坑不是所有qwen3相关 tag 都完整带上了工具能力模板。我建议拉取之后先跑一个最简单的工具调用测试确认返回里有tool_calls字段再集成到项目里。别问我怎么知道的我第一次就是没验证直接上项目结果模型全程只会回答我无法查询实时天气。三种方式的对比如下方便你按场景选部署方式适合场景并发能力工具调用解析上手难度transformers离线批处理、单进程脚本低需要自己写正则解析中vLLM线上服务、多客户端高服务端已转成标准结构中高Ollama个人电脑、快速原型中返回标准 tool_calls 结构低6. 实测中踩过的坑和调参心得6.1 arguments 既可能是字典也可能是字符串这是我在解析阶段踩的第一个坑。模型输出的arguments字段有时候直接是 JSON 对象有时候是 JSON 字符串两种形式我都见过而且是在同一个模型的连续两次输出里交替出现。刚开始我只处理了字典形式结果第二次请求直接解析失败日志里一片KeyError。所以解析代码里必须做一层类型判断if arguments in obj and isinstance(obj[arguments], str): obj[arguments] json.loads(obj[arguments])这层兼容成本几乎为零但能救回大量看起来模型没调对的请求。实际上模型调对了一多半只是格式形态不同卡在解析层太冤了。6.2 中文标点和 JSON 解析的相爱相杀小模型在生成 JSON 时偶尔会把全角冒号、全角引号混进来比如{city 北京}这种字符串直接json.loads必然报错。我的处理方式是先做一轮字符清洗把全角冒号、全角引号替换成半角再走 JSON 解析。要注意不要用力过猛。我自己早期写过一版正则强行修复缺失括号的逻辑结果把正常输出改坏了得不偿失。现在只做字符替换这一层最保守的清洗剩下的交给重试机制兜底。6.3 温度、max_new_tokens 和重复惩罚工具调用是结构化输出任务生成参数和写文章完全是两套配置。温度拉高输出的 JSON 格式就开始飘花括号对不齐、字段名被改写都是常态。我测试下来 0.1 到 0.3 之间比较稳日常对话场景才调回 0.7。max_new_tokens也很关键。工具调用的 JSON 加上前后标记一般 100 到 200 token 就够但如果你同时在输入里塞了较长的工具描述或者系统提示词比较长128 就可能截断。我统一用 256稳。还有一个 1.7B 特有的毛病重复倾向。工具调用失败之后它可能反复输出同一个工具调用完全不读取回填的错误信息。我在model.generate里加了repetition_penalty1.1配合轮数上限基本能压住。6.4 模型死活不调工具先查系统提示词如果模型面对明显需要工具的问题偏偏不输出工具调用而是用训练记忆硬答先别急着怀疑模型能力按这个顺序排查确认apply_chat_template传了tools参数确认工具description和用户问题里的关键词能对上确认系统提示词没有写仅根据已知信息回答之类的误导性指令。最后一条最隐蔽。我早期系统的提示词是你是一个乐于助人的助手这本身没问题但加了一句请尽量根据你的知识回答模型就开始依赖训练记忆把工具调用完全抛在脑后。把系统提示词改成当需要实时或外部信息时请使用工具获取最新数据之后调用率立刻上来了。Qwen3 系列还带思考模式小模型上思考经常表现为让我先想想之类的废话拖慢响应还容易干扰工具调用输出。我在系统提示词里明确加了不要思考直接调用工具给出结果部分部署框架也有关闭思考的开关实测响应速度和调用稳定性都有改善。6.5 量化版本对工具调用质量的影响最后说量化。1.7B 这个体量很多人会直接上 GGUF 量化版跑 CPU我之前也这么干。结论是能用但要选对量化档位。我在 CPU 上测试过 4bit 量化版日常对话没问题但工具调用时偶尔会把 JSON 结构生成得比较潦草比如字段名拼写错误、缺少结束标记。如果工具调用是你的核心场景建议至少用 Q5 或 Q6 档位的量化版生成质量明显更稳。FP16 在 GPU 上跑效果最好但如果你只有 CPUQ5 档位是一个不错的平衡点。生成速度方面GPU 上 1.7B 大概每秒 40 到 60 token一次工具调用从提问到拿到参数差不多 1 到 2 秒整个闭环 3 到 5 秒CPU 上用 GGUF 能到每秒 10 到 20 token响应时间会长不少但作为本地自动化脚本的后端完全够用。我现在的项目里Qwen3 1.7B 已经稳定跑了大半个月每天处理几百次工具调用天气、新闻、待办三条链路基本没出过岔子。最后分享一个我个人的习惯不管用什么部署方式我都会在代码里保留最原始的模型输出日志也就是带着特殊标记的完整响应字符串。工具调用这种多轮链路出了问题定位最快的路径永远是回看原始输出而不是看解析后的结构化结果。把这个习惯养成你在调试多轮 Agent 时能省下大量时间。
