Keterampilan AML dalam alur pengayaan Azure AI Search

  • Artikel

Penting

Kemampuan ini berada di pratinjau publik di bawah ketentuan penggunaan tambahan. REST API pratinjau mendukung kemampuan ini.

Keterampilan AML memungkinkan Anda untuk memperluas pengayaan AI dengan model Azure Machine Learning (AML) kustom. Setelah model AML dilatih dan digunakan, keterampilanAML mengintegrasikannya ke dalam pengayaan AI.

Seperti keterampilan bawaan, keterampilan AML memiliki input dan output. Input dikirim ke titik akhir online AML yang Anda sebarkan sebagai objek JSON, yang menghasilkan payload JSON sebagai respons bersama dengan kode status keberhasilan. Respon diharapkan memiliki output yang ditentukan oleh keterampilan AML Anda. Respons lain dianggap sebagai kesalahan dan tidak ada pengayaan yang dilakukan.

Catatan

Pengindeks akan mencoba kembali dua kali untuk kode status HTTP standar tertentu yang dikembalikan dari titik akhir online AML. Kode status HTTP ini adalah:

  • 503 Service Unavailable
  • 429 Too Many Requests

Prasyarat

@odata.type

Microsoft.Skills.Custom.AmlSkill

Parameter keterampilan

Parameternya peka huruf besar/kecil. Parameter mana yang Anda pilih untuk digunakan tergantung pada autentikasi apa yang diperlukan titik akhir online AML Anda, jika ada

Nama Parameter Deskripsi
uri (Diperlukan untuk autentikasi kunci) URI penilaian titik akhir online AML tempat payload JSON dikirim. Hanya skema URI https yang diperbolehkan.
key (Diperlukan untuk autentikasi kunci) Kunci untuk titik akhir online AML.
resourceId (Diperlukan untuk autentikasi token). ID sumber daya Azure Resource Manager dari titik akhir online AML. Ini harus dalam format langganan/{guid}/resourceGroups/{resource-group-name}/Microsoft.Machine Pembelajaran Services/workspaces/{workspace-name}/onlineendpoints/{endpoint_name}.
region (Bersifat opsional untuk autentikasi token). Wilayah tempat titik akhir online AML disebarkan.
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.
degreeOfParallelism (Opsional) Ketika ditentukan, menunjukkan jumlah panggilan yang dilakukan pengindeks secara paralel dengan titik akhir yang telah Anda berikan. Anda dapat mengurangi nilai ini jika titik akhir Anda gagal di bawah beban permintaan yang terlalu tinggi. Anda dapat menaikkannya jika titik akhir Anda dapat menerima lebih banyak permintaan dan Anda ingin meningkatkan performa pengindeks. Jika tidak diatur, nilai default 5 akan digunakan. DerajatOfParallelism dapat diatur ke maksimum 10 dan minimal 1.

Parameter keterampilan apa yang akan digunakan

Parameter keterampilan AML mana yang diperlukan tergantung pada autentikasi apa yang digunakan titik akhir online AML Anda, jika ada. Titik akhir online AML menyediakan dua opsi autentikasi:

  • Autentikasi berbasis kunc. Kunci statis disediakan untuk mengautentikasi permintaan penilaian dari keterampilan AML
    • Gunakan parameter uri dan kunci
  • Autentikasi berbasis token. Titik akhir online AML disebarkan menggunakan autentikasi berbasis token. Identitas terkelola Azure AI layanan Pencarian harus diaktifkan. Keterampilan AML kemudian menggunakan identitas terkelola layanan untuk mengautentikasi terhadap titik akhir online AML, tanpa kunci statis yang diperlukan. Identitas harus diberi peran pemilik atau kontributor.
    • Gunakan parameter resourceId.
    • Jika layanan pencarian berada di wilayah yang berbeda dari ruang kerja AML, gunakan parameter wilayah untuk mengatur wilayah tempat titik akhir online AML disebarkan

Input keterampilan

Tidak ada input "yang telah ditentukan" untuk keterampilan ini. Anda dapat memilih satu atau beberapa bidang yang akan sudah tersedia pada saat eksekusi keterampilan ini sebagai input dan payload JSON yang dikirim ke titik akhir online AML akan memiliki bidang yang berbeda.

Output keterampilan

Tidak ada input "yang telah ditentukan" untuk keterampilan ini. Bergantung pada respons yang dikembalikan titik akhir online AML Anda, tambahkan bidang output sehingga dapat diambil dari respons JSON .

Definisi sampel

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

Contoh input struktur JavaScript Object Notation

Struktur JSON ini mewakili payload yang dikirim ke titik akhir online AML Anda. Bidang tingkat atas struktur 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)

{
  "text": "Este es un contrato en Inglés"
}

Contoh struktur JSON output

Output sesuai dengan respons yang dikembalikan dari titik akhir online AML Anda. Titik akhir online AML hanya boleh mengembalikan payload JSON (diverifikasi Content-Type dengan melihat header respons) dan harus menjadi objek di mana bidang adalah pengayaan yang cocok dengan "nama" dalam output dan yang nilainya dianggap sebagai pengayaan.

{
    "detected_language_code": "es"
}

Definisi sampel pembentukan sebaris

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "shapedText",
        "sourceContext": "/document",
        "inputs": [
            {
              "name": "content",
              "source": "/document/content"
            }
        ]
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

Membentuk struktur JSON input sebaris

{
  "shapedText": { "content": "Este es un contrato en Inglés" }
}

Membentuk contoh struktur JSON secara sebaris

{
    "detected_language_code": "es"
}

Kasus kesalahan

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

  • Jika titik akhir online AML mengembalikan kode status keberhasilan tetapi respons menunjukkan bahwa itu bukan application/json, maka respons dianggap tidak valid dan tidak ada pengayaan yang dilakukan.
  • Jika titik akhir online AML mengembalikan json yang tidak valid

Untuk kasus ketika titik akhir online AML tidak tersedia atau mengembalikan kesalahan HTTP, kesalahan ramah dengan detail yang tersedia tentang kesalahan HTTP akan ditambahkan ke riwayat eksekusi pengindeks.

Baca juga