Keterampilan API Web Kustom dalam alur pengayaan Pencarian Azure AI

Gunakan keterampilan API Web Kustom untuk memperluas pengayaan AI dengan memanggil titik akhir API Web yang menyediakan operasi kustom. Seperti keterampilan bawaan, keterampilan API Web Kustom memiliki input dan output. Bergantung pada input, API Web Anda menerima payload JSON saat pengindeks berjalan, dan mengembalikan payload JSON sebagai respons, bersama dengan kode status keberhasilan. Respons harus menyertakan output yang ditentukan oleh keterampilan kustom Anda. Respons lain dianggap sebagai kesalahan dan tidak ada pengayaan yang dilakukan. Struktur payload JSON dijelaskan nanti 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 kesalahan saat membuat indeks vektor, verifikasi bahwa Pencarian Azure AI memiliki identitas yang ditetapkan sistem dan berjalan sebagai layanan tepercaya di Azure OpenAI.

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Parameter keterampilan

Parameter peka huruf besar/kecil.

authResourceId Memahami nilai

Saat keterampilan API Web Kustom menggunakan autentikasi identitas terkelola, Pencarian Azure AI mendapatkan token akses Microsoft Entra dan mengirimkannya ke titik akhir keterampilan kustom. Properti authResourceId menentukan pengidentifikasi sumber daya, juga dikenal sebagai audiens atau URI ID Aplikasi, yang tokennya diminta. Nilai harus sesuai dengan apa yang diharapkan aplikasi target selama validasi token. Jika tidak, autentikasi gagal dengan 401 Unauthorized respons.

Nilai authResourceId mengidentifikasi aplikasi yang menghosting keterampilan kustom Anda. Ini bukan URL layanan pencarian atau pengindeks Anda.

Tabel berikut ini memperlihatkan format umum:

Properti menerima format dengan dan tanpa akhiran .default cakupan. Gunakan api://<appId> untuk mencocokkan URI ID Aplikasi secara langsung. Jika Anda menyertakan .default akhiran, seperti api://<appId>/.default, klaim token aud akses berisi URI ID Aplikasi dasar tanpa akhiran.

Untuk langkah-langkah mengonfigurasi autentikasi Microsoft Entra untuk Fungsi Azure dan mengatur authResourceId, lihat Menggunakan identitas terkelola layanan pencarian untuk menyambungkan ke aplikasi fungsi Azure.

Contoh: Fungsi Azure dilindungi oleh Microsoft Entra ID

Dalam contoh ini, Pencarian Azure AI memperoleh token akses untuk audiens yang ditentukan oleh authResourceId dan menyertakan token saat memanggil titik akhir keterampilan kustom.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "uri": "https://contoso-function.azurewebsites.net/api/enrich",
  "authResourceId": "api://contoso-customskill"
}

Masukan keterampilan

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

Keluaran Keterampilan

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

Contoh definisi

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

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "uri": "https://contoso.example.org/api?code=<redacted>",
  "httpMethod": "POST",
  "name": "myCustomSkill",
  "httpHeaders": {
    "Authorization": "<redacted>",
    "Ocp-Apim-Subscription-Key": "<redacted>"
  }
}

{
  "uri": "<unchanged>",
  "httpHeaders": {
    "Authorization": "<unchanged>",
    "Ocp-Apim-Subscription-Key": "<unchanged>"
  }
}

Contoh input struktur JavaScript Object Notation

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

• Entitas tingkat atas dipanggil values dan merupakan array objek. Jumlah objek ini paling banyak batchSize.

• Setiap objek dalam values array memiliki:

  • Properti recordId yang merupakan string 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 API Web Anda tidak tersedia atau mengirim kode status yang tidak berhasil, pertimbangkan kasus berikut sebagai kesalahan:

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

• Jika array respons values berisi rekaman yang tidak valid (misalnya, hilang atau diduplikasi recordId), rekaman yang tidak valid tidak diperkaya. Saat mengembangkan keterampilan kustom, patuhi kontrak keterampilan API Web. 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, riwayat eksekusi pengindeks menyertakan kesalahan yang mudah diingat dengan detail yang tersedia tentang kesalahan HTTP.

Pertimbangan keamanan untuk autentikasi identitas terkelola

Saat menggunakan autentikasi identitas terkelola dengan keterampilan API Web Kustom, Pencarian Azure AI mendapatkan token akses Microsoft Entra untuk aplikasi yang diidentifikasi oleh authResourceId dan menyertakan token tersebut dalam permintaan yang dikirim ke titik akhir yang ditentukan oleh uri. Titik akhir yang direferensikan oleh uri biasanya adalah Fungsi Azure, Azure App Service, titik akhir Azure API Management, atau aplikasi lain yang dilindungi Microsoft Entra. Anda bertanggung jawab untuk mengonfigurasi dan memelihara hubungan antara titik akhir dan aplikasi yang diidentifikasi oleh authResourceId.

Terlepas dari metode autentikasi, input keterampilan kustom dapat berisi nilai dari dokumen atau nilai yang disediakan pelanggan yang berasal dari dokumen tersebut. Perlakukan semua input keterampilan kustom sebagai tidak tepercaya. Pencarian Azure AI meneruskan input yang dikonfigurasi dalam set keterampilan ke titik akhir Anda tanpa menafsirkan, memvalidasi, atau membatasi kontennya untuk implementasi kustom Anda.

Validasi dan batasi nilai yang diturunkan dokumen dalam keterampilan kustom Anda sebelum menggunakannya dalam permintaan keluar atau operasi sensitif keamanan lainnya. Gunakan validasi input, daftar izin tujuan, validasi URL dan nama host, pembatasan protokol, dan akses jaringan dengan hak istimewa terendah yang hanya mengizinkan tujuan dan port yang diperlukan keterampilan. Untuk informasi selengkapnya, lihat Strategi arsitektur untuk jaringan dan konektivitas.

Praktik keamanan yang direkomendasikan

Untuk membantu mempertahankan penyebaran yang aman, ikuti praktik berikut:

• Konfigurasikan uri properti untuk mengarahkan hanya ke titik akhir tepercaya yang dimaksudkan untuk menerima permintaan dari Pencarian Azure AI.
• Konfigurasikan authResourceId untuk mengidentifikasi aplikasi Microsoft Entra yang diharapkan menerima dan memvalidasi token akses.
• Pastikan bahwa permintaan penerimaan aplikasi memvalidasi klaim token standar, termasuk audiens (aud), penerbit (iss), penyewa (tid), dan peran atau izin aplikasi yang diperlukan, sebelum memproses permintaan.
• Terapkan prinsip hak istimewa paling sedikit saat memberikan izin ke identitas terkelola Pencarian Azure AI.
• Tinjau definisi keterampilan API Web Kustom secara berkala, Microsoft Entra pendaftaran aplikasi, dan penetapan peran aplikasi dan izin yang diberikan untuk Pencarian Azure AI identitas terkelola. Tinjau perubahan konfigurasi melalui proses manajemen perubahan dan peninjauan keamanan yang ditetapkan.
• Tinjau konfigurasi titik akhir secara berkala untuk Azure Functions, App Services, API, dan gateway API.
• Pantau log masuk aplikasi, peristiwa autentikasi, dan log akses API untuk aktivitas yang tidak terduga atau tidak sah.
• Hapus titik akhir, izin, pendaftaran aplikasi, dan penetapan peran yang tidak lagi diperlukan.

Membatasi akses ke konfigurasi skillset

Pengguna yang dapat membuat, memodifikasi, atau menjalankan set keterampilan dapat mengontrol titik akhir tujuan dan konfigurasi autentikasi yang digunakan oleh keterampilan API Web Kustom. Batasi izin ini ke administrator tepercaya dan ikuti proses manajemen perubahan dan peninjauan keamanan standar Anda saat mengonfigurasi keterampilan kustom yang mendukung identitas terkelola.

Baca juga

• Tentukan keterampilan
• Menambahkan keterampilan kustom ke alur pengayaan AI
• Contoh: Membuat keterampilan kustom untuk pengayaan AI
• Repositori Power Skill