meida/docs/开发任务包/T18-端侧小模型SPIKE.md

# T18 · 端侧小模型 SPIKE·MNN + Qwen3-0.6B 真机可行性与意图分类原型

> 对应需求：端云分工方案（弱网兜底 + 意图识别下沉端侧，见本文 §0 背景）｜ 分支：`task/t18-ondevice-llm-spike`
> 先读《README-FE批次.md》，ArkTS 严格模式铁律全部适用。**本任务是 SPIKE：产出是可运行的调试页 + 真机基准报告 + 结论，不是生产代码。**

## 0. 背景与分工结论（决策依据，勿复述进代码）

- 端侧只做「确定性高、判错代价低」的事：意图分类/越界拦截/离线兜底；需要记忆、知识库、规则引擎的生成永远留云端。
- 端侧结论默认是「建议」，云端权威。本 SPIKE 只验证可行性，**不接生产链路**（ApiClient fallback、hint 上行是 P1~P3 的事）。
- 框架选型：MNN 3.6.1（官方 harmony 产物，CPU-only，Apache-2.0）+ ModelScope 官方导出 `MNN/Qwen3-0.6B-MNN`（Apache-2.0，权重 450,810,338 B）。鸿蒙上 GPU/NPU 加速均不可用，按 CPU 规划。
- 内存红线：官方性能体验建议前台峰值 ≤1500MB；本任务验收按峰值 <1GB（加载后 native 堆）。

## 1. 目标（三问三答）

1. **跑不跑得动**：Qwen3-0.6B int4 在真机（麒麟芯片）上的首 token 延迟、生成速度、峰值内存——门槛：意图分类单次（输出 ≤32 token）**总耗时 <3s**、加载后 native 堆 **<1GB**、连续 9 次推理不因降频/内存崩掉；
2. **够不够准**：意图分类 smoke（标签集对齐《穿搭Agent-需求文档》§3.2 九类 + 越界）输出受 JSON schema 约束——门槛：20 条自建样例人工核对 **≥85%**（验证门槛；≥90% 上线门槛留待 P2 用服务端评测集）；
3. **链路通不通**：局域网下载 → 校验 → 加载 → 生成全链路可重复执行——门槛：新机器按本文档 §3 能在 30 分钟内复现。

**不达标就换方案（换 1.7B / 只做离线兜底 / 放弃端侧），不要硬做。**

## 2. 已就绪的契约（协调提交已提供，直接用）

- **MNN 预编译库**：`app/entry/src/main/libs/arm64-v8a/libMNN.so`（5.85MB，已验证含 `createLLM` 符号；官方 zip 只有 .so 没有头文件）。**不入库**（.gitignore），获取命令见 §3.1；
- **头文件**：`app/entry/src/main/cpp/third_party/mnn/include/`（MNN/* + llm/llm.hpp，来自 3.6.1 tag 稀疏克隆，**版本与 .so 严格绑定，禁止混版本**——C4 图融合新旧不匹配会静默算错）；
- **模型**：`models/qwen3-0.6b-mnn/`（6 个文件 + manifest.json，SHA256 已逐个与 ModelScope 官方清单核对）。**不入库**；
- **native 模块**：`app/entry/src/main/cpp/`（CMakeLists.txt / napi_init.cpp / local_llm.h/.cpp / types/liblocalllm/index.d.ts）。接口：`loadModel(dir)→Promise<string>`（空串=成功）、`generate(prompt,maxNewTokens)→Promise<string>`（JSON：text/first_token_ms/total_ms/chars）、`unloadModel()`、`isLoaded()`。计时在 native 侧（std::chrono）；
- **ArkTS 封装**：`ets/core/LocalLlm.ets`（下载/校验/加载状态机；SPIKE 只校文件尺寸，SHA256 流式校验留 P1）；
- **调试页**：`ets/pages/LlmTestPage.ets`（已注册 main_pages，入口在「我的」页底部「端侧LLM调试」，正式版移除）；
- **局域网服务器**：`scripts/serve-models.mjs`（零依赖，`node scripts/serve-models.mjs 8080`，打印局域网 IP）；
- **构建配置**：`entry/build-profile.json5` 已加 externalNativeOptions（仅 arm64-v8a；模拟器 x86_64 不在本任务范围——MNN 无官方 x86 鸿蒙包，且模拟器性能不代表真机）。

**FE 批次规程破例清单**（本任务新增/改动，超出 F 批次禁改范围，特此登记）：
`entry/build-profile.json5`（+externalNativeOptions）、`ets/core/LocalLlm.ets`（新文件）、`main_pages.json`（+1 页）、`components/f1/ProfileContent.ets`（+调试入口）、根 `.gitignore`（+models/ 与 libs/）。

## 3. 实现要点

### 3.1 环境复现（新机器 30 分钟口径）

```bash
# ① MNN 库（2MB）
mkdir -p models/mnn && cd models/mnn
curl -LO https://github.com/alibaba/MNN/releases/download/3.6.1/mnn_3.6.1_harmony_arm64_cpu.zip
unzip mnn_3.6.1_harmony_arm64_cpu.zip
cp mnn_3.6.1_harmony_arm64_cpu/arm64-v8a/libMNN.so ../../app/entry/src/main/libs/arm64-v8a/
# 头文件（与 .so 同 tag）：
git clone --depth 1 --branch 3.6.1 --filter=blob:none --sparse https://github.com/alibaba/MNN.git mnn-src
cd mnn-src && git sparse-checkout set include transformers/llm/engine/include
cp -r include ../../app/entry/src/main/cpp/third_party/mnn/
cp -r transformers/llm/engine/include/llm ../../app/entry/src/main/cpp/third_party/mnn/include/

# ② 模型（456MB）
mkdir -p models/qwen3-0.6b-mnn && cd models/qwen3-0.6b-mnn
for f in config.json configuration.json llm_config.json llm.mnn tokenizer.txt llm.mnn.weight; do
  curl -LO "https://modelscope.cn/models/MNN/Qwen3-0.6B-MNN/resolve/master/$f"
done
sha256sum -c <<< "953afb7e0165818add34a7a6caf0af5d0ed9428da102eb22c9b98ee9da292e9f  llm.mnn.weight"

# ③ 局域网服务（手机与电脑同 Wi-Fi）
node scripts/serve-models.mjs 8080   # 打印本机局域网 IP
```

### 3.2 真机验证步骤（用户在 DevEco 做，agent 不跑）

1. `app/.build-gate.bat`（或同等 hvigor 命令）构建 → 签名安装到真机（现有 debug 签名配置可直接用）；
2. App「我的」→「端侧LLM调试」→ 填开发机 IP → ① 下载 → ② 加载（记录加载耗时与 native 堆）→ ③ Benchmark（3 prompt × 3 次，首个为预热）→ ④ 意图 smoke（4 条样例人工核对 JSON 输出）；
3. 全程页面保持前台亮屏（无计算类长时任务，退后台会被冻结——这是产品约束不是 bug）；
4. 局域网 HTTP 明文：Network Kit 自 API 18 起默认支持明文 HTTP（本项目 targetSdk 6.1.1(24)，预期零配置可用；开发后端本身也是 `http://`）。真机若仍拦截，建 `resources/base/profile/network_config.json`（network-security-config/domain-config 白名单，仅调试，不得提交 release）；兜底改用 `hdc file send models/qwen3-0.6b-mnn /data/app/el2/100/base/<bundle>/haps/entry/files/models/`（先装 App 才有目录；注意物理路径与沙箱映射路径的区别）；
5. 若 `loadModel` 报 tokenizer 相关错误：该模型仓库用的是旧格式 `tokenizer.txt`（文档默认新格式 `tokenizer.mtok`），引擎回退行为未证实——在下载目录的 `config.json` 里加一行 `"tokenizer_file": "tokenizer.txt"` 再试（只改设备上的副本，不改 manifest）。

### 3.3 报告（`docs/开发任务包/T18-REPORT.md`，核心交付物）

结构对齐 T9：结论先行（三问三答：通过 / 有条件通过 / 不达标换方案）→ 基准数字表（机型/芯片/内存档位，首 token、总耗时、字/s、加载耗时、加载前后 native 堆、连续 9 次的降频曲线）→ 意图 smoke 明细 → 偏差与坑 → 对 P1（离线兜底）/P2（意图 shadow）的建议。

## 4. 验收标准

1. `assembleHap` 构建绿（.build-gate.bat）；
2. 真机三问三答有数字、有结论；
3. 复现文档（§3.1+§3.2）可独立执行；
4. 不入库的东西没入库：models/、libs/、任何模型权重；
5. 不改生产链路：ApiClient/ChatPage 的云端对话路径零改动（离线 fallback 是 P1 任务）。

## 5. 禁改清单

`ets/core/ApiClient.ets`、`AuthStore.ets`、`ApiTypes.ets`、`ContextHolder.ets`、除 LlmTestPage/ProfileContent 调试入口外的全部页面与组件、`module.json5`、后端仓库一切文件。

## 6. 提交信息

```
spike(ondevice-llm): MNN+Qwen3-0.6B harmony pipeline, bench page, LAN model serving

T18 可行性验证：native 骨架（liblocalllm+MNN 3.6.1）+ 局域网模型下载 +
LlmTestPage 基准/意图 smoke + T18-REPORT 三问三答（P1~P3 的决策依据）。

偏差说明：<写在这里，无则写"无">
```