跳到主要内容

前端仿真洞察工作台设计规格

字段值
版本v0.1.0
状态Accepted
日期2026-06-11
作者xiang.li
前置G5通信评估观测与结果存储设计规格、2026-06-11 前端功能脑爆

变更历史​

版本日期变更
v0.1.02026-06-11初版草稿

概述​

本 spec 冻结前端的产品定位与三波功能路线：前端从「配置提交 + 结果表格」升级为「仿真洞察工作台」，以可视化兑现 G5 指令级事件驱动仿真产出的微观数据。同时冻结两项横切技术决策：trace 数据协议（Arrow IPC 为主格式）与前后端实时通道（统一 WebSocket 消息信封）。

背景​

后端定位已收敛到 G5 仿真建模，G5 产出事件级微观数据（链路占用、排队、指令执行），但前端只消费汇总指标与 op 级 Gantt，微观数据的分析价值没有兑现。具体落差：

  • G5 微观数据无出口：Rust 端 TraceCollector 已记录 6 类事件并可导出 Parquet，但前端无任何事件级视图。
  • 任务执行黑盒：G5 分钟级仿真，WebSocket 仅推送任务级 progress 浮点值，无已仿真时间、事件数等过程信息。
  • 方案对比靠人肉：评估平台的核心用途是比较部署方案，前端只能开多个标签页逐项对照。
  • 横向决策无主：trace 传输格式、实时通道协议等横切设计散落在各功能实现里，无统一契约。

业界仿真器（ASTRA-sim、SimAI）以 CLI 与论文图表为主要交付形态，trace 级交互式可视化是本平台的差异化方向。

名词定义​

评估路径

  • Math 路径：代数性能模型，秒级出结果，用于设计空间粗筛。
  • G5 路径：Rust 指令级事件驱动仿真，分钟级，产出事件级微观数据，用于瓶颈分析。

数据形态

  • 汇总指标：任务完成后的标量结果（TTFT/TPOT/MFU/成本等）。
  • op 级 Gantt：以算子为粒度的时间区间集合，当前前端 Gantt 图的数据源。
  • 事件级 trace：仿真过程的事件记录（时间戳 + 事件类别 + 资源），粒度细于 op，量级可达百万条。
  • Arrow IPC：Apache Arrow 的列式二进制序列化格式，支持 RecordBatch 分块流式读取，浏览器端由 Arrow JS 解析。

功能路线

  • Wave：功能交付波次。Wave 1 体验止血、Wave 2 G5 价值兑现、Wave 3 工作流闭环。
  • 关键路径：端到端时延的决定性事件依赖链，缩短链上事件才能缩短总时延。
  • Pareto 前沿：多目标下不被任何其它方案全面支配的方案集合。

目标与非目标​

目标​

  1. 冻结前端产品定位：仿真洞察工作台，功能取舍以「是否放大 G5 微观数据的分析价值」为第一判据。
  2. 冻结三波功能路线及波内顺序，作为后续各功能 plan 的依据。
  3. 冻结 trace 数据协议：G5 事件级数据以 Arrow IPC 为主格式传输至前端。
  4. 冻结实时通道契约：任务进度、过程日志统一走单一 WebSocket 消息信封。
  5. 给出 Wave 1 四个功能的验收口径（不为其单独写 spec）。

非目标​

  • 不定义各功能的实现方案：组件结构、文件改动属于各功能的 plan。
  • 不冻结 Wave 2/3 功能的详细设计：event-trace-timeline、bottleneck-attribution 等到位前需各自的设计决策，届时按需写独立 spec，本 spec 只锁路线与数据协议。
  • 不做前端路由架构重构：全挂载 viewMode 模式保留，重构触发条件见局限与后续工作节。
  • 不改 G5 引擎建模语义：本 spec 只约定 G5 已有观测数据的出口形态，不新增仿真行为。
  • 不覆盖拓扑生成与编辑：归拓扑生成器设计规格。

用例说明​

用例 1：跟踪一次 G5 仿真（Wave 1）。用户提交 G5 评估任务，任务面板实时显示已仿真时间、已处理事件数与预计剩余时间；任务异常时用户查看过程日志定位原因，无需到后端终端看输出。

用例 2：判断优化方向（Wave 1）。用户打开某任务的 Gantt 图，关键路径上的 op 被高亮；用户点击关键路径段，看到「该段缩短 1ms 可使端到端缩短 X ms」的敏感度提示，据此决定优化算子还是优化通信。

用例 3：比较候选方案（Wave 1）。用户在结果页勾选 2-4 个任务进入对比视图：KPI 以差值/百分比并排呈现，Gantt 按相同时间尺度对齐，用户据此回答「方案 B 比 A 快在哪一段」。

用例 4：扫参选方案（Wave 1）。扫参实验完成后，用户打开 Pareto 前沿散点图（横轴成本、纵轴性能指标），圈选前沿上的方案跳转对比视图。

用例 5：钻取微观瓶颈（Wave 2）。用户对某 G5 任务打开事件时间线，从 op 级下钻到链路传输与排队事件，缩放定位拥塞时段；切换到 3D 拓扑回放，拖动时间条观察链路热力随仿真时间的演化。

用例 6：两级评估流水（Wave 3）。用户对设计空间先跑 Math 粗筛，在结果中圈选 top-k 候选一键提交 G5 精仿，平台跟踪两级任务的派生关系。

详细设计​

产品定位与功能判据​

前端是 G5 仿真的洞察界面，不是通用 BI 看板。新功能立项时按以下判据排序取舍：

  1. 是否让 G5 独有的微观数据（事件、链路、队列）变得可分析——最高优先。
  2. 是否缩短「提交 → 结果 → 结论」的分析闭环。
  3. 是否可由既有数据直接驱动（不需要后端新增建模语义）。

三波功能路线​

波次主题功能（按依赖顺序）前置依赖
Wave 1体验止血live-progress-stream → critical-path-highlight → side-by-side-compare → pareto-frontier-view无（复用既有数据）
Wave 2G5 价值兑现trace 数据协议落地 → event-trace-timeline → link-utilization-replayWebSocket 信封（Wave 1 落地）
Wave 3工作流闭环math-prescreen-pipeline → bottleneck-attributionWave 2 trace 协议

波内顺序是依赖顺序，不是排期；跨波不并行启动（Wave 2 开工以 Wave 1 验收为前提）。脑爆中 deferred 的候选（拓扑画布编辑器、trace SQL 查询等）不在路线内，重启需修订本 spec 或另立 spec。

trace 数据协议​

决策：G5 事件级数据以 Arrow IPC 为主格式，从后端传输至前端；Perfetto/Chrome JSON 作为可选导出目标，不作为前端渲染输入。

设计原理：

  • 列式匹配渲染访问模式：时间线渲染按列取数（时间戳列、资源列），Arrow 列式内存零解析开销；JSON 百万级事件解析耗时秒级且内存翻倍。
  • 分块匹配流式加载：RecordBatch 分块允许前端按视口窗口懒加载，避免整包传输。
  • 写端零摩擦：G5 为 Rust 引擎，arrow crate 原生支持；既有 TraceCollector → Parquet 链路与 Arrow 同生态。
  • 演化空间：Arrow schema 自带列元数据，新增事件属性列不破坏旧读取方。

协议分层契约：

层契约
事件模型一条事件 = (时间区间或时间点, 事件类别, 资源标识, 类别相关属性)。事件类别沿用 G5 观测框架既有分类（链路占用/空闲、未完成事务变化、线程阻塞/解除、跳到达），新增类别走 schema 演化
序列化Arrow IPC stream format，按 RecordBatch 分块；每块自描述 schema
传输HTTP 按块拉取（前端指定时间窗口与资源过滤），不经 WebSocket 传 trace 本体
存储服务端以任务为单位持久化 trace 文件（沿用 G5 观测框架的 Parquet 落盘，与本协议同属 Arrow 生态），按块拉取时由服务端转为 Arrow IPC stream 下发；汇总指标仍走既有 DB 路径

trace 采集默认关闭，由任务提交时显式开启（事件级 trace 量级大，不应成为每次评估的隐性成本）。

实时通道契约​

决策：任务进度与过程日志统一走单一 WebSocket 连接，消息采用类型化信封。

消息信封语义：每条消息含消息类型、任务标识、载荷三要素。本 spec 冻结两类消息语义：

消息类型载荷语义
任务进度任务状态 + 完成度 + 过程计量（G5 任务：已仿真时间、已处理事件数、事件处理速率；搜索任务：已评估方案数/可行数）
过程日志日志级别 + 时间戳 + 文本行，支持按任务订阅

约束：

  • 推送频率服务端节流，约束为：任务状态或过程计量发生变化后 1s 内至少推送一次；客户端不假设固定频率。节流参数本身归实现 plan。
  • 结果本体（汇总指标、Gantt、trace）不走 WebSocket，完成通知后由 HTTP 拉取。
  • 新增消息类型须向信封注册类型名，禁止复用既有类型塞异构载荷。

Wave 1 功能验收口径​

功能验收口径
live-progress-streamG5 任务运行期间，前端每秒级刷新已仿真时间/事件数/预计剩余；任务面板可打开实时日志流
critical-path-highlightGantt 图可一键高亮关键路径；点击关键路径段显示该段对端到端时延的敏感度数值；关键路径覆盖时长 = 端到端时长（链不断裂）
side-by-side-compare支持 2-4 任务并排：KPI 差值/百分比、Gantt 同尺度时间轴对齐；进入对比的操作不超过 2 步（勾选 → 对比）
pareto-frontier-view扫参实验结果可渲染成本-性能散点图并自动标出 Pareto 前沿；前沿点可多选跳转对比视图

关键路径的计算归属：op 级关键路径由后端基于既有 step 依赖计算并随结果下发，前端只做渲染。敏感度 first-cut 口径为「段时长占关键路径总时长的比例」近似，并在界面标注为估计值；基于依赖图重计算的精确敏感度列入局限与后续工作节。

备选方案​

决策点被否方案否决理由
trace 格式Perfetto protobuf 作为前端渲染输入Perfetto UI 无法作为组件嵌入自有 React 应用（官方仅支持 iframe + postMessage 旁路），两套 UI 并存割裂分析流；WASM trace_processor 受内存上限约束，多 GB 需本地原生进程，部署复杂
trace 格式Chakra execution trace定位是 workload 描述（仿真输入），非仿真结果 trace，无时间线可视化生态；其价值在未来做业界 workload 导入器，与本决策正交
trace 格式自定义 JSON 分块百万级事件 JSON 解析耗时秒级、内存翻倍；schema 演化靠约定无元数据保障
路线粒度每个 Wave 各写一份 specWave 1 均为局部增量撑不起 spec；trace 协议横跨 Wave 2/3，拆开导致互相引用
实时通道进度走 WebSocket、日志另开 SSE两套连接生命周期管理重复；信封模型下单连接多类型已覆盖需求

完整业界调研对比见附录 A。

非功能性需求​

性能

  • 事件时间线在 10^6 条事件量级下可交互（缩放/平移帧率不低于 30fps），通过视口懒加载与 LOD 聚合达成，不要求全量事件常驻内存。
  • trace 传输按块拉取，单块解析不阻塞主线程渲染。

兼容性

  • 既有汇总指标、Gantt、实验管理的 API 契约不变；trace 协议是增量出口，不替代既有结果路径。
  • trace 采集关闭时，G5 仿真行为与性能与现状一致。

安全性 / 隐私：N/A（内网自用工具）。

局限与后续工作​

  • frontend-route-split 未决：全挂载 viewMode 模式在 Wave 2 新增 trace 视图后可能出现内存压力，届时度量决定是否重构为真路由 + 状态持久化，不在本 spec 预判。
  • Wave 2/3 功能需后续独立 spec：event-trace-timeline 的交互模型、bottleneck-attribution 的归因算法（含 Rust/Python 分工）各需独立设计决策。
  • Math 与 G5 差分解释依赖后端对齐：math-g5-diff-explain 等候选以 G5 守恒断言等后端工作为前提，未排入路线。
  • 关键路径敏感度为近似值：first-cut 用段时长占比近似，忽略缩短后关键路径切换的二阶效应；基于依赖图重计算的精确敏感度待后端依赖图分析能力到位后升级。
  • trace 量级上限未标定：百万级事件的端到端链路（采集 → 落盘 → 传输 → 渲染）需在 Wave 2 落地时用真实任务标定，超限时的降采样策略届时补充。

验收标准​

  1. 定位判据生效：Wave 1 之后的任何前端功能立项材料（plan/issue）显式回答本 spec 的三条功能判据。
  2. Wave 1 验收：四个功能各自满足「Wave 1 功能验收口径」表，全部验收后方可启动 Wave 2。
  3. 路线顺序生效：各 Wave 功能的 plan 显式引用本 spec 的波次表；跨波并行启动视为不合规。
  4. trace 协议合规：Wave 2 的 trace 出口实现满足协议分层契约表的四层语义；用 Arrow JS 读取服务端 trace 文件可还原全部事件字段。
  5. 实时通道合规：所有新增实时推送走统一 WebSocket 信封；代码审查中发现绕过信封的旁路推送视为不合规。
  6. 性能达标：10^6 事件 trace 在前端时间线缩放/平移帧率 ≥ 30fps（以浏览器 performance 面板录制为准）。

附录 A：业界调研​

trace 格式与可视化方案对比​

维度PerfettoChakra ETArrow IPC（选定）
定位系统级 trace 采集 + 分析平台ML workload 标准描述格式通用列式序列化格式
浏览器渲染百万级事件UI 支持多 GB，但 WASM trace_processor 受内存上限，多 GB 需本地原生进程无可视化生态Arrow JS 零拷贝列式取数；ECharts 5 增量渲染宣称百万点实时
嵌入自有 React 应用不支持组件化嵌入，仅 iframe + postMessage（官方 issue #14/#2266 长期未支持）N/A原生（数据层格式，UI 自研）
写端（Rust）成本protobuf 编码，schema 庞大protobuf，面向 workload 图arrow crate 原生支持
schema 演化TracePacket 扩展字段MLCommons 治理列元数据自描述，加列兼容

来源：

仿真器交付形态对标​

工具交付形态借鉴点
ASTRA-sim 2.0CLI + 论文图表，Chakra workload 输入瓶颈系统性探索方法论；无交互式可视化 → 差异化空间
SimAI（阿里）CLI，框架/集合通信/网络全链路建模端到端归因思路
Perfetto浏览器 trace 工作台时间线交互范式（缩放/钻取/track 分组）是 event-trace-timeline 的交互参照

来源：https://astra-sim.github.io/、https://github.com/aliyun/SimAI、https://perfetto.dev/

附录 B：实现说明​

实验管理 API 契约的修正（2026-06-12）​

正文「集成点」中"既有汇总指标、Gantt、实验管理的 API 契约不变"的"实验管理"部分不再成立：实验结果读取契约（分页行 / 字段投影 / 单行全量三形态）由实验结果展示数据契约设计规格定义并取代。本 spec 其余内容（trace 协议、WebSocket 信封、Wave 路线）不受影响。

Wave 1 执行顺序调整（2026-06-12）​

正文「三波功能路线」把 critical-path-highlight 列为 Wave 1 第二项，实现探索发现其前提不成立：当前 convert_to_gantt_chart 把所有 step 串行堆叠（单资源行、无并行），makespan = 各 step 时长之和，关键路径退化为全部任务，高亮无信息量。真实并行调度时间线仅存在于 G5 SimRecords（每 engine 真实 start/end），未进入 Gantt。

决策：critical-path-highlight 依赖「G5 真实并行调度 Gantt」这一 Wave 1 范围外的前提，故延后；Wave 1 此轮先做数据就绪的 side-by-side-compare 与 pareto-frontier-view。critical-path-highlight 重新定位为依赖真实调度 Gantt（与 Wave 2 per-chip-occupancy 同源）就绪后再做。本调整不改变正文波次的依赖语义，仅修正一处被漏看的跨波依赖。

pareto-frontier-view（Wave 1 功能 3，2026-06-12 完成）​

  • 纯前端。getExperimentMetrics(experimentId) 取实验全部 task，过滤出 cost + tps 两维齐全的完成任务为散点。
  • Pareto 前沿：成本越小越优、性能越大越优，非被支配点高亮 + 虚线连线，被支配点淡色。
  • 框选跳转：ECharts brush（需注册 BrushComponent/ToolboxComponent）框选 ≥2 点 → 复用 enterComparison 跳对比；>4 点 toast 提示并取前 4。
  • 入口：实验详情任务列表卡片头部「Pareto 前沿」按钮，局部状态展开（避开 ExperimentDetailView 受控 activeTab 与预存 WIP 分支）。
  • 已知限制：computeParetoFrontier 单测 vitest 格式未接入 CI（逻辑经转译运行验证）。

side-by-side-compare（Wave 1 功能 2，2026-06-12 完成）​

  • 纯前端，复用既有多标签加载（AnalysisTabsContext）、GanttChart、TaskTable 批选。
  • KPI 差值表以第一个方案为基准，延迟/成本越小越优、吞吐/MFU 越大越优；缺失值显示「—」不参与最优。
  • Gantt 同尺度：各方案 timeRange.end 取最大值作 fixedTimeRange，dataZoom 初值统一 [0,100]。
  • 进入对比 2 步：结果表勾选 ≥2 → 「对比」按钮 → enterComparison（批量建 tab + LRU 回填存活 id + 切 analysis 视图）。
  • 已知限制：前端无 vitest runner，computeKpiDiffs 单测以 vitest 格式写就但未接入 CI（逻辑经一次性转译运行验证）；缺数据的对比列以提示横幅告知用户而非静默丢弃。

live-progress-stream（Wave 1 功能 1，2026-06-12 完成）​

  • 进度计量来源：实时 progress_meta（sim_time_ns / event_count / events_per_s / eta_s）仅多芯片通信原语仿真路径产出，在 Rust 回调 (frac, sim_time_ns, event_count) 上达 Python 后于 comm_primitive_pipeline._sim_progress 装配。部署 G5 路径走单芯片仿真，无实时计量。ETA 用 Rust 原始未缩放 frac。
  • 节流串联：Rust 端 400ms 墙钟或 2% 字节步长触发回调，services 端 0.5s 节流广播，串联最坏推送间隔 0.9s，满足「1s 内至少一次」。
  • 日志通道：每任务 deque(maxlen=1000) 环形缓冲（C 层原子截断免锁），生命周期 + 10% 里程碑写日志；HTTP GET /evaluation/tasks/{id}/logs 回放缓冲，WS task_log 消息推增量，前端经共享日志总线（单 WS 连接）分发，实时流允许丢行。

附录 C：数据结构​

  • trace Arrow schema 与出口端点的字段级定义：由 G5事件trace出口与事件时间线设计规格（Accepted）承接冻结——schema R（原始模式，与落盘 Parquet 同构）、schema G（聚合模式）、活跃区间快照 S、窗口查询端点签名见其附录 C。
  • WebSocket 信封的字段级定义：在 Wave 1 live-progress-stream 实现中落地（见附录 B 实现说明），字段级冻结版本待后续回填。