本地模型¶
使用 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 慢。最适合离线使用、隐私敏感内容或实验——不适合快速、高量的聊天。
导入聊天模型¶
- 将 GGUF 模型文件下载到设备（见下方推荐来源）
- 前往 设置 → 提供商
- 选择 Local 作为提供商
- 点按 导入 GGUF 模型
- 从设备中选择
.gguf文件 - 配置模型：
| 参数 | 描述 | 示例 |
|---|---|---|
| 模型 ID | 小写标识符，无空格 | qwen3-8b |
| 别名 | 显示名称 | Qwen 3 8B |
| 上下文大小 | 最大上下文窗口（tokens） | 4096 |
| 温度 | 随机性（0.0–2.0） | 0.7 |
| Top P | 核采样阈值（0.0–1.0） | 0.9 |
| 最大 Token | 最大生成长度 | 2048 |
- 点按 添加
模型导入后立即可用。
导入嵌入模型¶
嵌入模型更小，用于语义搜索：
- 前往 设置 → 对话搜索
- 点按 添加本地模型
- 选择
.gguf嵌入模型文件 - 命名
- 点按 添加
详见 嵌入 / RAG 的搜索设置。
选择活跃模型¶
导入一个或多个模型后：
- 前往 设置 → 提供商 → Local
- 你会看到列出的所有导入的模型
- 点按想要使用的模型旁边的单选按钮
- 当聊天提供商选择 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 — 搜索 "GGUF"
- bartowski 的量化模型 — 选择广泛，组织良好
Tip
寻找 Q4_K_M 量化——它为聊天模型提供质量与大小的最佳权衡。
性能建议¶
- 更小的上下文 = 更快：从 2048 开始，仅在需要时增加
- 更低量化 = 更快：Q4_K_M 比 Q6_K 或 Q8 快
- 关闭其他应用：本地推理需要尽可能多的 RAM
- 接通电源：推理是 CPU 密集型的，长时间使用会严重消耗电池