PyPTO-Pro 全部资料索引【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gymAPI{api_count}篇官方样例{sample_count}个教程{tutorial_count}篇。§A API 文档A.1 API 总索引{api_index}A.2 API 文档清单{api_rows}§B 官方指定算子样例#算子名称缓存相对路径类型描述{sample_rows}§C 教程与设计指南{tutorial_rows}各占位符的语义与填充规则如下 | 占位符 | 含义 | 生成规则 | |--------|------|----------| | {api_count} | API 文档总篇数 | docs/pypto_pro/api/**/*.md 全量数量 | | {api_index} | API 总索引路径 | 固定为 docs/pypto_pro/api/index.md缺失则生成失败 | | {api_rows} | API 文档逐篇清单 | 除总索引外的全部 API 文档路径每行一条 - path 稳定排序 | | {sample_count} | 官方样例个数 | 来自清单的样例行数 | | {sample_rows} | 官方样例表格行 | 逐行复制 official_samples.md 规范表中的数据行 | | {tutorial_count} | 教程篇数 | Pro 指南 快速入门 共享简介的总数 | | {tutorial_rows} | 教程逐篇清单 | 各目录全量 .md 路径含各目录 index.md最后并入 docs/guide/introduction.md | 从结构设计看索引刻意把**目标版本事实清单**与**人工结论**分离索引只负责列出有什么、在哪里§A/§B/§C 的路径与计数而每条 API 怎么用、公式步骤怎么映射、有哪些约束则写入配套的 [explore_report.md](https://link.gitcode.com/i/f5477251fe2f7d4b465e1941539e0aad) 探索报告。索引是报告的证据底座报告是 Stage 3 的事实输入。 ## 三、生成器实现模板校验与填充的源码级原理 生成器位于 [build_material_index.py](https://link.gitcode.com/i/6a1bd73ec97f222486d2662307784669)其核心是 build_index(devkit, manifest) 与 main() 两个入口。理解它可以回答为什么模板必须长这样。 ### 3.1 模板字段的强约束校验 生成器定义了两组硬性约束任何违反都会以 MaterialIndexError 拒绝生成 - **字段集合**TEMPLATE_FIELDS (api_count, api_index, api_rows, sample_count, sample_rows, tutorial_count, tutorial_rows)。生成器用 string.Formatter().parse() 解析模板要求每个字段**恰好出现一次**且不允许携带 format_spec 或 conversion即模板中只能写 {api_count} 这种最简形式不能写 {api_count:3}。 - **章节顺序**TEMPLATE_ORDER (## §A API 文档, - {api_index}, {api_rows}, ## §B 官方指定算子样例, {sample_rows}, ## §C 教程与设计指南, {tutorial_rows})。生成器逐行统计这些关键行在模板中恰好出现一次且行号位置必须严格递增——也就是说模板的章节编排顺序是**契约的一部分**不允许调整。 这意味着模板不是建议格式而是**可机检的规范**。下游 [validate_stage1.py](https://link.gitcode.com/i/af258a2304f2f90c77a2ec3c01cb7a9e) 会复用 build_index 现场重建标准索引与 custom/op/PRO_MATERIAL_INDEX.md 逐字节比对不一致即判定 PRO_MATERIAL_INDEX.md is stale索引过期。 ### 3.2 三类资料的扫描来源 生成器只从 devkit 缓存即 $PYPTO_DEVKIT_DIR中读取绝不读其他来源 | 章节 | 扫描根目录 | 额外完整性要求 | |------|-----------|----------------| | §A API | docs/pypto_pro/api/ | 目录必须存在且至少含一个 .mddocs/pypto_pro/api/index.md 必须在清单内 | | §B 官方样例 | references/official_samples.md 清单 pro_ops/ 目录 | 清单表结构合法、编号从 1 连续、路径无重复且每个清单文件都真实存在于 pro_ops/ | | §C 指南/教程 | docs/guide/programming_guide/pro/、docs/guide/quick_start/pro/ 与 docs/guide/introduction.md | 两个 Pro 目录都必须含各自 index.md简介文件必须存在 | 路径统一写成**相对 devkit 缓存根**的 posix 路径如 docs/pypto_pro/api/vf/vf_add.md、pro_ops/fa/test_fa_with_mask.py并以此统计 API/样例/教程的计数。值得注意的是 §C 只扫描 Pro 专属指南与快速入门目录**不扫描 Tensor 专属指南目录**这一边界在技能 SKILL 文档与生成器代码中保持一致。 ### 3.3 官方样例清单的解析规则 _samples() 函数对 [official_samples.md](https://link.gitcode.com/i/fd1cb0eb8581cd96edfb0d4caee907c1) 的解析相当严格 - 表头必须精确等于 (#, 算子名称, 缓存相对路径, 类型, 描述) 五列且全文只允许出现一个规范表 - 分隔行必须是五个 :?-{3,}:? 形式的单元格 - 每行第 3 列必须匹配 pro_ops/[^|]\.py 模式第 1 列必须是数字且编号必须从 1 连续递增、路径不得重复 - 清单中的每个路径都必须在 devkit/pro_ops/ 递归扫描结果中真实存在缺一即整体失败。 当前仓库清单中收录了 13 个官方指定样例覆盖三类参考价值 - **纯 Cube / matmul 类**pro_ops/matmul/test_matmul_8k_example.pymatmul 入门、test_matmul_perf_asw_4k_dn_move_offset.py、test_matmul_perf_asw_8k_k128_dn_move_offset.py 及两个动态轴版本matmul 性能 - **VC 融合 / FA 类**pro_ops/fa/test_fa_perf_tkv_preload_dn_vf_bufid_dynrank.py生产级、test_fa_tilingkey_attn_mask.py教学、test_fa_with_mask.pymask NBuffer auto_mutex 性能、test_flex_attention.py - **VF / elementwise 类**pro_ops/element_wise/test_add.py、pro_ops/lightning_indexer/test_quant_lightning_indexer_vf.pyVF TopK、pro_ops/vf_api/test_layernorm_tile_group_vf.py 与 test_softmax_tile_group_vf.py。 清单还规定了维护规则增删样例**只改 official_samples.md 一个文件**路径一律用 pro_ops/ 开头的相对路径。这是整个 PyPTO-Pro 工作流统一的样例索引来源orchestrator 装配 pro_ops/ 时也只保留清单内文件。 ## 四、命令行使用重建与校验 ### 4.1 重建索引 按技能 SKILL 文档的标准操作将 skill-dir 与 缓存绝对路径 分别替换为本技能绝对路径和编排器给定的 PYPTO_DEVKIT_DIR 值保留引号 bash python skill-dir/scripts/build_material_index.py \ --devkit 缓存绝对路径 \ --output custom/op/PRO_MATERIAL_INDEX.md参数说明参数必填作用--devkit是PyPTO-Pro 资料缓存根目录即$PYPTO_DEVKIT_DIR生成器只读该目录--output是索引输出文件路径不能是目录、不能落在 devkit 内部、不能覆盖生成器自身的输入脚本、清单、模板--check否只校验不写入重建标准索引后与现有文件比对不一致返回 material index is stale 错误成功时输出apiN samplesM tutorialsK并返回退出码 0遇到缓存缺目录、清单非法、样例缺失等任何MaterialIndexError时返回退出码 2且不覆盖已有索引。4.2 原子写入与安全设计_write_index()采用临时文件 os.replace的原子写策略在输出目录创建.{output.name}.XXXX.tmp临时文件写完后再原子替换目标文件避免生成中断产生半截索引。输出路径还会被校验不允许等于 devkit 本身或位于 devkit 之内防止污染只读缓存也不允许覆盖脚本、清单或模板三个受保护文件。4.3 只读校验模式--check模式是整个 Stage 1 收尾自检的关键一环。在 pypto-pro-op-plan/SKILL.md 定义的第 6 步会运行python skill-dir/scripts/validate_stage1.py \ --op-dir custom/op \ --devkit 缓存绝对路径 \ --kb-root kb-root【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考