Skip to main content

qualia_core_db/inference/qwen/
native_runtime.rs

1//! Activation for a Qwen4Exp package with an NVMe-resident PLE payload.
2//!
3//! Activation reads a bounded GGUF metadata header from the external trunk on
4//! E:, opens the C: PLE cursor for row gathers, and opens the trunk either as
5//! an ordinary file cursor (`Streamed`, default) or as a read-only mmap
6//! (`Mapped`) so the OS page cache keeps trunk weights in RAM.  It never
7//! creates a swap-backed decoded copy of the model either way.
8
9use std::path::Path;
10
11use crate::gguf_sharder::{GgufHeaderError, GgufTensorIndex};
12
13use super::{
14    load_qwen4exp_native_hmc, validate_qwen4exp_graph, PleNvmeError, PleNvmeReader,
15    Qwen4ExpGraphError, Qwen4ExpNativeAssetError, Qwen4ExpNativeDescriptor, TrunkNvmeError,
16    TrunkNvmeReader,
17};
18
19#[derive(Debug)]
20pub enum Qwen4ExpActivationError {
21    Package(Qwen4ExpNativeAssetError),
22    Header(GgufHeaderError),
23    Graph(Qwen4ExpGraphError),
24    Ple(PleNvmeError),
25    Trunk(TrunkNvmeError),
26    ContractChanged,
27}
28
29impl core::fmt::Display for Qwen4ExpActivationError {
30    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
31        match self {
32            Self::Package(error) => error.fmt(f),
33            Self::Header(error) => error.fmt(f),
34            Self::Graph(error) => error.fmt(f),
35            Self::Ple(error) => write!(f, "PLE reader error: {error:?}"),
36            Self::Trunk(error) => error.fmt(f),
37            Self::ContractChanged => {
38                write!(f, "Qwen4Exp GGUF PLE contract differs from the HMC package")
39            }
40        }
41    }
42}
43
44impl std::error::Error for Qwen4ExpActivationError {}
45
46impl From<Qwen4ExpNativeAssetError> for Qwen4ExpActivationError {
47    fn from(value: Qwen4ExpNativeAssetError) -> Self {
48        Self::Package(value)
49    }
50}
51
52impl From<GgufHeaderError> for Qwen4ExpActivationError {
53    fn from(value: GgufHeaderError) -> Self {
54        Self::Header(value)
55    }
56}
57
58impl From<Qwen4ExpGraphError> for Qwen4ExpActivationError {
59    fn from(value: Qwen4ExpGraphError) -> Self {
60        Self::Graph(value)
61    }
62}
63
64impl From<PleNvmeError> for Qwen4ExpActivationError {
65    fn from(value: PleNvmeError) -> Self {
66        Self::Ple(value)
67    }
68}
69
70impl From<TrunkNvmeError> for Qwen4ExpActivationError {
71    fn from(value: TrunkNvmeError) -> Self {
72        Self::Trunk(value)
73    }
74}
75
76/// How the trunk weights are reached during decode.
77#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
78pub enum Qwen4ExpTrunkResidency {
79    /// Seek+read each row span from disk; steady-state memory stays bounded.
80    #[default]
81    Streamed,
82    /// Read-only mmap of the source GGUF; the OS page cache holds the trunk
83    /// in RAM and row access is a pointer slice.  This deliberately trades
84    /// the bounded-memory guarantee for speed on machines whose RAM fits
85    /// the trunk (the intended deployment: trunk in RAM, PLE on NVMe).
86    Mapped,
87}
88
89/// A live package binding.  In `Streamed` residency the file cursors retain
90/// no model data in memory; in `Mapped` residency the trunk is a read-only
91/// page-cache view.  Decoder state and all compute scratch remain caller
92/// owned either way.
93pub struct Qwen4ExpNativeRuntime {
94    pub descriptor: Qwen4ExpNativeDescriptor,
95    pub index: GgufTensorIndex,
96    pub ple: PleNvmeReader,
97    pub trunk: TrunkNvmeReader,
98}
99
100impl Qwen4ExpNativeRuntime {
101    /// Fail-closed cold activation of an HMC package with streamed trunk
102    /// reads.  The only GGUF read is its metadata prefix (bounded by
103    /// `MAX_GGUF_HEADER_BYTES`).
104    pub fn activate(package: &Path) -> Result<Self, Qwen4ExpActivationError> {
105        Self::activate_with_residency(package, Qwen4ExpTrunkResidency::Streamed)
106    }
107
108    /// Activation with an explicit trunk residency mode.
109    pub fn activate_with_residency(
110        package: &Path,
111        residency: Qwen4ExpTrunkResidency,
112    ) -> Result<Self, Qwen4ExpActivationError> {
113        let descriptor = load_qwen4exp_native_hmc(package)?;
114        let source = descriptor.source_beside(package)?;
115        descriptor.verify_source_metadata(&source)?;
116        let index = GgufTensorIndex::from_gguf_header_file(&source)?;
117        let mut contracts = [Default::default(); 64];
118        let graph = validate_qwen4exp_graph(&index, &mut contracts)?;
119        if graph.layers != descriptor.n_layer
120            || index.ple_config != Some(descriptor.ple_config)
121            || index.ple_ngram_embedding_info().map(|info| info.dims[0])
122                != Some(descriptor.ple.row_width)
123            || index.ple_ngram_embedding_info().map(|info| info.dims[1])
124                != Some(descriptor.ple.rows)
125        {
126            return Err(Qwen4ExpActivationError::ContractChanged);
127        }
128        let ple = PleNvmeReader::open_from_native_descriptor(&descriptor)?;
129        let trunk = match residency {
130            Qwen4ExpTrunkResidency::Streamed => {
131                TrunkNvmeReader::open(&source, index.tensor_data_start)?
132            }
133            Qwen4ExpTrunkResidency::Mapped => {
134                TrunkNvmeReader::open_mapped(&source, index.tensor_data_start)?
135            }
136        };
137        Ok(Self {
138            descriptor,
139            index,
140            ple,
141            trunk,
142        })
143    }
144}
145
146impl Qwen4ExpNativeRuntime {
147    pub fn engine(&mut self) -> etalon_inference::qwen::Qwen4ExpRuntime<'_, crate::gguf_sharder::GgufHyperparams> {
148        etalon_inference::qwen::Qwen4ExpRuntime { index: &self.index, ple: &mut self.ple, trunk: &mut self.trunk }
149    }
150}