Embeddings wählen / konfigurieren

Embeddings treiben die Ähnlichkeitssuche für Memories und das Benutzerprofil. Konfiguration in derselben Datei (~/.config/opencode/opencode-mem.jsonc). Es gibt kein MLX-Backend — lokale Embeddings nutzen @huggingface/transformers mit ONNX, nicht Apple MLX.

Lokal (Standard): nur embeddingModel setzen. Beim ersten Einsatz wird das Modell von Hugging Face heruntergeladen und unter {storagePath}/.cache zwischengespeichert (Standard ~/.opencode-mem/data/.cache).

Remote (OpenAI-kompatibel): sowohl embeddingApiUrl als auch embeddingApiKey setzen. Das Plugin ruft dann {embeddingApiUrl}/embeddings mit Bearer-Token auf. embeddingApiKey akzeptiert dieselben Secret-Formate wie memoryApiKey (literal, env://…, file://…).

Schlüssel	Rolle
embeddingModel	Hugging-Face-ID (lokal) oder API-Modellname (remote). Standard: Xenova/nomic-embed-text-v1
embeddingDimensions	Optionaler Override; meist weglassen — Dimensionen werden aus einer Built-in-Map nachgeschlagen
embeddingPooling	Lokales Pooling: "mean" (Standard), "cls" oder "last_token". Ungesetzt → kleines Known-Model-Preset oder "mean"
embeddingQueryPrefix	Präfix für Query-Task-Embeddings. Ungesetzt → Modell-Preset oder Nomic, wenn embeddingUseTaskPrefixes true ist. Explizites "" deaktiviert
embeddingDocumentPrefix	Präfix für Document-Task-Embeddings (gleiche Auflösungsregeln wie embeddingQueryPrefix)
embeddingUseTaskPrefixes	Opt-in für Nomic-Präfixe search_query: / search_document:, wenn Custom-/Preset-Präfixe nicht gesetzt sind. Standard false
embeddingDtype	Optionaler lokaler ONNX-Dtype-Override (z. B. "q8", "fp32"). Wenn gesetzt, an transformers.js pipeline({ dtype }) übergeben
embeddingApiUrl	Basis-URL für eine OpenAI-kompatible Embeddings-API (kein trailing Path über /v1 hinaus)
embeddingApiKey	API-Key für diesen Endpoint (zusammen mit embeddingApiUrl erforderlich)

Empfohlene lokale Modelle:

Modell	Dims	Hinweise
Xenova/nomic-embed-text-v1	768	Standard; mehrsprachig, 8192 Kontext; Mean-Pooling
Xenova/jina-embeddings-v2-base-en	768	Nur Englisch, 8192 Kontext
Xenova/jina-embeddings-v2-small-en	512	Schneller, 8192 Kontext
Xenova/all-MiniLM-L6-v2	384	Sehr schnell, 512 Kontext
Xenova/all-mpnet-base-v2	768	Gute Qualität, 512 Kontext
Xenova/bge-m3	1024	Mehrsprachig; Auto-CLS-Pooling
intfloat/multilingual-e5-large	1024	Auto-Präfixe query: / passage:

Beispiel — Remote-OpenAI-Embeddings:

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

Beispiel — lokal bge-m3 (Pooling defaultet über Preset auf CLS; bei Bedarf überschreiben):

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

Änderungen an embeddingModel, Dimensionen, Pooling oder Task-Präfixen können erfordern, gespeicherte Memories neu zu embedden, damit Store- und Query-Vektoren ausgerichtet bleiben. Besser einmal ein Modell (und Pooling-/Präfix-Einstellungen) wählen und für ein gegebenes Datenverzeichnis dabei bleiben.

Nicht unterstützt — Intel Mac (darwin/x64): Lokale Persistenz erfordert @tursodatabase/database, das kein natives Intel-Mac-Binding veröffentlicht. Feste onnxruntime-node-Releases (1.24.1+, einschließlich des gepinnten 1.31.1) fehlen ebenfalls unter darwin/x64. Apple-Silicon-Mac, Linux oder Windows nutzen, oder einen Remote-Endpoint über embeddingApiUrl + embeddingApiKey (Beispiel oben). Auf unterstützten Plattformen pinnt opencode-mem onnxruntime-node@1.31.1 (Ort::Env-Teardown-Fix aus 1.24.1 / #225) und lädt Transformers über einen CJS-Resolve-Shim, damit verschachtelte OpenCode-Installs dieses Binding behalten. Transformers wird vor Installation dieses Shims auf einen absoluten Pfad aufgelöst, damit OpenCodes Bun---compile-Host nicht mit Cannot find module '@huggingface/transformers' from '' scheitert. Nach dem Upgrade den verschachtelten Plugin-Cache von OpenCode löschen (~/.cache/opencode/packages/opencode-mem@*) und neu installieren.