Hugging FaceCompatible with Milvus v2.6.20+

عادةً ما يتطلب استخدام نموذج التضمين من Hugging Face أن يقوم تطبيقك بإدارة بيانات الاعتماد، واستدعاء النموذج بشكل منفصل، وإنشاء تضمينات بشكل متسق للبيانات المُدرجة واستعلامات البحث. باستخدام وظيفة تضمين النص (Text Embedding Function)، يقوم Milvus باستدعاء مزودي الاستدلال (Inference Providers) المستضافين من Hugging Face لتحويل النص الخام إلى متجهات أثناء الإدراج والبحث.

يستخدم هذا التكامل جهاز التوجيه المستضاف من Hugging Face. لربط Milvus بخدمة استدلال تضمين النص (TEI) التي تم نشرها بشكل منفصل، راجع Hugging Face TEI.

القيود

• يجب أن يستخدم حقل إخراج الوظيفة نوع البيانات « FLOAT_VECTOR ». لا يدعم التضمين من Hugging Face في Milvus حقول الإخراج « INT8_VECTOR » أو « BINARY_VECTOR » أو « FLOAT16_VECTOR » أو « BFLOAT16_VECTOR ».
• يجب أن يتطابق بُعد حقل إخراج الدالة مع بُعد إخراج النموذج المحدد.

كيفية العمل

سير عمل تضمين النص في Hugging Face

يتكون سير العمل من ثلاث مراحل:

1. إرسال النص الخام. يقدم تطبيقك النص الخام في طلب إدراج أو بحث.
2. إنشاء تضمين. ترسل وظيفة تضمين النص (Text Embedding Function) النص عبر "إرسال النص إلى Hugging Face" ( hf-inference ) إلى مسار "تضمين النص" ( feature-extraction ) في Hugging Face. تستخدم الوظيفة "تحديد النموذج" ( model_name ) لاختيار النموذج ويمكنها تمرير خيارات الاستدلال المدعومة مثل التطبيع والاقتطاع.
3. استخدام التضمين. تُرجع Hugging Face تضمينًا واحدًا ذي نقطة عائمة لكل نص مدخل. أثناء الإدراج، يخزن Milvus المتجه في حقل إخراج الوظيفة. أثناء البحث، يستخدم Milvus المتجه كمتجه الاستعلام.

تتولى نفس تهيئة الوظيفة معالجة الإدراج والبحث، مما يحافظ على اتساق النموذج ومعلمات الاستدلال عبر كلتا العمليتين.

قبل البدء

قبل استخدام تضمين النص المستضاف من Hugging Face، تأكد من توفر ما يلي:

• Milvus 2.6.20 أو إصدار أحدث ضمن سلسلة الإصدارات 2.6.
• PyMilvus 2.6.16 أو أحدث.
• رمز وصول مستخدم Hugging Face يمكنه استدعاء مزودي الاستدلال.
• نموذج يتم تقديمه حاليًا بواسطة hf-inference لـ feature-extraction المهمة.

تستخدم الأمثلة sentence-transformers/all-MiniLM-L6-v2، الذي ينتج تضمينات ذات 384 بُعدًا. يُستخدم النموذج فقط لتوضيح التكوين ولا يمثل توصية أو اعتمادًا من Milvus.

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

يتطلب Milvus رمز وصول مستخدم Hugging Face لاستدعاء الموجه المستضاف. يمكنك تكوين الرمز في milvus.yaml أو من خلال متغير بيئة.

ترتيب أولوية بيانات الاعتماد هو:

Function credential label -> provider credential label in milvus.yaml -> environment variable

الخيار 1: ملف التكوين

حدد الرمز في قسم المستوى الأعلى credential في milvus.yaml ، ثم قم بتوجيه مزود التضمين Hugging Face إلى تسمية بيانات الاعتماد تلك:

# milvus.yaml
credential:
  huggingface_apikey:
    apikey: <YOUR_HUGGING_FACE_TOKEN>

function:
  textEmbedding:
    providers:
      huggingface:
        credential: huggingface_apikey
        # url: https://router.huggingface.co

يمكنك أيضًا تعيين credential في معلمات الوظيفة. يجب أن تكون القيمة هي التسمية المحددة في قسم المستوى الأعلى credential ، وليس الرمز نفسه. وتكون أولوية تسمية بيانات الاعتماد على مستوى الوظيفة أعلى من أولوية التسمية على مستوى المزود.

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

إذا لم تحدد إعدادات الوظيفة أو المزود تسمية بيانات الاعتماد، فإن Milvus يقرأ الرمز المميز من MILVUS_HUGGINGFACE_API_KEY.

بالنسبة إلى Docker Compose، قم بتعيين المتغير في خدمة Milvus المستقلة:

# docker-compose.yaml
standalone:
  environment:
    MILVUS_HUGGINGFACE_API_KEY: <YOUR_HUGGING_FACE_TOKEN>

للحصول على تفاصيل حول تطبيق إعدادات Docker Compose، راجع تكوين Milvus باستخدام Docker Compose.

استخدام تضمين النص في Hugging Face

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

قم بإنشاء مخطط يحتوي على حقل أساسي، وحقل إدخال VARCHAR ، وحقل إخراج FLOAT_VECTOR. يجب أن يتطابق بُعد الإخراج مع النموذج المحدد.

from pymilvus import DataType, Function, FunctionType, MilvusClient

client = MilvusClient(uri="http://localhost:19530")

collection_name = "hugging_face_embedding_demo"
schema = client.create_schema()

schema.add_field(
    field_name="id",
    datatype=DataType.INT64,
    is_primary=True,
    auto_id=False,
)
schema.add_field(
    field_name="document",
    datatype=DataType.VARCHAR,
    max_length=9000,
)
schema.add_field(
    field_name="dense",
    datatype=DataType.FLOAT_VECTOR,
    dim=384,
)

حدد دالة " TEXTEMBEDDING " التي تكتب التضمينات من " document " إلى " dense":

text_embedding_function = Function(
    name="hugging_face_embedding",
    input_field_names=["document"],
    output_field_names=["dense"],
    function_type=FunctionType.TEXTEMBEDDING,
    params={
        "provider": "huggingface",
        "model_name": "sentence-transformers/all-MiniLM-L6-v2",
        "hf_provider": "hf-inference",
        "credential": "huggingface_apikey",
        "normalize": "true",
        "truncate": "true",
        "max_client_batch_size": 128,
    },
)

schema.add_function(text_embedding_function)

إذا كنت تستخدم فقط بيانات الاعتماد على مستوى المزود أو متغير البيئة، فاحذف credential من معلمات الدالة.

قم بتكوين فهرس لحقل الإخراج، ثم أنشئ المجموعة:

index_params = client.prepare_index_params()
index_params.add_index(
    field_name="dense",
    index_type="AUTOINDEX",
    metric_type="COSINE",
)

client.create_collection(
    collection_name=collection_name,
    schema=schema,
    index_params=index_params,
)

يصف الجدول التالي معلمات الوظيفة الخاصة بـ Hugging Face:

المعلمة	مطلوب؟	الوصف
provider	نعم	مزود نموذج التضمين. اضبط هذه القيمة على huggingface.
model_name	نعم	معرف نموذج Hugging Face لنموذج يتم تقديمه عبر hf-inference لمهمة feature-extraction.
hf_provider	لا	مسار مزود الاستدلال في Hugging Face. القيمة الافتراضية والوحيدة المدعومة في Milvus 2.6.20 هي hf-inference.
credential	لا	تسمية بيانات الاعتماد المحددة في قسم credential ذي المستوى الأعلى ضمن milvus.yaml. هذه القيمة ليست الرمز نفسه.
normalize	لا	ما إذا كان يجب على Hugging Face إرجاع التضمينات المعيارية. القيم المدعومة هي true و false. إذا تم حذفها، فإن Milvus لا يضبط هذا الخيار في الطلب.
prompt_name	لا	اسم الموجه المحدد في تكوين Sentence Transformers للنموذج المحدد.
truncate	لا	ما إذا كان يجب على Hugging Face اقتطاع المدخلات التي تتجاوز الطول المدعوم من قبل النموذج. القيم المدعومة هي true و false.
truncation_direction	لا	الاتجاه الذي يقوم Hugging Face من خلاله باقتطاع المدخلات. القيم المدعومة هي left و right.
max_client_batch_size	لا	الحد الأقصى لعدد النصوص المدخلة المرسلة في طلب Hugging Face واحد. القيمة الافتراضية هي 128 ، ويجب أن تكون القيمة أكبر من 0.

الخطوة 2: إدراج النص الخام

أدخل النص دون توفير متجهات. يقوم Milvus باستدعاء Hugging Face وكتابة التضمينات التي تم إنشاؤها إلى dense.

client.insert(
    collection_name=collection_name,
    data=[
        {
            "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 نفس تكوين الوظيفة لإنشاء متجه الاستعلام قبل تشغيل البحث المتجهي.

results = client.search(
    collection_name=collection_name,
    data=["How does Milvus handle semantic search?"],
    anns_field="dense",
    limit=3,
    output_fields=["document"],
    consistency_level="Strong",
)

print(results)

تحتوي النتيجة على المستندات الأكثر صلة بنص الاستعلام، مرتبة حسب تشابه جيب التمام.

استكشاف الأخطاء وإصلاحها

النموذج غير متاح لاستخراج الميزات

افتح صفحة النموذج على Hugging Face وتحقق من قسم " Inference Providers " (مزودي الاستدلال). تأكد من أن " hf-inference " يقدم النموذج لـ " feature-extraction" (الاستدلال على النص). إذا لم يكن الأمر كذلك، فحدد نموذجًا آخر وقم بتحديث بُعد حقل المتجه إذا لزم الأمر.

أبعاد المتجه المرتجعة لا تتطابق مع الحقل

تحقق من بُعد مخرجات النموذج وقارنه مع dim في حقل «مخرجات الدالة» (Function output). يرفض Milvus أي استجابة يختلف بُعد متجهها عن بُعد حقل «مخرجات الدالة» ( FLOAT_VECTOR ).

يبلغ Milvus عن فقدان بيانات اعتماد Hugging Face

تأكد من وجود تسمية بيانات اعتماد الوظيفة (Function credential) في قسم «بيانات اعتماد Hugging Face» ( credential ) على المستوى الأعلى، أو أن التسمية على مستوى المزود صالحة، أو أن «بيانات اعتماد Hugging Face» ( MILVUS_HUGGINGFACE_API_KEY ) موجودة في بيئة خدمة Milvus.

الخطوات التالية

• للاطلاع على المفاهيم العامة لـ Function وسلوك الإدراج/البحث، راجع نظرة عامة على Embedding Function.
• لإعادة ترتيب المرشحين في البحث المتجه باستخدام درجات تشابه الجمل المستضافة من Hugging Face، راجع Hugging Face Ranker.