Blame for README.md

---
license: apache-2.0
base_model: openbmb/MiniCPM-V-4.7-1B
library_name: transformers
pipeline_tag: image-text-to-text
language:
  - zh
  - en
tags:
  - tool-calling
  - function-calling
  - agent
  - multimodal
  - chinese
---

# FinchAI-Rune1-Preview

> 首个 **FinchAI** 系列模型。底座 [MiniCPM-V 4.7-1B](https://huggingface.co/openbmb/MiniCPM-V-4.7-1B)（面壁智能 OpenBMB），
> 用 LoRA 微调而成，**重点是工具调用时的「判断力」**。

| | |
|---|---|
| **本仓库** | `-f16`（bfloat16 完整权重，2.9 GB） |
| **能力范围** | 文本 + **视觉**（多模态完整） |
| **加载方式** | `AutoModelForImageTextToText`（transformers ≥ 5.18.0） |
| **许可** | Apache 2.0 |

**这是当前唯一发布的版本，也是能力最完整的一份**：含视觉塔，可继续微调、可二次量化。
（GGUF 转换已验证可行，但导出的 GGUF 不含视觉，与「最完整」的定位不符，故暂不单独发布。）

---

## 一、这是什么

一个 1.55B 的本地小助手，专攻**什么时候该调工具、该调哪个**。

大多数小模型的工具调用只学会了「看到工具就调」或者「照抄工具名」。
Rune1-Preview 训练的重点是**判断**：

| 场景 | 期望行为 |
|---|---|
| 用户给了完整参数 | **直接调**，不要再问 |
| 用户漏了必填参数 | **反问**，不要瞎猜一个去试 |
| 两个工具都「能看文件」 | 按语义**选对**那个（按内容筛 vs 列目录） |
| 问题根本不需要工具 | **不调**，直接回答 |
| 调用报错了 | 读错误、**改对再来**，而不是放弃或硬编 |

## 二、验收数据（微调前 vs 微调后）

同一份基座权重，靠切换 adapter 跑两遍，27 条探针：

| 组 | 微调后 | 基座 |
|---|---|---|
| **判断力**（该不该调 / 要不要反问 / 选哪个） | **9/9** | 3/9 |
| 身份 | **3/3** | 0/3 |
| 留出沙箱（训练时从未见过的工具） | **6/6** | 6/6 |
| 已训沙箱 | **6/6** | 6/6 |
| 通用（问答 / 代码 / 拒绝） | **3/3** | 3/3 |
| **合计** | **27/27** | 21/27 |

**净增量 = 判断力 +6、身份 +3，合计 +9 项。**

其中有代表性的对比：

```
问：帮我看下目录里有什么文件。          （没给路径）
  微调后 → 「哪个目录？给我具体路径，我就去看。」   ✓ 反问
  基座   → 直接拿一个猜的路径去调了                  ✗

问：D:/inbox 里哪些文件提到 error？     （两个工具都能碰文件）
  微调后 → 调用搜索工具 seek_*                       ✓ 选对
  基座   → 调用列表工具 catalog_*                    ✗ 选错（但看起来"能跑"）
```

### 关于「留出沙箱」

**留出沙箱 = 训练时结构上不可能产出样本的沙箱**（生成器里直接抛异常拦截）。
它存在的意义是给「数据有没有泄漏」一个硬指标：
模型在那些**从未见过的工具名、路径、参数 schema** 上也能正确调用，
说明它学的是「读工具定义、按语义选」，而不是把训练时见过的名字背下来。

## 三、快速开始

### transformers

```bash
pip install "transformers>=5.18.0" torch accelerate
```

```python
from transformers import AutoProcessor, AutoModelForImageTextToText

model_id = "whcl412/FinchAI-Rune1-Preview-f16"
proc = AutoProcessor.from_pretrained(model_id)
model = AutoModelForImageTextToText.from_pretrained(
    model_id, dtype="bfloat16", device_map="auto")

tools = [{"type": "function", "function": {
    "name": "list_files", "description": "列出目录内容",
    "parameters": {"type": "object",
                   "properties": {"path": {"type": "string", "description": "目录路径"}},
                   "required": ["path"]}}}]

msgs = [{"role": "user", "content": "看下 /var/log 里有哪些文件。"}]
text = proc.apply_chat_template(msgs, tools=tools, tokenize=False,
                                add_generation_prompt=True)
out = model.generate(**proc(text=[text], return_tensors="pt").to(model.device),
                     max_new_tokens=256, do_sample=False)
print(proc.tokenizer.decode(out[0], skip_special_tokens=True))
```

**工具调用的输出格式是 XML：**

```
<tool_call>
<function=list_files>
<parameter=path>
/var/log
</parameter>
</function>
</tool_call>
```

思考内容走 `reasoning_content`（不在 `content` 里）。

### Ollama / llama.cpp

**尚未发布。** GGUF 转换本身已验证可行（llama.cpp 自 2026-10-17 起支持
`MiniCPMV4_7ForConditionalGeneration`），但导出的 GGUF **不含视觉能力**
（LoRA 只训了文本主干），与「最完整版本」的定位不符，因此暂不单独发布。

⚠️ **两个必须知道的限制**：

1. 我们**没有发布 MLX 4bit 版本** —— 底座架构 `minicpmv4_7` 不被 `mlx_lm` 支持
   （连最新 main 都没有）。Apple Silicon 用户请走 transformers，MPS 实测可用
   （训练峰值内存 6.5 GB）。
2. 全链路（加载 / 微调 / 融合）**只在 Apple Silicon 的 MPS 上验证过**，未在 CUDA 上实测。

## 四、能力边界

**擅长**
- 本地 agent 的「工具选择大脑」——判断该不该调、调哪个、参数够不够
- 读一份没见过的工具定义并按它调用
- 简短、不谄媚的中文/英文回答

**不擅长**
- 复杂多步推理和算法设计（1B 容量限制）
- 长文档理解（训练时序列 ≤950 token）
- 视觉任务——底座支持图像输入，但**本版 LoRA 只训了文本主干**，视觉能力未经强化

**实测性能**（MacBook Pro M4 / 16 GB，MPS）

| 项目 | 数值 |
|---|---|
| 权重体积 | 2.9 GB（bfloat16） |
| 加载后常驻内存 | ~3.1 GB |
| 训练/推理峰值 | ~6.5 GB |
| 训练速度 | 2.2~3.5 s/样本（≤950 token） |

**已知问题**

| # | 问题 | 规避 |
|---|---|---|
| 1 | 没有 MLX 4bit 版（底座架构不被 `mlx_lm` 支持） | Apple Silicon 走 transformers + MPS |
| 2 | 未发布 GGUF（转出来的不含视觉能力） | 要视觉就用本仓库的 f16 |
| 3 | 输出里偶发游离的 `</think>` 标签 | 宿主输出前过滤 |
| 4 | 思考文案带模板生成痕迹（如中英混排） | 不影响功能 |
| 5 | **偶发工具名幻觉**（吐出不在列表里的名字） | **宿主分发必须查注册表，绝不直接执行** |
| 6 | **工具结果不足时会编数字** | 让工具返回直接可得答案，别让它自己数 |
| 7 | 跨句式泛化有限 | 没见过的说法可能掉线 |
| 8 | 身份细节会补充编造 | 只采信「名字 + 底座」两项 |
| 9 | **工具的顺序会影响它选哪个** | 见下方说明 |

#### 关于第 6 条：工具结果不足时会编数字

如果工具返回的信息不足以回答，它可能**直接编一个结果**，而不是说"信息不够"。

实测：问「目录里有几个 `.gguf` 文件」，它只调了 `list_files`（返回的是目录列表），
却直接答「**有 269 个**」——它根本没数过（真实值是 20）。

**规避**：让工具的返回**直接可得答案**。例如不要指望它"从列表里数个数"，
而是提供一个 `count_files(pattern, path)` 这类专用工具。这是 1B 模型的可靠边界。

#### 关于第 9 条：工具的顺序会影响它选哪个

给同一组工具，**只换顺序、问题一字不改**，它的选择会变。

实测（工具：`get_weather` / `query_database` / `send_notification`）：

| 工具顺序 | 「查 users 表有多少条」 | 「给张三发通知」 |
|---|---|---|
| 天气, SQL, 通知 | ✗ 没调用工具 | ✓ |
| SQL, 天气, 通知 | ✓ | ✗ |
| 通知, SQL, 天气 | ✓ | ✗ |

**根因**：训练沙箱里工具顺序是固定的，模型学到了一点**位置先验**——
换一组语义完全不同的工具时，它不完全只看描述。

**规避**：
1. 把最可能被用到的工具**排在前面**
2. 一次只传相关的少数工具（工具越少选得越准）
3. 宿主侧校验结果，发现调了不相关工具就重试

**注意：这不是"必须用某个框架"** —— 工具仍然完全由调用方定义，模型没有内置工具，
只是对排列顺序比理想情况更敏感一些。

## 五、怎么训的（简述）

**沙箱式数据**：每个训练样本来自一个程序化生成的「沙箱」，包含独立的
工具名、参数 schema、路径风格、错误消息风格。任务是**真的去读工具定义**才能做对。

**Agent 分五个子类型**，这是模型价值的来源：

| 子类型 | 教什么 | 占比 |
|---|---|---|
| `single` | 标准两步调用 | 25% |
| `recover` | 撞错 → 读错误 → 改对重试 | 20% |
| `disambig` | 两个相似工具里按语义选对 | 20% |
| `no_tool` | 有工具但这个问题不该用 | 20% |
| `ask_back` / `ask_direct` | 缺参数才反问，给了参数就直接调 | 15% |

**防泄漏五层**：命名空间物理隔离 / 生成器硬拦截留出沙箱 / 渲染后 token 预算 /
渲染后文本审计 / 非 Agent 样本禁含沙箱标识符 —— 外加第六层「参数名必须属于该工具定义」。

**防遗忘**（增量训练时）：数据保持完整六类配比 + 学习率减半 + 只训 0.5 epoch。

## 六、局限与许可

- 底座 MiniCPM-V 4.7-1B 为 Apache 2.0，本模型沿用
- 这是 **Preview** 版本：判断力已达标（9/9），但句式泛化和拒绝场景仍在扩充
- 训练数据是**合成的**，用于教学/研究/自建 agent 均可，请自测后再用于生产

## 七、项目信息

```
权重    HuggingFace  whcl412/FinchAI-Rune1-Preview-f16
        ModelScope   whcl412/FinchAI-Rune1-Preview-f16
代码    GitHub       hwc-cell/FinchAI-Rune1-Preview
```
GitHub 仓库含训练脚本、数据生成器、验收脚本与 LoRA adapter。
训练数据为**程序化合成**（600 条），不使用任何真实用户数据。

---

*FinchAI 系列 · 训练于 Apple Silicon（transformers + PEFT + MPS）*