diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 62c6b3fd3..2d7a0bf90 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -233,6 +233,13 @@ Most `analyze` knobs are also CLI flags (`--workers`, `--worker-timeout`, `--max | `GITNEXUS_QUERY_MAX_RSS_MB` | max(8192 MiB, 25% of available RAM), capped at 75% of available RAM | Process-memory ceiling while pooled reads run; available RAM is the smaller of physical RAM and a reported runtime/container constraint. Positive MiB values override it; `0` disables the guard. Invalid, overflowing, or sub-byte values use the default. A breach exits the process with code 70. | Set in the CLI/MCP/serve environment when a legitimate read workload needs a different budget. It does not resize the database buffer pool. | | `GITNEXUS_QUERY_TRACE` | unset | `1` writes query duration, row count, and sampled memory to stderr. Bound parameters are omitted; query text is included. | Diagnose an expensive read or a memory-guard exit. Inspect trace output before sharing it. | +For local model setup and switching instructions, see [Local Embedding Model](../gitnexus/README.md#local-embedding-model). + +| Local embedding variable | Default | Effect | When to tune | +| ----------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `GITNEXUS_EMBEDDING_MODEL_ID` | `Snowflake/snowflake-arctic-embed-xs` | Selects the local transformers.js model. Trims whitespace; unset or blank uses the default. HTTP model selection uses `GITNEXUS_EMBEDDING_MODEL` instead. | Use another ONNX-compatible Hugging Face model. Set the same model in analyze and query/server environments, restart servers, and run `analyze --force --embeddings` when switching. | +| `GITNEXUS_EMBEDDING_DIMS` | `384` | Width of the stored vector column; also the expected output width for a custom local model. | Match the selected model's output width. Unset when returning to the default model; use the same width for indexing and queries. | + | Analyze configuration | Default | Effect | When to tune | | --- | --- | --- | --- | | `GITNEXUS_RC` | unset | Absolute path to a JSON file with the same keys as `.gitnexusrc`. Its keys override repository configuration; CLI flags still win. Missing, invalid, or oversized files fail analysis. | Keep local configuration outside the checkout. Re-indexing hooks and watch processes must inherit it too. Changing or removing router aliases or handler wrappers rebuilds route evidence. | diff --git a/gitnexus/README.md b/gitnexus/README.md index 8e9230a12..4cbc9d66b 100644 --- a/gitnexus/README.md +++ b/gitnexus/README.md @@ -439,10 +439,12 @@ Local embeddings use `Snowflake/snowflake-arctic-embed-xs` (384 dimensions). To ```bash export GITNEXUS_EMBEDDING_MODEL_ID=Xenova/bge-base-en-v1.5 export GITNEXUS_EMBEDDING_DIMS=768 # required unless the model returns 384-dimensional vectors -gitnexus analyze . --embeddings +gitnexus analyze . --force --embeddings ``` -Set the same two variables wherever the index is queried (MCP server, `serve`, `query`), so queries are embedded with the same model. A model that returns a different vector size than `GITNEXUS_EMBEDDING_DIMS` stops the run with the size to set. Changing the model re-embeds every node on the next `analyze`; switching back to the default does too. +Set the same two variables wherever the index is queried (MCP server, `serve`, `query`), and restart running servers after changing them. A server using another model of the same width cannot detect the mismatch and will return unreliable semantic results. A model that returns a different vector size than `GITNEXUS_EMBEDDING_DIMS` stops the run with the size to set. Local models use mean pooling and normalization; model-specific query prefixes and pooling settings are not configurable. + +When changing models, run `gitnexus analyze . --force --embeddings`. A plain `analyze`, even with `--embeddings`, can return "Already up to date" on unchanged source; without `--embeddings`, changed-source runs normally only preserve existing vectors. The forced embedding pass replaces vectors whose model changed, including switches between models of the same width. To return to the default model, unset both `GITNEXUS_EMBEDDING_MODEL_ID` and `GITNEXUS_EMBEDDING_DIMS`, then run the same command. For repositories above the default 50,000-node embedding cap, use `--embeddings 0` (no cap) or an explicit higher limit. ## Remote Embeddings diff --git a/gitnexus/test/integration/embedding-identity-integrity.test.ts b/gitnexus/test/integration/embedding-identity-integrity.test.ts index 51c579dd1..00801b251 100644 --- a/gitnexus/test/integration/embedding-identity-integrity.test.ts +++ b/gitnexus/test/integration/embedding-identity-integrity.test.ts @@ -14,6 +14,9 @@ import * as adapter from '../../src/core/lbug/lbug-adapter.js'; import { runFullAnalysis } from '../../src/core/run-analyze.js'; import { getStoragePaths, loadMeta } from '../../src/storage/repo-manager.js'; import { seedEmbeddingsForFiles, stampEmbeddingCount } from '../helpers/embedding-seed.js'; +import * as sidecar from '../../src/core/embeddings/embedding-sidecar-client.js'; +import * as runtimeSupport from '../../src/core/embeddings/runtime-support.js'; +import { DEFAULT_EMBEDDING_CONFIG } from '../../src/core/embeddings/types.js'; describe('embedding identity integrity (#3569)', () => { let tmp: TestDBHandle | undefined; @@ -21,9 +24,88 @@ describe('embedding identity integrity (#3569)', () => { await adapter.closeLbug(); await tmp?.cleanup(); tmp = undefined; + vi.restoreAllMocks(); vi.unstubAllEnvs(); }); + it('replaces same-width model vectors on forced analyze and reuses only matching hashes', async () => { + tmp = await createTempDir('gitnexus-test-embedding-identity-'); + const repo = path.join(tmp.dbPath, 'repo'); + await fs.mkdir(repo); + vi.stubEnv('GITNEXUS_HOME', path.join(tmp.dbPath, 'home')); + vi.stubEnv('GITNEXUS_SHARED_STORE', 'off'); + vi.stubEnv('GITNEXUS_LBUG_EXTENSION_INSTALL', 'never'); + vi.stubEnv('GITNEXUS_EMBEDDING_URL', ''); + vi.stubEnv('GITNEXUS_EMBEDDING_MODEL', ''); + vi.stubEnv('GITNEXUS_EMBEDDING_DIMS', String(EMBEDDING_DIMS)); + vi.spyOn(runtimeSupport, 'getLocalEmbeddingRuntimeBlocker').mockReturnValue(null); + const init = vi.spyOn(sidecar, 'ensureEmbeddingSidecar').mockResolvedValue({ device: 'cpu' }); + vi.spyOn(sidecar, 'reapEmbeddingSidecarAndWait').mockResolvedValue(undefined); + let marker = 0; + // Only inference is faked: analyze, cache restore, hashes and DB writes are real. + const embed = vi.spyOn(sidecar, 'sidecarEmbedBatch').mockImplementation(async (texts) => + texts.map(() => { + const vector = new Float32Array(EMBEDDING_DIMS); + vector[marker] = 1; + return vector; + }), + ); + await fs.writeFile(path.join(repo, 'main.ts'), 'export function main() { return 1; }\n'); + await fs.writeFile(path.join(repo, 'util.ts'), 'export function util() { return 2; }\n'); + const git = (...args: string[]) => execFileSync('git', args, { cwd: repo, stdio: 'pipe' }); + git('init', '-q'); + git('add', '.'); + git('-c', 'user.name=test', '-c', 'user.email=test@test', 'commit', '-qm', 'fixture'); + const options = { + force: true, + embeddings: true, + skipFts: true, + skipAgentsMd: true, + skipSkills: true, + }; + const readRows = async () => { + await adapter.initLbug(getStoragePaths(repo).lbugPath, { skipFts: true }); + try { + return await adapter.executeQuery( + 'MATCH (e:CodeEmbedding) RETURN e.nodeId AS nodeId, e.contentHash AS hash, e.embedding AS vector ORDER BY nodeId', + ); + } finally { + await adapter.closeLbug(); + } + }; + let previousHashes: string[] = []; + let defaultHashes: string[] = []; + let nodeIds: string[] = []; + for (const modelId of ['', 'fixture/model-a', 'fixture/model-b', '']) { + vi.stubEnv('GITNEXUS_EMBEDDING_MODEL_ID', modelId); + embed.mockClear(); + await runFullAnalysis(repo, options, { onProgress: () => {} }); + expect(init.mock.lastCall?.[0]?.embeddingConfig?.modelId).toBe( + modelId || DEFAULT_EMBEDDING_CONFIG.modelId, + ); + const rows = await readRows(); + expect(rows).toHaveLength(2); + expect(embed.mock.calls.flatMap(([texts]) => texts)).toHaveLength(2); + expect(rows.map((row) => row.vector[marker])).toEqual([1, 1]); + const hashes = rows.map((row) => row.hash); + if (marker === 0) { + defaultHashes = hashes; + nodeIds = rows.map((row) => row.nodeId); + } else { + expect(rows.map((row) => row.nodeId)).toEqual(nodeIds); + hashes.forEach((hash, index) => expect(hash).not.toBe(previousHashes[index])); + if (modelId === '') expect(hashes).toEqual(defaultHashes); + } + previousHashes = hashes; + + embed.mockClear(); + await runFullAnalysis(repo, options, { onProgress: () => {} }); + expect(embed).not.toHaveBeenCalled(); + expect(await readRows()).toEqual(rows); + marker += 1; + } + }, 180_000); + it.each([ '', ' ',