这是关于 Needle 2 的详细部署与使用教程。Needle 2 是一个仅 14MB 的微型基础模型，专为手机、穿戴设备等小型设备设计，擅长工具调用和结构化数据提取。

本教程将涵盖从安装、基础使用到高级微调的全流程。

📋 部署前准备

在开始前，请确保你的系统满足以下要求：

  • 操作系统：Windows、macOS 或 Linux。
  • Python 环境：需要 Python 3.8 或更高版本。
  • pip：Python 的包管理工具。

🚀 快速安装与入门

1. 基础安装

使用 pip 安装核心 Python 包。这是运行模型的最基本方式。

1
pip install cactus-needle

2. 加速安装（可选）

根据你的硬件，可以安装带有 GPU 加速的版本：

  • NVIDIA GPU (CUDA):

    1
    pip install "cactus-needle[gpu]"

  • Apple Silicon (Metal):

    1
    pip install "cactus-needle[metal]"

3. 运行你的第一个工具调用

安装完成后，你可以立即开始使用。模型权重会在首次运行时自动从 Hugging Face 下载并缓存。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import needle

# 1. 定义一个工具（函数）
@needle.tool
def get_weather(city: str):
    """获取某个城市的当前天气。"""
    # 这里模拟返回天气数据，实际可替换为 API 调用
    return {"city": city, "temp_c": 27, "sky": "晴朗"}

# 2. 创建 Needle 代理，并传入工具列表
agent = needle.Needle(tools=[get_weather])

# 3. 运行代理，提出自然语言请求
result = agent.run("拉各斯现在的天气怎么样？")

# 4. 查看结果
print(result["results"])
# 输出: [{'city': '拉各斯', 'temp_c': 27, 'sky': '晴朗'}]

📦 核心功能与用法

结构化数据提取

你可以使用 extract() 方法，直接从文本中提取结构化数据。只需定义一个 Pydantic 模型。

python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
from pydantic import BaseModel

class 发票信息(BaseModel):
    供应商: str
    总金额: float
    到期日: str

# 从文本中提取信息
发票 = needle.extract(
    "来自 Acme Corp 的发票，总金额 $1,200.00，到期日 2026-09-01",
    发票信息
)

print(发票.供应商, 发票.总金额)  # 输出: Acme Corp 1200.0

使用预置环境

Needle 为常见场景（如智能家居）提供了预置的工具集，开箱即用。

1
2
3
4
5
6
7
from needle.environments import smart_home

# 智能家居代理已预置了控制灯光、空调等工具
smart_home.agent.complete("将书房的灯光调暗到 30%")

# 运行测试套件验证环境
smart_home.run_tests()

启动 Playground 交互界面

你可以启动一个本地 Web 界面来交互式地测试模型。

1
2
3
4
5
# 启动基础模型的 Playground
needle playground

# 启动一个微调后模型的 Playground
needle playground --weights my_needle.cact

启动后，在浏览器中访问 http://127.0.0.1:7860 即可使用。

🔧 高级功能：微调模型

你可以使用自己的数据对 Needle 2 进行微调（LoRA），使其更适应你的特定任务。

1. 准备微调数据

数据应为 JSONL 格式，每行一个样本。reasoning 字段是可选的。

1
{"query": "将厨房灯光调到10", "tools": [{"name": "set_lights", "parameters": {"type": "object", "properties": {"room": {"type": "string"}, "brightness": {"type": "integer"}}, "required": ["room"]}}], "answers": [{"name": "set_lights", "arguments": {"room": "厨房", "brightness": 10}}], "reasoning": "'厨房' -> room; '调到10' -> brightness 10"}

2. （可选）合成数据

如果你没有数据，可以使用大模型（通过 OpenRouter）根据工具定义合成数据。

1
2
3
4
5
6
7
8
# 设置 API 密钥
export OPENROUTER_API_KEY=sk-or-...

# 从工具 schema 生成 500 个样本
needle generate-data --tools my_tools.json --num-samples 500 --output data.jsonl

# 扩展现有数据集
needle generate-data --augment data.jsonl --num-samples 500

3. 执行微调

使用 finetune 命令开始训练。基础模型会自动从 Hugging Face 下载。

1
2
3
4
5
# 基础微调
needle finetune data.jsonl --epochs 10

# 微调前先生成 300 个额外样本
needle finetune data.jsonl --epochs 10 --generate 300

常用微调选项：

  • --epochs：训练轮数（默认 3）
  • --lora-rank：LoRA 秩（默认 16）
  • --lr：学习率（默认 1e-4）
  • --batch-size：批次大小（默认 16）

4. 构建并导出微调后的模型

将 LoRA 适配器与基础模型合并，并导出为单个 .cact 文件。

1
needle build checkpoints/needle2.pkl --lora checkpoints/needle_lora.pkl --out my_needle.cact

添加 --bits 2 可以进一步压缩模型大小。

5. 使用微调后的模型

导出的 .cact 文件可以直接被 Needle 引擎加载使用。

1
2
3
import needle
agent = needle.Needle(weights="my_needle.cact", tools=[...])
agent.run("...")

❓ 常见问题

  • 问：模型文件在哪里？
    • 基础模型权重会在首次运行时自动从 Hugging Face 下载并缓存到本地。微调后导出的 .cact 文件会保存在你指定的路径。
  • 问：如何离线部署？
    • 详细的离线安装和部署指南请参考项目文档中的 doc/apis.md。核心思路是在有网的环境下载好模型和引擎，然后传输到目标设备。
  • 问：微调时显存不足怎么办？
    • 可以尝试减小 --batch-size 的值，或使用 --lora-rank 较小的值。
  • 问：如何获得更多帮助？
    • 项目提供了详细的文档目录 (doc/)，包含 API 参考、微调指南和环境说明。你也可以通过邮件 founders@cactuscompute.com 联系团队。

🔗 更多资源

按照以上步骤，你应该能够成功在本地运行、使用甚至微调 Needle 2 模型。