企业官网建设流程全解析

Needle 2工具描述书写进阶：docstring、Args块与默认值如何决定准确率

【免费下载链接】needle14MB foundation model for tiny devices; phones, wearables, smart home, and robots.项目地址: https://gitcode.com/GitHub_Trending/needle20/needle

Needle 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 里。三层各司其职：

第 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 会把每一行解析成对应参数的description：

@needle.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.md）：

Arguments 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(gt=0, le=10000)]之后，负数和超额转账在 token 级别就被堵死了。完整字段清单见 doc/apis.md。

技巧 3：大工具目录靠描述"抢进"前 5 名声明超过 5 个工具时，内置的检索头只把得分最高的 5 个工具渲染进上下文，没选中的工具不是"概率低"而是完全不可达（见 doc/apis.md）。此时 description 里的关键词就是检索命中的关键——把用户最可能说的词（房间名、动作词）写进描述里。

工具描述自查清单：5 项过一遍准确率更稳

发布前对照检查，每项 30 秒：

1. ✅docstring 首句是否说明"做什么 + 何时用"，而非复述函数名？
2. ✅每个参数是否都有Args:说明，并带单位/来源提示？
3. ✅可省略的参数是否给了默认值（或Optional标注）？
4. ✅有限选项是否全部用Literal/Field(enum=...)封闭？
5. ✅数值/字符串约束是否用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