koboldcpp Android 部署：在手机上离线跑 AI 模型完整指南
【免费下载链接】koboldcppKoboldCpp - Run GGUF AI models locally with a KoboldAI UI. One File. Zero Install.项目地址: https://gitcode.com/gh_mirrors/ko/koboldcpp
高铁上、飞机上，或者进了没信号的地方，想让 AI 继续干活又不依赖云端，可以试试 koboldcpp 的 Android 部署。它在手机上本地运行 GGUF 大模型，装完就能断网对话、写作，数据不出设备。下面带你从零装好并生成第一段内容。
先跑起来：从零到第一次生成
动手前 30 秒，过一遍这张清单
- 存储：留出 8GB 以上空闲，光模型文件就要好几个 G
- 系统：Android 8.0 及以上
- 网络：安装阶段要有网拉依赖和模型，装完可以离线用
- 架构：ARM64 的安卓手机
四项都满足再往下走，缺一项就先补齐。
一条命令装好 koboldcpp
在 Termux 里取得安装脚本 android_install.sh，然后执行：
sh android_install.sh脚本会自动检查依赖、拉取源码、编译并下载默认模型。交互菜单一共 6 个选项：带默认模型装、不带模型装、从 URL 下模型、加载本地模型、重新编译、退出。新手直接选第一项，脚本会用 Gemma3-1B 作为起步模型，装完自动启动。
打开界面，生成第一段
- 编译下载完成后，手机浏览器打开 http://localhost:5001
- 在输入框里写一句提示词
- 点提交，等待首 token
- 看到连续输出的文字，就成功了
这个界面是 koboldcpp 内置的 KoboldAI Lite WebUI，断网时一样可用。
三个关键决策：模型、参数、文件从哪来
模型选多大的才跑得动
手机内存有限，起步别贪大：
- 首选 Gemma3-1B，也就是安装脚本默认拉的那个，内存占用最小
- 内存富余可上 Gemma3-4B，体验更好
- 量化级别认准 Q4_K_M 或 Q5_K_S，再高的量化对手机意义不大
- 7B 及以上先放下，多数手机带不动
内存和线程怎么调
启动参数都在 koboldcpp.py 里，常用的三个：
| 参数 | 作用 | 建议 |
|---|---|---|
| --contextsize | 上下文长度（token 数） | 内存吃紧就调小，默认 8192 |
| --threads | 计算线程数 | 设成手机大核数量，别拉满 |
| --batchsize | 批处理大小 | 内存吃紧就调小，默认 512 |
三个默认值都能跑，先别动；卡了再按上表逐项收。
模型文件的三种拿法
- URL 直下：选脚本的「从 URL 下模型」，直接贴 GGUF 下载链接
- 本地加载：先装好程序，再用 --model 参数指向手机里的 GGUF 文件
- 离线传输：在电脑上把 GGUF 下好，用数据线拷进手机，再走「加载本地模型」
python koboldcpp.py --model /path/to/model.gguf这条命令用来手动喂模型，适合前面选了「仅装程序」的情况。
两个最常见的坑，先绕开
编译报错、手机发烫
编译阶段手机 CPU 会满负荷，天热时容易降频甚至中断。两个动作：
- 别用多核编译，装好后若需重建，走单线程
- 报错就先清理再重编
make clean && make -j 1⚠️ 编译时别边跑边刷别的应用，留散热余量。
模型下载太慢
弱网下手机直接拉模型很慢。更稳的做法是在电脑上把 GGUF 下完整，再用数据线拷到手机，最后走脚本的「加载本地模型」。手机只负责运行，不负责下载。
想继续深入，看这几处
- koboldcpp.py：主程序入口，所有启动参数在这里
- android_install.sh：安卓安装脚本，菜单逻辑都在这
- Makefile：编译规则，改编译选项看这里
更多细节查 README.md 的 Android（Termux installation）章节，那是官方文档入口。
装好之后还能换别的 GGUF 模型、在 Web 界面切换对话模式，甚至加载图像生成模型玩 StableUI。
觉得有用就点个收藏，下一篇讲怎么把速度再提一档。
【免费下载链接】koboldcppKoboldCpp - Run GGUF AI models locally with a KoboldAI UI. One File. Zero Install.项目地址: https://gitcode.com/gh_mirrors/ko/koboldcpp
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
