Skip to content

Fix: Resolve parameter mismatch between TE_FL and NVTE functions#34

Merged
lxd-cumt merged 7 commits into
flagos-ai:mainfrom
lihongyang1990:fix/te_fl_nvfl_func_mismatch
Feb 10, 2026
Merged

Fix: Resolve parameter mismatch between TE_FL and NVTE functions#34
lxd-cumt merged 7 commits into
flagos-ai:mainfrom
lihongyang1990:fix/te_fl_nvfl_func_mismatch

Conversation

@lihongyang1990

@lihongyang1990 lihongyang1990 commented Feb 2, 2026

Copy link
Copy Markdown

Description

Align TE_FL backend interface signatures with the upstream NVTE (NVIDIA TransformerEngine) C++ pybind API to
resolve parameter mismatches that cause runtime failures when TE_FL dispatches operations to different backends.

Motivation

The TEFLBackendBase abstract class and its concrete implementations (FlagOS, Reference, CUDA, Hygon, Iluvatar, MetaX) had function signatures that
diverged from the NVTE pybind interface defined in transformer_engine/pytorch/csrc/extensions/pybind.cpp. This caused parameter name/type
mismatches when the plugin layer forwarded calls to vendor backends, leading to TypeError exceptions at runtime.

Changes

  1. Unified function signatures across the base class and all backends
  • generic_gemm: Renamed parameters to match NVTE pybind (transA→transa, transB→transb, output_dtype→out_dtype, workspace_size→workspaceSize,
    comm_type typed as CommOverlapType). Changed bias_type from Any to DType and return type from Any to List[Any].
  • rmsnorm_bwd: Renamed dy→dz to match NVTE convention. Removed the eps parameter from the signature (it is not passed by the NVTE caller). Made eps
    a keyword default in the FlagOS impl for backward compatibility.
  • layernorm_bwd: Renamed dy→dz to match NVTE convention.
  • rmsnorm_fwd / layernorm_fwd: Changed otype type from torch.dtype to DType enum.
  • multi_tensor_l2norm: Changed return type from Union[torch.Tensor, List[torch.Tensor]] to Tuple[torch.Tensor, torch.Tensor] to match the actual
    NVTE return convention.
  • multi_tensor_adam / multi_tensor_adam_param_remainder: Renamed eps→epsilon. Removed the "callable-when-no-args" pattern (returning the function
    itself when called with no arguments) — these methods now always execute the operation directly.
  • dropout_fwd / dropout_bwd: Made out / grad_input parameters required (non-optional) to match NVTE pybind.
  • Softmax functions: Renamed parameters (scale→scale_factor, output_grad→output_grad_, softmax_output→softmax_results_) to match NVTE naming.
  • get_fused_attn_backend: Replaced *args, **kwargs with explicit typed parameters matching the NVTE pybind signature.
  • multi_tensor_unscale_l2norm: Renamed scale→inv_scale for clarity.
  1. Added explicit signatures to previously stub-only methods in TEFLBackendBase
  • moe_permute_fwd, moe_permute_bwd, moe_unpermute_fwd, moe_unpermute_bwd
  • te_general_grouped_gemm, fp8_transpose, swap_first_dims
  • fused_attn_fwd, fused_attn_bwd, fa_prepare_fwd, fa_prepare_bwd
  • compute_amax, fused_amax_and_scale_update_after_reduction
  • fp8_block_scaling_compute_partial_amax, fp8_block_scaling_partial_cast
  • fused_multi_row_padding, fused_multi_row_unpadding
  • rmsnorm_bwd_add — replaced *args, **kwargs with explicit parameters
  1. Added DType enum conversion in the reference backend
  • Introduced _DTYPE_TO_TORCH_DTYPE mapping and _to_torch_dtype() helper in reference/impl/normalization.py to convert DType enum values to
    torch.dtype before computation.
  1. Cleaned up wrapper classes in ops.py
  • FP8TensorMeta, CommOverlapHelper, CommOverlap, CommOverlapP2P now use new to route construction through the backend manager instead of
    raising NotImplementedError or holding dummy state.
  • Removed FusedAdamCUDAKernel and FusedSGDCUDAKernel stubs.
  1. Removed dead reference backend stubs
  • Removed ~30 raise NotImplementedError stub methods from ReferenceBackend and their corresponding OpImpl registrations in register_ops.py for
    operations that the reference backend cannot implement (NVSHMEM, THD, FP8, RoPE, MOE aux loss, etc.).
  1. Fixed FusedAdam optimizer call pattern
  • In fused_adam.py, changed self.multi_tensor_adam() (calling the method to get the function) to self.multi_tensor_adam (using the method
    directly), matching the new non-callable-return interface.
  1. Propagated rmsnorm_bwd signature change to PyTorch modules
  • Removed ctx.eps from layernorm_linear.py backward pass.
  • Removed self.eps from rmsnorm.py op_backward.
  1. Applied the same signature alignment to all vendor backends
  • CUDA, Hygon, Iluvatar, MetaX, and KunlunXin backends updated to match the new TEFLBackendBase signatures.
  1. Updated tests
  • test_normalization.py: Use DType.kFloat32 instead of torch.float32 for norm forward/backward calls. Removed eps from rmsnorm_bwd test calls.

  • test_operations.py: Use DType.kFloat32 for GEMM and pass explicit None for dropout optional params.

  • test_optimizer.py: Renamed eps→epsilon in multi_tensor_adam test. Added comprehensive multi_tensor_adam_param_remainder tests with
    FP32↔BF16+int16 split/reconstruct verification.

  • Documentation change (change only to the documentation, either a fix or a new content)

  • Bug fix (non-breaking change which fixes an issue)

  • New feature (non-breaking change which adds functionality)

  • Breaking change (fix or feature that would cause existing functionality to not work as expected)

  • Infra/Build change

  • Code refactoring

Changes

Please list the changes introduced in this PR:

  • Change A
  • Change B

Checklist:

  • I have read and followed the contributing guidelines
  • The functionality is complete
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes

@lihongyang1990 lihongyang1990 force-pushed the fix/te_fl_nvfl_func_mismatch branch from 045cfd6 to 06d0554 Compare February 5, 2026 16:48
# Write back
flag_gems.copy_(p, param_bf16)
flag_gems.copy_(p_remainder, remainder_int16)
p.view(torch.int16).copy_(new_p)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

use flag_gems to replace torch?

# Write back
p.view(torch.int16).copy_(new_p)
p_remainder.copy_(new_p_rem)
flag_gems.copy_(p, new_p.view(torch.bfloat16))

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

int16 or bfloat16?

@zhaoyinglia zhaoyinglia left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please keep only the changes relevant to the PR description. Move unrelated changes to a new PR.

@lihongyang1990

Copy link
Copy Markdown
Author

Remove optimizer changes for single-purpose PR

@lxd-cumt lxd-cumt left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Based on this PR, locally verified the qwen3, deepseek_v3, and aquila models, and they can train correctly.

@zhaoyinglia zhaoyinglia left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@lxd-cumt lxd-cumt merged commit 12b2077 into flagos-ai:main Feb 10, 2026
4 of 11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants