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

ملاحظة

البحث باستخدام الذكاء الاصطناعي في Azure متوفر من خلال بوابة Azure، وواجهات برمجة التطبيقات REST، وAzure SDKs. كما يدعم طبقة المعرفة المدارة Foundry IQ، وهي طبقة المعرفة المدارة التي تحول محتوى المؤسسات إلى قواعد معرفية قابلة لإعادة الاستخدام وواثقة للأذونات للوكلاء في بوابة Microsoft Foundry.

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

إليكم أحدث إصدارات واجهات برمجة تطبيقات REST:

العمليات المستهدفة واجهة برمجة تطبيقات REST الحالة
مستوى البيانات 2026-04-01 مستقرة
مستوى البيانات 2026-08-01-preview معاينة
طائرة التحكم 2025-05-01 مستقرة
طائرة التحكم 2026-03-01-preview معاينة

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

نوصي بترقية إصدارات API على التوالي، مع العمل على كل إصدار حتى تصل إلى الأحدث.

2023-07-01-preview كان أول واجهة برمجة تطبيقات REST لدعم المتجهات. لا تستخدم هذه النسخة من واجهة برمجة التطبيقات (API). الآن تم تعقيم التطبيق ويجب عليك الانتقال فورا إلى واجهات برمجة التطبيقات المستقرة أو الجديدة لمعاينة REST.

ملاحظة

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

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

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

  • كودك يشير إلى نسخة API متقاعدة أو غير مدعومة ويخضع لتغيير أو أكثر من التغييرات القاطعة.

  • يفشل كودك عندما يتم إرجاع خصائص غير معروفة في استجابة API. كأفضل ممارسة، يجب أن يتجاهل تطبيقك خصائص لا يفهمها.

  • الكود الخاص بك يبقي طلبات API ويحاول إعادة إرسالها إلى النسخة الجديدة من API. على سبيل المثال، قد يحدث هذا إذا استمر تطبيقك في استمرارية رموز الاستمرار التي تم إرجاعها من واجهة بحث API (لمزيد من المعلومات، ابحث في @search.nextPageParametersمرجع واجهة برمجة تطبيقات البحث).

كيفية الترقية

  1. إذا كنت تقوم بترقية نسخة مستوى البيانات، راجع ما تم إصداره في نسخة API الجديدة.

  2. قم بتحديث api-version المعامل المحدد في رأس الطلب إلى إصدار أحدث.

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

    إذا كنت تستخدم Azure SDK، فإن كل حزمة تستهدف إصدارا محددا من واجهة برمجة تطبيقات REST. لتحديد أي إصدار API من REST يدعمه الحزمة الخاصة بك، راجع سجل التغييرات الخاص به. تحديث إلى أحدث إصدار للحزمة للوصول إلى أحدث الميزات وتحسينات واجهة برمجة التطبيقات (API).

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

تغييرات حاسمة

تنطبق التغييرات العاجلة التالية على عمليات البيانات.

تغييرات كبرية لاسترجاع الوكيل

2026-04-01 هي أول نسخة REST API مستقرة للاسترجاع الوكالتي. يقدم التغييرات التالية في التقسيم من 2025-11-01-preview:

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

  • يتم استبدال شكل طلب الاسترجاع: messages ب intents، ويتم إعادة تسمية أو إزالة عدة معلمات.

  • فلاتر الأذونات على مستوى المستندات لمصادر المعرفة في Blob وOneLake غير مدعوم.

للاطلاع على القائمة الكاملة لتغييرات مستوى الخاصية وخطوات الترحيل، انظر ترحيل رمز الاسترجاع الوكيلي الخاص بك.

تغييرات كثيرة لوكلاء المعرفة

تم إدخال وكلاء المعرفة في 2025-05-01-preview. في 2025-08-01-preview، targetIndexes تم استبداله بكائن مصدر معرفة جديد، وتم defaultMaxDocsForReranker استبداله بواجهات برمجة تطبيقات أخرى. تم إدخال المزيد من التغييرات العاجلة في 2025-11-01-preview.

للاطلاع على القائمة الكاملة لتغييرات مستوى الخاصية وخطوات الترحيل، انظر ترحيل رمز الاسترجاع الوكيلي الخاص بك.

تغييرات كسر لكود العميل الذي يقرأ معلومات الاتصال

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

  • لم تعد GET SkillssetوGET IndexوGET Indexer تعيد المفاتيح أو خصائص الاتصال في الاستجابة. هذا تغيير كبير إذا كان لديك كود لاحق يقرأ مفاتيح أو اتصالات (بيانات حساسة) من استجابة GET.

  • إذا كنت بحاجة لاسترجاع مفاتيح API للمسؤول أو الاستعلام لخدمة البحث الخاصة بك، استخدم واجهات برمجة تطبيقات REST لإدارة البحث.

  • إذا كنت بحاجة لاسترجاع سلاسل اتصال لمورد Azure آخر مثل تخزين Azure أو Azure Cosmos DB، استخدم واجهات برمجة التطبيقات لذلك المورد والإرشادات المنشورة للحصول على المعلومات.

تغييرات كبرية لتصنيف الدلالة

أصبح التصنيف الدلالي متاحا بشكل عام في 2023-11-01. هذه هي التغييرات الحاسمة مقارنة بالإصدارات السابقة:

  • في جميع النسخ التي تلت 2020-06-01-preview، تحل : semanticConfigurationsearchFields كآلية لتحديد الحقول التي يجب استخدامها لترتيب اللغة الثانية.

  • بالنسبة لجميع إصدارات واجهة برمجة التطبيقات (API)، جعلت التحديثات في 14 يوليو 2023 على النماذج الدلالية المستضافة Microsoft غير معتمدة من لغة التصنيف الدلالي، مما أدى فعليا إلى إلغاء تشغيل خاصية queryLanguage. لا يوجد "تغيير كسر للكسر" في الكود، لكن الخاصية تتجاهل.

راجع الترحيل من نسخة المعاينة لنقل كودك لاستخدام semanticConfiguration.

ترقيات مستوى البيانات

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

الترقية إلى معاينة 2026-08-01

2026-08-01-preview يضيف عناصر تحكم استرداد عاملية جديدة وتحسينات مصدر المعرفة وفصل الصفحات للمؤشر لعمليات القائمة.

قبل الترقية، تحقق مما إذا كانت أي من التغييرات التالية 2026-08-01-preview تنطبق على الكود الخاص بك:

  • تتضمن تغييرات كسر الاسترداد الوكيل كائنات متداخلة model في سجلات النشاط، resultsProcessing واستبدال inclusionMode أدوات الخادم في مصدر معارف MCP، ومصادقة تطبيق Microsoft Entra المملوكة للعميل لمصادر معارف Work IQ. للحصول على إرشادات الترحيل خطوة بخطوة، راجع ترحيل التعليمات البرمجية للاسترداد الوكيل.

  • تستبدل $topعمليات السرد لمصادر البيانات والمفهرسات والفهارس ومجموعات المهارات ومصادر المعرفة و $skipو بقسمة $count المؤشر باستخدام pageSizeو searchو @odata.nextLink. لمزيد من المعلومات حول آلية الترحيل الجديدة، راجع Page through البحث باستخدام الذكاء الاصطناعي في Azure list results (preview).

بالنسبة لجميع واجهات برمجة التطبيقات الأخرى الموجودة، لا توجد تغييرات في السلوك. يمكنك تبديل نسخة API الجديدة، ويعمل كودك كما كان من قبل.

الترقية إلى 2026-05-01-preview

يضيف 2026-05-01-preview أنواع مصادر معرفة جديدة، ومعلمات جديدة على إجراء الاسترجاع، وأنواع محتوى مؤهرة SharePoint وخيارات ACL، وقدرات أخرى.

لا توجد تغييرات في كسر السلك من 2025-11-01-preview. ومع ذلك، إذا استخدمت Python أو مجموعة تطوير جافا سكريبت للاسترجاع الوكيلي، يتم إعادة تسمية عميل الاسترجاع إلى KnowledgeBaseRetrievalClient، ويتم استبدال retrieveKnowledge(...) ب retrieve(...). للحصول على إرشادات ترحيل SDK، راجع ترحيل كود الاسترجاع الوكيلي الخاص بك.

بالنسبة لجميع واجهات برمجة التطبيقات الأخرى الموجودة، لا توجد تغييرات في السلوك. يمكنك تبديل نسخة API الجديدة، ويعمل كودك كما كان من قبل.

الترقية إلى 2026-04-01

2026-04-01 هو أحدث إصدار مستقر لواجهة برمجة التطبيقات REST. يعزز الاسترجاع الوكيلي، واختيار مصادر المعرفة، وعدة مهارات وميزات إلى التوفر العام.

قبل الترقية، تحقق مما إذا كانت أي من التغييرات التالية 2026-04-01 تنطبق على الكود الخاص بك:

  • تمت إزالة ست خصائص من تعريف مهارة موجه الذكاء الاصطناعي المولد: httpMethod، timeout، batchSize، degreeOfParallelismhttpHeadersو authResourceId. قم بإزالة هذه الخصائص قبل الترقية. التعريفات التي لا تزال تتضمن هذه الخصائص ترد خطأ 400 Bad Request .

  • الاسترجاع الوكيل يتطلب الآن موافقة الفوترة الخاصة به. إذا كان لديك semanticSearch=standardحاليا ، يجب أن تحدد knowledgeRetrieval=standard صراحة قبل الترقية. لمزيد من المعلومات، راجع تمكين أو تعطيل الفوترة الوكيلية.

  • إذا كان كود الاسترجاع الوكيلي يستهدف ، 2025-11-01-preview2026-04-01 فإنه يزيل عدة قدرات معاينة ويجعل الاسترجاع موحدا حول إدخال النية، والمخرجات الاستخراجية، والاستدلال البسيط. لمزيد من المعلومات، راجع ترحيل رمز الاسترجاع الوكيلي الخاص بك.

بالنسبة لجميع واجهات برمجة التطبيقات الأخرى الموجودة، لا توجد تغييرات في السلوك. يمكنك تبديل نسخة API الجديدة، ويعمل كودك كما كان من قبل.

الترقية إلى معاينة 2025-11-01

2025-11-01-previewيقدم التغييرات القاطعة التالية في الاسترجاع الوكيلي كما تم تنفيذه في :2025-08-01-preview

  • يستبدل agents ب knowledgebases. انتقلت عدة خصائص متعلقة بمصادر المعرفة من تعريف قاعدة المعرفة إلى إجراء الاسترجاع.

  • يتم إعادة هيكلة خصائص مصادر المعرفة، حيث يتم تنفيذ كائن جديد ingestionParameters لمصادر المعرفة التي تولد خط أنابيب للفهرس.

للاطلاع على القائمة الكاملة لتغييرات مستوى الخاصية وخطوات الترحيل، انظر ترحيل رمز الاسترجاع الوكيلي الخاص بك.

بالنسبة لجميع واجهات برمجة التطبيقات الأخرى الموجودة، لا توجد تغييرات في السلوك. يمكنك تبديل نسخة API الجديدة، ويعمل كودك كما كان من قبل.

الترقية إلى 2025-09-01

2025-09-01 هو إصدار REST API مستقر يضيف توافرا عاما لفهرس OneLake، ومهارة تخطيط المستندات، وواجهات برمجة التطبيقات الأخرى.

لا توجد تغييرات معطلة إذا كنت تقوم بالترقية من 2024-07-01 أي ميزات معاينة دون استخدام. لاستخدام الإصدار الجديد المستقر، غير نسخة API واختبر الكود الخاص بك.

الترقية إلى معاينة 2025-08-01

2025-08-01-preview يقدم التغييرات القاضية التالية على وكلاء المعرفة الذين تم إنشاؤهم باستخدام 2025-05-01-preview:

  • يستبدل targetIndexes ب knowledgeSources.
  • يتم إزالته defaultMaxDocsForReranker دون استبدال.

بخلاف ذلك، لا توجد تغييرات سلوكية في واجهات برمجة التطبيقات الحالية. يمكنك تبديل نسخة API الجديدة، ويعمل كودك كما كان من قبل.

الترقية إلى 2025-05-01-Preview

2025-05-01-preview يوفر ميزات جديدة، لكن لا توجد تغييرات سلوكية في واجهات برمجة التطبيقات الحالية. يمكنك تبديل نسخة API الجديدة، ويعمل كودك كما كان من قبل.

الترقية إلى معاينة 2025-03-01

2025-03-01-preview يوفر ميزات جديدة، لكن لا توجد تغييرات سلوكية في واجهات برمجة التطبيقات الحالية. يمكنك تبديل نسخة API الجديدة، ويعمل كودك كما كان من قبل.

الترقية إلى معاينة 2024-11-01

2024-11-01-preview إعادة كتابة الاستعلام، مهارة تخطيط المستند، الفوترة بدون مفتاح لمعالجة المهارات، وضع تحليل ماركداون، وخيارات إعادة التنسيق للمتجهات المضغوطة.

إذا كنت تقوم بالترقية من 2024-09-01-preview، يمكنك تبديل نسخة API الجديدة، ويعمل كودك كما كان من قبل.

ومع ذلك، تقدم النسخة الجديدة تغييرات في النحو إلى vectorSearch.compressions:

  • يستبدل rerankWithOriginalVectors ب enableRescoring
  • ينتقل defaultOversampling إلى كائن خاصية جديد rescoringOptions

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

الترقية إلى 2024-09-01-Preview

2024-09-01-preview يضيف ضغط تعلم التمثيل (MRL) لنماذج تضمين النص 3، والتصفية المستهدفة بالمتجهات للاستعلامات الهجينة، وتفاصيل النقاط الفرعية المتجهية لتصحيح الأخطاء، وتقسيم الرموز لمهارة تقسيم النص.

إذا كنت تقوم بالترقية من 2024-05-01-preview، يمكنك تبديل نسخة API الجديدة، ويعمل كودك كما كان من قبل.

الترقية إلى 2024-07-01

2024-07-01 هو إصدار عام. الميزات السابقة للمعاينة متاحة الآن بشكل عام: تقسيم متكامل وتوجيه (مهارة تقسيم النص، مهارة AzureOpenAImbedding)، موجه استعلام يعتمد على AzureOpenAImbedding، ضغط المتجهات (التكميم العددي، الكمية الثنائية، الخاصية المخزنة، أنواع البيانات الضيقة).

لا توجد تغييرات كسر إذا قمت بالترقية من 2024-05-01-preview إلى مستقر. لاستخدام الإصدار الجديد المستقر، غير نسخة API واختبر الكود الخاص بك.

هناك تغييرات كبيرة إذا قمت بالترقية مباشرة من 2023-11-01. اتبع الخطوات الموضحة لكل معاينة جديدة للانتقال من 2023-11-01 إلى 2024-07-01.

الترقية إلى 2024-05-01-preview

يضيف 2024-05-01-preview مؤشرا ل Microsoft OneLake، والمتجهات الثنائية، والمزيد من نماذج التضمين.

إذا كنت تقوم بالترقية من 2024-03-01-preview، فإن مهارة AzureOpenAImbedding الآن تتطلب خاصية اسم النموذج والأبعاد.

  1. ابحث في قاعدة الشيفرة الخاصة بك عن المراجع AzureOpenAIEmbedding .

  2. ضبطه modelName على "text-embedding-ada-002" وضبطه dimensions على "1536".

الترقية إلى معاينة 2024-03-01

2024-03-01-preview يضيف أنواع بيانات ضيقة، وتكميم قياسي، وخيارات تخزين متجه.

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

  1. ابحث في قاعدة الكود الخاصة بك عن vectorFilterMode مراجع.

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

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

2023-11-01 هو إصدار عام. ميزات المعاينة السابقة متاحة الآن بشكل عام: دعم التصنيف الدلالي والمتجه.

لا توجد تغييرات كسر من 2023-10-01-preview، لكن هناك تغييرات كسر متعددة من 2023-07-01-preview إلى 2023-11-01. لمزيد من المعلومات، راجع الترقية من 2023-07-01-preview.

لاستخدام الإصدار الجديد المستقر، غير نسخة API واختبر الكود الخاص بك.

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

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

إذا كنت تقوم بالترقية من النسخة السابقة، فالقسم التالي يحتوي على الخطوات.

الترقية من 2023-07-01-preview

لا تستخدم هذه النسخة من واجهة برمجة التطبيقات. ينفذ بناء جملة استعلام متجه غير متوافق مع أي إصدار API أحدث.

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

ترقية البوابة لفهارس المتجهات

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

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

لا يوجد ترحيل بوابة لترقية بناء جملة استعلام المتجه. راجع تحديثات الكود لتغييرات بناء جملة الاستعلام.

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

ترقية الكود لفهارس المتجهات والاستعلامات

تم تقديم دعم البحث المتجه في برنامج إنشاء أو تحديث فهرس (2023-07-01-preview).

الترقية من 2023-07-01-preview إلى أي إصدار مستقر أو معاينة أحدث تتطلب ما يلي:

  • إعادة تسمية وإعادة هيكلة تكوين المتجهات في الفهرس
  • إعادة كتابة استعلامات المتجهات الخاصة بك

استخدم التعليمات في هذا القسم لنقل حقول المتجهات، والتكوين، والاستعلامات من 2023-07-01-preview.

  1. اتصل ب Get Index لاسترجاع التعريف الحالي.

  2. عدل إعدادات البحث المتجه. 2023-11-01 وتقدم الإصدارات اللاحقة مفهوم ملفات تعريف المتجهات التي تجمع التكوينات المتعلقة بالمتجهات تحت اسم واحد. الإصدارات الأحدث تعيد أيضا تسميتها algorithmConfigurations إلى algorithms.

    • أعد تسميته algorithmConfigurations إلى algorithms. هذه مجرد إعادة تسمية للمصفوفة. المحتوى متوافق مع الإصدارات السابقة. هذا يعني أنه يمكن استخدام معلمات تكوين HNSW الحالية لديك.

    • أضف profiles، مما يعطي اسما وتكوين خوارزمية لكل واحد.

    قبل الهجرة (معاينة 2023-07-01):

      "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"
      }
    ]
  }

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

    قبل (2023-07-01-معاينة):

      {
      "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"
  }

  4. اتصل بإنشاء أو تحديث فهرس لنشر التغييرات.

  5. عدل Search POST لتغيير صياغة الاستعلام. يتيح هذا التغيير في واجهة برمجة التطبيقات دعم أنواع استعلامات المتجهات متعددة الأشكال.

    • أعد تسميته vectors إلى vectorQueries.
    • لكل استعلام متجه، أضف kind، وضبطه على vector.
    • لكل استعلام متجه، أعد تسميته value إلى vector.
    • اختياريا، أضف vectorFilterMode إذا كنت تستخدم تعبيرات المرشح. الافتراضي هو التصفية المبدئية للفهارس التي يتم إنشاؤها بعد 2023-10-01. الفهارس التي تم إنشاؤها قبل ذلك التاريخ تدعم فقط ما بعد التصفية، بغض النظر عن كيفية ضبط وضع الفلتر.

    قبل (2023-07-01-معاينة):

    {
    "search": "*", //Required by the API but ignored for ranking in vector-only queries
    "vectors": [
      {
        "value": [
            0.103,
            0.0712,
            0.0852,
            0.1547,
            0.1183
        ],
        "fields": "contentVector",
        "k": 5
      }
    ],
    "select": "title, content, category"
}

    بعد (2023-11-01):

    {
  "search": "*", //Required by the API but ignored for ranking in vector-only queries
  "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 إصدار API مستقر أو إصدارات أحدث من المعاينة.

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

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

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

كسر التغيير

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

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

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

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

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

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

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

تغييرات حاسمة

الكود المكتوب مقابل نسخة API سابقة ينكسر لاحقا 2019-05-06 إذا احتوى على الوظائف التالية:

  1. اكتب خاصية Azure Cosmos DB. بالنسبة للفهرسين الذين يستهدفون مصدر بيانات Azure Cosmos DB لواجهة برمجة التطبيقات NoSQL، غيروا "type": "documentdb" إلى "type": "cosmosdb".

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

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

  4. مهارة التعرف على الكيان المسمى تم تقاعدها. إذا استدعيت مهارة التعرف على الكيان في الكود الخاص بك، تفشل المكالمة. وظيفة الاستبدال هي مهارة التعرف على الكيانات (V3). اتبع التوصيات في المهارات المهجورة للانتقال إلى مهارة مدعومة.

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

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

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

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

لمزيد من المعلومات، انظر حدود الخدمة ل البحث باستخدام الذكاء الاصطناعي في Azure.

كيفية ترقية هيكل قديم من نوع المجمع

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

{
  "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-PreviewAPI . في الصيغة الجديدة، يحتوي كل حقل مركب على مجموعة حقول حيث تعرف حقول فرعية. في إصدار API 2019-05-06، يستخدم هذا التنسيق الجديد حصريا ومحاولة إنشاء أو تحديث فهرس باستخدام الصيغة القديمة ستفشل. إذا كنت قد أنشأت فهارس باستخدام الصيغة القديمة، ستحتاج إلى استخدام نسخة 2017-11-11-Preview API لتحديثها إلى الصيغة الجديدة قبل أن يمكن إدارتها باستخدام إصدار API 2019-05-06.

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

  1. قم بإجراء طلب GET لاسترجاع فهرسك. إذا كان بالفعل بالصيغة الجديدة، فأنت قد انتهيت.

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

  3. قم بإجراء طلب PUT لتحديث الفهرس إلى التنسيق الجديد. تجنب تغيير أي تفاصيل أخرى للفهرس، مثل قابلية البحث/تصفية الحقول، لأن التغييرات التي تؤثر على التعبير الفيزيائي للفهرس الحالي غير مسموح بها من قبل واجهة تحديث فهرس.

ملاحظة

لا يمكن إدارة الفهارس التي تم إنشاؤها بالصيغة "المسطحة" القديمة من بوابة Azure. قم بترقية فهارسك من التمثيل "المسطح" إلى تمثيل "الشجرة" في أقرب وقت يناسبك.

ترقيات طائرة التحكم

ينطبق على:2014-07-31-Preview، 2015-02-28، و 2015-08-19

listQueryKeys طلب GET في إصدارات واجهة برمجة تطبيقات إدارة البحث القديمة أصبح الآن مهجورا. نوصي بالانتقال إلى أحدث إصدار API لمستوى التحكم المستقر لاستخدام listQueryKeys طلب POST.

  1. في الكود الحالي، غير المعامل api-version إلى أحدث إصدار (2025-05-01).

  2. أعد صياغة الطلب من GET إلى POST:

    POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/listQueryKeys?api-version=2025-05-01
Authorization: Bearer {{token}}

  3. إذا كنت تستخدم Azure SDK، ينصح بالترقية إلى أحدث إصدار.

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

راجع وثائق مرجعية API الخاصة بالبحث عن REST. إذا واجهت مشاكل، اطلب منا المساعدة في Stack Overflow أو تواصل مع الدعم.

مرجع API REST لخدمة البحث

  • Last updated on