Files
waggle-os/packages/core/src/recall/inprocess-reranker.ts
shumeiko.it c098f20872 chore: drop hive-mind provenance notes from comments (P2.2)
Comments that pointed at hive-mind-core files, the hive-mind OSS
mirror and its drift triage now describe the code as it is. The
in-process reranker caches its model in ~/.waggle/models, like the
embedder, when the caller passes no directory; the sidecar always
passes one.
2026-11-01 00:42:48 +01:00

138 lines
4.9 KiB
TypeScript

/**
* In-process cross-encoder reranker using @huggingface/transformers (ONNX).
*
* Cross-encoders take (query, doc) pairs and output a relevance score by
* jointly attending to both — much more discriminating than vector dot
* products. Use after RRF to rerank the top-K candidates from hybrid
* search. Standard pattern in production RAG systems.
*
* Default model: Xenova/ms-marco-MiniLM-L-6-v2 — the canonical
* SentenceTransformers cross-encoder, ~22MB on disk, ~30-50ms per pair
* on CPU. Trained on MS MARCO passage ranking, generalizes well to
* mixed-domain technical text.
*
* Alternative: Xenova/bge-reranker-base (~280MB, slightly higher quality
* on out-of-domain queries). Set via `model` config.
*
* `@huggingface/transformers` is an optional peer dep — if not installed,
* createInProcessReranker throws and the caller falls back to no reranking.
*/
import path from 'node:path';
import os from 'node:os';
import { createCoreLogger } from '../logger.js';
import { withTransformersModelLoad } from '../embeddings/transformers-model-load.js';
const log = createCoreLogger('inprocess-reranker');
export interface Reranker {
/**
* Score a single (query, doc) pair. Higher = more relevant.
* Score scale depends on the model — for ms-marco-MiniLM it's
* roughly [-10, 10]; relative ordering is what matters.
*/
score(query: string, doc: string): Promise<number>;
/**
* Score N pairs sharing one query. Same-shape result as score() but
* amortises the model invocation when supported.
*/
scoreBatch(query: string, docs: string[]): Promise<number[]>;
}
export interface InProcessRerankerConfig {
model?: string;
cacheDir?: string;
}
/**
* Build a reranker backed by @huggingface/transformers. Throws if the
* package isn't installed — caller is expected to catch and fall back.
*/
export async function createInProcessReranker(
config?: Partial<InProcessRerankerConfig>,
): Promise<Reranker> {
const model = config?.model ?? 'Xenova/ms-marco-MiniLM-L-6-v2';
const cacheDir = config?.cacheDir ?? path.join(os.homedir(), '.waggle', 'models');
log.info(`Loading in-process reranker: ${model} (~22MB first download)`);
const { AutoTokenizer, AutoModelForSequenceClassification } = await import(
'@huggingface/transformers'
);
const { tokenizer, seqModel } = await withTransformersModelLoad({
cacheDir,
model,
load: async (canonicalCacheDir) => ({
// Cross-encoders need direct tokenizer + model access — pipeline API
// doesn't expose the (text, text_pair) input pattern cleanly across
// all transformers.js versions. Calling the model directly with
// tokenized pairs is the stable path.
tokenizer: await AutoTokenizer.from_pretrained(model, { cache_dir: canonicalCacheDir }),
seqModel: await AutoModelForSequenceClassification.from_pretrained(model, {
dtype: 'fp32',
cache_dir: canonicalCacheDir,
}),
}),
onQuarantine: () => log.warn(`Quarantined corrupt reranker model cache: ${model}`),
});
log.info(`In-process reranker ready: ${model}`);
/** Score a single pair: tokenize, forward, extract logit. */
async function scorePair(query: string, doc: string): Promise<number> {
const inputs = await tokenizer(query, {
text_pair: doc,
padding: true,
truncation: true,
return_tensor: true,
});
const out = await seqModel(inputs);
// ms-marco-MiniLM outputs a single logit per pair (1-class regression).
// Other cross-encoders may output 2 classes — take logit[0] - logit[1]
// as a relevance score in that case.
const logits = out.logits ?? out[0];
const data = logits.data as Float32Array | number[];
if (logits.dims && logits.dims[logits.dims.length - 1] === 2) {
return Number(data[0]) - Number(data[1]);
}
return Number(data[0]);
}
return {
async score(query: string, doc: string): Promise<number> {
return scorePair(query, doc);
},
async scoreBatch(query: string, docs: string[]): Promise<number[]> {
if (docs.length === 0) return [];
// Tokenize all pairs together for batch inference. Padding aligns
// sequences so the model can process them in one forward pass.
const queries = docs.map(() => query);
const inputs = await tokenizer(queries, {
text_pair: docs,
padding: true,
truncation: true,
return_tensor: true,
});
const out = await seqModel(inputs);
const logits = out.logits ?? out[0];
const data = logits.data as Float32Array | number[];
const dims = logits.dims;
const lastDim = dims[dims.length - 1];
const scores: number[] = [];
if (lastDim === 2) {
for (let i = 0; i < docs.length; i++) {
scores.push(Number(data[i * 2]) - Number(data[i * 2 + 1]));
}
} else {
for (let i = 0; i < docs.length; i++) {
scores.push(Number(data[i]));
}
}
return scores;
},
};
}