这个附录是给谁的收录读者最可能卡住的问题按主题分组。每条都给直接可用的答案并附上去这一章看。使用建议遇到问题时先在这里搜一下关键词比如构建失败“ANR”“乱码”。如果这里没有再看每章末尾的常见错误与排查表。C.1 开始之前Q1我完全没写过代码能学这本书吗能但要调整预期。情况建议完全没写过代码先读附录 A补编程常识、命令行、字节/编码再回来读 ch01写过一点Python/JS/Excel 宏等可以直接读 ch01遇到不懂查附录 A/B写过 Java/其它面向对象语言ch03 可以快速过关键本书的 ch01–ch03第一部分就是专门给零基础打地基的。不要跳。Q2学完这本书要多久不做时间承诺因人而异但给一个节奏参考部分章节特点第一部分 起步ch01–ch03慢读这几章决定后面顺不顺第二部分 应用开发ch04–ch12与 Android 开发主线重合第三部分 原生与推理ch13–ch19最硬C/JNI/推理循环可能要反复读第四部分 工程化ch20–ch23相对轻松偏流程不要追求读完。追求每章都能动手验证成功——这比读完 23 章有价值得多。Q3需要什么电脑配置项建议内存16 GB 更稳编译 llama.cpp 吃内存8 GB 会吃力磁盘预留 30 GB 以上SDK/NDK/CMake 构建产物 模型文件系统Windows / macOS / Linux 都可以本书命令以 Windows 为例手机一台 arm64 安卓真机模拟器跑大模型很吃力⚠️关于手机本书的 ABI 是arm64-v8a。如果你想用模拟器需要额外配置见 ch20 6.(4)。Q4我要懂机器学习吗不需要。你只需要理解 ch01 讲的三个词词一句话量化把模型压小别人做好的不是你做的GGUF模型文件的格式推理给文字猜下一个字你不需要知道Transformer 的数学、不需要会训练模型。你要做的是用一个训练好的模型就像用一台冰箱不需要懂制冷原理。Q5这本书的代码都能跑吗分三种情况每章代码块都标了标记含义能跑吗✅取自工程、已编译验证能但要先按 ch02 把环境装好⚙️取自工程、未在上板运行源码真实存在但行为依赖设备/模型示例需自行验证要你自己确认通常是教学用的简化片段看到 就说明作者没替你验证过——不要直接当结论。C.2 环境与构建Q6gradlew报命令找不到原因你没在llama.android目录下执行。# ❌ 错在别的地方执行cdllamacpptest gradlew :app:assembleRelease# ✅ 对先 cd 进 llama.androidcdllamacpptest\llama.android gradlew :app:assembleRelease也可能Windows 下要用gradlew.bat或者.\gradlew。在 PowerShell 里推荐写.\gradlew.bat。详看ch02 2.5.1Q7构建报SDK location not found原因local.properties没写或路径写错了。排查# 文件在哪、内容是什么Get-Contentllamacpptest\llama.android\local.properties正确写法二选一sdk.dirC:/dev/Android/Sdk ← 推荐正斜杠最省心 sdk.dirD\:\\Environment\\Android\\Sdk ← 或者反斜杠要转义成 \\⚠️常见错误写成C:\dev\Android\Sdk单个反斜杠——properties 文件里反斜杠是转义字符会被解析错。详看ch02 2.3.1Q8构建很慢几分钟这是正常的。因为要编 llama.cpp 的几百个文件。情况大约耗时首次构建2 分钟以上要编全部 C增量构建只改 Kotlin几十秒只改 C1–2 分钟想提速方法说明用clang -fsyntax-only校验 C几秒不用完整构建ch13只编 Kotlingradlew :app:compileDebugKotlin约 20–30 秒不要加--no-daemon加了会构建失败见 Q9详看ch02 2.7、ch20Q9构建报journal-1.lock (拒绝访问)原因你给gradlew加了--no-daemon。因为常驻的 Gradle daemon 已经持有这个锁--no-daemon又 fork 了一个新进程来争抢。解决# 方案一去掉 --no-daemon推荐gradlew :app:assembleRelease# 方案二先停掉残留 daemongradlew--stopgradlew :app:assembleRelease这是本书特意强调的坑ch02 坑 1、ch21 第 6 节。很多教程/工具会习惯性加--no-daemon在本工程会直接失败。Q10构建报Unsupported ABI或 CMake 找不到报错原因解决CMake 3.31.6 was not foundCMake 没装sdkmanager cmake;3.31.6ch02No toolchains found/NDK not foundNDK 没装或版本不符sdkmanager ndk;29.0.13113456ch02Unsupported ABI: xxxCMakeLists 没处理这个 ABI改abiFiltersch20.6.2add_subdirectory ... not foundLLAMA_SRC路径层数不对按自己目录结构数ch20、ch23.5Q11Gradle 报一堆版本不兼容AGP/compileSdk/库核心认知ch02compileSdk/ AGP / AndroidX 库的版本是互相牵制的。怎么读这类报错别被前面几行吓住找requires和Current两个词。1. Dependency androidx.lifecycle:lifecycle-runtime:2.11.0 requires compileSdkVersion to be set to 37 or higher. Current compileSdkVersion is 36. ↑ 它要什么 ↑ 你现在是什么解法要么按 ch02 的版本表对齐要么全不升。不要先升一半。C.3 代码理解Q12MainScreenState.kt有 1132 行从哪读不要从第一行读。按 ch09 的职责分区读① 类的声明与依赖:69-86 ← 先看它持有什么 ② 状态清单:88-144 ← 再列出它管什么 ③ 会话相关:456-543 ← 一块一块看 ④ 聊天主流程:771-893 ← 核心 ⑤ 取消与清理:902、:1059 ← 收尾 ⑥ 常量:1095-1131 ← 最后看细节读长文件的通用方法先看文件头注释本工程注释写得很好只看函数签名fun xxx(...)那一行跳过函数体画出结构图哪几个函数、谁调谁再挑你关心的那几块深入。详看ch09 全章Q13Kotlin 语法看不懂先明确一点本项目只用 Kotlin 的一个子集。你不需要学完整本 Kotlin 书。按这个顺序查你看到的去查val/varch03.2?./?:/!!ch03.3data class/copych03.4by委托ch03.5、ch09objectch03.7whench03.8suspend/Flowch08Composablech06然后给ModelInfo加一个字段并编译通过ch03.9 的动手验证——这是检验真的学会了的最好方式。Q14Flow/协程完全没概念ch08 是全书第一个难点一遍没懂很正常。建议的读法① 先看 ch08 的本章导读餐厅上菜类比 ② 只看 8.3Flow 是什么 8.5取消 ③ 跑 ch08 的动手验证纯 Kotlin不用 Android ④ 回头看 8.2调度器和 8.4flowOn ⑤ 再读 8.6 那个事故catch 不重抛核心记住三句话Flow 一串随时间陆续到达的值emit发射、collect接收取消是协作式的cancel 只是打标记代码要有检查点。详看ch08Q15JNI 那一章完全看不懂先接受一件事JNI 代码很繁琐但概念不难。只要理解三件事#要点1Kotlin 用external fun声明实现在 C2C 函数名必须拼成Java_包_类_方法否则找不到3C 侧所有 JNI 方法第一行加锁保护全局状态然后做 ch13 的动手验证加一个nativeAdd(a, b)并调通。只要看到nativeAdd(3,4) 7被打印出来你就通了。详看ch13Q16ai_chat.cpp里的 llama.cpp API 我不认识你不用认识全部。本工程只用了十几个 API。必记的 6 个API作用章节llama_model_load_from_file加载模型ch15llama_init_from_model建上下文KV cachech15llama_batch_init/common_batch_add准备一批 tokench16llama_decode真正的计算ch16common_sampler_sample采样出下一个 tokench16/ch19llama_model_free/llama_free释放ch15其余的用到再查或者看 ch14 认识它的目录结构就够了。记住 ch14 的核心llama.cpp 是只调用不修改的第三方。C.4 运行与调试Q17App 装上但一打开就闪退按这个顺序排查检查怎么查① 看 logcatadb logcat找FATAL EXCEPTION或E开头的行② 如果是UnsatisfiedLinkError库没打进去 / ABI 不对ch13、ch20③ 如果是ClassNotFoundExceptionManifest 的.MainActivity与包名不一致ch04.3.4④ 如果是 C 崩溃无 Java 堆栈看ai-chattag 的日志可能是 use-after-freech15⚠️ 特别注意C 崩溃不会变成 Java 异常——logcat 里只有一堆内存地址tombstone。这是 ch13 强调的跨边界出错就是崩溃。Q18界面卡住不动可能 ANR原因几乎总是在主线程做了耗时操作。现象原因章节点发送后界面冻住生成跑在主线程ch08要Dispatchers.Default退出时卡一下onCleared里同步卸载模型ch09/ch10用cleanupScope加载模型时界面不响应加载跑在主线程ch15/ch08要Dispatchers.IO记住这条规则ch08主线程只干两件事更新 UI、响应用户操作。一切耗时的活都丢到后台。Q19模型加载失败 / 加载很慢现象原因File not found/Cannot read file路径不对 / 没权限UnsupportedArchitectureException模型架构不支持或文件损坏Failed to prepare resourcescontext/sampler 建不起来内存不够加载要几十秒正常几 GB 的文件要读ch15.3.2 的 mmap 也有首次缺页开销排查过滤InferenceEngineImpl和ai-chat的日志看走到哪一步。详看ch15Q20生成很慢每秒几个字这是物理限制不是 bug。影响因素说明手机 CPU本工程跑在 CPU 上ch01.2.4模型大小7B 比 1.5B 慢很多n_threads本工程取核数−2最多 4ch15.4.1上下文长度越长越慢prefill 更久想看具体速度用设置页的推理基准测试ch01 见过的benchModel看tg每秒 token。Q21中文输出出现乱码方块这是 ch16.5 讲的 UTF-8 被切断问题。确认方法看是不是偶尔出现一个或几个方块而不是全乱。如果是——就是 token 把汉字切成了两半。修复用 ch16.5 的 UTF-8 缓存cached_token_charsis_valid_utf8。自检在is_valid_utf8的两个分支加日志你会偶尔看到UTF8 PENDING——那就是拦截到了半个字符。Q22生成第二个字就停 / 一直不结束现象原因章节生成一个字就停stop_generation_position设错了ch16.2.3一直不结束没判断 EOG / 没设上限ch16.4.6点停止没用缺取消检查点ch08.5、ch10.2Q23多轮对话第二轮开始胡说 / 只输出数字这就是 ch17 那个经典事故。先确认是不是第 1 轮正常、从第 2 轮起不正常是 → 去看 ch17根因是按长度切片求增量导致的 24 字节偏移。自检看chat_add_and_format的日志第 2 轮的增量应该完整包含你的问题而不是被截断。Q24聊久了输出变乱这是 ch18 讲的位置错乱。特征需要聊到上下文顶满本工程 8192 token才出现而且一旦出现就持续之后每轮都错。为什么难查不报错——llama_decode不检查位置合理性ch18.5。对策ch18 练习 5加位置不变量检查current_position ≤ n_ctx。Q25怎么调试 C 代码四条路按推荐顺序方法什么时候用clang -fsyntax-only改完先验语法几秒ch13.9LOGd/LOGi/LOGe打日志用adb logcat -s ai-chat看纯逻辑模拟位置/算法类问题ch22真机 tombstone真崩溃时adb logcat里搜DEBUG⚠️ 注意LOGvverbose在很多设备上默认不输出调试时用LOGd更稳。C.5 模型相关Q26模型文件去哪找本书不能给你下载链接版权/时效问题但可以告诉你去哪找渠道说明Hugging Facehuggingface.co搜模型名 GGUF最主流ModelScopemodelscope.cn国内速度快模型作者官方仓库有些会直接提供 GGUF搜索关键词模型名 GGUF例如Qwen2.5 GGUF、Hy-MT2 GGUF。选量化版本内存紧张 →Q4_K_M本工程测试用的就是 Q4_K_M想要质量更好、内存够 →Q5_K_M/Q6_K/Q8_0。详看ch01.2.2量化、ch14.5FileType 枚举Q27我的手机能跑多大的模型用 ch15.5 的公式估算内存总内存 ≈ 模型文件大小 KV cache KV cache ≈ 2 × 层数 × n_ctx × (KV头数×每头维度) × 2 字节快速估算表Q4 量化、8K 上下文模型文件大小KV cache总需1.5B约 1 GB约 0.3 GB约 1.3 GB3B约 2 GB约 0.6 GB约 2.6 GB7BMHA约 4 GB约 4 GB约 8 GB⚠️8BGQA约 4.7 GB约 1 GB约 5.7 GB⚠️注意 7B MHA 的 KV cache 就有 4 GBch15.5.3 算过。而手机还要给系统和别的 App 留内存。所以 8 GB 内存的手机跑 7B 很勉强。建议从小模型开始1.5B–3B 的 Q4 模型先在手机上跑通再往大的试。Q28模型太大装不进手机 / 导入失败问题解决手机存储不够用更小的量化Q3/Q4或更小的模型导入中途失败看 ch10可能残留半成品要清理导入后加载失败内存不够KV cache 建不起来注意导入会把模型拷贝到 App 私有目录ch10所以需要两份空间原文件 副本。可以先删掉原文件再导入吗不行——导入时源文件还要用。Q29模型不进 APK 吗不进。这是刻意的ch01.1.3原因说明体积模型 GB 级进 APK 用户下载不了不联网本 App 不联网所以不能自动下载用户自己选用户从文件选择器导入ch12所以发布 APK 只有 97 MB 左右ch21模型另外给用户。C.6 关于学习本身Q30读完一遍还是记不住正常吗完全正常。而且记住不是目标。真实的学习过程是第 1 遍知道有这么个东西能看懂名词 第 2 遍知道它在哪、干什么用能定位 第 3 遍知道为什么这么做、不这么做会怎样能理解 动手做 1 次真的会了 讲给别人听 1 次再也忘不掉所以不要指望一遍就懂但一定要动手第 4 步是分水岭讲给别人听是终极检验能讲清说明真懂。Q31我应该按顺序读吗大致按顺序但可以调整你的情况建议路线完全零基础ch01 → ch02只求跑通别纠结报错→ch03慢读→ ch04…按顺序会别的语言没写过 Androidch01 → ch02 → ch03快过→ ch04 → ch06 → ch09 → ch13 → ch14 → ch16尽早打通能出字→ 再回头补会 Android想搞懂端侧推理ch01只看架构和规模→ ch13 → ch14 → ch15 → ch16 → ch17 → ch18 → ch19 → ch22详看ch01.7.3Q32哪些章可以跳过建议不要跳这几章它们是地基章为什么不能跳ch03 Kotlin不然后面所有 Kotlin 代码都看不懂ch04 Android 骨架不然后面不知道 App 怎么跑起来ch08 协程与 Flow不然后面流式输出完全没法理解ch22 诊断方法论不然后面遇到问题只能靠猜可以快速浏览的章为什么ch05 资源系统日常开发用不到那么深遇到再回来看ch21 签名发版不发布的话可以先跳过Q33读完能自己做一个类似的 App 吗能但要注意两点① 你会具备的能力本书 ch01.7.2 列过搭 Android NDK 环境并出包用 Compose 写界面、用 ViewModel 管状态用协程/Flow 处理流式数据读写 GGUF、改 JNI 与推理循环从零复刻一个最小可用版本。② 但换个模型/换个需求仍需适应换模型 → chat template 不同ch17 的教训换功能 → 需要自己设计ch23 的加回顺序是方法论。关键本书教的不只是这个 App 怎么做还有**“遇到没做过的事怎么下手”**ch22/ch23。后者才是能带走的能力。Q34下一步该学什么按你的兴趣选方向学什么为什么深入 AndroidFragment、Navigation、Room、WorkManager、测试本书只覆盖了 Compose ViewModel 这一支深入 Compose自定义 Layout、动画、性能优化、Preview/测试本书只讲了基础深入推理llama.cpp 源码、GPU/NPU 加速、更多量化格式本书只调用不改深入工程化CI/CD、自动化测试、多模块、依赖注入本书只讲了一次性发版做完整产品多语言、无障碍、埋点、崩溃收集、上架流程从能跑到能卖推荐的第一步把 ch23 的最小版真的做出来然后按 23.10 的顺序加功能。做完这个你就从读者变成了开发者。Q35我卡住了怎么办按这个顺序① 查本附录 CFAQ ② 查该章末尾的常见错误与排查表 ③ 查附录 B术语表确认你没理解错某个词 ④ 用附录 A 的学习姿势A.9检查方法 ⑤ 用 ch22 的五步框架自己排查 复现 → 隔离变量 → 最小对照实验 → 修正 → 回归 ⑥ 实在不行把问题最小化—— 能不能用最简单的输入复现能不能只保留几行代码最有用的一招把问题最小化。一个能稳定复现的 20 行代码比我的项目不行有用一万倍。这是 ch22 讲的最小对照实验的日常版。C.7 一句话速查最常见的 12 个坑现象一句话答案章节gradlew找不到要先cd到llama.androidch02SDK location not foundlocal.properties用正斜杠ch02journal-1.lock拒绝访问去掉--no-daemonch02桌面图标没变minSdk 33 走自适应图标要换ic_launcher_foreground.webpch05界面不刷新要产生新对象copy不能原地改ch03/ch09ANR / 界面卡死耗时活要丢到后台线程ch08错误提示看不见catch没重抛后续代码覆盖了它ch08生成的字有乱码方块UTF-8 被 token 切断要加缓存ch16第二轮开始胡说增量拼接错位24 字节ch17聊久了输出乱位置错乱要同步基准ch18参数改了不生效六环链路某环断了最常见是推送那环ch19APK 声称支持 x86_64 但用不了半残切片去掉注入参数ch20下一份附录 D《速查索引》——按主题和按工程文件两种方式定位内容。