python_api.md

Python API 参考

Python API 适用于能够控制训练入口和模型模块导入顺序的集成方式。常规多进程训练优先使用 turbo-physai run，由 Runner 在每个训练进程中应用优化并准备 RuntimeConfig。

算子接口

算子接口统一通过 turbo_physai.operators 调用，例如：

from turbo_physai.operators import grid_sample

output = grid_sample(input, grid, align_corners=False)

当前公开接口包括：

• grid_sample、interpolate；
• modulated_deform_conv2d、ModulatedDeformConv2dFunction；
• deformable_aggregation_function、DeformableAggregationFunction；
• ms_deform_attn_forward、ms_deform_attn_backward；
• bev_pool、bev_pool_prepare、bev_pool_prepare_geometry；
• voxelize、dynamic_voxelize、hard_voxelize、dynamic_scatter；
• get_indice_pairs、indice_conv、indice_maxpool。

仅导入 turbo_physai.operators 不会加载算子依赖；首次访问具体接口时才加载对应实现。原生扩展 turbo_physai._C 供内部封装使用。

turbo_physai.apply()

apply() 加载一份 OptimizationConfig，检查其适用性，在当前 Python 进程中安装满足条件的优化，并返回本次应用报告。

turbo_physai.apply(
    *,
    optimization_config_path=None,
    model=None,
    log_report=False,
    registry=None,
    catalog=None,
    force_groups=(),
    disable_groups=(),
) -> OptimizationReport

基本用法

在导入目标模型模块前调用 apply()：

import turbo_physai

report = turbo_physai.apply(
    model="bevformer",
    log_report=True,
)

# 在 apply() 返回后导入并执行目标模型代码。

model 的可选值见模型支持清单。省略 model 和 optimization_config_path 时，组件按配置选择顺序加载默认 OptimizationConfig。

加载外部 OptimizationConfig：

import turbo_physai

report = turbo_physai.apply(
    optimization_config_path="./configs/optimization.yaml",
    log_report=True,
)

参数

参数	类型	默认值	说明
optimization_config_path	str 或 os.PathLike	None	显式 OptimizationConfig 路径；优先于 model 和其他配置来源
model	str	None	随包交付的内置模型名称；名称不区分大小写，- 按 _ 处理
log_report	bool	False	为 True 时，由 Rank 0 将完整 OptimizationReport 输出到标准日志
force_groups	字符串序列	()	临时放行指定且已启用 Group 的可放行检查；结构性错误不能放行
disable_groups	字符串序列	()	本次调用不应用指定 Group；依赖这些 Group 的其他 Group 同时跳过
registry	Registry	None	自定义优化声明注册表；主要用于外部优化包、扩展和测试
catalog	OptimizationConfigCatalog	None	自定义配置目录，用于解析 OptimizationConfig 的 extends

force_groups 和 disable_groups 接收 Group ID 序列，不能直接传入单个字符串。同一 Group 不能同时出现在两个参数中。

配置选择顺序

apply() 按以下顺序选择 OptimizationConfig：

1. optimization_config_path 指定的文件；
2. model 对应的随包配置；
3. TURBO_PHYSAI_OPTIMIZATION_CONFIG 环境变量指定的文件；
4. 当前工作目录下的 turbophysai_configs/default/optimization.yaml；
5. 随包交付的公共 OptimizationConfig。

Python API 不加载或应用 RuntimeConfig，也不负责启动训练命令。需要 RuntimeConfig 时，应使用 turbo-physai run，或由调用方在执行模型代码前自行准备运行环境。

返回值

apply() 返回 OptimizationReport。常用字段包括：

字段	说明
run_id	本次优化应用的唯一标识
optimization_config	解析后的 OptimizationConfig
prepared_execution	Group 检查结果、决策、冲突和执行顺序
execution	各 Group 及其 Replacement 的执行结果
summary	applied、skipped、blocked、failed、rolled_back 和 not_started 计数
optimization_config_path	本次实际加载的 OptimizationConfig 绝对路径
runtime_config_path	Runner 提供的 RuntimeConfig 路径；直接调用 API 且未设置时为 None

应用成功返回不等于全部 Group 均为 applied。Group 被阻断或成功回滚时，apply() 仍可返回报告。调用方可以检查 Summary：

unavailable = (
    "blocked",
    "failed",
    "rolled_back",
    "not_started",
)

if any(report.summary[name] for name in unavailable):
    raise RuntimeError("not all enabled Optimization Groups were applied")

报告结构、状态和日志格式见优化应用报告。

调用约束和异常

• 每个 Python 进程只能调用一次 apply()；调用失败后也不能在同一进程中重试。
• 应在导入目标模型模块前调用，确保模型代码通过已安装的优化入口执行。
• force_groups 只能覆盖框架明确标记为可放行的检查。
• Group 应用失败且回滚成功时，报告将该 Group 记为 rolled_back，其他独立 Group 可以继续执行。
• 回滚失败时抛出 OptimizationRollbackError，异常的 report 属性保存已生成的报告。
• 配置不存在或配置内容无效时，分别抛出 OptimizationConfigNotFoundError 或 OptimizationConfigError。