[RFC]: 精度、性能问题定位案例知识库结构

### 背景与目标描述. 规范精度、性能问题定位案例文档结构，便于用户阅读的同时，支持大模型、搜索引擎检索。 ### 建议的方案. ### 案例标题：`一个简洁明了的问题描述` * *作用：快速了解问题核心。* * *示例： “Transformer模型在推理时显存溢出（OOM）问题定位”* #### 1. 案例标签 *案例关键词，可从下面选择，不超过10个。* *示例：微调，内存泄露，算子缓存* * *1.1 模型类型：稠密，稀疏，LLM，VLM，多模态，NLP模型，视觉模型，语音模型* * *1.2 阶段：预训练，微调，验证/评估，推理/部署* * *1.3 精度问题：数据预处理，不收敛，过拟合/欠拟合，指标异常，Loss为NaN，预测结果偏差* * *1.4 性能问题：训练速度慢，推理延迟高，吞吐量低，GPU利用率低，CPU瓶颈，I/O瓶颈* * *1.5 内存问题：内存泄露，主存泄露，显存溢出* * *1.6 算子问题：FlashAttention，PageAttention，MatMul* * *1.7 硬件：#ascend910b, #ascend910c* * *1.8 分布式：分布式训练，张量并行，优化器并行，流水线并行，专家并行* #### 2. 问题现象一句话描述 * *用具体、可量化的语言描述“发生了什么”。* * *示例：模型在A100显卡上推理批量大小为8时，出现CUDA out of memory错误。* * *可关注的关键指标异常：* * 精度指标： 例如：测试集准确率从85%骤降至10%，loss值为NaN。 * 性能指标： 例如：GPU利用率 >95%，但吞吐量 <10 samples/sec， 推理P99延迟 >500ms。 * 资源指标： 例如：显存占用16GB/16GB，CPU内存占用90%。 #### **3. 问题定位与根因分析** *案例的精华，详细记录“如何找到问题”和“问题本质是什么”。* ##### 3.1 定位工具与方法： * profiling工具：*例如：PyTorch Profiler, Nsight Systems, Nsight Compute, TensorBoard, vTune。* * 日志与监控：*查看了哪些日志？监控了哪些系统指标？* * 简化复现法：*是否通过构造最小化数据集或简化模型来复现问题？* * 对比排查法：*是否与已知的正常版本进行对比？* ##### 3.2 定位步骤与过程： * *按步骤记录排查流水账，这能体现逻辑思维。* * *示例：* 1. *使用 `torch.cuda.memory_summary()` 发现大量内存被 `nn.Module` 的中间激活值占用。* 2. *使用 PyTorch Profiler 定位到 `torch.einsum` 操作是计算热点和显存消耗大户。* 3. *检查数据流，发现某个张量的维度意外地为 `[batch, seq_len, seq_len, hidden]` 而非预期的 `[batch, seq_len, hidden]`，导致注意力计算时产生巨大的中间矩阵。* ##### 3.3 根本原因： * *用一句话精炼总结。* * *示例： “数据预处理环节的一个bug，导致输入张量多了一个冗余的维度，在注意力计算时引发二次方的显存开销。”* #### 4. 解决方案 *记录“如何修复问题”。* ##### 4.1 具体措施： * *详细描述代码、配置或流程上的修改。* * *示例： “修复数据预处理脚本，在第XX行增加 `squeeze()` 操作，移除多余的维度。”* ##### 4.2 验证结果： * *修复后，第2部分提到的异常指标如何恢复正常。* * *示例： “修复后，相同批量大小下显存占用降至6GB，吞吐量提升至50 samples/sec，准确率恢复至85%。”* #### 5. 经验总结与预防措施 *将具体问题升华成通用经验，这是对知识库最重要的贡献。* ##### 5.1 经验教训： * *示例： “对于自定义的复杂张量操作，必须在模型前向传播的入口处添加张量形状的断言（assert）检查。”* ##### 5.2 最佳实践/检查清单： * *形成一个可复用的检查点。* * *示例：* * *【模型训练前】数据形状一致性检查。* * *【模型部署前】使用Profiler进行性能和显存分析。* * *【代码规范】避免在模型内部创建巨大的临时中间变量。* ### 涉及到的对外AP…