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

  • مقالة

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

يتم أيضا استخدام مهارة واجهة برمجة تطبيقات الويب المخصصة في تنفيذ ميزة Azure OpenAI على بياناتك. إذا تم تكوين Azure OpenAI للوصول المستند إلى الدور والحصول على 403 Forbidden مكالمات عند إنشاء فهرس المتجهات، فتحقق من أن Azure الذكاء الاصطناعي Search لديه هوية معينة للنظام ويعمل كخدمة موثوق بها على Azure OpenAI.

إشعار

يعيد المفهرس المحاولة مرتين لبعض رموز حالة HTTP القياسية التي تم إرجاعها من واجهة برمجة تطبيقات الويب. التعليمات البرمجية لحالة HTTP هي:

  • 502 Bad Gateway
  • 503 Service Unavailable
  • 429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkill

معلمات المهارة

المعلمات حساسة لحالة الأحرف.

اسم المعلمة ‏‏الوصف
uri URI لواجهة برمجة تطبيقات الويب التي يتم إرسال حمولة JSON إليها. يسمح فقط بنظام URI https.
authResourceId (اختياري) تشير السلسلة التي إذا تم تعيينها إلى أن هذه المهارة يجب أن تستخدم هوية مدارة على الاتصال بالوظيفة أو التطبيق الذي يستضيف التعليمات البرمجية. تأخذ هذه الخاصية معرف تطبيق (عميل) أو تسجيل تطبيق في معرف Microsoft Entra، بتنسيق مدعوم: api://<appId>. يتم استخدام هذه القيمة لتحديد نطاق رمز المصادقة المميز الذي قام المفهرس باسترداده، ويتم إرسالها جنبا إلى جنب مع طلب واجهة برمجة تطبيقات مهارة الويب المخصصة إلى الوظيفة أو التطبيق. يتطلب تعيين هذه الخاصية تكوين خدمة البحث للهوية المدارة وتكوين تطبيق وظائف Azure لتسجيل الدخول إلى Microsoft Entra. لاستخدام هذه المعلمة، قم باستدعاء واجهة برمجة التطبيقات باستخدام api-version=2023-10-01-Preview.
httpMethod الأسلوب الذي يجب استخدامه أثناء إرسال الحمولة. الأساليب المسموح بها هي PUT أو POST
httpHeaders مجموعة من أزواج قيم المفاتيح حيث تمثل المفاتيح أسماء الرؤوس والقيم تمثل قيم الرأس التي يتم إرسالها إلى واجهة برمجة تطبيقات الويب الخاصة بك جنبا إلى جنب مع الحمولة. يحظر وجود العناوين التالية في هذه المجموعة: Accept، ، Accept-EncodingAccept-Charset، Content-Length، Content-Type، CookieHost، ، TE، . UpgradeVia
timeout (اختياري) عند تحديده، يشير إلى المهلة لعميل http الذي يقوم باستدعاء واجهة برمجة التطبيقات للنظام. يجب تنسيقه كقيمة XSD "dayTimeDuration" (مجموعة فرعية مقيدة لقيمة مدة ISO 8601). على سبيل المثال، PT60S لمدة 60 ثانية. إذا لم يتم الضبط، يتم اختيار قيمة افتراضية تبلغ 30 ثانية. يمكن ضبط المهلة على 230 ثانية كحد أقصى وثانية واحدة بحد أدنى.
batchSize (اختياري) يشير إلى عدد "سجلات البيانات" (راجع بنية حمولة JSON أدناه) التي يتم إرسالها لكل استدعاء API. إذا لم يتم تعيينه، يتم اختيار الافتراضي 1000. نوصي باستخدام هذه المعلمة لتحقيق مقايضة مناسبة بين معدل نقل الفهرسة والتحميل على واجهة برمجة التطبيقات الخاصة بك.
degreeOfParallelism (اختياري) عند تحديده، يشير إلى عدد المكالمات التي يقوم المفهرس بإجراءها بالتوازي مع نقطة النهاية التي توفرها. يمكنك تقليل هذه القيمة إذا فشلت نقطة النهاية تحت الضغط، أو رفعها إذا كانت نقطة النهاية الخاصة بك قادرة على التعامل مع الحمل. إذا لم يتم الضبط، يتم استخدام قيمة افتراضية تبلغ 5. degreeOfParallelism يمكن تعيين إلى 10 كحد أقصى و1 كحد أدنى.

إدخالات المهارات

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

إخراجات المهارات

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

تعريف العينة

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "batchSize": 4,
  "context": "/document",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    },
    {
      "name": "language",
      "source": "/document/languageCode"
    },
    {
      "name": "phraseList",
      "source": "/document/keyphrases"
    }
  ],
  "outputs": [
    {
      "name": "hitPositions"
    }
  ]
}

عينة بنية JSON للإدخال

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

  • يتم استدعاء values كيان المستوى الأعلى وهو صفيف من الكائنات. عدد هذه الكائنات هو على الأكثر batchSize.

  • يحتوي كل كائن في الصفيف على values :

    • recordId خاصية هي سلسلة فريدة، تستخدم لتعريف هذا السجل.

    • data خاصية هي كائن JSON. تتوافق حقول الخاصية data مع "الأسماء" المحددة في inputs قسم تعريف المهارة. تكون قيم هذه الحقول من source تلك الحقول (التي يمكن أن تكون من حقل في المستند، أو ربما من مهارة أخرى).

{
    "values": [
      {
        "recordId": "0",
        "data":
           {
             "text": "Este es un contrato en Inglés",
             "language": "es",
             "phraseList": ["Este", "Inglés"]
           }
      },
      {
        "recordId": "1",
        "data":
           {
             "text": "Hello world",
             "language": "en",
             "phraseList": ["Hi"]
           }
      },
      {
        "recordId": "2",
        "data":
           {
             "text": "Hello world, Hi world",
             "language": "en",
             "phraseList": ["world"]
           }
      },
      {
        "recordId": "3",
        "data":
           {
             "text": "Test",
             "language": "es",
             "phraseList": []
           }
      }
    ]
}

عينة بنية JSON للإخراج

يتوافق "الإخراج" مع الاستجابة التي تم إرجاعها من واجهة برمجة تطبيقات الويب الخاصة بك. يجب أن ترجع واجهة برمجة تطبيقات الويب حمولة JSON فقط (تم التحقق منها من خلال النظر إلى Content-Type عنوان الاستجابة) ويجب أن تفي بالقيود التالية:

  • يجب أن يكون هناك كيان من المستوى الأعلى يسمى values، والذي يجب أن يكون صفيفا من الكائنات.

  • يجب أن يكون عدد الكائنات في الصفيف هو نفسه عدد الكائنات المرسلة إلى واجهة برمجة تطبيقات الويب.

  • يجب أن يحتوي كل كائن على:

    • خاصية recordId .

    • data خاصية ، وهي كائن حيث تكون الحقول إثراء مطابقة "الأسماء" في output والتي تعتبر قيمتها الإثراء.

    • خاصية errors ، صفيف يسرد أي أخطاء تمت مواجهتها تتم إضافتها إلى محفوظات تنفيذ المفهرس. هذه الخاصية مطلوبة، ولكن يمكن أن يكون لها null قيمة.

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

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

{
    "values": [
        {
            "recordId": "3",
            "data": {
            },
            "errors": [
              {
                "message" : "'phraseList' should not be null or empty"
              }
            ],
            "warnings": null
        },
        {
            "recordId": "2",
            "data": {
                "hitPositions": [6, 16]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "0",
            "data": {
                "hitPositions": [0, 23]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "1",
            "data": {
                "hitPositions": []
            },
            "errors": null,
            "warnings": [
              {
                "message": "No occurrences of 'Hi' were found in the input text"
              }
            ]
        },
    ]
}

حالات الخطأ

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

  • إذا قامت واجهة برمجة تطبيقات الويب بإرجاع رمز حالة نجاح ولكن الاستجابة تشير إلى أنها ليست application/json كذلك، فإن الاستجابة تعتبر غير صالحة ولا يتم تنفيذ أي عمليات إثراء.

  • إذا كانت هناك سجلات غير صالحة (على سبيل المثال، recordId مفقودة أو مكررة) في صفيف الاستجابة values ، فلن يتم إجراء أي إثراء للسجلات غير الصالحة. من المهم الالتزام بعقد مهارة واجهة برمجة تطبيقات الويب عند تطوير مهارات مخصصة. يمكنك الرجوع إلى هذا المثال المقدم في مستودع Power Skill الذي يتبع العقد المتوقع.

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

(راجع أيضًا )