codecamp

怎么给 Qwen 写工具描述

工具使用属 Qwen 系列能力面,qwen3.7-max 接口未记载 tools 参数;工具描述按「名称、参数与类型、返回值、失败回退」四件套备好,缺项可以先让模型评审出来——不用等接入后才暴露。

一、前提与适用

前提 说明
适用模型 支持 tools 参数的 Qwen 系列模型档位(按各档接口文档核对)
能力面依据 官方能力清单中工具使用属 Qwen 系列能力;qwen3.7-max 接口文档未记该参数
本节做法 四件套写清工具描述;用纯文本评审让模型找出缺项
不适用 已经有成熟 function calling 框架的工程——schema 由框架校验,本节写法作描述文档参考

二、怎么做

工具描述四件套,每件都要可执行:

  1. 名称:一个动词短语,范围与功能一一对应(query_weather 管「查」,不管「订阅」)。
  2. 参数与类型:每个参数带类型、必填与否、取值约束——「city(城市名)」缺类型,模型不知道该传字符串还是行政区划代码。
  3. 返回值:结构说清(字段列表或示例 JSON),「返回:天气信息」这种一句话描述会让调用方无从解析。
  4. 失败回退:超时、无结果、参数非法时返回什么——没写回退,模型面对报错只能瞎猜或编造。

坏写法:

工具:query_weather,查询城市天气,参数是城市名,返回天气信息。

四件套缺了两件半:参数无类型、返回值无结构、失败回退完全没有。

改写后的完整提示词(评审形态——让模型当接口评审员):

你是接口评审员。下面是一份给模型用的工具描述,请对照「名称、参数与类型、返回值、失败回退」四项检查,输出缺失项清单,每项一行,格式:缺失:<项>:<建议补充内容>。没有缺失则输出「无」。

工具描述:
名称:query_weather
用途:查询城市天气
参数:city(城市名)
返回:天气信息

评审形态的价值:四件套检查项写进提示词,模型按清单逐项过,缺什么报什么。

「描述是否过四项检查」可以做成可跑检查:

## EXPECT: 名称=1 参数类型=0 返回结构=0 失败回退=0
DESC = """名称:query_weather
用途:查询城市天气
参数:city(城市名)
返回:天气信息"""

import re
name = int("名称:" in DESC)
ptype = int(bool(re.search(r"(str|int|float|bool|字符串|整数|布尔)", DESC)))
ret_struct = int(bool(re.search(r"返回.*(:|\{|字段)", DESC)))
fallback = int(("失败" in DESC) or ("超时" in DESC) or ("回退" in DESC))
print(f"名称={name} 参数类型={ptype} 返回结构={ret_struct} 失败回退={fallback}")

实测输出与判定:脚本实跑输出与首行注释一致。逐条判定:坏描述只有「名称」一项达标,参数类型、返回结构、失败回退三项计 0——与判定器预期完全一致。生产中把 DESC 换成真实工具描述即可复用;缺项内容则由下面的实测输出评审给出。

怎么看这个示例:判定器是本地脚本,上面那条提示词另在 qwen3.7-max(temperature=0.7、top_p=0.8) 上实测;脚本输出不等于模型输出,两者分别核对。

模型回复(真实输出节选):

缺失:参数与类型:建议补充参数的数据类型(如 string)以及是否为必填项。
缺失:返回值:建议补充返回值的具体数据类型和字段结构(如包含温度、湿度、天气状况的 JSON 对象)。
缺失:失败回退:建议补充查询失败、城市不存在或网络异常时的错误处理机制、错误码或默认提示信息。

Qwen 输出卡片

以上为模型真实回复的节选,实测日期 2026-11-16。

三、参数与边界

边界 说明
接口边界 qwen3.7-max 接口文档未记 tools 参数;写法按系列能力面口径准备,接入前核对目标档位文档
评审局限 模型评审只能查描述文本的自洽性,参数取值是否合理仍需业务方确认
schema 严格性 接入 function calling 后以框架的 JSON Schema 校验为准,本节四件套是描述底稿
描述漂移 工具升级后描述要同步改,过时描述会诱导模型传错参数

四、验收清单

检查项 通过标准
四件套齐 名称、参数类型、返回结构、失败回退四项逐项在案(判定器可查)
评审闭环 模型评审报出的缺项全部补齐,复审输出「无」
边界可回挂 每个参数的取值约束写进描述,不靠约定俗成
停手条件 接入后模型仍传错参数,先核对描述与实际接口是否漂移

五、注意与相关

工具描述是写给「选择工具的那个环节」看的说明书,不是给人看的简介——可执行是底线:每个参数能照着传值,每种失败能照着回退。qwen3.7-max 上用评审形态先把描述打磨好,接入支持 tools 的模型档位时直接以四件套底稿生成 schema。评审输出的缺项清单本质上就是 5.3 的自检清单反着用;工具调用失败后的多轮重试口径见 大需求怎么拆成 Qwen 多轮对话。

图片图表怎么问 Qwen
什么时候必须拦住 Qwen
温馨提示
下载编程狮App,免费阅读超1000+编程语言教程
取消
确定
目录

关闭

MIP.setData({ 'pageTheme' : getCookie('pageTheme') || {'day':true, 'night':false}, 'pageFontSize' : getCookie('pageFontSize') || 20 }); MIP.watch('pageTheme', function(newValue){ setCookie('pageTheme', JSON.stringify(newValue)) }); MIP.watch('pageFontSize', function(newValue){ setCookie('pageFontSize', newValue) }); function setCookie(name, value){ var days = 1; var exp = new Date(); exp.setTime(exp.getTime() + days*24*60*60*1000); document.cookie = name + '=' + value + ';expires=' + exp.toUTCString(); } function getCookie(name){ var reg = new RegExp('(^| )' + name + '=([^;]*)(;|$)'); return document.cookie.match(reg) ? JSON.parse(document.cookie.match(reg)[2]) : null; }