اختيار / إعداد التضمينات

تشغّل التضمينات البحث بالتشابه للذكريات وملف المستخدم. أعدها في نفس الملف (~/.config/opencode/opencode-mem.jsonc). لا توجد خلفية MLX — التضمينات المحلية تستخدم @huggingface/transformers مع ONNX، وليس Apple MLX.

محلي (الافتراضي): عيّن فقط embeddingModel. عند أول استخدام يُنزَّل النموذج من Hugging Face ويُخزَّن مؤقتًا تحت {storagePath}/.cache (الافتراضي ~/.opencode-mem/data/.cache).

بعيد (متوافق مع OpenAI): عيّن كلًا من embeddingApiUrl وembeddingApiKey. يستدعي المكون الإضافي حينها {embeddingApiUrl}/embeddings برمز Bearer. يقبل embeddingApiKey نفس صيغ الأسرار التي يقبلها memoryApiKey (literal، env://…، file://…).

المفتاح	الدور
embeddingModel	معرّف Hugging Face (محلي) أو اسم نموذج API (بعيد). الافتراضي: Xenova/nomic-embed-text-v1
embeddingDimensions	تجاوز اختياري؛ عادة احذفه — تُستمد الأبعاد من خريطة مدمجة
embeddingPooling	تجميع محلي: "mean" (الافتراضي)، "cls"، أو "last_token". غير معيَّن → إعداد مسبق لنموذج معروف صغير أو "mean"
embeddingQueryPrefix	بادئة لتضمينات مهمة الاستعلام. غير معيَّن → إعداد مسبق للنموذج أو Nomic عندما يكون embeddingUseTaskPrefixes صحيحًا. "" صريح يعطّل
embeddingDocumentPrefix	بادئة لتضمينات مهمة المستند (نفس قواعد الحل مثل embeddingQueryPrefix)
embeddingUseTaskPrefixes	الاشتراك الاختياري في بادئات Nomic search_query: / search_document: عندما تكون البادئات المخصصة/المسبقة غير معيَّنة. الافتراضي false
embeddingDtype	تجاوز اختياري لنوع بيانات ONNX المحلي (مثل "q8"، "fp32"). عند التعيين، يُمرَّر إلى transformers.js pipeline({ dtype })
embeddingApiUrl	عنوان URL الأساسي لـ API تضمينات متوافق مع OpenAI (بدون مسار لاحق بعد /v1)
embeddingApiKey	مفتاح API لتلك النقطة (مطلوب مع embeddingApiUrl)

النماذج المحلية الموصى بها:

النموذج	الأبعاد	ملاحظات
Xenova/nomic-embed-text-v1	768	الافتراضي؛ متعدد اللغات، سياق 8192؛ تجميع mean
Xenova/jina-embeddings-v2-base-en	768	إنجليزي فقط، سياق 8192
Xenova/jina-embeddings-v2-small-en	512	أسرع، سياق 8192
Xenova/all-MiniLM-L6-v2	384	سريع جدًا، سياق 512
Xenova/all-mpnet-base-v2	768	جودة جيدة، سياق 512
Xenova/bge-m3	1024	متعدد اللغات؛ تجميع CLS تلقائي
intfloat/multilingual-e5-large	1024	بادئات query: / passage: تلقائية

مثال — تضمينات OpenAI البعيدة:

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

مثال — bge-m3 محلي (التجميع الافتراضي CLS عبر الإعداد المسبق؛ تجاوز عند الحاجة):

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

تغيير embeddingModel أو الأبعاد أو التجميع أو بادئات المهام قد يتطلب إعادة تضمين الذكريات المخزّنة حتى تبقى متجهات التخزين والاستعلام متوافقة. فضّل اختيار نموذج (وإعدادات التجميع/البادئة) مرة واحدة والالتزام بها لمجلد بيانات معيّن.

غير مدعوم — Intel Mac (darwin/x64): يتطلب الاستمرار المحلي @tursodatabase/database، الذي لا ينشر ربطًا أصليًا لـ Intel Mac. إصدارات onnxruntime-node الثابتة (1.24.1+، بما في ذلك المثبّت 1.31.1) تفتقر أيضًا إلى darwin/x64. استخدم Mac بـ Apple Silicon أو Linux أو Windows، أو نقطة نهاية بعيدة عبر embeddingApiUrl + embeddingApiKey (المثال أعلاه). على المنصات المدعومة، يثبّت opencode-mem onnxruntime-node@1.31.1 (إصلاح تفكيك Ort::Env من 1.24.1 / #225) ويحمّل transformers عبر جسر حل CJS حتى تحافظ تثبيتات OpenCode المتداخلة على ذلك الربط. يُحل Transformers إلى مسار مطلق قبل تثبيت ذلك الجسر حتى لا يفشل مضيف OpenCode Bun --compile بـ Cannot find module '@huggingface/transformers' from ''. بعد الترقية، امسح ذاكرة التخزين المؤقت المتداخلة للمكون الإضافي في OpenCode (~/.cache/opencode/packages/opencode-mem@*) وأعد التثبيت.