Bagikan melalui

Mengambil data dengan menggunakan pangkalan pengetahuan di Azure AI Search

Nota

Fitur ini saat ini dalam pratinjau publik. Pratinjau ini disediakan tanpa perjanjian tingkat layanan dan tidak direkomendasikan untuk beban kerja produksi. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan terbatas. Untuk informasi lebih lanjut, lihat Supplemental Terms of Use for Microsoft Azure Previews.

Dalam alur multi-kueri pengambilan agenik, eksekusi kueri adalah melalui tindakan ambil pada pangkalan pengetahuan yang memanggil pemrosesan kueri paralel. Struktur permintaan ini diperbarui untuk pratinjau 2025-11-01 yang baru, yang memperkenalkan perubahan yang tidak kompatibel dari pratinjau sebelumnya. Untuk bantuan terkait perubahan yang melanggar, lihat Memigrasikan kode pengambilan agenik Anda.

Artikel ini menjelaskan cara menyetel aksi pengambilan. Ini juga menjelaskan tiga komponen dari respons pengambilan tersebut:

  • respons yang diekstrak untuk LLM
  • hasil yang dirujuk
  • aktivitas permintaan

Permintaan pengambilan dapat mencakup instruksi untuk pemrosesan kueri yang menggantikan instruksi default yang ditetapkan pada pangkalan pengetahuan. Aksi ambil memiliki parameter inti yang didukung pada permintaan apa pun, ditambah parameter yang khusus untuk sumber pengetahuan.

Anda juga dapat menggunakan sintesis jawaban opsional untuk membawa rumusan jawaban LLM ke dalam alur kueri, mengembalikan jawaban ringkas atau diformat ke agen atau aplikasi.

Prasyarat

  • Sumber pengetahuan yang didukung yang membungkus indeks yang dapat dicari atau menunjuk ke sumber eksternal untuk pengambilan data asli.

  • Pangkalan pengetahuan yang mewakili satu atau beberapa sumber pengetahuan. Jika Anda ingin perencanaan kueri cerdas dan rumusan jawaban, sertakan model penyelesaian obrolan.

  • Azure AI Search di mana saja di wilayah yang menyediakan pengambilan berbasis agen.

  • Izin pada Azure AI Search. Peran untuk mengambil konten termasuk Pembaca Data Indeks Pencarian untuk menjalankan kueri. Untuk mendukung panggilan keluar dari layanan pencarian ke model penyelesaian obrolan, Anda harus mengonfigurasi identitas terkelola untuk layanan pencarian, dan harus memiliki izin Pengguna Cognitive Services pada sumber daya Azure OpenAI. Untuk informasi selengkapnya tentang pengujian lokal dan mendapatkan token akses, lihat Mulai Cepat: Menyambungkan tanpa kunci.

  • Persyaratan versi API. Untuk membuat atau menggunakan basis pengetahuan, gunakan REST API datar data pratinjau 2025-11-01. Atau, gunakan paket pratinjau Azure SDK yang menyediakan API pangkalan pengetahuan: Python, .NET, Java.

Untuk mengikuti langkah-langkah dalam panduan ini, kami merekomendasikan Visual Studio Code dengan klien REST untuk mengirim panggilan REST API ke Azure AI Search.

Mengatur tindakan mengambil

Tentukan tindakan ambil pada pangkalan pengetahuan. Pangkalan pengetahuan memiliki satu atau beberapa sumber pengetahuan. Pengambilan dapat mengembalikan jawaban yang disintesis dalam bahasa alami atau potongan dasar mentah dari sumber pengetahuan.

  • Tinjau definisi pangkalan pengetahuan Anda untuk memahami sumber pengetahuan mana yang berada dalam cakupan.

  • Tinjau sumber pengetahuan Anda untuk memahami parameter dan konfigurasinya.

  • Gunakan REST API lapisan data pratinjau 2025-11-01 atau paket pratinjau Azure SDK untuk memanggil ambil.

Untuk sumber pengetahuan yang memiliki instruksi pengambilan default, Anda dapat mengambil alih default dalam permintaan pengambilan.

Pengambilan dari indeks pencarian

Untuk sumber pengetahuan yang menargetkan indeks pencarian, semua kolom searchable berada dalam cakupan untuk eksekusi kueri. Jika indeks menyertakan bidang vektor, indeks Anda harus memiliki definisi vektorizer yang valid sehingga mesin pengambilan agenik dapat mem-vektorisasi input kueri. Jika tidak, bidang vektor diabaikan. Jenis kueri tersirat adalah semantic, dan tidak ada mode pencarian.

Masukan untuk jalur pengambilan adalah riwayat percakapan obrolan dalam bahasa alami, yang mana array messages tersebut berisi percakapan. Mesin pengambilan agenik mendukung pesan hanya jika upaya penalaran pengambilan rendah atau sedang.

@search-url=<YOUR SEARCH SERVICE URL>
@accessToken=<YOUR PERSONAL ID>

# Send grounding request
POST https://{{search-url}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2025-11-01-preview
    Content-Type: application/json
    Authorization: Bearer {{accessToken}}

{
    "messages" : [
            {
                "role" : "assistant",
                "content" : [
                  { "type" : "text", "text" : "You can answer questions about the Earth at night.
                    Sources have a JSON format with a ref_id that must be cited in the answer.
                    If you do not have the answer, respond with 'I do not know'." }
                ]
            },
            {
                "role" : "user",
                "content" : [
                  { "type" : "text", "text" : "Why is the Phoenix nighttime street grid is so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?" }
                ]
            }
        ],
  "knowledgeSourceParams": [
    {
      "filterAddOn": null,
      "knowledgeSourceName": "earth-at-night-blob-ks",
      "kind": "searchIndex"
    }
  ]
}

Responses

Pengambilan yang berhasil menghasilkan 200 OK kode status. Jika pangkalan pengetahuan gagal mengambil dari satu atau beberapa sumber pengetahuan, kode status 206 Partial Content akan dikembalikan. Respons hanya mencakup hasil dari sumber yang berhasil. Detail tentang respons parsial muncul sebagai kesalahan dalam array aktivitas.

Mengambil parameter

Nama Description Tipe Dapat Diedit Diperlukan
messages Mengartikulasikan pesan yang dikirim ke model penyelesaian obrolan. Format pesan mirip dengan API Azure OpenAI. Objek Yes Tidak.
role Menentukan dari mana pesan berasal, misalnya atau assistantuser. Model yang Anda gunakan menentukan peran mana yang valid. String Yes Tidak.
content Pesan atau perintah yang dikirim ke LLM. Ini harus berupa teks dalam pratinjau ini. String Yes Tidak.
knowledgeSourceParams Menentukan parameter untuk setiap sumber pengetahuan jika Anda ingin mengkustomisasi kueri atau respons pada waktu kueri. Objek Yes Tidak.

Examples

Mengambil permintaan bervariasi tergantung pada sumber pengetahuan dan apakah Anda ingin mengambil alih konfigurasi default. Berikut adalah beberapa contoh yang mengilustrasikan berbagai permintaan.

Contoh: Mengambil alih upaya penalaran default dan menetapkan batas permintaan

Contoh ini menentukan rumusan jawaban, jadi retrievalReasoningEffort harus "rendah" atau "sedang".

POST {{url}}/knowledgebases/kb-override/retrieve?api-version={{api-version}}
api-key: {{key}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What companies are in the financial sector?" }
            ]
        }
    ],
    "retrievalReasoningEffort": { "kind": "low" },
    "outputMode": "answerSynthesis",
    "maxRuntimeInSeconds": 30,
    "maxOutputSize": 6000
}

Contoh: Mengatur referensi untuk setiap sumber pengetahuan

Contoh ini menggunakan upaya penalaran default yang ditentukan dalam pangkalan pengetahuan. Fokus dari contoh ini adalah spesifikasi berapa banyak informasi yang harus disertakan dalam respons.

POST {{url}}/knowledgebases/kb-medium-example/retrieve?api-version={{api-version}}
api-key: {{key}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What companies are in the financial sector?" }
            ]
        }
    ],
    "includeActivity": true,
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "demo-financials-ks",
            "kind": "searchIndex",
            "includeReferences": true,
            "includeReferenceSourceData": true
        },
        {
            "knowledgeSourceName": "demo-communicationservices-ks",
            "kind": "searchIndex",
            "includeReferences": false,
            "includeReferenceSourceData": false
        },
        {
            "knowledgeSourceName": "demo-healthcare=ks",
            "kind": "searchIndex",
            "includeReferences": true,
            "includeReferenceSourceData": false,
            "alwaysQuerySource": true
        }
    ]
}

Nota

Jika Anda mengambil konten dari Sumber pengetahuan OneLake atau SharePoint terindeks, atur includeReferenceSourceData ke true untuk menyertakan URL dokumen sumber dalam kutipan.

Contoh: upaya penalaran minimal

Dalam contoh ini, tidak ada model penyelesaian obrolan untuk perencanaan kueri cerdas atau rumusan jawaban. String kueri masuk ke mesin pengambilan agenik untuk pencarian kata kunci atau pencarian hibrid.

POST {{url}}/knowledgebases/kb-minimal/retrieve?api-version={{api-version}}
api-key: {{key}}
Content-Type: application/json

{
    "intents": [
        {
            "type": "semantic",
            "search": "what is a brokerage"
        }
    ]
}

Tinjau respons yang diekstrak

Respons yang diekstrak adalah string terintegrasi tunggal yang biasanya Anda teruskan ke LLM. LLM menggunakannya sebagai data grounding dan menggunakannya untuk merumuskan respons. Panggilan API Anda ke LLM menyertakan string terpadu dan instruksi untuk model, seperti apakah akan menggunakan grounding secara eksklusif atau sebagai suplemen.

Isi respons juga disusun dalam format gaya pesan obrolan. Saat ini, dalam rilis pratinjau ini, konten diserialisasikan JSON.

"response": [
    {
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "[{\"ref_id\":0,\"title\":\"Urban Structure\",\"terms\":\"Location of Phoenix, Grid of City Blocks, Phoenix Metropolitan Area at Night\",\"content\":\"<content chunk redacted>\"}]"
            }
        ]
    }
]

Poin utama:

  • content.text adalah array JSON. Ini adalah string tunggal yang terdiri dari dokumen (atau gugus) yang paling relevan yang ditemukan dalam indeks pencarian, mengingat input riwayat kueri dan obrolan. Array ini adalah data dasar atau acuan yang digunakan oleh model penyelesaian percakapan untuk merumuskan respons terhadap pertanyaan pengguna.

    Bagian respons ini terdiri dari 200 gugus atau lebih sedikit, tidak termasuk hasil apa pun yang gagal memenuhi ambang batas minimum skor reranker 2,5.

    String dimulai dengan ID referensi dari gugus (digunakan untuk tujuan kutipan), dan bidang apa pun yang ditentukan dalam konfigurasi semantik indeks target. Dalam contoh ini, asumsikan konfigurasi semantik dalam indeks target memiliki bidang "judul", bidang "istilah", dan bidang "konten".

  • content.type memiliki satu nilai yang valid dalam pratinjau ini: text.

Nota

Properti maxOutputSize pada pangkalan pengetahuan menentukan panjang string.

Meninjau susunan aktivitas

Array aktivitas menghasilkan rencana pencarian, yang membantu Anda melacak operasi yang dilakukan saat mengeksekusi kueri. Ini juga memberikan transparansi operasional sehingga Anda dapat memahami implikasi penagihan dan frekuensi pemanggilan sumber daya.

Output mencakup komponen-komponen berikut.

Section Description
modelQueryPlanning Untuk pangkalan pengetahuan yang menggunakan LLM untuk perencanaan kueri, bagian ini melaporkan jumlah token yang digunakan untuk input, dan jumlah token untuk subkueri.
aktivitas khusus sumber Untuk setiap sumber pengetahuan yang disertakan dalam kueri, laporkan waktu yang berlalu dan argumen mana yang digunakan dalam kueri, termasuk peringkat semantik. Jenis sumber pengetahuan termasuk searchIndex, azureBlob, dan sumber pengetahuan lain yang didukung.
upaya penalaran agenik Untuk setiap aksi pengambilan data, Anda dapat menentukan tingkat dukungan LLM. Gunakan minimal untuk melewati LLM, rendah untuk pemrosesan LLM yang dibatasi, dan sedang untuk pemrosesan LLM penuh.
modelAnswerSynthesis Untuk pangkalan pengetahuan yang menentukan rumusan jawaban, bagian ini melaporkan jumlah token untuk merumuskan jawaban, dan jumlah token output jawaban.

Output melaporkan konsumsi token untuk penalaran agensi selama proses pengambilan pada upaya penalaran pengambilan yang ditentukan.

Output juga mencakup informasi berikut:

  • Subkueri yang dikirim ke pipeline pengambilan data.
  • Kesalahan untuk setiap kegagalan pengambilan, seperti sumber pengetahuan yang tidak dapat diakses.

Berikut ini adalah contoh array aktivitas.

  "activity": [
    {
      "type": "modelQueryPlanning",
      "id": 0,
      "inputTokens": 2302,
      "outputTokens": 109,
      "elapsedMs": 2396
    },
    {
      "type": "searchIndex",
      "id": 1,
      "knowledgeSourceName": "demo-financials-ks",
      "queryTime": "2025-11-04T19:25:23.683Z",
      "count": 26,
      "elapsedMs": 1137,
      "searchIndexArguments": {
        "search": "List of companies in the financial sector according to SEC GICS classification",
        "filter": null,
        "sourceDataFields": [ ],
        "searchFields": [ ],
        "semanticConfigurationName": "en-semantic-config"
      }
    },
    {
      "type": "searchIndex",
      "id": 2,
      "knowledgeSourceName": "demo-healthcare-ks",
      "queryTime": "2025-11-04T19:25:24.186Z",
      "count": 17,
      "elapsedMs": 494,
      "searchIndexArguments": {
        "search": "List of companies in the financial sector according to SEC GICS classification",
        "filter": null,
        "sourceDataFields": [ ],
        "searchFields": [ ],
        "semanticConfigurationName": "en-semantic-config"
      }
    },
    {
      "type": "agenticReasoning",
      "id": 3,
      "retrievalReasoningEffort": {
        "kind": "low"
      },
      "reasoningTokens": 103368
    },
    {
      "type": "modelAnswerSynthesis",
      "id": 4,
      "inputTokens": 5821,
      "outputTokens": 344,
      "elapsedMs": 3837
    }
  ]

Meninjau kumpulan referensi

Array references berasal langsung dari data dasar yang mendasari. Ini termasuk sourceData yang digunakan untuk menghasilkan respons. Ini terdiri dari setiap dokumen yang ditemukan mesin pencarian berbasis agen dan diurutkan secara semantik. Bidang dalam sourceData mencakup sebuah id dan bidang semantik: title, terms, dan content.

id berfungsi sebagai ID referensi untuk item dalam respons tertentu. Ini bukan kunci dokumen dalam indeks pencarian. Anda menggunakannya untuk menambahkan kutipan.

Tujuan dari array ini adalah untuk menyediakan struktur gaya pesan obrolan untuk integrasi yang mudah. Misalnya, jika Anda ingin menserialisasikan hasilnya ke dalam struktur yang berbeda atau Anda memerlukan beberapa manipulasi data terprogram sebelum Anda mengembalikannya kepada pengguna.

Anda juga bisa mendapatkan data terstruktur dari objek data sumber dalam array referensi untuk memanipulasinya sesuai keinginan Anda.

Berikut adalah contoh array referensi.

  "references": [
    {
      "type": "AzureSearchDoc",
      "id": "0",
      "activitySource": 2,
      "docKey": "earth_at_night_508_page_104_verbalized",
      "sourceData": null
    },
    {
      "type": "AzureSearchDoc",
      "id": "1",
      "activitySource": 2,
      "docKey": "earth_at_night_508_page_105_verbalized",
      "sourceData": null
    }
  ]

Nota

Jika Anda mengambil konten dari sumber pengetahuan OneLake atau SharePoint terindeks, atur includeReferenceSourceData ke true pada permintaan ambil untuk mendapatkan URL dokumen sumber dalam kutipan.

Konten terkait

  • Last updated on