Skip to content

Add Transformer constructor knobs to omit the token embedding and output head - #284

Draft
amazloumi wants to merge 3 commits into
mainfrom
feat/transformer-embedding-head-knobs
Draft

amazloumi wants to merge 3 commits into
mainfrom
feat/transformer-embedding-head-knobs

Conversation

@amazloumi

Copy link
Copy Markdown
Member

Summary

  • Add keyword-only constructor parameters include_token_embedding and include_output_head (default True) to Transformer. When False the module is never built and its state-dict keys never exist, for wrappers that embed inputs externally or consume hidden states.
  • tie_embeddings=True with either module omitted raises at construction. forward with tokens and no embedding raises before any compute and points at modality.inputs_embeds. Without a head, forward returns hidden states.
  • generate() and apply_tensor_parallel reject a model built with either module omitted, before any cache allocation or mesh access. Pipeline stage modules are unaffected.
  • Defaults are bit-exact: construction order, initial weights, state-dict keys and outputs are unchanged. No TOML field.
  • Document the knobs in docs/architecture/model.md.

Testing

  • uv run ruff check and uv run ruff format --check pass on the touched files
  • uv run pyright kempnerforge/ passes (0 errors)
  • uv run pytest tests/unit/: 2277 passed, 3 skipped
  • New tests: each omission combination against a full model fed the same inputs, exact state-dict key sets, tie rejection, and the early guards in forward, generate() and tensor parallelism; seeded mutations of each guard are caught
  • Default builds fingerprint-identical to main (state dict, construction RNG, forward) for dense, tied, GQA with qk_norm, and MoE configs
  • Re-verified against the codebase design doc: a general model knob through the existing constructor seam

Closes #263

amazloumi and others added 2 commits October 15, 2026 17:16
With either knob False the module is None from construction and its
state-dict keys never exist, so wrappers that embed tokens externally or
consume hidden states directly no longer build modules they discard.
tie_embeddings=True with either omitted raises ValueError, forward with
tokens and no embedding points at modality.inputs_embeds, and a missing
head returns hidden states. Defaults are unchanged.

refs #263

Co-Authored-By: Timothy Ngotiaoco <timothy_ngotiaoco@harvard.edu>
generate() sampled hidden states as logits when the output head was
omitted, and with the embedding omitted it failed only after switching
to eval mode and allocating the KV caches. It now raises a ValueError
for either omitted module before doing either.

With the embedding omitted, tensor parallelism lost its Replicate input
hook while SequenceParallel stayed on, so inputs_embeds would be labeled
Shard(1). apply_tensor_parallel now raises a ValueError for a Transformer
built without either module, before touching the mesh or the model.
Pipeline stages, which hold only some modules, are accepted as before.

refs #263

Co-Authored-By: Timothy Ngotiaoco <timothy_ngotiaoco@harvard.edu>
@amazloumi amazloumi added the core Affecting core label Oct 15, 2026
@codecov

codecov Bot commented Oct 15, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines Coverage Δ
kempnerforge/distributed/tensor_parallel.py 57.35% <100.00%> (+11.32%) ⬆️
kempnerforge/model/generate.py 98.14% <100.00%> (+0.14%) ⬆️
kempnerforge/model/transformer.py 95.43% <100.00%> (+0.58%) ⬆️
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@amazloumi
amazloumi marked this pull request as draft October 16, 2026 14:38
@amazloumi
amazloumi requested a review from Naeemkh October 21, 2026 15:51
…dding-head-knobs

# Conflicts:
#	CHANGELOG.md

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

core Affecting core

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Transformer constructor knobs to omit the token embedding and output head

1 participant