Termux+llama.cpp：Android手机本地部署Llama3-8B Q4量化模型全攻略

1. 项目概述：为什么要在手机里跑本地大模型

1.1 这个项目到底在做什么

把一个大语言模型完整塞进手机，让它离线也能回答问题、写总结、处理文本——这件事我前后迭代了好几轮，最终稳定跑通的方案就是 Termux + Python + llama.cpp + Llama3-8B 的 Q4 量化版。这篇笔记是从零到一的全过程记录，包括环境搭建、模型下载、编译运行、Python 封装，还有我在真实设备上踩过的所有坑，尽量做到让你照着操作就能跑通。

标题里写的"万字图文学习笔记"并不夸张。网上关于 Termux 装 Python、装各种工具包的教程很多，但真正把"本地大模型"这件事讲完整、讲清楚、讲得能照做的，基本是零散的碎片。有的只讲命令行交互，有的挂着服务器的名义讲手机端，很少有文章把手机端从编译到调用的一条完整链路串起来讲。这篇就是补这个空缺的：你只需要一台 Android 手机和一点耐心，就能拥有一台离线的大模型问答终端。

1.2 为什么不用联网 API

很多人第一反应是：手机上直接调云端 API 不就行了吗？确实，ChatGPT、Kimi、文心一言这类云端服务体验很好，但有几类场景它们解决不了。首先是隐私敏感场景，比如把公司文档、个人日记、会议纪要喂给云端模型做总结，数据出网本身就让人不踏实。其次是稳定性，地铁、山区、地下车库，网络一断，云端模型瞬间变废。最后是成本，高频调用 API 一个月算下来并不便宜，本地部署属于一次性投入、长期免费，而且没有账号和额度限制。

本地部署的体验当然和云端服务有差距，推理速度慢、上下文短、模型能力也没那么强，但它的核心价值也很明确：数据完全在设备内处理，断网可用，不经过任何第三方服务器。我自己的定位不是让它替代云端，而是作为"离线兜底 + 隐私优先"的补充方案。最常用的场景就是出差路上把会议录音转成文字后，用本地模型做摘要、列待办，全程不用连网，心里踏实。

1.3 适合谁参考

如果你满足下面任意一条，这篇笔记就值得看完：第一，手里有台内存不小于 8GB（建议 12GB）的 Android 手机，想试试本地大模型但不知道从哪下手；第二，已经会用 Termux 装一些基础包，但没碰过大模型的编译部署；第三，在 PC 上跑过 llama.cpp 或 Ollama，想在手机端复现一套；第四，纯粹对"大模型能不能在消费级硬件上跑"这件事好奇。PC 用户也完全可以参考，整个流程几乎一致，只是编译参数和存储路径有些差异，我会在对应位置单独说明。

2. 方案选型：模型、量化格式与运行框架

2.1 为什么选 Llama3-8B

先交代选型逻辑。手机本地跑大模型，模型的参数量是第一约束。7B-8B 这个级别是目前消费级设备的甜点区：比它小的如 1.5B-3B，资源占用低但中文能力和指令跟随都明显拉胯，生成的文本经常前言不搭后语；比它大的如 14B 及以上，在手机上基本跑不动，除非你的手机有 24GB 内存且愿意忍受每秒几个 token 的速度。Llama3-8B 是 Meta 开源的 8B 模型，基座能力在同量级里是第一梯队，而且社区生态特别成熟：量化版、微调版、各种格式的权重都很齐全，后续想换模型接着玩非常方便。

这里要说明一点：Llama3 原版对中文的支持不如英文好，毕竟训练数据以英文为主。但配合 Q4 量化后的 Instruct 版本，日常对话、摘要、改写、简单代码生成这些任务完全够用，只是别指望它写古诗词或者深挖中文成语典故。如果你是中文高要求用户，后面可以无缝换成 Qwen2.5-7B、DeepSeek-R1-Distill-Qwen-7B 这类中文友好的 GGUF 模型，流程完全一样，只把模型文件换掉就行。这也是我在标题里点明"轻量文本生成模型"的原因——这个方案本质上是一套框架，模型是可替换的。

2.2 Q4 量化到底做了什么

大模型的权重默认是 FP16 精度，一个 8B 模型光权重就需要约 16GB 存储，手机根本装不下。量化就是把权重从 16 位浮点压缩到更低的位宽。Q4 表示用大约 4 bit 来表达每个权重，存储直接缩到四分之一左右：8B 模型 Q4 后大约 4.5-5GB，内存占用也随之下降，手机才可能跑得动。代价是模型精度略有损失，但 4-bit 量化在文本生成任务上的质量损失很小，属于性价比极高的取舍。

具体到 GGUF 里的 Q4 系列，又分 Q4_0 和 Q4_K_M 等版本。我强烈推荐 Q4_K_M：它是所谓 K-quants 混合量化方案的中档选项，大部分权重用 4-bit，部分对模型影响大的层保留更高精度，综合表现最均衡。纯 Q4_0 文件更小但质量略差，Q5_K_M 质量更好但文件多 1GB 左右。在手机上，Q4_K_M 基本是 8B 模型的最优解：文件 4.92GB，运行时再叠加 KV cache 和系统开销，整机内存至少需要预留 7-8GB，这也是我强调 12GB 内存手机优先的原因。你在网上看到的"Llama3-8b-Q4"这个称呼，指的就是这么一坨东西。

2.3 运行框架三选一：llama.cpp、Ollama、llama-cpp-python

现在主流的本地推理框架有三个：llama.cpp、Ollama、llama-cpp-python。llama.cpp 是纯 C/C++ 实现，用 CPU 就能跑，对 Android 这种资源受限的环境非常友好，支持 ARM 指令集优化，是手机端的首选底层引擎。Ollama 在 PC 上非常省心，拿来即用，但它对底层细节封装得太死，出了问题不好排查，在 Termux 里的安装路径也别扭。llama-cpp-python 是 llama.cpp 的 Python 绑定，可以理解成一个 Python 库形式的封装，既能复用底层引擎，又方便写自己的业务逻辑。

所以我的技术路线很明确：底层用 llama.cpp 作为推理引擎，一方面用它的命令行工具直接验证模型，另一方面通过 llama-cpp-python 在 Python 脚本里调用同一套引擎。这样既能快速跑通完整链路，又能灵活扩展成自己的小工具。整个链条完全开源、完全本地、不依赖任何云端服务。实际部署下来，编译一次 llama.cpp 大约十分钟，后面任何 GGUF 模型都能复用这套环境，边际成本很低。

2.4 硬件门槛：手机需要什么配置

我用一张表整理三种档位的真实体验，方便你对照自己的设备判断：

除了内存，CPU 和散热也很关键。手机端是 CPU 推理，主要看单核性能和散热能力。骁龙 8 系、天玑 9000 系这类旗舰芯片，Q4 模型大约每秒能生成 5-10 个 token；中端芯片可能只有 2-4 个 token。所谓"能跑"和"好用"是两回事，每秒 3 个 token 和每秒 8 个 token 的耐心成本完全不在一个量级。另外持续高负载会让手机发热，发热后系统自动降频，速度会进一步下降，所以跑长任务时把手机放在通风处、垫个金属片或者上散热背夹，差别很大。存储方面，模型文件接近 5GB，建议至少预留 10GB 空间，且把模型放在 /sdcard 公共存储，避免挤爆 Termux 的内部数据分区。

3. Termux 环境搭建与基础配置

3.1 安装 Termux 的正确途径

Termux 是一个 Android 上的终端模拟器，本质上是在手机上提供了一个 Linux 环境。很多人装 Termux 第一坑就踩在渠道上：Google Play 商店里的版本已经停更很久，装出来的环境跑不了新包，一堆依赖报错。正确做法是去 F-Droid 应用商店下载，或者去 Termux 的官方 GitHub Releases 页面拿最新的 APK 文件安装。注意 F-Droid 版和 GitHub 版的内部数据目录有差异，选定一个渠道装好以后就别混用，不然容易绕晕。

安装完成后打开，会进入一个类似 Linux shell 的界面，默认是$提示符。第一次启动需要一点时间初始化，装完基础文件后就可以执行命令了。这里提醒一句：Termux 的默认数据目录在应用内部，卸载应用或清数据都会把你的整个环境抹掉，所以后面的大文件模型建议放在 /sdcard 公共存储里，环境本身坏了可以重装，模型文件不能跟着陪葬。

3.2 包管理器换源与系统升级

Termux 使用 pkg 命令管理软件包，底层调用的是 apt 机制。装机第一件事就是更新软件源和升级所有包：

pkg update && pkg upgrade -y

这一步会更新源索引并升级系统包。网络环境一般的话，这一步可能会比较慢，可以换成国内镜像源。做法是编辑$PREFIX/etc/apt/sources.list文件，把官方源地址替换成你所在地区访问速度好的镜像地址。换源后重新执行pkg update验证一下。注意别把桌面 Linux 的那套源直接套进来，Termux 的源结构和目标平台都不一样，要用专门给 Termux 维护的镜像目录，否则一堆包版本对不上。

升级完成后再安装必要的基础工具。我会在下一步把 Python 和编译工具链一起装，这里先确认pkg工作正常即可。实测下来，pkg upgrade有时候会提示某些包需要手动处理，按提示pkg install补装就行，不用慌。

3.3 存储权限与基础工具链

Termux 默认只能访问自己的内部数据目录，访问不了手机相册、下载目录等公共存储。需要先执行：

termux-setup-storage

这条命令会在系统里触发存储权限请求，允许之后会生成~/storage目录。其中~/storage/downloads对应用户的 Download 目录，~/storage/shared对应整个公共存储根目录。模型文件我习惯放在/sdcard/Download/gguf/下，后面在 Termux 里的访问路径就是~/storage/downloads/gguf/xxx.gguf。

接下来安装 Python 和编译工具链：

pkg install python git cmake make clang binutils -y

这条命令一次装齐了 Python、Git、CMake、Make、Clang 编译器和二进制工具。llama.cpp 在 Android 上的编译主要靠 CMake + Make + Clang 这套组合，缺了任何一个都可能编译到一半报错。装完可以用python --version和clang --version分别验证安装是否成功。这一步是后面所有操作的基础，建议装完顺手执行一遍两个版本命令，别等到编译报错了才回来查。

4. Python 运行环境与依赖安装

4.1 确认 Python 版本与 pip

Termux 的 python 包目前默认装的是 Python 3.11 或更高版本，装完直接可用。先确认版本：

python --version pip --version

这两条命令如果都正常输出版本信息，说明 Python 和 pip 都就绪了。如果没有 pip，执行python -m ensurepip或者pkg install python-pip补一下。Termux 环境比较干净，没有桌面 Linux 那些复杂的环境冲突问题，Python 这块反而省心。

需要提醒的是，Termux 里 pip 默认安装的包是全局生效的。后面我们要装 llama-cpp-python、numpy 这类体积较大的包，建议先建一个虚拟环境，把项目依赖和系统环境隔离开。这样出问题可以整个环境删掉重来，不会污染基础环境，尤其是编译过 C 扩展的包，卸载不干净很常见，虚拟环境是最省心的沙箱。

4.2 编译工具链安装

上一节装的 clang、cmake、make、binutils 就是 Python 扩展包的编译基础。因为 llama-cpp-python 在安装时需要现场编译 C++ 扩展，如果工具链不完整，pip 安装会直接报编译器找不到或者 CMake 相关错误。这一点非常多人忽略——表面看是安装一个 Python 包，实际过程是在编译一个底层的 C 库，C++ 编译环境不齐全，安装必然失败。

编译工具链装好后，可以先测试安装一个 numpy，提前把编译链路验证一遍：

pip install numpy

numpy 的安装很快，如果有现成的 wheel 缓存就是秒装；如果走源码编译，也能顺便测试你的编译环境是否正常。这一步跑通了，后面装 llama-cpp-python 就心里有底了。如果 numpy 安装报错，先别急着换源，回头看 clang、cmake、make 是否真的装成功，八成是工具链的问题。

4.3 虚拟环境与 Python 依赖

建议在 Termux 里建一个独立虚拟环境：

python -m venv ~/llm-env source ~/llm-env/bin/activate

激活后命令行提示符前面会出现(llm-env)字样，表示已经进入虚拟环境。后面所有 Python 操作都在这套环境里进行，退出用deactivate命令。虚拟环境放在 Termux 内部目录就行，不建议放在 /sdcard 上：公共存储是 FUSE 文件系统，Python 的某些操作会明显变慢，文件权限也有坑。模型文件放 /sdcard 是没问题的，因为它只是被读取，环境本身还是放内部存储更稳。

在虚拟环境里先更新 pip，然后再装一遍基础依赖：

pip install --upgrade pip pip install numpy

这一步跑完，Python 侧的环境准备就结束了。接下来进入真正的重头戏：下载模型和编译推理引擎。

5. 模型获取：Llama3-8B Q4 GGUF 下载与校验

5.1 GGUF 格式与量化文件说明

llama.cpp 生态使用的模型格式是 GGUF，它是专为大模型设计的单文件格式，把权重、分词器、超参数全部打包在一个文件里，拷贝和加载都非常方便。llama.cpp 早些年用的是 GGML 格式，后来升级成 GGUF。你要是翻到老教程里说的 .bin 或 .ggml 文件，那是旧时代的产物，别再用。现在主流模型库提供的都是 GGUF 文件，兼容性最好。

Llama3-8B 的 GGUF 文件不需要你自己去量化，直接用社区做好的成品就行。Meta 官方开源的是 FP16 原版权重，体积约 16GB，量化的脏活累活社区里已经做得很成熟了。以 Hugging Face 上有关 Llama3-8B Instruct 的 GGUF 仓库为例，里面通常会提供多个量化版本：Q2_K、Q3_K_M、Q4_0、Q4_K_M、Q5_K_M、Q6_K、Q8_0 等。文件名里的数字越低，文件越小、推理越快、质量损失越大。手机上推荐 Q4_K_M，也就是项目标题里"Llama3-8b-Q4"所指的典型版本。

5.2 模型下载与文件放置

在 Termux 里下载模型有两种方式。第一种直接在手机浏览器里打开模型页面下载，这种方式最直观，适合不熟悉命令行的朋友。第二种是在 Termux 里用 wget 下载，好处是可以断点续传、命令行校验。命令行下载示例：

cd ~/storage/downloads mkdir -p gguf cd gguf wget -c https://huggingface.co/TheBloke/Llama-3-8B-Instruct-GGUF/resolve/main/llama-3-8b-instruct.Q4_K_M.gguf

有些网络环境访问海外站点不太稳定，如果下载失败或速度太慢，可以到国内的模型社区（比如魔搭 ModelScope）搜索同款模型的 GGUF 版本，国内服务器下载体验会好很多。另外现在不少模型在多个平台同时发布，GitHub Releases、ModelScope、Hugging Face 都有分发，选择自己网络环境最顺畅的渠道就行。下载过程我建议用电脑下载好再通过数据线拷贝到手机，或者手机浏览器直接下载都行。文件约 4.92GB，下载前确认手机剩余空间足够。

5.3 文件校验与存储路径

模型下载完不要急着跑，先做完整性校验。模型文件很大，下载中断、磁盘写入异常、断点续传出错都很常见，如果硬加载大概率报错或生成乱码。校验方法是在下载页面里找到对应的 SHA256 哈希值，然后在 Termux 里计算本地文件的哈希并比对：

sha256sum llama-3-8b-instruct.Q4_K_M.gguf

哈希值一致说明文件完整，可以放心使用；不一致就删除重新下载。这个操作虽然多花一分钟，但能避免后面排查半天发现其实是文件损坏这种冤案。模型路径我建议固定在一个位置，比如~/storage/downloads/gguf/llama-3-8b-instruct.Q4_K_M.gguf，后面所有命令都用这个绝对路径，别反复移动。路径一变，前面写的脚本、命令全部要跟着改，纯属给自己添麻烦。

6. 核心实操：编译 llama.cpp 并运行模型

6.1 拉取源码与编译

这是整个项目最核心的一步。先把 llama.cpp 源码拉下来：

cd ~ git clone https://github.com/ggerganov/llama.cpp cd llama.cpp

源码拉下来后，用 CMake 构建。Termux 环境下默认走 CPU 推理，不需要指定 CUDA 之类的选项。编译命令如下：

cmake -B build -DCMAKE_BUILD_TYPE=Release cmake --build build --config Release -j4

-j4表示用 4 个并行任务编译。手机核心多的话可以改成-j8，但编译本身非常吃内存，老机型并行开太高可能直接内存耗尽被系统杀掉。编译时间取决于手机性能，旗舰机大约 5-10 分钟，中端机可能要 20 分钟以上。编译完成后，可执行文件在build/bin/目录下，核心的是main和server两个。main是命令行推理工具，server可以起一个 HTTP 服务，手机浏览器直接访问对话界面，这个后面可以玩。

如果你不想用 CMake，llama.cpp 也支持直接make -j4，效果类似。但我个人建议走 CMake 构建路径：Termux 环境下 CMake 能更好地处理依赖查找和平台适配，报错信息也更规范，出问题在网上更容易搜到相同的解决方案。

6.2 首次命令行推理与参数解析

编译完成后，先跑一次最简单的命令行推理验证模型：

./build/bin/main -m ~/storage/downloads/gguf/llama-3-8b-instruct.Q4_K_M.gguf -p "请用一句话介绍你自己" -n 128

这里解释几个关键参数：-m指定模型文件路径；-p指定输入提示词；-n指定生成 token 数量上限，128 表示最多输出 128 个 token。首次加载模型时，终端会显示读取权重、分配 KV cache 等过程信息，模型加载完成后开始逐字生成。你能非常直观地看到手机推理的速度——每个 token 打印出来，快慢一眼便知。

如果这一步正常输出文本，恭喜，核心链路已经打通。此时可以调整更多参数体验不同效果。常用参数包括：--temp控制生成随机性，0.7 左右比较通用；--top-p控制采样范围，默认 0.9；-c指定上下文长度，默认 512，手机内存不充裕时不要开太大；-n控制单次生成的 token 数。参数搭配的本质是平衡质量和资源占用，跑长文本时把上下文调小，能明显降低内存压力，这是手机端最实用的调优手段。

6.3 交互式聊天模式

命令行单次生成只适合验证，真正日常使用需要多轮对话能力。llama.cpp 的 main 程序支持--interactive交互模式：

./build/bin/main -m ~/storage/downloads/gguf/llama-3-8b-instruct.Q4_K_M.gguf -c 2048 --interactive --temp 0.7

进入交互模式后，输入内容回车即发送给模型，模型会基于之前的所有对话内容继续生成。这个模式能让模型记住上下文，但有个关键细节：交互模式下要正确设置对话模板。Llama3 的 Instruct 版本有固定的对话格式，main 程序会尝试自动设置，但如果发现输出格式不对，比如模型把你的输入原样复述而不是对话式回应，就需要手动通过-p给出完整的模板格式，或者在提示语中明确角色设定。这一步在命令行里调通后，后面的 Python 封装就有参照基准了。

7. Python 脚本封装：打造自己的本地对话程序

7.1 安装 llama-cpp-python

命令行能跑通只是第一步，真正把这套能力变成自己的工具，还是得靠 Python。llama-cpp-python 是 llama.cpp 的 Python 绑定，安装方式很简单：

pip install llama-cpp-python

默认会从 PyPI 拉源码，然后在你本机编译。因为我们前面已经装好了完整的编译工具链，这一步正常情况能顺利通过。编译耗时几分钟，耐心等。如果安装时报错，最常见的原因就是编译环境缺失，回到第 4 节检查 clang、cmake、make 是否装好。

有一点提前说明：llama-cpp-python 会把一份内置的 llama.cpp 一起编译进来，所以它并不依赖第 6 节手动编译的那份源码，两者可以共存。Python 绑定的版本和你手动编译的版本可能略有差异，但推理结果基本一致，不需要纠结。如果你以后想升级 llama.cpp 的版本，pip 重新安装