📚 Termux 无 Root 学习开发系列
阶段一：环境搭建与终端基础 ✅ 已完成
01-05 安装 → 包管理 → 文件管理 → Vim/tmux
阶段二：编程开发环境 ✅ 已完成
06-09 Python → C/C++ → Node.js → Git
阶段三：网络与远程操作 ✅ 已完成
10-12 SSH → 网络工具 → 网络代理
阶段四：Termux:API 与自动化 ✅ 已完成
13-14 硬件调用 → 定时任务
阶段五：proot-distro 完整 Linux ✅ 已完成
15-17 proot-distro → Jupyter → 桌面环境/VNC
阶段六：AI 与 AIGC 实战
✓ 18 调用 LLM API 对话与自动化
19 llama.cpp 本地模型推理（当前篇）
20 RAG 知识库与本地文档问答（待制作）
阶段七至九共 8 篇，后续持续更新
19 llama.cpp 本地模型推理
难度：高级 · 阶段六：AI 与 AIGC 实战 · 约 18 分钟阅读
读完本篇你将能：
- 在 Termux 中编译 llama.cpp（原生 + proot 两种方式）
- 下载 GGUF 量化模型并在手机上运行离线对话
- 掌握核心参数调优，适配手机性能
- 启动本地 API 服务，兼容 OpenAI 格式调用
上一篇我们用 API 调用云端大模型，体验虽好但有两个前提：要有网络、要花钱。llama.cpp 走另一条路——把模型塞进手机里，纯本地推理，断网也能用，token 消耗为零。代价是模型要小、速度要慢一些，但对于日常问答、代码辅助、知识库检索完全够用。
本篇从 llama.cpp 是什么讲起，手把手带你在 Termux 里编译、下载模型、跑通第一次对话，再到性能调优和本地 API 服务。全程离线，所有数据不出手机。
📖 本篇目录
01
llama.cpp 与 GGUF 简介
02
编译安装：Termux 原生方式
03
编译安装：proot Ubuntu 方式
04
模型选择与下载
05
运行推理与参数调优
06
本地 API 服务模式
01 llama.cpp 与 GGUF 简介
llama.cpp 是一个纯 C/C++ 实现的大语言模型推理引擎，由 Georgi Gerganov 发起，现在已迁移到 ggml-org 组织下开发。它的核心价值就是"轻"——不需要 GPU、不需要 Python 依赖、几百兆的二进制文件就能跑大模型。手机、树莓派、老电脑这些边缘设备，全靠它才能跑得起 LLM。
什么是 GGUF
GGUF（GGML Universal Format）是 llama.cpp 原生支持的模型文件格式。它的核心是量化——把原本 16 位或 32 位浮点数的模型权重，压缩成 4 位、5 位、8 位整数，体积减少 70% 以上，推理速度翻倍，而质量损失非常有限。
| 量化等级 |
体积（3B 模型） |
质量 |
推荐场景 |
| Q2_K |
~1.2 GB |
损失较大 |
内存极度紧张 |
| Q3_K_M |
~1.6 GB |
可接受 |
低配手机 |
| Q4_K_M ⭐ |
~2.0 GB |
接近 FP16 |
推荐，质量速度平衡 |
| Q5_K_M |
~2.4 GB |
很好 |
内存充足时选择 |
| Q8_0 |
~3.4 GB |
几乎无损 |
旗舰机且追求质量 |
💡 小贴士：K 系列量化是什么
K 系列（Q4_K_M、Q5_K_M 等）是 llama.cpp 特有的量化方案，"K"代表 k-quants。相比旧的 Q4_0 简单量化，K 系列用更精细的分组策略，在相同体积下质量更好。后缀 _M 代表 medium 平衡型，_S 代表 small 小体积，_L 代表 large 高质量。日常选 Q4_K_M 准没错。
02 编译安装：Termux 原生方式
Termux 原生编译的好处是不需要 proot 环境，直接在 Termux 主系统里跑，性能损耗最小。缺点是要手动装依赖，且不支持某些需要完整 glibc 的优化项。对大多数用户，原生方式已经足够。
Bash · Termux 原生编译
|
1
2
3
4
5
6
7
8
9
10
11
12
|
# 1. 安装编译依赖
pkg install clang cmake git make -y
# 2. 克隆仓库（已迁移到 ggml-org）
git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
# 3. 使用稳定版本（可选，推荐）
git checkout b10502 # 2026年8月最新构建
# 4. 编译（开启 OpenBLAS 加速）
cmake -B build -DGGML_OPENBLAS=ON
cmake --build build -j$(nproc)
# 5. 验证编译产物
ls build/bin/
llama-cli llama-server llama-bench ...
|
编译过程大约 5-15 分钟，取决于手机性能。如果 OpenBLAS 在 Termux 中安装失败，去掉 -DGGML_OPENBLAS=ON 用纯 CPU 编译也能跑，只是慢一些。
⚠️ 常见错误
git clone 速度慢或超时
✅ 用代理加速：export https_proxy=http://127.0.0.1:7890 后再 clone
编译时 OOM（内存不足被杀死）
✅ 减少并行数：cmake --build build -j 2，只用 2 线程编译
03 编译安装：proot Ubuntu 方式
如果你已经装好了 proot-distro（第 15 篇内容），在 Ubuntu 里编译更省心——软件源更全，OpenBLAS 等依赖直接 apt 安装即可，遇到问题搜索资料也更多。缺点是 proot 有少量性能损耗，大约比原生慢 10%-15%。
Bash · proot Ubuntu 编译
|
1
2
3
4
5
6
7
8
9
10
11
12
13
|
# 进入 Ubuntu 环境
proot-distro login ubuntu
# 1. 安装依赖
apt update &&& apt install -y \
build-essential cmake git \
libopenblas-dev libgomp1
# 2. 克隆并编译
git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
cmake -B build -DGGML_OPENBLAS=ON
cmake --build build -j$(nproc)
# 3. 把编译产物软链接到 ~/bin 方便调用
mkdir -p ~/bin && ln -s ~/llama.cpp/build/bin/llama-cli ~/bin/
|
💡 小贴士：选原生还是 proot
新手推荐proot Ubuntu 方式，依赖全、资料多，出问题好查。追求极致性能或不想装 Ubuntu 的用户用 Termux 原生方式。两者编译出的 llama.cpp 功能完全一致，只是性能有细微差别。本篇后续的运行命令两种方式通用。
验证编译结果
编译完成后，用 llama-bench 快速测试一下当前设备的推理性能，心里有个数。
Bash
./build/bin/llama-bench -m 模型路径.gguf -p 128 -n 128
# 输出会包含：
# encode: XX.XX tok/s （提示处理速度）
# decode: XX.XX tok/s （生成速度，关键指标）
decode 速度就是你聊天时模型"打字"的速度。手机上 1.5B 模型 Q4 量化通常能到 5-12 token/s，3B 模型大约 2-5 token/s。一般 5 token/s 以上体验就比较流畅了，低于 2 token/s 会明显感觉慢。
04 模型选择与下载
模型决定了 AI 的能力上限。手机端选模型就三个标准：中文好不好、体积够不够小、license 能不能商用/个人用。以下是目前（2026 年）最适合在手机上跑的几款模型。
推荐模型对比
| 模型 |
参数量 |
中文能力 |
Q4_K_M 体积 |
特点 |
| Qwen2.5-1.5B-Instruct |
1.5B |
优秀 |
~1 GB |
入门首选，速度快 |
| Qwen2.5-3B-Instruct ⭐ |
3B |
非常好 |
~2 GB |
质量速度平衡最佳 |
| Phi-3-mini-4k |
3.8B |
一般 |
~2.3 GB |
微软出品，英文强 |
| Llama 3.2-3B-Instruct |
3B |
一般 |
~2 GB |
Meta 出品，生态好 |
| Gemma-2-2B-it |
2.7B |
一般 |
~1.7 GB |
Google 出品，许可宽松 |
中文用户首选 Qwen2.5 系列，通义千问的小模型中文表现在同级别里是最好的。6GB 内存的手机选 1.5B，8GB 以上选 3B，12GB 以上可以试试 7B（Q4 量化约 4.5GB）。
下载模型
GGUF 模型文件主要从 Hugging Face 下载。推荐用 huggingface-cli 或直接 wget 下载单个文件。
Bash · 下载 Qwen2.5-1.5B-Instruct Q4_K_M
# 方式一：pip 装 huggingface-hub 后下载
pip install huggingface-hub
huggingface-cli download \
Qwen/Qwen2.5-1.5B-Instruct-GGUF \
qwen2.5-1.5b-instruct-q4_k_m.gguf \
--local-dir ~/models/
# 方式二：直接 wget 下载（国内可能需要代理）
mkdir -p ~/models && cd ~/models
wget https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct-GGUF/\
resolve/main/qwen2.5-1.5b-instruct-q4_k_m.gguf
💡 小贴士：国内下载加速
Hugging Face 在国内访问不稳定，可以用镜像站：把域名换成 hf-mirror.com 即可。例如 https://hf-mirror.com/Qwen/Qwen2.5-1.5B-Instruct-GGUF/resolve/main/...。
05 运行推理与参数调优
模型下载好了，终于可以跑起来了。llama.cpp 提供了两个主要工具：llama-cli 用于命令行对话，llama-server 用于启动 API 服务。先从 cli 开始，体验第一次本地对话。
第一次对话
Bash · 交互对话模式
|
1
2
3
4
5
6
7
|
./build/bin/llama-cli \
-m ~/models/qwen2.5-1.5b-instruct-q4_k_m.gguf \
-cnv \ # 对话模式（chat no verbose）
-t 4 \ # 线程数，设为 CPU 核心数
-c 2048 \ # 上下文长度（token）
--temp 0.7 \ # 温度，越低越确定
-p "你好，请简单介绍一下你自己"
|
运行后会先看到模型加载信息（加载耗时、模型大小、内存占用），然后开始生成回复。如果用了 -cnv 参数，进入对话模式后可以继续输入新问题，输入 /exit 退出。
核心参数调优
| 参数 |
作用 |
手机端推荐值 |
| -t, --threads |
推理使用的 CPU 线程数 |
CPU 核心数（如 8 核设 6-8） |
| -c, --ctx-size |
上下文窗口大小（token） |
2048（省内存）~ 4096 |
| -n, --n-predict |
最大生成 token 数 |
512（短对话）~ 2048 |
| --temp |
采样温度，0=确定性输出 |
0.7（平衡）~ 1.0（创意） |
| --top-p |
核采样，限制候选词范围 |
0.9 |
| -b, --batch-size |
提示词批处理大小 |
512（提示长时调大） |
| --mlock |
锁定模型在内存，防止被换出 |
内存充足时开启 |
手机性能优化技巧
🔥 性能优化清单
1. 线程数设为大核数：手机通常 4 大核 + 4 小核，用 -t 6 或 -t 8 测试哪个更快
2. 关闭其他后台应用：腾出更多 RAM，避免系统杀进程
3. 插电玩：推理耗电快，插电避免降频
4. 用 Q4_K_M 量化：质量和速度的最佳平衡点
5. 上下文别贪大：2048 token 足够日常对话，4096 会明显变慢
6. Termux 保持前台：按 Home 键后台可能被系统限制 CPU
06 本地 API 服务模式
命令行对话虽然直接，但和其他程序集成不方便。llama.cpp 提供了 llama-server，启动后就是一个本地 API 服务，兼容 OpenAI 的 /v1/chat/completions 接口。上一篇写的所有调用 DeepSeek API 的代码，只要把 base_url 改成本地地址，就能无缝切换到本地模型。
Bash · 启动本地 API 服务
|
1
2
3
4
5
6
7
8
|
./build/bin/llama-server \
-m ~/models/qwen2.5-1.5b-instruct-q4_k_m.gguf \
--port 8080 \
-t 6 \
-c 2048 \
--host "0.0.0.0" \ # 允许局域网访问
--parallel 2 # 并发请求数
# 启动后访问 http://localhost:8080 可看到管理页面
|
服务启动后，在 Termux 里开另一个终端或者用 curl 测试一下：
Bash · 用 curl 测试本地 API
|
1
2
3
4
5
6
7
8
9
10
|
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "qwen2.5-1.5b",
"messages": [{"role":"user","content":"1+1等于几"}],
"stream": false
}'
# 返回 JSON 格式与 OpenAI 完全一致
# {"choices":[{"message":{"content":"1+1 等于 2。"}}]}
|
与上一篇的 AI 助手无缝切换
上一篇写的 ai_chat.py，把初始化客户端的 base_url 改成 http://localhost:8080/v1，api_key 随便填个字符串（本地服务不验证），就从云端 API 切换成本地模型了。代码一行都不用改。
Python · 本地模型版 AI 助手
client = OpenAI(
api_key="local", # 本地模型不需要真实 key
base_url="http://localhost:8080/v1"
)
# 其余代码完全不变！
💡 小贴士：服务常驻后台
想让 llama-server 一直在后台跑？用 tmux（第 05 篇学过）开一个 session 运行服务，需要时 attach 回去查看日志。但要注意 Android 后台限制——屏幕关闭后 Termux 可能被系统降速或杀死，建议配合 termux-wake-lock 获取 CPU 唤醒锁。
✏️ 分级练习
🟢 基础验证
跑通第一次本地对话
编译 llama.cpp（任选原生或 proot 方式），下载 Qwen2.5-1.5B-Instruct Q4_K_M 模型，使用 llama-cli 进行一次交互对话，向模型提问"什么是 GGUF 量化"，记录回复和推理速度（token/s）。
💡 参考解法：git clone → cmake 编译 → 下载模型 → ./llama-cli -m 模型路径 -cnv -p "什么是GGUF量化"，从终端输出中找到 eval time 行计算 token/s。
🟡 组合应用
本地 API + Python 脚本调用
启动 llama-server 本地 API 服务，用 Python 的 openai SDK 调用本地模型（base_url 指向 localhost:8080/v1），写一个脚本：读取一个 Python 文件内容，让本地模型解释这段代码的功能，并将解释结果保存到 explanation.md 文件中。要求：1）使用流式输出逐字打印；2）服务和脚本都在 Termux 中运行；3）验证本地模型确实不联网也能工作（关闭 WiFi 测试）。
💡 参考解法：llama-server 启动后，上一篇的 stream_chat 函数几乎不用改，只改 base_url 和 api_key。读取文件用 pathlib，保存结果用 write_text。
🔴 开放挑战
性能对比实验报告
设计一个性能对比实验，在你的手机上测试以下变量对推理速度的影响：1）不同量化等级（Q2_K vs Q4_K_M vs Q5_K_M vs Q8_0，同一模型同一大小）；2）不同线程数（2/4/6/8 线程）；3）不同上下文长度（512/2048/4096 token）。用 llama-bench 或自行编写测试脚本测量 decode 速度（token/s）和内存占用，将结果整理成 Markdown 表格，并撰写 300 字以内的结论说明在你的设备上最优配置是什么。思考：为什么线程数增加到一定程度速度不再提升？为什么上下文越长速度越慢？
提示：可以用不同大小的同系列模型近似对比，也可以用同一模型不同量化等级精确对比。用 /usr/bin/time -v 或 termux-battery-status 辅助测量内存和电量消耗。
🏷️ 知识回顾
llama.cpp
GGUF 量化
Q4_K_M
Qwen2.5
cmake 编译
llama-cli
llama-server
本地 API 服务
OpenAI 兼容
离线推理
性能调优
📬 下一篇预告
第 20 篇：RAG 知识库与本地文档问答——本地模型虽好但知识是固化的，RAG（检索增强生成）让模型能读取你的本地文档。从文档切分、向量嵌入到 ChromaDB 向量库，再到检索+生成的完整流程，手把手搭建你自己的离线知识库问答系统。
关注系列，持续更新中 · 点赞在看支持作者