تابع امبدینگ در ChromaDB چیست؟
در هر سیستم جستوجوی معنایی دو کار متفاوت انجام میشود: اول «تبدیل متن به بردار» و دوم «ذخیره و مقایسهٔ بردارها». ChromaDB فقط کار دوم را انجام میدهد؛ کار اول وظیفهٔ تابع امبدینگ است. تابع امبدینگ یک کامپوننت قابلجایگزین است که شما هنگام ساخت کالکشن آن را انتخاب میکنید و از آن لحظه، ChromaDB هر جا به بردار نیاز داشت، همان تابع را صدا میزند.
ChromaDB دقیقاً کِی و کجا تابع امبدینگ را صدا میزند؟
- هنگام collection.add یا collection.upsert اگر پارامتر documents بدهید و embeddings ندهید — هر سند امبدینگ میشود.
- هنگام collection.query اگر query_texts بدهید و query_embeddings ندهید — متن کوئری امبدینگ میشود.
- هنگام collection.get و collection.delete امبدینگی انجام نمیشود؛ این متدها فقط با id، metadata یا متن ذخیرهشده کار میکنند.
این لیست یک قاعدهٔ مهم را روشن میکند: اگر بهجای documents خودتان embeddings بدهید، تابع امبدینگ کاملاً کنار گذاشته میشود و مسئولیت درستی بردارها با شماست. به همین شکل، در query اگر query_embeddings بدهید، یک فراخوانی API امبدینگ صرفهجویی میکنید و میتوانید بردار کوئری را کش کنید. انتخاب بین ارسال متن و ارسال بردار، یعنی انتخاب بین راحتی و کنترل.
چطور اولین کالکشن را با تابع پیشفرض بسازم؟
- 1
نصب پکیجها
chromadb را نصب کنید؛ برای بخشهای بعدی که با API کار میکنیم، پکیج openai هم لازم است.
- 2
ساخت کلاینت پایدار
PersistentClient دادهها را در پوشهٔ مشخصی روی دیسک ذخیره میکند تا بعد از بستن برنامه هم بمانند.
- 3
ساخت کالکشن
بدون پارامتر embedding_function، کالکشن با تابع پیشفرض ساخته میشود.
- 4
افزودن سند و جستوجو
اسناد را با id یکتا اضافه کنید و سپس با یک پرسش متنی جستوجو کنید.
به خروجی دقت کنید: کوئری دربارهٔ «بازار رمزارز» بود و بالاترین نتیجه، سند قیمت بیتکوین است — با اینکه هیچ کلمهٔ مشترکی ندارند. این دقیقاً همان تفاوت جستوجوی معنایی با جستوجوی کلیدواژهای است. اما توجه کنید که مدل پیشفرض روی انگلیسی آموزش دیده و برای فارسی بهینه نیست؛ در سکشن مقایسه این محدودیت را با اعداد روشنتر میکنیم.
چطور تابع امبدینگ داخلی OpenAI را پیکربندی کنم؟
| تابع داخلی | محل اجرا | پیشنیاز | کاربرد معمول |
|---|---|---|---|
| OpenAIEmbeddingFunction | دور (API) | پکیج openai + کلید API | اتصال به OpenAI یا هر endpoint سازگار با آن |
| CohereEmbeddingFunction | دور (API) | کلید Cohere | امبدینگ با مدلهای Cohere |
| SentenceTransformerEmbeddingFunction | محلی | پکیج sentence-transformers | اجرای مدلهای Hugging Face روی سیستم خودتان |
| OllamaEmbeddingFunction | محلی/سرور شخصی | نصب Ollama | امبدینگ لوکال با مدلهای متنباز |
| GoogleGenerativeAiEmbeddingFunction | دور (API) | کلید Google AI | امبدینگ با Gemini |
نکتهٔ کلیدی این جدول، ردیف اول است: OpenAIEmbeddingFunction فقط برای سرویس رسمی OpenAI نیست. چون فرمت درخواست و پاسخ آن استاندارد شده، هر سرویسی که endpoint سازگار با OpenAI ارائه دهد — از جمله API اپکس۲۴ — با همین تابع کار میکند. فقط باید آدرس سرور را از حالت پیشفرض عوض کنید؛ که دقیقاً موضوع سکشن بعدی است.
چطور تابع امبدینگ را به API سازگار با OpenAI در APX24 وصل کنم؟
پیش از هر چیز، درخواست خام را ببینید. endpoint امبدینگ یک قرارداد ساده دارد: مدل را میگیرد و آرایهٔ input — که میتواند چند رشتهٔ همزمان باشد — و بهازای هر عضو input، یک بردار با index همان عضو برمیگرداند. دیدن پاسخ خام کمک میکند بعداً بفهمید کلاس OpenAIEmbeddingFunction در پشت صحنه دقیقاً چه چیزی دریافت و بازنویسی میکند.
چطور تابع امبدینگ سفارشی (Custom Embedding Function) بنویسم؟
کلاسهای داخلی تقریباً همهٔ نیازها را پوشش میدهند، اما سه سناریو به تابع سفارشی نیاز پیدا میکنید: سرویسی که قالب رسمی خودش را دارد و هیچ wrapper داخلی ندارد، نیاز به منطق خاص مثل retry و batching و کش، یا خواندن کلید و تنظیمات از سیستم داخلی شرکت. خوشبختانه پیادهسازی سفارشی فقط پیادهسازی چهار متد است.
- پارامتر ورودی را دقیقاً با نام input بگیرید؛ اعتبارسنج نسخههای جدید chromadb امضای تابع را بررسی میکند.
- خروجی باید list از list اعداد float باشد و طول آن دقیقاً برابر len(input)؛ ترتیب هم نباید بههم بریزد.
- خطاهای شبکه یا احراز هویت را همانجا در __call__ رها (raise) کنید تا ChromaDB عملیات را با خطای روشن متوقف کند، نه با بردارهای خراب.
- در get_config هیچ مقدار محرمانهای برنگردانید؛ این config در ساختار کالکشن ذخیره میشود.
امبدینگ محلی یا امبدینگ API؟ کدام را انتخاب کنم؟
| مورد | هزینهٔ راهاندازی | هزینه در مقیاس | کیفیت برای فارسی | حریم خصوصی داده | وابستگی به شبکه | ابعاد بردار |
|---|---|---|---|---|---|---|
| تابع پیشفرض محلی (all-MiniLM-L6-v2) | صفر (فقط دانلود مدل) | رایگان؛ فقط منابع سیستم | محدود — مدل عمدتاً انگلیسیمحور است | داده از سیستم خارج نمیشود | ندارد (آفلاین) | ۳۸۴ |
| تابع API (OpenAI EF + endpoint سازگار) | کلید API + اعتبار | به ازای هر ۱M توکن | بهتر — مدلهای چندزبانهٔ جدیدتر | متن به سرور API ارسال میشود | نیاز به اینترنت | ۱۵۳۶ یا ۳۰۷۲ |
| مدل | محل اجرا | ابعاد بردار | نکتهٔ انتخاب |
|---|---|---|---|
| all-MiniLM-L6-v2 (پیشفرض Chroma) | محلی — دانلود خودکار | ۳۸۴ | سریع و رایگان؛ مناسب شروع و تست |
| text-embedding-ada-002 | API | ۱۵۳۶ | نسل قدیمیتر؛ پیشفرض سازندهٔ OpenAI EF |
| text-embedding-3-small | API | ۱۵۳۶ | اقتصادی و چندزبانه؛ انتخاب متعارف محصول |
| text-embedding-3-large | API | ۳۰۷۲ | بالاترین کیفیت؛ هزینهٔ ذخیره و قیمت بیشتر |
مثال حلشده: جستوجوی معنایی روی تیکتهای پشتیبانی
چطور کالکشن را به مدل امبدینگ جدید مهاجرت بدهم؟
چه نکاتی برای production حیاتی است؟
- اسناد را در دستههای چندصدتایی add کنید تا خطای گذرا فقط یک دسته را تکرار کند و حجم هر درخواست API هم در محدودهٔ معقول بماند.
- برای اسناد تغییرناپذیر از upsert بهجای add استفاده کنید تا اجرای دوبارهٔ اسکریپت، خطای id تکراری ندهد.
- نام کالکشن و مدل را جفت نگه دارید (مثلاً tickets_te3s_1536) تا همیشه معلوم باشد چه مدلی آن را ساخته است.
- کلید API فقط در متغیر محیطی؛ در لاگها و پیامهای خطا کلید را mask کنید.
- پیش از کوئریهای پرتکرار، بردار کوئری را کش کنید و با query_embeddings جستوجو کنید.
- فضای فاصله را از همان ابتدا با configuration تعیین کنید؛ تغییرش بعداً بازسازی شاخص میخواهد.





