Tambahkan skill kustom ke alur pengayaan Pencarian Azure AI

Alur pengayaan AI dapat mencakup keterampilan bawaan dan keterampilan kustom yang Anda buat dan terbitkan. Kode kustom Anda dijalankan di luar search service (misalnya, sebagai fungsi Azure), tetapi menerima input dan mengirim output ke set keterampilan seperti keterampilan lainnya. Data Anda diproses dalam geography tempat model Anda disebarkan.

Keterampilan kustom mungkin terdengar kompleks, tetapi dapat dengan mudah diimplementasikan. Jika Anda memiliki paket yang ada yang menyediakan model pencocokan pola atau klasifikasi, konten yang diekstrak dari blob dapat diteruskan ke model tersebut untuk diproses. Karena pengayaan AI berbasis Azure, model Anda juga harus dihosting di Azure. Opsi hosting umum 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. 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.

Tetapkan titik akhir dan interval batas waktu

Antarmuka untuk keterampilan kustom ditentukan melalui 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:

Secara default, koneksi ke titik akhir kehabisan waktu jika respons tidak dikembalikan dalam jendela 30 detik (PT30S). Alur pengindeksan bersifat sinkron, sehingga pengindeksan akan menghasilkan kesalahan batas waktu jika respons tidak diterima dalam jangka waktu tersebut. Anda dapat meningkatkan interval ke nilai maksimum 230 detik dengan mengatur timeout parameter (PT230S).

Format input web API

API web harus menerima array rekaman untuk diproses. Dalam setiap rekaman, sediakan kantong properti sebagai input ke API web Anda.

Misalkan Anda ingin membuat program pengaya dasar yang mengidentifikasi tanggal pertama yang disebutkan dalam teks kontrak. Dalam contoh ini, keterampilan kustom menerima satu input, "contractText." Keterampilan ini juga memiliki satu output, yang merupakan tanggal kontrak. Untuk membuat pengkaya lebih menarik, kembalikan "contractDate" dalam bentuk tipe kompleks multipart.

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

  • Anggota "recordId" yang merupakan pengidentifikasi unik untuk catatan tertentu. Saat pengaya Anda mengembalikan hasil, harus memberikan "recordId" ini sehingga pemanggil dapat mencocokkan hasil catatan dengan input.

  • Anggota "data", yang merupakan kumpulan kolom input untuk setiap catatan.

Permintaan API Web yang dihasilkan mungkin terlihat seperti ini:

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issued on November 3, 2023 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 dapat dipanggil dengan ratusan atau ribuan rekaman alih-alih hanya tiga yang ditampilkan di sini.

Memformat keluaran API web

Format output adalah sekumpulan rekaman yang berisi "recordId" dan tas properti. Contoh khusus ini hanya memiliki satu output, tetapi Anda dapat mengembalikan 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" : 2023 }                    
        }
      },
      {
        "recordId": "c3",
        "data" : 
        {
        },
        "errors": [ { "message": "contractText field required "}   ],  
        "warnings": [ {"message": "Date not found" }  ]
      }
    ]
}

Menambahkan kemampuan khusus ke kumpulan kemampuan

Saat membuat penambah API web, Anda dapat menentukan HTTP header dan parameter 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.

  • Last updated on