ascend-robot【同步】【非开发代码】代码从 develop 同步到 master

RFC：Q2 建模技术规划

1. 文档信息

状态：Approved
适用范围：Q2 研发规划、跨模块协作、交付对齐
目标读者：研发、架构、测试、产品化及相关协作方
关键词：推理建模、模型适配、Roofline、实测算子、PP、CP、寻优、精度治理、易用性

2. 背景与问题

msModeling 当前已经具备推理场景下的模型性能建模、算子耗时评估、服务化吞吐寻优等基础能力，可用于模型部署前的性能评估、参数搜索和方案对比。随着 Q2 重点模型和复杂推理特性的增加，现有能力需要从“单点模型/单点特性支持”升级为“体系化的推理建模能力建设”。

当前主要问题包括：

新模型适配成本较高 热门模型持续演进，模型结构、算子形态、量化方式、并行策略差异增多。当前基于已有模型注册和手工适配的方式，在新模型快速支持上仍存在效率瓶颈。
复杂推理特性支持不完整 长序列、PP 并行、CP 并行、Chunked Prefill、低时延优化等场景在实际部署中逐渐成为重点，但当前工具对这些特性的建模能力仍不完整，影响 text_generate、throughput_optimizer 等核心链路的准确性。
算子建模需要从理论估算走向理论与实测结合 Roofline 路线具备较好的泛化能力，但在特定硬件、特定融合算子、复杂算子实现上可能与真实性能存在偏差。Q2 需要引入实测算子数据，提升核心场景的建模精度和结果可信度。
易用性和结果解释能力仍需增强 工具在安装、模型接入、device 配置、case 构造、结果分析等环节仍依赖使用者经验。需要通过前端可视化、自然语言 skills、文档体系和结果曲线输出降低使用门槛。
精度治理和回归防护不足 建模结果需要稳定可验证。当前仍需要进一步建设精度 CI、典型 case 回归、profiling 自动比对、Roofline 与实测路线对比等机制，提升工程稳定性和结果可解释性。

3. Q2 总体目标

Q2 的核心目标是围绕推理建模能力、算子建模底座、部署寻优、易用性和精度治理进行体系化升级，使 msModeling 能够更高效地支持新模型、更准确地覆盖复杂推理场景，并更容易被用户理解和使用。

3.1 模型支持目标

支持 Q2 重点推理模型的 Roofline 建模和核心算子耗时评估。
提升新模型适配效率，降低无新结构特性的 LLM 模型接入成本。
建立模型适配标准流程，减少模型支持对个人经验的依赖。
探索基于实际执行图或模型前端抓取的模型接入方案，提升算子调用、shape、次数等信息的准确性。

候选模型范围包括但不限于：GLM 系列、Kimi 系列、Qwen 系列、MiniMax 系列、DeepSeek 系列，例如DeepSeek V4、GLM 5等。

3.2 推理特性目标

支持 PP 并行建模，补齐 stage 间 send/receive 通信和 bubble 影响。
支持 CP 并行建模，覆盖长上下文并行场景下的计算、通信与额外开销。
支持 Chunked Prefill 场景建模，提升长序列服务化建模准确性。
完善低时延场景建模能力，支撑不同部署策略下的性能对比。

3.3 算子建模目标

在 Roofline 路线基础上，引入实测算子性能数据建模能力。
支持工具内置算子性能数据读取、匹配和计算。
支持算子性能数据采集，形成可沉淀、可扩展、可复用的数据资产。
探索源码级或 DSL 路线，提升复杂算子和融合算子的建模泛化能力。

3.4 精度目标

建立典型模型、典型 case 的精度看护机制。
Roofline 路线输出精度报告，支持误差分析和趋势判断。
实测路线在核心模型、核心硬件、典型高吞吐/低时延场景下达到可接受精度目标。
支持建模结果与 profiling 数据自动比对，逐步形成可持续的精度治理流程。

3.5 易用性目标

支持前端可视化能力，降低参数配置和结果理解门槛。
支持安装、case 构造、device 配置等环节的 skills 化。
增强 throughput_optimizer 结果输出，支持曲线、对比和推荐配置展示。
完善模型支持列表、特性列表、精度报告、工具原理和版本更新文档。

5. 总体方案

5.1 架构分层

Q2 建议按以下分层推进能力建设：

模型输入层
  - HF Model
  - Built-in Model
  - 自定义 Python Model
  - vLLM / 执行图抓取方案
  - 配置化 Model Profile

模型适配与表达层
  - Model Profile 注册
  - model-doctor / verify / validate
  - shape / op / call count 捕获
  - 并行策略注入
  - 量化策略注入
  - 融合算子识别

建模执行层
  - Roofline 理论建模
  - 实测算子数据建模
  - 通信建模
  - PP / CP / Chunked Prefill 特性建模
  - 服务化调度建模

部署寻优层
  - throughput_optimizer
  - SLO 约束
  - 并发搜索
  - TP / DP / EP / PP / CP 策略搜索
  - 多硬件结果对比

验证与展示层
  - 精度 CI
  - profiling 自动比对
  - 结果曲线
  - 前端可视化
  - 文档与报告输出

5.2 工作主线

Q2 工作拆分为五条主线：

主线 A：新模型适配与适配效率提升 解决新模型接入成本高、适配流程不标准、模型前端不够准确的问题。
主线 B：推理特性建模增强 补齐 PP、CP、Chunked Prefill 等复杂推理特性，提升长序列和多并行策略场景下的建模能力。
主线 C：算子建模底座建设 建设实测算子接入、算子数据采集、DSL/源码级建模和融合算子自动化能力。
主线 D：易用性与结果分析增强 通过前端、skills、文档和结果曲线提升工具安装、使用、分析效率。
主线 E：精度治理与工程稳定性建设 建设精度 CI、profiling 自动比对、Roofline 与实测结果比对、精度分析流程等能力。

6. 重点工作规划

6.1 主线 A：新模型适配与适配效率提升

6.1.1 目标

支持 Q2 重点模型建模，并显著降低新模型适配成本。对于无新结构特性的 LLM 模型，目标是尽可能通过自动化流程完成模型注册、适配校验和基础建模。

6.1.2 工作内容

任务 A1：重点模型适配

支持 Q2 重点模型完成建模能力接入，包括模型结构解析、关键算子识别、算子耗时评估、融合算子适配、并行/量化配置支持等。

功能要求：

支持指定模型成功输出建模结果。
支持关键算子耗时评估。
能够在 breakdown 中展示关键算子或融合算子的耗时信息。
支持目标硬件、量化方式、TP/DP/EP 等常见切分策略。
支持算子融合场景下的耗时建模。

验收标准：

指定模型可以通过工具入口完成建模并输出结果。
关键算子在指定 case 中可被识别并进入耗时 breakdown。
典型 prefill、decode case 与实测 profiling 进行对比，误差达到对应模型的验收阈值。
模型适配过程沉淀为可复用的 Model Profile 或适配说明。

任务 A2：Built-in Model 方案优化

优化 built-in model 方案，降低模型接入复杂度，优先支持“注册 Profile + 可选 patch”的接入模式。

功能要求：

增加 model-doctor、verify、profile normalize/validate 等能力。
支持构建阶段 fail-fast，提前暴露未适配项和配置错误。
对常见模型系列形成标准适配路径和测试基线。
输出可执行的修复建议，减少使用者排查成本。

验收标准：

model-doctor、verify、profile normalize/validate 等能力可通过 CLI 独立运行。
在典型 LLM、MoE、VL 场景中完成验证。
自动生成或校验的 Model Profile 与人工基线相比误差在可接受范围内。
对失败样例能够明确输出失败原因和下一步建议。

任务 A3：LLM 模型适配 Skills

基于 built-in model 方案建设 LLM 模型适配 skills，使无新结构特性的模型可以通过自动化流程完成候选适配。

功能要求：

给定一个未接入模型，skill 能自动调用 doctor/verify 流程。
自动产出候选 Model Profile 或模型注册代码。
对成功样例输出可落库结果。
对失败样例输出明确失败原因和下一步建议。

验收标准：

典型 LLM、MoE、VL 模型 case 能够跑通自动适配流程。
成功样例产出的注册结果可直接用于基础建模。
失败样例的错误定位和修复建议具备可执行性。
自动化测试覆盖典型模型接入流程。

任务 A4：执行图抓取式模型前端探索

探索基于实际执行过程的模型前端接入方案，通过运行时抓取算子名、shape、调用次数等信息，获得更准确的模型前端表达。

功能要求：

支持从实际执行路径中获取算子调用信息。
支持导出可用于建模的 op、shape、call count 等结构化数据。
评估依赖硬件和不依赖硬件两类方案的可行性。
与现有 HF/Built-in Model 前端形成互补。

验收标准：

完成技术方案评估。
至少在一个典型模型上验证抓取链路可行性。
输出与现有模型前端的差异分析。
明确后续是否纳入正式建模入口。

6.2 主线 B：推理特性建模增强

6.2.1 目标

补齐 PP、CP、Chunked Prefill 等复杂推理特性，使 text_generate 和 throughput_optimizer 能够覆盖更多真实部署场景。

6.2.2 工作内容

任务 B1：PP 并行适配

PP 并行是典型模型切分策略，适用于模型跨多组设备部署的场景。Q2 需要支持 PP 切分下的单次 forward 建模和服务化吞吐建模。

text_generate 功能要求：

支持配置 PP 参数，默认 PP=1。
当 PP=1 时，对原有评估结果无影响。
当 PP>1 时，支持自动平均切分 layer，或由用户指定 layer 切分策略。
增加 PP stage 间 send/receive 通信耗时。
输出中包含 send、receive 耗时信息。

throughput_optimizer 功能要求：

支持 PP 切分下的服务化性能建模。
支持 stage 间 send/receive 通信耗时。
考虑不同 PP stage 耗时不均衡引入的 pipeline bubble。
输出中包含 send、receive、bubble 等关键信息。

验收标准：

text_generate 支持 PP 配置，并能输出 PP 场景下的单 forward 建模结果。
throughput_optimizer 支持 PP 配置，并能输出 PP 场景下的吞吐、时延和 bubble 信息。
PP=1 场景与原有行为保持一致。
PP>1 场景可通过典型 case 完成结果校验。

任务 B2：CP 并行适配

CP 并行面向长上下文场景，是支持超长序列模型部署的重要并行策略。Q2 需要支持 CP 配置识别、切分逻辑扩展和计算/通信建模。

功能要求：

text_generate 支持 CP 配置并输出建模结果。
throughput_optimizer 支持 CP 配置并输出服务化建模结果。
支持长上下文场景下 CP 引入的计算、通信和额外开销建模。
CP 配置不影响非 CP 场景的已有行为。

验收标准：

text_generate 和 throughput_optimizer 能够识别并处理 CP 配置。
长上下文 case 在 CP 场景下可以正常运行并输出结果。
结果中能够体现 CP 场景下的关键开销项。

任务 B3：Chunked Prefill 适配

Chunked Prefill 是长序列服务化中的重要调度能力，可影响 TTFT、吞吐和显存使用。Q2 需要在服务化建模中补齐该能力。

功能要求：

支持将长 prompt 按配置切分为多个 prefill chunk。
支持 chunked prefill 对 TTFT、TPOT、吞吐和调度行为的影响建模。
与 prefix cache、并发、batch 参数等服务化参数协同工作。
在 throughput_optimizer 中支持相关参数搜索或结果分析。

验收标准：

典型长序列 case 可开启 chunked prefill 并输出建模结果。
结果中能够体现 chunk 大小、并发、缓存命中等因素对性能的影响。
与非 chunked prefill 场景相比，输出趋势符合预期。

6.3 主线 C：算子建模底座建设

6.3.1 目标

构建理论建模与实测建模结合的算子建模底座。Roofline 路线用于提供泛化能力和理论上界分析，实测路线用于提升目标硬件和核心场景下的预测精度，并反向指导 Roofline 误差分析。

6.3.2 工作内容

任务 C1：工具内置算子性能数据建模能力

新增基于内置算子性能数据的建模能力，使工具可以在特定硬件、特定算子、特定 shape 下直接读取实测性能数据进行耗时估算。

功能要求：

支持读取结构化算子性能数据。
支持根据算子类型、shape、dtype、硬件、软件版本等信息匹配实测数据。
支持在建模流程中选择 Roofline 路线或实测算子路线。
支持实测数据缺失时 fallback 到 Roofline 或插值/近似策略。

验收标准：

在典型模型和目标硬件上完成 text_generate 实测路线建模。
高吞吐、低时延典型场景下，核心指标精度达到 Q2 设定目标。
工具输出中能够区分 Roofline 估算结果和实测数据结果。
数据匹配失败时有明确提示和 fallback 行为。

任务 C2：算子性能数据采集能力

提供工具内置的算子性能采集能力，支持用户对指定算子开展实测采集，生成可用于建模的结构化数据。

功能要求：

支持指定算子、shape、dtype、硬件配置进行采集。
支持生成统一格式的算子性能数据。
支持数据校验、版本标记和可追溯管理。
支持后续持续补充和复用算子性能数据。

验收标准：

可对指定算子完成采集并生成结构化数据。
采集数据可被建模流程读取和使用。
数据格式满足后续扩展和版本管理要求。

任务 C3：源码级 / DSL 路线建模增强

探索基于源码级或 DSL 表达的算子建模增强能力，提升复杂算子、融合算子的泛化建模能力。

功能要求：

支持对部分算子进行源码级或 DSL 级表达分析。
支持从更细粒度表达中推导计算量、访存量或工程可达性能特征。
与 Roofline 路线结合，形成更强的算子建模能力。

验收标准：

完成方案调研和原型验证。
至少选取一个典型算子完成建模路径验证。
输出与现有 Roofline 方式的对比分析。

任务 C4：融合算子接入效率提升

对于结构不复杂的融合算子，减少手写融合 pass 的成本，探索通过定义融合范围自动完成融合识别和建模。

功能要求：

支持定义融合范围。
支持自动识别可融合片段。
支持生成融合后算子耗时估算。
支持在 breakdown 中体现融合算子耗时。

验收标准：

至少在一个典型融合算子 case 中验证自动融合流程。
与手写融合 pass 的结果进行对比。
明确适用边界和不适用场景。

6.4 主线 D：易用性与结果分析增强

6.4.1 目标

降低 msModeling 的安装、使用、配置和结果分析门槛，使用户能够更快完成建模 case 构造、更直观理解建模结果，并能基于输出做部署决策。

6.4.2 工作内容

任务 D1：前端可视化能力

提供本地网页形式的可视化能力，支持性能建模类参数配置、case 运行和结果展示。

功能要求：

支持本地网页打开。
支持主要性能建模参数配置。
支持运行典型 text_generate 和 throughput_optimizer case。
支持展示吞吐、TTFT、TPOT、并发、并行配置、算子 breakdown 等结果。

验收标准：

前端界面原生支持主要性能建模参数。
典型 case 可通过页面配置并运行。
结果展示与 CLI 输出保持一致。

任务 D2：公共入口与云端运行能力探索

探索在公共平台上提供可访问入口，支持云端仿真运行和并发使用。

功能要求：

支持公共入口访问。
支持云端仿真计算。
支持并发使用。
支持基于数据库自动匹配历史 case 或已有结果。

验收标准：

公共入口可访问并完成基础 case 运行。
支持并发使用的基础验证。
支持根据查询 case 匹配已有结果或数据库记录。

任务 D3：建模结果分析能力增强

增强 throughput_optimizer 输出，支持并发与 TPS 曲线、TTFT/TPOT 曲线、多硬件对比和最优配置输出。

功能要求：

支持不同并发下 TPS 曲线输出。
支持 TTFT/TPOT 与吞吐之间关系展示。
支持多个硬件同时输入并进行结果对比。
输出不同硬件最优性能配置，包括 TPS、TTFT、TPOT、并发、并行配置等。

验收标准：

throughput_optimizer 支持寻优曲线展示。
支持多硬件同时输入。
支持输出各硬件最优配置对比。
输出结果具备可解释性，能支撑部署策略判断。

任务 D4：安装与使用 Skills

通过 skills 提升安装、case 构造、device 配置的易用性。

功能要求：

支持通过口令或自然语言触发工具环境安装。
支持自然语言描述仿真 case，并自动补全必要参数。
支持交互式确认仿真条件后运行工具脚本。
支持用户通过自然语言描述硬件关键参数，自动生成 device 配置代码。

验收标准：

新环境下调用 skills 自动安装依赖后，可直接运行工具案例脚本。
用户自然语言描述仿真 case 后，skills 能补全必要信息并成功运行对应脚本。
skills 能引导用户填写硬件拓扑、静态开销、算力、访存带宽等关键参数，并生成可调用 device 配置。

任务 D5：文档完善

完善工具文档体系，提升用户对模型支持范围、建模原理、精度表现和版本变化的认知。

功能要求：

新增模型支持列表。
新增模型特性列表。
新增典型 case 精度报告。
新增工具基本原理介绍。
新增近期 update 列表。

验收标准：

文档随版本更新。
用户可以通过文档明确当前支持模型、特性、典型精度表现和使用入口。
文档覆盖安装、运行、结果解读和常见问题。

6.5 主线 E：精度治理与工程稳定性建设

6.5.1 目标

通过精度验证、自动化比对和回归防护，提升建模结果的准确性、稳定性和可解释性。

6.5.2 工作内容

任务 E1：精度 CI 搭建

对主流模型和典型 case 建立每日冒烟和门禁看护，降低代码变更引入精度回退的风险。

功能要求：

建设典型 case 精度防护。
对关键模型、关键场景、关键指标进行自动化回归。
重构 UT 用例，降低执行耗时。
将精度异常及时暴露到开发流程中。

验收标准：

典型 case 纳入精度门禁。
主流模型具备每日冒烟看护能力。
UT 执行耗时相比当前显著下降。
精度异常可以定位到模型、算子或配置维度。

任务 E2：精度分析流程 / Skill

沉淀精度分析方法论和标准流程，降低精度问题排查门槛。

功能要求：

梳理精度问题分析流程。
形成可复用的分析 skill 初版。

验收标准：

输出精度分析流程文档。
在典型误差 case 中验证流程有效性。
skill 初版可辅助完成基础误差归因。

7. 优先级建议

7.1 P0：Q2 核心交付

P0 任务需要优先保障，直接影响 Q2 主目标是否达成。

重点模型适配。
Built-in Model 方案优化。
LLM 模型适配 Skills。
实测算子性能数据建模能力。
算子性能数据采集能力。
前端可视化基础能力。
throughput_optimizer 结果分析增强。
安装与使用 Skills。
精度 CI 搭建。
PP 并行适配。
CP 并行适配。
Chunked Prefill 适配。
文档体系完善。

7.2 P1：重要能力增强

P1 任务对复杂场景覆盖和后续演进重要，建议根据人力情况尽量纳入 Q2。

训练场景建模
基于profiling数据的建模
执行图抓取式模型前端探索。
精度分析流程 / Skill。
Roofline 与实测路线自动比对。
源码级 / DSL 路线建模增强。
公共入口与云端运行能力探索

7.3 P2：探索与预研

P2 任务以方案调研、原型验证和技术储备为主。

融合算子自动化接入。
建模结果与 profiling 自动比对。

9. 统一验收标准

Q2 各任务除各自验收标准外，还应满足以下统一标准。

9.1 工程验收

新增能力可通过 CLI 或明确入口调用。
配置项具备默认值，默认行为不破坏已有使用方式。
关键流程具备自动化测试或典型 case 验证。
失败场景具备明确错误信息和排查建议。
输出结果格式稳定，可被前端、报告或后续工具消费。

9.2 建模验收

能够输出核心指标，包括 forward latency、TTFT、TPOT、throughput、算子 breakdown 等。
对关键并行和调度特性，能够体现新增计算、通信、等待或调度开销。
对核心 case，能够与 profiling 或实测结果进行对比。
误差较大时，可以定位到模型、算子、通信、调度或配置维度。

9.3 精度验收

典型模型、典型硬件、典型输入输出条件下具备精度报告。
核心场景趋势判断与实测结果保持一致。
实测路线在核心 case 上达到 Q2 设定精度目标。
精度 CI 能够发现主要回退问题。

9.4 易用性验收

用户可以通过文档完成安装、运行和结果解读。
典型 case 支持一键或低成本运行。
前端或结果曲线能够帮助用户理解部署参数对性能的影响。
skills 能够覆盖安装、case 构造、device 配置等高频操作。

10. 附录：任务汇总

主线	任务	优先级	主要交付
新模型适配	重点模型适配	P0	模型建模能力、Model Profile、精度报告
新模型适配	Built-in Model 方案优化	P0	doctor / verify / validate、适配指导
新模型适配	LLM 模型适配 Skills	P0	自动适配流程、候选注册代码
新模型适配	执行图抓取式模型前端探索	P1	技术方案、原型验证、差异分析
推理特性	PP 并行适配	P1	text_generate / throughput_optimizer PP 支持
推理特性	CP 并行适配	P1	长上下文 CP 建模能力
推理特性	Chunked Prefill 适配	P1	长序列服务化建模增强
算子建模	实测算子数据建模	P0	内置实测数据读取与建模
算子建模	算子性能数据采集	P0	采集工具、结构化数据
算子建模	源码级 / DSL 路线增强	P2	原型验证、方案对比
算子建模	融合算子接入效率提升	P2	自动融合原型、适用边界
易用性	前端可视化能力	P1	本地页面、参数配置、结果展示
易用性	结果分析能力增强	P1	曲线输出、多硬件对比、最优配置展示
易用性	安装与使用 Skills	P0	安装、case 构造、device 配置 skills
易用性	文档完善	P1	模型列表、特性列表、精度报告、update 列表
精度治理	精度 CI 搭建	P0	精度门禁、每日冒烟、UT 优化
精度治理	精度分析流程 / Skill	P1	方法论、流程文档、skill 初版