在JIT编译的GPU内核库中添加并测试内核

## 搭建可编辑安装，修改内核后自动重新编译 使用可编辑安装，并保留环境中现有的框架和加速器版本。 如果隔离的依赖解析可能拉取不兼容的运行时软件包，请将其禁用。 构建或测试前，初始化所有必需的源代码子模块。 将即时编译作为默认开发循环。 编辑内核源文件，运行重点测试，让源文件哈希触发重新编译。 除非打包代码本身发生变化，否则不要在每次编辑内核后重新安装软件包。 只有陈旧工件属于诊断对象时，才清除 JIT 缓存。 只有首次使用需要更快速度或分发有此要求时，才使用预编译内核软件包。 在日常开发中，将预编译工件保持为可选项。 为检测到的本地 GPU 之外的设备构建时，明确设置目标架构。 根据可用内存限制编译器线程数和并行构建任务数。 以任务数、编译器线程数和每线程需求三者的乘积估算总编译内存。 不要让测试参数大小造成可避免的设备内存耗尽。 只有需要准确的硬件计时时，才安装性能分析支持。 审查前运行格式化和仓库钩子。 ## 生成的文件只写入可写的工作区，不写入安装目录 通过通用的规格接口表示每条编译工具链。 为每项规格提供唯一名称、源文件列表、编译器标志、链接器标志和支持的架构。 使用共享的构建与加载模板协调缓存查找、锁定、编译和加载。 明确生命周期：先尝试从缓存加载，需要时构建，再加载已编译模块。 如果设置了禁用标志，且不存在有效的缓存模块或预编译模块，则拒绝 JIT 编译。 安装后的软件包目录可能是只读的，因此绝不能将生成文件写入其中。 将源文件模板和预编译软件包数据保持为只读。 仅将渲染后的源文件和复制的编译单元写入生成源文件工作区。 仅将对象文件、共享库、元数据和构建文件写入 JIT 工件工作区。 根据确切的源文件列表和编译标志生成构建清单。 确保共享、临时或受限环境可以覆盖工作区位置。 使用架构上下文，将检测到的设备与明确请求的目标相结合。 编译开始前，将模块限制在受支持的架构系列内。 请求的架构均不受支持时，应明确失败。 不得在没有提示的情况下为其他设备系列编译。 ## 从设备代码到公共API，逐层添加新内核 针对裸指针和可移植内核类型实现与框架无关的设备代码。 不要在可复用的内核包含层中放置框架头文件。 在绑定层添加启动器，用于验证张量并准备调用参数。 通过项目的类型化跨语言 FFI 导出启动器。 根据专用化参数计算确定性的操作 URI。 在可写源文件工作区中创建每项操作独立的生成目录。 只有需要具体类型或参数专用化时，才使用模板。 只有内容不同时，才写入渲染后的配置。 将所需的编译单元复制到生成目录。 返回包含 URI、源文件、标志和架构限制的编译规格。 提供可复用已加载模块的缓存式高级 API。 分发需要时，为预先编译的软件包生成注册该操作。 从软件包入口点导出公共 API。 附加一个定义轴、输入、输出和可选参考结果的跟踪模板。 对于先规划后运行的 API，将跟踪功能附加到执行操作的方法。 添加实际可用的跟踪示例，重新生成基准定义工件，并提交预期结果。 重新生成后运行跟踪一致性测试和端到端测试。 ## 测试时跳过不支持的GPU，速度结论必须附带正确性检查 进行广泛验证时运行完整测试套件，迭代期间运行重点测试。 通过统一的能力辅助函数有意跳过不支持的硬件。 API 提供相关判定函数时，同时检查设备计算能力和后端支持情况。 明确每项功能的架构要求。 不要将不受支持的架构转变为测试失败。 不要因为本地设备不同而跳过受支持的架构。 选择能够验证契约，同时不会因可避免的内存不足而跳过的测试形状。 覆盖受变更影响的注意力、矩阵乘法、混合专家、通信和实用工具路径。 对集合或分布式测试使用多设备启动工具。 通过支持可比较后端和批量配置的统一工具执行基准测试。 优先使用硬件级性能分析器计时，不可用时改用加速器事件。 记录生成每项基准结果的计时机制。 报告中位数、变化、迭代次数、工作负载形状、数据类型、架构和后端。 比较内核时启用参考结果检查。 没有正确性检查和可复现参数时，不得宣称速度优势。 批准性能敏感型内核前，必须取得基准测试和测试证据。 ## 源码或目标GPU变化时，重新构建缓存的内核 对已加载模块使用进程内缓存，对已编译工件使用磁盘缓存。 源文件、标志、架构、参数或库版本变化时，使缓存模块失效。 根据操作类型、参数、源文件哈希、标志和目标架构派生缓存标识。 确保缓存键在不同专用化和工具链变体之间保持唯一。 将兼容性元数据存储在工件旁，并在加载前验证。 通过锁定保护编译，防止并发进程损坏共享工件。 对于单一架构 DSL 输出，存储一个包含元数据的模块目录，并为每项专用化存储一个对象。 根据 DSL 编译目标或活动设备派生架构。 编译器软件包版本或内核源文件哈希变化时，使 DSL 模块失效。 允许在诊断时禁用缓存，同时默认保持复用启用。 使用分派宏或生成代码管理数据类型与块大小的组合空间。 明确分派选择，并测试不支持的组合。 直接编写源代码已经足够时，不要添加模板化处理。 不要让陈旧的预编译软件包绕过版本兼容性检查。 只有进行有意且已诊断的混合版本实验时，才绕过版本检查。 ## 在内核运行前记录API输入，以便复现崩溃 在内核执行前记录 API 输入，使导致崩溃的参数能够在设备故障后保留下来。 禁用日志时，保持零开销。 为调用名称、输入和输出以及高开销统计提供分级级别。 仅在明确启用的高详细度诊断中收集统计信息和扫描无效值。 图捕获期间跳过不兼容的统计收集。 按事件数量和总大小限制诊断转储。 支持包含和排除过滤器，使高开销捕获仅针对相关 API。 如果转储必须在环境之间移动，请选择可移植的张量格式。 使用专用的可写转储目录。 只有在诊断故障时，才启用详细编译输出和调试符号。 同时检查生成源文件、构建清单、已编译模块和缓存元数据。 复现崩溃时记录形状、数据类型、架构、标志和选定的后端。 性能分析器或调试器需要源文件映射时，使用行信息。 将常规优化设置与调试构建分开。 将强制选择算法或后端视为诊断控制，而不是生产环境默认值。 记录复现结果时使用的每项非默认控制。 ## 校验下载的工件，并按明确的GPU列表构建发布包 在离线或锁定环境中缺少本地工件时，必须直接失败。 允许受信任的镜像替换默认工件仓库。 默认验证下载工件的校验和。 只有作为临时调试手段时，才禁用校验和验证。 限制并行工件下载数量。 尝试下载前，优先使用已配置的本地源。 保持编译标志和启动器覆盖值明确且可观察。 将工件加载器的日志控制与 API 调用日志控制区分开。 自动调优应使用稳定计时；事件计时不可靠时，可使用硬件全局计时器。 允许在受控的 CI 诊断中覆盖机密计算检测结果。 只有指定了明确的缓存位置且环境兼容时，才持久化自动调优结果。 加载策略阻止列表，避开已知会在当前软件栈上挂起或崩溃的内核。 让实验性路由和内核选择覆盖值保持其文档规定的默认设置。 针对明确的架构列表构建预先编译的软件包。 从唯一的权威版本来源生成软件包版本元数据。 对内核、设备支持和错误修复使用向后兼容的版本增量。 将不兼容的 API 变更限定在架构版本边界。 ## 让公共API和文档与内核代码保持一致 使用类型化跨语言 ABI，使同一内核能够服务多个宿主框架。 将框架特定的张量处理放在绑定中，而不是设备头文件中。 只有编译和图捕获需要时，才在宿主框架中注册自定义操作。 保持 Python API、JIT 生成器、绑定导出、预先编译注册表和软件包导出同步。 采用高级工作区或先规划后运行设计前，先从最简单的可工作内核模式开始。 参数变化时，同时更新函数签名、模板、启动器和测试。 从附近可工作的示例中学习既有的风格、复杂度、防御性和效率。 记录有意的偏离和性能关键型算法选择，并说明考虑过的替代方案。 对于特定于架构的行为，请查阅权威的指令集和工具链文档。 外部文档陈旧时，优先使用随项目提供的依赖源代码。 保持跟踪模板和生成的基准定义与公共 API 同步。 日志、要求、FFI 或代码生成模式发生变化时，更新基础设施示例和教程。 明确标记弃用的方法，或将其从当前指南中移除。 按照贡献政策披露有实质意义的 AI 协助。 只有源文件、生成工件、缓存、测试、基准、导出和文档一致时，才予以批准。