Tambahkan skill kustom ke alur pengayaan Pencarian Azure AI

Note

Pencarian Azure AI tersedia melalui portal Azure, REST API, dan Azure SDK. Ini juga mendukung Foundry IQ, lapisan pengetahuan terkelola yang mengubah konten perusahaan menjadi pangkalan pengetahuan yang dapat digunakan kembali dan sadar izin untuk agen di portal Microsoft Foundry.

Alur pengayaan AI dapat mencakup keterampilan bawaan dan keterampilan kustom yang Anda buat dan terbitkan. Kode kustom Anda berjalan di luar layanan pencarian (misalnya, sebagai fungsi Azure), tetapi menerima input dan mengirim output ke skillset sama 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, Anda dapat meneruskan konten yang diekstrak dari blob ke model tersebut untuk diproses. Karena pengayaan AI berbasis Azure, Anda juga harus menghosting model Anda 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 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

Tentukan antarmuka untuk keterampilan kustom 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 Anda menghosting kode di aplikasi fungsi Azure, sertakan kunci API di header atau sebagai parameter URI di 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:

Pastikan bahwa uri menunjuk ke titik akhir aplikasi yang diidentifikasi oleh authResourceId. Nilai yang tidak cocok dapat menyebabkan kegagalan autentikasi atau permintaan dikirim ke titik akhir yang tidak diinginkan. Untuk panduan keamanan, praktik yang direkomendasikan, dan langkah-langkah untuk memverifikasi konfigurasi Anda, lihat Pertimbangan keamanan untuk autentikasi identitas terkelola.

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).

Jika titik akhir yang dilindungi oleh pembatasan akses IP tidak merespons, atur timeout sementara ke nilai pendek, seperti PT10S, untuk menampilkan kesalahan batas waktu lebih cepat. Untuk aplikasi fungsi Azure, kelola aturan IP masuk di bawah Pengaturan>Pembatasan Akses>. Agar alamat IP diizinkan, lihat Mengonfigurasi aturan firewall IP untuk mengizinkan koneksi pengindeks.

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, keahlian kustom menerima satu input, contractText. Keterampilan ini juga memiliki satu output, yang merupakan tanggal kontrak. Untuk membuat pengaya lebih menarik, kembalikan contractDate dalam bentuk tipe kompleks multipart.

API web Anda harus siap untuk menerima sekumpulan catatan input. Setiap anggota values array mewakili input untuk rekaman tertentu. Setiap data harus memiliki elemen berikut:

  • Anggota recordId yang menjadi pengenal unik untuk catatan tertentu. Saat enricher Anda mengembalikan hasil, enricher tersebut harus menyediakan recordId ini agar pemanggil dapat mencocokkan hasil untuk setiap record dengan masukannya.

  • Sebuah 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 keluaran adalah sekumpulan rekaman yang berisi recordId dan kumpulan 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"
          }
        ]
      }
  ]
}

Note

Saat Anda mengambil kumpulan keterampilan dengan GET, layanan mengembalikan <redacted> untuk semua nilai httpHeaders guna mencegah tereksposnya kredensial. Untuk memperbarui keterampilan tanpa mengubah nilai header tersimpan, atur setiap nilai ke <unchanged>. Untuk detail dan contohnya, lihat Keterampilan API Web Kustom — Parameter keterampilan.

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. Untuk mempelajari selengkapnya tentang keterampilan kustom dan komposisi set keterampilan, lihat sumber daya berikut:

  • Terakhir diperbarui pada