Samsung Edge AI Training端侧 LLM / 小模型量化部署工程课

一日工程课 · 09:00-17:00

端侧模型量化部署技术专题

从端侧部署共同语言、Qwen/GGUF 量化证据、低比特/KV 质量归因，到 Runtime/Local API 验收、Jetson/移动端迁移和最终报告。

288页 · 6 个工程专题

8×5页闭环 / 专题

Qwen2.5-0.5BGGUF 实作主线

9节部署评估报告

QwenGGUFllama.cppQ8/Q5/Q4ProfilingLocal APIFinal Report

专题 01 · 核心概念

学完后要能做三类工程判断

判断能不能端侧化

说清目标设备、隐私边界、延迟要求和质量阈值。
知道哪些任务适合本地，哪些需要云端兜底。

判断哪种量化可用

用同源 Qwen/GGUF 跑 baseline、Q8 / Q5 / Q4。
同时比较质量、速度、内存和日志 warning。

判断能不能交付

把 runtime、profiling、local API 和风险写进报告。
推荐、回退或暂不推荐都要能被证据复核。

专题 01 · 证据图表

一天课程按六个工程专题推进

端侧共同语言与准入001-040

Qwen/GGUF 量化证据041-080

低比特/KV 质量归因081-120

修复/压缩/微调决策121-160

Runtime/API 验收161-200

Jetson/移动端与报告201-240

专题 01 · 课堂实作

今天的实作主线是一条可复现部署链路

从 Qwen2.5-0.5B-Instruct GGUF baseline 起步，先确认模型能在本地稳定输出
用 Q8 / Q5 / Q4 做同源对比，记录质量、速度和内存
用 profiling 和本地 API 验证它能否进入应用
最后写成推荐、回退或暂不推荐

~/edge-ai-lab/
├── models/qwen/qwen2.5-0.5b-instruct-q4_k_m.gguf
├── logs/qwen2.5-0.5b-instruct-q4_k_m-completion.log
├── results/quant_compare.csv
└── report/final-report.md

专题 01 · 证据图表

课程网站被压成六个课堂专题

网站内容	一日课专题	课堂交付
导读 + Part I/II	端侧部署共同语言与环境准入	场景、指标、设备画像、日志字段
Part III + Part VI	Qwen/GGUF Baseline 与 PTQ/QAT 量化证据	baseline log、Q8/Q5/Q4 实验单
Part III + 样例日志	低比特 LLM、KV Cache 与质量归因	方法矩阵、低比特失败样例
Part III + Part IV	精度修复、压缩蒸馏与 LoRA/QLoRA 决策	修复路径、训练去留判断
Part V + Part VI	Runtime、Profiling 与 Local API 验收	瓶颈定位、服务化 smoke test
Part VI + Part VII	Jetson/移动端迁移、VLM/Agent 与最终报告	迁移风险、最终部署评估报告

专题 01 · 核心概念

上午先把问题和量化证据立住

1. 共同语言与准入

先写清目标设备、场景约束和端云边界。
环境快照决定今天能跑哪条路线。

2. Qwen 量化证据

先跑通同一 Qwen/GGUF 和同一 runtime。
Q8/Q5/Q4 只允许在固定条件下比较。

3. 低比特质量归因

把权重、激活、KV Cache 和生成质量分开记。
GPTQ/AWQ 进入方法边界，不替代主实验。

专题 01 · 核心概念

下午把质量、Runtime 和端侧迁移闭环

4. 修复与训练决策

先定位质量下降是不是量化造成的。
再判断回退、混精、蒸馏或 LoRA/QLoRA。

5. Runtime/API 验收

模型格式、backend、kernel 和服务接口分层验证。
profiling、bench 和 server log 一起入报告。

6. Jetson/移动端与报告

区分 Ubuntu baseline、Jetson 实测和移动端路线图。
VLM/Agent 只在报告里扩展系统边界。

专题 01 · 证据图表

每个专题都按同一套五页闭环讲

先提出工程问题问题框架

再给必要概念核心概念

用表格或流程压实变量证据图表

进入命令、日志和样例课堂实作

最后回到报告字段风险与报告

专题 01 · 课堂实作

课堂实作只允许改变一个主变量

固定 prompt / --ctx-size / --seed 和采样参数
固定 runtime commit、构建参数、offload 和设备状态
每次只改变一个量化版本、backend 或服务化参数
证据不足时只能写“未验证”，不能写推荐

# 只切换 -m 模型文件，其余参数逐字不变
./build/bin/llama-completion \
  -m ~/edge-ai-lab/models/qwen/qwen2.5-0.5b-instruct-q4_k_m.gguf \
  -p "用三句话解释端侧模型量化的价值。" \
  -n 128 --ctx-size 2048 --temp 0.2 --seed 42 \
  -ngl 99 -cnv -st --no-display-prompt --perf

专题 01 · 风险与报告

进入量化实验前先完成准入检查

不能直接进入实验

目标设备、系统版本和 runtime 来源没记录。
baseline 还不能稳定输出固定 prompt。
没有日志路径，后面无法复核性能或质量。

下一专题准入门槛

报告第 1-2 节草稿已完成。
设备表、模型表、指标表和实验单已建立。
Qwen/GGUF baseline 可以开始同条件对比。

专题 01 · 问题框架

目标场景先决定端侧路线

同一个 Qwen 小模型，放在手机、PC、车载、摄像头、Jetson 或本地服务器里，验收口径会完全不同。

课堂追问 这次实验到底代表哪一种真实使用场景？

专题 01 · 核心概念

场景地图要覆盖设备和使用边界

个人设备

手机、PC、本地工作站强调交互延迟、权限和离线体验。
要写清哪些数据留在本地，哪些允许端云协同。

边缘终端

车载、IoT、摄像头更关心弱网、功耗、温度和长期稳定性。
持续流、传感器输入和恢复策略要进入验收。

实验与网关

Ubuntu GPU、Jetson、本地服务器适合建立 baseline 和迁移证据。
不能把开发机结果直接写成所有端侧设备可用。

专题 01 · 证据图表

场景约束决定第一轮证据

场景	硬约束	第一轮证据
本地助手 / PC 工具	首 token、格式稳定、隐私文件不外发	固定 prompt、TTFT、tokens/s、local API log
车载 / IoT / 摄像头	弱网、低功耗、温度、连续运行	设备状态、功耗温度、失败恢复记录
Jetson / 边缘网关	统一内存、GPU offload、部署维护	JetPack、tegrastats、Qwen GGUF baseline

专题 01 · 课堂实作

每个小组先写一张场景画像

目标用户、输入数据、输出格式和失败后果
目标设备、系统版本、内存和可用 runtime
隐私、离线、首 token、tokens/s 和稳定性阈值
允许本地、云端兜底或必须人工确认的边界

课堂验收 画像要能直接生成实验单

写不出约束和阈值，就不能判断 Q4 是否可用，也不能解释为什么需要本地推理。

专题 01 · 风险与报告

场景画像不足会让后续实验失真

失败样例

在服务器上测出 Q4 快，就推断手机和摄像头也快。
只写“保护隐私”，但没有列出哪些字段不能外发。
没有定义质量阈值，后面无法判断量化退化是否可接受。

报告落点

报告第 1 节: 场景、任务和端侧必要性
报告第 2 节: 目标设备和 runtime 约束
第 7 节: 未测设备、端云协同和隐私风险

专题 01 · 问题框架

先拆开一次请求，后面指标才可比

量化、KV Cache、runtime 和 profiling 都会改变不同阶段；不拆 tokenize、prefill、decode 和服务开销，速度结论就会混在一起。

课堂追问 同一个模型，为什么首 token 慢但 tokens/s 还可以？

专题 01 · 核心概念

三组词决定后续指标是否可比

输入契约

messages、chat template、tokenizer、ctx-size。
模板错了，模型能跑但质量不可信。

生成阶段

prefill 处理 prompt，decode 逐 token 生成。
TTFT 和 tokens/s 不能混成一个速度数字。

运行资源

weights、activations、KV Cache、runtime buffers。
权重量化不等于 KV Cache 自动变小。

专题 01 · 证据图表

Qwen 请求不是一行 prompt

messageschat 输入

chat template格式化

tokenizer编码

prefillTTFT

KV Cache显存/内存

decodetokens/s

detokenize解码

API / CLI output最终输出

专题 01 · 课堂实作

第一轮 baseline 必须记录推理字段

messages / prompt 文件和 chat template
prompt tokens、ctx-size、生成 token 数
prompt eval time、eval time、tokens/s
峰值内存、warning、fallback 日志

# llama.cpp stderr 会直接打印这几行，逐字段抄进日志
llama_print_timings: prompt eval time = N ms /  N tokens
llama_print_timings:        eval time = N ms /  N runs
llama_print_timings:               total time = N ms

专题 01 · 风险与报告

推理字段缺失会让量化对比失真

失败样例

只记录输出文本，没有 prompt token 数。
只记录 tokens/s，没有 prompt eval time。
chat template 换了，却继续比较量化质量。

报告落点

报告第 3 节: Baseline 输入契约
报告第 4 节: Q8/Q5/Q4 对比条件
报告第 5 节: prefill/decode profiling

专题 01 · 问题框架

端云协同要先写清路由证据

端侧部署不是只选本地或云端；真正要决定的是每条请求为什么留在本地、为什么允许兜底、为什么必须确认或拒绝。

课堂追问 这条请求的路径能否被日志复核？

专题 01 · 核心概念

路由先按隐私、复杂度和风险分三类

必须本地

隐私原文、离线场景、低延迟控制面。
结果不达标时也不能直接上传原文。

脱敏后兜底

复杂 reasoning、长上下文、开放问答。
只上传允许字段、摘要或用户确认内容。

确认或拒绝

高风险工具、外发数据、不可逆动作。
本地模型只能给建议，不能越权执行。

专题 01 · 证据图表

路由表必须能被日志字段复核

判断条件	默认路径	日志字段
包含隐私原文、图片或本地文件	本地处理，必要时只上传脱敏摘要	sensitivity、redaction、upload_allowed
短指令、格式化、摘要草稿	端侧小模型优先	route=local、latency、quality_check
复杂推理或长上下文	云端或大模型兜底	fallback_reason、uploaded_fields
高风险工具或外发动作	确认后执行或拒绝	confirm_required、policy_result

专题 01 · 课堂实作

每条请求都要留下路由判定

request_id、请求类型、敏感等级和上传许可
本地模型、质量检查、超时阈值和延迟
fallback 触发原因、上传字段和脱敏结果
最终响应来源、拒绝原因或人工确认记录

最小验收 三条样例覆盖本地、兜底和拒绝

只有架构图没有日志，不能证明端云协同真的可上线；报告里必须放样例路径。

专题 01 · 风险与报告

fallback 失败通常败在边界没写清

失败样例

低质量本地结果直接返回，没有触发兜底。
fallback 上传了原始敏感内容，报告里没有边界说明。
本地和云端输出格式不一致，应用层无法稳定处理。

报告落点

第 1 节: 哪些数据必须留在本地
第 7 节: fallback、隐私和未测风险
第 8 节: local-first、hybrid 或暂不推荐

专题 01 · 问题框架

baseline 前先完成环境准入

环境准入不是证明机器够强，而是决定今天能跑 Ubuntu GPU、Jetson、CPU-only，还是只能写移动端路线图。

课堂追问 哪些证据缺失时，结果只能写“未验证”？

专题 01 · 核心概念

环境准入分成三类证据

设备证据

OS、CPU、RAM、GPU 或 Jetson 型号。
Jetson 还要记录 JetPack/L4T、功耗模式和散热条件。

工具链证据

Python、Git、CMake、CUDA、llama.cpp commit。
确认 llama-cli、llama-bench、llama-server 是否构建成功。

模型证据

模型来源、许可证、文件大小、SHA256。
日志目录、命令输出和报告字段要能对应。

专题 01 · 证据图表

准入结果决定今天能跑哪条路线

准入结果	今天可以做	报告必须标注
CUDA + llama.cpp + Qwen GGUF 都可用	baseline、Q8/Q5/Q4、profiling、local API	commit、hash、CUDA/offload 日志
只有 CPU 或 GPU 后端不可用	CPU baseline、API smoke test、报告结构	GPU offload 未验证，速度不代表目标设备
Jetson 可登录但构建不完整	JetPack、tegrastats、环境预检	Qwen 迁移未完成，不能写推荐
模型文件或 hash 不清楚	停止量化对比，先补模型清单	模型来源未确认，结果不可复查

专题 01 · 课堂实作

环境快照要能直接粘进报告第 2 节

OS、CPU、RAM、GPU / Jetson、Driver / CUDA / JetPack
Python、Git、CMake、llama.cpp commit
模型来源、许可证、文件大小、SHA256
日志路径、构建日志、API 端口和绑定地址

# Ubuntu Server：一条命令生成可直接粘贴的环境记录
{
  date; uname -a; lscpu | head -n 30; free -h; df -h
  python3 --version; git --version; cmake --version
  nvidia-smi || true; nvcc --version || true
} | tee ~/edge-ai-lab/env/ubuntu-env.txt

专题 01 · 风险与报告

环境准入没过只能标未验证

失败样例

llama-server 没构建，却临时把 API 章节跳过。
以为在跑 GPU，日志里其实没有 offload。
模型文件换过，但报告里仍用旧 hash 和旧 baseline。

报告落点

第 2 节: 环境和模型证据
第 7 节: 未测、fallback、构建失败风险
附录: 环境日志、构建日志、模型清单

专题 01 · 实验口径

变量控制单是进入量化实验的门票

专题一结束前，学员要先写清模型、输入、运行和日志字段。没有这张单，Q8/Q5/Q4 的差异只能算运行现象，不能算部署证据。

课堂追问 如果 Q4 看起来更快，怎么证明只改了量化文件？

专题 01 · 核心概念

三类变量先锁定，第四类结果再记录

模型

base model、量化格式、文件来源、size、SHA256。
Q8/Q5/Q4 必须来自同一基座，不能混用不同 tokenizer。

输入

prompt、ctx-size、生成长度、temperature、seed。
课程默认先用同一 prompt 跑通，再增加边界 prompt。

运行

llama.cpp commit、-ngl、threads、backend、设备状态。
内存不足可以调 ctx-size，但所有版本必须一起调。

专题 01 · 证据图表

比较表要同时写条件和结果

表格列	课堂最低字段	不能省略的原因
模型条件	model_path、quant_type、size、sha256	证明 Q8/Q5/Q4 同源，避免把不同模型混成量化差异。
输入条件	prompt_id、ctx-size、n_predict、seed	质量现象必须能按同一输入复跑。
运行条件	commit、backend、-ngl、threads、device_state	解释 GPU offload、CPU fallback、温度或功耗造成的变化。
结果证据	TTFT、tokens/s、memory、quality_note、log_path	最终报告只能引用可追溯数字和样例。

专题 01 · 课堂实作

第一张实验单只允许量化档位变化

三行模型: Q8、Q5、Q4 或教师提供的同类变体
同一输入: prompt、ctx-size、生成长度、采样参数
同一运行: llama.cpp commit、backend、-ngl、threads
同一证据: stderr timing、监控日志、输出样例、日志路径

# parse_llama_log.py 把 stderr timing 抽成一行 CSV，字段名不能自己改
python3 labs/scripts/parse_llama_log.py run-q4.log \
  --append results/quant_compare.csv

# 追加后的表头（源自脚本 PATTERNS 字典，逐字段可追溯）
log,load_time_ms,prompt_eval_time_ms,prompt_eval_tokens_per_s,eval_time_ms,eval_tokens_per_s,total_time_ms

专题 01 · 风险与报告

变量漂移要写进失败记录

失败样例

Q4 因内存不足改成 ctx-size 1024，Q8 仍用 2048。
一次运行实际 fallback 到 CPU，却仍写成 GPU 对比。
prompt template 或 seed 被改动，质量差异无法归因。

报告落点

第 4 节: 本轮量化对比无效或只作阶段记录
第 7 节: 写清变量漂移、影响和下一轮补测动作
附录: 保留失败命令和原始日志，不删除“跑坏了”的证据

专题 01 · 报告收束

专题一交付 M0 和 M1 的报告材料

第一专题不是概念铺垫。它要交付场景约束卡、环境记录表、baseline plan 和量化实验变量单，后面五个专题只是在这份报告上继续补证据。

课堂追问 如果现在让你推荐 Q4，报告里还缺哪几张表？

专题 01 · 核心概念

第 1-2 节先证明任务边界和实验可信

第 1 节

目标设备、固定 workload、质量阈值、延迟和内存预算。
说明为什么必须端侧，哪些输入不能上云。

第 2 节

OS、CPU/GPU/Jetson、CUDA/JetPack、Python。
llama.cpp commit、模型来源、许可证、SHA256。

第 3 节草稿

baseline prompt、ctx-size、-ngl、日志路径。
未采集字段写“未记录”，不能靠印象补。

专题 01 · 证据图表

第一专题留下五个可复用证据块

证据块	回答的问题	后续用途
场景约束卡	为什么必须端侧	判断推荐方案是否真的可部署。
环境记录表	今天能跑哪条路线	解释 Ubuntu、Jetson、CPU-only 或未测项。
模型清单	模型从哪里来	保证 baseline、量化、API 服务使用同一来源。
指标口径	速度、内存、质量怎么读	避免把一次快输出写成整体最佳。
变量控制单	对比是否可复现	支撑 Q8/Q5/Q4 和 runtime 参数结论。

专题 01 · 课堂实作

进入专题二前先过六项检查

第 1 节: 目标设备、workload、质量阈值和资源预算
第 2 节: 环境快照、模型来源、许可证和 hash
第 3 节草稿: baseline prompt、ctx-size、seed 和日志路径
第 4 节空表: Q8/Q5/Q4 字段、监控方式和质量备注栏

课堂验收 过不了准入，就不讨论 bit-width

量化只是后续手段。报告前两节没有成稿时，任何“Q4 更适合端侧”的判断都只能写成待验证假设。

专题 01 · 风险与报告

缺证据时要写未记录和未测

失败样例

模型许可证查不到，却在建议里写“可上线”。
server 参数和 hash 没记录，API 结果无法复查。
Jetson 未实跑，却把 Ubuntu GPU 结果写成端侧结论。
没有质量阈值，最快结果被误写成最好结果。

报告落点

第 2 节: 查不到就写“未记录”，不要猜
第 7 节: 没跑过就写“未测”，不要推广结论
第 8 节: 推荐和不推荐方案都必须指向证据

专题 02 · 041-080

专题二进入 Qwen/GGUF baseline 与量化证据

先证明同一个 Qwen GGUF 能在目标设备上按固定条件跑通，再讨论 Q8/Q5/Q4、PTQ/QAT 和低比特收益。

先交付baseline 结果表

再讨论数值格式和 PTQ

最后形成Q8/Q5/Q4 对比表

专题 02 · 问题框架

baseline 不是能说话，而是能复查

一次输出文本只能证明模型启动了。课程里的 baseline 必须同时留下模型、runtime、输入、资源和质量证据，后面每个量化结论都要回到这里。

课堂追问 如果一周后重跑，你能证明还是同一个模型和同一套参数吗？

专题 02 · 证据图表

baseline 证据链从模型页走到报告第 3 节

1model id / license

2GGUF name / size / SHA256

3llama.cpp commit + CUDA build

4fixed prompt / ctx / seed

5prompt eval / eval / tokens/s

6quality note + log path

专题 02 · 课堂实作

第一堂实作先交 baseline 表

构建证据: llama-cli、llama-bench、llama-server 是否可运行
模型证据: model id、许可证、GGUF 文件、大小和 SHA256
运行证据: prompt、ctx-size、-ngl、seed、生成长度
结果证据: prompt eval、eval、tokens/s、显存、质量备注

课堂验收 报告第 3 节必须能填一行

如果日志路径、模型 hash 或运行参数缺失，baseline 只能算烟雾测试，不能作为 Q8/Q5/Q4 的参照物。

专题 02 · 风险与报告

baseline 不合格时不要抢跑量化

失败样例

模型能输出，但没有保存 stderr timing。
llama.cpp commit 未记录，后续结果无法复查。
baseline 用 Q4 临时跑通，却没有写明内存不足原因。
输出样例没有质量备注，只剩一串速度数字。

报告落点

第 2 节: 补环境、模型来源、许可证和 hash
第 3 节: 补 baseline 结果和日志路径
第 4 节: baseline 合格后再填 Q8/Q5/Q4

专题 02 · 问题框架

baseline 合格后才讨论数值格式

bit 数只是入口。端侧部署真正要问的是格式能不能被 runtime 加载、被目标 backend 承接，并且在固定 prompt 下保住质量。

课堂追问 文件变小以后，目标设备真的更快、更稳、更可用了吗？

专题 02 · 核心概念

格式不是标签，而是运行约束

浮点基线

FP16、BF16、FP32 用来判断质量和资源基线。
baseline 不一定最快，但必须可复查。

整数量化

INT8、INT4 要看 scale、zero-point、累加和反量化。
runtime 先反量化再算，速度收益可能很小。

GGUF 变体

Q4_K_M、Q5_K_M、Q8_0 是具体文件和 metadata。
记录完整格式名，而不是只写“4bit”。

专题 02 · 证据图表

量化格式先过四个检查项

检查项	要问的问题	报告字段
模型同源	Q8/Q5/Q4 是否来自同一 model id 和 tokenizer	model_id、filename、SHA256
格式含义	weight-only、per-group、metadata 写清了吗	quant_type、group、GGUF metadata
Runtime 支持	目标 backend 是否直接承接低比特格式	backend、offload、startup log
端到端收益	文件、内存、速度、质量是否同时成立	size、TTFT、tokens/s、quality_note

专题 02 · 课堂实作

第二堂实作准备 Q8/Q5/Q4 清单

列出完整文件名、量化名、文件大小、SHA256
核对 base model、tokenizer、许可证和模型页来源
先不比较速度，先确认三个文件能被 llama.cpp 识别
准备同一 prompt、ctx-size、-ngl 和监控方式

课堂验收 先列清单，再做对比

第 4 节不是写“4bit 更小”，而是写同源模型在同一条件下的文件、内存、速度和质量证据。

专题 02 · 风险与报告

只按 bit 数排序会带偏实验

失败样例

把所有 INT4 都当成同一种格式。
只看文件大小，忽略输出跑题、重复或乱码。
runtime 启动日志显示 fallback，却仍写成低比特加速。
Q4/Q5/Q8 不是同一来源，却放进同一张表。

报告落点

第 4 节: 量化版本清单写完整格式名
第 5 节: runtime 支持和 backend 单独说明
第 7 节: 格式不明、fallback 或质量未测写入风险

专题 02 · 问题框架

线性量化先回答误差从哪里来

scale 把真实数值范围压进有限整数格点。范围越大，普通值的格点越粗；Q4/Q8 的质量差异，要先从范围、舍入和 clipping 找原因。

课堂追问 Q4 输出变差时，你能说清是量化误差还是实验条件漂移吗？

专题 02 · 核心概念

四个量决定一条量化映射

scale

一个整数格代表多少真实数值间隔。
scale 变粗，舍入噪声按平方放大。

zero-point

让浮点 0 对齐到整数空间。
权重常用对称，激活常见非对称。

qmin / qmax

bit 数决定整数格点数量。
clipping 决定哪些极端值被牺牲。

专题 02 · 证据图表

公式要落到排障问题

公式部件	课堂解释	报告里要检查
real_range	原始数值覆盖多宽	outlier 是否把 scale 拉粗。
integer_range	bit 数给了多少格点	Q8 到 Q4 损失了多少分辨率。
rounding	每个值落到最近格点	普通值是否累积舍入噪声。
clipping	先牺牲极端值保护主体	被裁掉的是噪声还是任务关键信号。

专题 02 · 课堂实作

用一个 outlier 例子复盘质量退化

主体数值集中在 -2 到 2，INT8 格点较细
加入一个 60，scale 被迫覆盖 -60 到 60
普通值没有变，但量化后可用格点变粗
Q4 更明显，因为整数格点更少，舍入误差更大

课堂验收 不要只写“Q4 变差”

报告第 4 节要写可能原因：范围被 outlier 拉大、舍入误差变粗、clipping 过强、格式支持不足，还是 prompt 条件漂移。

专题 02 · 风险与报告

只会背公式不会支撑部署结论

失败样例

背出 scale 公式，却解释不了 outlier 为什么危险。
只看平均误差，不看固定 prompt 的失败样例。
把 clipping 当成模型能力提升。
没区分量化误差和 runtime fallback。

报告落点

第 4 节: 质量差异必须有固定 prompt 样例
第 5 节: runtime 是否真正低比特计算
第 7 节: outlier、clipping、fallback 写入风险

专题 02 · 问题框架

粒度决定误差由谁承担

同样是 4bit，scale 覆盖整个张量、一个通道、一组权重或一个 token，误差分布、metadata、kernel 支持和运行开销都会不同。

课堂追问 Q4_K_M 比另一个 Q4 稳，是 bit 数原因，还是粒度和打包方式原因？

专题 02 · 核心概念

三类粒度对应三种工程取舍

per-tensor

整个张量共享一组 scale。
metadata 少，但容易被局部 outlier 牵制。

per-channel

每个输出通道一组 scale。
保护通道差异，但依赖格式和 kernel 支持。

per-group

LLM 低比特权重量化常见。
group size 同时影响质量、文件和速度。

专题 02 · 证据图表

量化对象要分账记录

对象	主要解决	仍要单独记录
Weight-only	权重文件、显存和带宽压力	activation、KV Cache、kernel 支持。
Activation	计算链路和激活内存	校准集、outlier、runtime 支持。
KV Cache	长上下文解码内存	ctx-size、质量、吞吐变化。
Mixed precision	保护敏感层或模块	回退范围、层名单和部署格式。

专题 02 · 课堂实作

Qwen GGUF 表格要写清粒度和对象

量化格式: Q4_K_M、Q5_K_M、Q8_0 写全名
量化对象: weight-only、activation、KV Cache 分列
粒度信息: group size、metadata 或工具默认值
验证证据: 同 prompt 的速度、内存、质量和启动日志

课堂验收 不要把三种量化写成“模型 4bit”

权重、激活和 KV Cache 影响的资源不同。报告里混成一个标签，后面就无法解释 OOM、速度或质量变化。

专题 02 · 风险与报告

粒度和对象写错会让部署结论失真

失败样例

只按 bit-width 排序，忽略格式内部差异。
把 weight-only 写成全链路 INT4。
忽略 KV Cache，长上下文仍然 OOM。
细粒度格式没有 kernel 支持，实际运行更慢。

报告落点

第 4 节: 量化对象、格式和粒度分列
第 5 节: runtime/kernel 支持单独验证
第 7 节: KV Cache、OOM、fallback 写入风险

专题 02 · 问题框架

PTQ 先产出候选，不直接产出结论

PTQ 不需要重新训练，适合快速得到 Q8/Q5/Q4 或 INT8 候选；但候选只有经过同一 baseline、同一 prompt、真实设备和质量样例验证，才算进入部署判断。

课堂追问 文件已经变小，为什么还不能写“可以部署”？

专题 02 · 核心概念

PTQ 有三条课堂入口

现成 GGUF

直接使用 Q8_0、Q5_K_M、Q4_K_M。
适合课堂快速比较文件、内存、速度和质量。

自己量化

从 FP16 或原始 GGUF 生成量化版本。
记录工具版本、命令、输出文件和 hash。

静态校准

传统模型或 W8A8 需要校准集。
校准覆盖不到的输入，部署时可能先坏。

专题 02 · 证据图表

PTQ 闭环要回到同一张证据表

1确认 baseline

2选择 PTQ 入口

3生成或下载候选

4同 prompt 复跑

5对比文件/内存/速度/质量

6保留、回退或修复

专题 02 · 课堂实作

Qwen GGUF 第一轮只允许改量化文件

固定 base model、tokenizer、prompt、ctx-size、seed 和 runtime
Q8_0、Q5_K_M、Q4_K_M 分别写入模型清单
每次运行保存 stdout、stderr timing 和设备监控
结果表同时记录文件大小、内存、tokens/s 和质量备注

课堂验收 只生成文件不算完成 PTQ

只有同条件复跑后的日志、资源记录和质量样例，才能支撑报告第 4 节的量化版本对比。

专题 02 · 风险与报告

PTQ 最常见的问题是只证明文件变小

失败样例

Q4 文件更小，但输出重复、跑题或格式坏掉。
Q8 质量稳定，但目标设备内存仍放不下。
校准集只覆盖短问答，长上下文任务先退化。
runtime 不支持低比特 kernel，速度没有收益。

报告落点

第 4 节: PTQ 版本对比表和质量证据
第 5 节: runtime/kernel 是否承接低比特
第 7-8 节: 风险、回退和推荐理由

专题 02 · 问题框架

QAT 是质量修复决策，不是默认下一步

只有 PTQ 在同一 prompt、同一 runtime 和真实设备上被证伪，且数据、预算、导出链路和回归测试都具备，才值得进入 QAT、LoRA 或蒸馏修复。

课堂追问 质量下降时，先训练，还是先回退 Q5/Q8、换 prompt 或补评估？

专题 02 · 核心概念

进入 QAT 前先过四个条件

失败已定位

PTQ 低 bit 在固定样例上稳定退化。
先排除 chat template、ctx、seed 和 backend 变化。

数据和预算

训练、验证和评估样本要分清用途。
显存、训练时间和回归轮次能被课程承受。

导出和回归

fake quant 或 adapter 结果能进入目标 runtime。
训练后还要重跑量化、profiling 和 API smoke test。

专题 02 · 证据图表

PTQ 失败后的三种处理

证据状态	课堂判断	报告写法
低 bit 稳定退化，数据和导出都就绪	进入 QAT、LoRA 或蒸馏 smoke test	训练式修复有进入条件
低 bit 退化，但无训练数据或预算	回退 Q5/Q8、换小模型或调混精	不训练，说明成本和替代方案
baseline、prompt 或 runtime 自身不稳	停止训练判断，先修变量控制	当前不是量化问题
目标 runtime 不能加载训练产物	QAT 不能作为部署路径	只可写研究实验或未验证风险

专题 02 · 课堂实作

QAT 决策要写成训练、不训练或回退

固定 PTQ 失败样例、质量指标和触发条件
说明训练、校准、评估样本如何分开
确认 adapter、fake quant 或导出格式能被 runtime 承接
结论必须落成训练、不训练或回退 Q5/Q8

最小验收 训练决定也要有证据

QAT 相关实验必须回到同一失败样例、tokens/s、内存、API 可用性和部署报告。

专题 02 · 风险与报告

没有导出和回归，QAT 只是训练实验

失败样例

baseline 还没跑稳就开始训练。
chat template 错误被误判为量化退化。
目标 runtime 不支持 adapter 或 fake quant 产物。
训练后没有重新做 Q8/Q5/Q4 和 API 回归。

报告落点

第 4 节: PTQ 是否足够
第 7 节: 数据、导出和回归风险
第 8 节: 训练、不训练或回退理由

专题 02 · 问题框架

数据口径先定，量化差异才可归因

同一模型、prompt 集、chat template、ctx、seed、runtime 和日志路径先固定，Q8/Q5/Q4 的差异才可能被解释为量化差异。

课堂追问 这条样本是在做校准、验收质量，还是登记失败？

专题 02 · 核心概念

三类样本各自只承担一件事

校准样本

覆盖长度、语言、格式和领域分布。
只负责 range、observer 或 imatrix 统计。

评估样本

固定业务 prompt、边界 prompt 和规则检查。
判断 Q8/Q5/Q4 是否可以进入部署候选。

失败样例

保存输入、输出、量化档位和失败标签。
用于决定回退、修复、训练或不训练。

专题 02 · 证据图表

一张表先把数据角色写清

数据角色	课堂字段	不能替代什么
校准集	source、type、token_len、template	不能证明质量达标
评估集	prompt_id、rule、repeat、seed	不能反推校准充分
失败样例	quant_type、output_path、failure_label	不能被平均分掩盖
脱敏边界	redacted_summary、access_level	不能贴原始敏感样本

专题 02 · 课堂实作

每行实验记录都要能重跑

model_id=qwen...
quant_type=Q8/Q5/Q4
prompt_set=eval_v1.jsonl
prompt_id=json_runtime
chat_template=qwen2.5
ctx_size=2048
temperature=0
seed=42
runtime_commit=
log_path=

最小验收 同一行能重跑同一输出

字段缺一个，Q8/Q5/Q4 的速度、内存或质量差异都只能写成风险。

专题 02 · 风险与报告

口径不清时只能写风险，不能写推荐

失败样例

校准集只有短问答，实际任务是长文档或 JSON。
评估 prompt、template、ctx 或 seed 每次都变。
只记录平均分，没有保存 Q4 失败输出。
把隐私样本原文贴进公开报告。

报告落点

第 4 节: prompt 集、规则和日志路径
第 7 节: 数据偏差、脱敏和未测风险
附录: 样例摘要、失败标签和访问边界

专题 02 · 问题框架

专题二的交付物是一张可审查的量化证据表

到这里不急着宣布哪个量化档位最好；先交 Q8/Q5/Q4 同源、同条件、同口径的对比表，让推荐和不推荐都能指向日志和输出样例。

课堂追问 这行记录是在支撑推荐，还是只证明跑过一次？

专题 02 · 核心概念

量化证据表先证明三件事

同源

同一 Qwen 基座、tokenizer、文件来源和 hash。
不同来源 GGUF 不能混成量化差异。

同条件

prompt、template、ctx、seed、-ngl 和 runtime 一致。
每次只改变一个量化版本。

同口径

文件大小、TTFT、tokens/s、内存和质量同表。
每个判断都要有日志路径。

专题 02 · 证据图表

第 4 节表格必须同时写收益和代价

表格区块	最低字段	支撑什么结论
模型证据	version、hash、quant_type、size	证明 Q8/Q5/Q4 同源
运行条件	prompt_id、ctx、seed、runtime、-ngl	证明对比可复现
资源收益	TTFT、tokens/s、memory、log_path	证明速度或内存收益
质量证据	output_path、rule、failure_label	证明是否可部署
判断	keep、fallback、risk、untested	写推荐或不推荐

专题 02 · 课堂实作

进入专题三前先完成 M2 交付

补齐模型清单：基座、量化档位、size、hash
补齐实验单：prompt、template、ctx、seed、runtime
补齐结果表：TTFT、tokens/s、内存、质量样例
写出推荐、回退、不推荐或未测理由

下一专题准入 没有 M2，就不讲新方法

GPTQ、AWQ 和 KV Cache 不是替代基础证据表的捷径；它们要接在 Q8/Q5/Q4 记录之后。

专题 02 · 风险与报告

证据没闭合，就不能带着结论进入专题三

失败样例

只说低 bit 更小，不写质量证据。
只引用外部 benchmark，不写本机日志。
Q8 放不下或 Q4 变差，却没有回退策略。
只跑 CLI，没有留下 profiling/API 准入字段。

报告落点

第 4 节: Q8/Q5/Q4 对比表
第 7 节: 质量、内存、未测风险
第 8 节: 推荐和不推荐方案

专题 03 · 081-120

专题三拆开低比特 LLM、KV Cache 与质量归因

Q8/Q5/Q4 表只回答“哪几个候选可复查”；专题三继续拆清权重文件、激活 outlier、KV Cache、runtime warning 和生成质量。

输入M2 量化证据表

拆账权重、运行、质量

交付低比特方法边界

专题 03 · 核心概念

LLM 低比特不是一个 4bit 标签

权重账

记录 GGUF Q8/Q5/Q4、文件大小、hash 和来源。
写清它是 weight-only，还是同时改变了别的对象。

运行账

记录 prefill、decode、KV Cache、ctx-size 和内存峰值。
backend fallback、warning 和 offload 必须单独留证据。

质量账

固定 prompt 保存输出样例和 failure_label。
最后判断 keep、fallback、risk 或 untested。

专题 03 · 证据图表

四本账决定低比特能不能留下

账本	要记录什么	报告里怎么用
权重文件	quant type、size、hash、来源、是否同源	第 4 节解释资源收益来自哪里
激活 / outlier	是否涉及 W8A8、SmoothQuant、LLM.int8 或敏感层	第 4 节说明质量风险和未测边界
KV / runtime	ctx-size、prompt/generated tokens、RAM/VRAM、warning/fallback	第 5 节解释长上下文和服务化瓶颈
生成质量	固定输出、格式错误、重复、拒答、failure_label	第 7-8 节决定推荐、回退或暂不推荐

专题 03 · 课堂实作

专题三第一步是扩展 M2 表

从 quant_compare.csv 或等价表开始，不重开表
补 prompt_tokens、generated_tokens 和 ctx_size
补 RAM/VRAM 峰值、warning、fallback 和 runtime 参数
每个版本保存输出样例、failure_label 和判断

下一步准入 先扩表，再讲 GPTQ/AWQ

GPTQ、AWQ、SmoothQuant、LLM.int8 和 KV Cache 都要回到同一张表，而不是停在方法名。

专题 03 · 风险与报告

只看文件大小会错过真正瓶颈

失败样例

Q4 文件更小，但 backend fallback 后反而更慢。
长上下文 OOM 来自 KV Cache，不是权重文件。
速度可接受，但输出重复、JSON 破坏或事实缺失。

报告落点

第 4 节: 写清权重收益和质量证据
第 5 节: 写清 runtime、KV 和 profiling 证据
第 7 节: 记录长上下文、并发和生成稳定性风险

专题 03 · 问题框架

tokens/s 不能解释一次请求的全部成本

M2 表里的 tokens/s 只解释持续生成。专题三要继续拆 prefill、decode 和 KV Cache，否则短 prompt 下的快，会被误写成长上下文也可用。

课堂追问 短问答快，长文档还快吗？

专题 03 · 核心概念

三段成本对应三类记录字段

prefill

处理 prompt tokens，决定首 token 等待。
记录 prompt_tokens、ctx_size、prompt_eval_time。

decode

逐 token 生成，决定持续输出速度。
记录 generated_tokens、eval_time、tokens/s。

KV Cache

保存历史 key/value，随上下文和会话增长。
记录 RAM/VRAM 峰值、cache dtype、OOM 或 fallback。

专题 03 · 证据图表

M2 扩展表要能定位等待来自哪里

问题	先看字段	报告解释
启动慢	model size、backend、offload、load log	不要把加载成本混进生成速度
首 token 慢	prompt_tokens、ctx_size、prompt_eval_time	长 prompt 的成本主要在 prefill
持续输出慢	generated_tokens、eval_time、tokens/s	decode 速度要在同一输出长度下比较
长上下文 OOM	ctx_size、cache dtype、RAM/VRAM、warning	KV Cache 风险不能归因给权重文件

专题 03 · 课堂实作

llama.cpp timing 要写回同一行实验

`prompt eval time` 写入 prefill 字段
`eval time` 和 `tokens per second` 写入 decode 字段
`ctx-size`、prompt/generated tokens 写入 workload 字段
RAM/VRAM、warning 和 fallback 写入 runtime 字段

最小验收 一条日志只产生一行可复查记录

同一行里同时放模型、prompt、ctx、量化格式、timing、内存和质量备注，避免跨实验拼结论。

专题 03 · 风险与报告

总耗时不能直接写成部署建议

失败样例

短 prompt 下 Q4 很快，长上下文却因为 KV Cache OOM。
decode tokens/s 高，但首 token、加载或 API 排队拖慢体验。
ctx-size 或生成长度变了，却直接比较 tokens/s。

报告落点

第 4 节: 量化收益必须同时写 prefill 和 decode
第 5 节: ctx/offload/cache 进入 profiling 表
第 7 节: 长上下文、并发和 API 体验进入风险登记

专题 03 · 问题框架

Q4 失败不能直接怪量化方法

Q4 输出变差只是现象。先确认 Q8/F16 baseline、prompt/template、ctx、采样参数和 runtime 一致，才有资格判断是不是低比特造成的退化。

课堂追问 Q8 也错，还能怪 Q4 吗？

专题 03 · 核心概念

先排除四个非量化原因

baseline

Q8/F16 也答错时，先修任务或换模型。
baseline_fail 不能写成 Q4 退化。

输入条件

prompt、chat template、tokenizer 和采样参数必须一致。
ctx-size 或截断变化会伪装成质量下降。

runtime

backend、offload、kernel、fallback 和设备状态要留日志。
只在某设备失败时，先查 runtime_fallback。

专题 03 · 证据图表

归因表先判断能不能怪 Q4

现象	失败标签	下一步
Q8 和 Q4 都错	baseline_fail / prompt_issue	先修任务、prompt 或模型，不归因给量化
Q8 对，Q4 格式或事实错	low_bit_regression	比较 Q5/Q8，准备回退或敏感层保护
只在长上下文失败	ctx_kv_issue	记录 token、ctx、KV、截断和内存峰值
只在某设备失败	runtime_fallback	补启动日志、offload、kernel 和 profiling

专题 03 · 课堂实作

输出对照表要保留原始失败样例

同 prompt 保存 F16/Q8/Q5/Q4 原始输出
记录 prompt_id、ctx_size、seed、temperature 和日志路径
给失败打标签：baseline_fail、low_bit_regression、ctx_kv_issue、runtime_fallback
只把可复现失败写进报告第 7 节

最小验收 没有原始输出，就不能做修复决策

失败标签决定后续是回退 Q5/Q8、调 ctx、查 runtime，还是进入 mixed precision 或校准修复。

专题 03 · 风险与报告

错误归因会把修复方向带偏

失败样例

baseline 本来就错，却把失败归因给 Q4。
chat template 变了，却去换 GPTQ/AWQ。
长上下文被截断，却写成低比特质量差。
没有原始输出，后续无法复查修复效果。

报告落点

第 4 节: 写质量现象、失败标签和证据路径
第 7 节: 写 baseline、ctx、runtime 和低比特归因
第 8 节: 只给出能回放证据的回退或修复建议

专题 03 · 问题框架

GPTQ 先过格式和 runtime 闸门

GPTQ 解决的是逐层 weight-only 误差补偿，不是部署结论。进入课堂表格前，先问三件事：校准数据是否代表任务，产物格式是否能被 runtime 加载，是否有目标设备日志。

课堂追问 不能加载到 runtime 的 GPTQ，能写推荐吗？

专题 03 · 核心概念

GPTQ 的质量上限先看校准输入

输入 X 决定补偿方向

H=2XX^T 只依赖校准输入。
样本偏了，补偿也会偏。

逐层补偿不是全局保险

每层尽量保持 WX 不变。
跨层累积仍要用固定 prompt 复查。

bit 数不是完整口径

4-bit 还要写 group size、实现和格式。
目标 runtime 支持必须单独验证。

专题 03 · 证据图表

GPTQ 与 GGUF 不是同一个交付物

判断点	GPTQ 路线	课程主线怎么写
产物格式	safetensors + quantize_config.json	不能直接写成 GGUF
runtime	Transformers / vLLM / GPTQ runtime	llama.cpp 主线要另走 GGUF
证据	校准集、质量输出、runtime 日志	未实跑写候选，不写推荐
风险	校准偏、格式链路、设备支持	写入第 7 节风险

专题 03 · 课堂实作

GPTQ 决策表只回答是否进入候选

记录校准文本来源、数量、语言和任务覆盖
记录 bits、group_size、实现和产物路径
记录目标 runtime 是否能加载、是否有 profiling
未实跑时只写候选路线或未测原因

最小验收 先判定候选，再谈优化

如果主线使用 Qwen GGUF，GPTQ 只能作为方法对照或扩展路线，不能替代 Q8/Q5/Q4 实测。

专题 03 · 风险与报告

把 GPTQ 写成推荐要有三份证据

失败样例

没有校准文本来源，却写 GPTQ 质量更稳。
把 safetensors/quantize_config 当成 GGUF。
用论文或排行榜替代目标设备日志。
runtime 不支持，却写成推荐部署方案。

报告落点

第 4 节: 方法、格式、质量证据
第 5 节: runtime 支持和 profiling
第 7-8 节: 风险、候选或不推荐理由

专题 03 · 问题框架

AWQ 先判断它要保护哪类退化

AWQ 用激活统计识别少数重要通道，再用缩放让这些通道在低比特网格里保留更多分辨率。它只能作为候选路线进入表格，不能替代 Qwen/GGUF 主实验。

课堂追问 没有校准和 runtime 证据，AWQ 能写推荐吗？

专题 03 · 核心概念

AWQ 的三条证据线

校准覆盖

激活幅值决定哪些通道被保护。
文本、语言和任务不覆盖时，保护对象会偏。

缩放边界

缩放不是把关键通道保留高精度。
它只让重要权重获得更细量化分辨率。

模块和 runtime

VLM projector 等敏感模块要单独评估。
格式、kernel 和 runtime 加载都要留日志。

专题 03 · 证据图表

AWQ 与 GGUF 仍要分层记录

判断点	AWQ 路线	课程主线怎么写
量化目标	activation-aware weight-only INT4	不能写成普通 GGUF Q4
校准证据	文本覆盖、模板、语言和任务	缺失时只写未测风险
质量验证	固定失败样例是否恢复	和 Q8/Q5/Q4 分开比较
端侧承接	模型格式、kernel、runtime 日志	没实跑就不写推荐

专题 03 · 课堂实作

AWQ 只进入候选表，不替代 Q8/Q5/Q4

先定位 Q4 失败是不是低比特退化
记录校准文本来源、语言、模板和任务覆盖
记录 AWQ 格式、group size、runtime 加载和 profiling
只有外部 AWQ 模型时，写成不可直接横比

最小验收 先证明候选可加载，再讨论是否更好

AWQ 是方法和生态路线；今天主线的 GGUF Q4/Q5 是文件、runtime 和设备日志证据。

专题 03 · 风险与报告

把 AWQ 写成推荐要先补三类证据

失败样例

只说 activation-aware，不写校准文本。
把缩放保护说成关键通道高精度保留。
用 AWQ 论文或 VLM 数字替代本地设备日志。
不确认模型格式、kernel 和 runtime 支持。

报告落点

第 4 节: 校准、方法、质量样例
第 5 节: 格式、runtime、profiling
第 7-8 节: VLM 风险、候选或不推荐理由

专题 03 · 问题框架

先判断问题在激活、权重还是 KV Cache

SmoothQuant 和 LLM.int8() 处理激活 outlier，GGUF Q4/Q5 主要压权重，KV Cache 随上下文增长。三类问题混写，后面的速度、内存和质量结论都会失真。

课堂追问 这次失败到底来自哪一本账？

专题 03 · 核心概念

三条路线解决三类不同问题

SmoothQuant

把量化压力从激活迁到权重。
服务有 W8A8 kernel 的部署路线。

LLM.int8()

outlier 列保留或特殊处理。
8-bit 更稳，但压缩率不如 INT4。

KV Cache

随 ctx、batch 和并发线性增长。
权重量化不会自动降低 cache 压力。

专题 03 · 证据图表

路线选择表先写清解决对象

路线	解决对象	必须验证
SmoothQuant	activation outlier 与 W8A8 动态范围	校准、W8A8 kernel、质量输出
LLM.int8()	8-bit 矩阵乘中的 outlier 列	bitsandbytes/Transformers 路径和设备支持
GGUF Q4/Q5	权重文件、加载内存和带宽	llama.cpp 日志、速度、质量
KV Cache 量化	ctx、batch、并发带来的 cache 内存	KV buffer、OOM、长上下文质量

专题 03 · 课堂实作

课堂表格要把四本账分开填

weight-only 写格式、bit、group/imatrix 和文件大小
W8A8 写校准、缩放、kernel 和 runtime
LLM.int8 写库、device map、outlier 处理和质量
KV Cache 写 ctx、tokens、cache dtype 和 buffer size

最小验收 同一结论不能只写模型 4bit

GGUF Q8/Q5/Q4 让学生先拿到同模型、同 prompt、同 runtime 的证据；W8A8、LLM.int8 和 KV cache 是并行扩展路线。

专题 03 · 风险与报告

没有 runtime 证据就只能写扩展路线

失败样例

把 SmoothQuant、LLM.int8 和 GGUF Q4 混成一条路线。
写 activation outlier，但实验只有 weight-only。
用 bitsandbytes 或论文结果替代 llama.cpp 设备日志。
长上下文 OOM，却只继续讨论权重文件大小。

报告落点

第 4 节: 写清量化对象和质量证据
第 5 节: 写 runtime、kernel、KV buffer 和 profiling
第 7-8 节: 未测路线只写风险或下一步验证

专题 03 · 问题框架

GGUF 主实验回答今天能不能交付

GPTQ、AWQ、SmoothQuant 可以进入候选表，但今天的主结论必须来自同源 Qwen GGUF、同一 prompt、同一 llama.cpp 和同一套日志。

课堂追问 哪一组证据能直接写进最终报告？

专题 03 · 核心概念

三类变量先锁住，量化差异才可信

模型变量

model id、GGUF 文件、SHA256 和量化格式同表。
chat template、tokenizer、许可证不能缺。

运行变量

prompt、ctx-size、-ngl、seed、生成长度固定。
每轮只改变一个量化档位。

证据变量

stdout、stderr timing、资源采样、输出样例同名归档。
没有日志路径就没有推荐理由。

专题 03 · 证据图表

每一步都要落到一个报告字段

课堂动作	报告字段	最低证据
建模型清单	第 2 节模型来源	文件名、量化格式、SHA256、许可证
跑 Q8/Q5/Q4	第 4 节量化对比	同 prompt 输出、stderr timing、质量备注
采资源状态	第 5 节 profiling	nvidia-smi / tegrastats、offload、warning
接本地服务	第 6 节 API 测试	request、response、elapsed、server log

专题 03 · 课堂实作

命令页要让每行日志可追溯

循环只替换 model 文件，prompt、ctx、seed、-ngl 不变
每个 stem 生成同名 completion.log 和结果表行
stdout/stderr 一起保存，保留 prompt eval 和 eval timing
字段没出现在日志里就写未记录，不能补猜

最小验收 一条日志对应一行量化对比表

模型文件、命令参数、输出样例、timing 和资源记录必须能互相追到。

专题 03 · 风险与报告

主实验不闭合就不能进入推荐

失败样例

Q8/Q5/Q4 来自不同 base model，却写成 bit 对比。
prompt、ctx 或 seed 变了，输出差异被误判为量化差异。
API 可用但 Q4 输出跑题，仍写成可部署。
stderr timing、资源采样或失败样例没有保存。

报告落点

第 4 节: 量化对比只写已闭合证据
第 5-6 节: profiling 和 API 不替代质量判断
第 7-8 节: 缺日志时只能写回退或继续验证

专题 03 · 问题框架

专题三结束前先给证据分级

GPTQ、AWQ、SmoothQuant、LLM.int8、GGUF 和 KV Cache 最后不按热度排序，而按证据等级进入推荐、回退或继续验证。

课堂追问 哪条路线现在有资格写进建议？

专题 03 · 核心概念

方法矩阵按证据等级排序

路线	当前证据等级	下一步
GGUF Q8/Q5/Q4	主线实测候选	按失败样例决定推荐、回退或修复
KV Cache	长上下文资源风险	用 ctx-size 和 KV buffer 继续 profiling
GPTQ/AWQ	校准和格式候选	有目标 runtime 才扩展验证
SmoothQuant/LLM.int8	W8A8/outlier 扩展路线	未跑通就写风险，不写推荐

专题 03 · 课堂实作

下一专题需要四类输入材料

baseline 与 Q8/Q5/Q4 原始输出
同条件 timing、资源和模型文件表
失败样例标签：事实、格式、遗漏、重复
推荐候选、回退候选和继续验证路线

最小验收 报告第 4 节可以被别人复查

如果只剩平均分或口头判断，后续无法定位质量问题，也无法解释为什么推荐某个量化版本。

专题 03 · 风险与报告

专题四从证据缺口和失败样例开始

失败样例

质量问题：Q4 输出不稳、格式错或事实错。
资源问题：Q8 质量稳但文件、内存或 ctx 不达标。
证据问题：runtime 参数改变了，却没有单变量记录。
路线问题：GPTQ/AWQ/W8A8 未跑通但被写成推荐。

报告落点

第 4 节: 量化证据表先闭合
第 7 节: 质量、资源、未测路线风险
第 8 节: 最终建议只引用已闭合证据

专题 04 · 121-160

专题四把精度修复和训练取舍放进决策门

接住专题三留下的原始输出、timing、资源和失败标签，先排除 baseline、prompt、ctx、runtime 和设备差异，再决定校准、回退、蒸馏、LoRA/QLoRA 或不训练。

输入专题三证据包

方法先排除非量化因素

交付归因标签和修复门槛

专题 04 · 质量归因

先证明失败不是基线或输入问题

基线先过关

Q8 或 F16 在同一 prompt 上先答对。
baseline 已经错时，先修任务、prompt 或模型。

输入先固定

chat template、ctx-size、temperature 和 seed 一致。
prompt tokens 和输出要求要能复查。

运行先对齐

runtime commit、offload、设备状态和日志路径齐全。
Jetson 失败先看内存、温度和功耗。

专题 04 · 归因表

失败样例先归到一个主因

现象	首要判断	下一步
Q8 和 Q4 都答错	baseline 或 prompt 问题	先修任务定义、prompt 或换模型
Q8 正确，Q4 漏关键概念	低比特质量下降	比较 Q5/Q8 或保护敏感张量
长上下文才失败	ctx、KV Cache 或截断	记录 token 数、ctx-size 和峰值内存
只在 Jetson 上失败	设备、runtime 或编译差异	查启动日志、offload 和 tegrastats
单次失败不可复现	采样随机性	固定 seed 或多次运行统计

专题 04 · 复现记录

质量记录要能重跑同一个失败

prompt_id、prompt tokens、ctx-size
模型 hash、量化格式、runtime commit
temperature、seed、repeat count
输出 JSONL、stderr、资源日志路径

最小验收 同一 prompt 跑 Q8、Q5、Q4

只要换了模板、采样参数或 runtime，就不是同一次质量对比，不能直接写成量化退化。

专题 04 · 失败复盘

训练前先做最低成本修复

失败样例

看到 Q4 变差就直接做 LoRA 或 QAT。
没有确认 baseline、prompt 或 template 是否已错。
Jetson 上失败，却没有检查 offload、温度和内存。
质量修好了，却没有重新记录速度和内存。

报告落点

第 7 节: 失败类型和证据日志
第 8 节: prompt、回退、mixed precision 或训练门槛
附录: prompt、参数、输出和资源记录

专题 04 · 问题框架

先把失败分到正确任务账本

“效果不好”不是工程证据。先判断失败来自分类/检测指标、LLM 原始输出、VLM 图像链路，还是 Agent 工具轨迹，再进入修复。

课堂追问 这条失败样例应该填进哪一张质量表？

专题 04 · 核心概念

质量证据不能跨任务替代

指标型任务

accuracy、F1、mAP、漏检和误检。
数据版本、阈值、预处理和后处理一致。

生成型任务

事实、格式、关键概念、重复和拒答。
prompt、template、ctx、seed 和温度固定。

链路型任务

OCR、小目标、空间关系、工具调用。
保存图片处理、tool trace 和恢复动作。

专题 04 · 证据图表

每条失败都要能回放

任务	质量信号	必须保存
分类/检测	指标下降、漏检、框偏移	数据版本、阈值、错例图
LLM	事实错、格式错、漏关键概念	prompt_id、原始输出、seed、失败标签
VLM	OCR 错、小目标漏、关系错	输入图、裁剪、分辨率、视觉 prompt
Agent	工具选错、恢复失败、权限越界	tool trace、policy 结果、observation

专题 04 · 课堂实作

固定失败标签后才能比较 Q8/Q5/Q4

baseline_fail: 高精度版本已经失败
format_error: JSON、表格或字段不合规
missing_key_concept: 漏掉关键概念
runtime_fallback: 执行路径或设备状态异常

最小验收 同一 prompt 三个版本同表记录

标签固定后，才能判断低比特是否让某类失败变多，而不是凭一次聊天体验下结论。

专题 04 · 风险与报告

分诊没闭合，修复就是猜

失败样例

只展示 Q4 成功输出，没有失败样例。
LLM、VLM、Agent 失败混写成“效果不好”。
没有保留原始输入、输出或 trace。
标签随手写，后续无法统计和复查。

报告落点

第 4 节: 质量信号、样例和失败标签
第 7 节: 按任务类型登记风险
附录: prompt、图片、输出或 trace 路径

专题 04 · 问题框架

修复前先让 Q8/F16 站住

只有高精度版本在同一 prompt、template、runtime 和 ctx-size 下答对，Q4/Q5 的失败才可能归因到量化；否则先修任务、prompt、模型或评估集。

课堂追问 这个错误在 Q8/F16 里还会不会出现？

专题 04 · 核心概念

baseline 和评估集回答两个问题

baseline

模型在同条件下能不能完成任务。
保存模型 hash、prompt、ctx、runtime 和输出。

评估集

这次比较是否覆盖真实任务。
包含概念、格式、长上下文和部署诊断。

一致性

量化前后只允许量化档位变化。
template、seed、温度、设备状态固定。

专题 04 · 证据图表

baseline gate 先挡住假退化

检查项	不过关时说明什么	下一步
Q8/F16 已失败	不是低比特退化	修 prompt、换模型或重定义任务
评估集太窄	不能代表课程任务	补概念、JSON、长上下文和诊断样例
输入或运行不同	Q8/Q5/Q4 不可比	固定 template、ctx、seed、runtime 后重跑
日志证据缺失	结论不可复查	补输出、stderr 和资源日志路径

专题 04 · 课堂实作

最小评估集要能被脚本重复跑

每条样例写 id、type、prompt、must_include
覆盖概念解释、JSON 格式、长上下文和部署诊断
同一 JSONL 依次跑 Q8、Q5、Q4
输出按 prompt_id 和量化档位保存

最小验收 先固定样例，再比较模型

课堂 smoke test 不等于完整评测，但它必须能重复，才能暴露低比特模型的明显退化。

专题 04 · 风险与报告

baseline 过不了就不写修复建议

失败样例

Q8 已经答错，却把 Q4 失败归因给量化。
Q8/Q5/Q4 使用了不同 prompt 或 template。
评估集只有演示样例，没有边界和长上下文。
没有输出和日志路径，无法复查。

报告落点

第 3 节: baseline gate 和日志路径
第 4 节: 同条件量化质量表
第 7 节: 评估覆盖不足和未验证风险

专题 04 · 问题框架

一次只改一个变量

质量下降不能直接写成“量化导致”。先固定 baseline、prompt、ctx、seed 和 runtime，只改变一个条件，再判断失败是否消失。

课堂追问 如果换回 Q8 后恢复，下一步还要排除什么？

专题 04 · 核心概念

归因先查三层可反证证据

输入与任务

baseline、prompt、template、tokenizer。
Q8 也错时，先修任务或输入。

运行与设备

ctx-size、seed、runtime、backend、fallback。
Jetson 差异要看启动日志和 tegrastats。

量化与模型

校准分布、敏感层、outlier、KV Cache。
只在同条件低比特失败时进入修复。

专题 04 · 证据图表

归因表要写出反证和动作

现象	先查什么	下一步动作
Q8/Q4 都错	baseline 或 prompt	修任务、prompt 或换模型
Q8 对，Q4 漏关键点	低比特损伤	试 Q5/Q8、imatrix 或敏感张量保护
长上下文才失败	ctx、KV Cache、截断	记录 token、ctx-size、峰值内存
Jetson 才失败	runtime、offload、设备状态	查启动日志、温度、tegrastats

专题 04 · 课堂实作

三步排查必须留下日志

先重跑 Q8/F16，确认 baseline 是否失败
再重跑 Q8/Q5/Q4，只改变量化档位
最后单独改变 ctx、seed、runtime 或设备状态
每一步都保存输出、stderr 和资源记录

最小验收 每个归因都有反证路径

如果说不清什么证据会推翻这个归因，就不要把它写成最终部署建议。

专题 04 · 风险与报告

归因没闭合就不能选修复手段

失败样例

把所有失败都写成“模型太小”。
baseline 本来错，却去做 mixed precision。
runtime fallback，却去重构校准集。
没有单变量实验，就推荐 LoRA 或 QAT。

报告落点

第 7 节: 失败归因和反证记录
第 8 节: 只给有证据的修复建议
附录: 单变量对照日志

专题 04 · 问题框架

先做最便宜且可复测的修复

修复不是越复杂越好。归因闭合后，先试 prompt/template、采样、Q5/Q8 回退，再到校准/imatrix、mixed precision，最后才考虑 LoRA、QAT 或蒸馏。

课堂追问 这个动作能不能今天用同一评估集复测？

专题 04 · 核心概念

三类修复动作对应三类证据

输入侧修复

修 prompt/template、固定 seed 和 temperature。
Q8/Q4 都错时优先走这条。

量化侧修复

换 Q5/Q8、重构校准集、imatrix。
只在同条件低比特退化时使用。

模型侧补偿

mixed precision、LoRA、QAT、蒸馏。
必须重新评估资源和部署链路。

专题 04 · 证据图表

修复决策先看证据门槛

已证明的归因	优先动作	必须复测
Q8/Q4 都错	修 prompt/template 或换模型	baseline 质量
Q4 错，Q5/Q8 对	回退 Q5/Q8 或换量化类型	文件、内存、tokens/s、质量
校准分布不匹配	重构校准集或 imatrix	PPL、失败样例、量化日志
少数模块敏感	mixed precision 或局部回退	runtime 支持、文件和内存

专题 04 · 课堂实作

只有实跑闭合的修复才能写成结论

Q4 失败先看 Q5 是否满足质量阈值
校准集重构要保存 v1/v2 文本和量化日志
mixed precision 要记录新增文件大小和内存
LoRA/QAT 未实跑时只能写候选，不写推荐

最小验收 修复前后必须同一评估集复测

质量恢复、速度变化、内存变化和日志路径要在同一张表里，否则不能进入最终建议。

专题 04 · 风险与报告

质量修好了也可能不能部署

失败样例

质量恢复了，但 Q5/Q8 文件和内存超过设备约束。
mixed precision 格式不被目标 runtime 支持。
校准集只覆盖课堂 prompt，没有覆盖真实任务。
LoRA/QAT 成本很高，却没有比回退 Q5 更好。

报告落点

第 7 节: 修复尝试和新风险
第 8 节: 推荐、回退或不继续修复
附录: 修复前后同条件记录

专题 04 · 问题框架

压缩先问真正卡在哪里

压缩不是先挑剪枝、低秩或蒸馏。先证明瓶颈在文件、峰值内存、算子延迟、输出质量还是设备稳定性，再选择能被目标 runtime 验收的动作。

课堂追问 今天要降低的是哪一种部署成本？

专题 04 · 核心概念

压缩动作要绑定可验证收益

表示更紧凑

量化、低秩、参数共享、聚类。
必须复测文件、内存和同集质量。

结构更小

结构化剪枝、删 head/层、换小模型。
必须证明 runtime/kernel 真能加速。

能力再迁移

蒸馏、LoRA、QAT 或 adapter 补偿。
必须记录数据、教师质量和回归成本。

专题 04 · 证据图表

压缩矩阵要先写验收证据

已证明的瓶颈	先试路线	不能缺的证据
文件或权重内存过大	Q5/Q4、换小模型、低秩候选	文件大小、峰值内存、同集质量
算子延迟高	runtime 参数、换架构、结构化剪枝候选	TTFT、tokens/s、kernel/offload 日志
低比特质量下降	Q5 回退、mixed precision、蒸馏/LoRA 候选	失败样例复测、资源变化、训练成本
设备长跑不稳定	降 ctx、换小模型、任务拆分或端云协同	tegrastats、温度、功耗和长稳日志

专题 04 · 课堂实作

课堂只做低成本压缩判断

先用 Q8/Q5/Q4 和更小模型形成可复测对照
剪枝、低秩、蒸馏只写进入条件和验证计划
没有 kernel/runtime 证据时，不承诺稀疏或低秩加速
路线选择必须进入第 7 节风险和第 8 节建议

课堂验收 参数少不是部署结论

只有质量、速度、内存、设备日志和 runtime 支持同时闭合，压缩路线才允许写成建议。

专题 04 · 风险与报告

压缩失败要写成路线降级

失败样例

非结构化稀疏没有专用 kernel，tokens/s 没变。
低秩拆成更多小算子，端侧反而更慢。
小模型靠更长 prompt/RAG 才补回能力，总延迟上升。

报告落点

第 7 节: 写清压缩风险、未测条件和反证路径
第 8 节: 推荐采用、回退 Q5/Q8、换模型或端云协同

专题 04 · 问题框架

蒸馏先过四个进入门槛

蒸馏不是质量下降后的默认动作。只有任务稳定、教师可靠、学生可部署、评估能回归时，训练型补偿才值得进入第二阶段。

课堂追问 这次失败真的是训练能解决的吗？

专题 04 · 核心概念

蒸馏准备度看三张卡

教师输出卡

记录模型来源、版本、许可证和生成参数。
先抽查教师是否比 baseline 更可靠。

学生部署卡

学生容量要匹配目标设备和 tokenizer。
确认能导出、量化、profiling 和服务化。

数据回归卡

样例覆盖失败标签、schema 和边界任务。
训练后必须重跑同一评估集和 Q5/Q4。

专题 04 · 证据图表

蒸馏路线必须先写反证

已证明的条件	可选路线	必须复测
原模型资源不达标，任务稳定	先蒸馏学生，再量化部署	学生 Q5/Q4、速度、内存和质量
低比特退化已归因	LoRA、蒸馏或 QAT 补偿候选	原失败样例和资源变化
固定格式或窄领域任务	response/SFT 蒸馏候选	schema、边界样例和负面样例
教师、数据或许可证不稳	先不蒸馏，回到任务定义	错误样例、来源和反证记录

专题 04 · 课堂实作

课堂只交付蒸馏准备度

从失败标签里挑 10 条蒸馏候选样例
填写教师输出卡、学生部署卡和数据回归卡
标记先蒸馏后量化，还是量化后补偿
未实跑训练时，只写进入条件和验证计划

课堂验收 准备度不是推荐结论

没有训练日志、同集复测和再量化结果，蒸馏只能写成第二阶段候选。

专题 04 · 风险与报告

蒸馏会继承教师和数据的错误

失败样例

教师输出带错事实或格式，学生稳定复读错误。
学生容量过小，只学到风格，任务能力下降。
训练指标提升，但 GGUF/local API 回归失败。

报告落点

第 7 节: 写清教师、数据、许可证和回归风险
第 8 节: 写不蒸馏、二阶段蒸馏或直接换模型

专题 04 · 问题框架

专题四结尾要回答能不能写建议

质量修复、压缩和蒸馏不以方法跑过结束，而以报告第 7 节风险登记和第 8 节部署建议结束；证据不齐时只能写回退或继续验证。

课堂追问 这条建议缺哪类证据？

专题 04 · 核心概念

第 8 节先选结论类型

保留回退

Q4 有收益但不稳，默认保留 Q5/Q8。
写清触发回退的质量、延迟或内存条件。

暂不推荐

LoRA、QAT、蒸馏或剪枝缺训练和回归证据。
只能写进入条件、成本和下一步验证。

专题 04 · 证据图表

第 7 节风险决定第 8 节措辞

风险记录	证据要求	第 8 节写法
Q4 输出跑题、重复或乱码	固定 prompt 输出、失败标签、Q5/Q8 对照	Q4 暂不作为默认版本，保留高精度回退
修复后资源变差	同条件速度、内存和设备日志	只作为候选，不写上线推荐
蒸馏、LoRA 或 QAT 未实跑	数据、教师、训练成本和回归计划	写第二阶段验证，不写已解决
API 或 runtime 未验收	server log、请求样例、HTTP 状态和 elapsed	进入专题五补证据后再判断

专题 04 · 课堂实作

用十分钟写出一条保守建议

选一个固定失败样例和对应日志
填写风险、影响、缓解动作和是否进入建议
写一条推荐方案，同时写一条不推荐方案
缺证据的字段只写未记录、失败或下一轮验证

课堂验收 先写能被审查的结论

建议可以保守，但不能脱离日志、输出样例、复测条件和风险登记。

专题 04 · 风险与报告

写不进报告的修复不算完成

失败样例

只说“调参后好了”，没有记录变量和复测条件。
只贴最好结果，不解释回退和不推荐方案。
推荐训练型修复，却没有数据、成本和回归证据。

报告落点

第 7 节: 风险、失败样例和缓解动作成稿
第 8 节: 推荐、回退和暂不推荐分开写
下一专题: 用 runtime、profiling 和 API 补服务证据

专题 05 · 161-200

专题五把建议放进 Runtime 与 Local API 验收

专题四得到的推荐、回退或暂不推荐，进入专题五后必须用同一 Qwen GGUF 在 CLI、bench、profiling 和 local API 下复查。

输入第 8 节候选建议

方法runtime、profiling、API 分账

交付第 5-6 节证据包

专题 05 · 部署分层

模型文件不是本地服务能力

能加载

runtime 能识别 GGUF、tokenizer 和 chat template。
启动日志要写清模型路径、hash 和参数。

能跑得动

backend 是否启用要看 CUDA/CPU/offload 日志。
速度、内存和温度要用 profiling 记录。

能被调用

CLI 跑通后，还要验证 local API。
HTTP 状态、响应 JSON 和 server log 要留证据。

专题 05 · 证据链

四类运行证据不能混成一个速度

证据	回答的问题	写进报告哪里
CLI stderr timing	单次 prompt 的 prefill、decode 和 total time	第 5 节 runtime 实验
llama-bench	标准化 pp、tg 能否支撑参数比较	第 5 节 benchmark 行
nvidia-smi / tegrastats	显存、RAM、温度和功耗是否可接受	第 5、7 节资源和风险
local API smoke test	服务接口是否可调用、是否超时或报错	第 6 节 API 服务测试

专题 05 · 课堂实作

第一轮验收只做四个动作

用同一 Qwen GGUF 复跑 CLI，并用 `2>&1 | tee` 保存日志
跑一次 llama-bench，分开记录 pp 和 tg
同步采样显存、内存、温度或功耗
启动 llama-server，完成一次 curl 或 Python smoke test

最小验收 同一个模型至少四类证据

CLI、bench、资源采样和 API 缺一项时，第 8 节建议只能写成“未完全验证”。

专题 05 · 指标误读

CLI 速度不能替代服务验收

失败样例

把 llama-bench 的 tg 当成 API 端到端延迟。
只说“GPU 启用”，没有记录 offload 和 fallback。
接口返回 200，却没有保存请求、响应和 server log。

报告落点

第 5 节: runtime 参数、benchmark 和资源证据
第 6 节: API 请求、响应、elapsed 和日志
第 7 节: fallback、OOM、超时和安全边界

专题 05 · 问题框架

先证明三段跑的是同一个对象

CLI、llama-bench 和 llama-server 的结果只有在模型文件、tokenizer/template 和 runtime 参数一致时才能放进同一张表；否则速度和质量结论都会失真。

课堂追问 server 有没有偷偷换模型或参数？

专题 05 · 核心概念

连续性先看身份、语义和执行

身份一致

模型路径、hash、量化格式和来源能对上。
server 请求里的 model id 不能替代文件证据。

语义一致

tokenizer、special token、chat template 要一致。
固定 prompt 的输出差异要能解释。

执行一致

ctx、`-ngl`、threads、batch 和 backend 要可比。
offload、fallback 和 warning 写进风险。

专题 05 · 证据图表

四段链路各留一类证据

链路段	最低证据	不合格信号
模型准备	来源、许可证、路径、文件大小、hash	只有模型名，没有具体文件
转换/量化	命令、参数、stdout/stderr、产物名	Q4/Q5 文件和 baseline 来源对不上
CLI / bench	runtime commit、ctx、`-ngl`、timing 日志	bench 换了参数还写进同一列
server / API	启动命令、model id、请求 JSON、server log	API 跑了别名或另一个模型路径

专题 05 · 课堂实作

课堂先填一张对象核对表

把 CLI、llama-bench、llama-server 的模型路径写成三列
补上 hash、量化格式、ctx、`-ngl`、threads 和 backend
保存 server 启动日志里的 model id、port 和 warning
三列对不上时，先改证据表，不急着写推荐

课堂验收 三列能对上才允许比较

对象核对表不通过时，CLI、bench 和 API 的数字不能支撑同一个部署建议。

专题 05 · 风险与报告

对象对不上会制造假结论

失败样例

server 跑了另一个模型或别名，却沿用 CLI 数字。
ctx、`-ngl` 或 threads 不一致，却比较 tokens/s。
template 或 tokenizer 漂移，被误写成量化质量问题。

报告落点

第 5 节: runtime 参数和对象核对表
第 6 节: server model id、请求 JSON 和响应日志
第 7 节: 对象不一致、fallback 和 template 风险

专题 05 · 问题框架

Runtime 选型先看证据能不能闭合

runtime 不是框架名投票；一条路线只有能证明模型格式、目标设备、backend/kernel、接口形态和日志字段都可复查，才允许进入部署建议。

课堂追问 这条路线能证明什么，不能证明什么？

专题 05 · 核心概念

三层匹配要落成三类证据

模型证据

GGUF、ONNX、engine、TFLite、Core ML 包含的信息不同。
tokenizer/template 和转换日志一起记录。

设备证据

CUDA、CPU、Metal、Vulkan、NPU 要看实际启用。
provider、delegate、compute units 和 fallback 都要留痕。

接口证据

CLI、SDK、HTTP server 不能共用一个延迟口径。
请求、响应、错误和 timeout 要能被应用侧复查。

专题 05 · 证据图表

Runtime 矩阵按证据等级排序

路线	本课状态	进入建议前要有什么
llama.cpp	主线实测	GGUF、CLI、bench、server、backend log
ONNX / TensorRT	候选对照	provider/engine、shape、fallback、精度回归
LiteRT / Core ML / ExecuTorch	端侧路线图	delegate、compute units、温度、包体和失败日志
MLC / vLLM / TensorRT-LLM	进阶 serving	compiled artifact、KV Cache、并发和 API 指标

专题 05 · 课堂实作

课堂只填主线和一个替代路线

主线写 llama.cpp：模型文件、backend、CLI、bench、server 证据
替代路线只选一个：ONNX/TensorRT、移动端或进阶 serving
写清替代路线解决什么瓶颈，缺什么实测证据
未实跑的路线只写候选，不写推荐

课堂验收 选型表不是愿望清单

推荐路线必须有日志；替代路线可以没有实测，但必须写适用条件、未测原因和下一步验证。

专题 05 · 风险与报告

Runtime 选型不能替代实验结论

失败样例

因为 TensorRT/MLC 听起来更强，就把未测路线写成推荐。
移动端路线和服务器路线混在一起比较。
provider、engine、delegate fallback 没被日志发现。

报告落点

第 5 节: runtime 选择理由、backend 和 fallback 证据
第 7 节: 未测路线、版本风险和维护成本
第 8 节: 推荐 runtime 与替代路线分开写

专题 05 · 问题框架

性能没变时先查三类假收益

文件变小、写了 -ngl 或换了 runtime，都不等于端到端更快；先证明没有 fallback、反量化再计算和负载形状漂移，再谈加速结论。

课堂追问 收益消失在哪一层日志里？

专题 05 · 核心概念

三类陷阱都有可观察信号

fallback

日志出现 provider 回退、unsupported op 或 CPU fallback。
GPU 采样很低，CPU 占用或等待时间升高。

反量化

低 bit 文件变小，但 tg tokens/s 没变。
kernel 仍按高精度或通用路径执行。

负载形状漂移

prompt、generated tokens、ctx 或 batch 改了。
bench 负载和 API 请求不是同一个形状。

专题 05 · 证据图表

性能收益要先被反证

现象	先查什么	证据字段
Q4 文件小但不快	低比特 kernel 或反量化路径	runtime log、tg tokens/s、显存
写了 `-ngl` 仍慢	实际 offload 层数和 fallback	stderr、`-ngl`、GPU/RAM 采样
bench 快但 API 慢	加载、排队、stream、timeout	curl elapsed、server log
换 prompt 后波动大	prompt tokens、generated tokens、ctx、batch	pp/tg 拆分、负载形状

专题 05 · 课堂实作

课堂先给每个慢结果贴标签

选一条速度没有提升的记录。
贴标签: fallback、dequant、shape、API overhead、quality regression、untested。
找一条能支持标签的日志或资源采样。
找不到证据就写未记录，不写“可能是”。

课堂验收 慢不是结论

只有现象、标签、证据和下一步动作都齐，才能进入第 5 节 runtime 实验表。

专题 05 · 风险与报告

性能陷阱要写成风险和回退

失败样例

只看 tg tokens/s，不看 prompt eval、API elapsed 和质量。
GPU utilization = 0% 就误判 GPU 没用，没看显存、功耗或更长采样。
API 慢于 CLI，却直接推荐服务化。

报告落点

第 5 节: 写慢在哪里和支持证据。
第 7 节: fallback、反量化、shape/API 风险。
第 8 节: 写保留、回退或下一轮 profiling。

专题 05 · 问题框架

llama.cpp 实作从 baseline 开始

这 45 分钟先留下一份能复跑的 Qwen GGUF baseline：llama.cpp commit、CUDA build、模型 hash、固定 prompt、stderr timing 和质量样例。后续快慢才有锚点。

课堂追问 这条记录能让别人原样跑一遍吗？

专题 05 · 核心概念

Baseline 先锁住对象、负载和证据

对象

模型路径、文件大小、SHA256、量化格式。
llama.cpp commit 和 CUDA 构建日志。

负载

固定 prompt、ctx-size、生成长度、seed 和 temperature。
后续 Q8/Q5/Q4 只改一个变量。

证据

保存 stdout/stderr、GPU 采样和输出样例。
提取 prompt eval、eval、tokens/s 和 warning。

专题 05 · 证据图表

Baseline 有四个验收口

步骤	验收动作	不能缺的证据
CUDA build	`-DGGML_CUDA=ON` 后检查可执行文件	cmake/build log、llama.cpp commit
模型入库	确认 Qwen GGUF 路径、大小和 SHA256	模型信息表、来源和许可证
CLI run	固定 prompt、ctx、`-ngl`、seed	qwen-baseline 日志
结果解读	抽取 prompt eval、eval、显存和输出质量	报告第 3 节字段

专题 05 · 课堂实作

命令必须同时展示参数和日志路径

cd ~/edge-ai-lab/src/llama.cpp
MODEL=~/edge-ai-lab/models/qwen/qwen2.5-1.5b-instruct-q4_k_m.gguf
./build/bin/llama-cli -m "$MODEL" \
  -p "用三句话解释端侧模型量化的价值。" \
  -n 128 --ctx-size 2048 -ngl 99 \
  --temp 0.2 --seed 42 \
  2>&1 | tee ~/edge-ai-lab/logs/qwen-baseline-q4.txt

课堂验收 命令页要能复跑

模型路径、prompt、seed、ctx-size、生成长度、-ngl 和日志路径都不能只写在口头说明里。

专题 05 · 风险与报告

CLI baseline 不稳会污染后续实验

失败样例

只截图输出，不保存 stdout/stderr 和日志路径。
llama.cpp commit、模型 hash、ctx 或 -ngl 未记录。
baseline 跑 Q4，后续 Q5/Q8 又换 prompt 或 seed。

报告落点

第 2 节: 模型来源、许可证、SHA256 和 runtime commit。
第 3 节: baseline 命令、prompt eval、eval、显存和质量样例。
第 5-6 节: Q8/Q5/Q4、offload 和 API 都回到这条 baseline。

专题 05 · 问题框架

Profiling 不是 tokens/s 截图

课堂 profiling 的目标不是找一个最大数字，而是证明同一条 baseline 在改变一个变量后，负载、pp/tg、资源状态和输出质量发生了什么变化。

课堂追问 这次实验只改了哪个变量？

专题 05 · 核心概念

一行 profiling 记录要有四类证据

负载

prompt tokens、generated tokens、ctx-size、并发数。
CLI 和 API 负载不能混成一行。

Timing / 资源

prompt eval/pp 与 eval/tg 分开记录。
VRAM/RAM、温度、功耗和 warning 同步保存。

质量

固定 prompt 输出和失败标签同步记录。
更快但答错不能进入推荐。

专题 05 · 证据图表

结果表按问题拆字段

字段	课堂记录什么	用来回答什么
workload	prompt tokens、生成长度、ctx、并发	数字是否可比
timing	prompt eval、eval、pp/tg、elapsed	慢在 prefill 还是 decode
resource	显存/RAM、温度、功耗、GPU/GR3D	是否碰到设备边界
quality	输出样例、失败标签、质量备注	速度提升是否可用

专题 05 · 课堂实作

课堂采集顺序固定成三步

先运行 CLI：用 2>&1 | tee 保存 stdout/stderr。
再采系统：Ubuntu 用 nvidia-smi，Jetson 用 tegrastats。
再拆 timing：记录 prompt eval、eval、pp/tg 和 warning。
最后补质量：固定 prompt 输出、失败标签和日志路径。

课堂验收 短跑不要只看 GPU utilization

短实验可能采到 0%；同时看显存、功耗、llama.cpp timing，需要稳定利用率时改用更长生成或 llama-bench。

专题 05 · 风险与报告

Profiling 不合格会让建议失真

失败样例

只截屏，没有原始命令、stderr 日志和重复条件。
把 CLI tokens/s、llama-bench pp/tg 和 API elapsed 写成同一指标。
GPU utilization 采到 0% 就下结论，没看显存、功耗和 timing。

报告落点

第 5 节: profiling 表、日志索引、pp/tg 和质量备注。
第 7 节: warning、资源边界、热降频和质量回归风险。
第 8 节: 推荐参数必须指回同一 baseline 和日志。

专题 05 · 问题框架

Local API 只验收服务化新增证据

CLI baseline 证明模型能跑；local API 要额外证明 endpoint、model alias、请求 JSON、响应 JSON、elapsed、server log、端口、安全边界和资源状态都可复查。

课堂追问 API 证据能回到哪条 CLI baseline？

专题 05 · 核心概念

API 验收分成三张账

服务端账

记录模型路径、host/port、ctx、-ngl 和 backend。
检查 ready、warning、OOM、fallback 和 server log。

客户端账

保存 curl 或 Python 请求 JSON。
记录 HTTP 状态、elapsed、响应 JSON 和错误 JSON。

边界账

默认绑定 127.0.0.1 或受控内网。
记录 timeout、模型别名和是否含敏感数据。

专题 05 · 证据图表

API smoke test 留四份证据

证据	最低保存内容	回答的问题
server log	启动命令、模型、backend、端口	服务是否跑对模型
request JSON	model、messages、temperature、max_tokens	客户端实际发了什么
response/meta	HTTP status、elapsed、响应 JSON	接口是否真的可调用
CLI 对照	baseline、资源变化、质量备注	API 是否值得接入应用

专题 05 · 课堂实作

API 验收要同时启动服务和记录响应

./build/bin/llama-server -m "$MODEL" -ngl 99 \
  --ctx-size 2048 --host 127.0.0.1 --port 8080 \
  2>&1 | tee ~/edge-ai-lab/logs/llama-server.txt

curl -sS http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d @~/edge-ai-lab/logs/api-curl-request.json \
  -o ~/edge-ai-lab/logs/api-curl-response.json \
  -w "HTTP:%{http_code} elapsed:%{time_total}s\n"

课堂验收 第 6 节只收可复查 API 证据

启动日志、请求体、响应体、meta 和 CLI baseline 对照缺任一项，都不能写成 API 已验收。

专题 05 · 风险与报告

API 成功也不等于可用

失败样例

HTTP 200，但回答质量不合格。
CLI 很快，API 慢在冷启动、JSON、排队或超时。
server 使用错误模型，model alias 误导记录。
端口暴露到公网，local-first 边界失效。

报告落点

第 6 节: 启动命令、请求 JSON、响应 JSON、HTTP 状态和 elapsed。
第 7 节: timeout、server 异常、资源变化和暴露范围。
第 8 节: 是否进入应用、VLM 或 Agent 集成。

专题 05 · 问题框架

专题五收口先过报告闸门

模型和量化表只说明“哪个版本可能可用”；runtime profiling、API smoke test 和风险登记补齐后，才有资格写第 8 节部署建议。

课堂追问 这条建议能指到哪份日志？

专题 05 · 核心概念

专题五交付三包证据

Runtime 包

模型格式、runtime commit、backend、-ngl、ctx。
warning、fallback、未测路线和回退参数。

Profiling 包

CLI timing、llama-bench、资源采样和质量样例。
每行结果都能追到日志或采样文件。

API 包

server log、request/response JSON、HTTP meta。
host 绑定、timeout、model alias 和服务化风险。

专题 05 · 证据图表

报告第 5-8 节要这样承接

报告位置	必须写入	不能替代
第 5 节	runtime 参数、pp/tg、资源采样、日志路径	不能只写 tokens/s
第 6 节	server log、请求/响应、HTTP meta、模型 hash	不能用 CLI 结果替代 API
第 7 节	warning、fallback、timeout、OOM、质量退化	不能只报成功输出
第 8 节	推荐、不推荐、回退参数和下一步验证	不能写无证据推荐

专题 05 · 课堂实作

进入专题六前先做证据盘点

把第 5 节 runtime/profiling 表补到有日志路径。
把第 6 节 API 表补到有请求、响应和 meta。
把第 7 节风险表补到有失败现象和缓解动作。
给第 8 节先写推荐、回退、不推荐和下一步。

课堂验收 缺证据就写未记录

下一专题可以扩展设备和系统场景，但不能替代本专题缺失的 runtime、profiling 或 API 证据。

专题 05 · 风险与报告

证据没闭合时不能写最终建议

失败样例

没有 API 化证据，却写“可集成应用”。
没有失败样例，只保存成功输出。
推荐版本的成立条件、回退参数和不推荐方案缺失。
CLI、bench、API 指向的模型文件或 hash 对不上。

报告落点

第 5 节: runtime 参数实验成稿。
第 6 节: API 服务测试成稿。
第 7 节: 风险和缓解动作成稿。
第 8 节: 只写证据闭合的建议。

专题 06 · 201-240

专题六从同一条 baseline 迁移到 Jetson 和移动端路线

不重开模型路线；把专题五闭合的 Ubuntu baseline 迁移到 Jetson 或移动端路线，再判断 VLM、Agent 和最终建议是否有证据支撑。

输入专题五三包证据

方法Jetson 实测 + 移动端路线图

交付风险边界和最终建议

专题 06 · 端侧迁移

迁移不是换设备跑一次命令

先证明同源

模型 hash、量化格式、prompt、ctx、-ngl 和 runtime commit 要对上。
对不上时只能写新实验，不能写迁移对照。

再记录设备

Jetson 写型号、内存、JetPack/L4T、功耗模式和 tegrastats。
移动端先写格式、runtime、delegate 和未测原因。

最后写边界

实测、失败、未记录和路线图要分开。
VLM/Agent 扩展只能继承已闭合证据。

专题 06 · 收束表

迁移前先做证据对照

对象	新增变量	最低证据
Ubuntu baseline	作为对照锚点	模型 hash、CLI/API 日志、profiling 表
Jetson 实测	统一内存、功耗、温度、软件栈	L4T/JetPack、nvpmodel、tegrastats、运行日志
移动端路线	runtime、delegate、包体、温度	模型格式、backend、fallback、未测说明
VLM/Agent	输入链路、工具权限、状态恢复	输入样例、policy check、trace log
最终报告	推荐、不推荐和下一步验证	日志路径、风险登记、证据缺口

专题 06 · Jetson 记录

Jetson 迁移先验环境，再比较速度

设备型号、内存、JetPack / L4T、CUDA/TensorRT。
功耗模式、散热、电源和存储空间。
同一 Qwen GGUF、hash、prompt、ctx-size 和量化档位。
推理前后 tegrastats、stdout/stderr 和质量样例。

最小验收 Ubuntu vs Jetson 对照表

服务器结果只能做 baseline。Jetson 结论必须来自同一模型、同一 prompt 和设备状态日志。

专题 06 · 最终复盘

没有本机日志只能写路线图

失败样例

写“适合手机部署”，但没有 LiteRT/Core ML/ExecuTorch 实测或未测说明。
写“Jetson 可用”，但没有 tegrastats、功耗模式和温度记录。
只做工具调用 demo，忽略权限、确认和失败恢复。

报告落点

第 2 节: 目标设备和软件栈。
第 7 节: 系统风险和未测边界。
第 8 节: 本地、降级或端云协同建议。

专题 06 · 问题框架

VLM 先定位输入链路，再评价模型质量

纯文本 baseline 过了不代表 VLM 过了；图像输入、resize/crop、visual token、mmproj、LLM decode 和原始回答要拆开记录。

课堂追问 这次失败到底发生在哪一段？

专题 06 · 核心概念

VLM 链路按输入、对齐和生成三本账记录

输入账

image id、分辨率、裁剪、帧率和预处理耗时。
摄像头流要记录连续输入成本。

对齐账

visual token count、encoder latency、mmproj 文件和精度。
projector 版本不对会直接破坏多模态对齐。

生成账

prompt、ctx、pp/tg、KV Cache、原始回答和失败标签。
同一图片要保留原始输出。

专题 06 · 证据图表

视觉 token 决定 prefill 和 KV Cache 成本

记录项	课堂写法	为什么影响结论
输入尺寸	原图、crop/resize、帧率	OCR、小目标和空间关系会被输入策略改变
视觉 token	`n_vis ≈ H×W/(p²×m)`	token 越多，prefill 和 KV Cache 越重
Encoder/mmproj	encoder 耗时、mmproj 文件、精度和版本	对齐层出错会伪装成语言模型退化
LLM 输出	pp/tg、ctx、原始回答、失败标签	只有原始输出能支撑报告里的质量判断

专题 06 · 课堂实作

课堂实作先建一行 VLM 证据

保存输入图、image id、resolution、crop/resize 策略。
记录 visual token count、mmproj 文件、hash 和精度。
记录 encoder latency、LLM pp/tg、ctx 和峰值内存。
给 OCR、小目标、空间关系和格式错误贴失败标签。

课堂验收 没有输入图和 mmproj 记录，就不能评价 VLM

VLM 报告至少要保存输入图、处理参数、组件版本、原始输出和失败标签，不能只写一条总耗时。

专题 06 · 风险与报告

VLM 结论必须落到组件风险

失败样例

低分辨率导致 OCR 错，却误判为模型知识不足。
视觉 token 太多，prefill 和 KV Cache 暴涨。
mmproj 与语言模型版本不匹配，输出异常。

报告落点

第 7 节: VLM 输入、对齐和生成风险。
第 8 节: 纯端侧、端云协同或暂不推荐。
附录: VLM 专项 profiling 表和失败图例。

专题 06 · 问题框架

VLM 优化先让系统少看一点图

端侧 VLM 不应默认把每张原图都送进多模态模型；先用 ROI、分辨率、帧率、缓存或传统视觉初筛减少输入成本，再判断模型量化。

课堂追问 这张图真的需要完整 VLM 吗？

专题 06 · 核心概念

VLM 优化按输入、模型和系统三层取舍

输入先减负

ROI 裁剪、降分辨率、降帧率、缓存和去重。
目标是减少 visual token 和预处理复制。

模型再取舍

vision encoder INT8、LLM Q5/Q4、ctx 和 KV Cache 控制。
mmproj/projector 保持谨慎，必须单独回归。

系统最后兜底

端侧初筛，云端复杂推理，人工确认高风险结果。
记录路由条件、隐私边界和失败恢复。

专题 06 · 证据图表

VLM 优化动作必须绑定复测证据

现象	先做什么	复测证据
visual token 或预处理成本高	ROI、降分辨率、降帧率、缓存	OCR、小目标、空间关系和 pp 时间
vision encoder 占主耗时	TensorRT/ONNX/INT8 或换轻模型	视觉质量、backend 日志和峰值内存
LLM decode 占主耗时	Q5/Q4、ctx 控制、KV 策略	tg、ctx、输出格式和失败标签
端侧质量仍不够	端云协同或人工确认	隐私规则、fallback trace 和授权记录

专题 06 · 课堂实作

课堂实作只选一条 VLM 路线写清证据

判断场景是否真的需要完整 VLM。
能用传统视觉、OCR 或 ROI 初筛时先写替代路线。
复杂问答、隐私数据和高风险输出分开处理。
未实跑 VLM 时只写路线图、进入条件和未测风险。

课堂验收 推荐必须绑定输入规模和复测结果

“适合端侧 VLM”必须说明输入规模、质量阈值、隐私边界、复测记录和未测风险。

专题 06 · 风险与报告

VLM 推荐不能跳过输入和隐私边界

失败样例

所有图像都送给 VLM，预处理和 prefill 成本过高。
OCR 任务先降分辨率，质量不可用。
没有隐私边界，却把端云协同写成默认兜底。

报告落点

第 7 节: 多模态质量、隐私和 fallback 风险。
第 8 节: 端侧 VLM 推荐、不推荐或继续验证。
附录: 输入策略、复测表和未测路线。

专题 06 · 问题框架

Agent 端侧部署先过权限闸门

Agent 能在本地生成 JSON 不等于可以执行动作；工具白名单、确认点、阻断规则、状态保存和失败恢复要先通过策略校验。

课堂追问 这个工具调用为什么允许执行？

专题 06 · 核心概念

Agent 链路按意图、策略和状态三本账记录

意图账

planner output、tool intent、args 和目标对象。
小模型规划结果必须能被 schema 校验。

策略账

allowed、confirm_required、blocked 三个集合不能冲突。
高风险工具默认确认或阻断。

状态账

session、memory、tool result、error 和 recovery action。
状态要可清理、可恢复、可审计。

专题 06 · 证据图表

Agent 权限表先验证集合，再验证动作

检查点	最低要求	失败时写法
集合互斥	同一工具不能同时 allowed、confirm_required、blocked	policy invalid，不进入执行
高风险 denylist	`run_shell`、`delete_file`、发送/联网默认阻断	只能写路线图或需人工确认
参数校验	tool args 通过 schema 和范围检查	拒绝执行并记录原因
执行边界	应用层 executor 执行，模型只给意图	不能写已验收 Agent

专题 06 · 课堂实作

课堂实作保存一条可重放 Agent trace

planner output、tool intent、tool name 和 args。
schema result、policy result、permission decision。
confirm_required、blocked reason、execution status。
observation、error、recovery action 和脱敏日志路径。

课堂验收 没有 trace 就不能写 Agent 已验收

JSON 合法只能证明模型会输出格式；策略校验、执行状态和恢复记录才支撑部署判断。

专题 06 · 风险与报告

Agent 风险要写成策略缺口

失败样例

allowed、confirm_required、blocked 三个集合互相冲突。
高风险工具进入 allowed，模型可绕过确认。
工具失败没有 recovery action，模型编造成成功。

报告落点

第 7 节: Agent 权限、状态、隐私和恢复风险。
第 8 节: 接入 Agent、只做路线图或暂不推荐。
附录: policy validator 和 trace 证据。

专题 06 · 问题框架

Function Calling 只是意图，不是执行权限

模型可以生成工具调用 JSON，但执行权在应用层：schema validator、policy check、confirm gate 和 executor 都要能拒绝调用；local API 只是入口。

课堂追问 哪一道门能拒绝危险工具调用？

专题 06 · 核心概念

工具调用先过三类闸门

Schema gate

校验工具名、参数类型、必填项、范围和默认值。
合法 JSON 不等于参数可信，也不等于业务允许。

Policy gate

allowed、confirm_required、blocked 三类互斥。
高风险 denylist 不能进入 allowed，确认点要可记录。

Executor gate

应用层二次校验后执行，模型不能直接操作系统。
返回 status/error/observation，失败、超时和拒绝都写 trace。

专题 06 · 证据图表

工具调用日志要证明每道门怎么判

门槛	保存字段	失败写法
模型意图	tool name、args、reason	不需要工具时返回普通回答
Schema gate	schema result、missing/conflict fields	拒绝调用或要求重试
Policy / confirm	policy result、confirm flag、deny reason	阻断、人工确认或 fallback
Executor result	status、error、observation、trace id	失败恢复，不把 error 写成成功

专题 06 · 课堂实作

课堂实作只交付可审查调用样例

保存 local API response，证明模型能产出工具意图。
给出 tool schema，写清参数类型、范围和必填项。
保存 validator 与 policy result，说明允许、确认或阻断。
保存 executor status/error/observation 和脱敏 trace 路径。

课堂验收 本课不让模型直接操作系统

没有 validator、policy、executor 和 trace 时，只能写接入条件，不能写可部署 Agent。

专题 06 · 风险与报告

工具调用风险必须写成证据缺口

失败样例

JSON 合法，但字段冲突或 schema 缺必填项。
policy validator 判失败，报告却写成允许执行。
高风险工具缺 confirm gate，或确认记录不可追溯。
工具返回 error，模型把失败编造成成功。

报告落点

第 6 节: local API 只证明服务入口。
第 7 节: schema、policy、executor 和 trace 风险。
第 8 节: 集成、只做路线图或暂不推荐。

专题 06 · 问题框架

端云协同先判定能不能出端

端云协同不是“本地不行就上云”；每条请求先判定敏感级别、任务复杂度、工具风险和网络状态，再选择 local、cloud fallback、人工确认或拒绝。

课堂追问 这次请求允许上传哪些字段？

专题 06 · 核心概念

端云路由先过三道闸门

Privacy gate

原始图片、日志、位置和个人数据默认留在端侧。
允许上云时只上传脱敏字段、摘要或用户确认内容。

Capability gate

固定格式抽取、摘要和低风险工具优先走本地 SLM。
长上下文、开放推理和知识补全才进入云端候选。

Failure gate

本地低质量、云端失败、断网都要有降级路径。
fallback reason、authorization 和 final source 进入日志。

专题 06 · 证据图表

路由表要把任务类型落到字段

任务类型	默认路径	证据字段
固定格式抽取	本地 SLM	output schema、通过率、latency
本地日志摘要	本地优先，脱敏后兜底	sensitivity、redaction、upload_allowed
工具参数生成	本地生成，应用层校验	schema result、policy result、confirm flag
长文复杂推理	云端候选或受限回答	context length、fallback reason、authorization
设备控制	只读或建议，动作需确认	tool level、rollback、trace id

专题 06 · 课堂实作

课堂交付是一条可重放路由样例

记录 request_id、task_type、sensitivity 和 upload_allowed。
保存 local result、quality check、latency 和 timeout。
触发 fallback 时保存 reason、uploaded_fields 和 authorization。
最后写 final_source、output schema、拒绝原因或重试计划。

课堂验收 架构图必须能被日志复核

没有 privacy gate、能力边界、授权记录和 fallback trace 时，只能写概念路线图。

专题 06 · 风险与报告

端云协同风险要写成边界缺口

失败样例

本地质量不达标，但没有触发 fallback 阈值。
fallback 上传原始敏感数据，缺少脱敏字段表。
云端和本地输出 schema 不一致，应用层无法接。
断网时没有受限回答、重试计划或用户提示。

报告落点

第 1 节: 哪些数据不能离开设备。
第 7 节: 隐私、网络、授权和 fallback 风险。
第 8 节: local-first、hybrid 或暂不推荐。

专题 06 · 问题框架

案例复盘先找主瓶颈

传统视觉、小型 LLM、VLM 和 Agent 的瓶颈不一样；最后复盘先写目标、workload、瓶颈和证据，再判断量化、runtime、架构或权限是否真的解决问题。

课堂追问 这个结论能被哪条日志推翻？

专题 06 · 核心概念

四类案例各有一套证据

传统视觉

看输入尺寸、预处理、算子支持和设备延迟。
INT8 是否有效取决于 backend、delegate 和校准覆盖。

小型 LLM

看 GGUF Q8/Q5/Q4、KV Cache、pp/tg 和 API smoke test。
速度表旁边必须放固定 prompt 输出和失败标签。

VLM / Agent

VLM 拆输入、visual token、mmproj、LLM 和输出。
Agent 拆 schema、policy、trace、fallback 和确认记录。

专题 06 · 证据图表

案例矩阵用来决定下一步实验

案例	先定位	证据	下一步
传统视觉	输入 / 算子 / delegate	accuracy、latency、fallback log	换 runtime 或补校准
小型 LLM	权重 / KV / runtime / API	Q8/Q5/Q4、pp/tg、质量样例	回退量化或调参数
VLM	图像 / visual token / projector	输入图、组件耗时、失败标签	先减输入或改架构
Hybrid Agent	权限 / 状态 / fallback	schema、policy、trace、恢复动作	补策略或只写路线图

专题 06 · 课堂实作

每个案例交一张复盘卡

目标: 场景、设备、workload、阈值和不可接受风险。
条件: 模型、量化、runtime、ctx、硬件和日志路径。
结果: 质量、延迟、内存、失败标签和主瓶颈。
判断: 推荐、回退、暂不推荐或下一轮只测一个变量。

课堂验收 案例结论必须能回到报告字段

目标进第 1 节，条件进第 2-6 节，失败和判断进第 7-8 节。

专题 06 · 风险与报告

案例复盘失败通常因为证据错位

失败样例

把所有案例都套 Q4，却没有定位主瓶颈。
只展示最快数字，没有 workload、日志和失败样例。
传统视觉、VLM 和 Agent 混用同一质量指标。
Agent 只看模型回答，不看 policy、confirm 和 trace。

报告落点

第 7 节: 任务形态、系统风险和未测边界。
第 8 节: 推荐、回退、暂不推荐和下一步。
第 9 节: 日志、复盘表和参考资料。

专题 06 · 问题框架

最终收束要变成证据索引

今天不是以 demo 跑通结束，而是以端侧部署评估报告结束；每个推荐、不推荐和继续验证都要指向命令、参数、日志、输出样例或失败记录。

课堂追问 这句话背后的证据在哪里？

专题 06 · 核心概念

最终建议只有三种合格写法

暂不推荐

质量不稳、资源不满足、API 未验收或权限风险过高。
不推荐也必须绑定日志、样本、失败原因和回退方案。

继续验证

缺少长稳、功耗、更多样本、Jetson/移动端或 VLM/Agent 证据。
写清下一轮先补哪条证据，不能写“继续优化”。

专题 06 · 证据图表

报告验收表按证据链检查

报告模块	必须有的证据	不合格信号
1-2 场景与环境	目标设备、任务、模型来源、环境快照	只写“端侧部署”
3-4 baseline 与量化	Q8/Q5/Q4 同源、同 prompt、同 runtime	变量混在一起
5-6 runtime 与 API	CLI、bench、server log、请求和响应	只给 tokens/s
7-8 风险与建议	失败样例、fallback、推荐/回退/不推荐	只展示成功
9 附录	命令、日志路径、表格、失败样例	找不到原始证据

专题 06 · 课堂实作

最后一小时只补证据缺口

补场景、设备、环境快照和模型 hash。
补 prompt、ctx、seed、量化版本和同条件说明。
补 profiling、API smoke test、server log 和请求响应。
补风险登记、fallback、未测说明和下一轮验证。

课堂验收 缺证据就标注未完成或未测

没有记录的“感觉更快”不作为结论；缺字段写未记录，不靠回忆补数字。

专题 06 · 风险与报告

最终报告不通过通常因为证据断链

失败样例

结论没有绑定目标设备、workload 和质量阈值。
量化数字只有均值，没有 prompt、样本和日志。
CLI、bench、API 跑的不是同一模型和参数。
只展示成功，不写风险、回退和未测边界。

报告落点

提交物: 端侧 Qwen 小模型部署评估报告。
评分: 问题定义、复现证据、量化判断、profiling、API、风险和建议。
最终页: 推荐、回退、暂不推荐或后续验证。

附录 · 扩展参考 · 241-288

扩展参考：TinyML 与端侧系统

用 tinyML Foundation、HarvardX/TinyML、MIT 6.5940、MLSys 公开课程补强设备、runtime、传感器和系统复盘视角。

定位扩展参考

用途支撑主课复盘

范围48 页

扩展参考 · 核心概念

tinyML 为什么是端侧 AI 的落脚点

核心定义

在极低功耗嵌入式设备上执行 ML 推理。
重点不是云端训练，而是把智能贴近物理世界。

端侧范围

与手机、车载、IoT、摄像头和 Jetson 场景一致。
能解释端侧场景为什么不止是 LLM。

工程约束

mW 级功耗、有限内存、有限算力。
必须先讲设备约束，再讲量化和 runtime。

扩展参考 · 证据图表

AI / ML / DL / TinyML 关系图解释端侧层级

1Artificial Intelligence

2Machine Learning

3Deep Learning

4Embedded Systems

5TinyML

6Edge AI deployment

扩展参考 · 核心概念

训练与推理要分开讲

Training

学习输入到输出的映射。
会调整模型内部权重和超参数。

Inference

在新输入上执行模型并输出预测。
端侧部署关注的是 inference 约束。

端侧边界

训练通常不在终端设备上完成。
推理、微调和部署要分开记录。

扩展参考 · 证据图表

Cloud / Edge / Things 三层架构

1Cloud backend

2Edge gateway

3On-device sensors

4Local preprocessing

5Local inference

6Cloud fallback

扩展参考 · 证据图表

MPU 与 MCU 的硬件谱系

维度	Microprocessor	Microcontroller
系统	OS、外设、外部内存	裸机/RTOS、片上外设
资源	MB-GB 级内存，可能有 GPU	KB-MB 级内存，实时/DSP 能力
部署路线	PC/Jetson/手机路线	IoT/传感器/低功耗路线

扩展参考 · 核心概念

“Things” 由输入、处理和输出组成

输入

传感器、通信接口、物理对象状态。
音频、图像、IMU、环境量都是模型输入。

处理

MCU/SoC、内存、存储、runtime。
预处理和后处理同样占资源。

输出

actuator、告警、网关上报、UI 反馈。
部署报告要说明模型结果如何进入产品动作。

扩展参考 · 核心概念

tinyML 的五个价值点

低功耗

适合电池供电和长期在线场景。
功耗/温度应进入设备画像。

弱网/离线

不依赖互联网即可推理。
local-first 与 fallback 要拆开设计。

隐私/延迟/成本

数据留在采集点，响应更快。
低成本硬件支撑大规模部署。

扩展参考 · 证据图表

tinyML 用例地图扩展端侧场景

场景	典型任务	对本课的启发
Healthcare	异常/疾病/睡眠检测	隐私和长稳测试
Agriculture	土壤、病虫害、产量	低功耗和弱网
Industrial	预测维护、过程控制	传感器、边缘网关、报警
Transport/Retail	驾驶监控、自动结账	实时性和风险控制

扩展参考 · 证据图表

传感器就是机器的感官

1Motion / IMU

2Sound / Microphone

3Sight / Camera

4Environment sensors

5Proximity / Distance

6Dedicated local models

扩展参考 · 证据图表

Edge Impulse / MLOps 工作流强调实验闭环

1Understand problem

2Collect data

3Prepare data

4Choose model and train

5Validate and retrain

6Deploy

7Observe and iterate

扩展参考 · 核心概念

HarvardX: TinyML = Embedded Systems + Machine Learning

交叉点

TinyML 位于嵌入式系统和机器学习交叉处。
端侧课程必须同时讲模型和设备。

设备视角

不要只讲 Qwen/LLM。
MCU、传感器、TF Micro 说明更小设备的部署边界。

主课连接

专题一设备画像。
专题五 runtime 与部署链路。

扩展参考 · 证据图表

三步推理链：输入、处理、动作

1Sensor input

2Preprocess input

3Run model

4Postprocess output

5Execute command

6Record evidence

扩展参考 · 证据图表

TinyML 挑战 A：Compute / Memory / Storage

资源	课堂讲法	报告字段
Compute	CPU/DSP/NPU 是否够用	latency, throughput
Memory	RAM / tensor arena / KV cache	peak memory
Storage	Flash / model file / binary	model size, binary size

扩展参考 · 核心概念

TinyML 挑战 B：软件栈和平台碎片化

OS 不一致

手机、Linux、RTOS、裸机差异很大。
同一个模型不等于同一个部署链路。

库支持缺口

嵌入式平台缺少完整系统库。
framework features 不能默认存在。

验收证据

runtime 选型要说明系统支持边界。
报告写清 OS、SDK 和 runtime 版本。

扩展参考 · 证据图表

TinyML 挑战 C：模型变大而设备受限

1Model size growth

2Training compute growth

3Memory pressure

4Deployment gap

5Compression and runtime choices

扩展参考 · 证据图表

TinyML 挑战 D：压缩工具箱

1Pruning

2Quantization

3Knowledge distillation

4Architecture choice

5Runtime profiling

6Deployment regression

扩展参考 · 核心概念

HarvardX 课程结构强调基础、应用和部署

Fundamentals

ML/TinyML 基础语言。
先建立设备和模型共同语言。

Applications

用真实应用串联背景和数据。
案例段要回答任务、输入和风险。

Deploying

从模型到设备运行。
runtime 和本地服务都要留下证据。

扩展参考 · 核心概念

Endpoint 设备的传感器密度

传感器类别

motion、acoustic、image、environment、proximity。
输入不是只有 prompt。

对 VLM/Agent 的意义

传感器决定任务类型和风险。
本地模型可以做初筛和事件触发。

报告字段

多传感器输入会影响 Agent 工具链。
报告要写数据采集和隐私边界。

扩展参考 · 核心概念

Responsible AI 问题要前置

建什么

What am I building?
任务目标不清，优化没有意义。

给谁用

Who am I building this for?
设备、人群、场景决定指标。

失败后果

What are the consequences if it fails?
决定安全、fallback 和人工确认。

扩展参考 · 证据图表

部署工作流必须形成完整闭环

1Collect data

2Preprocess data

3Design model

4Train model

5Evaluate

6Optimize

7Convert model

8Deploy model

9Make inferences

扩展参考 · 证据图表

嵌入式系统：sense → process → actuate

1Physical phenomenon

2Sense input

3Digital processing

4ML inference

5Actuate output

6Monitor behavior

扩展参考 · 证据图表

嵌入式硬件表提供设备画像字段

字段	示例	报告字段
Clock	MHz / GHz	CPU/GPU/NPU capability
Memory	Flash / RAM	model + runtime + cache
Sensors	Mic / IMU / Camera	input modality
Radio	BLE / Wi-Fi / LoRa	端云协同边界

扩展参考 · 核心概念

嵌入式 ML 软件栈

训练侧

TensorFlow/PyTorch/Keras 主要在上位机。
训练框架不是端侧 runtime。

部署侧

TFLite Micro、vendor SDK、裸机/RTOS。
需要模型格式、内存和算子支持。

链路证据

必须区分 framework、runtime、backend。
报告要记录转换链路。

扩展参考 · 核心概念

TF Micro 展示嵌入式 runtime 分层

硬件异构

CPU、NPU、GPU、DSP 都可能出现。
kernel 覆盖决定真实速度。

资源限制

memory、power、missing library features。
嵌入式缺少 malloc 或完整 OS 支持。

课堂落点

作为 llama.cpp 之外的 TinyML runtime 对照。
解释 MCU 端和 LLM 端部署差异。

扩展参考 · 证据图表

Model format / FlatBuffer 说明格式层边界

1Training model

2Convert to flatbuffer

3Compile into firmware

4Load interpreter

5Allocate tensors

6Invoke operator kernels

扩展参考 · 核心概念

Tensor Arena 说明运行期内存不能省略

为什么重要

嵌入式 RAM 可能只有几十到几百 KB。
端到端应用很容易撞上内存上限。

课堂类比

TFLM tensor arena 类似 LLM 的 KV cache：不是模型文件大小就结束。
运行期内存必须单独测。

报告字段

RAM / peak memory / allocation failure。
长稳运行和重启行为。

扩展参考 · 核心概念

OpsResolver：二进制大小和算子覆盖

为什么重要

框架代码本身占 Flash。
嵌入式设备可用 Flash 很有限。

工程做法

只注册需要的 operators。
减少 binary size，降低不必要依赖。

报告证据

对应专题五的 unsupported op / fallback。
报告要记录算子覆盖和 warning。

扩展参考 · 证据图表

KWS 应用架构展示传统 TinyML 闭环

1Audio capture

2Feature extraction

3KWS model

4Inference loop

5Post-processing

6Command / wake word

扩展参考 · 核心概念

传感器生态：输入功耗也要算

传统 ML 盲点

只看模型，不看传感器采集功耗。
camera、IMU、mic 的功耗差别很大。

端侧指标

输入采集、预处理、推理、通信都消耗资源。
低功耗不只是低 bit。

放进报告

数据来源、采样率、传感器功耗和延迟。
VLM/音频/IMU 分开写。

扩展参考 · 风险与报告

Privacy：端侧不是自动隐私安全

课堂提醒

本地推理减少数据外发，但不消除数据采集风险。
训练数据、日志、缓存和本地 API 都可能泄漏。
隐私边界必须写进 system design。

报告落点

报告第 1 节: 数据是否出端
报告第 6 节: API host/port/日志
报告第 7 节: 隐私风险和缓解

扩展参考 · 风险与报告

Security：模型、固件和接口都要看

课堂提醒

设备可能被物理接触、固件篡改或接口滥用。
本地 Agent 工具调用需要权限控制。
安全不能等到上线前才补。

报告落点

报告第 7 节: 权限与攻击面
第 8 节: 是否允许本地工具执行
附录: firmware/runtime/API 版本

扩展参考 · 风险与报告

Monitoring after deployment：上线后还要观测

课堂提醒

模型漂移、环境变化、传感器老化会影响质量。
端侧设备需要日志、采样和远程诊断策略。
长期运行不是一次 smoke test。

报告落点

报告第 8 节: 下一步验证
长稳测试: 温度/功耗/错误日志
产品化: drift 和回滚策略

扩展参考 · 核心概念

专题一扩展：端侧问题框架需要 TinyML 视角

设备画像

增加 MCU/MPU/SoC/传感器字段。
把功耗、通信和输入形态前置。

场景地图

补 healthcare、agriculture、industrial、transport、retail。
把任务类型和风险放进地图。

端云协同

Cloud/Edge/Things 三层图替代空泛云边端。
明确 gateway 和 local inference 角色。

扩展参考 · 核心概念

专题二/四扩展：量化、压缩、蒸馏要和设备约束对齐

压缩工具箱

HarvardX 明确把 pruning、quantization、distillation 放一起讲。
我们专题四的压缩蒸馏可以更前置。

内存约束

Tensor Arena 说明运行期内存比模型大小更关键。
与 KV Cache、activation memory 联动讲。

失败样例

Flash 放不下、RAM 分配失败、operator 缺失。
不要只写 LLM 生成质量失败。

扩展参考 · 核心概念

专题五扩展：runtime 也要覆盖 TinyML 路线

LLM 路线

GGUF / llama.cpp / local API。
适合 Qwen 小模型主线。

TinyML 路线

TFLite Micro / FlatBuffer / Tensor Arena / OpsResolver。
适合 MCU、传感器和 KWS 案例。

共同点

格式、内存、算子、后端、日志、监控。
都必须用目标设备实测闭环。

扩展参考 · 核心概念

专题六扩展：VLM/Agent 之前先讲传感器系统

多模态输入

camera、mic、IMU、environment sensor。
不是所有输入都值得交给大模型。

专用小模型

KWS、person detection、motion detection 可本地初筛。
Agent 只处理被触发的高价值事件。

系统策略

传感器 -> tiny model -> local LLM/VLM -> cloud fallback。
这比“全量上 VLM”更工程化。

扩展参考 · 证据图表

参考课件的结构服务课堂节奏

做法	参考课件表现	课堂作用
短标题	一页只讲一个动作或问题	减少满屏 bullet
重复框架	挑战/例子/流程反复出现	每专题固定讲授节奏
真实图表	硬件表、流程图、系统图很多	使用设备表和日志表
项目导向	部署、监控、责任问题贯穿	每段回到报告字段

扩展参考 · 证据图表

扩展参考材料索引

材料	本地文件	用途
HarvardX selected slides	research/course-ppt/harvardx-tinyml-selected/	TinyML 设备/runtime/隐私监控
tinyML Foundation parsed deck	research/course-ppt/tinyml-foundation-peter-ing-quantization.md	TinyML 定义/用例/Edge Impulse 流程，补充页 280-287
MIT 6.5940 decks	research/course-ppt/mit-65940-*.pdf	课程节奏和 LLM/量化/部署结构
MLSys 2024 Atom slides	research/course-ppt/mlsys-2024-*.pdf	低比特 LLM serving

tinyML Foundation · 扩展参考

AI 能力层级：不要把智能说成一个词

1Reactive machines

2Limited memory

3Theory of mind

4Self awareness

tinyML Foundation · 扩展参考

ML 的课堂定义：从经验中提升表现

Experience

训练数据、环境反馈和历史样本。
端侧设备还包括现场数据漂移。

Task

检测人、识别语音、判断故障。
任务要能落到输入和输出。

Measure

准确率、误报、延迟、功耗。
课堂报告必须写清性能度量。

tinyML Foundation · 扩展参考

经典 ML 与深度学习：计算复杂度怎么来

路线	课堂讲法	部署影响
Classical ML	统计特征和较少参数	更容易解释和部署
Deep Learning	多层神经网络学习特征	算力、内存和数据需求更高
端侧取舍	用任务约束模型复杂度	不是越大越好

tinyML Foundation · 扩展参考

AI 架构谱系：Cloud AI 到 Edge AI

1Cloud AI: data leaves device

2Cloud + Edge: gateway preprocesses

3Edge AI: inference close to sensor

4TinyML: low-power local inference

tinyML Foundation · 扩展参考

IoT 到 AIoT：连接不是智能

IoT

物理设备通过 Wi-Fi、BLE、Zigbee、LoRa、蜂窝网络连接。
连接本身只解决数据通路。

AIoT

在传感器、网关或设备端执行推理。
把“采集数据”升级为“现场判断”。

系统边界

端侧 AI 不是把云模型搬小。
系统设计要同时写通信和推理边界。

tinyML Foundation · 扩展参考

tinyML Movement：这是工程社区，不只是算法主题

社区性质

non-profit、global community、multidisciplinary。
算法、硬件、软件和应用一起推进。

活动形态

summits、talks、vision challenge、meetups。
适合作为课后资料入口。

课堂价值

把学员从“调参”带到“部署系统”。
强调实践报告和复现实验。

tinyML Foundation · 扩展参考

Edge Impulse 实验页要强调数据闭环

1Understand problem

2Collect data

3Feature extraction

4Train and validate

5Deploy

6Retrain from field evidence

tinyML Foundation · 扩展参考

EON Compiler：压缩不只发生在模型文件

特征提取

前处理代码和 buffer 同样占资源。
传感器任务常常被输入链路限制。

编译优化

部署工具链会影响 ROM/RAM。
部署报告要把 compiler/runtime 放在一张图里。

报告字段

model size、binary size、peak RAM 分开写。
记录转换工具和优化开关。

扩展参考 · 总结归纳

扩展参考必须回到主课证据链

使用边界

附录只补充 001-240 的讲授主线。
外部图表只提供解释角度，部署结论仍看本地实验。
公开课材料进入正式页时必须重画或改写。

报告落点

主线仍以 Qwen/GGUF/llama.cpp 证据链为核心。
TinyML 参考补强设备、传感器、功耗和监控字段。
未实测内容只能写成扩展路线或风险说明。