Skip to main content

hyprstream_inference/training/
pipeline.rs

1//! Pipeline-split (2b) **training** orchestration for TTT-on-split (#316).
2//!
3//! This is the training counterpart to the inference `forward_layers` pipeline
4//! (#314): it drives a TTT/training forward across a set of per-device *stage*
5//! models, building a single autograd graph over the
6//! [`crate::runtime::device_pool::LayerDeviceMap`] so that `loss.backward()`
7//! traverses the same partition inference uses (M-TRAIN-COUPLING). The only
8//! cross-device copies are the stage-boundary `hidden.to_device(next)` transfers
9//! inside each stage's `forward_layers_train`, which tch makes
10//! autograd-transparent — gradients flow back across device boundaries to each
11//! parameter's own device.
12//!
13//! # Stage contract (mirrors the inference pipeline)
14//! Stages are contiguous global layer ranges `[a..b)` derived from the device
15//! map. The first stage owns `embed_tokens`, the last stage owns the final norm
16//! and LM head:
17//! - **stage 0** : `embed_tokens` → `forward_layers_train(0..b)`
18//! - **middle**  : `forward_layers_train(a..b)`
19//! - **last**    : `forward_layers_train(a..N)` → `apply_final_norm` → `lm_head`
20//!
21//! Each stage's training runner uses **no KV cache, full causal attention,
22//! `start_pos = 0`, and fresh call-local recurrent (SSM) state** — see
23//! [`crate::runtime::architectures::ModelOperations::forward_layers_train`].
24//!
25//! # Send / !Send
26//! Like the inference pipeline, the stage models hold `!Send` tch tensors and
27//! must all live on the **one** engine-owning thread; this module never crosses a
28//! thread boundary. Multi-device-on-one-thread is fine (libtorch `DeviceGuard`).
29//! The single-stage case (`stages.len() == 1` over a single-device map) is the
30//! unsplit fast path and is byte-identical to whole-model training.
31
32use anyhow::{anyhow, Result};
33use tch::Tensor;
34
35use super::tenant_delta::TenantDelta;
36use crate::runtime::architectures::ModelOperations;
37use crate::runtime::device_pool::LayerDeviceMap;
38
39/// A single pipeline stage: the stage model plus the global layer range it owns.
40///
41/// `range` is in **global** layer indices `[a..b)`; the stage model remaps to its
42/// local `self.layers` via the `layer_offset` it was constructed with. Built from
43/// `stage_from_weights_with_config` (#314).
44pub struct TrainStage<'a> {
45    /// The stage's model (owns embeddings iff `range.start == 0`; owns final
46    /// norm + LM head iff `range.end == num_layers`).
47    pub model: &'a dyn ModelOperations,
48    /// Global layer range this stage owns.
49    pub range: std::ops::Range<usize>,
50}
51
52/// Derive contiguous stage ranges from a [`LayerDeviceMap`].
53///
54/// Each maximal run of consecutive layers mapped to the same device becomes one
55/// stage `[a..b)`. A single-device map yields exactly one stage `0..N`.
56#[must_use]
57pub fn stage_ranges(map: &LayerDeviceMap) -> Vec<std::ops::Range<usize>> {
58    let n = map.len();
59    let mut ranges = Vec::new();
60    if n == 0 {
61        return ranges;
62    }
63    let mut start = 0usize;
64    let mut prev = map.device_for(0);
65    for g in 1..n {
66        let dev = map.device_for(g);
67        if dev != prev {
68            ranges.push(start..g);
69            start = g;
70            prev = dev;
71        }
72    }
73    ranges.push(start..n);
74    ranges
75}
76
77/// Run the TTT/training forward across pipeline stages and return logits with the
78/// autograd graph intact across device boundaries.
79///
80/// `input_ids` is `[batch, seq]` and must already live on the first stage's
81/// device. Stages must be contiguous, gap-free, and cover `0..num_layers` in
82/// order (validated). The caller is responsible for wrapping this in
83/// `tch::with_grad` and computing/backpropagating the loss.
84pub fn forward_train_pipeline(
85    stages: &[TrainStage<'_>],
86    input_ids: &Tensor,
87    delta: Option<&TenantDelta>,
88) -> Result<Tensor> {
89    if stages.is_empty() {
90        return Err(anyhow!("forward_train_pipeline: no stages provided"));
91    }
92    // Validate contiguity and full coverage (the first stage must start at 0;
93    // each subsequent stage must start where the previous ended).
94    if stages[0].range.start != 0 {
95        return Err(anyhow!(
96            "forward_train_pipeline: first stage must start at layer 0 (got {:?})",
97            stages[0].range
98        ));
99    }
100    for w in stages.windows(2) {
101        if w[0].range.end != w[1].range.start {
102            return Err(anyhow!(
103                "forward_train_pipeline: stages must be contiguous ({:?} then {:?})",
104                w[0].range,
105                w[1].range
106            ));
107        }
108    }
109
110    let first = &stages[0];
111    // Stage 0 owns the embedding; subsequent stages consume the prior hidden.
112    let mut hidden = first.model.embed_tokens(input_ids)?;
113    hidden = first
114        .model
115        .forward_layers_train(&hidden, first.range.clone(), delta)?;
116
117    for stage in &stages[1..] {
118        hidden = stage
119            .model
120            .forward_layers_train(&hidden, stage.range.clone(), delta)?;
121    }
122
123    // The last stage owns the final norm + LM head.
124    let last = stages
125        .last()
126        .ok_or_else(|| anyhow!("forward_train_pipeline: missing last stage"))?;
127    hidden = last.model.apply_final_norm(&hidden)?;
128    last.model.lm_head(&hidden)
129}
130
131/// Compute the next-token-prediction (NTP) cross-entropy loss for a TTT step over
132/// a pipeline split, with the autograd graph intact across device boundaries.
133///
134/// Mirrors `TestTimeTrainer::compute_ntp_loss_with_delta` (the single-device
135/// path) but drives the forward across `stages`. The returned loss tensor's
136/// backward pass materializes gradients on each parameter's own device.
137///
138/// `input_ids` is `[1, seq]` on the first stage's device; the loss is computed on
139/// that same device (the last stage's logits are produced on the last stage's
140/// device, and the shifted targets are taken from `input_ids`, moved to the
141/// logits' device).
142pub fn compute_ntp_loss_split(
143    stages: &[TrainStage<'_>],
144    input_ids: &Tensor,
145    delta: Option<&TenantDelta>,
146) -> Result<Tensor> {
147    tch::with_grad(|| {
148        let logits = forward_train_pipeline(stages, input_ids, delta)?;
149
150        let seq_len = input_ids.size()[1];
151        if seq_len < 2 {
152            return Err(anyhow!(
153                "compute_ntp_loss_split: need at least 2 tokens for NTP loss (got {seq_len})"
154            ));
155        }
156        let vocab_size = logits.size()[2];
157
158        // Shift for next-token prediction. Targets live on `input_ids`' device;
159        // move them to the logits' device (the last stage's) for cross_entropy.
160        let pred_logits = logits.narrow(1, 0, seq_len - 1).reshape([-1, vocab_size]);
161        let target_ids = input_ids
162            .narrow(1, 1, seq_len - 1)
163            .reshape([-1])
164            .to_device(pred_logits.device());
165
166        let loss = pred_logits.cross_entropy_loss::<Tensor>(
167            &target_ids,
168            None,
169            tch::Reduction::Mean,
170            -100,
171            0.0,
172        );
173        Ok(loss)
174    })
175}
176
177#[cfg(test)]
178#[allow(clippy::unwrap_used, clippy::expect_used)]
179mod tests {
180    use super::*;
181    use tch::Device;
182
183    #[test]
184    fn stage_ranges_single_device_is_one_stage() {
185        let map = LayerDeviceMap::single(Device::Cpu, 4).expect("map");
186        assert_eq!(stage_ranges(&map), vec![0..4]);
187    }
188
189    #[test]
190    fn stage_ranges_two_device_split() {
191        let map = LayerDeviceMap::from_per_layer(vec![
192            Device::Cpu,
193            Device::Cpu,
194            Device::Cuda(0),
195            Device::Cuda(0),
196        ])
197        .expect("map");
198        assert_eq!(stage_ranges(&map), vec![0..2, 2..4]);
199    }
200
201    #[test]
202    fn stage_ranges_three_stages() {
203        let map = LayerDeviceMap::from_per_layer(vec![
204            Device::Cpu,
205            Device::Cuda(0),
206            Device::Cuda(0),
207            Device::Cuda(1),
208        ])
209        .expect("map");
210        assert_eq!(stage_ranges(&map), vec![0..1, 1..3, 3..4]);
211    }
212}