PR 提交说明

1. 影响面评估

接口变更（按需）： 无

备注：本 PR 仅涉及文档。文档中同步的 CLI 行为（attn_head 默认使用内置校准集、--calibration_dataset 变为可选）与配置字段（unary_analysis.metric_params）均由配套特性 PR 引入，文档侧无代码接口变更。

输出件变更（按需）： 无

备注：仅修正 head.pt 的用途描述（交付推理框架用于长序列 KV Cache 压缩），产物格式与路径未变。

非兼容变更（按需）： 无

SIG 评审结论（按需）： 无

2. 修改描述

修改背景（可选）： RA Compress（attn_head 范围分析）相关文档与当前实现存在多处不一致：校准集仍被描述为「必须显式指定 calib_dummy.jsonl」；head 选择比例（14% / 1%）被描述为「不通过 YAML 配置」；head.pt 的用途被描述为「用于 RA Compress 量化流程」，而实际是交付推理框架做长序列 KV Cache 压缩；unary_analysis 处理器文档未收录 ra_compress 指标与 metric_params；另有失效的相对链接。

关联issue
https://gitcode.com/Ascend/msmodelslim/issues/510

修改目的： 使 6 篇文档与实现保持一致，使用户能按文档正确完成 attention head 分析、head 选择比例调优与 head.pt 交付，并清理过期表述与失效链接。

修改内容：

• cli：api_reference/cli/msmodelslim_analyze.md —— 功能说明与退出码 0 说明补充 head.pt 交付推理框架用于长序列 KV Cache 压缩（附 MindIE 支持模型列表引用）；attn_head 示例移除 --calibration_dataset calib_dummy.jsonl；5.6 节标题与说明调整并新增 ratio 覆盖 YAML 示例；修正 ra_compress.yaml 模板链接层级（../../ → ../../../../）。
• core（配置参考）：api_reference/config/processor/unary_analysis.md —— metrics 取值新增 ra_compress；新增 metric_params 字段（induction_head_ratio 默认 0.14、echo_head_ratio 默认 0.01）及配置约束（仅 ra_compress 可用，未知键 / 越界值直接报错）；补充完整 YAML 示例。
• core（算法知识库）：knowledge_base/quantization_algorithms/README.md —— 新增「4. 注意力头分析算法」章节并顺延后续章节编号；将敏感层分析口径拆分为「量化敏感度（linear/layer/attn）」与「KV Cache 压缩头筛选（attn_head）」；attn_head 条目改为默认使用内置 ra_compress_dummy 校准集。
• core（术语）：ra_compress/term_ra_compress.md —— 校准数据表述统一为内置 ra_compress_dummy（1 个 BOS + 2500×4 = 10001 tokens）；删除过期条目（必须显式指定 calib_dummy.jsonl、ratio 不通过 YAML 配置、内部接口实现清单）；补充 ratio 覆盖方式与模板渲染链路说明；参考文献补充 arXiv 链接。
• core（使用指南）：ra_compress/usage_ra_compress.md —— 前置条件、输入与参数表、流程图、操作步骤同步为「默认内置校准集」；明确内置 10001 tokens 与自定义校准集「2500 的整数倍 + 1（≥ 10000 tokens）」的对齐要求；新增 ratio 覆盖示例、head.pt 交付说明及异常处置（得分为空、Q/K 投影层未命中、GQA 分组报错）。
• app（用户指南）：user_guide/usage_sensitive_attn_head_analysis.md —— 步骤 5、验收条件与异常处置同步校准集与 ratio 变更；术语统一为 induction / echo head。
• utils / 全量：清理 calib_dummy.jsonl 过期引用，统一术语与相对链接写法。

合入依赖： 文档所描述的代码行为由配套特性 PR feature/ra_compress-refine-v2 引入；其中 term_ra_compress.md 引用的 msmodelslim/infra/dataset_loader/builtin_datasets/ra_compress_dummy.py 在 master 上尚不存在，建议代码 PR 先行合入，或两者同期合入。

3. 功能验证

• 功能自验
• 本地自验用例截图（请勿包含个人信息；可附复现命令）

本 PR 为纯文档改动，无运行输出可截图；自验方式为静态检查与链接解析校验，结果如下。

复现步骤（可选）：

# 1) 静态检查（typos / end-of-file / markdown 等 hook 全部通过）
pre-commit run --files \
  docs/zh/api_reference/cli/msmodelslim_analyze.md \
  docs/zh/api_reference/config/processor/unary_analysis.md \
  docs/zh/knowledge_base/quantization_algorithms/README.md \
  docs/zh/knowledge_base/quantization_algorithms/ra_compress/term_ra_compress.md \
  docs/zh/knowledge_base/quantization_algorithms/ra_compress/usage_ra_compress.md \
  docs/zh/user_guide/usage_sensitive_attn_head_analysis.md

# 2) 文档内相对链接可解析性检查（唯一剩余项为上述待合入的 ra_compress_dummy.py）

4. 自检（请逐项确认，不适用标 N/A）

典型安全编码问题

• [N/A] 是否已校验外部数据
• [N/A] 是否未采集或打印敏感信息
• [N/A] 是否已正确设置文件权限
• [N/A] 是否充分考虑浮点运算溢出、除零等异常场景
• [N/A] 是否已对正则表达式做 ReDos 检查

以上均为纯文档改动，不涉及代码逻辑。

DT

• [N/A] 是否具备 UT 测试用例看护（纯文档改动，无需新增 UT）
• 是否需要添加冒烟：否