14MB模型本地跑Agent：Needle 2部署实战，手机级设备也能调工具

为什么值得学： 昨天 Hacker News 上爆火的 Show HN 项目 Needle 2，把”能调用工具的 Agent 模型”压缩到了 14MB——整个模型是一个单文件二进制，跑完一轮完整会话只占约 28MB 内存。这意味着你不需要 GPU、不需要云端 API，在手机、树莓派、智能家居设备上就能跑一个能”看懂工具、调用工具”的小型 Agent。今天这篇教程带你 20 分钟跑通。

前置条件

– Python 3.9+（建议 3.10）

– 能联网的电脑（首次运行需要从 Hugging Face 下载引擎，约几十 MB）

– 不需要 GPU，纯 CPU 即可

成功标准： 让模型根据你的指令，返回一个结构化的工具调用 JSON，而不是普通聊天文本。

第 1 步：安装

Needle 2 已经发布为 Python 包，一条命令搞定：

pip install cactus-needle

安装完成后可以用下面的命令验证：

python -c "import needle; print(needle.__version__)"

能输出版本号说明安装成功。如果报错，多半是 Python 版本太低，先升级到 3.10 再试。

第 2 步：定义一个工具

Needle 2 的核心设计是”工具调用即结构化输出”。你先用 Python 描述一个工具，模型读懂了你的描述，就会在需要时调用它。

新建 `tools_demo.py`，写入：

from needle import Needle

model = Needle()  # 首次运行会自动下载引擎并缓存

# 用 docstring 描述工具，模型靠这个决定何时调用
def get_weather(city: str) -> str:
    """查询指定城市的天气，返回一句话摘要。参数：城市名"""
    return f"{city} 今天晴，26 度"

model.add_tool(get_weather)

第 3 步：让模型调用工具

接着写主逻辑：

result = model.run("北京今天天气怎么样？")
print(result)
# 期望输出：{"tool": "get_weather", "arguments": {"city": "北京"}}

模型不会真的帮你查天气，它做的是识别意图 + 填好参数 + 返回结构化调用——真正执行由你自己的 Python 代码完成。这是端侧小模型的正确用法：模型负责”决策”，工具负责”执行”。

第 4 步：完整可运行示例

把上面的代码合并成一个文件，直接跑：

from needle import Needle

model = Needle()

def get_weather(city: str) -> str:
    """查询指定城市的天气，返回一句话摘要。参数：城市名"""
    return f"{city} 今天晴，26 度"

model.add_tool(get_weather)

def calculator(expr: str) -> str:
    """计算数学表达式。参数：要计算的表达式"""
    return str(eval(expr))

model.add_tool(calculator)

for question in ["北京天气", "23*17 等于多少", "你好"]:
    result = model.run(question)
    print(f"Q: {question}")
    print(f"A: {result}")
    print("---")

预期行为：

– “北京天气” → 调用 `get_weather`，参数为 `{“city”: “北京”}`

– “23*17 等于多少” → 调用 `calculator`，参数为 `{“expr”: “23*17”}`

– “你好” → 无工具可调用，返回普通文本回复

第 5 步：常见失败处理

问题 1：首次运行下载很慢或失败。

Needle 2 的引擎托管在 Hugging Face。如果网络不通，手动下载后放到缓存目录，或设置镜像：

export HF_ENDPOINT=https://hf-mirror.com

问题 2：输出不是 JSON 而是普通文字。

说明你的工具描述不够清晰。给 docstring 加上”参数：xxx”这种明确提示，模型更倾向走工具调用。

问题 3：结果不稳定，同一问题两次回答不同。

14MB 模型的确定性不如大模型，这是正常现象。官方建议用”置信度阈值”过滤：结果里自带置信度分数，低于阈值的调用自动转人工或重试。

部署到手机/树莓派

官方仓库提供了导出接口，可以把模型导出为单文件二进制，配合 Python 的嵌入式解释器打包，整体体积可以控制在 30MB 以内——塞进手机 App 或树莓派项目完全可行。具体做法：

# 导出模型为独立文件（约14MB）
python -m needle.export --output needle2.bin

之后在目标设备上用同一个 Python 包加载这个文件即可，推理过程不联网、不依赖云。

小结

Needle 2 教给我们的核心思路：端侧 AI 不是”什么都会”的通用大脑，而是”会做决定、会调用工具”的轻量调度器。 把重计算留给云端、把决策放到本地，是未来一年小模型落地最现实的路径。今天 20 分钟跑通的这套流程，可以直接迁移到你的下一个硬件项目上。

— END —
LC 智趣厅 · 科技与生活的交点
ihygg.cn