cuml.accel 基准测试页同步指南从 cumlbench-dash 数据到 Sphinx 页面与 SVG 热力图【免费下载链接】cumlNVIDIA cuML: GPU-Accelerated Machine Learning项目地址: https://gitcode.com/GitHub_Trending/cu/cuml本指南面向 NVIDIA cuML 仓库中 cuml.accel 基准测试文档的维护者与贡献者完整讲解基准页面的数据契约publication schema v1、sync/render同步工作流、校验规则与编辑规范。读完本文你将掌握如何用一条命令把 cumlbench-dash 产出的便携式基准数据校验、落盘并渲染为 Sphinx RST 页面与两张 SVG 热力图以及如何安全地修改页面叙述而不破坏生成物。一、基准页的生成架构数据与呈现分离cuml.accel 的基准测试页面采用“紧凑数据 渲染时推导”的两层架构这是整个同步流程设计的核心前提仓库内检入的 benchmark-data.json 是 Sphinx 页面的唯一紧凑输入由 NVIDIA 内部工具cumlbench-dash产出原始基准观测数据保存在仓库之外该文件只存储无法从标签推导的事实基准系统CPU/GPU/内存与软件包版本、用例标签、数据形状行数/特征数、CPU/GPU 中位耗时、适用时的 CPU 超时上限以及无法从标签推导的 PCA 成分数components加速比speedup、分类classification、汇总summary、输入尺寸input bytes与显示单位M/s、k/s、×全部在渲染阶段派生并不落盘存储。渲染链路在 generate_cuml_accel_benchmarks.py 中实现约 1050 行纯标准库无第三方依赖最终产物有三份产物路径说明RST 页面benchmarks.rst由模板渲染生成禁止直接编辑训练热力图training-heatmap.svg训练与组合操作加速比热力图推理热力图inference-heatmap.svg推理与 transform 加速比热力图二、数据契约publication schema v1 与 168 个用例同步命令只接受publication schema version 1的数据契约由validate_publication_data()源码 L179-L340强制校验。顶层对象必须且只能包含四个字段schema_version、system、packages、records。2.1 system基准硬件环境system.components必须恰好包含三个组件cpu、gpu、memory 各一个count必须为 1cpu属性为logical_cores与physical_cores且逻辑核数不得小于物理核数gpu / memory属性为total_memory_bytes。当前检入数据描述的测试机为AMD Ryzen Threadripper PRO 7975WX32 物理核 / 64 逻辑核、约 134 GB 系统内存、NVIDIA RTX PRO 6000 Blackwell Workstation Edition约 102 GB 显存。测试 test_narrative_gpu_matches_publication_hardware 专门断言页面叙述中的 GPU 名称与发布数据一致防止图文脱节。2.2 packages软件版本快照packages必须恰好包含四个包cuml、scikit-learn、umap-learn、hdbscan缺一即校验失败见 test_required_package_version_is_rejected_when_missing。当前版本快照为cuml 26.10.0a69、scikit-learn 1.9.0、umap-learn 0.5.12、hdbscan 0.8.44。2.3 records168 条用例记录records必须是恰好 168 条的列表构成为165 条性能网格用例20 个估计器 × 各类操作 × 5 类相对工作量3 条额外的 medium-wide PCA 成分数rank测量pca.fit_transform.rank128/rank256/rank512.medium.wide现有的pca.fit_transform.medium.wide用例本身承担rank-1024数据点因此 PCA rank 表共覆盖 128/256/512/1024 四个成分数。每条记录必填字段为case_label、cpu_median_sec、gpu_median_sec、rows、features可选字段为cpu_timeout_sec仅当 CPU 超时、cpu_median_sec为null时使用与components仅 PCA 非 rank 变体需要。2.4 case_label 解析规则用例标签是数据契约的核心解析逻辑见_parse_case_label()源码 L163-L176支持两种格式常规格式estimator.operation.size.shape例如dbscan.fit_predict.large.balancedrank 限定格式estimator.operation.rankN.size.shape例如pca.fit_transform.rank128.medium.wide其中N必须匹配rank([1-9]\d*)拒绝rank0128这类前导零写法。校验还强制估计器必须属于七大算法族见 FAMILIES 定义 L71-L96操作必须属于训练类fit/fit_predict/fit_transform或推理类predict/transform/score_samples/kneighbors工作量必须是五个相对类别之一rank 变体仅允许pca.fit_transform×medium.wide组合所有 rank 表记录必须使用相同的形状否则抛出PCA rank-table records must use the same shape对应 test_pca_rank_table_records_with_different_shapes_are_rejected。2.5 CPU 超时语义当 CPU 侧超过整用例而非单次估计器调用墙钟上限时cpu_median_sec记为null改由cpu_timeout_sec携带超时上限。此时渲染器把cpu_timeout_sec / gpu_median_sec作为保守下界加速比页面以≥前缀与斜纹填充标记而不是精确值。当前检入数据中 7 条 CPU 超时用例分布为umap 5 条、kernel_density 1 条、random_forest_regressor 1 条。三、同步工作流sync 命令从仓库根目录执行将 cumlbench-dash 产出的新发布数据同步进文档树并渲染全部产物python docs/benchmarks/generate_cuml_accel_benchmarks.py sync \ --data /path/to/benchmark-data.jsonsync的实际执行序列见 sphinx_main L1029-L1040load_publication_data()加载并完整校验外部数据JSON 解析失败或契约违规立即报错将外部产物原样复制byte-for-byte到 benchmark-data.json不做任何改写调用render_files()源码 L959-L970渲染benchmarks.rst与两张 SVG 热力图通过_write_or_check()写盘存在差异时打印过期文件清单。--template可选参数可指定替代的 RST 模板默认 benchmarks.rst.in。四、渲染与校验render、sync --check、render --check日常文档构建只需要基于检入数据渲染三种常用姿势python docs/benchmarks/generate_cuml_accel_benchmarks.py render python docs/benchmarks/generate_cuml_accel_benchmarks.py sync --check \ --data /path/to/benchmark-data.json python docs/benchmarks/generate_cuml_accel_benchmarks.py render --check各模式语义如下命令数据来源行为失败退出码render检入的benchmark-data.json--data可覆盖渲染并写盘 RST 两张 SVG1render --check同上只比对不写盘文件过期即失败并列出差异文件1sync --data f外部产物校验并复制外部产物随后渲染写盘1sync --check --data f外部产物 检入数据校验两份产物、验证二者逐字节一致并检查渲染文件是否最新全程不写盘1其中sync --check是三合一校验既验证外部数据的契约合法性又用同一套校验器验证检入数据还比对渲染产物与预期内容内容以字符串全等比较等价于字节级一致任何一步不满足都以非零码退出适合作为 CI 门禁。五、渲染产物解析RST 页面与热力图5.1 模板占位符驱动的 RST 页面render_rst()源码 L890-L956先把发布数据规范化为内部记录补充分类、输入字节数、加速比、超时侧、阶段等派生字段再对模板中的PLACEHOLDER做替换。主要占位符TRAINING_PROSE_SPEEDUP训练阶段配对用例的中位加速比叙述文案保留一位小数WORKLOAD_TABLE五个相对工作量类别的行数/特征数/输入尺寸范围表ESTIMATOR_SECTIONS按七大算法族组织的各估计器详细结果.. dropdown::折叠块锚点见 ANCHORS L101-L123PCA_RANK_RESULTS/PCA_RANK_ROWS/PCA_RANK_FEATURESPCA rank 对比表及其形状GPU_NAME/GPU_MEMORY_GB/CPU_NAME/SYSTEM_MEMORY_GB/PACKAGES测试环境叙述CPU_TIMEOUTS/GPU_TIMEOUTS/BOTH_TIMEOUTS超时统计。替换完成后脚本会扫描未解析的…占位符存在残留立即抛错防止页面出现半成品占位符。测试 test_benchmark_files_can_be_rendered 断言渲染结果非空且不含。5.2 两张 SVG 热力图热力图由render_heatmap()源码 L604-L726纯代码生成行按中位精确加速比降序排列列固定为五个工作量类别训练热力图training-heatmap.svg895×768覆盖全部 16 个有精确数据的训练/组合操作推理热力图inference-heatmap.svg只展示中位精确加速比最高的 10 个操作INFERENCE_HEATMAP_MAX_OPERATIONS 10详细表格仍保留全部推理结果——短操作中调度与数据转换开销占主导单独展示会误导颜色语义绿色为加速、灰色居中于 1×、暖色为减速饱和度以 16× 封顶abs(log2(v))/4斜纹填充表示 CPU 超时下界与不可用结果每个单元格带roleimg与完整aria-label操作标签为指向对应估计器详情的超链接href../../cuml-accel/benchmarks/#benchmark-xxx保证无障碍可读。训练热力图docs/source/_static/cuml-accel-benchmarks/training-heatmap.svg 按中位精确加速比排序的 16 个训练/组合操作 × 5 类工作量加速比网格推理热力图docs/source/_static/cuml-accel-benchmarks/inference-heatmap.svg 中位精确加速比最高的 10 个推理/transform 操作的加速比网格5.3 推理结果的吞吐量表示推理与 transform 行以吞吐量呈现输入行数除以同一中位墙钟时间一行计为一个样本按量级格式化为M/s、k/s或/s下方附计算所用墙钟时间训练与组合操作行只显示墙钟时间见_fmt_backend_result()L529-L538。六、编辑规范只改模板不碰生成物页面叙述与结构修改只允许编辑模板benchmarks.rst.in其头部注释明确要求改后执行render。具体约束不得直接编辑生成的 benchmarks.rst 或两张 SVG 文件——render --check/sync --check会把任何手工改动判定为“过期”并让 CI 失败测试 test_generated_files_are_current 同样守护这一约束模板替换机制会把文件头自动从 “editable template” 注释改写为 “Generated from benchmarks.rst.in; do not edit this file directly.”从源头提醒后续维护者模板中还定义了:benchmark-throughput:、:benchmark-time:两个 Sphinx 角色与benchmark-lede、benchmark-heatmap等 CSS 类叙述性修改时需保持这些结构约定。七、验证与回归测试用例佐证整个同步-渲染链路有独立测试套件守护测试文件 test_generate_cuml_accel_benchmarks.py 通过importlib直接加载生成脚本不依赖安装核心覆盖可渲染性render_files()输出非空 RST、无未解析占位符、SVG 根节点为合法svg且带roleimg产物最新性所有生成文件与当前检入内容逐字节一致环境一致性叙述中的 GPU 名称/包版本必须来自发布数据test_rendered_environment_comes_from_publication_data契约拒绝路径重复系统组件、缺失包版本、非法标签组合未知估计器、未知操作、rank 变体搭配错误形状/操作等一律抛ValueError合法扩展dbscan.predict.large.balanced与pca.fit_transform.rank64.medium.wide这类受支持扩展可正常通过校验。回归时可运行python -m pytest docs/benchmarks/tests/test_generate_cuml_accel_benchmarks.py八、当前检入数据的速览与解读边界基于仓库内检入的 benchmark-data.json 可以快速勾勒页面数据画像20 个估计器、33 个估计器×操作组合、168 条用例含 3 条 PCA rank 变体161 条精确加速比记录中位约 3.4×按阶段拆分训练配对用例82 条中位约 5.5×推理配对用例79 条中位约 1.3×渲染脚本以 “approximately 5.5×” 写入页面叙述7 条 CPU 超时用例以≥下界呈现umap 占 5 条PCA 的 rank 敏感性体现得最直观在 61,035 行 × 4,096 特征的中宽数据上rank-128 时 CPU 快于 GPUrank-256 接近持平rank-512 起 GPU 反超rank-1024 加速比约 2.6×——这正是模板中“transfer-dominated 低 rank 工作到高 rank 正加速”的跨拐点叙述的数据来源同时存在 GPU 慢于 CPU 的用例如 PCA 大宽 transform、elastic_net 大宽 predict说明短操作与数据搬运开销以及形状/参数对加速比的显著影响页面因此特别强调这些测量只描述被测用例在本测试机上的表现其他工作负载与系统上的结果会不同。解读数据时务必遵循模板中的方法论边界CPU 对照实现使用对应 scikit-learn 估计器UMAP 用umap.UMAP、HDBSCAN 用hdbscan.HDBSCAN每个隔离用例执行一次预热 三次测量取中位墙钟时间 操作适配的正确性校验 整用例超时加速测量经插桩确认 GPU-only 执行。这些细节见 benchmarks.rst.in 的 Methodology 一节与 benchmarks.rst 渲染结果保持一致。九、小结一条命令维护完整基准页整套机制的收益在于单一数据源 全量派生维护者只需把 cumlbench-dash 的便携式产物交给sync校验、落盘、渲染、校验输出一气呵成页面叙述改动走benchmarks.rst.in模板CI 用--check系列命令保证数据、模板与生成物三者永远同步。后续可继续阅读 usage、compatibility 与 logging-and-profiling 了解 cuml.accel 的零代码加速用法与运行期行为。【免费下载链接】cumlNVIDIA cuML: GPU-Accelerated Machine Learning项目地址: https://gitcode.com/GitHub_Trending/cu/cuml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考