needle

环境要求

• 可用的 Python 环境与 pip（README 未指定具体版本）
• 首次使用需联网从 Hugging Face 拉取一次推理引擎，之后本地缓存、推理不联网
• 如需 LoRA 微调或检查点导出，需额外安装 train 依赖
• 设备内存可支撑约 28MB 的会话运行时（模型为单文件 14MB 二进制）

安装与启动步骤

1. 1安装 Needle 包

   通过 pip 安装 Python 包 cactus-needle，包含推理、LoRA 微调与导出能力，无需其他构建步骤。

   pip install cactus-needle

   复制

2. 2按需安装训练栈

   仅在需要微调或导出检查点时执行；运行时包默认不包含训练相关依赖。

   pip install "cactus-needle[train]"

   复制

3. 3定义工具函数

   用 @needle.tool 装饰函数，函数签名的类型注解即参数类型，docstring 即工具描述，描述好坏直接影响调用准确率。

   import needle
   
   @needle.tool
   def get_weather(city: str):
       "Get the current weather for a city."
       return {"city": city, "temp_c": 27, "sky": "clear"}

   复制

4. 4创建 Agent 并调用

   把工具列表传给 needle.Needle，run() 会自动完成“模型选调用—执行函数—回传结果—生成最终回答”的完整闭环。

   agent = needle.Needle(tools=[get_weather])
   print(agent.run("what's it like in Lagos right now?")["results"])

   复制

关键配置

如何确认成功

执行 agent.run(...) 后返回结果中带有 results 字段（含已执行工具的返回值），即表示安装与调用链路正常。

常见问题

注意事项

• 模型返回的是结构化数据：文本输入、JSON 输出，由根据你的 schema 编译的字节级语法约束每个 token。
• 每个响应都带有一个由学习到的 head 给出的校准置信度，可设置阈值：高于阈值直接执行，低于阈值转人工或升级处理。
• 务必只在 README 给出的 pip 包名 cactus-needle 下安装，不要自行拼装其他包名或参数。
• 需要 LoRA 微调或导出检查点时再安装 train 额外依赖，纯推理无需训练栈。