Embeddings kiezen / configureren

Embeddings voeden similarity search voor herinneringen en het gebruikersprofiel. Configureer ze in hetzelfde bestand (~/.config/opencode/opencode-mem.jsonc). Er is geen MLX-backend — lokale embeddings gebruiken @huggingface/transformers met ONNX, niet Apple MLX.

Lokaal (standaard): stel alleen embeddingModel in. Bij eerste gebruik wordt het model gedownload van Hugging Face en gecached onder {storagePath}/.cache (standaard ~/.opencode-mem/data/.cache).

Remote (OpenAI-compatibel): stel zowel embeddingApiUrl als embeddingApiKey in. De plugin roept dan {embeddingApiUrl}/embeddings aan met een Bearer-token. embeddingApiKey accepteert dezelfde geheime formaten als memoryApiKey (literal, env://…, file://…).

Sleutel	Rol
embeddingModel	Hugging Face-id (lokaal) of API-modelnaam (remote). Standaard: Xenova/nomic-embed-text-v1
embeddingDimensions	Optionele override; meestal weglaten — dimensies worden opgezocht uit een ingebouwde map
embeddingPooling	Lokale pooling: "mean" (standaard), "cls", of "last_token". Unset → klein known-model-preset of "mean"
embeddingQueryPrefix	Prefix voor query-task-embeddings. Unset → modelpreset of Nomic wanneer embeddingUseTaskPrefixes true is. Expliciete "" schakelt uit
embeddingDocumentPrefix	Prefix voor document-task-embeddings (zelfde resolutieregels als embeddingQueryPrefix)
embeddingUseTaskPrefixes	Opt-in Nomic search_query: / search_document:-prefixes wanneer custom/preset-prefixes unset zijn. Standaard false
embeddingDtype	Optionele lokale ONNX-dtype-override (bijv. "q8", "fp32"). Indien gezet, doorgegeven aan transformers.js pipeline({ dtype })
embeddingApiUrl	Basis-URL voor een OpenAI-compatibele embeddings-API (geen trailing path voorbij /v1)
embeddingApiKey	API-sleutel voor dat endpoint (vereist samen met embeddingApiUrl)

Aanbevolen lokale modellen:

Model	Dims	Opmerkingen
Xenova/nomic-embed-text-v1	768	Standaard; meertalig, 8192 context; mean pooling
Xenova/jina-embeddings-v2-base-en	768	Alleen Engels, 8192 context
Xenova/jina-embeddings-v2-small-en	512	Sneller, 8192 context
Xenova/all-MiniLM-L6-v2	384	Zeer snel, 512 context
Xenova/all-mpnet-base-v2	768	Goede kwaliteit, 512 context
Xenova/bge-m3	1024	Meertalig; auto CLS-pooling
intfloat/multilingual-e5-large	1024	Auto query: / passage:-prefixes

Voorbeeld — remote OpenAI-embeddings:

{
  "embeddingApiUrl": "https://api.openai.com/v1",
  "embeddingApiKey": "env://OPENAI_API_KEY",
  "embeddingModel": "text-embedding-3-small",
}

Voorbeeld — lokaal bge-m3 (pooling standaard CLS via preset; override indien nodig):

{
  "embeddingModel": "Xenova/bge-m3",
  // "embeddingPooling": "cls",
  // "embeddingDtype": "q8",
}

Wijzigen van embeddingModel, dimensies, pooling of task-prefixes kan opnieuw embedden van opgeslagen herinneringen vereisen zodat store- en queryvectoren uitgelijnd blijven. Kies liever één keer een model (en pooling-/prefixinstellingen) en blijf daarbij voor een gegeven datadirectory.

Niet ondersteund — Intel Mac (darwin/x64): Lokale persistentie vereist @tursodatabase/database, dat geen Intel Mac native binding publiceert. Vaste onnxruntime-node-releases (1.24.1+, inclusief de vastgezette 1.31.1) missen ook darwin/x64. Gebruik een Apple Silicon Mac, Linux of Windows, of een remote endpoint via embeddingApiUrl + embeddingApiKey (voorbeeld hierboven). Op ondersteunde platforms pinnet opencode-mem onnxruntime-node@1.31.1 (Ort::Env teardown-fix uit 1.24.1 / #225) en laadt transformers via een CJS resolve-shim zodat geneste OpenCode-installaties die binding behouden. Transformers wordt naar een absoluut pad opgelost voordat die shim wordt geïnstalleerd, zodat OpenCode’s Bun --compile-host niet faalt met Cannot find module '@huggingface/transformers' from ''. Wis na een upgrade de geneste plugincache van OpenCode (~/.cache/opencode/packages/opencode-mem@*) en herinstalleer.