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}