Azure OpenAICompatible with Milvus 2.6.x

يصف هذا الموضوع كيفية تكوين واستخدام وظائف تضمين Azure OpenAI في Milvus.

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

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

النموذج	الأبعاد	الحد الأقصى للرموز	الوصف
تضمين النص-التضمين 3-صغير	افتراضي: 1,536 (قابل للتحويل إلى حجم بعد أقل من 1536)	8,191	مثالي للبحث الدلالي الحساس من حيث التكلفة والقابل للتطوير-يقدم أداءً قوياً بسعر أقل.
نص-تضمين النص-3-كبير	افتراضي: 3,072 3 (قابل للتقسيم إلى حجم أبعاد أقل من 3072)	8,191	الأفضل للتطبيقات التي تتطلب دقة استرجاع محسّنة وتمثيلات دلالية أكثر ثراءً.
تضمين النص-تضمين النص-ADA-002	ثابت: 1,536 (لا يدعم الاقتطاع)	8,191	نموذج الجيل السابق المناسب لخطوط الأنابيب القديمة أو السيناريوهات التي تتطلب التوافق مع الإصدارات السابقة.

يدعم الجيل الثالث من نماذج التضمين من الجيل الثالث(تضمين النص-3) تقليل حجم التضمين عبر معلمة dim. عادةً ما تكون التضمينات الأكبر حجمًا أكثر تكلفة من منظور الحوسبة والذاكرة والتخزين. تتيح القدرة على ضبط عدد الأبعاد مزيدًا من التحكم في التكلفة الإجمالية والأداء. لمزيد من التفاصيل حول كل نموذج، راجع التضمينات.

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

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

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

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

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

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

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

1. **أعلن مفاتيحك تحت credential:

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

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

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

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

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

   function:
     textEmbedding:
       providers:
         azure_openai:
           credential: apikey_dev      # ← choose any label you defined above
           resource_name:  # Your azure openai resource name
           # url: # Your azure openai embedding url
   

   يؤدي هذا إلى ربط مفتاح معين بكل طلب يرسله Milvus إلى نقطة نهاية تضمينات Azure OpenAI.

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

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

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

المتغير	مطلوب	الوصف
MILVUSAI_AZURE_OPENAI_API_KEY	نعم	يجعل مفتاح Azure OpenAI متاحًا داخل كل حاوية Milvus (يتم تجاهله عند وجود مفتاح Azure OpenAI في milvus.yaml )
MILVUSAI_AZURE_OPENAI_RESOURCE_NAME	نعم	اسم مورد Azure OpenAI الخاص بك كما تم تعريفه عند إنشاء مورد خدمة Azure OpenAI الخاص بك.

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

# docker-compose.yaml (standalone service section)
standalone:
  # ... other configurations ...
  environment:
    # ... other environment variables ...
    # Set the environment variable pointing to the Azure OpenAI API key inside the container
    MILVUSAI_AZURE_OPENAI_API_KEY: <MILVUSAI_AZURE_OPENAI_API_KEY>
    MILVUSAI_AZURE_OPENAI_RESOURCE_NAME: <MILVUSAI_AZURE_OPENAI_RESOURCE_NAME>

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

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

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

الخطوة 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.
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=1536)

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

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

# Define embedding function specifically for Azure OpenAI provider
text_embedding_function = Function(
    name="azopenai",                                # Unique identifier for this embedding function
    function_type=FunctionType.TEXTEMBEDDING,       # Indicates a text embedding function
    input_field_names=["document"],                 # Scalar field(s) containing text data to embed
    output_field_names=["dense"],                   # Vector field(s) for storing embeddings
    params={                                        # Provider-specific embedding parameters
        "provider": "azure_openai",                 # Embedding provider name (must be "azure_openai")
        "model_name": "zilliz-text-embedding-3-small",      # Model should be set to the deployment name you chose when you deployed the embedding model
        # Optional parameters (only specify if necessary):
        # "url": "https://{resource_name}.openai.azure.com/" # Optional: Your Azure OpenAI service endpoint
        # "credential": "apikey_dev",               # Optional: Credential label specified in milvus.yaml
        # "dim": "1536",                            # Optional: Shorten the output vector dimension
        # "user": "user123",                        # Optional: identifier for API tracking
    }
)

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

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

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