Skip to content

perf(tree_attn): Add lazy attention mask creation for tree training#872

Merged
garrett4wade merged 3 commits into
mainfrom
mzy/tree-lazy-attnmask
Feb 2, 2026
Merged

perf(tree_attn): Add lazy attention mask creation for tree training#872
garrett4wade merged 3 commits into
mainfrom
mzy/tree-lazy-attnmask

Conversation

@nuzant

@nuzant nuzant commented Feb 1, 2026

Copy link
Copy Markdown
Collaborator

Description

Changes:

  • Defer block mask creation from batch packing time to forward pass to reduce peak memory usage
  • Add build_block_mask_from_trie() function to lazily build block masks from trie nodes just before
    the forward pass
  • Update FSDP and Megatron engines to create and release block masks around forward calls

Previously, block masks were created during build_packed_tree_batch() and stored in memory until the
forward pass. This caused unnecessary peak memory usage as all block masks for all micro-batches were
held simultaneously.

With this change:

  1. build_packed_tree_batch() stores the trie_node instead of block_mask in micro-batch data
  2. Engines call build_block_mask_from_trie() just before each forward pass
  3. Block masks are immediately released after each forward pass

This reduces peak memory footprint for tree training, especially beneficial for large batch sizes or
long sequences.

Related Issue

Fixes #(issue)

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not
    work as expected)
  • Documentation update
  • Code refactoring (no functional changes)
  • Performance improvement
  • Test coverage improvement

Checklist

  • I have read the Contributing Guide
  • I have run formatting tools (pre-commit or manual)
  • I have run relevant unit tests and they pass
  • I have added tests for new functionality
  • I have updated documentation if needed
  • My branch is up to date with main
  • This PR introduces breaking changes (if yes, fill out details below)
  • If this PR changes documentation, I have built and previewed it locally with
    jb build docs
  • No critical issues raised by AI reviewers (/gemini review)

Breaking Change Details (if applicable):

Additional Context


Need help? Check the Contributing Guide or ask in
GitHub Discussions!

@gemini-code-assist

Copy link
Copy Markdown
Contributor

Summary of Changes

Hello @nuzant, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request implements a performance improvement by optimizing memory usage during tree training, particularly concerning attention masks. By shifting the creation of block masks from an eager, batch-level process to a lazy, per-forward-pass approach, the system avoids holding all block masks in memory simultaneously. This change is crucial for scaling to larger models and datasets by mitigating peak memory consumption without altering the core functionality of tree attention.

Highlights

  • Memory Optimization: Block mask creation for tree training is now deferred from the batch packing phase to just before the forward pass, significantly reducing peak memory usage, especially for large batch sizes or long sequences.
  • New Functionality: A new function, build_block_mask_from_trie(), has been introduced to lazily construct block masks from trie nodes as needed.
  • Engine Updates: Both FSDP and Megatron engines have been updated to utilize this lazy block mask creation, calling build_block_mask_from_trie() before each forward pass and releasing the mask immediately afterward.
  • Data Structure Change: The build_packed_tree_batch() function now stores the trie_node directly in micro-batch data instead of the pre-computed block_mask.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

@gemini-code-assist gemini-code-assist 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.

Code Review

This pull request introduces a performance optimization for tree attention training by deferring the creation of block masks to the forward pass. This change reduces peak memory usage, which is particularly beneficial for large batch sizes or long sequences.

The implementation is solid:

  • The build_packed_tree_batch function is updated to no longer create the block_mask, instead storing the trie_node.
  • A new function build_block_mask_from_trie is added to lazily create the block mask.
  • Both FSDP and Megatron engines are updated to call this new function just before the forward pass and release the mask's memory immediately after.
  • The necessary data plumbing (padded_to_length in MicroBatchItem) is also correctly implemented.

I have one suggestion to improve code consistency between the FSDP and Megatron engines. Overall, this is a great improvement.

Comment thread areal/engine/fsdp_engine.py Outdated
@nuzant nuzant added safe-to-test Ready to run unit-tests in a PR. and removed safe-to-test Ready to run unit-tests in a PR. labels Feb 1, 2026
@nuzant nuzant temporarily deployed to AReaL-unittests February 1, 2026 13:43 — with GitHub Actions Inactive
Comment thread areal/models/tree_attn/tree.py Outdated
@garrett4wade garrett4wade merged commit c5c138e into main Feb 2, 2026
1 check passed
@garrett4wade garrett4wade deleted the mzy/tree-lazy-attnmask branch February 2, 2026 05:59
leandermaben pushed a commit to leandermaben/AReaL that referenced this pull request Mar 24, 2026
…real-project#872)

* lazy attn mask for tree training

* Raise error for padded_size.
SathyaGnanakumar pushed a commit to danielkiely/AReaL that referenced this pull request Apr 29, 2026
…real-project#872)

* lazy attn mask for tree training

* Raise error for padded_size.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

safe-to-test Ready to run unit-tests in a PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants