Keterampilan API Web Kustom dalam alur pengayaan Azure AI Search

  • Artikel

Keterampilan Kustom Web API memungkinkan Anda memperluas pengayaan AI dengan memanggil titik akhir Web API yang menyediakan operasi kustom. Mirip dengan keterampilan bawaan, keterampilanCustom Web API memiliki input dan output. Bergantung pada input, Web API Anda menerima muatan JavaScript Object Notation saat pengindeks berjalan, dan menghasilkan muatan JavaScript Object Notation sebagai respons, bersama dengan kode status keberhasilan. Respons diharapkan memiliki output yang ditentukan oleh keterampilan kustom Anda. Respons lain dianggap sebagai kesalahan dan tidak ada pengayaan yang dilakukan. Struktur payload JSON dijelaskan lebih lanjut dalam dokumen ini.

Keterampilan API Web Kustom juga digunakan dalam implementasi fitur Azure OpenAI On Your Data . Jika Azure OpenAI dikonfigurasi untuk akses berbasis peran dan Anda mendapatkan 403 Forbidden panggilan saat membuat indeks vektor, verifikasi bahwa Azure AI Search memiliki identitas yang ditetapkan sistem dan berjalan sebagai layanan tepercaya di Azure OpenAI.

Catatan

Pengindeks mencoba kembali dua kali untuk kode status HTTP standar tertentu yang dikembalikan dari API Web. Kode status HTTP ini adalah:

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

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Parameter keterampilan

Parameternya peka huruf besar/kecil.

Nama Parameter Deskripsi
uri URI API Web tempat payload JSON dikirim. Hanya skema URI https yang diperbolehkan.
authResourceId (Opsional) String yang jika diatur, menunjukkan bahwa keterampilan ini harus menggunakan identitas terkelola pada koneksi ke fungsi atau aplikasi yang menghosting kode. Properti ini mengambil ID aplikasi (klien) atau pendaftaran aplikasi di ID Microsoft Entra, dalam format yang didukung: api://<appId>. Nilai ini digunakan untuk mencakup token autentikasi yang diambil oleh pengindeks, dan dikirim bersama dengan permintaan API keterampilan Web kustom ke fungsi atau aplikasi. Mengatur properti ini mengharuskan layanan pencarian Anda dikonfigurasi untuk identitas terkelola dan aplikasi fungsi Azure Anda dikonfigurasi untuk masuk Microsoft Entra. Untuk menggunakan parameter ini, panggil API dengan api-version=2023-10-01-Preview.
httpMethod Metode yang digunakan saat mengirim payload. Metode yang diperbolehkan adalah PUT atau POST
httpHeaders Kumpulan pasangan kunci-nilai di mana kunci mewakili nama header dan nilai mewakili nilai header yang dikirim ke API Web Anda bersama dengan payload. Header berikut dilarang berada dalam koleksi ini: Accept, , Accept-Charset, Content-LengthAccept-Encoding, Content-Type, Cookie, Host, TE, , Upgrade, . Via
timeout (Opsional) Ketika ditentukan, menunjukkan batas waktu untuk klien http yang melakukan panggilan API. Interval ini harus diformat sebagai nilai “dayTimeDuration” XSD (subset terbatas dari nilai durasi ISO 8601). Misalnya, PT60S selama 60 detik. Jika tidak diatur, nilai default 30 detik akan dipilih. Batas waktu dapat diatur hingga maksimum 230 detik dan minimal 1 detik.
batchSize (Opsional) Menunjukkan berapa banyak "rekaman data" (lihat struktur payload JSON di bawah) dikirim per panggilan API. Jika tidak disetel, default 1000 dipilih. Kami menyarankan agar Anda menggunakan parameter ini untuk mencapai tradeoff yang sesuai antara throughput pengindeksan dan beban pada API Anda.
degreeOfParallelism (Opsional) Ketika ditentukan, menunjukkan jumlah panggilan yang dilakukan pengindeks secara paralel dengan titik akhir yang Anda sediakan. Anda dapat mengurangi nilai ini jika titik akhir Anda gagal di bawah tekanan, atau menaikkannya jika titik akhir Anda dapat menangani beban. Jika tidak diatur, nilai default 5 akan digunakan. Yang degreeOfParallelism dapat diatur ke maksimum 10 dan minimal 1.

Input keterampilan

Tidak ada input yang telah ditentukan sebelumnya untuk keterampilan ini. Input adalah bidang yang ada, atau simpul apa pun di pohon pengayaan yang ingin Anda teruskan ke keterampilan kustom Anda.

Output keterampilan

Tidak ada output yang telah ditentukan sebelumnya untuk keterampilan ini. Pastikan untuk menentukan pemetaan bidang output di pengindeks jika output keterampilan harus dikirim ke bidang dalam indeks pencarian.

Definisi sampel

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

Contoh input struktur JavaScript Object Notation

Struktur JSON ini mewakili payload yang dikirim ke API Web Anda. Ini selalu mengikuti batasan ini:

  • Entitas tingkat atas dipanggil values dan merupakan array objek. Jumlah objek tersebut batchSizepaling banyak .

  • Setiap objek dalam values array memiliki:

    • Properti recordId yang merupakan untai (karakter) unik, digunakan untuk mengidentifikasi rekaman tersebut.

    • Properti data yang merupakan objek JSON. Bidang data properti sesuai dengan "nama" yang ditentukan di bagian inputs definisi keterampilan. Nilai bidang tersebut berasal dari bidang tersebut source (yang bisa berasal dari bidang dalam dokumen, atau berpotensi dari keterampilan lain).

{
    "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": []
           }
      }
    ]
}

Contoh struktur JSON output

"Output" sesuai dengan respons yang dikembalikan dari Web API Anda. API Web hanya boleh mengembalikan payload JSON (diverifikasi Content-Type dengan melihat header respons) dan harus memenuhi batasan berikut:

  • Harus ada entitas tingkat atas yang disebut values, yang harus menjadi array objek.

  • Jumlah objek dalam larik harus sama dengan jumlah objek yang dikirim ke Web API.

  • Setiap objek harus memiliki:

    • Properti recordId .

    • Sebuah properti data, yang merupakan objek di mana bidang adalah pengayaan yang cocok dengan "nama" di output dan yang nilainya dianggap sebagai pengayaan.

    • Properti errors , array yang mencantumkan kesalahan apa pun yang ditemui yang ditambahkan ke riwayat eksekusi pengindeks. Properti ini diperlukan, tetapi dapat memiliki nilai null.

    • Properti warnings , array yang mencantumkan peringatan apa pun yang ditemui yang ditambahkan ke riwayat eksekusi pengindeks. Properti ini diperlukan, tetapi dapat memiliki nilai null.

  • Pengurutan objek dalam values permintaan atau respons tidak penting. Namun, recordId digunakan untuk korelasi sehingga rekaman apa pun dalam respons yang recordIdberisi , yang bukan bagian dari permintaan asli ke API Web dibuang.

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

Kasus kesalahan

Selain Web API Anda yang tidak tersedia, atau mengirimkan kode status yang tidak berhasil berikut ini dianggap sebagai kasus yang salah:

  • Jika API Web mengembalikan kode status keberhasilan tetapi respons menunjukkan bahwa itu tidak application/json maka respons dianggap tidak valid dan tidak ada pengayaan yang dilakukan.

  • Jika ada rekaman yang tidak valid (misalnya, recordId hilang atau diduplikasi) dalam array respons values , tidak ada pengayaan yang dilakukan untuk rekaman yang tidak valid. Penting untuk mematuhi kontrak keterampilan API Web saat mengembangkan keterampilan kustom. Anda dapat merujuk ke contoh ini yang disediakan di repositori Power Skill yang mengikuti kontrak yang diharapkan.

Untuk kasus ketika API Web tidak tersedia atau mengembalikan kesalahan HTTP, kesalahan yang mudah diingat dengan detail yang tersedia tentang kesalahan HTTP ditambahkan ke riwayat eksekusi pengindeks.

Lihat juga