Imported from LISTENAI/lnn_skills (lnn-model-pack-validation/SKILL.md). Install upstream with npx skills add LISTENAI/lnn_skills --skill lnn-model-pack-validation. Copyright stays with the author.

Thinker 模型打包与一致性验证

对 Linger 导出的量化 ONNX 计算图执行完整的 Thinker 算法适配：从模型检查开始，完成打包、拆分分析、参数优化和一致性验证。输入信息齐全时应自主执行，不要只给出建议命令；需要实际运行、检查结果、迭代参数、完成验证并汇报结论。

必要输入

打包前需要获取或可靠推导以下信息：

• 量化 ONNX 路径。
• 真实目标平台：venus、arcs 或 venusa。
• 部署目标真实可用的共享内存和 PSRAM 上限。
• 动态模型每个符号维度的 shape 范围。
• 可选的固定 .npy 输入，顺序必须与 ONNX 图输入一致。
• 可选的现有 libthinker.so，必须为同一平台构建并开启结果 dump。
• 可选的子图边界或流式模式，仅在部署设计明确需要时使用。

只有无法安全推导必要信息时才询问一个简短问题。禁止虚构硬件内存容量。如果用户没有提供内存限制，可以暂时使用文档或工具中的平台默认值，但必须在结果中明确标记该假设。

信息来源

执行前读取当前仓库文件，不要依赖记忆中的参数：

• docs/thinker_packer.md
• docs/thinker_validator.md
• docs/thinker_compile.md
• tools/tpacker/argument_parser.py
• 阈值行为不明确时读取 tools/tpacker/graph_optimizer/op_split.py
• tools/tpacker/load_model.py 和 tools/tpacker/graph/Graph.py，用于确认子图边界与裁剪方向。
• tools/tpacker/graph_analysis/combine.py 和 memory.py，用于确认张量放置、DMA buffer 和总内存规划。
• auto_test/arcs_test.sh、auto_test/venus_test.sh、auto_test/venusa_test.sh，用于查找同平台、同算子族的已验证配置。只能将其作为候选起点，不能照搬其中的 tensor 名称或假设其内存上限等于真实部署上限。

如果已安装命令可能与源码不同，运行 tpacker -h 和 tvalidator -h。验证本地源码修改时，优先使用当前检出的源码和重新安装的 pythinker。

必须区分的三种拆分

分析和汇报时必须明确使用以下术语，不得把三者统称为“子图拆分”：

threshold4、-m、--dma_prefetch 和总内存上限属于内存放置与规划，不是部署子图切分。7_graph_op_split.onnx 的存在也不能证明使用了 --inputs/--outputs。

部署子图边界规则

• --inputs 和 --outputs 接受逗号分隔的 graph entry/tensor 名称，不是算子节点名称；不要加入空格。
• --outputs 是反向依赖裁剪的根，--inputs 是反向遍历的停止边界。
• 只指定 --outputs 时保留原始输入边界；只指定 --inputs 时保留原始输出边界。
• 切分前必须从 ONNX 图连接关系生成资源 DAG，列出每个资源的有序输入输出，以及每条跨资源 tensor 的生产者和消费者。
• 分叉和汇合必须显式处理，不能默认模型是线性链。例如 auto_test 中已有以下成熟拓扑：
  • ARCS cat-face：part1 同时产生两个旁路特征和 part2 输入，part3 汇合旁路特征与 part2 输出。
  • VenusA body detect/text detect：前缀资源产生多个特征，后续资源分叉处理后再汇合。
  • ARCS translation encoder：使用连续边界组成线性四段链。
• 每段单独打包成功不代表整图切分正确。必须检查所有原始最终输出可达、没有遗漏跨段依赖、边界 tensor 的 dtype/shape/scale/layout 一致，并按 DAG 顺序做端到端 runtime 验证。
• 不要仅为解决单个算子拆分过多而先切部署子图。部署切分适合整体资源无法满足内存、应用已有调度边界、需要阶段复用或存在明确分叉/汇合接口的情况；单算子问题应先调 threshold1~3。

流式改图规则

• 仅在模型语义允许按空间轴分块且应用能维护新增 history/state 时使用。
• split_h 和 split_w 是流式方向，不是“按高度/宽度生成多个 bin”。
• 改图后重新检查资源公开 I/O；新增 history/state 必须纳入固定输入、runtime 测试和部署接口。
• auto_test 的成熟用法包括 VenusA TRUNet 的 split_h，以及 VenusA decoder/encoder 配置的 split_w。这些只能证明对应模型可用，不能推广为通用的内存修复开关。

安全与可复现性

• 保留输入 ONNX，不得原地修改。
• 从 Thinker 仓库根目录执行，因为两个工具都会使用相对路径 workspace/、data/、data.ignore/ 和 build/。
• 结果目录必须位于 workspace/<model> 之外，因为 tvalidator 会删除并重建该工作区。
• 记录每次尝试的完整命令、退出码、有效参数、资源大小和拆分指标。
• 每次只修改一类参数，并在尝试新候选前保存当前最佳成功资源。
• 禁止将 --ramsize 或 --psramsize 提高到真实硬件限制以上。阈值不是总容量，但也不得为了减少拆分而跳过平台硬限制或最终内存规划验证。
• 禁止仅为了降低拆分数而使用 --inputs、--outputs 或 --isstream。这些参数会改变部署计算图或执行方式，必须有明确的功能需求。
• 参数优化后禁止省略 tvalidator -r。省略 -r 会导致 tvalidator 使用默认参数重新打包，无法验证优化后的候选资源。
• 优先使用固定输入。如果 tvalidator 自动生成输入，保存 workspace/<model>/*_linger.npy，并通过 -i 固定输入重新运行后，才能认定问题可复现。
• 不要只依赖 shell 退出码判断 tpacker 成功。还要确认资源文件存在且非空，并检查日志中没有 Error occurred。

执行流程

1. 前置检查

1. 获取仓库、模型、结果目录、可选输入和仿真库的绝对路径。
2. 检查 python、tpacker、tvalidator、cmake 和所有输入文件是否存在。
3. 记录精简环境信息：
   • python --version
   • python -c 'import linger; print(linger.__version__)'
   • python -c 'from importlib.metadata import version; print(version("pythinker"))'
   • ONNX 包版本
   • Thinker Git 提交，以及工作区是否存在未提交修改
4. 使用 onnx.load 加载模型，在支持时执行 onnx.checker.check_model，并检查：
   • IR 和 opset 版本
   • 图输入名称、数据类型和 shape
   • 符号维度
   • 节点数和算子类型统计
   • 标识目标平台的模型元数据或节点属性
5. 确认请求的平台与计算图一致。平台不一致属于配置错误，不能通过调参绕过。
6. 动态图必须为每个必要符号提供合法的 name=min:max:factor。tpacker -c 和 tvalidator --cfg 必须使用相同配置。

建议使用以下结果目录：

<result_dir>/
├── attempts.tsv
├── commands.txt
├── best/
├── logs/
└── failure-report/       # 仅在失败时创建

2. 建立打包基线

使用明确的平台和部署内存约束执行基线打包，并开启 dump：

tpacker \
  -g <model.onnx> \
  -o <result_dir>/baseline.bin \
  -d True \
  -p <platform> \
  -r <真实共享内存字节数> \
  --psramsize <真实PSRAM字节数> \
  --dma_prefetch True \
  --threshold1 <初始值> \
  --threshold2 <初始值> \
  --threshold3 <初始值> \
  --threshold4 <初始值> \
  [动态shape或子图参数]

先建立两个基线：

1. 不改变部署边界的整图基线，用来判断失败来自单算子限制、总共享内存、PSRAM、DMA buffer 还是整图生命周期。
2. 仅当部署设计明确需要切图时，再建立带 --inputs/--outputs 的分段基线。

不要机械地把 threshold1~4 全部设为共享内存大小。CLI 默认值均为 655360，但它们不是四个同义的总内存上限，而且 ARCS/VenusA 的共享内存平台上限只有 393216。应从同平台同算子族的 auto_test 配置、工具默认值和真实内存预算推导候选，并以最终 memory plan 为准。-m 中的共享内存关键字必须写为 share-mem。

每次尝试保留：

• 完整标准输出和错误日志。
• 成功时生成的资源文件。
• 通过 --export_config 导出的有效配置。
• workspace/<model>/<model>_memory_report.txt。
• workspace/<model>/model.ignore/6_graph_layout_convert.onnx。
• workspace/<model>/model.ignore/7_graph_op_split.onnx。

只有打包成功且生成资源满足真实内存约束后，才能进入一致性验证。

3. 统计算子拆分

对比硬件拆分前后的计算图：

• 拆分前：6_graph_layout_convert.onnx。
• 拆分后：7_graph_op_split.onnx。

至少统计：

• 拆分前后的节点数。
• 算子类型数量变化。
• 新增的 Split、iqCat 和其他组合节点。
• 被 <name>_0、<name>_1 等编号副本替换的原始大算子。
• 每个原始算子的分片数。
• 总额外分片数，即所有 分片数 - 1 之和。
• 每个资源的公开输入输出；使用部署子图时额外输出资源 DAG 和跨资源 tensor 总字节数。

归一化副本名称时必须保守，并通过计算图连接关系和算子类型验证推断。不能仅凭名称以 _0 或 _1 结尾，就把原模型节点误判为拆分副本。如果无法精确分组，同时报告计算图结构变化和明确标记为“估算”的拆分数。

使用以下字典序目标选择最佳候选：

1. 在真实内存限制内打包成功。
2. 被拆分的原始算子数量最少。
3. 总额外分片数最少。
4. 拆分后节点增长最少。
5. 运行时共享内存、PSRAM 和资源文件更小。

不得用正确性或实际可部署性换取更低的拆分指标。

4. 先定位内存压力来源

读取 <model>_memory_report.txt，至少拆分记录以下项目：

• share-mem 峰值和真实 --ramsize 的余量。
• PSRAM 使用量和真实 --psramsize 的余量。
• workspace、runtime tensor、参数、DMA buffer 各自占用。
• 最大张量及其生命周期；边界输出通常会跨资源长期存在，切图后不能只看单段峰值而忽略应用侧同时驻留。
• 大算子在 6_graph_layout_convert.onnx 中的输入、权重、输出 shape，以及在 7_graph_op_split.onnx 中的实际分片方向和数量。

按现象选择机制：

5. 减少拆分的参数优化

仅调整与实际拆分算子相关的参数：

优化规则：

1. 修改参数前先分析 7_graph_op_split.onnx 和内存报告。
2. 每次只调整一个阈值类别，或一小组明确相关的节点存储位置。
3. 先使用有边界的粗粒度步进，再在最佳成功值和最近失败值之间二分搜索。
4. 每次成功后重新统计拆分，不能仅根据阈值变化推断结果改善。
5. 候选增加拆分、内存超限、序列化失败，或增加数据搬运却未改善拆分目标时，应放弃该候选。
6. 没有合法候选能继续改善、剩余拆分由硬件下限强制产生，或达到迭代预算时停止。

阈值的实际源码语义比 CLI 帮助更具体：

• threshold1：Conv 权重/kernel 分片候选；Venus 普通卷积有效上限通常被限制到 32768，继续提高往往无效。ARCS 普通卷积有 8192 下限；VenusA 普通 Conv 与 ConvTranspose 的限制方向并不完全相同。
• threshold2：Conv 输出分片候选；Venus/VenusA 常见路径有 65536 下限，ARCS 常见路径有 32768 下限。低于下限的配置不一定产生变化。
• threshold3：平台相关。Venus/ARCS 主要影响 Linear 右侧/权重矩阵限制，VenusA 主要影响左侧/输入矩阵限制；不同权重 dtype 还有固定硬限制。
• threshold4：单 tensor 自动放置阈值。payload 大于它时默认放 PSRAM，否则默认放共享内存；显式 -m 优先。它不是共享内存总容量。
• 文档将阈值描述为字节，但 threshold1~3 的若干实现按对齐后的元素数计算；对 int8 数值等同于字节，对其他 dtype 不应直接按字节推断。threshold4 实际按 payload 字节比较。

遇到源码分支不确定、阈值调整无效果或行为与文档不符时，必须读取当前版本 op_split.py，不能依赖通用表格。特别注意平台硬限制、最多拆分数等约束无法通过增大阈值绕过。

当前 auto_test 中经过 CI/runtime 使用的代表性候选如下。仅在平台、算子族、dtype 和 shape 接近时作为首轮搜索种子：

从这些配置推导候选时，先复制“参数关系”而不是数字。例如发现目标是 VenusA Conv 子图，应先尝试较小 threshold4、threshold2=65536 和定向 PSRAM 放置，再根据实际 split graph 与 memory report 调整；不能因另一个模型使用 threshold1=131072 就直接套用。

平台内核具有不可绕过的对齐、输入尺寸、权重块、拆分数和 workspace 限制。无限提高阈值不能突破硬件约束。此类拆分应记录为不可避免，而不是持续盲目调参。

建议搜索范围：

1. 使用文档或默认阈值建立基线。
2. 对实际相关的每个阈值，在其他参数固定时测试到源码平台分支允许且最终 memory plan 可承受的上界；该上界不一定等于共享内存容量。
3. 如果上限值成功且减少拆分，向下二分查找保持该拆分指标的最小阈值。
4. DMA 内存占用明显时测试一次 --dma_prefetch False。
5. 仅对内存报告确认的张量测试定向 -m 放置。
6. 默认控制在 8 到 20 个候选，除非用户要求穷举。

6. 设计部署子图

只有整图基线在真实限制内无法满足，或部署本身明确要求多资源时执行本节。

1. 从 ONNX 拓扑和内存报告选择边界。优先选择 fan-out 较低、tensor 较小、量化和 layout 明确、算子块之间的自然边界。
2. 避免切在大量并行特征之间。若必须切在分叉处，将所有后续仍需要的旁路 tensor 一并列入上游 --outputs。
3. 为每段明确列出 --inputs、--outputs；名称必须来自待切分阶段加载后的 graph entries。
4. 分别打包每段，并记录每段 memory plan、资源大小、内部算子拆分和公开 I/O。
5. 计算跨资源数据成本：每次传递字节数、同时驻留边界 tensor 峰值、是否需要 PSRAM、是否引入 layout copy。
6. 用资源 DAG 做端到端 runtime 验证，不能只对每段运行独立随机输入。下游输入必须使用上游真实输出。
7. 每段的一致性参考应是与该段边界一致的 ONNX 子图或固定中间 tensor；不能拿完整模型最终输出直接比较中间资源。

可借鉴的 auto_test 模式：

不要把 auto_test 中的数字当成平台通用最佳值。它们是具体 graph、shape、dtype 和部署边界的已验证实例。

7. 固化最佳资源

将最佳候选复制到 <result_dir>/best/：

• 打包资源。
• 有效 tpacker JSON 配置。
• 精确打包命令。
• 打包日志。
• 内存报告。
• 拆分前、后的 ONNX。
• 与基线对比的拆分指标。

清理打包工作区后重新执行一次最佳命令。确认退出状态、非空资源、有效配置和拆分指标一致。如果序列化是确定性的，优先比较资源校验和。

8. 验证 Linger 与 Thinker 一致性

使用原始量化 ONNX 和最佳资源：

tvalidator \
  -g <model.onnx> \
  -r <result_dir>/best/<model.bin> \
  -l <同平台且开启dump的libthinker.so> \
  [-i <input_0.npy> <input_1.npy> ...] \
  [--cfg <与打包相同的动态shape配置>] \
  --param_check ON \
  --runtime_check ON

如果没有可用动态库，只允许从 Thinker 仓库根目录让 tvalidator 自动构建。必须确认构建平台与 ONNX 一致，并开启结果 dump。优先显式传入 -l，避免静默重建或选错库。

一致性通过必须同时满足：

• Linger 参考推理成功。
• Thinker 加载并运行的确实是最佳资源。
• 存在可配对比较的 dump。
• tvalidator 明确输出 Consistency verification passed。

不能只根据进程退出码判断一致性通过，因为部分比较失败可能只打印日志而不返回非零状态。

如果首轮使用随机输入：

1. 立即保存 workspace/<model>/*_linger.npy。
2. 按 ONNX 输入顺序通过 -i 传入这些文件重新运行。
3. 以固定输入复测结果作为最终结论。

动态模型在时间和资源允许时，至少验证一个接近最小值、一个典型值和一个接近最大值的合法 shape，并保留所有失败用的固定输入。

多资源模型还必须增加一次端到端验证：按资源 DAG 顺序运行，直接把上游 Thinker 输出作为下游输入，并将最终结果与完整 Linger 模型比较。分段 tvalidator 全部通过但端到端失败时，优先检查边界 tensor 顺序、dtype、scale、layout、shape 和旁路依赖。

9. 故障诊断

按最早失败阶段分类：

• 前置检查：依赖、ONNX 有效性、不支持的平台/算子或动态配置格式错误。
• 打包：计算图优化、硬件适配、内存规划、序列化或资源写入失败。
• 构建/加载：仿真库构建、加载或平台不匹配。
• 运行时：模型初始化、内存分配、输入设置、shape 更新或算子执行失败。
• 一致性比较：首个不一致张量，或没有可比较的 dump。

不要让完整日志掩盖首个可处理错误。完整日志作为附件保存，报告中只引用最短的相关错误栈。

一致性比较失败时记录：

• 首个不一致张量，以及原始 ONNX 中对应的生产节点和算子类型。
• 张量 shape、数据类型，以及可用的量化属性或 scale。
• tvalidator 输出的首批不一致索引和两侧数值。
• 两个对应 dump 文件的路径。
• 更早的可比较张量是否一致。

默认不要收集所有 dump。通常只需要固定模型输入和首个不一致张量对；只有需要证明差异起点时，才增加紧邻的前一个一致张量对。

最小复现报告

只有打包或一致性验证无法成功完成时，才创建 <result_dir>/failure-report/report.md。报告应自包含但尽量精简：

# Thinker 打包/一致性验证故障

## 摘要
- 失败阶段：<前置检查|打包|构建/加载|运行时|一致性比较>
- 现象：<一句话>
- 首个可处理错误或不一致：<一句话>

## 环境
- 操作系统/架构：<值>
- Python：<值>
- linger：<值>
- pythinker：<值>
- onnx：<值>
- Thinker 提交：<值及工作区状态>
- 目标平台：<值>

## 输入
- ONNX：<报告内相对路径和校验和>
- 固定输入：<有序路径和校验和，或尚未进入该阶段>
- 动态配置：<精确值或无>

## 复现步骤
```bash
<涉及打包时的最小打包命令>
<涉及验证时的最小验证命令>
```

## 有效打包配置
- ramsize / psramsize：<字节数>
- dma_prefetch：<值>
- threshold1~4：<值>
- 节点存储位置：<值或无>
- 拆分指标：<值>

## 实际结果
<简短错误块，或首个不一致张量、shape、索引和数值>

## 预期结果
<在限制内打包成功，或一致性验证通过>

## 附件
<最小文件列表及用途>

根据失败阶段只附带必要文件：

除非已经证明必要，否则不要附带：

• 整个 workspace 目录。
• 所有中间 ONNX。
• 所有张量 dump。
• 构建目录或编译目标文件。
• 绝对路径、用户名、令牌、无关的私有文件或机器缓存。

如果模型或权重不能共享，不得声称报告可以独立复现。应明确说明限制，并提供模型校验和、计算图/算子摘要、失败节点元数据和精确命令，作为诊断报告。

最终回复

成功时报告：

• 最佳资源和配置路径。
• 目标平台及实际使用的内存上限。
• 基线与最终拆分指标。
• 修改的参数及原因。
• 资源大小和内存规划汇总。
• 精确验证命令及固定输入。
• 一致性结果和已测试的动态 shape 点。
• 剩余不可避免的拆分及已知硬件原因。

失败时首先说明失败阶段和首个可处理错误，然后给出报告目录及其中的最小附件。明确区分已验证事实和假设。