FlashInfer 实验性 API 与后端（Experimental APIs and Backends）完全指南：显式启用、自动路由门控与升级毕业流程

• 大模型
• 深度学习
• 算子库
• 后端
• 高性能计算

FlashInfer 在稳定功能之外，为快速迭代的工作（如 SM12x 客户端 GPU 内核、最新模型的新算子、针对特定问题规模的高度特化内核）专门划分了实验性（experimental）轨道：实验性 API 是可能随时变更或消失的公开接口，实验性后端是尚未就绪的稳定实现。本文以 docs/experimental.rst 为骨架，结合flashinfer/experimental/README.md（该策略的规范性全文）与源码实现，完整讲解实验性功能的两种显式启用方式、FLASHINFER_ALLOW_EXPERIMENTAL_AUTO_BACKENDS自动路由门控、JIT-only 打包约束、用户契约、贡献者准入/评审/升级毕业（graduation）全流程，并给出可直接照做的配置与代码示例。

一、实验性功能的两类形态：API 与后端

FlashInfer 对实验性功能做了两类严格区分（见 flashinfer/experimental/README.md）：

二者是相互独立的关注点。组合矩阵如下：

从源码结构看，代码放置遵循"核心薄入口 + 实验包承载实现"的原则：

• 实验性 API 位于核心代码中，用@flashinfer_experimental_api装饰器标记（定义于 flashinfer/api_logging.py）。升级毕业时只需移除该标签，用户无需改变导入路径；
• 实验性后端与后端特有逻辑位于flashinfer/experimental/（可整体导入为flashinfer.experimental）。

核心中若存在实验性入口点，其函数体只允许包含：公开 API 签名、通用（共享的）校验、feature-gate 检查、后端选择、以及直接转交flashinfer.experimental的处理。而后端的支持检查、启发式、路由、编译、缓存与内核实现全部留在实验包内——这保证了"移除 = 删除一个目录"的干净生命周期。

当前仓库的flashinfer/experimental/下已容纳大量真实实验功能，例如b12x/、balanced_gqa_decode/、deepgemm_*系列（batched/fp4/fp8/kgroup/mega_gate/mixed_gemm 等）、kimi_k3_*系列（attn_res/fp8_projection/fused_router/latent_moe/tp12_tail/vision_tower）、minimax_h3_varlen_attention/、nvfp4_attention/、nvfp4_mla_decode/、sm110_gqa_decode/、sm110_xqa/等，可作为理解实验轨道的具体参照。

二、显式启用（opt-in）：两种无需环境变量的形式

使用实验性功能永远是显式、可见的选择。以下两种形式都不需要任何环境变量：

1. 调用被@flashinfer_experimental_api标记的 API；
2. 向稳定 API 显式传入实验性后端名，例如backend="sm12x_cute"。

两种方式都会触发一次ExperimentalWarning（实验性 API 每个 API 警告一次；实验性后端每个 API/后端 组合警告一次）。从 flashinfer/api_logging.py 看，ExperimentalWarning继承自UserWarning，其语义即"无兼容性与长期支持保证，可能不经弃用期直接变更或移除"。

关于环境变量，需要特别澄清：FLASHINFER_ALLOW_EXPERIMENTAL_AUTO_BACKENDS不控制显式选择，只控制自动选择。experimental_auto_backends_allowed()的实现（flashinfer/api_logging.py）为每次调用读取环境变量，使得门控可在运行时动态切换（例如在测试中）；它检查的是os.environ.get("FLASHINFER_ALLOW_EXPERIMENTAL_AUTO_BACKENDS", "0") == "1"，即只有精确设为1才放行。

三、自动选择门控：FLASHINFER_ALLOW_EXPERIMENTAL_AUTO_BACKENDS

被门控的只有自动选择（automatic selection）。稳定 API 以backend="auto"调用时——包括其背后的调度启发式（heuristics）与自动调优（autotuning）——只有在用户显式设置环境变量后才可能选中实验性后端：

export FLASHINFER_ALLOW_EXPERIMENTAL_AUTO_BACKENDS=1

行为分两种情形：

• 未设置该变量：自动选择只考虑稳定后端。若一次调用的唯一可行候选全是实验性后端，调用会失败并抛出BackendSupportedError，错误信息会点名该环境变量，并建议显式传入backend=。从 flashinfer/utils.py 的源码看，错误提示还会列出"被排除的实验性后端"清单（dropped_experimental_backends），并给出完整提示文案：(experimental backend(s) [...] were excluded from automatic selection; set FLASHINFER_ALLOW_EXPERIMENTAL_AUTO_BACKENDS=1 to include them, or pass backend= explicitly)；
• 设置了该变量：实验性后端加入自动候选列表；一旦被选中，每个 API/后端 组合发出一次ExperimentalWarning。

3.1 门控如何穿透到自动调优

门控并非只作用于一次 dispatch。自动调优的 API 是在<api>.suitable_auto_backends候选列表上做调优的，而该列表本身就是被过滤后的结果（见 flashinfer/utils.py 的suitable_auto_backends实现：先逐后端跑 checker 收集合适候选，再把实验性后端从列表剔除，除非环境变量放行）。因此，环境变量未设置时，实验性后端同样不会进入自动调优的搜索空间——这从根源上防止了调优结果悄悄依赖实验实现。

3.2 手工路由的等价门控

对于不使用@backend_requirement、而是手工路由"auto"的稳定 API，需要在自动路由分支（绝不是显式分支）调用require_experimental_auto_backends(feature)（flashinfer/api_logging.py）。该函数在变量未设置时直接抛出RuntimeError，文案与BackendSupportedError的提示一致。原始文档与 README 中给出的等价写法：

from .api_logging import require_experimental_auto_backends if backend == "auto" and candidate == "experimental_xyz": require_experimental_auto_backends("op_name -> experimental_xyz") if candidate == "experimental_xyz": from .experimental.xyz import run # deferred import return run(...)

3.3 门控的边界：trace-apply 不在门控内

Trace-apply 位于此门控之外：实验性后端不要求支持 trace（fi_trace），而 trace-apply 方案是部署者显式的选择。导入flashinfer.experimental本身也永远被允许——以便工具链、文档与自省可以工作；导入阶段不做任何强制（见 flashinfer/experimental/init.py 的模块注释）。

四、门控原语（Gating Primitives）速查

所有门控原语定义于 flashinfer/api_logging.py（其中experimental_backend位于 flashinfer/utils.py，紧邻backend_requirement），并统一从flashinfer.experimental重新导出（见 flashinfer/experimental/init.py）：

其中@experimental_backend在@backend_requirement内部有三种效果（flashinfer/utils.py 的实现）：

• 自动选择跳过该后端（除非变量放行），自动调优因共享候选列表而同样被覆盖；
• 显式backend="<name>"始终可用——命名后端本身就是 opt-in——并对每个 (API, backend) 组合发出一次ExperimentalWarning；
• 后端被列入<api>.experimental_backends属性。

这里还有一个重要的"放置即兜底"机制：@backend_requirement装饰时会检查 checker 的__module__，凡是定义在flashinfer.experimental下却未被标记的 checker 会立即raise ValueError——忘记加标记会在导入期失败，而不是悄悄混进自动选择（flashinfer/utils.py）。

五、实战一：新增一个实验性 API（新公开函数）

原始文档与策略 README 给出如下流程：先在flashinfer/experimental/<feature>/下实现后端，再在合适的核心模块中新增公开函数并加装饰器：

from .api_logging import flashinfer_experimental_api @flashinfer_experimental_api def my_new_op(x, ...): """Docstring (the decorator prepends the experimental banner).""" # shared validation only from .experimental.my_feature import run # deferred import return run(x, ...)

调用my_new_op本身就是 opt-in。装饰器每个进程警告一次（ExperimentalWarning）并设置is_experimental = True，全程不涉及任何环境变量。

从源码实现看（flashinfer/api_logging.py），该装饰器还做三件附带的事：

• 先给原函数f打上is_experimental = True标记再交给flashinfer_api注册——因为 trace 注册表记录的是f而非包装后的 wrapper，稳定 trace 测试靠该标记做过滤；
• 在 wrapper 上设置is_experimental与experimental_feature（默认取f.__qualname__）；
• 在 docstring 前自动拼接一段 Sphinx 风格的.. warning::banner，即"文档中的警告横幅"的来源。

注意函数体是典型的薄核心入口：共享校验后，通过函数级延迟导入（deferred import）直接转交flashinfer.experimental。延迟导入保证import flashinfer永远不会加载实验性内核。

六、实战二：在稳定 API 下暴露一个实验性后端

策略 README 以"假想的 SM12x CuTe GEMM 后端挂到稳定 APImm_bf16上"为例完整演示了工作流，原始文档与 CLAUDE.md 中也包含该示例。关键约束：support 模块必须保持轻量——只包含 dtype、shape、compute-capability 逻辑，绝不导入内核或 JIT，因为核心在模块加载期就导入它以完成@backend_requirement注册：

# flashinfer/experimental/sm12x_gemm/support.py import torch from flashinfer.utils import supported_compute_capability from flashinfer.experimental import experimental_backend @experimental_backend @supported_compute_capability([120, 121]) def check_sm12x_cute(a, b, out=None, backend="auto"): return a.dtype == torch.bfloat16 and a.shape[-1] % 64 == 0

核心入口按普通后端一样注册它（只导入 checker，不导入内核）：

# flashinfer/gemm/gemm_base.py from ..experimental.sm12x_gemm.support import check_sm12x_cute # checker only @backend_requirement( backend_checks={ "cutlass": _check_cutlass, "cudnn": _check_cudnn, "sm12x_cute": check_sm12x_cute, # experimental: auto skips it unless opted in }, heuristic_func=_heuristic_mm_bf16, ) @flashinfer_api def mm_bf16(a, b, out=None, backend="auto"): if backend == "auto": backend = mm_bf16.suitable_auto_backends[0] if backend == "sm12x_cute": from ..experimental.sm12x_gemm import run # deferred import return run(a, b, out) ...

最终行为一览（这是原始文档与 README 中的核心行为表，需完整保留）：

自动调优的 API 在mm_bf16.suitable_auto_backends上做调优，因此同样的过滤在变量未设置时也将实验性后端排除在自动调优之外。

在真实仓库中，这一"核心薄入口 + 实验包实现"模式已有现成范例：flashinfer/sm110_xqa.py中的prepare与attention两个入口均以@flashinfer_experimental_api标记，函数体内仅做参数转发，并通过函数级延迟导入调用flashinfer.experimental.sm110_xqa.backend（flashinfer/sm110_xqa.py）。对应的后端 README（flashinfer/experimental/sm110_xqa/README.md）则详细记载了五类物理内核族（tcgen05、register_mma、register_mma_split、tmem、pair）的选择方式与验证命令，可作为实验功能文档完备度的参照。

七、用户契约（User Contract）

使用实验性 API 与后端意味着接受如下契约：

• 无兼容性或长期支持保证：可能不经弃用期直接变更或移除；
• 适用对象：主要面向 main 分支用户、社区容器与本地框架集成；不应在受支持的框架发行版中默认启用。一旦出现"要求默认启用或纳入支持版发布路径"的诉求，这本身就是该功能应考虑升级毕业（graduation）的信号；
• 文档要求：每个实验性功能的文档必须明确说明——是 API、后端还是两者皆实验性；支持的使用场景与限制；所需的 feature-gate；以及开启门控后该功能是否参与自动路由（dispatch、autotuning、trace-apply）；
• 打包约束（JIT-only）：实验性功能仅走 JIT 路径，不包含在flashinfer-jit-cache/flashinfer-cubin预构建包中。对应地，实验性功能在 flashinfer/aot.py 中的 AOT 注册是被禁止的——这正是"实验性内核不得进入预构建包"这一规则存在的目的；功能毕业时作为毕业步骤的一部分再注册 AOT。

八、面向贡献者：准入、评审、隔离与生命周期

策略 README（flashinfer/experimental/README.md）给出了完整的管理规范，flashinfer/experimental/CLAUDE.md是面向 Agent 的操作性摘要，根目录 CONTRIBUTING.md 中有概要。

8.1 所有权与生命周期

每个实验性功能必须拥有：

• 具名负责人（named owner）；
• 跟踪 issue：记录使用场景、进入实验路径的理由、以及带目标版本的毕业计划（例如"四周内于 0.6.xx 版本完成 API 定稿并毕业"）。

实验性 PR 的默认意图是四周内毕业。生命周期评审按此节奏进行：要么继续孵化、要么按正常稳定流程毕业、要么被移除。继续孵化不是自动的——每次评审负责人必须说明为何仍处实验期、给出活跃使用或进展的证据、列出剩余毕业阻碍，且扩展需维护者批准；重复相同理由而无实质进展是不够的。测试损坏、失去负责人、或缺乏实质使用，都是无需稳定弃用保证即可移除的充分理由。

8.2 准入标准（Admission Criteria）

实验轨道存在的目的就是容纳三类快节奏工作：

• 客户端 GPU 内核与后端（如 SM12x）；
• 最新模型的新算子：功能性支持可以先于稳定 API 落地；
• 针对特定问题规模的高度特化内核：以实验性后端形式挂到既有稳定 API 之后，而非新增 API。

其他类别经维护者批准也可准入。功能需要文件化的理由，例如：新的算子族或算法；实质不同的 API 契约；新的编译器、后端或架构特化实现路径；FlashInfer 尚未承诺维护的用例。注意：不应为既有稳定 API 的参数空间扩展而新建实验性 API；实验性后端可以在引入实质性新实现路径时实现既有稳定 API。

8.3 测试与评审要求

每个实验性功能必须包含：

• 对照参考实现的正确性测试；
• 至少一个代表性支持的配置；
• 在目标硬件上的验证；
• 一个可运行示例。

测试位于tests/experimental/并运行在独立的 CI 通道；修改该功能的 PR 必须通过相应测试。准入阶段不要求广泛的移植性、全面的性能覆盖与长期可维护性。

对flashinfer/experimental/的改动走较窄的评审（聚焦资格、正确性、隔离性、明显安全/可维护性风险）；对核心（含薄入口）的改动走正常核心评审流程，评审者需验证集成是显式的、默认情况下稳定行为不变、后端特有逻辑未泄漏进核心。PR 通过勾选 PR 模板中的Experimental Track复选框声明实验性并链接跟踪 issue，维护者添加experimental标签；新实验性功能的跟踪 issue 与 PR 一同评审。

8.4 与稳定 API 检查清单的差异（Relaxations）

相对根目录 CLAUDE.md 的 "Adding a New Operation" 检查清单：

8.5 隔离机制：稳定测试与检查永不因实验代码失败

• tests/experimental/通过 pytest.ini 中的norecursedirs从pytest tests/（稳定通道）排除；实验测试只在独立通道中显式运行，命令为pytest tests/experimental/。pytest.ini中该排除是路径锚定的（norecursedirs = test_helpers tests/experimental），避免误伤其他同名目录；
• Trace 注册表工具（tests/trace/）与 scripts/pr_checks/ 按字面名匹配@flashinfer_api；@flashinfer_experimental_api函数被排除在稳定 trace 一致性测试、docstring 与 API/RST 覆盖检查之外；
• 毕业前，实验性 API 不列入docs/api/*.rst（否则 API/RST 检查会将其报告为 stale）。

8.6 包含规则（Containment Rules）

• 核心不得在模块级导入flashinfer.experimental，唯一例外是定义@experimental_backendchecker 的轻量 support 模块（供@backend_requirement注册）；内核、JIT 规范与重依赖只能通过受认可薄入口内的延迟（函数级）导入访问；
• flashinfer/__init__.py不得急切导入flashinfer.experimental（导入开销；实验代码可能依赖可选包）；
• flashinfer/experimental/下的代码可以自由从核心导入；
• 面向稳定、可自动调优 API 的实验性后端，必须保证实验功能开启期间捕获的实验性 tactic 不会干扰关闭实验功能的场景：包含实验性 tactic 的 autotune 缓存与trace_apply配置必须能被加载器安全跳过（回退到稳定 tactic），无论是FLASHINFER_ALLOW_EXPERIMENTAL_AUTO_BACKENDS未设置，还是功能已被移除。

九、毕业（Graduation）检查清单与移除路径

要把一个功能升级为稳定，按策略 README 的清单执行：

1. 定稿 API 契约（命名、dtype、仅关键字性能参数）；
2. 将后端代码从flashinfer/experimental/移到其稳定归属位置；若实验路径曾对用户可见，保留一个发行版的 re-export shim；
3. 将@flashinfer_experimental_api替换为@flashinfer_api，并从入口移除require_experimental调用；
4. 完成根目录 CLAUDE.md 的完整稳定 API 检查清单（trace 模板、tests/trace/example.py、文档页、顶层导出）；
5. 若功能应预编译发布，在 flashinfer/aot.py 注册；
6. 将测试从tests/experimental/移到对应稳定测试目录；
7. 关闭跟踪 issue，注明毕业的发行版本。

移除则无需弃用周期：删除后端目录、被标记的 API 与测试，并在跟踪 issue 中注明移除即可。

十、快速参考：启用实验性功能的三种决策路径

最终提醒：实验性功能没有兼容性承诺，可能不经弃用直接变更或移除；它们仅存在于 JIT 路径，不会出现在flashinfer-jit-cache/flashinfer-cubin预构建包中。生产环境请优先依赖稳定 API，将实验性能力用于前沿模型支持、新架构验证与性能探索，并在确有价值时推动其走完毕业流程。

• 大模型
• 深度学习
• 算子库
• 后端
• 高性能计算