企业官网建设流程全解析

Needle 2 的 reset() 与会话设计：为什么一个会话只绑一个工具集

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

Needle 2 是一个 45M 参数、仅需 14MB 的端侧小模型，专攻工具调用（tool calling）与结构化抽取，整个会话约 28MB 内存即可运行。它的会话模型非常克制：一个会话（session）只绑定一个工具集（toolset）——reset()只回退对话历史、永不改变工具；要换工具，必须新建Needle(...)实例。这篇文章讲清楚reset()到底做什么、为什么这样设计，以及切换工具时的正确姿势。

reset() 到底做了什么？

先看官方 API 的一句话定义（doc/apis.md）：

agent.reset()— 回退对话（rewind the conversation），保留已加载的工具（keep the tools loaded）。

对应到源码，实现只有三步：先确保引擎绑定到当前 agent，再调用 C 引擎的needle_reset（needle/init.py）：

def reset(self): self._bind() _lib().needle_reset()

它清空的是对话历史，不动工具。反过来，complete()在同一个 agent 上重复调用就是同一个会话的后续轮次：后一轮的参数可以依赖前一轮工具执行的结果（比如先search_for_contact拿到contact_id，再send_instant_message），这个多轮语义正是"会话"存在的意义（doc/apis.md）。

为什么一个会话只绑一个工具集？

这不是 API 偷懒，而是由 Needle 2 的推理机制决定的：

• 工具集在初始化时就被编译进了解码语法。needle_init会把 system 与全部工具 schema 一次性交给引擎，编译出字节级语法（byte-level grammar），约束后续每一个 token（needle/init.py）。换工具集 = 重建整套语法与上下文，代价远高于"清空历史"，所以设计成"新工具 = 新实例"。
• 记忆是有界的，工具被钉死在窗口里。模型使用 256 token 的滑动窗口，工具作为 KV sink 固定（pinned）在上下文中，因此对话无论多长，内存都稳定在约 28MB（README.md）。工具被钉住，天然意味着"会话期内不变"。

• 规模换确定性的前提是"小"。Needle 2 用 45M 参数、2-bit 量化（CQ2）在 Mobile-Actions 等基准上打平数倍于它的 270M 模型。这么小的模型没有余力做"运行时热换工具"，与其让语法动态变化，不如把工具集冻结在会话级，把复杂度挡在初始化之外。

补充一点：当声明的工具超过 5 个时，内置检索头会在初始化时嵌入所有 schema，每轮只把得分最高的 5 个工具渲染进上下文，语法也只在这一子集上重建（doc/apis.md）。注意这是每轮的检索，不是换工具集——整个目录仍然属于同一个会话。

切换工具集的正确姿势

官方行为约定写得很直白（llms.txt）：

One toolset per session. To change tools, make a newNeedle(...).reset()clears history but keeps the tools.

官方 Playground 的实现就是标准范例（needle/playground/server.py）：

def complete(self, tools_json, query): with self.lock: if self.agent is None or tools_json != self.tools_json: self.agent = Needle(tools=tools_json, weights=self.weights) # 工具变了 → 新会话 self.tools_json = tools_json else: _lib().needle_reset() # 工具没变 → 只重置历史 return self.agent.complete(query)

页面上的New chat按钮就是走POST /reset调needle_reset()（needle/playground/app.js）：清历史、留工具；而切换预设工具时，则按上面的逻辑重建 agent。

⚠️ 一个连带约束：引擎无法卸载已加载的权重。如果你先加载了微调过的.cact再想建一个基础模型 agent，会直接抛出 "cannot unload" 的RuntimeError而不是静默地用错权重——测试里有专门覆盖这一点（tests/test_weights.py）。

常见坑清单

1. 别给一个会话的每一轮都新建Needle。上下文不会延续，多轮依赖会断；正确做法是复用同一实例（llms.txt）。
2. reset()不能换工具。想换工具集就建新 agent；reset()只是"重开一轮对话"。
3. 话题不符时返回空调用[]，不是自由文本。没有声明的工具能接住的问题会被拒绝，代码里要处理这个分支（doc/apis.md）。
4. extract()本质是"单工具一次性会话"。它把 schema 声明为唯一工具、用完即弃，所以语法保证 schema 一定被满足（needle/init.py）。

小结

一句话记住 Needle 2 的会话模型：工具集在创建时冻结，reset()只清历史，换工具 = 新实例。这个看似简单的约定，让 28MB 内存、字节级语法约束和有界记忆三件事都能成立——端侧小模型的设计，往往就是用明确的边界换确定性。

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