Skip to content

Avoid re-gathering vocab tiling output head in backward - #4720

Draft
huytransformer wants to merge 1 commit into
mainfrom
htn-vocab-tiling-context-gather
Draft

Avoid re-gathering vocab tiling output head in backward#4720
huytransformer wants to merge 1 commit into
mainfrom
htn-vocab-tiling-context-gather

Conversation

@huytransformer

Copy link
Copy Markdown
Collaborator

Description

Start with a short description of what the PR does and how this is a change from
the past.

The rest of the description includes relevant details and context, examples:

  • why is this change being made,
  • the problem being solved and any relevant context,
  • why this is a good solution,
  • some information about the specific implementation,
  • shortcomings of the solution and possible future improvements.

If the change fixes a bug or a Github issue, please include a link, e.g.,:
FIXES: b/123456
FIXES: #123456

You can also provide a comma-separated list. If you don't want to close a bug but
simply to reference it, use BUGS, e.g.:
BUGS: b/123456

Notice 1: Once all tests pass, the "pull ready" label will automatically be assigned.
This label is used for administrative purposes. Please do not add it manually.

Notice 2: For external contributions, our settings currently require an approval from a MaxText maintainer to trigger CI tests.

Tests

Please describe how you tested this change, and include any instructions and/or
commands to reproduce.

Checklist

Before submitting this PR, please make sure (put X in square brackets):

  • I have performed a self-review of my code. For an optional AI review, add the gemini-review label.
  • I have necessary comments in my code, particularly in hard-to-understand areas.
  • I have run end-to-end tests tests and provided workload links above if applicable.
  • I have made or will make corresponding changes to the doc if needed, including adding new documentation pages to the relevant Table of Contents (toctree directive) as explained in our documentation.

@gemini-code-assist

Copy link
Copy Markdown

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

@codecov

codecov Bot commented Aug 4, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@github-actions

github-actions Bot commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

🤖 Hi @huytransformer, I've received your request, and I'm working on it now! You can track my progress in the logs for more details.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

## 📋 Review Summary

This Pull Request introduces a high-impact optimization for vocabulary tiling in the NNX path. By gathering the output head parameters over both FSDP and context axes before entering the custom_vjp boundary, the backward pass can reuse the already-gathered table instead of re-gathering it for every single chunk, significantly reducing communication overhead.

🔍 General Feedback

  • Excellent Performance Enhancement: Moving the all-gather operation outside the custom_vjp and including the "context" axis prevents redundant communication during both forward and backward passes. This is a very clean and highly elegant JAX SPMD design pattern.
  • Import Ordering: For long-term maintainability and codebase cleanliness, consider sorting the imported symbols from maxtext.utils.sharding alphabetically at the top of the file.
  • Syntactic Correctness: The replacement of all_gather_over_fsdp with get_physical_spec_without_axes and maybe_shard_with_name is implemented with correct parameter arguments and aligns perfectly with existing vocabulary tiling patterns.

# all gather the output head over fsdp and context; doing it before the
# custom_vjp lets the backward reuse the gathered table instead of
# re-gathering it for every chunk
head_physical_spec = get_physical_spec_without_axes(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 **Testing Coverage:** While the legacy Linen path (`VocabTilingTest`) includes a `test_vocab_tiling_gradient_context_parallelism` test case, there is currently no equivalent test for context parallelism in the new NNX path (`VocabTilingNNXTest`).

To ensure the new context gathering logic on the NNX path is fully covered and to prevent future regressions, consider adding an equivalent context parallelism test (e.g., test_nnx_vocab_tiling_gradient_context_parallelism) in tests/unit/tiling_test.py.

@huytransformer
huytransformer force-pushed the htn-vocab-tiling-context-gather branch from ecacf08 to 3518faa Compare August 4, 2026 04:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant