Embedding seçimi / yapılandırması

Embedding’ler bellekler ve kullanıcı profili için benzerlik aramasını güçlendirir. Bunları aynı dosyada yapılandırın (~/.config/opencode/opencode-mem.jsonc). MLX backend yoktur — yerel embedding’ler Apple MLX değil, ONNX ile @huggingface/transformers kullanır.

Yerel (varsayılan): yalnızca embeddingModel ayarlayın. İlk kullanımda model Hugging Face’ten indirilir ve {storagePath}/.cache altında önbelleğe alınır (varsayılan ~/.opencode-mem/data/.cache).

Uzak (OpenAI uyumlu): hem embeddingApiUrl hem embeddingApiKey ayarlayın. Eklenti ardından Bearer belirteciyle {embeddingApiUrl}/embeddings çağırır. embeddingApiKey, memoryApiKey ile aynı gizli biçimleri kabul eder (literal, env://…, file://…).

Anahtar	Rol
embeddingModel	Hugging Face kimliği (yerel) veya API model adı (uzak). Varsayılan: Xenova/nomic-embed-text-v1
embeddingDimensions	İsteğe bağlı geçersiz kılma; genellikle atlayın — boyutlar yerleşik bir haritadan alınır
embeddingPooling	Yerel pooling: "mean" (varsayılan), "cls" veya "last_token". Ayarlanmamış → küçük bilinen-model ön ayarı veya "mean"
embeddingQueryPrefix	Sorgu-görevi embedding’leri için önek. Ayarlanmamış → model ön ayarı veya embeddingUseTaskPrefixes true iken Nomic. Açık "" devre dışı bırakır
embeddingDocumentPrefix	Belge-görevi embedding’leri için önek (embeddingQueryPrefix ile aynı çözüm kuralları)
embeddingUseTaskPrefixes	Özel/ön ayar önekleri ayarlanmamışken Nomic search_query: / search_document: öneklerine katılma. Varsayılan false
embeddingDtype	İsteğe bağlı yerel ONNX dtype geçersiz kılması (örn. "q8", "fp32"). Ayarlandığında transformers.js pipeline({ dtype })’a iletilir
embeddingApiUrl	OpenAI uyumlu bir embeddings API’si için temel URL (/v1 ötesinde sondaki yol yok)
embeddingApiKey	O uç nokta için API anahtarı (embeddingApiUrl ile birlikte gerekli)

Önerilen yerel modeller:

Model	Boyut	Notlar
Xenova/nomic-embed-text-v1	768	Varsayılan; çok dilli, 8192 bağlam; mean pooling
Xenova/jina-embeddings-v2-base-en	768	Yalnızca İngilizce, 8192 bağlam
Xenova/jina-embeddings-v2-small-en	512	Daha hızlı, 8192 bağlam
Xenova/all-MiniLM-L6-v2	384	Çok hızlı, 512 bağlam
Xenova/all-mpnet-base-v2	768	İyi kalite, 512 bağlam
Xenova/bge-m3	1024	Çok dilli; otomatik CLS pooling
intfloat/multilingual-e5-large	1024	Otomatik query: / passage: önekleri

Örnek — uzak OpenAI embedding’leri:

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

Örnek — yerel bge-m3 (pooling ön ayar üzerinden CLS’ye varsayılan; gerekirse geçersiz kılın):

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

embeddingModel, boyutlar, pooling veya görev öneklerini değiştirmek, depo ve sorgu vektörlerinin hizalı kalması için saklanan belleklerin yeniden embedding’ini gerektirebilir. Belirli bir veri dizini için bir modeli (ve pooling/önek ayarlarını) bir kez seçip bunlara bağlı kalmayı tercih edin.

Desteklenmez — Intel Mac (darwin/x64): Yerel kalıcılık, Intel Mac yerel bağlayıcısı yayınlamayan @tursodatabase/database gerektirir. Sabit onnxruntime-node sürümleri (1.24.1+, sabitlenmiş 1.31.1 dahil) de darwin/x64 içermez. Apple Silicon Mac, Linux veya Windows kullanın; ya da embeddingApiUrl + embeddingApiKey ile uzak bir uç nokta (yukarıdaki örnek). Desteklenen platformlarda opencode-mem, onnxruntime-node@1.31.1’ı sabitler (1.24.1 / #225’ten Ort::Env teardown düzeltmesi) ve OpenCode iç içe kurulumlarının o bağlayıcıyı koruması için transformers’ı bir CJS çözüm shim’i üzerinden yükler. Transformers, o shim kurulmadan önce mutlak bir yola çözülür; böylece OpenCode’un Bun --compile ana bilgisayarı Cannot find module '@huggingface/transformers' from '' ile başarısız olmaz. Yükseltmeden sonra OpenCode’un iç içe eklenti önbelleğini temizleyin (~/.cache/opencode/packages/opencode-mem@*) ve yeniden kurun.