جوجل الجوزاء

استخدم نموذج تضمين Google Gemini مع Milvus عن طريق اختيار نموذج وتكوين Milvus باستخدام مفتاح واجهة برمجة تطبيقات Gemini الخاص بك.

اختر نموذج التضمين

يدعم Milvus نماذج التضمين التي يوفرها Google Gemini. فيما يلي نماذج التضمين المتوفرة حاليًا من Gemini للرجوع إليها سريعًا:

اسم النموذج	الأبعاد	الحد الأقصى للرموز	الوصف
تضمين الجوزاء-001	افتراضي: 3,072 (موصى به: 768 أو 1,536 أو 3,072)	8,192	نموذج تضمين النص بأبعاد مرنة، تم تدريبه باستخدام تعلم تمثيل ماتريوشكا (MRL).
التضمين الجيمي -2	افتراضي: 3,072 (موصى به: 768 أو 1,536 أو 3,072)	8,192	أول نموذج تضمين متعدد الوسائط أصلاً من Google، يدعم النصوص والصور والفيديو والصوت والمستندات في مساحة تضمين موحدة.

يتم تدريب كلا النموذجين باستخدام تقنية تعلُّم تمثيل ماتريوشكا (MRL)، والتي تسمح بأبعاد مخرجات مرنة عبر معلمة dim. يوصى بالبدء بـ 768 بُعدًا وتوسيع نطاقها إلى 1,536 أو 3,072 إذا لزم الأمر. لمزيد من التفاصيل، راجع نماذج تضمين الجوزاء.

تدعم نماذج تضمين الجوزاء أيضًا معلمة نوع المهمة التي تعمل على تحسين التضمينات لحالات استخدام محددة. يقوم Milvus تلقائيًا بتعيين نوع المهمة بناءً على العملية:

• إدراج/إدراج: RETRIEVAL_DOCUMENT

• بحث: RETRIEVAL_QUERY

يمكنك تجاوز ذلك من خلال تحديد معلمة task بشكل صريح (على سبيل المثال، SEMANTIC_SIMILARITY ، ، CLASSIFICATION ، CLUSTERING).

تكوين بيانات الاعتماد

يجب أن يعرف Milvus مفتاح Gemini API الخاص بك قبل أن يتمكن من طلب التضمينات. يوفر Milvus طريقتين لتكوين بيانات الاعتماد:

• ملف التكوين (موصى به): قم بتخزين مفتاح واجهة برمجة التطبيقات في milvus.yaml بحيث تلتقطه كل إعادة تشغيل وعقدة تلقائيًا.

• متغيرات البيئة: أدخل المفتاح في وقت النشر - مثالي لـ Docker Compose.

اختر إحدى الطريقتين أدناه - من الأسهل الحفاظ على ملف التهيئة على الأجهزة العارية والأجهزة الافتراضية، بينما يناسب مسار env-var سير عمل الحاوية.

إذا كان مفتاح واجهة برمجة التطبيقات لنفس الموفر موجودًا في كل من ملف التكوين ومتغير البيئة، يستخدم Milvus دائمًا القيمة في milvus.yaml ويتجاهل متغير البيئة.

الخيار 1: ملف التكوين (موصى به وأولوية أعلى)

احتفظ بمفاتيح واجهة برمجة التطبيقات الخاصة بك في milvus.yaml ؛ يقرأها Milvus عند بدء التشغيل ويتجاوز أي متغير بيئة لنفس الموفر.

1. أعلن مفاتيحك ضمن بيانات الاعتماد:

   يمكنك سرد مفتاح واحد أو أكثر من مفاتيح واجهة برمجة التطبيقات - أعطِ كل منها تسمية تخترعها وستشير إليها لاحقًا.

   # milvus.yaml
   credential:
     apikey_dev:            # dev environment
       apikey: <YOUR_DEV_KEY>
     apikey_prod:           # production environment
       apikey: <YOUR_PROD_KEY>    
   

   وضع مفاتيح واجهة برمجة التطبيقات هنا يجعلها ثابتة عبر عمليات إعادة التشغيل ويتيح لك تبديل المفاتيح بمجرد تغيير التسمية.

2. أخبر ميلفوس بالمفتاح الذي يجب استخدامه لمكالمات الجوزاء

   في نفس الملف، وجّه موفر Gemini إلى التسمية التي تريده أن يستخدمها.

   function:
     textEmbedding:
       providers:
         gemini:
           credential: apikey_dev      # ← choose any label you defined above
   

   هذا يربط مفتاحًا محددًا لكل طلب يرسله ميلفوس إلى نقطة نهاية تضمينات الجوزاء.

الخيار 2: متغير البيئة

استخدم هذه الطريقة عندما تقوم بتشغيل Milvus مع Docker Compose وتفضل الاحتفاظ بالأسرار خارج الملفات والصور.

يعود Milvus إلى متغير البيئة فقط إذا لم يتم العثور على مفتاح للموفر في milvus.yaml.

المتغير	مطلوب	الوصف
Milvus_gemini_api_key	نعم	يجعل مفتاح Gemini متاحًا داخل كل حاوية Milvus (يتم تجاهله عند وجود مفتاح ل Gemini في milvus.yaml)

في ملف docker-compose.yaml الخاص بك، قم بتعيين متغير البيئة MILVUS_GEMINI_API_KEY.

# docker-compose.yaml (standalone service section)
standalone:
  # ... other configurations ...
  environment:
    # ... other environment variables ...
    # Set the environment variable pointing to the Gemini API key inside the container
    MILVUS_GEMINI_API_KEY: <YOUR_GEMINI_API_KEY>

تقوم كتلة environment: بحقن المفتاح فقط في حاوية Milvus، تاركةً نظام التشغيل المضيف الخاص بك دون أن يمسه أحد. لمزيد من التفاصيل، راجع تكوين Milvus مع Docker Compose.

الخطوة 1: إنشاء مجموعة بدالة تضمين نصية

تحديد حقول المخطط

لاستخدام دالة التضمين، قم بإنشاء مجموعة بمخطط محدد. يجب أن يتضمن هذا المخطط ثلاثة حقول ضرورية على الأقل:

• الحقل الأساسي الذي يحدد بشكل فريد كل كيان في المجموعة.

• حقل VARCHAR الذي يخزن البيانات الأولية المراد تضمينها.

• حقل متجه محجوز لتخزين التضمينات المتجهة الكثيفة التي ستقوم دالة تضمين النص بإنشائها للحقل VARCHAR.

يحدد المثال التالي مخططًا يحتوي على حقل قياسي واحد "document" لتخزين البيانات النصية وحقل متجه واحد "dense" لتخزين التضمينات التي سيتم إنشاؤها بواسطة الوحدة النمطية للدالة. تذكر تعيين البعد المتجه (dim) لمطابقة مخرجات نموذج التضمين الذي اخترته.

from pymilvus import MilvusClient, DataType, Function, FunctionType

# Initialize Milvus client
client = MilvusClient(
    uri="http://localhost:19530",
)

# Create a new schema for the collection
schema = client.create_schema()

# Add primary field "id"
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=False)

# Add scalar field "document" for storing textual data
schema.add_field("document", DataType.VARCHAR, max_length=9000)

# Add vector field "dense" for storing embeddings.
# IMPORTANT: Set dim to match the exact output dimension of the embedding model.
# For instance, Gemini's gemini-embedding-001 model outputs 3072-dimensional vectors by default,
# but can be shortened to 768 or 1536 dimensions.
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=768)

تحديد دالة تضمين النص

تقوم دالة تضمين النص تلقائيًا بتحويل البيانات الأولية المخزنة في حقل VARCHAR إلى تضمينات وتخزينها في حقل المتجه المحدد صراحةً.

يضيف المثال أدناه وحدة دالة (gemini_embedding) تقوم بتحويل الحقل القياسي "document" إلى تضمينات، وتخزين المتجهات الناتجة في الحقل المتجه "dense" المحدد مسبقًا.

# Define embedding function (example: Gemini provider)
text_embedding_function = Function(
    name="gemini_embedding",                        # Unique identifier for this embedding function
    function_type=FunctionType.TEXTEMBEDDING,       # Type of embedding function
    input_field_names=["document"],                 # Scalar field to embed
    output_field_names=["dense"],                   # Vector field to store embeddings
    params={                                        # Provider-specific configuration (highest priority)
        "provider": "gemini",                       # Embedding model provider
        "model_name": "gemini-embedding-001",       # Embedding model
        # Optional parameters:
        # "credential": "apikey_dev",               # Optional: Credential label specified in milvus.yaml
        # "dim": "768",                             # Optional: Output vector dimension (default 3072)
        # "task": "RETRIEVAL_DOCUMENT",             # Optional: Task type for embedding optimization
    }
)

# Add the embedding function to your schema
schema.add_function(text_embedding_function)

أنواع المهام المدعومة لمعلمة المهمة:

• RETRIEVAL_DOCUMENT - تحسين التضمينات لفهرسة المستندات (افتراضي للإدراج/الإدراج).

• RETRIEVAL_QUERY - تحسين التضمينات لاسترجاع الاستعلام (افتراضي للبحث).

• SEMANTIC_SIMILARITY - تحسين التضمينات لقياس تشابه النص.

• CLASSIFICATION - تحسين التضمينات لتصنيف النصوص.

• CLUSTERING - تحسين التضمينات للتجميع.

عندما لا يتم تعيينها بشكل صريح، يستخدم Milvus تلقائيًا RETRIEVAL_DOCUMENT أثناء الإدراج/الإضافة و RETRIEVAL_QUERY أثناء البحث.

تكوين الفهرس

بعد تحديد المخطط مع الحقول الضرورية والوظيفة المدمجة، قم بإعداد الفهرس لمجموعتك. لتبسيط هذه العملية، استخدم AUTOINDEX كـ index_type ، وهو خيار يسمح لـ Milvus باختيار وتكوين نوع الفهرس الأنسب بناءً على بنية بياناتك.

# Prepare index parameters
index_params = client.prepare_index_params()

# Add AUTOINDEX to automatically select optimal indexing method
index_params.add_index(
    field_name="dense",
    index_type="AUTOINDEX",
    metric_type="COSINE" 
)

إنشاء المجموعة

الآن قم بإنشاء المجموعة باستخدام المخطط ومعلمات الفهرس المحددة.

# Create collection named "demo"
client.create_collection(
    collection_name='demo', 
    schema=schema, 
    index_params=index_params
)

الخطوة 2: إدراج البيانات

بعد إعداد المجموعة والفهرس الخاص بك، تكون جاهزًا لإدراج بياناتك الأولية. في هذه العملية، تحتاج فقط إلى توفير النص الخام. تقوم وحدة الدالة التي حددناها سابقًا بإنشاء المتجه المتناثر المقابل تلقائيًا لكل إدخال نصي.

# Insert sample documents
client.insert('demo', [
    {'id': 1, 'document': 'Milvus simplifies semantic search through embeddings.'},
    {'id': 2, 'document': 'Vector embeddings convert text into searchable numeric data.'},
    {'id': 3, 'document': 'Semantic search helps users find relevant information quickly.'},
])

الخطوة 3: البحث بالنص

بعد إدراج البيانات، قم بإجراء بحث دلالي باستخدام نص الاستعلام الخام. يقوم Milvus تلقائيًا بتحويل استعلامك إلى متجه تضمين تلقائيًا، ويسترجع المستندات ذات الصلة بناءً على التشابه، ويعيد النتائج الأكثر مطابقة.

# Perform semantic search
results = client.search(
    collection_name='demo', 
    data=['How does Milvus handle semantic search?'], # Use text query rather than query vector
    anns_field='dense',   # Use the vector field that stores embeddings
    limit=1,
    output_fields=['document'],
)

print(results)

لمزيد من المعلومات حول عمليات البحث والاستعلام، راجع البحث المتجه الأساسي والاستعلام.