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 硬件门槛手机需要什么配置我用一张表整理三种档位的真实体验方便你对照自己的设备判断手机内存能否运行实际体验6GB不建议内存不足容易加载失败或被系统杀进程8GB勉强能跑 Q4但需要降上下文、开 Swap速度慢12GB推荐Q4 流畅运行可同时开少量应用16GB舒适可以尝试更长上下文甚至更大模型除了内存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 版本与 pipTermux 的 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 numpynumpy 的安装很快如果有现成的 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_TYPERelease cmake --build build --config Release -j4-j4表示用 4 个并行任务编译。手机核心多的话可以改成-j8但编译本身非常吃内存老机型并行开太高可能直接内存耗尽被系统杀掉。编译时间取决于手机性能旗舰机大约 5-10 分钟中端机可能要 20 分钟以上。编译完成后可执行文件在build/bin/目录下核心的是main和server两个。main是命令行推理工具server可以起一个 HTTP 服务手机浏览器直接访问对话界面这个后面可以玩。如果你不想用 CMakellama.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 重新安装 
长河君 · 2026/9/10 7:07:14 · 阅读 1.2k 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 硬件门槛手机需要什么配置我用一张表整理三种档位的真实体验方便你对照自己的设备判断手机内存能否运行实际体验6GB不建议内存不足容易加载失败或被系统杀进程8GB勉强能跑 Q4但需要降上下文、开 Swap速度慢12GB推荐Q4 流畅运行可同时开少量应用16GB舒适可以尝试更长上下文甚至更大模型除了内存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 版本与 pipTermux 的 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 numpynumpy 的安装很快如果有现成的 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_TYPERelease cmake --build build --config Release -j4-j4表示用 4 个并行任务编译。手机核心多的话可以改成-j8但编译本身非常吃内存老机型并行开太高可能直接内存耗尽被系统杀掉。编译时间取决于手机性能旗舰机大约 5-10 分钟中端机可能要 20 分钟以上。编译完成后可执行文件在build/bin/目录下核心的是main和server两个。main是命令行推理工具server可以起一个 HTTP 服务手机浏览器直接访问对话界面这个后面可以玩。如果你不想用 CMakellama.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 重新安装