Keterampilan GenAI Prompt

Keterampilan GenAI (Generative AI) Prompt mengeksekusi permintaan chat completion terhadap model bahasa besar (LLM) yang disebarkan di Azure OpenAI di Foundry Models atau Microsoft Foundry. Gunakan keterampilan ini untuk membuat informasi baru yang dapat diindeks dan disimpan sebagai konten yang dapat dicari.

Berikut adalah beberapa contoh bagaimana skill prompt GenAI dapat membantu Anda membuat konten:

• Memverifikasi gambar
• Ringkas bagian-bagian teks yang besar
• Menyederhanakan konten yang kompleks
• Lakukan tugas lain yang dapat Anda artikulasikan dalam prompt

Keterampilan GenAI Prompt umumnya tersedia di 2026-04-01 Search Service REST API dan di Azure SDK yang menargetkan versi ini. Keterampilan ini mendukung teks, gambar, dan konten multimodal, seperti gambar dengan visual dan teks yang diekstrak dari file PDF.

Model yang didukung

• Anda dapat menggunakan model inferensi penyelesaian obrolan apa pun yang disebarkan di Foundry, seperti model GPT, DeepSeek-R#, Llama-4-Maverick, dan Cohere-command-r. Untuk model GPT secara khusus, hanya titik akhir API penyelesaian obrolan yang didukung. Titik akhir yang menggunakan Azure OpenAI Responses API (berisi /openai/responses dalam URI) saat ini tidak kompatibel.

• Untuk verbalisasi gambar, model yang Anda gunakan untuk menganalisis gambar menentukan format gambar apa yang didukung.

• Untuk model GPT-5, parameter tidak temperature didukung dengan cara yang sama seperti model sebelumnya. Jika ditentukan, itu harus diatur ke 1.0, karena nilai lain akan menghasilkan kesalahan.

• Penagihan didasarkan pada harga model yang Anda gunakan.

Prasyarat

• Azure OpenAI di sumber daya Foundry Models atau proyek Foundry.

• Model yang didukung yang disebarkan ke sumber daya atau proyek Anda.

  • Untuk Azure OpenAI, salin titik akhir dengan domain openai.azure.com dari halaman Keys dan Endpoint di portal Azure. Gunakan titik akhir ini untuk Uri parameter dalam keterampilan ini.

  • Untuk Foundry, salin URI target untuk penyebaran dari halaman Model di portal Foundry. Gunakan titik akhir ini untuk Uri parameter dalam keterampilan ini.

• Autentikasi dapat berbasis kunci dengan kunci API dari sumber daya Foundry atau Azure OpenAI Anda. Namun, kami merekomendasikan akses berbasis peran menggunakan identitas terkelola layanan pencarian yang ditetapkan ke peran.

  • Di Azure OpenAI, tetapkan Cognitive Services OpenAI User ke identitas terkelola.

  • Di Foundry, tetapkan Pengguna Foundry ke identitas terkelola.

    Important

    Peran RBAC Foundry baru-baru ini diganti namanya. pengguna Foundry, pemilik Foundry, Pemilik Akun Foundry, dan Manajer Project Foundry sebelumnya diberi nama Azure Pengguna AI, Pemilik AI Azure, Pemilik Akun AI Azure, dan Manajer Project AI Azure. Anda mungkin masih melihat nama sebelumnya di beberapa tempat saat penggantian nama diluncurkan. ID peran dan izin inti tidak berubah oleh penggantian nama.

@odata.type

#Microsoft.Skills.Custom.ChatCompletionSkill

Batasan data

Parameter keterampilan

* Tepat salah satu dari apiKey, authIdentity, atau identitas yang ditetapkan sistem layanan harus digunakan.

commonModelParameters Default

Masukan keterampilan

Keluaran Keterampilan

Contoh definisi

Ringkasan teks saja

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "Summarizer",
  "description": "Summarizes document content.",
  "context": "/document",
  "inputs": [
    { "name": "text", "source": "/document/content" },
    { "name": "systemMessage", "source": "='You are a concise AI assistant.'" },
    { "name": "userMessage", "source": "='Summarize the following text:'" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "apiKey": "<api-key>",
  "commonModelParameters": { "temperature": 0.3 }
}

Deskripsi teks + gambar

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "Image Describer",
  "context": "/document/normalized_images/*",
  "inputs": [
    { "name": "image", "source": "/document/normalized_images/*/data" },
    { "name": "imageDetail", "source": "=high" },
    { "name": "systemMessage", "source": "='You are a useful AI assistant.'" },
    { "name": "userMessage", "source": "='Describe this image:'" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "authIdentity": "11111111-2222-3333-4444-555555555555",
  "responseFormat": { "type": "text" }
}

Pencari fakta numerik terstruktur

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "NumericalFactFinder",
  "context": "/document",
  "inputs": [
    { "name": "systemMessage", "source": "='You are an AI assistant that helps people find information.'" },
    { "name": "userMessage", "source": "='Find all the numerical data and put it in the specified fact format.'"}, 
    { "name": "text", "source": "/document/content" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "apiKey": "<api-key>",
  "responseFormat": {
    "type": "json_schema",
    "jsonSchemaProperties": {
      "name": "NumericalFactObj",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": "{\"facts\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"number\":{\"type\":\"number\"},\"fact\":{\"type\":\"string\"}},\"required\":[\"number\",\"fact\"]}}}",
        "required": [ "facts" ],
        "additionalProperties": false
      }
    }
  }
}

Keluaran sampel (terpotong)

{
  "response": {
    "facts": [
      { "number": 32.0, "fact": "Jordan scored 32 points per game in 1986-87." },
      { "number": 6.0,  "fact": "He won 6 NBA championships." }
    ]
  },
  "usageInformation": {
    "usage": {
      "completion_tokens": 203,
      "prompt_tokens": 248,
      "total_tokens": 451
    }
  }
}

Praktik terbaik

• Potong dokumen panjang dengan keterampilan Text Split agar tetap berada dalam jendela konteks model.
• Untuk pengindeksan volume tinggi, dedikasikan penyebaran model terpisah untuk keterampilan ini sehingga kuota token untuk beban kerja RAG waktu kueri tetap tidak terpengaruh.
• Untuk meminimalkan latensi, temukan model dan layanan Pencarian Azure AI Anda di wilayah Azure yang sama.
• Gunakan responseFormat.json_schema dengan GPT-4o untuk ekstraksi terstruktur yang andal dan pemetaan yang lebih mudah ke bidang indeks.
• Pantau penggunaan token dan kirimkan permintaan peningkatan kuota jika pengindeks menjenuhkan batas Token per Menit (TPM) Anda.

Kesalahan dan peringatan

Pertimbangan keamanan untuk autentikasi identitas terkelola

Ketika keterampilan GenAI Prompt menggunakan autentikasi identitas terkelola, Pencarian Azure AI mendapatkan token akses Microsoft Entra untuk audiens Foundry Tools (https://cognitiveservices.azure.com) dan menyertakannya dalam permintaan yang dikirim ke titik akhir yang ditentukan oleh uri. Autentikasi identitas terkelola berlaku saat authIdentity diatur, atau ketika dan apiKeyauthIdentity kosong dan layanan menggunakan identitas yang ditetapkan sistem.

Titik akhir yang dirujuk oleh uri diharapkan menjadi sumber daya OpenAI atau Foundry Azure Anda sendiri. Domain yang didukung adalah:

• openai.azure.com
• cognitiveservices.azure.com
• services.ai.azure.com

titik akhir Azure API Management (APIM) (*.azure-api.net) dan domain kustom yang berada di depan sumber daya ini juga didukung. Karena domain kustom atau nama host APIM tidak dapat diverifikasi dari namanya saja, Pencarian Azure AI memvalidasi titik akhir ini dengan pemeriksaan konektivitas langsung pada waktu konfigurasi daripada dengan pencocokan domain. Anda bertanggung jawab untuk mengonfigurasi dan memelihara hubungan antara titik akhir dan sumber daya OpenAI atau Foundry Azure di belakangnya.

Praktik keamanan yang direkomendasikan

Untuk membantu mempertahankan penyebaran yang aman, ikuti praktik berikut:

• Atur uri hanya ke titik akhir yang Anda miliki dan percayai. Lebih suka domain Foundry Tools yang tercantum sebelumnya. Jika Anda menggunakan APIM atau titik akhir domain kustom, konfirmasikan itu depan sumber daya Anda sendiri sebelum mengaktifkan identitas terkelola. Nama host yang terlihat tepercaya bukan bukti kepemilikan.
• Terapkan prinsip hak istimewa paling sedikit ke identitas terkelola yang digunakan oleh layanan pencarian:
  • Di Azure OpenAI, tetapkan hanya Pengguna OpenAI Cognitive Services.
  • Di Foundry, hanya tetapkan Pengguna Foundry. Hindari memberikan peran yang lebih luas.
• Gunakan Perimeter Keamanan Jaringan (NSP) dan titik akhir privat atau integrasi VNet untuk membatasi titik akhir mana yang dapat dijangkau layanan pencarian dan sumber sumber daya target mana yang menerima permintaan.
• Jika Anda menggunakan APIM atau titik akhir domain kustom, pastikan gateway memvalidasi permintaan masuk dan meneruskannya hanya ke backend yang dimaksudkan. Anda juga harus meninjau kebijakan aksesnya secara berkala.
• Lebih suka identitas terkelola daripada apiKey. Jika Anda menggunakan apiKey, simpan dan putar dengan aman dan jangan sematkan dalam kontrol sumber. Layanan menolak konfigurasi yang mengatur dan apiKeyauthIdentity.
• Tinjau definisi skillset secara berkala, penetapan peran identitas terkelola, serta APIM dan konfigurasi domain kustom untuk mengonfirmasi bahwa uri nilai, kontrol akses, dan izin identitas tetap terkini dan sesuai. Tinjau perubahan konfigurasi melalui proses manajemen perubahan dan peninjauan keamanan yang ditetapkan.
• Pantau Azure log masuk OpenAI, Foundry Tools, dan Foundry, peristiwa autentikasi, dan log akses untuk aktivitas yang tidak terduga atau tidak sah.
• Hapus keterampilan, titik akhir, penetapan peran, dan kunci API yang tidak lagi diperlukan.

Membatasi akses ke konfigurasi skillset

Pengguna yang dapat membuat, memodifikasi, atau menjalankan set keterampilan mengontrol titik akhir tujuan (uri) dan konfigurasi autentikasi yang digunakan oleh keterampilan. Karena keterampilan mengirim token identitas terkelola untuk audiens Foundry Tools ke titik akhir tersebut, batasi izin ini ke administrator tepercaya dan ikuti proses manajemen perubahan dan peninjauan keamanan standar Anda saat mengonfigurasi keterampilan yang mendukung identitas terkelola.

Baca juga

• Pencarian Azure AI pengindeks bawaan
• Vektorisasi terintegrasi
• Cara menentukan keahlian
• Cara menghasilkan penyelesaian obrolan dengan inferensi model AI Azure (Foundry)
• Output terstruktur di Azure OpenAI