Menambahkan keterampilan kustom ke alur pengayaan Azure AI Search

  • Artikel

Alur pengayaan AI dapat mencakup keterampilan bawaan dan keterampilan kustom yang Anda buat dan terbitkan secara pribadi. Kode kustom Anda dijalankan secara eksternal ke layanan pencarian (misalnya, sebagai fungsi Azure), tetapi menerima input dan mengirim output ke set keterampilan seperti keterampilan lainnya.

Keterampilan kustom mungkin terdengar kompleks tetapi memiliki implementasi yang sederhana dan mudah. Jika Anda sudah memiliki paket yang menyediakan model pencocokan atau klasifikasi pola, konten yang Anda ekstrak dari blob dapat diteruskan ke model ini untuk diproses. Karena pengayaan AI berbasis Azure, model Anda juga harus berada di Azure. Beberapa metodologi hosting yang umum digunakan termasuk Azure Functions atau Kontainer.

Jika Anda membangun keterampilan kustom, artikel ini menjelaskan antarmuka yang Anda gunakan untuk mengintegrasikan keterampilan ke dalam alur. Persyaratan utama adalah kemampuan untuk menerima input dan memancarkan output dengan cara yang dapat dikonsumsi dalam set keterampilan secara keseluruhan. Dengan demikian, fokus artikel ini adalah pada format input dan output yang diperlukan alur pengayaan.

Manfaat keterampilan kustom

Membuat keterampilan khusus memberi Anda cara untuk menyisipkan transformasi unik ke konten Anda. Keterampilan khusus berjalan secara independen, menerapkan langkah pengayaan apa pun yang Anda perlukan. Misalnya, Anda dapat membuat model klasifikasi khusus untuk membedakan kontrak dan dokumen bisnis dan keuangan, atau menambahkan keterampilan pengenalan suara untuk mengoptimalkan penggunaan file audio pada konten yang relevan. Untuk contoh langkah demi langkahnya, lihat Contoh: Membuat keterampilan khusus untuk Pengayaan AI.

Mengatur interval titik akhir dan batas waktu

Antarmuka untuk keterampilan kustom ditentukan melalui keterampilan API Web Kustom.

"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "This skill has a 230 second timeout",
"uri": "https://[your custom skill uri goes here]",
"authResourceId": "[for managed identity connections, your app's client ID goes here]",
"timeout": "PT230S",

URI adalah titik akhir HTTPS fungsi atau aplikasi Anda. Saat mengatur URI, pastikan URI aman (HTTPS). Jika kode Anda dihosting di aplikasi fungsi Azure, URI harus menyertakan kunci API di header atau sebagai parameter URI untuk mengotorisasi permintaan.

Jika fungsi atau aplikasi Anda menggunakan identitas terkelola Azure dan peran Azure untuk autentikasi dan otorisasi, keterampilan kustom dapat menyertakan token autentikasi pada permintaan. Poin-poin berikut menjelaskan persyaratan untuk pendekatan ini:

  • Layanan pencarian, yang mengirim permintaan atas nama pengindeks, harus dikonfigurasi untuk menggunakan identitas terkelola (baik sistem atau yang ditetapkan pengguna) sehingga pemanggil dapat diautentikasi oleh ID Microsoft Entra.

  • Fungsi atau aplikasi Anda harus dikonfigurasi untuk ID Microsoft Entra.

  • Definisi keterampilan kustom Anda harus menyertakan properti "authResourceId". Properti ini mengambil ID aplikasi (klien), dalam format yang didukung: api://<appId>.

Secara default, koneksi ke titik akhir kehabisan waktu jika respons tidak dikembalikan dalam jendela 30 detik. Alur pengindeksan sinkron dan pengindeksan akan menghasilkan kesalahan waktu habis jika respons tidak diterima dalam jangka waktu tersebut. Anda dapat meningkatkan interval ke nilai maksimum 230 detik dengan mengatur parameter batas waktu:

Memformat input WEB API

Web API harus menerima array data untuk diproses. Setiap rekaman harus berisi tas properti yang merupakan input yang disediakan untuk API Web Anda.

Misalkan Anda ingin membuat pengaya dasar yang mengidentifikasi tanggal pertama yang disebutkan dalam teks kontrak. Dalam contoh ini, keterampilan kustom menerima satu input "contractText" sebagai teks kontrak. Keterampilan juga memiliki satu output, yaitu tanggal kontrak. Untuk membuat pengaya lebih menarik, kembalikan "contractDate" ini dalam bentuk jenis kompleks multi-bagian.

Web API Anda harus siap menerima batch data input. Setiap anggota array "nilai" mewakili input untuk rekaman tertentu. Setiap data harus memiliki elemen berikut:

  • Anggota "recordId" yang merupakan pengidentifikasi unik untuk rekaman tertentu. Ketika pengaya Anda mengembalikan hasil, pengaya harus memberikan "recordId" ini untuk memungkinkan pemanggil mencocokkan hasil rekaman dengan input mereka.

  • Anggota "data", yang pada dasarnya merupakan kantong bidang input untuk setiap rekaman.

Permintaan API Web yang dihasilkan mungkin terlihat seperti ini:

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issues on November 3, 2017 and that involves... "
           }
      },
      {
        "recordId": "b5",
        "data":
           {
             "contractText": 
                "In the City of Seattle, WA on February 5, 2018 there was a decision made..."
           }
      },
      {
        "recordId": "c3",
        "data":
           {
             "contractText": null
           }
      }
    ]
}

Dalam praktiknya, kode Anda mungkin dipanggil dengan ratusan atau ribuan rekaman alih-alih hanya tiga yang ditampilkan di sini.

Memformat output WEB API

Format output adalah sekumpulan rekaman yang berisi "recordId", dan tas properti. Contoh khusus ini hanya memiliki satu output, tetapi Anda dapat menghasilkan output lebih dari satu properti. Sebagai praktik terbaik, pertimbangkan untuk mengembalikan pesan kesalahan dan peringatan jika rekaman tidak dapat diproses.

{
  "values": 
  [
      {
        "recordId": "b5",
        "data" : 
        {
            "contractDate":  { "day" : 5, "month": 2, "year" : 2018 }
        }
      },
      {
        "recordId": "a1",
        "data" : {
            "contractDate": { "day" : 3, "month": 11, "year" : 2017 }                    
        }
      },
      {
        "recordId": "c3",
        "data" : 
        {
        },
        "errors": [ { "message": "contractText field required "}   ],  
        "warnings": [ {"message": "Date not found" }  ]
      }
    ]
}

Menambahkan kemampuan khusus ke kumpulan kemampuan

Saat membuat pengaya Web API, Anda dapat mendeskripsikan header dan parameter HTTP sebagai bagian dari permintaan. Cuplikan berikut menunjukkan bagaimana parameter permintaan dan header HTTP opsional dapat disertakan dalam definisi set keterampilan. Mengatur header HTTP berguna jika Anda perlu meneruskan pengaturan konfigurasi ke kode Anda.

{
    "skills": [
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "name": "myCustomSkill",
        "description": "This skill calls an Azure function, which in turn calls TA sentiment",
        "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/DateExtractor?language=en",
        "context": "/document",
        "httpHeaders": {
            "DateExtractor-Api-Key": "foo"
        },
        "inputs": [
          {
            "name": "contractText",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "contractDate",
            "targetName": "date"
          }
        ]
      }
  ]
}

Tonton video ini

Untuk pengantar dan demo video, tonton demo berikut.

Langkah berikutnya

Artikel ini membahas persyaratan antarmuka yang diperlukan untuk mengintegrasikan keterampilan khusus ke kumpulan keterampilan. Lanjutkan dengan tautan ini untuk mempelajari lebih lanjut tentang keterampilan kustom dan komposisi set keterampilan.