ماژولهای Weaviate چیستند و چه چیزی به دیتابیس اضافه میکنند؟
مستندات رسمی Weaviate آن را اینطور تعریف میکند: «Weaviate ساختاری ماژولار دارد و قابلیتهایی مثل برداریسازی یا پشتیبانگیری توسط ماژولهای اختیاری مدیریت میشوند.» به زبان ساده، ماژول یک پلاگین داخلی است که در همان باینری Weaviate lives اما تا آن را فعال نکنید، وجود خارجی ندارد. این طراحی باعث شده یک ایمیج Docker واحد، هم نقش دیتابیس برداری خام را بازی کند و هم نقش یک پلتفرم RAG کامل.
- برداریسازی خودکار: درج شیء بدون وکتور و برداریشدن خودکار کوئریهای متنی (ماژولهای vectorizer).
- گسترش API جستجو: افزودن عملگرهایی مثل nearText و فیلدهایی مثل _additional { generated } به API.
- پردازش بعد از بازیابی: بازترتیب نتایج (reranker)، استخراج پاسخ (qna) و تولید متن (generative).
- عملیات زیرساختی: پشتیبانگیری به فایلسیستم، S3، GCS یا Azure (ماژولهای backup).
انواع ماژولهای Weaviate کداماند؟
مستندات مفهومی Weaviate ماژولها را در سه سطح میبیند، اما مرجع ماژولها شش دستهٔ عملیاتی را پوشش میدهد: vectorizer و ranker که داده را به وکتور تبدیل یا نتایج را مرتب میکنند؛ reader و generator که روی خروجی جستجو پردازش بعدی انجام میدهند؛ و سایر ماژولهای کمکی مثل spellcheck و backup. نامگذاری هم سیستم دارد: ماژولهای برداریسازی از الگوی <media>2vec-<name> پیروی میکنند (مثل text2vec-openai و img2vec-neural) و بقیه از الگوی <functionality>-<name> (مثل qna-transformers).
| دسته | الگوی نام / نمونه | نقش در pipeline |
|---|---|---|
| Vectorizer | text2vec-openai، text2vec-transformers، text2vec-ollama، text2vec-weaviate، img2vec-neural، ref2vec-centroid، multi2vec-* | تبدیل داده به وکتور در درج و کوئری |
| Reranker | reranker-cohere (و ماژولهای reranker سایر ارائهدهندهها) | بازترتیب نتایج با مدل دقیقتر |
| Generative | generative-openai و ماژولهای generative سایر ارائهدهندهها | تولید پاسخ LLM روی نتایج بازیابی (RAG) |
| Reader / سایر پردازشها | qna-openai، qna-transformers، ner-transformers، sum-transformers، text-spellcheck | استخراج پاسخ، تشخیص موجودیت، خلاصهسازی، اصلاح املا |
| Backup | backup-filesystem، backup-s3، backup-gcs، backup-azure | پشتیبانگیری و بازیابی داده |
| ویژه | text2vec-contextionary (منسوخ)، self_provided (بدون ماژول)، ماژولهای سفارشی | میراث قدیمی، وکتور دستی، توسعهٔ اختصاصی |
چطور یک ماژول Weaviate را فعال کنیم؟
فعالسازی ماژولها یک کارِ هنگام راهاندازی است، نه هنگام اجرا: ماژولها در کد Weaviate ساخته شدهاند و فقط با متغیرهای محیطی روشن میشوند. متغیر اصلی ENABLE_MODULES است که فهرست ماژولها را بهصورت comma-separated میگیرد. از نسخهٔ 1.33 به بعد همهٔ یکپارچهسازیهای API-based (مثل text2vec-openai و generative-openai) بهصورت پیشفرض فعالاند و اگر محیط شما محدود یا air-gapped است، باید آنها را صریحاً خاموش کنید.
- 1
نوشتن docker-compose.yml
ایمیج رسمی cr.weaviate.io/semitechnologies/weaviate (مثلاً تگ 1.40.3) با پورتهای 8080 برای REST و 50051 برای gRPC و متغیر ENABLE_MODULES با فهرست ماژولها.
- 2
اجرای stack
با docker compose up -d هر دو کانتینر (دیتابیس و کانتینر استنتاج) بالا میآیند؛ vectorizerهای self-hosted به کانتینر استنتاج جداگانه نیاز دارند.
- 3
بررسی آماده بودن
تا آماده شدن Weaviate صبر کنید؛ endpoint آمادگی باید کد 200 بدهد.
- 4
تأیید ماژولهای فعال
endpointی v1/meta فهرست ماژولهای فعال و نسخهٔ Weaviate را برمیگرداند؛ این سریعترین راه تأیید فعالسازی است.
vectorizer هر collection را کجا تنظیم کنیم؟ (جایگزین DEFAULT_VECTORIZER_MODULE)
در نسخههای قدیمی، متغیر DEFAULT_VECTORIZER_MODULE مشخص میکرد collectionهای بدون vectorizer صریح از کدام ماژول استفاده کنند. این متغیر از نسخهٔ 1.40 منسوخ شده و Weaviate آن را نادیده میگیرد؛ استاندارد جدید این است که vectorizer در تعریف هر collection صریحاً ست شود. این تغییر عملاً به نفع شماست: میتوانید در یک دیتابیس، collection محصولات را با یک مدل و collection اسناد قانونی را با مدل دیگری برداری کنید.
اگر وکتورها را از قبل دارید یا مدل برداریسازی شما ماژول Weaviate ندارد، از Configure.Vectors.self_provided استفاده کنید؛ در این حالت هر شیء باید همراه وکتورش درج شود و جستجو با nearVector انجام خواهد شد. این همان الگوی Bring Your Own Vectors است و دقیقاً همان چیزی است که در سرویسهای Embeddings مستقل (مثل تولید embedding با API خودتان) استفاده میشود.
ماژولهای Vectorizer: برداریسازی خودکار چطور انجام میشود؟
ماژولهای vectorizer دو کار همزمان انجام میدهند: در هنگام درج، properties متنی شیء را به وکتور تبدیل و ذخیره میکنند و در هنگام جستجو، متن کوئری را با همان مدل برداری میکنند تا مقایسهٔ فاصله در یک فضا انجام شود. دقیقاً به همین دلیل مدلِ درج و مدلِ کوئری باید یکی باشد؛ اگر vectorizer را بعد از درج عوض کنید، وکتورهای قدیمی و کوئریهای جدید در دو فضای متفاوت خواهند بود و نتایج بیمعنا میشود.
| ماژول | نوع | پیشنیاز | مناسب برای |
|---|---|---|---|
| text2vec-openai | API-based | متغیر OPENAI_APIKEY یا هدر X-OpenAI-Api-Key | شروع سریع، کیفیت بالا، وابستگی به endpoint سازگار با OpenAI |
| text2vec-transformers | Self-hosted | کانتینر استنتاج + TRANSFORMERS_INFERENCE_API | حریم خصوصی داده، بدون هزینهٔ API، کار بدون اینترنت |
| text2vec-ollama | Self-hosted | سرویس Ollama روی شبکه | استفاده از مدلهای محلی مثل nomic-embed-text |
| text2vec-weaviate | API-based | حساب Weaviate (Embeddings سرویس خود Weaviate) | کاربران Weaviate Cloud که میخواهند همهچیز یکجا باشد |
| multi2vec-* / img2vec-neural | چندرسانهای | بسته به ماژول | جستجوی تصویر، ویدئو و ترکیبی (text+image) |
| ref2vec-centroid | مرجعمحور | — | وکتور مبتنی بر مرکز اشیاء مرجع (مثلاً سلیقهٔ کاربر) |
چطور Weaviate را به API سازگار با OpenAI اپکس۲۴ وصل کنیم؟
ماژولهای خانوادهٔ OpenAI در Weaviate فقط به یک endpoint «سازگار با OpenAI» نیاز دارند، نه لزوماً به خود OpenAI. مستندات Weaviate صراحتاً هدر X-OpenAI-Baseurl را برای «استفاده از یک baseURL سفارشی (مثلاً پروکسی) بهجای URL پیشفرض OpenAI» معرفی میکند و از نسخهٔ 1.33 هم نام مدل دیگر اعتبارسنجی نمیشود. ترکیب این دو یعنی هر سرویسی که فرمت OpenAI را پیاده کرده باشد — از جمله اپکس۲۴ با آدرس https://api.apx24.ir/v1 — میتواند موتور تولید متن Weaviate شما باشد.
اپکس۲۴ پلتفرم API هوش مصنوعی است که بیش از ۵۰ مدل متن را پشت یک کلید واحد با فرمت «کاملاً سازگار با OpenAI» ارائه میدهد؛ quickstart رسمی آن دقیقاً همان الگوی SDK رسمی OpenAI با تغییر base_url است و احراز هویت با هدر Authorization: Bearer انجام میشود. برای توسعهدهندگان ایرانی این یعنی دسترسی مستقیم و پرداخت ریالی به مدلهایی که ماژول generative میفهمد، بدون نیاز به تغییر یک خط از منطق Weaviate.
جستجوی برداری و RAG: nearText و generate چطور استفاده میشوند؟
وقتی vectorizer فعال است، جستجوی معنایی یک خط کد است: near_text متن کوئری را میگیرد، خود Weaviate آن را با همان مدل collection برداری میکند و نزدیکترین اشیاء را با فاصلهٔ عددی برمیگرداند. اگر ماژول generative هم فعال باشد، متد generate روی همان نتایج تولید متن انجام میدهد — این دقیقاً RAG داخل دیتابیس است، بدون نوشتن یک خط pipeline اضافه.
reranker و ماژولهای کمکی چه کاری میکنند؟
جستجوی برداری سریع است اما گاهی ترتیب نتایج را میشود بهتر کرد؛ اینجاست که ماژولهای reranker وارد میشوند. ماژول reranker-cohere نتایج اولیه را با مدل بازترتیب Cohere (پیشفرض rerank-v3.5) دوباره مرتب میکند و به هر نوع جستجویی — برداری، keyword یا hybrid — قابل اضافه شدن است. هزینهاش یک فراخوانی API اضافه بهازای هر کوئری است، پس معمولاً فقط روی نتایج برتر (limit کوچک) اجرا میشود.
- qna-openai و qna-transformers: استخراج پاسخ مستقیم از متن بازیابیشده (reader)؛ نسخهٔ transformers به یک vectorizer متنی وابسته است.
- ner-transformers: تشخیص موجودیتهای نامدار (افراد، سازمان، مکان) روی متن بازیابیشده.
- sum-transformers: خلاصهسازی نتایج جستجو با مدل محلی.
- text-spellcheck: اصلاح غلط املایی کوئری پیش از جستجو — برای فارسی هم قابل امتحان است اما مدلهای آن انگلیسیمحورند.
- backup-filesystem و backup-s3 / backup-gcs / backup-azure: پشتیبانگیری collectionها؛ نسخهٔ فایلسیستم فقط برای توسعه و تست توصیه شده و برای محیط چندنود مناسب نیست.





