# 本地模型

使用 GGUF 模型文件和 llama.cpp 直接在 Android 设备上运行 LLM。无需网络，无需 API 密钥，完全私密。

## 工作原理

Agora 通过 Android NDK (CMake) 捆绑 llama.cpp。当你导入 GGUF 文件时，模型完全在设备 CPU 上运行——数据不会离开设备。

## 要求

- 仅 **GGUF 格式** 模型（llama.cpp 的标准格式）
- **设备内存**：模型必须能装入可用 RAM。经验法则：
    - 1–3B 参数模型：4–6 GB RAM
    - 7–8B 参数模型：6–8 GB RAM
- **存储**：GGUF 文件大小从 ~500 MB（量化小模型）到 5+ GB

!!! warning
    本地推理是 CPU 密集型的，远比云端 API 慢。最适合离线使用、隐私敏感内容或实验——不适合快速、高量的聊天。

---

## 导入聊天模型

1. 将 GGUF 模型文件下载到设备（见下方推荐来源）
2. 前往 **设置 → 提供商**
3. 选择 **Local** 作为提供商
4. 点按 **导入 GGUF 模型**
5. 从设备中选择 `.gguf` 文件
6. 配置模型：

| 参数 | 描述 | 示例 |
|-----------|-------------|---------|
| **模型 ID** | 小写标识符，无空格 | `qwen3-8b` |
| **别名** | 显示名称 | `Qwen 3 8B` |
| **上下文大小** | 最大上下文窗口（tokens） | `4096` |
| **温度** | 随机性（0.0–2.0） | `0.7` |
| **Top P** | 核采样阈值（0.0–1.0） | `0.9` |
| **最大 Token** | 最大生成长度 | `2048` |

7. 点按 **添加**

模型导入后立即可用。

---

## 导入嵌入模型

嵌入模型更小，用于语义搜索：

1. 前往 **设置 → 对话搜索**
2. 点按 **添加本地模型**
3. 选择 `.gguf` 嵌入模型文件
4. 命名
5. 点按 **添加**

详见 [嵌入 / RAG](embedding.md) 的搜索设置。

---

## 选择活跃模型

导入一个或多个模型后：

1. 前往 **设置 → 提供商 → Local**
2. 你会看到列出的所有导入的模型
3. 点按想要使用的模型旁边的**单选按钮**
4. 当聊天提供商选择 **Local** 时，选中的模型生效

---

## 管理本地模型

### 重命名

点按模型更改其别名或调整参数（温度、上下文大小等）。

### 删除

长按模型并点按**删除**。这会从 Agora 中移除模型并从存储中删除 GGUF 文件。

---

## 推荐模型

### 聊天模型

| 模型 | 大小 | RAM 需求 | 备注 |
|-------|------|------------|-------|
| Qwen 3 1.7B | ~1 GB | 3–4 GB | 尺寸下质量好 |
| Llama 3.2 3B | ~2 GB | 4–5 GB | 扎实的全能型 |
| Qwen 3 8B | ~5 GB | 7–8 GB | 最佳质量，高 RAM |

### 嵌入模型

| 模型 | 大小 | 备注 |
|-------|------|-------|
| BGE Small EN v1.5 | ~130 MB | 好的英文嵌入 |
| BGE Small ZH v1.5 | ~130 MB | 中文优化 |
| Nomic Embed Text v1.5 | ~270 MB | 好的多语言 |

### GGUF 文件来源

- [Hugging Face](https://huggingface.co/models?library=gguf) — 搜索 "GGUF"
- [bartowski 的量化模型](https://huggingface.co/bartowski) — 选择广泛，组织良好

!!! tip
    寻找 `Q4_K_M` 量化——它为聊天模型提供质量与大小的最佳权衡。

---

## 性能建议

- **更小的上下文 = 更快**：从 2048 开始，仅在需要时增加
- **更低量化 = 更快**：Q4_K_M 比 Q6_K 或 Q8 快
- **关闭其他应用**：本地推理需要尽可能多的 RAM
- **接通电源**：推理是 CPU 密集型的，长时间使用会严重消耗电池
