نظرة عامة على وظيفة التضمينCompatible with Milvus 2.6.x

تسمح لك وحدة الدالة في Milvus بتحويل البيانات النصية الخام إلى تضمينات متجهة عن طريق الاتصال تلقائيًا بموفري خدمة التضمين الخارجيين (مثل OpenAI و AWS Bedrock و Google Vertex AI، إلخ). باستخدام الوحدة النمطية Function، لم تعد بحاجة إلى التفاعل يدويًا مع واجهات برمجة تطبيقات التضمين - حيث تتولى ميلفوس العملية الكاملة لإرسال الطلبات إلى مقدمي الخدمات، واستلام التضمينات، وتخزينها في مجموعاتك. للبحث الدلالي، تحتاج إلى توفير بيانات استعلام أولية فقط، وليس متجه استعلام. ينشئ Milvus متجه الاستعلام بنفس النموذج الذي استخدمته في الاستيعاب، ويقارنه بالمتجهات المخزنة، ويعيد النتائج الأكثر صلة.

الحدود

• يجب أن يحتوي أي حقل إدخال تقوم الوحدة النمطية "الدالة" بتضمينه على قيمة دائمًا؛ إذا تم توفير حقل فارغ، فستعرض الوحدة النمطية خطأ.

• تعالج الوحدة النمطية الدالة فقط الحقول التي تم تعريفها صراحةً في مخطط المجموعة؛ فهي لا تنشئ تضمينات للحقول الديناميكية.

• يجب أن تكون حقول الإدخال المراد تضمينها من النوع VARCHAR.

• يمكن للوحدة النمطية الدالة تضمين حقل الإدخال إلى:

  • FLOAT_VECTOR

  • INT8_VECTOR

  لا يتم دعم التحويلات إلى BINARY_VECTOR أو FLOAT16_VECTOR أو BFLOAT16_VECTOR.

موفرو خدمة التضمين المدعومون

الموفر	النماذج النموذجية	نوع التضمين	طريقة التوثيق
OpenAI	تضمين النص-3-*	FLOAT_VECTOR	مفتاح API
Azure OpenAI	قائم على النشر	FLOAT_VECTOR	مفتاح API
داش سكوب	تضمين النص-تضمين النص-ف3	FLOAT_VECTOR	مفتاح API
بيدروك	أمازون.تيتان-تضمين النص-ف2	FLOAT_VECTOR	زوج AK/SK
فيرتكس AI	تضمين النص-005	FLOAT_VECTOR	بيانات اعتماد JSON لحساب خدمة GCP
Voyage AI	رحلة-3، رحلة-لايت-02	FLOAT_VECTOR / INT8_VECTOR	مفتاح واجهة برمجة التطبيقات
كوهير	تضمين-الإنجليزية-v3.0	FLOAT_VECTOR / INT8_VECTOR	مفتاح API
سيليكون فلو	BAAI/Bge-large-zh-v1.5	FLOAT_VECTOR	مفتاح API
وجه المعانقة	أي نموذج مخدوم من TEI	FLOAT_VECTOR	مفتاح API اختياري

كيف تعمل

يوضح الرسم البياني التالي كيفية عمل الوظيفة في ميلفوس.

1. إدخال النص: يُدخل المستخدمون البيانات الأولية (مثل المستندات) في ملفوس.

2. توليد التضمينات: تستدعي وحدة الدالة في ميلفوس تلقائيًا موفر النموذج المهيأ لتحويل البيانات الأولية إلى تضمينات متجهة.

3. تخزين التضمينات: يتم تخزين التضمينات الناتجة في حقول متجهية محددة بشكل صريح ضمن مجموعات Milvus.

4. نص الاستعلام: يرسل المستخدمون استعلامات نصية إلى ميلفوس.

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

6. إرجاع النتائج: يقوم ميلفوس بإرجاع أفضل النتائج المطابقة إلى التطبيق.

نظرة عامة على وظيفة التضمين

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

قبل استخدام دالة تضمين مع Milvus، قم بتكوين بيانات اعتماد خدمة التضمين للوصول إلى Milvus.

يتيح لك Milvus توفير بيانات اعتماد خدمة التضمين بطريقتين:

• ملف التكوين (milvus.yaml):

  يوضح المثال في هذا الموضوع الإعداد الموصى به باستخدام milvus.yaml.

• متغيرات البيئة:

  للحصول على تفاصيل حول تكوين بيانات الاعتماد عبر متغيرات البيئة، راجع وثائق موفر خدمة التضمين (على سبيل المثال، OpenAI أو Azure OpenAI).

يوضح الرسم البياني التالي عملية تكوين بيانات الاعتماد عبر ملف تكوين Milvus (milvus.yaml) ثم استدعاء الوظيفة داخل Milvus.

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

الخطوة 1: إضافة بيانات الاعتماد إلى ملف تكوين Milvus

في ملف milvus.yaml الخاص بك، قم بتحرير كتلة credential مع إدخالات لكل موفر تحتاج إلى الوصول إليه:

# milvus.yaml credential store section
# This section defines all your authentication credentials for external embedding providers
# Each credential gets a unique name (e.g., aksk1, apikey1) that you'll reference elsewhere
credential:
  # For AWS Bedrock or services using access/secret key pairs
  # 'aksk1' is just an example name - you can choose any meaningful identifier
  aksk1:                       
    access_key_id: <YOUR_AK>      
    secret_access_key: <YOUR_SK>  
  
  # For OpenAI, Voyage AI, or other API key-based services
  # 'apikey1' is a custom name you choose to identify this credential  
  apikey1:                     
    apikey: <YOUR_API_KEY>        
  
  # For Google Vertex AI using service account credentials
  # 'gcp1' is an example name for your Google Cloud credentials
  gcp1:                        
    credential_json: <BASE64_OF_JSON>

الخطوة 2: تكوين إعدادات الموفر

في ملف التكوين نفسه (milvus.yaml)، قم بتحرير المكوِّن function لإخبار ميلفوس بالمفتاح الذي يجب استخدامه لتضمين استدعاءات الخدمة:

function:
  textEmbedding:
    providers:
      openai:                         # calls OpenAI
        credential: apikey1           # Reference to the credential label
        # url:                        # (optional) custom url

      bedrock:                        # calls AWS Bedrock
        credential: aksk1             # Reference to the credential label
        region: us-east-2

      vertexai:                       # calls Google Vertex AI
        credential: gcp1              # Reference to the credential label
        # url:                        # (optional) custom url

      tei:                            # Built-in Tiny Embedding model
        enable: true                  # Whether to enable TEI model service

لمزيد من المعلومات حول كيفية تطبيق تكوين Milvus، راجع تكوين Milvus أثناء التنقل.

استخدام وظيفة التضمين

بمجرد تكوين بيانات الاعتماد في ملف تكوين Milvus الخاص بك، اتبع هذه الخطوات لتعريف دوال التضمين واستخدامها.

الخطوة 1: تحديد حقول المخطط

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

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

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

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

يحدد المثال التالي مخططًا يحتوي على حقل قياسي واحد "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, OpenAI's text-embedding-3-small model outputs 1536-dimensional vectors.
# For dense vector, data type can be FLOAT_VECTOR or INT8_VECTOR
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=1536)

// java

// nodejs

// go

# restful

الخطوة 2: إضافة دالة التضمين إلى المخطط

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

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

# Define embedding function (example: OpenAI provider)
text_embedding_function = Function(
    name="openai_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": "openai",                 # Embedding model provider
        "model_name": "text-embedding-3-small",     # Embedding model
        # "credential": "apikey1",            # Optional: Credential label
        # Optional parameters:
        # "dim": "1536",       # Optionally shorten the vector dimension
        # "user": "user123"    # Optional: identifier for API tracking
    }
)

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

// java

// nodejs

// go

# restful

المعلمة	الوصف	مثال القيمة
name	المعرف الفريد لدالة التضمين داخل ميلفوس.	"openai_embedding"
function_type	نوع الدالة المستخدمة. لتضمين النص، اضبط القيمة على FunctionType.TEXTEMBEDDING. ملاحظة: يقبل Milvus FunctionType.BM25 (لتحويل التضمين المتناثر) و FunctionType.RERANK (لإعادة الترتيب) لهذه المعلمة. ارجع إلى نظرة عامة على البحث عن النص الكامل وتناقص التصنيف للحصول على التفاصيل.	FunctionType.TEXTEMBEDDING
input_field_names	الحقل العددي الذي يحتوي على البيانات الأولية المراد تضمينها. تقبل هذه المعلمة حاليًا اسم حقل واحد فقط.	["document"]
output_field_names	حقل متجه لتخزين التضمينات التي تم إنشاؤها. تقبل هذه المعلمة حالياً اسم حقل واحد فقط.	["dense"]
params	قاموس يحتوي على تكوينات التضمين. ملاحظة: تختلف المعلمات داخل params اعتماداً على موفري نماذج التضمين.	{...}
provider	موفر نموذج التضمين.	"openai"
model_name	يحدد نموذج التضمين المراد استخدامه.	"text-embedding-3-small"
credential	تسمية بيانات الاعتماد المحددة في قسم المستوى الأعلى credential: من milvus.yaml. عند توفيره، يسترد Milvus زوج المفاتيح المطابق أو رمز واجهة برمجة التطبيقات المطابق ويوقع الطلب من جانب الخادم. عند حذفها (None)، يعود ميلفوس إلى بيانات الاعتماد التي تم تكوينها صراحةً لمزود النموذج الهدف في milvus.yaml. إذا كانت التسمية غير معروفة أو كان المفتاح المشار إليه مفقودًا، يفشل الاستدعاء.	"apikey1"
dim	عدد الأبعاد لتضمينات الإخراج. بالنسبة لنماذج الجيل الثالث من OpenAI، يمكنك اختصار المتجه الكامل لتقليل التكلفة والكمون دون خسارة كبيرة في المعلومات الدلالية. لمزيد من المعلومات، راجع منشور مدونة إعلان OpenAI. ملاحظة: إذا قمت بتقصير بُعد المتجه، تأكد من أن القيمة dim المحددة في طريقة add_field الخاصة بالمخطط لحقل المتجه تطابق بُعد الإخراج النهائي لدالة التضمين الخاصة بك.	"1536"
user	معرّف على مستوى المستخدم لتتبع استخدام واجهة برمجة التطبيقات.	"user123"

الخطوة 3: تكوين الفهرس

بعد تحديد المخطط مع الحقول الضرورية والدالة المدمجة، قم بإعداد الفهرس لمجموعتك. لتبسيط هذه العملية، استخدم 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" 
)

// java

// nodejs

// go

# restful

الخطوة 4: إنشاء مجموعة

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

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

// java

// nodejs

// go

# restful

الخطوة 5: أدخل البيانات

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

# 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.'},
])

// java

// nodejs

// go

# restful

الخطوة 6: إجراء بحث المتجه

بعد إدخال البيانات، قم بإجراء بحث دلالي باستخدام نص الاستعلام الخام. يقوم 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)

# Example output:
# data: ["[{'id': 1, 'distance': 0.8821347951889038, 'entity': {'document': 'Milvus simplifies semantic search through embeddings.'}}]"]

// java

// nodejs

// go

# restful

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

الأسئلة الشائعة

ما الفرق بين تكوين بيانات الاعتماد في milvus.yaml مقابل متغيرات البيئة؟

تعمل كلتا الطريقتين، لكن استخدام milvus.yaml هو النهج الموصى به لأنه يوفر إدارة مركزية لبيانات الاعتماد وتسمية متسقة لبيانات الاعتماد عبر جميع الموفرين. عند استخدام متغيرات البيئة، تختلف أسماء المتغيرات اعتمادًا على موفر خدمة التضمين، لذا راجع الصفحة المخصصة لكل موفر لفهم أسماء متغيرات البيئة المحددة المطلوبة (على سبيل المثال، OpenAI أو Azure OpenAI).

ماذا يحدث إذا لم أحدد معلمة بيانات الاعتماد في تعريف الدالة؟

يتبع ميلفوس ترتيب حل بيانات الاعتماد هذا:

1. أولاً، يبحث عن بيانات الاعتماد الافتراضية التي تم تكوينها لهذا الموفر في الملف milvus.yaml
2. في حالة عدم وجود بيانات الاعتماد الافتراضية في ملف milvus.yaml، فإنه يعود إلى متغيرات البيئة (إذا تم تكوينها)
3. إذا لم يتم تكوين بيانات الاعتماد milvus.yaml ولا متغيرات البيئة، فسيقوم ميلفوس بإلقاء خطأ

كيف يمكنني التحقق من أن التضمينات يتم إنشاؤها بشكل صحيح؟

يمكنك التحقق من ذلك عن طريق:

1. الاستعلام عن مجموعتك بعد التضمين لمعرفة ما إذا كان حقل المتجه يحتوي على بيانات
2. التحقق من أن طول الحقل المتجه يطابق أبعادك المتوقعة
3. إجراء بحث تشابه بسيط للتحقق من أن التضمينات تنتج نتائج ذات مغزى

عندما أقوم بإجراء بحث تشابه، هل يمكنني استخدام متجه استعلام بدلاً من النص الخام؟

نعم، يمكنك استخدام متجهات الاستعلام المحسوبة مسبقًا بدلاً من النص الخام للبحث عن التشابه. بينما تقوم الوحدة النمطية Function بتحويل الاستعلامات النصية الأولية تلقائيًا إلى استعلامات نصية خام إلى متجهات، يمكنك أيضًا توفير بيانات المتجهات مباشرةً إلى المعلمة data في عملية البحث الخاصة بك. ملاحظة: يجب أن يكون حجم أبعاد متجه الاستعلام المقدم متوافقًا مع حجم أبعاد المتجهات المضمنة التي تم إنشاؤها بواسطة الوحدة النمطية Function.

مثال:

# Using raw text (Function module converts automatically)
results = client.search(
    collection_name='demo', 
    data=['How does Milvus handle semantic search?'],
    anns_field='dense',
    limit=1
)

# Using pre-computed query vector (must match stored vector dimensions)
query_vector = [0.1, 0.2, 0.3, ...]  # Must be same dimension as stored embeddings
results = client.search(
    collection_name='demo', 
    data=[query_vector],
    anns_field='dense',
    limit=1
)

// java

// nodejs

// go

# restful