Skip to content

Align M3 ColBERT vectors and masks across variable-length sub-batches - #1636

Open
Afloat16 wants to merge 1 commit into
FlagOpen:masterfrom
Afloat16:fix/m3-variable-subbatch-lengths-20261112
Open

Afloat16 wants to merge 1 commit into
FlagOpen:masterfrom
Afloat16:fix/m3-variable-subbatch-lengths-20261112

Conversation

@Afloat16

Copy link
Copy Markdown

Problem

Both embedder collators can dynamically pad each sub-batch to a different sequence length. M3's list-input encoding path directly concatenates the ColBERT vectors along the batch dimension, so unified fine-tuning raises a tensor-size mismatch when those sequence lengths differ. This prevents the documented sub-batch option from working on ordinary variable-length training text.

Changes

Pad the ColBERT vectors to the longest sub-batch sequence before concatenation, using the tokenizer's padding side and zero vectors for padding. Build the corresponding list-input attention mask in the same order: remove each sub-batch's first position, as ColBERT encoding already does, then pad. A leading column preserves the existing full-mask scoring interface.

Dense-only encoding and the tensor-input sub-batch path are unchanged.

Validation

Added 20 tests with an actual local BertTokenizerFast, tiny BERT backbone, sparse/ColBERT heads, and both native collators:

  • Dynamic sub-batch embeddings match the existing full-batch path with right padding.
  • Supervised, teacher-distillation, and self-distillation training match full-batch losses and all parameter gradients.
  • Left/right padding preserves each original vector and aligns every mask value with it, with zero vectors and zero masks in added positions.
  • Dense-only and fixed-length tensor sub-batches retain their previous behavior.

The unchanged upstream base produces 14 failed, 6 passed. With the fix, the new tests and existing Trainer/import checks produce 28 passed, 1 skipped. Ruff on the new test module and git diff --check pass.

The tests preserve the existing first-position removal convention and do not claim to redefine left-padded special-token handling. This change is separate from passage MaxSim masking in #1610; it does not change that scoring reduction.

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