الترقية إلى أحدث واجهة برمجة تطبيقات REST في Azure الذكاء الاصطناعي Search

مقالة
05/06/2024

استخدم هذه المقالة لترحيل استدعاءات مستوى البيانات إلى إصدارات أحدث من Search REST API.

2023-11-01 هو أحدث إصدار مستقر. الترتيب الدلالي والدعم للفهرسة المتجهة والاستعلامات متاحة بشكل عام في هذا الإصدار.
معاينة 2023-10-01 هي أحدث إصدار معاينة. تتضمن ميزات المعاينة متجهات الاستعلام المضمنة، وتقسيم البيانات المضمنة، والتجهيز أثناء الفهرسة (تستخدم مهارة تقسيم النص ومهارة تضمين Azure OpenAI).
معاينة 2023-07-01 كانت واجهة برمجة تطبيقات REST الأولى لدعم المتجهات. تم إهماله الآن ويجب عليك الترحيل إلى إما 2023-11-01 أو 2023-10-01-preview على الفور.

إشعار

تم إصدار المستندات المرجعية لواجهة برمجة تطبيقات REST الآن. للحصول على المحتوى الصحيح، افتح صفحة مرجعية ثم قم بالتصفية حسب الإصدار، باستخدام المحدد الموجود أعلى جدول المحتويات.

متى يتم الترقية

يكسر Azure الذكاء الاصطناعي Search التوافق مع الإصدارات السابقة كحل أخير. الترقية ضرورية عندما:

تشير التعليمات البرمجية إلى إصدار واجهة برمجة تطبيقات متوقف أو مهمل وتخضع لواحد أو أكثر من التغييرات العاجلة. تتضمن إصدارات واجهة برمجة التطبيقات التي تندرج في هذه الفئة معاينة 2023-07-10 للخطوط المتجهة و2019-05-06.
تفشل التعليمات البرمجية الخاصة بك عند إرجاع الخصائص غير المعترف بها في استجابة واجهة برمجة التطبيقات. كأفضل ممارسة، يجب أن يتجاهل تطبيقك الخصائص التي لا يفهمها.
تستمر التعليمات البرمجية في طلبات واجهة برمجة التطبيقات وتحاول إعادة إرسالها إلى إصدار واجهة برمجة التطبيقات الجديد. على سبيل المثال، قد يحدث هذا إذا استمر التطبيق الخاص بك في متابعة الرموز المميزة التي تم إرجاعها من Search API (لمزيد من المعلومات، ابحث @search.nextPageParameters عن في مرجع Search API).

تغيير كسر التعليمات البرمجية للعميل الذي يقرأ معلومات الاتصال

اعتبارا من 29 مارس 2024 وينطبق على جميع واجهات برمجة تطبيقات REST المدعومة:

لم تعد GET Skillset و GET Index و GET Indexer ترجع المفاتيح أو خصائص الاتصال في استجابة. هذا تغيير فاصل إذا كان لديك تعليمة برمجية انتقال البيانات من الخادم تقرأ المفاتيح أو الاتصالات (البيانات الحساسة) من استجابة GET.
إذا كنت بحاجة إلى استرداد مفاتيح واجهة برمجة تطبيقات المسؤول أو الاستعلام لخدمة البحث، فاستخدم واجهات برمجة تطبيقات REST للإدارة.
إذا كنت بحاجة إلى استرداد سلسلة الاتصال لمورد Azure آخر مثل Azure Storage أو Azure Cosmos DB، فاستخدم واجهات برمجة التطبيقات لهذا المورد وإرشادات منشورة للحصول على المعلومات.

الترقية إلى معاينة 2023-10-01

يشرح هذا القسم مسار الترحيل من 2023-07-01-preview إلى 2023-10-01-preview. يجب الترحيل إلى معاينة 2023-10-01 إذا كنت تريد استخدام ميزات المتجهات التي لا تزال في المعاينة العامة. إذا لم تكن بحاجة إلى ميزات المعاينة، نوصي بالترقية إلى الإصدار المستقر، 2023-11-01.

تتضمن ميزات المعاينة ما يلي:

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

في المقابل، تغيرت تعريفات حقل المتجه وتكوين خوارزمية البحث عن المتجهات وبناء جملة استعلام المتجهات التي تم تقديمها لأول مرة في 2023-07-01-preview. بناء الجملة 2023-10-01-preview لحقول المتجهات والخوارزميات واستعلامات المتجهات متطابقة مع بناء الجملة 2023-11-01. يتم شرح خطوات الترحيل لبنى المتجهات هذه في الترقية إلى 2023-11-01.

ترقية المدخل لفهرس المتجهات

يدعم مدخل Microsoft Azure مسار ترقية بنقرة واحدة لفهرس معاينة 2023-07-01. يكشف المدخل عن حقول متجه 2023-07-01-preview ويوفر زر ترحيل .

مسار الترحيل من 2023-07-01-preview إلى 2023-10-01-preview.
تقتصر التحديثات على تعريفات حقول المتجهات وتكوينات خوارزمية البحث عن المتجهات.
التحديثات أحادي الاتجاه. لا يمكنك عكس الترقية. بمجرد ترقية الفهرس، يجب استخدام معاينة 2023-10-01 أو إصدار أحدث للاستعلام عن الفهرس.

لا يوجد ترحيل المدخل لترقية بناء جملة استعلام المتجهات. راجع الترقية إلى 2023-11-01 للاطلاع على تغييرات بناء جملة الاستعلام.

قبل تحديد Migrate، حدد Edit JSON لمراجعة المخطط المحدث أولا. يجب أن تجد مخططا يتوافق مع التغييرات الموضحة في الترقية إلى 2023-11-01. يعالج ترحيل المدخل الفهارس فقط بتكوين خوارزمية بحث متجه واحدة. يقوم بإنشاء ملف تعريف افتراضي يعين إلى خوارزمية البحث المتجه 2023-07-01-preview. تتطلب الفهارس ذات تكوينات بحث المتجهات المتعددة ترحيلا يدويا.

الترقية إلى 2023-11-01

يحتوي هذا الإصدار على تغييرات فاصلة واختلافات سلوكية للتصنيف الدلالي ودعم البحث المتجه.

الترتيب الدلالي متاح بشكل عام في 2023-11-01. لم يعد يستخدم الخاصية queryLanguage . كما يتطلب تعريفا semanticConfiguration . يستبدل semanticConfigurationsearchFields في الإصدارات السابقة. راجع الترحيل من إصدار المعاينة للاطلاع على الخطوات.
تم تقديم دعم البحث المتجه في إنشاء فهرس أو تحديثه (2023-07-01-preview). تتطلب الترقية من 2023-07-01-preview إعادة تسمية وإعادة هيكلة تكوين المتجه في الفهرس. كما يتطلب إعادة كتابة استعلامات المتجهات. استخدم الإرشادات الموجودة في هذا القسم لترحيل حقول المتجهات والتكوين والاستعلامات.

إذا كنت تقوم بالترقية من 2023-10-01-preview إلى 2023-11-01، فلا توجد تغييرات فاصلة، ولكن هناك اختلاف واحد في السلوك: vectorFilterMode تم تغيير الافتراضي من عامل تصفية البريد إلى التصفية المسبقة لتعبيرات التصفية. إذا لم يتم تعيين vectorFilterMode التعليمات البرمجية 2023-10-01-preview بشكل صريح، فتأكد من فهم السلوك الافتراضي الجديد، أو تعيين vectorFilterMode صريح إلى postfilter للاحتفاظ بالسلوك القديم.

فيما يلي خطوات الترحيل من 2023-07-01-preview إلى 2023-11-01:

اتصل ب Get Index لاسترداد التعريف الموجود.
تعديل تكوين البحث المتجه. يقدم 2023-11-01 مفهوم ملفات تعريف المتجهات التي تجمع التكوينات المتعلقة بالمتجه تحت اسم واحد. كما أنه يعيد تسمية algorithmConfigurations إلى algorithms.
- أعد تسمية algorithmConfigurations إلى algorithms. هذه مجرد إعادة تسمية للصفيف. المحتويات متوافقة مع الإصدارات السابقة. وهذا يعني أنه يمكن استخدام معلمات تكوين HNSW الحالية.
- إضافة profiles، وإعطاء اسم وتكوين خوارزمية لكل واحد.
قبل الترحيل (2023-07-01-preview):
```
  "vectorSearch": {
    "algorithmConfigurations": [
        {
            "name": "myHnswConfig",
            "kind": "hnsw",
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]}
```
بعد الترحيل (2023-11-01):
```
  "vectorSearch": {
    "algorithms": [
      {
        "name": "myHnswConfig",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ],
    "profiles": [
      {
        "name": "myHnswProfile",
        "algorithm": "myHnswConfig"
      }
    ]
  }
```

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

قبل (2023-07-01-preview):

  {
      "name": "contentVector",
      "type": "Collection(Edm.Single)",
      "key": false,
      "searchable": true,
      "retrievable": true,
      "filterable": false,  
      "sortable": false,  
      "facetable": false,
      "analyzer": "",
      "searchAnalyzer": "",
      "indexAnalyzer": "",
      "normalizer": "",
      "synonymMaps": "", 
      "dimensions": 1536,
      "vectorSearchConfiguration": "myHnswConfig"
  }

بعد (2023-11-01):

  {
    "name": "contentVector",
    "type": "Collection(Edm.Single)",
    "searchable": true,
    "retrievable": true,
    "filterable": false,  
    "sortable": false,  
    "facetable": false,
    "analyzer": "",
    "searchAnalyzer": "",
    "indexAnalyzer": "",
    "normalizer": "",
    "synonymMaps": "", 
    "dimensions": 1536,
    "vectorSearchProfile": "myHnswProfile"
  }

اتصل بإنشاء فهرس أو تحديثه لنشر التغييرات.
تعديل Search POST لتغيير بناء جملة الاستعلام. يتيح تغيير واجهة برمجة التطبيقات هذا دعم أنواع استعلام المتجهات متعددة الأشكال.
- أعد تسمية vectors إلى vectorQueries.
- لكل استعلام متجه، أضف kind، ثم قم بتعيينه إلى vector.
- لكل استعلام متجه، أعد تسمية value إلى vector.
- بشكل اختياري، أضف vectorFilterMode إذا كنت تستخدم تعبيرات عامل التصفية. الافتراضي هو التصفية المسبقة للفهرس التي تم إنشاؤها بعد 2023-10-01. لا تدعم الفهارس التي تم إنشاؤها قبل ذلك التاريخ سوى التصفية البريدية، بغض النظر عن كيفية تعيين وضع التصفية.
قبل (2023-07-01-preview):
```
{
    "search": (this parameter is ignored in vector search),
    "vectors": [
      {
        "value": [
            0.103,
            0.0712,
            0.0852,
            0.1547,
            0.1183
        ],
        "fields": "contentVector",
        "k": 5
      }
    ],
    "select": "title, content, category"
}
```
بعد (2023-11-01):
```
{
  "search": "(this parameter is ignored in vector search)",
  "vectorQueries": [
    {
      "kind": "vector",
      "vector": [
        0.103,
        0.0712,
        0.0852,
        0.1547,
        0.1183
      ],
      "fields": "contentVector",
      "k": 5
    }
  ],
  "vectorFilterMode": "preFilter",
  "select": "title, content, category"
}
```

تكمل هذه الخطوات الترحيل إلى إصدار واجهة برمجة التطبيقات 2023-11-01.

الترقية إلى 2020-06-30

في هذا الإصدار، هناك تغيير واحد كسر والعديد من الاختلافات السلوكية. تتضمن الميزات المتوفرة بشكل عام ما يلي:

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

كسر التغيير

يتم تشغيل التعليمات البرمجية المكتوبة مقابل إصدارات واجهة برمجة التطبيقات السابقة والإصدارات الأحدث إذا كانت التعليمات 2020-06-30 البرمجية تحتوي على الوظائف التالية:

يجب أن تتبع أي Edm.Date قيم حرفية (تاريخ يتكون من يوم من السنة إلى شهر، مثل 2020-12-12) في تعبيرات عامل التصفية Edm.DateTimeOffset التنسيق: 2020-12-12T00:00:00Z. كان هذا التغيير ضروريا لمعالجة نتائج الاستعلام الخاطئة أو غير المتوقعة بسبب اختلافات المنطقة الزمنية.

تغييرات السلوك

تستبدل خوارزمية ترتيب BM25 خوارزمية الترتيب السابقة بتقنية أحدث. تستخدم الخدمات التي تم إنشاؤها بعد عام 2019 هذه الخوارزمية تلقائيا. بالنسبة للخدمات القديمة، يجب تعيين معلمات لاستخدام الخوارزمية الجديدة.
تم تغيير النتائج مرتبة للقيم الخالية في هذا الإصدار، مع ظهور القيم الخالية أولا إذا كان الفرز asc والأخير إذا كان الفرز هو desc. إذا كتبت تعليمة برمجية للتعامل مع كيفية فرز القيم الخالية، فكن على دراية بهذا التغيير.

الترقية إلى 2019-05-06

تتضمن الميزات التي أصبحت متوفرة بشكل عام في إصدار واجهة برمجة التطبيقات هذا ما يلي:

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

كسر التغييرات

يتم تشغيل التعليمات البرمجية المكتوبة مقابل إصدار واجهة برمجة تطبيقات سابق والإصدارات 2019-05-06 الأحدث إذا كانت تحتوي على الوظائف التالية:

خاصية النوع ل Azure Cosmos DB. بالنسبة للمفهرسات التي تستهدف مصدر بيانات Azure Cosmos DB ل NoSQL API ، قم بالتغيير "type": "documentdb" إلى "type": "cosmosdb".
إذا كانت معالجة أخطاء المفهرس تتضمن مراجع إلى الخاصية status ، فيجب إزالتها. لقد أزلنا الحالة من استجابة الخطأ لأنها لم توفر معلومات مفيدة.
لم تعد سلسلة الاتصال مصدر البيانات يتم إرجاعها في الاستجابة. من إصدارات 2019-05-06 واجهة برمجة التطبيقات وما 2019-05-06-Preview بعدها، لم تعد واجهة برمجة تطبيقات مصدر البيانات ترجع سلسلة الاتصال استجابة لأي عملية REST. في إصدارات واجهة برمجة التطبيقات السابقة، بالنسبة لمصادر البيانات التي تم إنشاؤها باستخدام POST، أرجع Azure الذكاء الاصطناعي Search 201 متبوعا باستجابة OData، التي تحتوي على سلسلة الاتصال في نص عادي.
تم إيقاف المهارة المعرفية التعرف على الكيان المسماة. إذا قمت باستدعاء مهارة التعرف على كيان الاسم في التعليمات البرمجية الخاصة بك، يفشل الاستدعاء. وظيفة الاستبدال هي مهارة التعرف على الكيان (V3). اتبع التوصيات الواردة في المهارات المهملة للترحيل إلى مهارة مدعومة.

ترقية الأنواع المعقدة

أضاف إصدار 2019-05-06 واجهة برمجة التطبيقات دعما رسميا للأنوع المعقدة. إذا نفذت التعليمات البرمجية توصيات سابقة لتكافؤ النوع المعقد في 2017-11-11-Preview أو 2016-09-01-Preview، فهناك بعض الحدود الجديدة والمتغيرة بدءا من الإصدار 2019-05-06 الذي يجب أن تكون على علم به:

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

لمزيد من المعلومات، راجع حدود الخدمة ل Azure الذكاء الاصطناعي Search.

كيفية ترقية بنية نوع معقدة قديمة

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

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType" },
    { "name": "Address/StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
    { "name": "Address/City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)" }, 
    { "name": "Rooms/Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
    { "name": "Rooms/Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
    { "name": "Rooms/Type", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
    { "name": "Rooms/BedOptions", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
    { "name": "Rooms/SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
    { "name": "Rooms/Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
  ]
}

تم تقديم تنسيق أحدث يشبه الشجرة لتعريف حقول الفهرس في إصدار 2017-11-11-Previewواجهة برمجة التطبيقات . في التنسيق الجديد، يحتوي كل حقل معقد على مجموعة حقول حيث يتم تعريف حقوله الفرعية. في إصدار API 2019-05-06، يتم استخدام هذا التنسيق الجديد حصريا وستفشل محاولة إنشاء فهرس أو تحديثه باستخدام التنسيق القديم. إذا كانت لديك فهارس تم إنشاؤها باستخدام التنسيق القديم، فستحتاج إلى استخدام إصدار 2017-11-11-Preview واجهة برمجة التطبيقات لتحديثها إلى التنسيق الجديد قبل أن تتمكن من إدارتها باستخدام إصدار واجهة برمجة التطبيقات 2019-05-06.

يمكنك تحديث الفهارس المسطحة إلى التنسيق الجديد بالخطوات التالية باستخدام إصدار 2017-11-11-Previewواجهة برمجة التطبيقات :

تنفيذ طلب GET لاسترداد الفهرس الخاص بك. إذا كان بالتنسيق الجديد بالفعل، فقد انتهيت.
ترجمة الفهرس من التنسيق المسطح إلى التنسيق الجديد. يجب عليك كتابة التعليمات البرمجية لهذه المهمة نظرا لعدم توفر نموذج التعليمات البرمجية في وقت كتابة هذا التقرير.
تنفيذ طلب PUT لتحديث الفهرس إلى التنسيق الجديد. تجنب تغيير أي تفاصيل أخرى للفهرس، مثل قابلية البحث/تصفية الحقول، لأن التغييرات التي تؤثر على التعبير الفعلي للفهرس الحالي غير مسموح بها من قبل واجهة برمجة تطبيقات تحديث الفهرس.