Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(relevance): load the Rust default embedder from Python's pinned snapshot (#4190)

Kenneth Wong9bb4b130ff87
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5b581dc9a..8122375f3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -489,9 +489,11 @@ jobs:
- name: Run relevance tests
# Offline so fastembed reads the cache the prefetch step just warmed,
# without an unauthenticated cache-validation HEAD that could 429.
+ # RUN_FASTEMBED_TESTS runs the Python half of the embedding parity check.
env:
HF_HUB_OFFLINE: "1"
TRANSFORMERS_OFFLINE: "1"
+ RUN_FASTEMBED_TESTS: "1"
run: pytest tests/test_relevance.py tests/test_fastembed_pinned_snapshot.py -v
- name: Run HTML extraction and tool reversibility tests
diff --git a/crates/headroom-core/src/relevance/embedding.rs b/crates/headroom-core/src/relevance/embedding.rs
index dc61fd33e..575e0ffc2 100644
--- a/crates/headroom-core/src/relevance/embedding.rs
+++ b/crates/headroom-core/src/relevance/embedding.rs
@@ -1,18 +1,21 @@
//! Embedding-based relevance scorer using `fastembed-rs`.
//!
-//! Uses BAAI/bge-small-en-v1.5 (33M params, 384 dims) by default —
-//! same model the Python side runs via the `fastembed` package, giving
-//! byte-equal embeddings on identical inputs. fastembed wraps ONNX
-//! Runtime under the hood, with the runtime binary auto-downloaded
-//! once at build time and the model weights auto-downloaded from
-//! Hugging Face Hub on first use (~30 MB int8-quantized ONNX).
+//! Uses BAAI/bge-small-en-v1.5 (33M params, 384 dims) by default, loaded
+//! from the same pinned `Qdrant/bge-small-en-v1.5-onnx-Q` snapshot the
+//! Python side's `fastembed` package runs (~67 MB quantized ONNX). fastembed
+//! wraps ONNX Runtime under the hood, with the runtime library loaded
+//! dynamically and the model files downloaded from Hugging Face Hub on
+//! first use.
//!
//! # Caching
//!
//! Loading a sentence-transformer model takes ~1-2 seconds (HF Hub
//! call + ONNX session init). Construct the scorer once per process
//! and reuse — `try_new` returns a `Result` because the first
-//! construction may need network access to fetch the model.
+//! construction may need network access to fetch the model. The files
+//! live in the HuggingFace hub cache directory Python's `huggingface_hub`
+//! would pick (`HF_HUB_CACHE`, `HF_HOME/hub`, `~/.cache/huggingface/hub`,
+//! …; see `hf_hub_cache_dir`), shared with Python.
//!
//! When constructed, `is_available()` returns `true` and `HybridScorer`
//! switches off the BM25-fallback path automatically. If construction
@@ -21,16 +24,24 @@
//!
//! # Output stability vs Python
//!
-//! Both languages call into the same ONNX file via ONNX Runtime (`ort`
-//! crate in Rust, `onnxruntime` package in Python's fastembed). Same
-//! kernels, same weights — embeddings agree to floating-point
-//! representation. Cosine similarity agrees to ~1e-6.
+//! Both languages run the same ONNX file and tokenizer through ONNX
+//! Runtime (`ort` crate in Rust, `onnxruntime` package in Python's
+//! fastembed), with the same CLS pooling and normalization. On the same
+//! ONNX Runtime build they agree within 1e-6 per component; across ORT
+//! versions they drift by up to ~4e-4, so they are close, not byte-equal.
+//! The gated parity fixture in `tests/parity/fixtures/embedding/` bounds
+//! that drift on both sides (see `tests/parity/record_embedding.py`).
+#[cfg(feature = "ml")]
+use std::path::{Path, PathBuf};
#[cfg(feature = "ml")]
use std::sync::Mutex;
#[cfg(feature = "ml")]
-use fastembed::{EmbeddingModel, InitOptions, QuantizationMode, TextEmbedding};
+use fastembed::{
+ EmbeddingModel, InitOptions, InitOptionsUserDefined, Pooling, QuantizationMode, TextEmbedding,
+ TokenizerFiles, UserDefinedEmbeddingModel,
+};
use super::base::{RelevanceScore, RelevanceScorer};
@@ -47,6 +58,382 @@ fn embed_batch_size(model_kind: &EmbeddingModel) -> Option<usize> {
.then_some(EMBED_BATCH_SIZE)
}
+/// Name the default model reports, the same string Python uses.
+#[cfg(feature = "ml")]
+const DEFAULT_MODEL_NAME: &str = "BAAI/bge-small-en-v1.5";
+
+/// HF repo the default model loads from: the one Python's fastembed
+/// resolves `BAAI/bge-small-en-v1.5` to. fastembed-rs maps its own
+/// `BGESmallENV15` to `Xenova/bge-small-en-v1.5`, a different (fp32) export,
+/// and always on `main`, so the default is loaded as a user-defined model
+/// from this repo instead. Keep equal to `DEFAULT_MODEL_REPO` in
+/// `headroom/relevance/embedding.py`.
+#[cfg(feature = "ml")]
+const DEFAULT_MODEL_REPO: &str = "Qdrant/bge-small-en-v1.5-onnx-Q";
+
+/// Pinned commit of [`DEFAULT_MODEL_REPO`]. Keep equal to its entry in
+/// `_PINNED_REVISIONS` (`headroom/onnx_runtime.py`);
+/// `tests/test_fastembed_pinned_snapshot.py` enforces both equalities.
+#[cfg(feature = "ml")]
+const DEFAULT_MODEL_REVISION: &str = "52398278842ec682c6f32300af41344b1c0b0bb2";
+
+#[cfg(feature = "ml")]
+const DEFAULT_MODEL_FILE: &str = "model_optimized.onnx";
+
+/// Every file the load reads: the ONNX graph, then what `TokenizerFiles`
+/// needs. Same list as Python's `DEFAULT_MODEL_FILES`.
+#[cfg(feature = "ml")]
+const DEFAULT_MODEL_FILES: [&str; 5] = [
+ DEFAULT_MODEL_FILE,
+ "tokenizer.json",
+ "tokenizer_config.json",
+ "special_tokens_map.json",
+ "config.json",
+];
+
+/// The revision to load: the pin, or `main` when `HEADROOM_HF_PIN` turns
+/// pinning off (same values as Python's `onnx_runtime._resolve_revision`).
+#[cfg(feature = "ml")]
+fn default_model_revision() -> &'static str {
+ let pin = std::env::var("HEADROOM_HF_PIN").unwrap_or_default();
+ match pin.trim().to_ascii_lowercase().as_str() {
+ "off" | "0" | "false" | "no" => "main",
+ _ => DEFAULT_MODEL_REVISION,
+ }
+}
+
+/// The HuggingFace hub cache directory, resolved the way Python's
+/// `huggingface_hub` resolves `constants.HF_HUB_CACHE`, so both languages look
+/// up and download into the same place: `HF_HUB_CACHE`, then
+/// `HUGGINGFACE_HUB_CACHE` (its legacy name), then `HF_HOME/hub`, then
+/// `XDG_CACHE_HOME/huggingface/hub`, then `~/.cache/huggingface/hub`.
+///
+/// It is exactly one directory. A snapshot in a lower-priority cache is not
+/// used when a higher one is configured, which is also what Python does: with
+/// `HF_HUB_CACHE` set, a model under `~/.cache` is neither found nor reused.
+///
+/// Both expansions happen as in `huggingface_hub.constants`:
+/// `expandvars(expanduser(...))`, first on `HF_HOME` (or its
+/// `XDG_CACHE_HOME` default) and then on the hub path itself. So
+/// `HF_HUB_CACHE=${ROOT}/hub` names the same directory in both languages, and
+/// a `~` that only appears once a variable is expanded stays literal, as it
+/// does in Python. The home directory comes from `std::env::home_dir`, which
+/// falls back to the user database when `HOME` is unset, as `expanduser`
+/// does. A variable that is set but empty still counts, as with `os.getenv`:
+/// `HF_HUB_CACHE=''` is the working directory itself, `HF_HOME=''` is `hub`
+/// and `XDG_CACHE_HOME=''` is `huggingface/hub` under it, and none of them
+/// falls through to a lower-priority cache. `tests/parity/fixtures/hf_hub_cache/`
+/// holds the cases both languages are checked against.
+#[cfg(feature = "ml")]
+fn hf_hub_cache_dir() -> Option<PathBuf> {
+ let var = |name: &str| std::env::var_os(name).map(PathBuf::from);
+ let home = std::env::home_dir();
+ let expand = |path: PathBuf| expand_vars(&expand_user(path, home.as_deref()));
+ let hub = match var("HF_HUB_CACHE").or_else(|| var("HUGGINGFACE_HUB_CACHE")) {
+ Some(dir) => dir,
+ None => {
+ let hf_home = match var("HF_HOME") {
+ Some(dir) => dir,
+ None => var("XDG_CACHE_HOME")
+ .or_else(|| home.as_ref().map(|home| home.join(".cache")))?
+ .join("huggingface"),
+ };
+ expand(hf_home).join("hub")
+ }
+ };
+ Some(expand(hub))
+}
+
+/// Python's `os.path.expanduser` for a leading bare `~` component. `~user`
+/// stays as written, which is also what `expanduser` does when it cannot
+/// resolve the user.
+#[cfg(feature = "ml")]
+fn expand_user(path: PathBuf, home: Option<&Path>) -> PathBuf {
+ match (path.strip_prefix("~"), home) {
+ (Ok(rest), Some(home)) => home.join(rest),
+ _ => path,
+ }
+}
+
+/// Python's `os.path.expandvars`: `posixpath` rules off Windows, `ntpath`
+/// rules on it. A path that is not valid Unicode is returned unchanged.
+#[cfg(feature = "ml")]
+fn expand_vars(path: &Path) -> PathBuf {
+ let Some(text) = path.to_str() else {
+ return path.to_path_buf();
+ };
+ #[cfg(windows)]
+ let expanded = expand_vars_nt(text, env_lookup);
+ #[cfg(not(windows))]
+ let expanded = expand_vars_posix(text, env_lookup);
+ PathBuf::from(expanded)
+}
+
+/// An environment value for `expand_vars`. Names the OS cannot hold (empty,
+/// or containing `=` or NUL) are unset, which is how Python's `os.environ`
+/// lookup fails for them too.
+#[cfg(feature = "ml")]
+fn env_lookup(name: &str) -> Option<std::ffi::OsString> {
+ if name.is_empty() || name.contains(['=', '\0']) {
+ return None;
+ }
+ std::env::var_os(name)
+}
+
+/// `posixpath.expandvars`: `$name` (ASCII letters, digits, `_`) or
+/// `${anything but a brace}`. An unset name, and a `$` that starts neither
+/// form, stay as written. Expanded values are not scanned again.
+#[cfg(feature = "ml")]
+#[cfg_attr(windows, allow(dead_code))] // tests run both rule sets everywhere
+fn expand_vars_posix(
+ text: &str,
+ lookup: impl Fn(&str) -> Option<std::ffi::OsString>,
+) -> std::ffi::OsString {
+ let mut out = std::ffi::OsString::new();
+ let mut rest = text;
+ while let Some(at) = rest.find('$') {
+ out.push(&rest[..at]);
+ let after = &rest[at + 1..];
+ let word = after
+ .find(|c: char| !(c.is_ascii_alphanumeric() || c == '_'))
+ .unwrap_or(after.len());
+ // (name, length of the reference after the `$`)
+ let reference = if word > 0 {
+ Some((&after[..word], word))
+ } else {
+ after
+ .strip_prefix('{')
+ .and_then(|braced| braced.find('}').map(|end| (&braced[..end], end + 2)))
+ };
+ match reference {
+ Some((name, len)) => {
+ match lookup(name) {
+ Some(value) => out.push(value),
+ None => out.push(&rest[at..at + 1 + len]),
+ }
+ rest = &after[len..];
+ }
+ None => {
+ out.push("$");
+ rest = after;
+ }
+ }
+ }
+ out.push(rest);
+ out
+}
+
+/// `ntpath.expandvars`: `%name%`, `${name}` and `$name` (ASCII letters,
+/// digits, `_`, `-`); `%%` and `$$` are a literal `%` and `$`; nothing inside
+/// single quotes expands. An unset or unterminated reference stays as
+/// written.
+#[cfg(feature = "ml")]
+#[cfg_attr(not(windows), allow(dead_code))] // tests run both rule sets everywhere
+fn expand_vars_nt(
+ text: &str,
+ lookup: impl Fn(&str) -> Option<std::ffi::OsString>,
+) -> std::ffi::OsString {
+ let mut out = std::ffi::OsString::new();
+ let mut rest = text;
+ while let Some(c) = rest.chars().next() {
+ let after = &rest[c.len_utf8()..];
+ match c {
+ '\'' => match after.find('\'') {
+ Some(end) => {
+ out.push(&rest[..end + 2]);
+ rest = &after[end + 1..];
+ }
+ None => {
+ out.push(rest);
+ rest = "";
+ }
+ },
+ '%' if after.starts_with('%') => {
+ out.push("%");
+ rest = &after[1..];
+ }
+ '%' => match after.find('%') {
+ Some(end) => {
+ let name = &after[..end];
+ match lookup(name) {
+ Some(value) => out.push(value),
+ None => out.push(&rest[..end + 2]),
+ }
+ rest = &after[end + 1..];
+ }
+ None => {
+ out.push(rest);
+ rest = "";
+ }
+ },
+ '$' if after.starts_with('$') => {
+ out.push("$");
+ rest = &after[1..];
+ }
+ '$' if after.starts_with('{') => match after[1..].find('}') {
+ Some(end) => {
+ let name = &after[1..1 + end];
+ match lookup(name) {
+ Some(value) => out.push(value),
+ None => out.push(&rest[..end + 3]),
+ }
+ rest = &after[end + 2..];
+ }
+ None => {
+ out.push(rest);
+ rest = "";
+ }
+ },
+ '$' => {
+ let end = after
+ .find(|c: char| !(c.is_ascii_alphanumeric() || c == '_' || c == '-'))
+ .unwrap_or(after.len());
+ let name = &after[..end];
+ match lookup(name) {
+ Some(value) => out.push(value),
+ None => out.push(&rest[..end + 1]),
+ }
+ rest = &after[end..];
+ }
+ _ => {
+ out.push(&rest[..c.len_utf8()]);
+ rest = after;
+ }
+ }
+ }
+ out
+}
+
+/// Find a snapshot of [`DEFAULT_MODEL_REPO`] at `revision` in the hub cache
+/// `cache` that holds every file in [`DEFAULT_MODEL_FILES`]. Never touches the
+/// network.
+///
+/// Looks the snapshot up by directory rather than through `hf_hub::Cache`:
+/// that resolves every revision through `refs/<revision>`, which Python's
+/// `huggingface_hub` does not write for a commit SHA, so a snapshot Python
+/// downloaded would be missed. A branch name still goes through its ref.
+#[cfg(feature = "ml")]
+fn cached_snapshot(cache: &Path, revision: &str) -> Option<PathBuf> {
+ let repo = cache.join(format!("models--{}", DEFAULT_MODEL_REPO.replace('/', "--")));
+ let commit = std::fs::read_to_string(repo.join("refs").join(revision))
+ .map(|c| c.trim().to_string())
+ .unwrap_or_else(|_| revision.to_string());
+ let snapshot = repo.join("snapshots").join(commit);
+ // `is_file` follows the snapshot's symlinks, so blobs deleted from under
+ // it count as a miss rather than a load failure.
+ DEFAULT_MODEL_FILES
+ .iter()
+ .all(|name| snapshot.join(name).is_file())
+ .then_some(snapshot)
+}
+
+/// The Hub handle for [`DEFAULT_MODEL_REPO`] at `revision`, caching under
+/// `cache_root`. Honors `HF_ENDPOINT` like the Python side does.
+#[cfg(feature = "ml")]
+fn default_model_repo(
+ cache_root: &Path,
+ revision: &str,
+) -> Result<hf_hub::api::sync::ApiRepo, String> {
+ // Air-gap chokepoint, ahead of the client: building it resolves the Hub
+ // endpoint and the `ureq` agent, and `hf-hub` downloads on a cache miss
+ // even with `HF_HUB_OFFLINE` set. Callers reach this only on a cache
+ // miss, so a pre-seeded air-gapped host still loads.
+ //
+ // The refusal is soft by design: every caller degrades to the BM25
+ // scorer on `Err`, so an air-gapped box loses embedding relevance instead
+ // of failing a request. The message names the switch so the operator can
+ // tell the causes apart in the log.
+ crate::offline::guard_egress("fastembed embedding model download", DEFAULT_MODEL_REPO)
+ .map_err(|e| format!("EmbeddingScorer model load refused: {e}"))?;
+ let mut builder =
+ hf_hub::api::sync::ApiBuilder::from_cache(hf_hub::Cache::new(cache_root.to_path_buf()))
+ .with_progress(false);
+ if let Ok(endpoint) = std::env::var("HF_ENDPOINT") {
+ builder = builder.with_endpoint(endpoint);
+ }
+ let api = builder
+ .build()
+ .map_err(|e| format!("EmbeddingScorer: HuggingFace client init failed: {e}"))?;
+ Ok(api.repo(hf_hub::Repo::with_revision(
+ DEFAULT_MODEL_REPO.to_string(),
+ hf_hub::RepoType::Model,
+ revision.to_string(),
+ )))
+}
+
+/// Download every file of the snapshot at `revision` through `repo` (from
+/// [`default_model_repo`]) and return the snapshot directory.
+#[cfg(feature = "ml")]
+fn download_snapshot(repo: &hf_hub::api::sync::ApiRepo, revision: &str) -> Result<PathBuf, String> {
+ let mut snapshot: Option<PathBuf> = None;
+ for name in DEFAULT_MODEL_FILES {
+ let path = repo.get(name).map_err(|e| {
+ format!(
+ "EmbeddingScorer: downloading {DEFAULT_MODEL_REPO}/{name}@{revision} failed: {e}"
+ )
+ })?;
+ let dir = path
+ .parent()
+ .map(Path::to_path_buf)
+ .ok_or_else(|| format!("EmbeddingScorer: {} has no parent", path.display()))?;
+ match &snapshot {
+ None => snapshot = Some(dir),
+ Some(first) if *first == dir => {}
+ Some(first) => {
+ return Err(format!(
+ "EmbeddingScorer: {DEFAULT_MODEL_REPO} files resolved to more than one \
+ snapshot: {} and {}",
+ first.display(),
+ dir.display()
+ ))
+ }
+ }
+ }
+ snapshot.ok_or_else(|| "EmbeddingScorer: no model files configured".to_string())
+}
+
+/// Load the snapshot in `dir` with the settings fastembed uses for this
+/// model (`BGESmallENV15Q` in fastembed-rs, the Python default): CLS
+/// pooling, static quantization, 512-token truncation.
+#[cfg(feature = "ml")]
+fn load_snapshot(dir: &Path) -> Result<TextEmbedding, String> {
+ let read = |name: &str| {
+ std::fs::read(dir.join(name))
+ .map_err(|e| format!("EmbeddingScorer: reading {}: {e}", dir.join(name).display()))
+ };
+ let tokenizer_files = TokenizerFiles {
+ tokenizer_file: read("tokenizer.json")?,
+ config_file: read("config.json")?,
+ special_tokens_map_file: read("special_tokens_map.json")?,
+ tokenizer_config_file: read("tokenizer_config.json")?,
+ };
+ let model = UserDefinedEmbeddingModel::new(read(DEFAULT_MODEL_FILE)?, tokenizer_files)
+ .with_pooling(Pooling::Cls)
+ .with_quantization(QuantizationMode::Static);
+ TextEmbedding::try_new_from_user_defined(model, InitOptionsUserDefined::new())
+ .map_err(|e| format!("EmbeddingScorer model load failed: {e}"))
+}
+
+/// Refuse before ONNX Runtime is touched on a host that cannot run it.
+#[cfg(feature = "ml")]
+fn onnx_runtime_ready() -> Result<(), String> {
+ // fastembed links the precompiled ONNX Runtime binary, which contains
+ // AVX2 instructions on x86. Loading/running it on a non-AVX2 CPU traps
+ // with SIGILL (issue #1723) — an uncatchable native fault. Bail early so
+ // callers fall back to the BM25/stub path instead of killing the process.
+ if !crate::onnx_cpu::onnx_runtime_supported_by_cpu() {
+ return Err("EmbeddingScorer: ONNX Runtime backend requires AVX2 on \
+ this x86 CPU; embedding relevance disabled (falling back to BM25)"
+ .to_string());
+ }
+ // The crate loads ONNX Runtime dynamically (`ort-load-dynamic`);
+ // resolve and commit the dylib before fastembed touches ort — a
+ // failed in-ort load deadlocks instead of erroring (see
+ // `dynamic_ort_loader_ready`).
+ crate::transforms::magika_detector::dynamic_ort_loader_ready()
+ .map_err(|e| format!("EmbeddingScorer: ONNX Runtime unavailable: {e}"))
+}
+
/// fastembed-backed semantic relevance scorer.
///
/// Construct via `EmbeddingScorer::try_new()` to handle the model-load
@@ -98,53 +485,65 @@ impl Default for EmbeddingScorer {
#[cfg(feature = "ml")]
impl EmbeddingScorer {
/// Construct the scorer with the default model
- /// (BAAI/bge-small-en-v1.5). May trigger a one-time HF Hub
- /// download if the model isn't cached locally; subsequent calls
- /// are fast.
+ /// (BAAI/bge-small-en-v1.5) from its pinned snapshot. May trigger a
+ /// one-time HF Hub download if the snapshot isn't cached locally;
+ /// subsequent calls are fast.
///
- /// Returns an error from fastembed if model initialization fails
- /// (network failure during download, missing ONNX runtime
+ /// Returns an error if model initialization fails (refused while
+ /// offline, network failure during download, missing ONNX runtime
/// binaries, etc.).
pub fn try_new() -> Result<Self, String> {
- Self::try_new_with_model(EmbeddingModel::BGESmallENV15)
+ let cache = hf_hub_cache_dir().ok_or_else(|| {
+ "EmbeddingScorer: no HuggingFace cache directory (set HF_HUB_CACHE or HF_HOME)"
+ .to_string()
+ })?;
+ Self::try_new_pinned(&cache)
+ }
+
+ /// [`Self::try_new`] against an explicit hub cache directory, used for
+ /// both the lookup and any download. Split out so tests can point it at a
+ /// temporary cache.
+ fn try_new_pinned(cache: &Path) -> Result<Self, String> {
+ let revision = default_model_revision();
+ let snapshot = match cached_snapshot(cache, revision) {
+ Some(dir) => {
+ onnx_runtime_ready()?;
+ dir
+ }
+ None => {
+ // Built (and so guarded) ahead of the AVX2 and ort-loader
+ // probes, so an air-gapped box reports the policy refusal
+ // rather than whichever local prerequisite was missing too.
+ let repo = default_model_repo(cache, revision)?;
+ onnx_runtime_ready()?;
+ download_snapshot(&repo, revision)?
+ }
+ };
+ let model = load_snapshot(&snapshot)?;
+ // The snapshot is statically quantized (see `load_snapshot`), so it
+ // batches like fastembed's `BGESmallENV15Q`.
+ Ok(EmbeddingScorer {
+ model_name: DEFAULT_MODEL_NAME.to_string(),
+ model: Some(Mutex::new(model)),
+ batch_size: Some(EMBED_BATCH_SIZE),
+ })
}
- /// Construct with an explicit model. See `fastembed::EmbeddingModel`
- /// for the catalog. The default `BGESmallENV15` is the best
- /// quality/speed tradeoff for compression-relevance scoring on
- /// short snippets.
+ /// Construct with an explicit model from fastembed-rs's catalog (see
+ /// `fastembed::EmbeddingModel`). Unlike [`Self::try_new`], these are not
+ /// pinned: fastembed resolves them on the repo's `main`. Note that
+ /// `BGESmallENV15` here is the `Xenova` fp32 export, not the snapshot
+ /// Python runs; use `try_new` for the default model.
pub fn try_new_with_model(model_kind: EmbeddingModel) -> Result<Self, String> {
let name = format!("{:?}", model_kind);
// Air-gap chokepoint, FIRST thing in the function. `TextEmbedding::
// try_new` resolves the model's ONNX weights through `hf-hub`, which
// downloads from huggingface.co on a cache miss even with
- // `HF_HUB_OFFLINE` set — the same hole the tokenizer and Kompress model
- // fetches had. It sits ahead of the AVX2 and ort-loader probes below so
- // that an air-gapped box reports the policy refusal rather than
- // whichever local prerequisite happened to be missing as well.
- //
- // The refusal is soft here by design: this function already returns
- // `Err(String)` for "ONNX runtime unavailable" and every caller degrades
- // to the BM25 scorer, so an air-gapped box loses embedding relevance
- // instead of failing a request. The message names the switch so the
- // operator can tell the two causes apart in the log.
+ // `HF_HUB_OFFLINE` set, and offers no cache-only attempt to put the
+ // guard behind, so this refuses even a cached model.
crate::offline::guard_egress("fastembed embedding model download", &name)
.map_err(|e| format!("EmbeddingScorer model load refused: {e}"))?;
- // fastembed links the precompiled ONNX Runtime binary, which contains
- // AVX2 instructions on x86. Loading/running it on a non-AVX2 CPU traps
- // with SIGILL (issue #1723) — an uncatchable native fault. Bail early so
- // callers fall back to the BM25/stub path instead of killing the process.
- if !crate::onnx_cpu::onnx_runtime_supported_by_cpu() {
- return Err("EmbeddingScorer: ONNX Runtime backend requires AVX2 on \
- this x86 CPU; embedding relevance disabled (falling back to BM25)"
- .to_string());
- }
- // The crate loads ONNX Runtime dynamically (`ort-load-dynamic`);
- // resolve and commit the dylib before fastembed touches ort — a
- // failed in-ort load deadlocks instead of erroring (see
- // `dynamic_ort_loader_ready`).
- crate::transforms::magika_detector::dynamic_ort_loader_ready()
- .map_err(|e| format!("EmbeddingScorer: ONNX Runtime unavailable: {e}"))?;
+ onnx_runtime_ready()?;
let batch_size = embed_batch_size(&model_kind);
let model = TextEmbedding::try_new(InitOptions::new(model_kind))
.map_err(|e| format!("EmbeddingScorer model load failed: {}", e))?;
@@ -332,7 +731,7 @@ mod tests {
use super::*;
// The real-model tests are gated behind RUN_FASTEMBED_TESTS=1
- // since they require network access on first run (~30 MB model
+ // since they require network access on first run (~67 MB model
// download). Without the env var, only the offline-safe stub
// path is exercised.
@@ -341,20 +740,36 @@ mod tests {
std::env::var("RUN_FASTEMBED_TESTS").is_ok()
}
- /// `try_new_with_model` must refuse before fastembed resolves the model,
- /// and must say so in the returned message rather than looking like an
- /// ordinary load failure — the caller only ever sees the `String`.
+ /// Lay out a fake HF cache snapshot of the default repo at `commit`,
+ /// holding `files` (dummy bytes), and return the snapshot directory.
+ #[cfg(feature = "ml")]
+ fn fake_snapshot(root: &Path, commit: &str, files: &[&str]) -> PathBuf {
+ let snapshot = root
+ .join(format!("models--{}", DEFAULT_MODEL_REPO.replace('/', "--")))
+ .join("snapshots")
+ .join(commit);
+ std::fs::create_dir_all(&snapshot).unwrap();
+ for name in files {
+ std::fs::write(snapshot.join(name), b"not a model").unwrap();
+ }
+ snapshot
+ }
+
+ /// A cold cache must refuse before anything resolves the model, and say
+ /// so in the returned message rather than looking like an ordinary load
+ /// failure — the caller only ever sees the `String`.
///
/// Not gated on `RUN_FASTEMBED_TESTS`: the whole point is that no network
/// call happens, so this is safe to run in CI. If the guard were removed
- /// this test would either download ~30 MB or fail with a load error, and
+ /// this test would either download ~67 MB or fail with a load error, and
/// neither says "refused".
#[cfg(feature = "ml")]
#[test]
fn try_new_refuses_while_offline() {
+ let cache = tempfile::tempdir().unwrap();
let _guard = crate::test_support::env_lock();
std::env::set_var(crate::offline::OFFLINE_ENV, "1");
- let result = EmbeddingScorer::try_new();
+ let result = EmbeddingScorer::try_new_pinned(cache.path());
std::env::remove_var(crate::offline::OFFLINE_ENV);
let err = result.err().expect("guard must refuse while offline");
@@ -363,6 +778,346 @@ mod tests {
assert!(err.contains("fastembed embedding model download"), "{err}");
}
+ /// A pre-seeded snapshot is the air-gapped setup: the guard sits on the
+ /// cache miss only, so a cached snapshot gets past it. The dummy ONNX
+ /// bytes then fail to load (or ORT is missing), which is fine; what
+ /// matters is that the failure is not the refusal.
+ #[cfg(feature = "ml")]
+ #[test]
+ fn a_cached_snapshot_is_not_refused_offline() {
+ let cache = tempfile::tempdir().unwrap();
+ fake_snapshot(cache.path(), DEFAULT_MODEL_REVISION, &DEFAULT_MODEL_FILES);
+ let _guard = crate::test_support::env_lock();
+ let pin = std::env::var_os("HEADROOM_HF_PIN");
+ std::env::remove_var("HEADROOM_HF_PIN");
+ std::env::set_var(crate::offline::OFFLINE_ENV, "1");
+ let result = EmbeddingScorer::try_new_pinned(cache.path());
+ std::env::remove_var(crate::offline::OFFLINE_ENV);
+ if let Some(pin) = pin {
+ std::env::set_var("HEADROOM_HF_PIN", pin);
+ }
+
+ let err = result
+ .err()
+ .expect("dummy model bytes can never load into a session");
+ assert!(!err.contains("refused"), "{err}");
+ }
+
+ #[cfg(feature = "ml")]
+ #[test]
+ fn cached_snapshot_finds_the_pinned_commit() {
+ let cache = tempfile::tempdir().unwrap();
+ let snapshot = fake_snapshot(cache.path(), DEFAULT_MODEL_REVISION, &DEFAULT_MODEL_FILES);
+ assert_eq!(
+ cached_snapshot(cache.path(), DEFAULT_MODEL_REVISION),
+ Some(snapshot)
+ );
+ }
+
+ /// The regression this pin exists for: a snapshot of whatever `main`
+ /// pointed to must not satisfy the pinned lookup.
+ #[cfg(feature = "ml")]
+ #[test]
+ fn cached_snapshot_ignores_other_commits() {
+ let cache = tempfile::tempdir().unwrap();
+ let main_commit = "aa8f8b060edb00e03bfdd08813a2949946c8ba55";
+ let snapshot = fake_snapshot(cache.path(), main_commit, &DEFAULT_MODEL_FILES);
+ let refs = snapshot.parent().unwrap().parent().unwrap().join("refs");
+ std::fs::create_dir_all(&refs).unwrap();
+ std::fs::write(refs.join("main"), main_commit).unwrap();
+
+ assert_eq!(cached_snapshot(cache.path(), DEFAULT_MODEL_REVISION), None);
+ // `main` still resolves through its ref, for HEADROOM_HF_PIN=off.
+ assert_eq!(cached_snapshot(cache.path(), "main"), Some(snapshot));
+ }
+
+ #[cfg(feature = "ml")]
+ #[test]
+ fn cached_snapshot_needs_every_file() {
+ let cache = tempfile::tempdir().unwrap();
+ fake_snapshot(
+ cache.path(),
+ DEFAULT_MODEL_REVISION,
+ &DEFAULT_MODEL_FILES[..DEFAULT_MODEL_FILES.len() - 1],
+ );
+ assert_eq!(cached_snapshot(cache.path(), DEFAULT_MODEL_REVISION), None);
+ }
+
+ /// Every variable `hf_hub_cache_dir` reads.
+ #[cfg(feature = "ml")]
+ const CACHE_ENV: [&str; 6] = [
+ "HF_HUB_CACHE",
+ "HUGGINGFACE_HUB_CACHE",
+ "HF_HOME",
+ "XDG_CACHE_HOME",
+ "HOME",
+ "USERPROFILE",
+ ];
+
+ /// Saves [`CACHE_ENV`], clears it, and puts it back on drop, so a failing
+ /// assertion cannot leak a fake cache into later tests. Take
+ /// `env_lock()` first.
+ #[cfg(feature = "ml")]
+ struct CacheEnv(Vec<(String, Option<std::ffi::OsString>)>);
+
+ #[cfg(feature = "ml")]
+ impl CacheEnv {
+ fn cleared() -> Self {
+ Self::cleared_with(std::iter::empty())
+ }
+
+ /// [`Self::cleared`], plus `extra` variables (the ones a test's
+ /// paths reference).
+ fn cleared_with(extra: impl IntoIterator<Item = String>) -> Self {
+ let names: Vec<String> = CACHE_ENV
+ .iter()
+ .map(|name| name.to_string())
+ .chain(extra)
+ .collect();
+ let saved = names
+ .into_iter()
+ .map(|name| {
+ let value = std::env::var_os(&name);
+ std::env::remove_var(&name);
+ (name, value)
+ })
+ .collect();
+ CacheEnv(saved)
+ }
+ }
+
+ #[cfg(feature = "ml")]
+ impl Drop for CacheEnv {
+ fn drop(&mut self) {
+ for (name, value) in &self.0 {
+ match value {
+ Some(value) => std::env::set_var(name, value),
+ None => std::env::remove_var(name),
+ }
+ }
+ }
+ }
+
+ /// Same order as `huggingface_hub.constants.HF_HUB_CACHE`: each variable
+ /// wins over every one after it, and only one directory comes back.
+ #[cfg(feature = "ml")]
+ #[test]
+ fn hf_hub_cache_dir_follows_huggingface_hub_precedence() {
+ let _guard = crate::test_support::env_lock();
+ let _env = CacheEnv::cleared();
+ let t = tempfile::tempdir().unwrap();
+ let p = |name: &str| t.path().join(name);
+ std::env::set_var("HOME", p("home"));
+ std::env::set_var("USERPROFILE", p("home"));
+ std::env::set_var("XDG_CACHE_HOME", p("xdg"));
+ std::env::set_var("HF_HOME", p("hf-home"));
+ std::env::set_var("HUGGINGFACE_HUB_CACHE", p("legacy"));
+ std::env::set_var("HF_HUB_CACHE", p("explicit"));
+
+ assert_eq!(hf_hub_cache_dir(), Some(p("explicit")));
+ std::env::remove_var("HF_HUB_CACHE");
+ assert_eq!(hf_hub_cache_dir(), Some(p("legacy")));
+ std::env::remove_var("HUGGINGFACE_HUB_CACHE");
+ assert_eq!(hf_hub_cache_dir(), Some(p("hf-home").join("hub")));
+ std::env::remove_var("HF_HOME");
+ assert_eq!(
+ hf_hub_cache_dir(),
+ Some(p("xdg").join("huggingface").join("hub"))
+ );
+ std::env::remove_var("XDG_CACHE_HOME");
+ assert_eq!(
+ hf_hub_cache_dir(),
+ Some(p("home").join(".cache").join("huggingface").join("hub"))
+ );
+
+ // A leading `~` expands.
+ std::env::set_var("HF_HOME", "~/models");
+ assert_eq!(
+ hf_hub_cache_dir(),
+ Some(p("home").join("models").join("hub"))
+ );
+
+ // A set but empty variable is the working directory, as in Python,
+ // and still wins over every variable after it.
+ std::env::set_var("HF_HUB_CACHE", "");
+ assert_eq!(hf_hub_cache_dir(), Some(PathBuf::new()));
+ std::env::remove_var("HF_HUB_CACHE");
+ std::env::set_var("HF_HOME", "");
+ std::env::set_var("XDG_CACHE_HOME", p("xdg"));
+ assert_eq!(hf_hub_cache_dir(), Some(PathBuf::from("hub")));
+ }
+
+ /// Cases checked against Python itself (`posixpath`, `ntpath` and
+ /// `huggingface_hub.constants`) by `tests/test_fastembed_pinned_snapshot.py`.
+ #[cfg(feature = "ml")]
+ const HF_CACHE_FIXTURE: &str = include_str!(concat!(
+ env!("CARGO_MANIFEST_DIR"),
+ "/../../tests/parity/fixtures/hf_hub_cache/cases.json"
+ ));
+
+ /// Both rule sets on every platform, so the Windows port is exercised by
+ /// the macOS and Linux runs too.
+ #[cfg(feature = "ml")]
+ #[test]
+ fn expand_vars_matches_python_posixpath_and_ntpath() {
+ let fixture: serde_json::Value = serde_json::from_str(HF_CACHE_FIXTURE).unwrap();
+ let section = &fixture["expandvars"];
+ let env: std::collections::HashMap<String, String> =
+ serde_json::from_value(section["env"].clone()).unwrap();
+ let lookup = |name: &str| env.get(name).map(std::ffi::OsString::from);
+ for case in section["cases"].as_array().unwrap() {
+ let input = case["input"].as_str().unwrap();
+ let want = |key: &str| std::ffi::OsString::from(case[key].as_str().unwrap());
+ assert_eq!(
+ expand_vars_posix(input, lookup),
+ want("posix"),
+ "posix {input:?}"
+ );
+ assert_eq!(expand_vars_nt(input, lookup), want("nt"), "nt {input:?}");
+ }
+ }
+
+ /// The review case among them: `HF_HUB_CACHE=${ROOT}/hub` is
+ /// `<ROOT>/hub` in Python, so Rust must not look up or download into a
+ /// literal `${ROOT}` directory instead.
+ #[cfg(feature = "ml")]
+ #[test]
+ fn hf_hub_cache_dir_matches_the_shared_fixture() {
+ let fixture: serde_json::Value = serde_json::from_str(HF_CACHE_FIXTURE).unwrap();
+ let section = &fixture["cache_dir"];
+ let probe_vars: Vec<String> =
+ serde_json::from_value(section["probe_vars"].clone()).unwrap();
+ let _guard = crate::test_support::env_lock();
+ let _env = CacheEnv::cleared_with(probe_vars.clone());
+ let t = tempfile::tempdir().unwrap();
+ let (root, home) = (t.path().join("root"), t.path().join("home"));
+ let fill = |text: &str| {
+ text.replace("{root}", root.to_str().unwrap())
+ .replace("{home}", home.to_str().unwrap())
+ };
+ for case in section["cases"].as_array().unwrap() {
+ for name in CACHE_ENV
+ .iter()
+ .copied()
+ .chain(probe_vars.iter().map(String::as_str))
+ {
+ std::env::remove_var(name);
+ }
+ std::env::set_var("HOME", &home);
+ std::env::set_var("USERPROFILE", &home);
+ for (name, value) in case["env"].as_object().unwrap() {
+ std::env::set_var(name, fill(value.as_str().unwrap()));
+ }
+ let expected = match &case["expected"] {
+ serde_json::Value::Object(by_os) => {
+ &by_os[if cfg!(windows) { "nt" } else { "posix" }]
+ }
+ expected => expected,
+ };
+ assert_eq!(
+ hf_hub_cache_dir(),
+ Some(PathBuf::from(fill(expected.as_str().unwrap()))),
+ "{}",
+ case["name"]
+ );
+ }
+ }
+
+ /// With no `HOME` (a service started with a bare environment) the home
+ /// directory still comes from the user database, as Python's
+ /// `expanduser` does, instead of leaving the scorer with no cache.
+ #[cfg(all(feature = "ml", unix))]
+ #[test]
+ fn hf_hub_cache_dir_without_home_uses_the_user_database() {
+ let _guard = crate::test_support::env_lock();
+ let _env = CacheEnv::cleared();
+ let dir = hf_hub_cache_dir().expect("a cache directory without HOME");
+ assert!(dir.is_absolute(), "{}", dir.display());
+ assert!(
+ dir.ends_with(Path::new(".cache").join("huggingface").join("hub")),
+ "{}",
+ dir.display()
+ );
+ }
+
+ /// The case from review: an explicit, empty `HF_HUB_CACHE` next to a
+ /// complete snapshot in the default cache under `HOME`. Python looks only
+ /// in the explicit cache and downloads there, so Rust must not find the
+ /// `HOME` copy, for the pinned revision or for floating `main`
+ /// (`HEADROOM_HF_PIN=off`). `try_new` is `try_new_pinned` on
+ /// `hf_hub_cache_dir()`, which looks up and downloads only in the
+ /// directory it is given (see the two offline tests above), so checking
+ /// the resolver and the lookup here covers it without flipping
+ /// `HEADROOM_OFFLINE` for a long stretch of the parallel run.
+ #[cfg(feature = "ml")]
+ #[test]
+ fn an_empty_explicit_cache_ignores_a_lower_priority_snapshot() {
+ let _guard = crate::test_support::env_lock();
+ let _env = CacheEnv::cleared();
+ let explicit = tempfile::tempdir().unwrap();
+ let home = tempfile::tempdir().unwrap();
+ let default_cache = home.path().join(".cache").join("huggingface").join("hub");
+ // A complete pinned snapshot, plus an older `main` behind refs/main.
+ let pinned = fake_snapshot(&default_cache, DEFAULT_MODEL_REVISION, &DEFAULT_MODEL_FILES);
+ let main_commit = "aa8f8b060edb00e03bfdd08813a2949946c8ba55";
+ let main = fake_snapshot(&default_cache, main_commit, &DEFAULT_MODEL_FILES);
+ let refs = main.parent().unwrap().parent().unwrap().join("refs");
+ std::fs::create_dir_all(&refs).unwrap();
+ std::fs::write(refs.join("main"), main_commit).unwrap();
+ std::env::set_var("HOME", home.path());
+ std::env::set_var("USERPROFILE", home.path());
+
+ std::env::set_var("HF_HUB_CACHE", explicit.path());
+ let cache = hf_hub_cache_dir().expect("cache directory");
+ assert_eq!(cache, explicit.path());
+ assert_eq!(cached_snapshot(&cache, DEFAULT_MODEL_REVISION), None);
+ assert_eq!(cached_snapshot(&cache, "main"), None);
+
+ // Without the explicit cache, the same HOME snapshots are the cache.
+ std::env::remove_var("HF_HUB_CACHE");
+ let cache = hf_hub_cache_dir().expect("cache directory");
+ assert_eq!(cache, default_cache);
+ assert_eq!(
+ cached_snapshot(&cache, DEFAULT_MODEL_REVISION),
+ Some(pinned)
+ );
+ assert_eq!(cached_snapshot(&cache, "main"), Some(main));
+ }
+
+ /// The download asks the Hub for the pinned commit. This is what Python's
+ /// fastembed silently dropped; building the URL makes no network call.
+ #[cfg(feature = "ml")]
+ #[test]
+ fn download_requests_the_pinned_revision() {
+ let cache = tempfile::tempdir().unwrap();
+ let _guard = crate::test_support::env_lock();
+ std::env::remove_var(crate::offline::OFFLINE_ENV);
+ let repo = default_model_repo(cache.path(), DEFAULT_MODEL_REVISION).unwrap();
+ let url = repo.url(DEFAULT_MODEL_FILE);
+ assert!(
+ url.ends_with(&format!(
+ "/{DEFAULT_MODEL_REPO}/resolve/{DEFAULT_MODEL_REVISION}/{DEFAULT_MODEL_FILE}"
+ )),
+ "{url}"
+ );
+ }
+
+ #[cfg(feature = "ml")]
+ #[test]
+ fn pin_can_be_disabled() {
+ let _guard = crate::test_support::env_lock();
+ let pin = std::env::var_os("HEADROOM_HF_PIN");
+ std::env::set_var("HEADROOM_HF_PIN", " OFF ");
+ let disabled = default_model_revision();
+ std::env::remove_var("HEADROOM_HF_PIN");
+ let pinned = default_model_revision();
+ if let Some(pin) = pin {
+ std::env::set_var("HEADROOM_HF_PIN", pin);
+ }
+ assert_eq!(disabled, "main");
+ assert_eq!(pinned, DEFAULT_MODEL_REVISION);
+ }
+
/// Construct a stub scorer with `model = None` for offline-safe
/// tests of the unavailable-path behavior.
#[cfg(feature = "ml")]
@@ -500,7 +1255,69 @@ mod tests {
}
let s = EmbeddingScorer::try_new().expect("model loads");
assert!(s.is_available());
- assert_eq!(s.model_name, "BGESmallENV15");
+ assert_eq!(s.model_name, "BAAI/bge-small-en-v1.5");
+ }
+
+ /// Rust half of the cross-language parity check: the pinned model must
+ /// reproduce the embeddings Python recorded (tests/parity/record_embedding.py)
+ /// within the fixture's tolerance. The Python half is
+ /// tests/test_fastembed_pinned_snapshot.py; both comparing against one
+ /// fixture bounds the drift between the two languages.
+ #[cfg(feature = "ml")]
+ #[test]
+ fn fastembed_matches_parity_fixture() {
+ if !fastembed_enabled() {
+ return;
+ }
+ let path = Path::new(env!("CARGO_MANIFEST_DIR"))
+ .join("../../tests/parity/fixtures/embedding/bge_small_en_v15_pinned.json");
+ let fixture: serde_json::Value =
+ serde_json::from_str(&std::fs::read_to_string(&path).expect("fixture readable"))
+ .expect("fixture is JSON");
+ assert_eq!(fixture["repo"], DEFAULT_MODEL_REPO);
+ assert_eq!(fixture["revision"], DEFAULT_MODEL_REVISION);
+ let max_abs_diff = fixture["max_abs_diff"].as_f64().expect("max_abs_diff");
+ let texts: Vec<String> = fixture["texts"]
+ .as_array()
+ .expect("texts")
+ .iter()
+ .map(|t| t.as_str().expect("text").to_string())
+ .collect();
+ let expected: Vec<Vec<f64>> = fixture["embeddings"]
+ .as_array()
+ .expect("embeddings")
+ .iter()
+ .map(|row| {
+ row.as_array()
+ .expect("row")
+ .iter()
+ .map(|v| v.as_f64().expect("float"))
+ .collect()
+ })
+ .collect();
+
+ let s = EmbeddingScorer::try_new().expect("model loads");
+ let got = s
+ .model
+ .as_ref()
+ .unwrap()
+ .lock()
+ .unwrap()
+ .embed(texts.clone(), None)
+ .expect("embed");
+ assert_eq!(got.len(), expected.len());
+ for ((text, got), expected) in texts.iter().zip(&got).zip(&expected) {
+ assert_eq!(got.len(), expected.len(), "{text}");
+ let worst = got
+ .iter()
+ .zip(expected)
+ .map(|(g, e)| (*g as f64 - e).abs())
+ .fold(0.0_f64, f64::max);
+ assert!(
+ worst <= max_abs_diff,
+ "{text:?}: max |rust - fixture| = {worst:e} > {max_abs_diff:e}"
+ );
+ }
}
#[cfg(feature = "ml")]
diff --git a/headroom/onnx_runtime.py b/headroom/onnx_runtime.py
index b456625a0..4330236eb 100644
--- a/headroom/onnx_runtime.py
+++ b/headroom/onnx_runtime.py
@@ -82,7 +82,10 @@ _PINNED_REVISIONS: dict[str, str] = {
# Third-party repo — pinning matters most here.
"Qdrant/all-MiniLM-L6-v2-onnx": "5f1b8cd78bc4fb444dd171e59b18f3a3af89a079",
# Default relevance embedder (BAAI/bge-small-en-v1.5), third-party too.
- # relevance/embedding.py downloads each of its files at this SHA.
+ # relevance/embedding.py downloads each of its files at this SHA. The Rust
+ # scorer loads the same snapshot: keep this SHA equal to
+ # DEFAULT_MODEL_REVISION in crates/headroom-core/src/relevance/embedding.rs
+ # (tests/test_fastembed_pinned_snapshot.py enforces it).
"Qdrant/bge-small-en-v1.5-onnx-Q": "52398278842ec682c6f32300af41344b1c0b0bb2",
}
diff --git a/headroom/relevance/embedding.py b/headroom/relevance/embedding.py
index b52b76152..5abd817aa 100644
--- a/headroom/relevance/embedding.py
+++ b/headroom/relevance/embedding.py
@@ -2,8 +2,12 @@
This module provides semantic relevance scoring using `fastembed`
(BAAI/bge-small-en-v1.5 by default — 33M params, 384 dims, ~67 MB
-quantized ONNX), loaded from a pinned Qdrant/bge-small-en-v1.5-onnx-Q
-snapshot in the HuggingFace hub cache.
+quantized ONNX). The Rust scorer (fastembed-rs crate) loads the same
+pinned Qdrant/bge-small-en-v1.5-onnx-Q snapshot, so both languages run
+the same ONNX file and tokenizer. On the same ONNX Runtime build the two
+agree within 1e-6 per component; across ORT versions they drift by up to
+~4e-4, so they are close, not byte-equal. The gated parity fixture in
+tests/parity/fixtures/embedding/ bounds that drift.
Key features:
- Semantic understanding ("errors" matches "failed", "issues")
@@ -16,8 +20,8 @@ Install with: pip install "headroom-ai[relevance]"
History: this module previously wrapped `sentence-transformers`
(PyTorch). Switched to fastembed in Stage 3c.1 of the Rust port to:
-1. Match the Rust embedding scorer byte-for-byte (both call into
- ONNX Runtime over the identical ONNX file).
+1. Run the same ONNX model as the Rust embedding scorer (both call
+ into ONNX Runtime over the identical pinned ONNX file).
2. Remove the torch dependency from the relevance/ path
(Phase 6: "drop torch from Python").
3. Get a better default model (bge-small-en-v1.5 vs MiniLM-L6-v2).
@@ -157,12 +161,14 @@ def _load_text_embedding(kwargs: dict[str, Any]) -> TextEmbedding:
return TextEmbedding(**kwargs)
-# Default model name. Same string used by the Rust embedding scorer.
+# Default model name. Same model the Rust embedding scorer loads.
DEFAULT_MODEL_NAME = "BAAI/bge-small-en-v1.5"
# The HF repo fastembed resolves DEFAULT_MODEL_NAME to, and every file a
# fastembed load of it reads. Its revision is pinned in
-# ``onnx_runtime._PINNED_REVISIONS`` (HEADROOM_HF_PIN=off floats it).
+# ``onnx_runtime._PINNED_REVISIONS`` (HEADROOM_HF_PIN=off floats it). The Rust
+# scorer loads the same snapshot: keep both equal to DEFAULT_MODEL_REPO and
+# DEFAULT_MODEL_FILES in crates/headroom-core/src/relevance/embedding.rs.
DEFAULT_MODEL_REPO = "Qdrant/bge-small-en-v1.5-onnx-Q"
DEFAULT_MODEL_FILES = (
"model_optimized.onnx",
@@ -182,9 +188,9 @@ def _resolve_default_model_snapshot() -> str:
here through ``hf_hub_download_local_first`` instead, which applies the
pinned SHA, tries the cache first and guards the network fallback.
- The files land in the standard HuggingFace hub cache rather than
- fastembed's default under the system temp dir, which macOS purges after a
- few idle days.
+ The files land in the standard HuggingFace hub cache, which the Rust
+ scorer searches too, rather than fastembed's default under the system temp
+ dir, which macOS purges after a few idle days.
Raises:
OfflineEgressBlocked: ``HEADROOM_OFFLINE`` is set and a file is not cached.
diff --git a/pyproject.toml b/pyproject.toml
index 3eb88bc8f..1cb0e02d4 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -177,8 +177,10 @@ pytorch-mps = [
]
# Semantic relevance scoring with embeddings.
# Uses `fastembed` (BAAI/bge-small-en-v1.5 by default — 33M params,
-# 384 dims, ~67 MB quantized ONNX), loaded from a pinned
-# Qdrant/bge-small-en-v1.5-onnx-Q snapshot. Replaced sentence-transformers in
+# 384 dims, ~67 MB quantized ONNX). The Rust scorer (`fastembed` crate)
+# loads the same pinned Qdrant/bge-small-en-v1.5-onnx-Q snapshot, so both
+# languages run the same ONNX file; tests/parity/fixtures/embedding/
+# bounds the remaining ONNX Runtime drift. Replaced sentence-transformers in
# Stage 3c.1 — fastembed is faster (~2-3x), smaller (no torch
# dependency), and outranks all-MiniLM-L6-v2 on MTEB by ~6 points.
# >=0.6.0 for `specific_model_path`, which the pinned-snapshot load needs.
diff --git a/tests/parity/fixtures/embedding/bge_small_en_v15_pinned.json b/tests/parity/fixtures/embedding/bge_small_en_v15_pinned.json
new file mode 100644
index 000000000..81f5cecdc
--- /dev/null
+++ b/tests/parity/fixtures/embedding/bge_small_en_v15_pinned.json
@@ -0,0 +1,22 @@
+{
+ "model": "BAAI/bge-small-en-v1.5",
+ "repo": "Qdrant/bge-small-en-v1.5-onnx-Q",
+ "revision": "52398278842ec682c6f32300af41344b1c0b0bb2",
+ "max_abs_diff": 0.001,
+ "texts": [
+ "login error",
+ "authentication failed for user admin: invalid credentials",
+ "{\"status\": \"failed\", \"error\": \"connection refused\", \"retries\": 3}",
+ "def retry(fn, attempts=3):\n for i in range(attempts):\n return fn()",
+ "Ünïcödé text, emoji 🚀 and CJK 中文 mixed in one line.",
+ "log line 0: request handled in 0 ms log line 1: request handled in 1 ms log line 2: request handled in 2 ms log line 3: request handled in 3 ms log line 4: request handled in 4 ms log line 5: request handled in 5 ms log line 6: request handled in 6 ms log line 7: request handled in 7 ms log line 8: request handled in 8 ms log line 9: request handled in 9 ms log line 10: request handled in 10 ms log line 11: request handled in 11 ms log line 12: request handled in 12 ms log line 13: request handled in 13 ms log line 14: request handled in 14 ms log line 15: request handled in 15 ms log line 16: request handled in 16 ms log line 17: request handled in 17 ms log line 18: request handled in 18 ms log line 19: request handled in 19 ms log line 20: request handled in 20 ms log line 21: request handled in 21 ms log line 22: request handled in 22 ms log line 23: request handled in 23 ms log line 24: request handled in 24 ms log line 25: request handled in 25 ms log line 26: request handled in 26 ms log line 27: request handled in 27 ms log line 28: request handled in 28 ms log line 29: request handled in 29 ms log line 30: request handled in 30 ms log line 31: request handled in 31 ms log line 32: request handled in 32 ms log line 33: request handled in 33 ms log line 34: request handled in 34 ms log line 35: request handled in 35 ms log line 36: request handled in 36 ms log line 37: request handled in 37 ms log line 38: request handled in 38 ms log line 39: request handled in 39 ms log line 40: request handled in 40 ms log line 41: request handled in 41 ms log line 42: request handled in 42 ms log line 43: request handled in 43 ms log line 44: request handled in 44 ms log line 45: request handled in 45 ms log line 46: request handled in 46 ms log line 47: request handled in 47 ms log line 48: request handled in 48 ms log line 49: request handled in 49 ms log line 50: request handled in 50 ms log line 51: request handled in 51 ms log line 52: request handled in 52 ms log line 53: request handled in 53 ms log line 54: request handled in 54 ms log line 55: request handled in 55 ms log line 56: request handled in 56 ms log line 57: request handled in 57 ms log line 58: request handled in 58 ms log line 59: request handled in 59 ms log line 60: request handled in 60 ms log line 61: request handled in 61 ms log line 62: request handled in 62 ms log line 63: request handled in 63 ms log line 64: request handled in 64 ms log line 65: request handled in 65 ms log line 66: request handled in 66 ms log line 67: request handled in 67 ms log line 68: request handled in 68 ms log line 69: request handled in 69 ms log line 70: request handled in 70 ms log line 71: request handled in 71 ms log line 72: request handled in 72 ms log line 73: request handled in 73 ms log line 74: request handled in 74 ms log line 75: request handled in 75 ms log line 76: request handled in 76 ms log line 77: request handled in 77 ms log line 78: request handled in 78 ms log line 79: request handled in 79 ms log line 80: request handled in 80 ms log line 81: request handled in 81 ms log line 82: request handled in 82 ms log line 83: request handled in 83 ms log line 84: request handled in 84 ms log line 85: request handled in 85 ms log line 86: request handled in 86 ms log line 87: request handled in 87 ms log line 88: request handled in 88 ms log line 89: request handled in 89 ms log line 90: request handled in 90 ms log line 91: request handled in 91 ms log line 92: request handled in 92 ms log line 93: request handled in 93 ms log line 94: request handled in 94 ms log line 95: request handled in 95 ms log line 96: request handled in 96 ms log line 97: request handled in 0 ms log line 98: request handled in 1 ms log line 99: request handled in 2 ms log line 100: request handled in 3 ms log line 101: request handled in 4 ms log line 102: request handled in 5 ms log line 103: request handled in 6 ms log line 104: request handled in 7 ms log line 105: request handled in 8 ms log line 106: request handled in 9 ms log line 107: request handled in 10 ms log line 108: request handled in 11 ms log line 109: request handled in 12 ms log line 110: request handled in 13 ms log line 111: request handled in 14 ms log line 112: request handled in 15 ms log line 113: request handled in 16 ms log line 114: request handled in 17 ms log line 115: request handled in 18 ms log line 116: request handled in 19 ms log line 117: request handled in 20 ms log line 118: request handled in 21 ms log line 119: request handled in 22 ms log line 120: request handled in 23 ms log line 121: request handled in 24 ms log line 122: request handled in 25 ms log line 123: request handled in 26 ms log line 124: request handled in 27 ms log line 125: request handled in 28 ms log line 126: request handled in 29 ms log line 127: request handled in 30 ms log line 128: request handled in 31 ms log line 129: request handled in 32 ms log line 130: request handled in 33 ms log line 131: request handled in 34 ms log line 132: request handled in 35 ms log line 133: request handled in 36 ms log line 134: request handled in 37 ms log line 135: request handled in 38 ms log line 136: request handled in 39 ms log line 137: request handled in 40 ms log line 138: request handled in 41 ms log line 139: request handled in 42 ms log line 140: request handled in 43 ms log line 141: request handled in 44 ms log line 142: request handled in 45 ms log line 143: request handled in 46 ms log line 144: request handled in 47 ms log line 145: request handled in 48 ms log line 146: request handled in 49 ms log line 147: request handled in 50 ms log line 148: request handled in 51 ms log line 149: request handled in 52 ms log line 150: request handled in 53 ms log line 151: request handled in 54 ms log line 152: request handled in 55 ms log line 153: request handled in 56 ms log line 154: request handled in 57 ms log line 155: request handled in 58 ms log line 156: request handled in 59 ms log line 157: request handled in 60 ms log line 158: request handled in 61 ms log line 159: request handled in 62 ms log line 160: request handled in 63 ms log line 161: request handled in 64 ms log line 162: request handled in 65 ms log line 163: request handled in 66 ms log line 164: request handled in 67 ms log line 165: request handled in 68 ms log line 166: request handled in 69 ms log line 167: request handled in 70 ms log line 168: request handled in 71 ms log line 169: request handled in 72 ms log line 170: request handled in 73 ms log line 171: request handled in 74 ms log line 172: request handled in 75 ms log line 173: request handled in 76 ms log line 174: request handled in 77 ms log line 175: request handled in 78 ms log line 176: request handled in 79 ms log line 177: request handled in 80 ms log line 178: request handled in 81 ms log line 179: request handled in 82 ms log line 180: request handled in 83 ms log line 181: request handled in 84 ms log line 182: request handled in 85 ms log line 183: request handled in 86 ms log line 184: request handled in 87 ms log line 185: request handled in 88 ms log line 186: request handled in 89 ms log line 187: request handled in 90 ms log line 188: request handled in 91 ms log line 189: request handled in 92 ms log line 190: request handled in 93 ms log line 191: request handled in 94 ms log line 192: request handled in 95 ms log line 193: request handled in 96 ms log line 194: request handled in 0 ms log line 195: request handled in 1 ms log line 196: request handled in 2 ms log line 197: request handled in 3 ms log line 198: request handled in 4 ms log line 199: request handled in 5 ms log line 200: request handled in 6 ms log line 201: request handled in 7 ms log line 202: request handled in 8 ms log line 203: request handled in 9 ms log line 204: request handled in 10 ms log line 205: request handled in 11 ms log line 206: request handled in 12 ms log line 207: request handled in 13 ms log line 208: request handled in 14 ms log line 209: request handled in 15 ms log line 210: request handled in 16 ms log line 211: request handled in 17 ms log line 212: request handled in 18 ms log line 213: request handled in 19 ms log line 214: request handled in 20 ms log line 215: request handled in 21 ms log line 216: request handled in 22 ms log line 217: request handled in 23 ms log line 218: request handled in 24 ms log line 219: request handled in 25 ms log line 220: request handled in 26 ms log line 221: request handled in 27 ms log line 222: request handled in 28 ms log line 223: request handled in 29 ms log line 224: request handled in 30 ms log line 225: request handled in 31 ms log line 226: request handled in 32 ms log line 227: request handled in 33 ms log line 228: request handled in 34 ms log line 229: request handled in 35 ms log line 230: request handled in 36 ms log line 231: request handled in 37 ms log line 232: request handled in 38 ms log line 233: request handled in 39 ms log line 234: request handled in 40 ms log line 235: request handled in 41 ms log line 236: request handled in 42 ms log line 237: request handled in 43 ms log line 238: request handled in 44 ms log line 239: request handled in 45 ms log line 240: request handled in 46 ms log line 241: request handled in 47 ms log line 242: request handled in 48 ms log line 243: request handled in 49 ms log line 244: request handled in 50 ms log line 245: request handled in 51 ms log line 246: request handled in 52 ms log line 247: request handled in 53 ms log line 248: request handled in 54 ms log line 249: request handled in 55 ms log line 250: request handled in 56 ms log line 251: request handled in 57 ms log line 252: request handled in 58 ms log line 253: request handled in 59 ms log line 254: request handled in 60 ms log line 255: request handled in 61 ms log line 256: request handled in 62 ms log line 257: request handled in 63 ms log line 258: request handled in 64 ms log line 259: request handled in 65 ms log line 260: request handled in 66 ms log line 261: request handled in 67 ms log line 262: request handled in 68 ms log line 263: request handled in 69 ms log line 264: request handled in 70 ms log line 265: request handled in 71 ms log line 266: request handled in 72 ms log line 267: request handled in 73 ms log line 268: request handled in 74 ms log line 269: request handled in 75 ms log line 270: request handled in 76 ms log line 271: request handled in 77 ms log line 272: request handled in 78 ms log line 273: request handled in 79 ms log line 274: request handled in 80 ms log line 275: request handled in 81 ms log line 276: request handled in 82 ms log line 277: request handled in 83 ms log line 278: request handled in 84 ms log line 279: request handled in 85 ms log line 280: request handled in 86 ms log line 281: request handled in 87 ms log line 282: request handled in 88 ms log line 283: request handled in 89 ms log line 284: request handled in 90 ms log line 285: request handled in 91 ms log line 286: request handled in 92 ms log line 287: request handled in 93 ms log line 288: request handled in 94 ms log line 289: request handled in 95 ms log line 290: request handled in 96 ms log line 291: request handled in 0 ms log line 292: request handled in 1 ms log line 293: request handled in 2 ms log line 294: request handled in 3 ms log line 295: request handled in 4 ms log line 296: request handled in 5 ms log line 297: request handled in 6 ms log line 298: request handled in 7 ms log line 299: request handled in 8 ms log line 300: request handled in 9 ms log line 301: request handled in 10 ms log line 302: request handled in 11 ms log line 303: request handled in 12 ms log line 304: request handled in 13 ms log line 305: request handled in 14 ms log line 306: request handled in 15 ms log line 307: request handled in 16 ms log line 308: request handled in 17 ms log line 309: request handled in 18 ms log line 310: request handled in 19 ms log line 311: request handled in 20 ms log line 312: request handled in 21 ms log line 313: request handled in 22 ms log line 314: request handled in 23 ms log line 315: request handled in 24 ms log line 316: request handled in 25 ms log line 317: request handled in 26 ms log line 318: request handled in 27 ms log line 319: request handled in 28 ms log line 320: request handled in 29 ms log line 321: request handled in 30 ms log line 322: request handled in 31 ms log line 323: request handled in 32 ms log line 324: request handled in 33 ms log line 325: request handled in 34 ms log line 326: request handled in 35 ms log line 327: request handled in 36 ms log line 328: request handled in 37 ms log line 329: request handled in 38 ms log line 330: request handled in 39 ms log line 331: request handled in 40 ms log line 332: request handled in 41 ms log line 333: request handled in 42 ms log line 334: request handled in 43 ms log line 335: request handled in 44 ms log line 336: request handled in 45 ms log line 337: request handled in 46 ms log line 338: request handled in 47 ms log line 339: request handled in 48 ms log line 340: request handled in 49 ms log line 341: request handled in 50 ms log line 342: request handled in 51 ms log line 343: request handled in 52 ms log line 344: request handled in 53 ms log line 345: request handled in 54 ms log line 346: request handled in 55 ms log line 347: request handled in 56 ms log line 348: request handled in 57 ms log line 349: request handled in 58 ms log line 350: request handled in 59 ms log line 351: request handled in 60 ms log line 352: request handled in 61 ms log line 353: request handled in 62 ms log line 354: request handled in 63 ms log line 355: request handled in 64 ms log line 356: request handled in 65 ms log line 357: request handled in 66 ms log line 358: request handled in 67 ms log line 359: request handled in 68 ms log line 360: request handled in 69 ms log line 361: request handled in 70 ms log line 362: request handled in 71 ms log line 363: request handled in 72 ms log line 364: request handled in 73 ms log line 365: request handled in 74 ms log line 366: request handled in 75 ms log line 367: request handled in 76 ms log line 368: request handled in 77 ms log line 369: request handled in 78 ms log line 370: request handled in 79 ms log line 371: request handled in 80 ms log line 372: request handled in 81 ms log line 373: request handled in 82 ms log line 374: request handled in 83 ms log line 375: request handled in 84 ms log line 376: request handled in 85 ms log line 377: request handled in 86 ms log line 378: request handled in 87 ms log line 379: request handled in 88 ms log line 380: request handled in 89 ms log line 381: request handled in 90 ms log line 382: request handled in 91 ms log line 383: request handled in 92 ms log line 384: request handled in 93 ms log line 385: request handled in 94 ms log line 386: request handled in 95 ms log line 387: request handled in 96 ms log line 388: request handled in 0 ms log line 389: request handled in 1 ms log line 390: request handled in 2 ms log line 391: request handled in 3 ms log line 392: request handled in 4 ms log line 393: request handled in 5 ms log line 394: request handled in 6 ms log line 395: request handled in 7 ms log line 396: request handled in 8 ms log line 397: request handled in 9 ms log line 398: request handled in 10 ms log line 399: request handled in 11 ms"
+ ],
+ "embeddings": [
+ [-0.00958575, -0.00990991, 0.01390562, -0.09716735, -0.0402747, 0.00719097, -0.00727697, -0.00701235, 0.03204511, -0.01980658, 0.00619534, -0.08176664, -0.00094601, 0.04850429, 0.01493763, -0.00433972, -0.0108493, -0.0036881, 0.01074345, 0.01585056, 0.02918725, -0.0117953, 0.00157612, -0.07594506, -0.02237336, 0.03715222, -0.03895162, -0.03045741, -0.11135082, -0.07774446, -0.06927672, -0.0480809, 0.02159274, -0.01406439, 0.0549874, -0.00412141, -0.01323746, 0.02229398, 0.02759955, -0.00084471, 0.0692238, 0.04810736, -0.039719, -0.05202369, 0.04620212, -0.03657006, -0.01829826, 0.01546686, 0.12140626, -0.04323841, 0.01735887, 0.0280494, -0.00037356, 0.02580015, 0.00054122, 0.08203126, 0.03082788, 0.05440525, -0.01607548, 0.01611517, 0.02126197, 0.04273564, -0.21423389, 0.07441029, -0.02396107, -0.03490298, 0.00844128, -0.02095766, -0.01198053, -0.00858682, -0.07102319, -0.02081212, -0.01373362, 0.07658015, 0.04710182, 0.04043347, 0.00666835, -0.02016381, 0.04157132, 0.02916079, -0.00130241, 0.01339623, -0.0202035, -0.0340562, 0.01693549, -0.01596963, -0.00651288, 0.0080642, 0.01417024, 0.01255608, 0.02302168, 0.00832882, 0.0475252, -0.0025734, -0.01325069, -0.03400328, 0.03810484, -0.01706779, -0.1061114, 0.30399197, 0.00656912, 0.02921371, -0.00749528, -0.00492188, -0.00155214, -0.03355343, -0.02868448, 0.02685862, -0.03625252, 0.02799647, 0.05379663, 0.03929562, 0.06885333, 0.03704637, 0.00120401, 0.05162677, 0.04043347, -0.02037551, -0.01065083, 0.03630545, 0.00582157, -0.00023154, -0.01856288, -0.01839088, -0.01264869, -0.06340222, -0.04352949, 0.10335939, -0.01549332, -0.00464403, 0.01451424, 0.07478075, -0.03162173, -0.02974295, 0.04733998, -0.02089151, 0.00988344, 0.05109753, -0.09314517, 0.01100807, -0.02542969, -0.13569558, -0.00891098, -0.02085182, -0.04702243, 0.01114699, 0.0143687, 0.0225586, -0.00033449, -0.02658077, 0.00749528, 0.03323589, -0.05236769, 0.00419418, 0.01236423, -0.01411731, 0.11547884, 0.02497984, 0.01513609, -0.03829008, -0.00509388, -0.11727823, -0.02124874, 0.01604902, -0.01028037, -0.02508569, -0.00533534, -0.00867282, -0.08271926, -0.02377583, -0.04053932, 0.03254789, -0.06165575, 0.00010156, 0.051468, 0.00385018, 0.07594506, -0.01952873, -0.03829008, 0.06753024, 0.00691312, -0.0087059, -0.0346119, -0.03852823, 0.03842238, -0.02976941, 0.00475649, -0.05064769, 0.05562248, 0.00313571, -0.06700101, -0.02233367, -0.07943801, -0.08314265, -0.02451676, -0.03873992, 0.00971806, -0.07298136, 0.01623425, -0.0464932, 0.10849296, 0.03604083, -0.00150501, 0.02942541, 0.01710749, 0.06848287, 0.00423387, 0.00560326, -0.03873992, -0.05631049, -0.07583922, 0.02415953, 0.1070111, 0.00652281, 0.00242621, 0.04141255, 0.01039283, 0.06483115, 0.03299773, 0.01696195, -0.03601437, 0.0560988, -0.07880293, -0.27604842, 0.03818423, 0.03310358, -0.06430192, -0.07869709, 0.02512538, -0.01340946, 0.01627394, -0.03855469, 0.03810484, 0.06520162, 0.02147367, 0.03159526, -0.03146296, 0.0229026, -0.01779549, -0.02425214, 0.00730343, -0.03313004, -0.03866054, -0.04741936, -0.05191785, 0.05392894, -0.04223287, 0.01657825, 0.0014463, 0.1384476, 0.0536114, 0.03532637, 0.00933436, -0.00787897, 0.11621977, 0.02744078, -0.12087703, 0.14014114, 0.04098917, -0.02369645, 0.06753024, -0.02733493, -0.07509829, -0.0136807, 0.04982737, 0.00869928, -0.02339214, 0.03299773, -0.02201613, -0.01477886, 0.02639554, -0.04419103, -0.00288102, 0.08822329, 0.00919544, 0.03720514, 0.05162677, 0.00444556, -0.02463584, -0.0069925, 0.03424143, 0.03008695, 0.07573337, 0.02460938, -0.0186555, 0.01049868, -0.05636341, -0.01923765, -0.03106603, -0.01950227, -0.05276462, 0.08711191, 0.01589025, -0.01463332, 0.05445817, 0.02378906, 0.03479713, -0.00858021, -0.01291992, -0.0108493, -0.02118259, 0.0314365, 0.00845451, 0.01536101, -0.09219255, 0.0732989, -0.01169607, -0.00514349, 0.06795364, -0.00168528, -0.00632104, 0.05953882, -0.0102936, -0.02577369, 0.02460938, -0.02515184, -0.03077495, 0.04800152, 0.04395288, -0.22862905, 0.01862903, 0.03556452, 0.05011845, 0.01676348, 0.00786574, 0.0011453, 0.01211946, -0.06509577, -0.05017138, 0.00205409, -0.02886971, 0.02717616, -0.00484911, 0.00695943, 0.01669733, -0.03228327, -0.03265373, 0.04800152, 0.01508317, 0.02704385, 0.02810232, 0.08377773, -0.05509325, -0.00241628, 0.03746976, 0.02992818, -0.04495842, 0.07234628, -0.01729272, 0.0074622, -0.01926412, 0.07790323, -0.01570502, 0.04339718, 0.03998362, 0.03490298, -0.11060989, 0.03400328, -0.04736644, -0.05451109, 0.05390247, 0.04503781, 0.02221459, 0.07314013, -0.04069809, 0.05562248, -0.03392389, -0.02459615, 0.00740266, -0.05895666, -0.0420741, -0.04088332, 0.04950983, -0.03342112, -0.01274792, 0.03601437, -0.04445565, -0.07589214, -0.08308972, 0.04130671, -0.01779549, 0.06954134, -0.04710182, -0.02507246],
+ [-0.01925702, -0.02807642, 0.01101076, -0.07454679, -0.05674618, -0.01713983, 0.01034997, -0.03293113, -0.03538545, -0.04026714, 0.01390335, -0.06553861, 0.06807385, 0.03187927, 0.09310258, 0.01040392, -0.04738738, 0.03255354, 0.01972901, 0.07411526, -0.00931835, 0.03988955, -0.00656397, -0.04050987, -0.08242221, 0.05391427, -0.05062385, -0.07125638, -0.07627291, -0.100061, -0.05496612, -0.04024016, -0.01715331, -0.00050907, 0.05286241, -0.05895777, -0.00790239, 0.04558035, 0.03924225, 0.01250762, 0.01944582, -0.01556205, -0.03918831, -0.02505571, 0.06872114, -0.04317996, -0.04183143, 0.06402825, 0.05831048, -0.04833135, 0.08199068, 0.02657955, 0.01933794, 0.11020195, 0.01039717, 0.01525189, 0.04598491, 0.06311125, -0.02904736, 0.00292294, -0.00027434, -0.0156025, -0.21910931, 0.05868807, -0.00131987, -0.00869128, 0.01076802, -0.0500305, -0.05831048, -0.07735174, -0.04274843, -0.07805298, -0.05167571, -0.01960764, 0.00123728, 0.06062995, -0.03549334, -0.00654038, 0.06149301, -0.01136812, 0.03182533, 0.01369433, 0.01187382, 0.02320822, -0.02384203, -0.02133376, -0.0137685, 0.01974249, -0.00248804, -0.00644935, 0.02190014, -0.0235049, 0.03077348, 0.04986868, 0.00419056, -0.00979033, -0.02416568, 0.00443667, -0.10054647, 0.30120787, 0.03031498, 0.02466463, -0.05933536, -0.0434227, 0.03649125, 0.02961374, 0.00203122, -0.03468422, 0.02591876, 0.03436057, 0.03347054, -0.02154952, 0.0272673, -0.03268839, 0.02915524, 0.04417787, -0.0182726, 0.03301204, -0.11651308, 0.01490127, 0.02559512, -0.010559, 0.05170268, 0.01123326, -0.03854102, -0.00058324, 0.00289091, 0.08857152, -0.00473671, 0.06661743, -0.01006004, 0.09596147, -0.02072692, 0.00891379, 0.0343336, 0.00219473, -0.02086177, 0.06267972, 0.02920918, 0.05507401, -0.01927051, -0.06861325, -0.04253267, -0.00652689, -0.00223688, 0.01728817, -0.00319265, 0.04549944, -0.02505571, 0.04331481, 0.05561342, 0.00656397, -0.01802986, 0.01515749, -0.0205651, -0.03174442, 0.03921528, 0.0600366, -0.00840135, -0.04326088, 0.02537935, -0.09671664, -0.05917354, 0.04237084, -0.00962851, -0.05998266, 0.02451629, 0.0051379, -0.0447982, -0.00317242, 0.0300183, -0.07168791, -0.01701846, -0.04282935, 0.00715396, 0.0010232, 0.0241387, -0.03552031, -0.04714464, 0.03036892, 0.00317916, -0.02288457, -0.06580831, -0.00550538, -0.00630101, 0.03614063, 0.05156783, -0.01643859, 0.03314689, 0.029371, -0.0852811, 0.00077498, -0.08905698, -0.12028897, 0.02853492, -0.02363975, 0.00020649, -0.06192454, 0.02912827, -0.06305731, 0.09277894, 0.03303901, 0.00620324, 0.00823952, 0.01638465, 0.06543072, -0.009406, -0.00274932, -0.00166459, -0.01564296, -0.06467555, 0.05523583, 0.01030278, -0.00097853, 0.00861037, 0.0072079, -0.03031498, 0.05011141, 0.05669224, 0.01978295, 0.03082742, 0.11802343, -0.01812426, -0.25611299, 0.03441451, -0.01700498, -0.03713854, -0.04331481, -0.00067595, 0.05199936, -0.00695168, -0.04485214, 0.00158031, 0.06499919, 0.00813838, 0.05647648, 0.03187927, 0.03338963, 0.00826649, -0.00394445, 0.07772933, -0.00168988, -0.03986258, -0.08830181, -0.02099663, 0.09067523, -0.00285214, -0.02668743, 0.01273688, 0.13442157, 0.0018576, 0.00778777, -0.03222989, 0.02177878, 0.08145127, -0.01612843, -0.15092759, 0.08571263, 0.04317996, -0.01130069, 0.0411302, 0.0618706, -0.04118413, -0.03870284, 0.03077348, -0.02749655, -0.01519794, -0.00115889, -0.04633553, -0.00622684, 0.02346444, -0.07810692, 0.0138629, 0.04552641, 0.03012618, 0.02252047, -0.00481088, -0.04965291, -0.01954021, 0.01901429, 0.03767795, 0.01121978, 0.0886794, 0.03935013, 0.00446701, -0.03757007, -0.01902777, 0.00566383, -0.04102231, -0.07945544, -0.0511363, 0.10157135, -0.04916744, 0.00478391, 0.05280847, -0.01177268, 0.01925702, 0.01921657, 0.00129796, 0.01057248, -0.04781891, 0.00549526, -0.02060555, -0.03730037, -0.07033937, 0.0413999, -0.00631787, 0.04129202, 0.0480077, -0.01657345, 0.0566383, 0.05032718, -0.01591267, -0.04682099, -0.0196481, 0.01937839, 0.02697062, -0.01248065, 0.03603275, -0.207458, 0.0217518, -0.03314689, -0.0067258, -0.02945192, -0.01732862, 0.00837438, -0.05127115, -0.08706116, 0.01564296, 0.02222379, -0.03681489, -0.03311992, -0.05922748, 0.01638465, 0.0268088, -0.07314432, 0.03659913, 0.06127725, -0.01511703, -0.06014448, 0.03641034, 0.06257184, -0.0566383, -0.02237213, 0.06241002, 0.07535591, 0.04148081, 0.06634773, -0.03303901, -0.02327565, 0.01204238, 0.08145127, 0.02123936, -0.00444678, 0.05426489, 0.00560315, -0.07362979, 0.07093273, -0.00623358, -0.03851404, 0.03012618, 0.04714464, -0.01250088, 0.04749526, -0.08668357, 0.08333921, -0.02103708, 0.07098667, 0.01944582, -0.00497945, -0.08609022, -0.00275437, 0.05000353, 0.00237847, 0.0714182, 0.02622893, 0.01384941, -0.03897255, -0.03932316, 0.01792198, 0.00516487, 0.06106148, -0.05793289, -0.01805683],
+ [-0.06524435, -0.04958571, 0.01320865, -0.01524587, 0.06087697, -0.02704312, -0.04513844, -0.00557906, -0.02637736, 0.00738326, 0.02129096, -0.0565096, 0.04188954, 0.01740293, 0.01862793, 0.05720199, -0.00681071, -0.03422, -0.03643031, 0.05533786, 0.0037915, 0.03677651, -0.02616432, -0.04596398, -0.0321162, 0.07323346, 0.02235618, -0.00843516, -0.0368564, -0.11759961, -0.04923951, -0.0602911, -0.07094324, 0.00295098, 0.02820154, -0.01516598, -0.00418762, -0.00154872, -0.00335875, 0.05832046, 0.00655439, 0.00122999, -0.04471235, -0.01025934, -0.00214707, -0.04284823, -0.02484611, 0.01306884, 0.0998638, -0.07813343, -0.02910697, -0.00826207, -0.02326161, -0.00294265, 0.04535148, 0.10774639, 0.02135754, 0.05816068, 0.0166706, -0.00164858, 0.02495264, -0.02471296, -0.12356481, 0.05366015, 0.08037039, 0.03131729, 0.00166107, -0.03720259, -0.00348525, -0.03752216, -0.01592495, 0.00386806, -0.01944015, 0.1230322, 0.01147102, 0.00795582, 0.00443062, -0.02788197, 0.032995, 0.04109063, -0.01422061, -0.03840096, -0.01687033, 0.00276956, -0.00566893, -0.08415189, -0.03989226, 0.06130306, 0.00106105, -0.01037252, -0.0132486, 0.0215839, 0.09224752, 0.01878771, -0.07200846, 0.01914722, -0.01484642, 0.00962021, -0.08468451, 0.3939161, 0.01037918, 0.02224965, 0.00144137, 0.01707005, 0.05597699, -0.00788258, -0.00392798, -0.01987955, 0.00506309, 0.03816129, 0.05067755, -0.03208957, 0.04428627, -0.04628354, -0.00940051, -0.00462369, -0.03395369, -0.00080765, -0.06535087, 0.05656286, -0.02665698, -0.01143108, 0.0415966, -0.02647056, 0.01986624, -0.05358026, 0.00212543, 0.09815945, 0.01900075, 0.05094386, 0.00678075, 0.02572492, -0.05030473, -0.0265904, -0.00451384, 0.00766288, -0.02138417, 0.00354184, 0.04726886, 0.05073081, -0.01416734, -0.0689726, -0.02661703, -0.02820154, -0.00834196, 0.02548524, -0.02977273, 0.11376484, -0.0135615, 0.00429747, -0.03736238, 0.01161083, -0.01556544, -0.01619125, -0.03965259, -0.02515236, 0.04327431, 0.01029263, 0.00995309, -0.00874807, -0.01262944, -0.08793341, -0.0481743, 0.0333412, -0.04455257, -0.04902647, 0.01912059, 0.02131759, -0.0248328, 0.00589196, -0.04838734, -0.02001271, -0.04995853, -0.0529145, 0.03720259, 0.00840187, 0.05126342, -0.02280889, 0.00445393, 0.02371432, -0.04702919, 0.00391466, -0.0612498, -0.01211681, 0.04180964, 0.01125132, 0.02806839, 0.0050864, 0.04409985, -0.03776183, -0.0650313, -0.03776183, -0.05139657, -0.05874655, 0.01800212, -0.05603025, 0.00094538, -0.04567105, 0.03246239, -0.02998577, 0.14135388, 0.03541836, 0.00962687, 0.01098502, 0.0027163, 0.04106399, -0.01338175, -0.01765592, 0.01135784, -0.05171613, -0.09432469, 0.03547162, 0.05895959, 0.02961295, 0.03914661, -0.03499227, 0.0181619, 0.06423239, 0.02921349, 0.03688303, -0.02750915, 0.06455196, -0.05592373, -0.32446414, 0.02115781, -0.00806899, -0.03704281, -0.04226236, 0.05943893, -0.00970676, -0.03504554, -0.05187592, 0.05874655, 0.0403716, 0.02548524, 0.04130367, 0.00923407, 0.02557845, -0.06146284, -0.0570422, 0.01410077, -0.01121803, 0.01495294, -0.02268906, -0.05640307, -0.01391436, -0.06306066, -0.04697593, 8.275e-05, 0.13837129, 0.02822817, -0.06220849, -0.07738779, 0.02335481, 0.10684095, 0.01529913, -0.07104976, 0.07270084, 0.0511569, -0.00292434, 0.03429989, 0.03030534, -0.01443365, -0.0552846, 0.05336722, 0.02203661, -0.02027901, 0.06082371, -0.05997154, 0.02234286, 0.03512543, -0.04724224, -0.01730973, 0.01758934, 0.01169072, 0.04359388, 0.02777545, -0.03911998, 0.03171674, -0.01216341, 0.02485943, 0.00441065, -0.00985323, 0.05190255, 0.01129127, 0.0243934, -0.01531245, 0.02165047, 0.02142411, 0.02390074, -0.0017809, 0.03698955, 0.01793554, -0.01030594, 0.04838734, 0.05264819, 0.01604478, 0.03672325, 0.04897321, -0.02565834, -0.08138234, 0.02467302, 0.00932062, 0.00206552, -0.03581782, 0.03182326, -0.02001271, 0.04119715, 0.02579149, 0.02651051, 0.00580209, 0.0233415, 0.00790256, -0.03275533, 0.00051929, -0.06135632, -0.03432652, 0.03706944, 0.03690966, -0.23541227, -0.00710364, -0.01865456, 0.00802239, 0.02081162, 0.04793463, 0.00507641, -0.03845422, -0.09347252, 0.010266, 0.00764957, 0.00798245, -0.05310091, -0.05560416, 0.0172032, 0.0392265, -0.01577848, -0.03174337, 0.03680314, -0.06013132, -0.0178157, 0.0630074, 0.15850383, -0.04433953, -0.03118414, 0.06162262, 0.04226236, 0.0764291, 0.00962021, -0.0027629, -0.05805416, -0.03706944, 0.05363352, 0.04593735, 0.01234317, -0.01251626, -0.01675049, -0.04050476, 0.06764108, -0.04881343, -0.05033135, 0.06114328, 0.05496503, 0.03107761, 0.05991828, -0.01635103, 0.01838825, -0.02327492, 0.03523195, -0.00018007, -0.06769434, -0.0814356, 0.06018458, 0.01094507, -0.00084218, 0.00695718, 0.02063852, -0.00057463, -0.02368769, -0.01411408, 0.03134392, -0.04748191, 0.04567105, -0.02208987, -0.02788197],
+ [-0.11326776, -0.03719082, -0.00411907, 0.01378762, 0.02482037, 0.0494818, 0.02181385, 0.02558855, 0.03072746, -0.04746862, 0.0308599, -0.06325617, -0.01652925, 0.03173405, -0.03462137, 0.04190589, -0.02717791, 0.0286613, -0.03393265, 0.00286414, -0.00569517, 0.03406509, 0.03981325, 0.00121436, 0.00635409, 0.03146916, 0.03128373, -0.05997152, -0.02573424, -0.1829873, 0.02942949, -0.04913744, -0.03194596, -0.07628886, -0.04153505, -0.00109102, -0.08757325, 0.01891328, -0.02209198, 0.08926856, 0.01576107, 0.06071322, -0.05133604, -0.01756233, -0.05059434, -0.00119201, -0.04119068, 0.0158008, 0.05880599, -0.03520413, -0.00932419, -0.02268799, 0.02982682, -0.02414489, 0.06097811, 0.02590642, 0.05668686, 0.07623588, 0.01688686, 0.03983974, 0.01827754, 0.02569451, -0.07125591, -0.05287242, 0.08195754, 0.03602529, 0.01954902, -0.051442, 0.00943015, 0.10309591, -0.0301182, -0.02455548, -0.04566736, 0.08185159, -0.01343664, 0.01200622, -0.06156087, 0.00133356, 0.02268799, 0.0296414, -0.01031754, -0.03083341, 0.01081421, 0.02937651, 0.01950929, -0.09096386, 0.01052283, 0.05742856, 0.05944173, 0.00456276, -0.0046919, 0.04399854, 0.01680739, 0.00233602, -0.04495215, -0.04884606, 0.01684712, 0.04762756, -0.06071322, 0.35643849, 0.02844939, 0.03679348, -0.04685937, 0.0536406, 0.02619781, -0.04675341, -0.02258203, -0.0301182, -0.03406509, -0.02078077, 0.03976027, -0.02184033, 0.08582497, -0.07750736, -0.05226316, 0.09355981, -0.00594682, -0.03170756, 0.00737724, -0.00319526, -0.00678785, -0.01070163, 0.05795834, -0.02564153, -0.02961491, 0.02319128, -0.01002616, 0.08953345, -0.03451541, 0.05226316, -0.02213171, -0.05891195, -0.02240985, -0.04206483, 0.00016566, 0.04060792, -0.02613158, -0.00660574, -0.0065031, -0.01467501, 0.0367405, -0.07973245, 0.07316313, 0.00585742, -0.02442303, 0.0504619, -0.03459488, 0.04534949, -0.02770769, -0.0722625, -0.00425814, -0.01366842, -0.04097877, -0.09901658, 0.01269494, -0.00325983, 0.07565311, -0.01863514, -0.02615807, 0.03989271, -0.0480249, -0.04166749, -0.04100526, 0.0624615, 0.01091354, -0.01490017, 0.03459488, 0.02088672, -0.07072613, -0.02099268, 0.03242276, -0.04071388, -0.01682063, -0.02471441, 0.03308499, 0.03141617, -0.05178636, -0.05125657, 0.05822323, 0.06664679, -0.04765405, -0.01081421, 0.02304559, 7.015e-05, 0.00458263, 0.00476143, 0.01576107, 0.02336346, 0.00822489, 0.03022416, -0.07819608, 0.00210258, -0.01875434, -0.00506937, -0.05891195, -0.08132181, -0.03184, 0.01393331, -0.00184265, -0.03523062, 0.05541538, 0.01067514, 0.0243833, 0.01697957, 0.04799841, 0.04638257, 0.02166815, -0.03078043, 0.02770769, 0.0115228, -0.06797125, 0.03642263, 0.04979967, -0.06304426, -0.03642263, -0.03189298, 0.02446276, 0.00638058, -0.01056256, 0.02271448, 0.02602562, 0.0083176, 0.01358895, -0.30833414, -0.04058143, 0.00598987, -0.02591967, 0.07549418, 0.00254627, -0.01328433, 0.00541373, -0.04119068, 0.0160392, 0.01962849, -0.00269362, -0.02349591, 0.03878017, 0.05636899, -0.05589218, -0.05515049, -0.02361511, -0.02017152, 0.01270156, -0.01007914, 0.01442336, 0.01781398, -0.07167974, 0.00150823, 0.04450183, 0.18478857, 0.00537068, 0.04174696, -0.06357405, 0.02810503, 0.02127082, -0.0269395, 0.04868712, 0.02195954, 0.03059501, -0.01390682, 0.0879441, 0.04304493, -0.01240356, 0.00637065, 0.03538955, 0.05406443, -0.01317175, 0.00936393, -0.03459488, -0.00788053, -0.03422403, -0.0181186, 0.04564087, 0.02209198, 0.02688652, 0.00825138, -0.00964869, 0.00296513, 0.01318499, -0.05742856, -0.00675474, -0.01768153, -0.00372173, 0.0301182, 0.03915102, 0.02214496, -0.01148306, 0.01062216, 0.01572133, 0.02207874, 0.01074137, 0.01249627, 0.04333631, 0.00697328, 0.02234363, 0.0056124, -0.0301182, 0.00611238, 0.01374789, -0.02050263, -0.01192013, -0.0061488, -0.04672692, 0.02089997, -0.0288997, -0.04640906, -0.01923115, 0.0253634, -0.01126453, 0.00170359, 0.0534022, 0.06277937, -0.00391709, -0.02818449, 0.00919175, -0.01443661, 0.0742227, 0.0350452, 0.00174001, -0.26764673, -0.0387007, 0.00092215, 0.05790536, 0.01073474, 0.04010463, -0.00577795, 0.0161584, -0.11761199, -0.03891261, -0.01425118, 0.03340286, -0.00223834, -0.02741631, 0.0394424, 0.00224993, -0.02042316, 0.04431641, -0.00463892, -0.04815734, 0.0521837, 0.08386476, 0.16179594, -0.0801033, 0.00316711, 0.03334989, 0.02327075, -0.03883315, 0.03432998, -0.04325684, 0.0156816, -0.05279295, 0.00162163, -0.00035574, 0.05382603, 0.02011854, -0.03989271, 0.00713221, 0.05075328, -0.07655375, -0.06256746, 0.01105261, -0.01851594, -0.01552266, 0.11189032, -0.06479255, -0.02921757, -0.01692659, 0.00423827, 0.05091222, -0.05748153, -0.03051554, 0.07003741, -0.00817854, 0.05348167, 0.04601172, -0.04879308, 0.04005165, -0.07284527, -0.01220489, 0.01503261, -0.03417105, 0.10542696, -0.01986689, -0.04974669],
+ [-0.04962855, 0.03222805, 0.03411134, -0.02848801, -0.0272148, -0.00472479, -0.03572937, -0.00872014, 0.02079571, 0.03177712, -0.00917107, -0.00411803, 0.05957548, -0.02928376, 0.0911404, 0.01546416, 0.01308353, -0.04774527, -0.07448261, 0.04445615, 0.03384609, 0.01895222, 0.03766571, -0.0456763, -0.00559681, 0.00794428, -0.01248671, -0.03562327, 0.01962861, -0.16063629, -0.01076921, 0.04193626, 0.03103442, 0.02607422, 0.02481427, 0.0199867, 0.00658818, 0.02107423, -0.00429044, -0.01039123, -0.02408483, -0.01992038, -0.00542771, 0.01489387, 0.03031824, -0.09209531, -0.06700252, 0.02177715, -0.04302379, 0.00219164, 0.00525861, -0.03267898, 0.07931019, -0.01146549, 0.02673735, 0.04801052, 0.0814322, 0.05549061, 0.002374, 0.02384611, -0.01860739, 0.06790438, -0.09400512, 0.0999998, 0.01215515, -0.03806359, -0.02936334, -0.00620025, 0.02891241, 0.0635012, -0.06583542, -0.00927054, -0.03647208, 0.06153834, -0.02909809, 0.0233156, 0.02076919, 0.00023893, -0.05278504, -0.02677714, -0.02600791, 0.05697602, -0.03323601, -0.02210871, 0.00096983, -0.00718168, -0.05925718, 0.02180367, -0.00797081, -0.02952249, -0.01781164, -0.05618026, 0.04872669, 0.02596812, -0.04111398, -0.05100786, 0.01275196, -0.01815646, 0.01880633, 0.35946879, -0.0399734, -0.03994687, 0.06445611, -0.04066305, 0.06933673, -0.03204238, 0.00071121, -0.05517231, 0.00422081, -0.00769892, -0.03912459, -0.06668422, 0.01399202, -0.01081563, -0.0094098, -0.01708219, 0.02301056, 0.04273201, 0.00863393, 0.02705565, -0.01328247, 0.02328908, -0.06519881, -0.04206888, -0.05384605, 0.01009945, 0.03525192, 0.09257276, 0.03870019, 0.00335212, 0.03307686, 0.00929043, 0.02015911, -0.01337531, -0.03002647, 0.03877977, -0.05005295, -0.01010608, 0.02523868, -0.01305037, 0.00111903, -0.07485396, 0.00573275, -0.01648538, -0.03042434, 0.05697602, -0.04660468, 0.04132618, 0.00748672, 0.00758619, 0.02683019, 0.04392564, -0.01985407, -0.00692969, -0.00750662, -0.01217504, 0.06143224, 0.00550728, -0.03244025, 0.00342838, 0.06779827, -0.06403171, -0.06896538, 0.08541097, -0.0096021, -0.06100784, 0.00440649, 0.02575592, -0.03578242, -0.06742692, 0.02542435, -0.03920417, 0.00327751, 0.05005295, 0.01706893, -0.01541111, -0.04371344, -0.01698936, 0.03318296, 0.03151187, -0.00353116, -0.03400524, -0.01088194, 0.06238715, 0.03169755, -0.05355427, -0.01183685, 0.00564986, 0.07564972, 0.02348802, 0.00355437, -0.00334548, 0.02538457, -0.02470817, -0.06620677, -0.00258952, 0.0079907, -0.05580891, -0.01749333, -0.06944283, 0.11437643, 0.03148535, -0.00820953, -0.04185668, -0.01876654, -0.05413783, 0.00623341, -0.02034479, 0.05575586, 0.02192303, -0.04360734, 0.01843498, 0.05724127, -0.0412466, 0.03535802, -0.00358089, 0.00440649, 0.02965511, 0.07177705, -0.01243366, -0.08334201, -0.01480103, -0.11819606, -0.30705509, -0.03421744, 0.03848799, -0.01842172, -0.02702913, -0.00729442, 0.00642572, 0.0267904, 0.09872659, 0.091777, 0.06302375, 0.00529508, -0.05193624, -0.03999992, 0.00387267, 0.00144479, 0.02354107, 0.0038992, 0.05554366, 0.05936328, -0.00868035, 0.02153842, -0.01354772, -0.02653841, 0.03384609, 0.01623339, 0.1089653, 0.03801053, -0.00412798, -0.02034479, -0.00898539, 0.07803698, 0.01636602, -0.09660459, 0.02984079, 0.05915108, -0.02112728, 0.03514582, -0.04641901, 0.05175056, 0.00200265, -0.03251983, 0.01249334, -0.05007948, 0.05655161, -0.05920413, -0.04758611, -0.05602111, -0.04084872, 0.03602115, -0.02197608, -0.01737397, -0.0246286, 0.05660466, -0.02045089, 0.01982755, -0.03281161, -0.01013924, 0.05543756, -0.03148535, -0.00085461, -0.05665771, 0.04931025, -0.04350124, -0.01795752, 0.01970818, 0.01734745, 0.02745353, 0.0271087, 0.05952243, -0.090716, 0.06806353, -0.03159145, 0.03408481, 0.02293099, 0.04867364, -0.02734743, -0.01047743, -0.00109582, 0.02184346, 0.02891241, 0.03679038, 0.03984077, 0.04371344, 0.00182195, -0.02557024, 0.02896546, -0.00184184, 0.02944291, -0.01738723, -0.00289621, -0.01113393, 0.02171083, -0.00370689, 0.0312201, 0.02241375, -0.30259886, 0.03734741, 0.0225729, 0.03785139, 0.04464182, 0.04384607, -0.01702914, -0.07607412, -0.07114045, 0.08408471, -0.02737395, 0.02994689, 0.00740052, -0.11554354, -0.01028513, -0.01363393, 0.0817505, -0.03567632, 0.01937662, -0.01592835, 0.03273203, -0.02652515, 0.20318262, -0.03641903, -0.03824926, -0.03066307, 0.03405829, 0.00933022, 0.04453572, 0.00361074, 0.0098342, 0.02184346, 0.0725728, 0.04464182, 0.01173075, 0.03047739, 0.00075887, -0.02026521, -0.01183022, 0.00427055, -0.04671078, 0.06037124, -0.06896538, -0.08694943, 0.02628642, 0.05137921, 0.0123143, 0.00933685, -0.00381631, -0.05899193, -0.01876654, -0.03419092, -0.04864712, 0.00830237, 0.00440317, 0.02660472, -0.03999992, -0.05697602, 0.00355105, -0.04206888, -0.01704241, -0.01900527, 0.00192639, 0.0186737, -0.01324268],
+ [-0.02941449, 0.0083443, -0.01961409, -0.04741956, -0.00110121, -0.01527904, 0.0005531, -0.02994639, 0.00684166, 0.02140928, 0.0903179, -0.01220728, -0.04146219, 0.01598382, -0.02571773, 0.01310487, -0.00436164, -0.06021193, -0.02260607, 0.07079689, 0.09999862, -0.01077778, 0.0132578, -0.00480379, 0.02430817, 0.02591719, -0.02394914, -0.04287175, -0.06590334, -0.20563546, -0.01539872, 0.00193481, 0.01226712, -0.01486682, -0.00261466, 0.02252628, 0.03401549, 0.03986647, -0.00052069, 0.00248667, 0.05390883, 0.05412159, 0.03630269, -0.03178148, -0.01102378, -0.07329686, -0.05468009, -0.01658222, -0.00309836, -0.00660563, -0.06569058, 0.01341072, -0.04566426, 0.0362495, 0.0293613, 0.00475392, 0.01211419, -0.02650229, -0.00050988, -0.00196972, 0.07148837, 0.01485352, -0.13531728, 0.03646226, 0.03718034, 0.00439489, -0.04231324, -0.01405566, 0.00026533, 0.09967947, -0.04587702, -0.01751306, -0.0236167, 0.0029471, -0.00708767, -0.00509966, 0.00436497, 0.01699445, -0.06292466, -0.08372225, -0.07856274, 0.0581375, 0.04015902, -0.0149865, 0.00127824, 0.04741956, -0.00837089, 0.0178588, 0.06249914, 0.02861663, 0.0235901, -0.02107684, -0.04390897, 0.0305049, -0.06829693, -0.0068749, -0.02001302, 0.04885571, -0.00224565, 0.4108454, 0.05606306, -0.02845705, 0.06031832, 0.03132936, 0.01646254, 0.00885626, -0.00609699, -0.04015902, -0.02925492, -0.01913537, 0.0036203, -0.00907567, 0.01757954, -0.0259039, 0.00481709, 0.01652903, 0.00173867, 0.01884283, -0.0552652, -0.05297799, 0.0206912, -0.0166753, 0.02566454, -0.02752621, 0.02901556, -0.0178455, 0.06999903, 0.1006901, 0.04013243, 0.0310634, 0.01912208, -0.01914867, -0.0373931, -0.02207416, -0.04574405, -0.03061128, 0.03430803, -0.00391949, -0.01972047, 0.03398889, -0.02922832, -0.11414736, 0.00797196, -0.11297716, -0.04747275, 0.13701938, -0.00948125, 0.02057152, -0.04390897, -0.08377544, 0.02978682, 0.05039824, 0.01113017, -0.07845636, 0.03241976, 0.02441456, 0.01893591, 0.05228651, -0.01730029, 0.02249969, -0.01242669, -0.06255233, 0.05388223, 0.12308341, 0.04015902, -0.08292439, 0.00690815, 0.01075118, -0.02659538, 0.01309157, -0.00264292, -0.01997313, -0.01405566, 0.00973391, -0.0178322, 0.05856302, 0.02712728, -0.01429502, -0.032207, -0.00789218, -0.03473356, -0.04449407, 0.01134293, 0.03029213, 0.05968003, -0.0103456, -0.07031818, 0.04970676, 0.01634286, -0.01545191, -0.08590307, -0.04343025, 0.00591082, 0.02268586, 0.02081088, 0.03361656, -0.01481363, -0.00607704, -0.00286898, -0.02563794, 0.1271259, 0.06106299, -0.04194091, -0.00704113, 0.00672863, 0.06967989, -0.0132445, 0.03914839, 0.01468065, 0.00961423, -0.06622249, -0.0144014, 0.00995332, -0.03143574, -0.01760614, -0.02202097, 0.01988005, -0.02688793, 0.00627983, 0.05425457, -0.03864308, 0.00444143, 0.0184173, -0.2882939, -0.02752621, 0.05135567, 0.00068317, -0.01909548, -0.09079662, -0.01586414, -0.02256618, 0.01542532, 0.02861663, 0.04114305, -0.02715388, 0.05489286, -0.03518568, 0.03343039, 0.03183467, 0.01760614, -0.00386298, -0.01477373, -0.02441456, 0.01543862, 0.02160874, -0.00557173, 0.0247603, 0.03114319, -0.00072182, 0.09366892, -0.07170114, -0.0126328, -0.06893522, -0.01013284, 0.02624964, 0.01089746, -0.01749976, 0.0500525, -0.01993323, -0.05207375, 0.00580112, 0.07585002, -0.06936074, -0.00412228, 0.04249941, 0.00565817, -0.01550511, -0.03529207, -0.00125414, -0.05050462, -0.10616875, -0.05398862, -0.01230701, -0.03005278, -0.00306844, -0.03170169, 0.01349051, 0.02747303, -0.03146233, -0.03840372, -0.05329714, -0.03991966, -0.0080318, -0.01357029, 0.00291718, 0.0247204, -0.050611, 0.00282576, -0.00904908, 0.00332442, 0.03965371, 0.0126727, 0.00209605, -0.01325115, 0.01569127, 0.01502639, 0.01410885, 0.02984001, 0.05803111, -0.07037137, -0.0437494, -0.03319103, 0.0351059, 0.05686092, -0.00279085, 0.05055781, 0.03704736, 0.02440126, 0.07829679, -0.02216725, 0.00109124, 0.01696785, 0.05712687, 0.03872287, -0.01948111, -0.00993337, -0.05148865, 0.10345602, 0.03619631, -0.25297523, 0.03345698, -0.02869641, 0.02215395, -0.00113363, 0.04018562, -0.00199133, 0.01960079, -0.0247337, 0.01643594, 0.03667502, 0.04816423, 0.04999931, -0.02429488, 0.02787196, -0.00322635, 0.04994612, -0.08148824, 0.01691466, -0.01825773, 0.00432175, 0.01412215, 0.14063635, 0.02321776, 0.03178148, 0.00467414, -0.03747289, 0.03460059, 0.07866912, -0.00590417, 0.02581081, -0.04853657, 0.10287092, 0.00857036, 0.0574992, -0.02323106, 0.02744643, -0.01448118, -0.01335753, -0.01511947, -0.04111645, 0.02343053, 0.01507958, 0.01581095, 0.00856371, -0.00287729, -0.03372294, -0.08622222, -0.00995332, 0.03901542, 0.00595404, -0.06521186, 0.01470724, -0.00726719, 0.03952073, 0.04303132, 0.00116022, -0.00556508, -0.09398806, -0.01191473, -0.02398903, 0.01537213, 0.0793606, 0.00346405, -0.02928151]
+ ]
+}
diff --git a/tests/parity/fixtures/hf_hub_cache/cases.json b/tests/parity/fixtures/hf_hub_cache/cases.json
new file mode 100644
index 000000000..0bb5c85a1
--- /dev/null
+++ b/tests/parity/fixtures/hf_hub_cache/cases.json
@@ -0,0 +1,279 @@
+{
+ "description": "Cases both languages are checked against so Rust's hf_hub_cache_dir() names the directory huggingface_hub would. tests/test_fastembed_pinned_snapshot.py checks them against Python's posixpath/ntpath and huggingface_hub.constants; crates/headroom-core/src/relevance/embedding.rs checks its port against the same file.",
+ "expandvars": {
+ "comment": "posix = posixpath.expandvars, nt = ntpath.expandvars, with env set and unset absent (identical on CPython 3.10, 3.11, 3.13).",
+ "env": {
+ "HEADROOM_EV_A": "x",
+ "HEADROOM_EV_B_C": "y$HEADROOM_EV_A",
+ "HEADROOM_EV_D-E": "z"
+ },
+ "unset": "HEADROOM_EV_UNSET",
+ "cases": [
+ {
+ "input": "plain/path",
+ "posix": "plain/path",
+ "nt": "plain/path"
+ },
+ {
+ "input": "$HEADROOM_EV_A",
+ "posix": "x",
+ "nt": "x"
+ },
+ {
+ "input": "${HEADROOM_EV_A}",
+ "posix": "x",
+ "nt": "x"
+ },
+ {
+ "input": "$HEADROOM_EV_A/$HEADROOM_EV_B_C",
+ "posix": "x/y$HEADROOM_EV_A",
+ "nt": "x/y$HEADROOM_EV_A"
+ },
+ {
+ "input": "$$HEADROOM_EV_A",
+ "posix": "$x",
+ "nt": "$HEADROOM_EV_A"
+ },
+ {
+ "input": "$",
+ "posix": "$",
+ "nt": "$"
+ },
+ {
+ "input": "a$",
+ "posix": "a$",
+ "nt": "a$"
+ },
+ {
+ "input": "$/x",
+ "posix": "$/x",
+ "nt": "$/x"
+ },
+ {
+ "input": "${HEADROOM_EV_A",
+ "posix": "${HEADROOM_EV_A",
+ "nt": "${HEADROOM_EV_A"
+ },
+ {
+ "input": "${}",
+ "posix": "${}",
+ "nt": "${}"
+ },
+ {
+ "input": "$HEADROOM_EV_UNSET/x",
+ "posix": "$HEADROOM_EV_UNSET/x",
+ "nt": "$HEADROOM_EV_UNSET/x"
+ },
+ {
+ "input": "${HEADROOM_EV_UNSET}/x",
+ "posix": "${HEADROOM_EV_UNSET}/x",
+ "nt": "${HEADROOM_EV_UNSET}/x"
+ },
+ {
+ "input": "%HEADROOM_EV_A%/x",
+ "posix": "%HEADROOM_EV_A%/x",
+ "nt": "x/x"
+ },
+ {
+ "input": "%%HEADROOM_EV_A%%",
+ "posix": "%%HEADROOM_EV_A%%",
+ "nt": "%HEADROOM_EV_A%"
+ },
+ {
+ "input": "%HEADROOM_EV_A",
+ "posix": "%HEADROOM_EV_A",
+ "nt": "%HEADROOM_EV_A"
+ },
+ {
+ "input": "%HEADROOM_EV_UNSET%/x",
+ "posix": "%HEADROOM_EV_UNSET%/x",
+ "nt": "%HEADROOM_EV_UNSET%/x"
+ },
+ {
+ "input": "'$HEADROOM_EV_A'/$HEADROOM_EV_A",
+ "posix": "'x'/x",
+ "nt": "'$HEADROOM_EV_A'/x"
+ },
+ {
+ "input": "'$HEADROOM_EV_A",
+ "posix": "'x",
+ "nt": "'$HEADROOM_EV_A"
+ },
+ {
+ "input": "$HEADROOM_EV_D-E",
+ "posix": "$HEADROOM_EV_D-E",
+ "nt": "z"
+ },
+ {
+ "input": "${HEADROOM_EV_D-E}",
+ "posix": "z",
+ "nt": "z"
+ },
+ {
+ "input": "$HEADROOM_EV_A-x",
+ "posix": "x-x",
+ "nt": "$HEADROOM_EV_A-x"
+ },
+ {
+ "input": "~$HEADROOM_EV_A",
+ "posix": "~x",
+ "nt": "~x"
+ },
+ {
+ "input": "é/$HEADROOM_EV_A/é",
+ "posix": "é/x/é",
+ "nt": "é/x/é"
+ }
+ ]
+ },
+ "cache_dir": {
+ "comment": "{root} and {home} are temporary directories; HOME and USERPROFILE are set to {home}, every other cache variable is cleared first. expected may be {posix, nt}.",
+ "probe_vars": [
+ "HEADROOM_HF_PROBE_ROOT",
+ "HEADROOM_HF_PROBE_UNSET"
+ ],
+ "cases": [
+ {
+ "name": "HF_HUB_CACHE through ${VAR} (the #4190 review case)",
+ "env": {
+ "HEADROOM_HF_PROBE_ROOT": "{root}",
+ "HF_HUB_CACHE": "${HEADROOM_HF_PROBE_ROOT}/hub"
+ },
+ "expected": "{root}/hub"
+ },
+ {
+ "name": "HF_HUB_CACHE through $VAR",
+ "env": {
+ "HEADROOM_HF_PROBE_ROOT": "{root}",
+ "HF_HUB_CACHE": "$HEADROOM_HF_PROBE_ROOT/hub"
+ },
+ "expected": "{root}/hub"
+ },
+ {
+ "name": "legacy HUGGINGFACE_HUB_CACHE through ${VAR}",
+ "env": {
+ "HEADROOM_HF_PROBE_ROOT": "{root}",
+ "HUGGINGFACE_HUB_CACHE": "${HEADROOM_HF_PROBE_ROOT}/legacy"
+ },
+ "expected": "{root}/legacy"
+ },
+ {
+ "name": "HF_HOME through ${VAR}",
+ "env": {
+ "HEADROOM_HF_PROBE_ROOT": "{root}",
+ "HF_HOME": "${HEADROOM_HF_PROBE_ROOT}/hf-home"
+ },
+ "expected": "{root}/hf-home/hub"
+ },
+ {
+ "name": "XDG_CACHE_HOME through ${VAR}",
+ "env": {
+ "HEADROOM_HF_PROBE_ROOT": "{root}",
+ "XDG_CACHE_HOME": "${HEADROOM_HF_PROBE_ROOT}/xdg"
+ },
+ "expected": "{root}/xdg/huggingface/hub"
+ },
+ {
+ "name": "HF_HUB_CACHE still wins over an expanded HF_HOME",
+ "env": {
+ "HEADROOM_HF_PROBE_ROOT": "{root}",
+ "HF_HOME": "${HEADROOM_HF_PROBE_ROOT}/hf-home",
+ "HF_HUB_CACHE": "{root}/explicit"
+ },
+ "expected": "{root}/explicit"
+ },
+ {
+ "name": "an unset variable stays literal",
+ "env": {
+ "HF_HUB_CACHE": "{root}/${HEADROOM_HF_PROBE_UNSET}/hub"
+ },
+ "expected": "{root}/${HEADROOM_HF_PROBE_UNSET}/hub"
+ },
+ {
+ "name": "leading ~ in HF_HUB_CACHE",
+ "env": {
+ "HF_HUB_CACHE": "~/models"
+ },
+ "expected": "{home}/models"
+ },
+ {
+ "name": "leading ~ in HF_HOME",
+ "env": {
+ "HF_HOME": "~/hf"
+ },
+ "expected": "{home}/hf/hub"
+ },
+ {
+ "name": "a ~ that a variable produces in HF_HUB_CACHE stays literal (expanduser runs first)",
+ "env": {
+ "HEADROOM_HF_PROBE_ROOT": "~/r",
+ "HF_HUB_CACHE": "${HEADROOM_HF_PROBE_ROOT}/hub"
+ },
+ "expected": "~/r/hub"
+ },
+ {
+ "name": "a ~ that a variable produces in HF_HOME expands on the second pass",
+ "env": {
+ "HEADROOM_HF_PROBE_ROOT": "~/r",
+ "HF_HOME": "${HEADROOM_HF_PROBE_ROOT}/hf"
+ },
+ "expected": "{home}/r/hf/hub"
+ },
+ {
+ "name": "%VAR% is a variable on Windows only",
+ "env": {
+ "HEADROOM_HF_PROBE_ROOT": "{root}",
+ "HF_HUB_CACHE": "%HEADROOM_HF_PROBE_ROOT%/hub"
+ },
+ "expected": {
+ "posix": "%HEADROOM_HF_PROBE_ROOT%/hub",
+ "nt": "{root}/hub"
+ }
+ },
+ {
+ "name": "an empty HF_HUB_CACHE is the working directory, not HF_HOME (the #4438 review case)",
+ "env": {
+ "HF_HUB_CACHE": "",
+ "HF_HOME": "{root}/fallback-home"
+ },
+ "expected": ""
+ },
+ {
+ "name": "an empty legacy HUGGINGFACE_HUB_CACHE is the working directory",
+ "env": {
+ "HUGGINGFACE_HUB_CACHE": "",
+ "HF_HOME": "{root}/fallback-home"
+ },
+ "expected": ""
+ },
+ {
+ "name": "an empty HF_HUB_CACHE still wins over a set legacy HUGGINGFACE_HUB_CACHE",
+ "env": {
+ "HF_HUB_CACHE": "",
+ "HUGGINGFACE_HUB_CACHE": "{root}/legacy"
+ },
+ "expected": ""
+ },
+ {
+ "name": "an empty HF_HOME is hub under the working directory, not XDG_CACHE_HOME",
+ "env": {
+ "HF_HOME": "",
+ "XDG_CACHE_HOME": "{root}/xdg"
+ },
+ "expected": "hub"
+ },
+ {
+ "name": "an empty XDG_CACHE_HOME is huggingface/hub under the working directory, not the home default",
+ "env": {
+ "XDG_CACHE_HOME": ""
+ },
+ "expected": "huggingface/hub"
+ },
+ {
+ "name": "nothing set: the default under the home directory",
+ "env": {},
+ "expected": "{home}/.cache/huggingface/hub"
+ }
+ ]
+ }
+}
diff --git a/tests/parity/record_embedding.py b/tests/parity/record_embedding.py
new file mode 100644
index 000000000..e78217ec9
--- /dev/null
+++ b/tests/parity/record_embedding.py
@@ -0,0 +1,85 @@
+"""Record the embedding parity fixture for the default relevance model.
+
+Embeds a fixed set of texts with the Python ``EmbeddingScorer``, which loads
+the pinned Qdrant/bge-small-en-v1.5-onnx-Q snapshot, and writes them to
+``fixtures/embedding/bge_small_en_v15_pinned.json``. Two gated tests compare
+against it: ``tests/test_fastembed_pinned_snapshot.py`` (Python) and
+``fastembed_matches_parity_fixture`` in
+``crates/headroom-core/src/relevance/embedding.rs`` (Rust). Both reading one
+fixture bounds the drift between the languages by ``MAX_ABS_DIFF``.
+
+The languages run the same ONNX file, so the gap between them comes from the
+ONNX Runtime build, not the pipeline. Measured when this fixture was recorded:
+Rust and Python on the same ORT (1.31.0) agree within 1e-6 per component;
+Python on ORT 1.23.2 vs 1.31.0 differs by up to 4.1e-4. ``MAX_ABS_DIFF``
+covers the ORT range the project supports with ~2x headroom.
+
+This bounds numeric drift; it does not identify the model. Xenova's fp32
+export of the same model sits within 4.7e-4 of this fixture, inside the
+tolerance. Which files load is guaranteed by the pinned SHA and the unit tests
+on both sides, not by this fixture.
+
+Re-record after bumping the pinned revision (needs network on a cold cache),
+with an interpreter whose onnxruntime is >= 1.24, the runtime the Rust side
+needs:
+ python tests/parity/record_embedding.py
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from headroom.onnx_runtime import _PINNED_REVISIONS
+from headroom.relevance.embedding import DEFAULT_MODEL_NAME, DEFAULT_MODEL_REPO, EmbeddingScorer
+
+FIXTURE_PATH = os.path.join(
+ os.path.dirname(__file__), "fixtures", "embedding", "bge_small_en_v15_pinned.json"
+)
+
+# Largest allowed |embedding component - fixture|, on either side. See the
+# module docstring for how it was chosen.
+MAX_ABS_DIFF = 1e-3
+
+TEXTS = [
+ "login error",
+ "authentication failed for user admin: invalid credentials",
+ '{"status": "failed", "error": "connection refused", "retries": 3}',
+ "def retry(fn, attempts=3):\n for i in range(attempts):\n return fn()",
+ "Ünïcödé text, emoji 🚀 and CJK 中文 mixed in one line.",
+ # Longer than the 512-token window, so truncation is covered too.
+ " ".join(f"log line {i}: request handled in {i % 97} ms" for i in range(400)),
+]
+
+
+def write_fixture(fixture: dict[str, object], path: str = FIXTURE_PATH) -> None:
+ """Write ``fixture`` with each list item, so each embedding row, on one line."""
+ lines = []
+ for key, value in fixture.items():
+ if isinstance(value, list):
+ items = ",\n".join(f" {json.dumps(item, ensure_ascii=False)}" for item in value)
+ lines.append(f" {json.dumps(key)}: [\n{items}\n ]")
+ else:
+ lines.append(f" {json.dumps(key)}: {json.dumps(value, ensure_ascii=False)}")
+ os.makedirs(os.path.dirname(path), exist_ok=True)
+ with open(path, "w", encoding="utf-8", newline="\n") as f:
+ f.write("{\n" + ",\n".join(lines) + "\n}\n")
+
+
+def main() -> None:
+ scorer = EmbeddingScorer(DEFAULT_MODEL_NAME)
+ embeddings = scorer._encode(TEXTS)
+ fixture = {
+ "model": DEFAULT_MODEL_NAME,
+ "repo": DEFAULT_MODEL_REPO,
+ "revision": _PINNED_REVISIONS[DEFAULT_MODEL_REPO],
+ "max_abs_diff": MAX_ABS_DIFF,
+ "texts": TEXTS,
+ "embeddings": [[round(float(v), 8) for v in row] for row in embeddings],
+ }
+ write_fixture(fixture)
+ print(f"wrote {FIXTURE_PATH} ({len(TEXTS)} texts x {len(embeddings[0])} dims)")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tests/test_fastembed_pinned_snapshot.py b/tests/test_fastembed_pinned_snapshot.py
index c266136b1..48ade3f2f 100644
--- a/tests/test_fastembed_pinned_snapshot.py
+++ b/tests/test_fastembed_pinned_snapshot.py
@@ -1,15 +1,17 @@
-"""The default relevance embedder loads one pinned snapshot.
+"""The default relevance embedder loads one pinned snapshot, in both languages.
fastembed's ``TextEmbedding`` accepts ``revision`` but drops it before
``snapshot_download``, so the old pin never reached the Hub and the model
floated on ``main``. These tests hold the replacement in place: the pinned
-SHA reaches every file download and fastembed only gets the resolved
-directory.
+SHA reaches every file download, fastembed only gets the resolved directory,
+and the Rust scorer names the same repo, SHA and files.
"""
from __future__ import annotations
+import json
import os
+import re
import sys
from pathlib import Path
from types import SimpleNamespace
@@ -26,6 +28,12 @@ from headroom.relevance.embedding import (
EmbeddingScorer,
)
+REPO_ROOT = Path(__file__).resolve().parents[1]
+RUST_EMBEDDING = REPO_ROOT / "crates/headroom-core/src/relevance/embedding.rs"
+PARITY_FIXTURE = REPO_ROOT / "tests/parity/fixtures/embedding/bge_small_en_v15_pinned.json"
+HF_CACHE_FIXTURE = json.loads(
+ (REPO_ROOT / "tests/parity/fixtures/hf_hub_cache/cases.json").read_text(encoding="utf-8")
+)
PIN = _PINNED_REVISIONS[DEFAULT_MODEL_REPO]
@@ -171,3 +179,112 @@ def test_fastembed_loads_specific_model_path_without_a_download(monkeypatch, tmp
lazy_load=True,
)
assert Path(model.model._model_dir) == tmp_path
+
+
+def _rust_const(name: str) -> str:
+ match = re.search(rf'const {name}: &str = "([^"]+)";', RUST_EMBEDDING.read_text())
+ assert match, f"{name} not found in {RUST_EMBEDDING}"
+ return match.group(1)
+
+
+def test_rust_loads_the_same_snapshot():
+ assert _rust_const("DEFAULT_MODEL_REPO") == DEFAULT_MODEL_REPO
+ assert _rust_const("DEFAULT_MODEL_REVISION") == PIN
+ assert _rust_const("DEFAULT_MODEL_FILE") == DEFAULT_MODEL_FILES[0]
+ files = re.search(
+ r"const DEFAULT_MODEL_FILES: \[&str; \d+\] = \[(.*?)\];",
+ RUST_EMBEDDING.read_text(),
+ re.S,
+ )
+ assert files, "DEFAULT_MODEL_FILES not found"
+ entries = [part.strip() for part in files.group(1).split(",") if part.strip()]
+ assert entries == ["DEFAULT_MODEL_FILE", *(f'"{name}"' for name in DEFAULT_MODEL_FILES[1:])]
+
+
+def test_parity_fixture_was_recorded_at_the_pin():
+ fixture = json.loads(PARITY_FIXTURE.read_text(encoding="utf-8"))
+ assert fixture["repo"] == DEFAULT_MODEL_REPO
+ assert fixture["revision"] == PIN
+ assert len(fixture["embeddings"]) == len(fixture["texts"])
+
+
+ not os.environ.get("RUN_FASTEMBED_TESTS"),
+ reason="loads the real model (~67 MB download on a cold cache); set RUN_FASTEMBED_TESTS=1",
+)
+def test_python_matches_parity_fixture():
+ """Python half of the cross-language check; the Rust half is
+ ``fastembed_matches_parity_fixture`` in the Rust scorer."""
+ np = pytest.importorskip("numpy")
+ pytest.importorskip("fastembed")
+ fixture = json.loads(PARITY_FIXTURE.read_text(encoding="utf-8"))
+
+ got = EmbeddingScorer()._encode(fixture["texts"])
+
+ for text, row, expected in zip(fixture["texts"], got, fixture["embeddings"]):
+ worst = float(np.abs(np.asarray(row, dtype=np.float64) - np.asarray(expected)).max())
+ assert worst <= fixture["max_abs_diff"], f"{text!r}: max |python - fixture| = {worst:e}"
+
+
+# ── the shared HuggingFace cache directory ──────────────────────────────────
+#
+# Rust's ``hf_hub_cache_dir`` re-implements how ``huggingface_hub`` picks the
+# hub cache, so both languages look up and download into one directory. These
+# check the shared fixture against Python itself; the Rust tests
+# ``expand_vars_matches_python_posixpath_and_ntpath`` and
+# ``hf_hub_cache_dir_matches_the_shared_fixture`` check the port against the
+# same file.
+
+_CACHE_VARS = ("HF_HUB_CACHE", "HUGGINGFACE_HUB_CACHE", "HF_HOME", "XDG_CACHE_HOME")
+
+
+ "case", HF_CACHE_FIXTURE["expandvars"]["cases"], ids=lambda case: case["input"]
+)
+def test_expandvars_fixture_matches_posixpath_and_ntpath(
+ case: dict[str, str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+ import ntpath
+ import posixpath
+
+ for name, value in HF_CACHE_FIXTURE["expandvars"]["env"].items():
+ monkeypatch.setenv(name, value)
+ monkeypatch.delenv(HF_CACHE_FIXTURE["expandvars"]["unset"], raising=False)
+ assert posixpath.expandvars(case["input"]) == case["posix"]
+ assert ntpath.expandvars(case["input"]) == case["nt"]
+
+
+ "case", HF_CACHE_FIXTURE["cache_dir"]["cases"], ids=lambda case: case["name"]
+)
+def test_cache_dir_fixture_matches_huggingface_hub(case: dict, tmp_path: Path) -> None:
+ """``huggingface_hub`` reads these variables once, at import, so each case
+ runs in a fresh interpreter."""
+ import subprocess
+
+ pytest.importorskip("huggingface_hub")
+ root, home = tmp_path / "root", tmp_path / "home"
+
+ def fill(text: str) -> str:
+ return text.replace("{root}", str(root)).replace("{home}", str(home))
+
+ probe_vars = HF_CACHE_FIXTURE["cache_dir"]["probe_vars"]
+ env = {k: v for k, v in os.environ.items() if k not in (*_CACHE_VARS, *probe_vars)}
+ env["HOME"] = env["USERPROFILE"] = str(home)
+ env.update({name: fill(value) for name, value in case["env"].items()})
+ result = subprocess.run(
+ [
+ sys.executable,
+ "-c",
+ "import sys, huggingface_hub.constants as c; sys.stdout.write(c.HF_HUB_CACHE)",
+ ],
+ capture_output=True,
+ text=True,
+ env=env,
+ timeout=60,
+ check=True,
+ )
+ expected = case["expected"]
+ if isinstance(expected, dict):
+ expected = expected["nt" if os.name == "nt" else "posix"]
+ assert Path(result.stdout) == Path(fill(expected))
diff --git a/tests/test_offline_egress_chokepoint.py b/tests/test_offline_egress_chokepoint.py
index 06ec2cb43..4d9dbef71 100644
--- a/tests/test_offline_egress_chokepoint.py
+++ b/tests/test_offline_egress_chokepoint.py
@@ -3205,8 +3205,8 @@ class TestDocsMatchTheGuarantee:
_RUST_EGRESS_PATTERNS = re.compile(
r"""
- hf_hub::api::(?:sync|tokio)::Api(?:Builder)?::new\(
- | (?<![\w:])Api(?:Builder)?::new\(
+ hf_hub::api::(?:sync|tokio)::Api(?:Builder)?::(?:new|from_env|from_cache)\(
+ | (?<![\w:])Api(?:Builder)?::(?:new|from_env|from_cache)\(
| (?<![\w:])TextEmbedding::try_new\w*\(
| (?<![\w:])reqwest::(?:Client::(?:new|builder)|get|post)\(
| (?<![\w:])ureq::(?:agent|builder|get|post|put|delete|request)\(
@@ -3220,6 +3220,14 @@ _RUST_FN = re.compile(
)
_RUST_ALLOWLIST: dict[str, tuple[int, str]] = {
+ "headroom-core/src/relevance/embedding.rs": (
+ 1,
+ "cache-only: TextEmbedding::try_new_from_user_defined in load_snapshot "
+ "builds the ONNX session from bytes already read off disk and has no "
+ "Hub client at all. The files reach the disk through "
+ "default_model_repo, whose ApiBuilder is guarded, and only on a cache "
+ "miss, so a pre-seeded air-gapped host still loads.",
+ ),
"headroom-proxy/src/proxy.rs": (
1,
"user-traffic: the reqwest client the Rust proxy forwards the caller's "
@@ -3326,7 +3334,13 @@ class TestRustEgressChokepointCoverage:
"headroom-core/src/relevance/embedding.rs",
):
assert relpath in sites, f"{relpath} has no detected egress site at all"
- assert all(site.guarded for site in sites[relpath]), (
+ # Every site is guarded, except the cache-only loads the allowlist
+ # counts for the file (embedding.rs: the user-defined model load).
+ unguarded = [site for site in sites[relpath] if not site.guarded]
+ assert len(unguarded) < len(sites[relpath]), (
+ f"{relpath} has no egress site the Rust sweep sees as guarded"
+ )
+ assert len(unguarded) == _RUST_ALLOWLIST.get(relpath, (0, ""))[0], (
f"{relpath} has an egress site the Rust sweep does not see as guarded"
)