用Needle 2的complete()手写Agent循环不依赖run()的完整可控教程【免费下载链接】needle14MB foundation model for tiny devices; phones, wearables, smart home, and robots.项目地址: https://gitcode.com/GitHub_Trending/needle20/needleNeedle 2 是一个仅 14MB 的端侧工具调用基础模型45M 参数约 28MB 内存跑完整个会话专为手机、可穿戴、智能家居和机器人等小设备设计。本文教你跳出run()的自动托管用complete()一步步手写 Agent 循环获得对每一轮的完全控制权。从上图可以看到Needle 2 在 Mobile-Actions 基准上的精度与 FunctionGemma 270M、LFM2.5 230M 等模型互有胜负但体积小 5~70 倍、且采用 2-bit 量化。正因如此它常被嵌入到对内存敏感、需要精细控制的应用里——而手写complete()循环正是这类场景的必修课。先搞懂run() 和 complete() 的分工方法行为适合场景agent.run(query)全自动循环模型选工具 → 执行 → 回喂结果直到结束results里附带所有已执行结果快速验证、标准调用agent.complete(text)只跑一轮返回原始调用 JSON由你自己执行函数、自己决定下一步需要拦截、审计、自定义逻辑agent.reset()清空对话历史但保留已加载的工具开始新话题run()本质上就是自动版的手写循环。想理解它内部在做什么可以对照 needle/init.py 中run()的实现它就是一个while循环不断调用complete()、执行function_calls、把结果json.dumps回喂进去。手写Agent循环的3步流程手动驱动循环只需要记住一个节奏发问 → 执行 → 回喂。import json import needle needle.tool def set_lights(room: str, on: bool, brightness: int): Turn a rooms lights on or off and set brightness. return {ok: True, room: room} agent needle.Needle(tools[set_lights]) # 第 1 步发问拿回模型的第一轮决策 response agent.complete(把客厅灯调暗一点亮度30) # 第 2 步判断是调用就自己执行 if response[type] call: result set_lights(**response[function_calls][0][arguments]) # 第 3 步把执行结果回喂给模型进入下一轮 response agent.complete(json.dumps(result))注意两点回喂的内容是结果对象的 JSON 字符串不是自然语言。模型会基于这个结构继续推理。一轮可能返回多个function_calls同一轮要调多个工具要逐个执行后合并回喂。每轮响应里藏着什么complete()每轮都返回同一个结构的 JSON 信封{ type: call, function_calls: [ { name: set_lights, arguments: { room: 客厅, on: true, brightness: 30 } } ], reasoning: 客厅 - room; 调暗 - brightness 30, confidence: 0.94, peak_ram_mb: 28.5 }几个关键字段值得每个循环都读一遍typecall表示模型发起调用respond且function_calls为空表示循环结束——这就是你的while条件。reasoning模型对每个参数来源的简短推导如ten minutes - minutes 10调试时非常有用。confidence校准过的置信度分数见下一节。无关请求不会编造调用而是返回空调用[]拒绝——这是契约的一部分。用 confidence 给循环加一道安全闸手写循环的最大红利是你可以在每一轮检查置信度而不是等run()跑完response agent.complete(query) if response[type] call and response[confidence] is not None \ and response[confidence] 0.8: # 低于门槛不执行转人工或升级到大模型 response agent.complete(insufficient confidence, please clarify)confidence取校准头打分和解码概率两者的最小值官方建议定一个产品门槛高于它就执行低于就重新提问或升级模型。一个细节微调后的权重.cact不会更新置信头此时该字段为None需要跳过阈值判断。详见 doc/apis.md 的 Confidence 一节。什么时候该手写循环适合手动驱动的典型场景执行前审批转账、删除这类高危操作执行前弹确认框——run()无法中途暂停。结果后处理把工具结果先落库、脱敏或改写再决定回喂什么。多轮业务逻辑根据上一轮结果动态决定是继续、重试还是切换工具集。循环护栏run()内置max_steps8手写时你可以自己实现更复杂的步数限制、超时和降级策略。会话结束时记得调用agent.reset()清空对话工具集保留避免旧话题污染下一轮推理。小结与延伸循环骨架就三步complete()拿调用 → 自己执行 →json.dumps(result)回喂type respond时收尾。每一轮都读取type、reasoning、confidence它们分别决定停不停为什么信不信。完整 APIField约束、工具检索、system 事实、离线部署都整理在 doc/apis.md想让自己的工具更听话可以参考 doc/finetuning.md 的 LoRA 微调流程训完的.cact同样能用这套循环驱动。想直接上手pip install cactus-needle即可首次运行会自动从 Hugging Face 拉取引擎并缓存推理过程完全离线、不联网。【免费下载链接】needle14MB foundation model for tiny devices; phones, wearables, smart home, and robots.项目地址: https://gitcode.com/GitHub_Trending/needle20/needle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考