Skip to content

[Backend 9] refactor(objectives): pass the attention backend and SP groups at construction - #1212

Draft
maocheng23 wants to merge 5 commits into
maocheng/backend-08-declarationsfrom
maocheng/backend-09-construction
Draft

maocheng23 wants to merge 5 commits into
maocheng/backend-08-declarationsfrom
maocheng/backend-09-construction

Conversation

@maocheng23

@maocheng23 maocheng23 commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Motivation

Next step of the training-backend design (#1177), stacked on the declarations PR. build_bundle constructed the objective model and then assigned to it: runtime.attention_backend, and under USP ring_group, ulysses_group and reduce_sequence_statistics, which configure_sequence_parallel(runtime) read from the getters of specforge.distributed. The EAGLE3 protocol read all four with getattr(runtime, name, None). So the same model class trained with or without its sequence-parallel groups depending on who built it, and nothing failed when they were missing. The design passes the one handle that may cross into a program, the process groups of a declared model-parallel axis, at construction.

Change

Part Before After
build_objective_model, ObjectiveModel — take attention_backend= and sequence_parallel=; both are fixed for the model's lifetime
training/sequence_parallel.py configure_sequence_parallel(runtime) assigned three attributes SequenceParallel(ring_group, ulysses_group, sequence_group) is the value: three process groups, none of which may be missing, and it reduces loss statistics over the third itself; sequence_parallel_groups() reads the process's groups once
build_bundle built, then assigned resolves the groups first and passes them to the constructor
EAGLE3 protocol four getattr(runtime, ..., None) runtime.attention_backend, runtime.sequence_parallel

The getters themselves (specforge.distributed) are still process-global; replacing them with a Topology value is the design's step 4 and is not part of this PR.

Behaviour-change ledger

# What Before After Kind
1 Training numerics of every model build_bundle builds — identical on the recorded trajectories (see Evidence and Not verified) unchanged
2 runtime.attention_backend = ... after construction changed the rollout the next forward used still an assignable attribute, but no code path assigns it tests updated to pass it at construction
3 configure_sequence_parallel importable removed internal API
4 build_objective_model(attention_backend=..., sequence_parallel=...) with a backend or an axis the protocol does not declare not expressible: the attributes were assigned after construction and P-EAGLE ignored them ValueError new refusal; the CLI already refused it
5 A SequenceParallel without one of its three groups, however it is built a reducer bound to no group, which is the world ValueError new refusal
6 build_objective_model with the USP backend and no groups, or with groups and D-PACE weighting the first failed at the first cached attention step; the second trained with weights normalized per shard ValueError at construction earlier failure; new refusal that the CLI already had
7 Assigning runtime.reduce_sequence_statistics after construction read by the EAGLE3 protocol not read; pass sequence_parallel= callers have to use the constructor

Evidence

  • Recorded trajectories: 90 cases, 0 differences against main. They cover EAGLE3 and P-EAGLE with the default attention backend; they do not reach the cached rollout or USP.
  • Full CPU suite: 1,988 passed; the failure set (15 failed, 1 error, all environmental on this machine) is identical to main's.
  • New tests (test_eagle_backends.py): the rollout receives the groups the model was built with, and none by default; sequence_parallel_groups() binds the draft's sequence group into the reduction. The existing tests of Flex routing through the cached rollout and of trimming under a cross-rank reduction now pass their backend and reducer at construction.

Not verified

  • USP end to end: it needs flash_attn and GPUs. tests/test_algorithms/helpers/check_eagle_usp.py (a multi-GPU helper) and load_eagle3 in the runtime fixtures are updated and compile; they were not run. The change on that path is three assignments becoming three constructor arguments.
  • CUDA: not run.

After Codex review

One read-only Codex round (maocheng/backend-08-declarations...HEAD): no P0 or P1; it traced all six backend selections with and without groups to the same values at new_rollout, cached.step and reduce_statistics. Fixed in a follow-up commit:

  • P2 the builder checks the two new arguments against the protocol's declarations (ledger row 4); sequence_parallel_groups() refuses missing groups (row 5).
  • P2 the handoff inside build_bundle was not covered: removing it left the tests green. A test now builds a USP configuration up to the objective model's construction and checks what arrives; it fails with the handoff removed.
  • P3 the test of the getters asserts each is read once.

Second Codex round

A second read-only round on the fixes above: the four first-round findings confirmed fixed and no CLI configuration newly refused. Fixed in a further commit:

  • P1 the builder accepted D-PACE weighting together with sequence parallelism, which the CLI refuses (ledger row 6).
  • P2 SequenceParallel carried a reducer the caller had bound to a group; it now carries the group and binds the reduction itself, so no callable crosses into the objective model and a missing group is refused however the value is built (row 5). The USP backend without groups is refused at construction (row 6).

Not changed: groups together with a local attention backend are still accepted. No data path builds sequence shards without the USP backend, and that combination is how the rule "trimming is skipped when statistics cross ranks" is tested on CPU.

🤖 Generated with Claude Code

maocheng23 and others added 5 commits November 18, 2026 14:29
…struction

build_bundle built the objective model and then set attributes on it:
attention_backend, and under USP ring_group, ulysses_group and
reduce_sequence_statistics, the last three read from process-global
getters by configure_sequence_parallel. The EAGLE3 protocol read all four
with getattr defaults, so a model built another way silently trained
without them.

- build_objective_model and ObjectiveModel take attention_backend= and
  sequence_parallel=; both are fixed for the model's lifetime.
- training/sequence_parallel.py: SequenceParallel is the value that
  carries the axis's process groups; sequence_parallel_groups() reads them
  once. configure_sequence_parallel is removed.
- The EAGLE3 protocol reads runtime.attention_backend and
  runtime.sequence_parallel.

Recorded training trajectories are bit-identical to main (90 cases); the
USP path needs flash_attn and GPUs and is not covered by them.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…-09-construction

# Conflicts:
#	specforge/algorithms/objectives/base.py
#	specforge/algorithms/objectives/registry.py
#	specforge/training/canonical.py
Review findings on the construction change:

- build_objective_model checks attention_backend= against the protocol's
  attention_backends and sequence_parallel= against
  supports_sequence_parallel. P-EAGLE accepted a USP request it ignored;
  the CLI already refused it.
- sequence_parallel_groups() refuses a process without the three groups:
  a statistic reduced over no group is pooled over the world.
- Tests: the handoff in build_bundle is checked on a USP configuration
  up to the objective model's construction (it failed to be covered
  before); each getter is asserted to be read once.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Second review round on the construction change:

- SequenceParallel carries the product group (the ranks that share one
  sequence) in place of a caller-built reducer, refuses a missing group
  however it is constructed, and reduces loss statistics over that group
  itself. A callable no longer crosses into the objective model.
- build_objective_model refuses what the CLI refuses: D-PACE weighting
  with sequence parallelism (chain weights are normalized within a
  shard), and the USP backend without its groups, which used to fail at
  the first cached attention step.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

This branch has not been deployed

No deployments
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.

1 participant