Needle 2工具描述书写进阶docstring、Args块与默认值如何决定准确率【免费下载链接】needle14MB foundation model for tiny devices; phones, wearables, smart home, and robots.项目地址: https://gitcode.com/GitHub_Trending/needle20/needleNeedle 2 是面向手机、可穿戴设备等微型设备的 14MB 函数调用模型而工具描述tool description正是决定它准确率的最直接杠杆。docstring 写一句话、Args 块写一行、默认值加一个等号——这三处不起眼的文本决定了模型能否选对工具、填对参数。本文用一份对照清单带你把工具描述写到准确率拉满。为什么描述是准确率的命门Needle 2 的设计哲学非常直接模型只靠你声明的工具描述来决定调什么、怎么填。它的解码过程由一份从你的 schema 编译出的字节级语法byte-level grammar约束每个 token 都被限制在合法范围内——描述写得越好合法空间里的对答案就越靠前。官方在 README.md 中有一句点睛之笔Needle reads your tool descriptions to decide what to call and how to fill arguments, so describing them well is the whole game.换句话说工具描述写得不好再强的模型也救不回来。下面拆解描述的三层结构。工具描述的三层结构needle.tool装饰器会把你写的函数翻译成一份 JSON schema源码见 needle/agent/tools.py翻译规则就藏在 build_schema 和 _parse_doc 里。三层各司其职层次你写的东西模型看到的东西作用① docstring函数文档首段工具级description决定该不该调这个工具② Args 块Args:下的逐行说明每个参数的description决定参数该填什么值③ 默认值x: int 5参数移出required列表决定哪些参数可以省略第 1 层docstring 是工具的一句话定位docstring 的开头段落Args:之前的部分会成为整个工具的description是模型做工具检索和选择时的主要依据。写的时候回答三个问题做什么、何时用、和相似工具的区别。needle.tool def get_weather(city: str): Get the current weather for a city. return {city: city, temp_c: 27, sky: clear}反例工具函数、helper 这类空话等于没写——当你的目录里同时有send_email和share_message时模型只能靠 description 里的动词和场景词来区分它们。第 2 层Args 块是逐参数的填值说明书Needle 原生支持 Google 风格的Args:块Arguments:、Parameters:、Params:也可以_parse_doc 会把每一行解析成对应参数的descriptionneedle.tool def set_thermostat(temperature: int, mode: Literal[heat, cool, auto] auto): Set the thermostat. Args: temperature: target temperature in Celsius mode: heating strategy to use return {temperature: temperature, mode: mode}注意两个细节写单位、写来源。target temperature in Celsius比the temperature好得多——它告诉模型用户说的 21 度就是填 21不用换算。一行一个参数格式是参数名: 说明行首缩进冒号不能省否则正则匹配不到见 tests/test_tools.py 的解析测试。第 3 层默认值 告诉模型可以留空这是最容易被忽略的一层。在 build_schema 中有默认值的参数不会进入required列表Optional[...]/X | None类型标注同理。而 Needle 的行为契约很明确见 doc/apis.mdArguments contain only values evidenced by the input. An optional field with no evidence is omitted, not guessed.即参数没证据就省略而不是瞎猜。给参数加上默认值等于明确授权模型没有证据时可以不填从根源上消灭编造参数值这类错误。三个进阶技巧把合法空间收窄描述决定模型想填什么而这三招决定模型只能填什么——它们都会被编译进解码语法技巧 1用Literal把参数变成选择题Literal[heat, cool, auto]会被翻译成一个固定枚举集合needle/agent/tools.py模型只能从中选输出集合外的值在语法层面就不可能。凡是有限选项的参数一律用Literal而不是str。技巧 2用needle.Field上硬约束通过typing.Annotated内联 Field范围ge/le/gt/lt、正则pattern、长度min_length/max_length等全部编译进语法。例如amount: Annotated[float, needle.Field(gt0, le10000)]之后负数和超额转账在 token 级别就被堵死了。完整字段清单见 doc/apis.md。技巧 3大工具目录靠描述抢进前 5 名声明超过 5 个工具时内置的检索头只把得分最高的 5 个工具渲染进上下文没选中的工具不是概率低而是完全不可达见 doc/apis.md。此时 description 里的关键词就是检索命中的关键——把用户最可能说的词房间名、动作词写进描述里。工具描述自查清单5 项过一遍准确率更稳发布前对照检查每项 30 秒✅docstring 首句是否说明做什么 何时用而非复述函数名✅每个参数是否都有Args:说明并带单位/来源提示✅可省略的参数是否给了默认值或Optional标注✅有限选项是否全部用Literal/Field(enum...)封闭✅数值/字符串约束是否用Field写进了语法如果对照检查后准确率仍不理想下一步是把描述好的工具作为种子做 LoRA 微调doc/finetuning.md——训练数据 JSONL 里的tools字段用的正是你写好的这份描述描述质量直接决定合成数据和微调的上限。延伸阅读完整 API 与行为契约doc/apis.md工具 schema 构建源码needle/agent/tools.py描述解析的单元测试可当格式范例tests/test_tools.py快速上手与最小示例README.md【免费下载链接】needle14MB foundation model for tiny devices; phones, wearables, smart home, and robots.项目地址: https://gitcode.com/GitHub_Trending/needle20/needle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考