Bagikan melalui

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

Di Azure AI Search, pangkalan pengetahuan adalah objek tingkat atas yang mengatur pengambilan agenik. Ini menentukan sumber pengetahuan mana yang akan dikueri dan perilaku default untuk operasi pengambilan. Pada waktu kueri, metode ambil menargetkan pangkalan pengetahuan untuk menjalankan alur pengambilan yang dikonfigurasi.

Anda dapat membuat pangkalan pengetahuan dalam beban kerja Foundry IQ di portal Microsoft Foundry (baru). Anda juga memerlukan pangkalan pengetahuan dalam solusi agenik apa pun yang Anda buat menggunakan API Pencarian Azure AI.

Pangkalan pengetahuan menentukan:

  • Satu atau beberapa sumber pengetahuan yang menunjuk ke konten yang dapat dicari.
  • LLM opsional yang menyediakan kemampuan penalaran untuk perencanaan kueri dan rumusan jawaban.
  • Upaya penalaran pengambilan yang menentukan apakah LLM dipanggil dan mengelola biaya, latensi, dan kualitas.
  • Properti kustom yang mengontrol perutean, pemilihan sumber, format output, dan enkripsi objek.

Setelah membuat pangkalan pengetahuan, Anda dapat memperbarui propertinya kapan saja. Jika pangkalan pengetahuan sedang digunakan, pembaruan akan berlaku pada pengambilan berikutnya.

Penting

2025-11-01-pratinjau mengganti nama "agen pengetahuan" dari pratinjau 2025-08-01 menjadi "pangkalan pengetahuan." Ini adalah perubahan yang mengganggu kompatibilitas. Sebaiknya migrasikan kode yang ada ke API baru sesegera mungkin.

Prasyarat

Model yang didukung

Gunakan salah satu LLM berikut dari Azure OpenAI atau model sumber terbuka yang setara. Untuk instruksi penyebaran, lihat Menyebarkan model Azure OpenAI dengan Microsoft Foundry.

  • gpt-4o
  • gpt-4o-mini
  • gpt-4.1
  • gpt-4.1-nano
  • gpt-4.1-mini
  • gpt-5
  • gpt-5-nano
  • gpt-5-mini

Mengonfigurasi akses

Pencarian Azure AI memerlukan akses ke LLM dari Azure OpenAI. Kami merekomendasikan ID Microsoft Entra untuk autentikasi dan akses berbasis peran untuk otorisasi. Untuk menetapkan peran, Anda harus menjadi Pemilik atau Administrator Akses Pengguna. Jika Anda tidak dapat menggunakan peran, gunakan autentikasi berbasis kunci sebagai gantinya.

  1. Konfigurasikan Azure AI Search untuk menggunakan identitas terkelola.

  2. Pada penyedia model Anda, seperti Model Foundry, tetapkan Pengguna Cognitive Services ke identitas terkelola layanan pencarian Anda. Jika Anda menguji secara lokal, tetapkan peran yang sama ke akun pengguna Anda.

  3. Untuk pengujian lokal, ikuti langkah-langkah di Mulai Cepat: Sambungkan tanpa Kunci untuk masuk ke langganan dan tenant tertentu. Gunakan DefaultAzureCredential alih-alih AzureKeyCredential di setiap permintaan, yang akan terlihat mirip dengan contoh berikut:

    using Azure.Search.Documents.Indexes;
using Azure.Identity;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());

Penting

Cuplikan kode dalam artikel ini menggunakan kunci API. Jika Anda menggunakan autentikasi berbasis peran, perbarui setiap permintaan yang sesuai. Dalam permintaan yang menentukan kedua pendekatan, kunci API lebih diutamakan.

Periksa pangkalan pengetahuan yang ada

Mengetahui tentang pangkalan pengetahuan yang ada sangat membantu untuk menggunakannya kembali atau penamaan objek baru. Setiap agen informasi pratinjau versi 2025-08-01 dikembalikan dalam koleksi basis pengetahuan.

Jalankan kode berikut untuk mencantumkan pangkalan pengetahuan yang ada berdasarkan nama.

// List knowledge bases by name
  using Azure.Search.Documents.Indexes;
  
  var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
  var knowledgeBases = indexClient.GetKnowledgeBasesAsync();
  
  Console.WriteLine("Knowledge Bases:");
  
  await foreach (var kb in knowledgeBases)
  {
      Console.WriteLine($"  - {kb.Name}");
  }

Anda juga dapat mengembalikan satu pangkalan pengetahuan berdasarkan nama untuk meninjau definisi JSON-nya.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge base name to retrieve
string kbNameToGet = "earth-knowledge-base";

// Get a specific knowledge base definition
var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet);
var kb = knowledgeBaseResponse.Value;

// Serialize to JSON for display
string json = JsonSerializer.Serialize(kb, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

JSON berikut adalah contoh pangkalan pengetahuan.

{
  "Name": "earth-knowledge-base",
  "KnowledgeSources": [
    {
      "Name": "earth-knowledge-source"
    }
  ],
  "Models": [
    {}
  ],
  "RetrievalReasoningEffort": {},
  "OutputMode": {},
  "ETag": "\u00220x8DE278629D782B3\u0022",
  "EncryptionKey": null,
  "Description": null,
  "RetrievalInstructions": null,
  "AnswerInstructions": null
}

Membuat basis pengetahuan

Pangkalan pengetahuan mendorong alur pengambilan agenik. Dalam kode aplikasi, agen atau chatbot lain memanggilnya.

Pangkalan pengetahuan menghubungkan sumber pengetahuan (konten yang dapat dicari) ke penyebaran LLM dari Azure OpenAI. Properti pada LLM membuat koneksi, sementara properti pada sumber pengetahuan menetapkan default yang menginformasikan eksekusi kueri dan respons.

Jalankan kode berikut untuk membuat pangkalan pengetahuan.

using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Create a knowledge base
var knowledgeBase = new KnowledgeBase(
    name: knowledgeBaseName,
    knowledgeSources: new KnowledgeSourceReference[] { new KnowledgeSourceReference(knowledgeSourceName) }
)
{
    RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort(),
    OutputMode = KnowledgeRetrievalOutputMode.AnswerSynthesis,
    Models = { model }
};
await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);
Console.WriteLine($"Knowledge base '{knowledgeBaseName}' created or updated successfully.");

# Create a knowledge base
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
using Azure;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

var aoaiParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiGptDeployment,
    ModelName = aoaiGptModel
};

var knowledgeBase = new KnowledgeBase(
    name: "my-kb",
    knowledgeSources: new KnowledgeSourceReference[] 
    { 
        new KnowledgeSourceReference("hotels-sample-knowledge-source"),
        new KnowledgeSourceReference("earth-knowledge-source")
    }
)
{
    Description = "This knowledge base handles questions directed at two unrelated sample indexes.",
    RetrievalInstructions = "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    AnswerInstructions = "Provide a two sentence concise and informative answer based on the retrieved documents.",
    OutputMode = KnowledgeRetrievalOutputMode.AnswerSynthesis,
    Models = { new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: aoaiParams) },
    RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort()
};

await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);
Console.WriteLine($"Knowledge base '{knowledgeBase.Name}' created or updated successfully.");

Properti pangkalan pengetahuan

Teruskan properti berikut untuk membuat pangkalan pengetahuan.

Nama Description Tipe Diperlukan
name Nama basis pengetahuan. Ini harus unik dalam koleksi pangkalan pengetahuan dan mengikuti panduan penamaan untuk objek di Azure AI Search. String Yes
knowledgeSources Satu atau beberapa sumber pengetahuan yang didukung. Array Yes
Description Deskripsi pangkalan pengetahuan. LLM menggunakan deskripsi untuk menginformasikan perencanaan kueri. String Tidak.
RetrievalInstructions Permintaan agar LLM menentukan apakah sumber pengetahuan harus berada dalam cakupan kueri. Sertakan perintah ini saat Anda memiliki beberapa sumber pengetahuan. Bidang ini memengaruhi pemilihan sumber pengetahuan dan rumusan kueri. Misalnya, instruksi dapat menambahkan informasi atau memprioritaskan sumber pengetahuan. Instruksi diteruskan langsung ke LLM, yang berarti dimungkinkan untuk memberikan instruksi yang melanggar rencana kueri, seperti instruksi yang mengakibatkan mengabaikan sumber pengetahuan yang penting. String Yes
AnswerInstructions Instruksi kustom untuk membentuk jawaban yang disintesis. Defaultnya adalah null. Untuk informasi selengkapnya, lihat Menggunakan sintesis jawaban untuk respons yang didukung kutipan. String Yes
OutputMode Nilai yang valid adalah AnswerSynthesis untuk jawaban yang diformulasikan oleh LLM atau ExtractedData untuk hasil pencarian lengkap yang dapat Anda teruskan ke LLM sebagai langkah berikutnya. String Yes
Models Koneksi ke LLM yang didukung yang digunakan dalam formulasi jawaban atau perencanaan kueri. Dalam pratinjau ini, Models hanya boleh berisi satu model, dan penyedia model harus Azure OpenAI. Dapatkan informasi model dari portal Foundry atau permintaan baris perintah. Berikan parameter dengan menggunakan kelas KnowledgeBaseAzureOpenAIModel. Anda dapat menggunakan kontrol akses berbasis peran alih-alih kunci API untuk koneksi Azure AI Search ke model. Untuk informasi selengkapnya, lihat Cara menyebarkan model Azure OpenAI dengan Foundry. Objek Tidak.
RetrievalReasoningEffort Menentukan tingkat pemrosesan kueri terkait LLM. Nilai yang valid adalah minimal, low (default), dan medium. Untuk informasi selengkapnya, lihat Mengatur usaha penalaran pengambilan data. Objek Tidak.

Meminta pangkalan pengetahuan

Siapkan instruksi dan pesan untuk dikirim ke LLM.

string instructions = @"
Use the earth at night index to answer the question. If you can't find relevant content, say you don't know.
";

var messages = new List<Dictionary<string, string>>
{
    new Dictionary<string, string>
    {
        { "role", "system" },
        { "content", instructions }
    }
};

retrieve Panggil tindakan pada pangkalan pengetahuan untuk memverifikasi koneksi LLM dan mengembalikan hasil. Untuk informasi selengkapnya tentang retrieve skema permintaan dan respons, lihat Mengambil data menggunakan pangkalan pengetahuan di Azure AI Search.

Ganti "Di mana laut terlihat hijau?" dengan string kueri yang valid untuk sumber pengetahuan Anda.

using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;

var baseClient = new KnowledgeBaseRetrievalClient(
    endpoint: new Uri(searchEndpoint),
    knowledgeBaseName: knowledgeBaseName,
    tokenCredential: new DefaultAzureCredential()
);

messages.Add(new Dictionary<string, string>
{
    { "role", "user" },
    { "content", @"Where does the ocean look green?" }
});

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
foreach (Dictionary<string, string> message in messages) {
    if (message["role"] != "system") {
        retrievalRequest.Messages.Add(new KnowledgeBaseMessage(content: new[] { new KnowledgeBaseMessageTextContent(message["content"]) }) { Role = message["role"] });
    }
}
retrievalRequest.RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort();
var retrievalResult = await baseClient.RetrieveAsync(retrievalRequest);

messages.Add(new Dictionary<string, string>
{
    { "role", "assistant" },
    { "content", (retrievalResult.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent).Text }
});

(retrievalResult.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent).Text 

// Print the response, activity, and references
Console.WriteLine("Response:");
Console.WriteLine((retrievalResult.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent)!.Text);

Poin-poin penting:

  • KnowledgeBaseRetrievalRequest adalah kontrak input untuk permintaan pengambilan.

  • RetrievalReasoningEffort diperlukan. Mengaturnya ke minimal mengecualikan LLM dari alur kueri dan hanya intent yang digunakan untuk input kueri. Defaultnya adalah low dan mendukung perencanaan kueri berbasis LLM dan menjawab sintesis dengan pesan dan konteks.

  • knowledgeSourceParams digunakan untuk menimpa parameter default saat melakukan kueri.

Respons terhadap kueri sampel mungkin terlihat seperti contoh berikut:

  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica’s Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
        }
      ]
    }
  ]

Menghapus pangkalan pengetahuan

Jika Anda tidak lagi memerlukan pangkalan pengetahuan atau perlu membangunnya kembali di layanan pencarian Anda, gunakan permintaan ini untuk menghapus objek.

using Azure.Search.Documents.Indexes;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
System.Console.WriteLine($"Knowledge base '{knowledgeBaseName}' deleted successfully.");

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.

Di Azure AI Search, pangkalan pengetahuan adalah objek tingkat atas yang mengatur pengambilan agenik. Ini menentukan sumber pengetahuan mana yang akan dikueri dan perilaku default untuk operasi pengambilan. Pada waktu kueri, metode ambil menargetkan pangkalan pengetahuan untuk menjalankan alur pengambilan yang dikonfigurasi.

Anda dapat membuat pangkalan pengetahuan dalam beban kerja Foundry IQ di portal Microsoft Foundry (baru). Anda juga memerlukan pangkalan pengetahuan dalam solusi agenik apa pun yang Anda buat menggunakan API Pencarian Azure AI.

Pangkalan pengetahuan menentukan:

  • Satu atau beberapa sumber pengetahuan yang menunjuk ke konten yang dapat dicari.
  • LLM opsional yang menyediakan kemampuan penalaran untuk perencanaan kueri dan rumusan jawaban.
  • Upaya penalaran pengambilan yang menentukan apakah LLM dipanggil dan mengelola biaya, latensi, dan kualitas.
  • Properti kustom yang mengontrol perutean, pemilihan sumber, format output, dan enkripsi objek.

Setelah membuat pangkalan pengetahuan, Anda dapat memperbarui propertinya kapan saja. Jika pangkalan pengetahuan sedang digunakan, pembaruan akan berlaku pada pengambilan berikutnya.

Penting

2025-11-01-pratinjau mengganti nama "agen pengetahuan" dari pratinjau 2025-08-01 menjadi "pangkalan pengetahuan." Ini adalah perubahan yang mengganggu kompatibilitas. Sebaiknya migrasikan kode yang ada ke API baru sesegera mungkin.

Prasyarat

Model yang didukung

Gunakan salah satu LLM berikut dari Azure OpenAI atau model sumber terbuka yang setara. Untuk instruksi penyebaran, lihat Menyebarkan model Azure OpenAI dengan Microsoft Foundry.

  • gpt-4o
  • gpt-4o-mini
  • gpt-4.1
  • gpt-4.1-nano
  • gpt-4.1-mini
  • gpt-5
  • gpt-5-nano
  • gpt-5-mini

Mengonfigurasi akses

Pencarian Azure AI memerlukan akses ke LLM dari Azure OpenAI. Kami merekomendasikan ID Microsoft Entra untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika peran tidak memungkinkan, gunakan autentikasi berbasis kunci sebagai gantinya.

  1. Konfigurasikan Azure AI Search untuk menggunakan identitas terkelola.

  2. Pada penyedia model Anda, seperti Model Foundry, tetapkan Pengguna Cognitive Services ke identitas terkelola layanan pencarian Anda. Jika Anda menguji secara lokal, tetapkan peran yang sama ke akun pengguna Anda.

  3. Untuk pengujian lokal, ikuti langkah-langkah di Mulai Cepat: Sambungkan tanpa Kunci untuk masuk ke langganan dan tenant tertentu. Gunakan DefaultAzureCredential alih-alih AzureKeyCredential di setiap permintaan, yang akan terlihat mirip dengan contoh berikut:

    # Authenticate using roles
from azure.identity import DefaultAzureCredential
index_client = SearchIndexClient(endpoint = "search_url", credential = DefaultAzureCredential())

Penting

Cuplikan kode dalam artikel ini menggunakan kunci API. Jika Anda menggunakan autentikasi berbasis peran, perbarui setiap permintaan yang sesuai. Dalam permintaan yang menentukan kedua pendekatan, kunci API lebih diutamakan.

Periksa pangkalan pengetahuan yang ada

Mengetahui tentang pangkalan pengetahuan yang ada sangat membantu untuk menggunakan kembali atau memberi nama objek baru. Setiap agen informasi pratinjau versi 2025-08-01 dikembalikan dalam koleksi basis pengetahuan.

Jalankan kode berikut untuk mencantumkan pangkalan pengetahuan yang ada berdasarkan nama.

# List knowledge bases by name
import requests
import json

endpoint = "{search_url}/knowledgebases"
params = {"api-version": "2025-11-01-preview", "$select": "name"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

Anda juga dapat mengembalikan satu pangkalan pengetahuan berdasarkan nama untuk meninjau definisi JSON-nya.

# Get a knowledge base definition
import requests
import json

endpoint = "{search_url}/knowledgebases/{knowledge_base_name}"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

JSON berikut adalah contoh respons untuk pangkalan pengetahuan.

{
  "name": "my-kb",
  "description": "A sample knowledge base.",
  "retrievalInstructions": null,
  "answerInstructions": null,
  "outputMode": null,
  "knowledgeSources": [
    {
      "name": "my-blob-ks"
    }
  ],
  "models": [],
  "encryptionKey": null,
  "retrievalReasoningEffort": {
    "kind": "low"
  }
}

Membuat basis pengetahuan

Pangkalan pengetahuan mendorong alur pengambilan agenik. Dalam kode aplikasi, agen atau chatbot lain memanggilnya.

Pangkalan pengetahuan menghubungkan sumber pengetahuan (konten yang dapat dicari) ke penyebaran LLM dari Azure OpenAI. Properti pada LLM membuat koneksi, sementara properti pada sumber pengetahuan menetapkan default yang menginformasikan eksekusi kueri dan respons.

Jalankan kode berikut untuk membuat pangkalan pengetahuan.

# Create a knowledge base
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import KnowledgeBase, KnowledgeBaseAzureOpenAIModel, KnowledgeSourceReference, AzureOpenAIVectorizerParameters, KnowledgeRetrievalOutputMode, KnowledgeRetrievalLowReasoningEffort

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

aoai_params = AzureOpenAIVectorizerParameters(
    resource_url = "aoai_endpoint",
    api_key="aoai_api_key",
    deployment_name = "aoai_gpt_deployment",
    model_name = "aoai_gpt_model",
)

knowledge_base = KnowledgeBase(
    name = "my-kb",
    description = "This knowledge base handles questions directed at two unrelated sample indexes.",
    retrieval_instructions = "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    answer_instructions = "Provide a two sentence concise and informative answer based on the retrieved documents.",
    output_mode = KnowledgeRetrievalOutputMode.ANSWER_SYNTHESIS,
    knowledge_sources = [
        KnowledgeSourceReference(name = "hotels-ks"),
        KnowledgeSourceReference(name = "earth-at-night-ks"),
    ],
    models = [KnowledgeBaseAzureOpenAIModel(azure_open_ai_parameters = aoai_params)],
    encryption_key = None,
    retrieval_reasoning_effort = KnowledgeRetrievalLowReasoningEffort,
)

index_client.create_or_update_knowledge_base(knowledge_base)
print(f"Knowledge base '{knowledge_base.name}' created or updated successfully.")

Properti pangkalan pengetahuan

Teruskan properti berikut untuk membuat pangkalan pengetahuan.

Nama Description Tipe Diperlukan
name Nama basis pengetahuan. Ini harus unik dalam koleksi pangkalan pengetahuan dan mengikuti panduan penamaan untuk objek di Azure AI Search. String Yes
description Deskripsi pangkalan pengetahuan. LLM menggunakan deskripsi untuk menginformasikan perencanaan kueri. String Tidak.
retrieval_instructions Permintaan agar LLM menentukan apakah sumber pengetahuan harus berada dalam cakupan kueri. Sertakan perintah ini saat Anda memiliki beberapa sumber pengetahuan. Bidang ini memengaruhi pemilihan sumber pengetahuan dan rumusan kueri. Misalnya, instruksi dapat menambahkan informasi atau memprioritaskan sumber pengetahuan. Kirim instruksi langsung kepada LLM. Dimungkinkan untuk memberikan instruksi yang merusak perencanaan kueri, seperti instruksi yang mengakibatkan melewati sumber pengetahuan penting. String Yes
answer_instructions Instruksi kustom untuk membentuk jawaban yang disintesis. Defaultnya adalah null. Untuk informasi selengkapnya, lihat Menggunakan sintesis jawaban untuk respons yang didukung kutipan. String Yes
output_mode Nilai yang valid adalah answer_synthesis untuk jawaban yang diformulasikan oleh LLM atau extracted_data untuk hasil pencarian lengkap yang dapat Anda teruskan ke LLM sebagai langkah berikutnya. String Yes
knowledge_sources Satu atau beberapa sumber pengetahuan yang didukung. Array Yes
models Koneksi ke LLM yang didukung yang digunakan dalam formulasi jawaban atau perencanaan kueri. Dalam pratinjau ini, models hanya boleh berisi satu model, dan penyedia model harus Azure OpenAI. Dapatkan informasi model dari portal Foundry atau permintaan baris perintah. Anda dapat menggunakan kontrol akses berbasis peran alih-alih kunci API untuk koneksi Azure AI Search ke model. Untuk informasi selengkapnya, lihat Cara menyebarkan model Azure OpenAI dengan Foundry. Objek Tidak.
encryption_key Kunci yang dikelola pelanggan untuk mengenkripsi informasi sensitif di pangkalan pengetahuan dan objek yang dihasilkan. Objek Tidak.
retrieval_reasoning_effort Menentukan tingkat pemrosesan kueri terkait LLM. Nilai yang valid adalah minimal, low (default), dan medium. Untuk informasi selengkapnya, lihat Mengatur usaha penalaran pengambilan data. Objek Tidak.

Meminta pangkalan pengetahuan

retrieve Panggil tindakan pada pangkalan pengetahuan untuk memverifikasi koneksi LLM dan mengembalikan hasil. Untuk informasi selengkapnya tentang retrieve skema permintaan dan respons, lihat Mengambil data menggunakan pangkalan pengetahuan di Azure AI Search.

Ganti "Di mana laut terlihat hijau?" dengan string kueri yang valid untuk sumber pengetahuan Anda.

# Send grounding request
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import KnowledgeBaseMessage, KnowledgeBaseMessageTextContent, KnowledgeBaseRetrievalRequest, SearchIndexKnowledgeSourceParams

kb_client = KnowledgeBaseRetrievalClient(endpoint = "search_url", knowledge_base_name = "knowledge_base_name", credential = AzureKeyCredential("api_key"))

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role = "assistant",
            content = [KnowledgeBaseMessageTextContent(text = "Use the earth at night index to answer the question. If you can't find relevant content, say you don't know.")]
        ),
        KnowledgeBaseMessage(
            role = "user",
            content = [KnowledgeBaseMessageTextContent(text = "Where does the ocean look green?")]
        ),
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name = "earth-at-night-ks",
            include_references = True,
            include_reference_source_data = True,
            always_query_source = False,
        )
    ],
    include_activity = True,
)

result = kb_client.retrieve(request)
print(result.response[0].content[0].text)

Poin-poin penting:

  • messages diperlukan, tetapi Anda dapat menjalankan contoh ini dengan menggunakan peran user yang menyediakan kueri saja.

  • knowledge_source_params menentukan satu atau beberapa target kueri. Untuk setiap sumber pengetahuan, Anda dapat menentukan berapa banyak informasi yang akan disertakan dalam output.

Respons terhadap kueri sampel mungkin terlihat seperti contoh berikut:

  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica’s Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
        }
      ]
    }
  ]

Menghapus pangkalan pengetahuan

Jika Anda tidak lagi memerlukan pangkalan pengetahuan atau perlu membangunnya kembali di layanan pencarian Anda, gunakan permintaan ini untuk menghapus objek.

# Delete a knowledge base
from azure.core.credentials import AzureKeyCredential 
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
index_client.delete_knowledge_base("knowledge_base_name")
print(f"Knowledge base deleted successfully.")

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.

Di Azure AI Search, pangkalan pengetahuan adalah objek tingkat atas yang mengatur pengambilan agenik. Ini menentukan sumber pengetahuan mana yang akan dikueri dan perilaku default untuk operasi pengambilan. Pada waktu kueri, metode ambil menargetkan pangkalan pengetahuan untuk menjalankan alur pengambilan yang dikonfigurasi.

Anda dapat membuat pangkalan pengetahuan dalam beban kerja Foundry IQ di portal Microsoft Foundry (baru). Anda juga memerlukan pangkalan pengetahuan dalam solusi agenik apa pun yang Anda buat menggunakan API Pencarian Azure AI.

Pangkalan pengetahuan menentukan:

  • Satu atau beberapa sumber pengetahuan yang menunjuk ke konten yang dapat dicari.
  • LLM opsional yang menyediakan kemampuan penalaran untuk perencanaan kueri dan rumusan jawaban.
  • Upaya penalaran pengambilan yang menentukan apakah LLM dipanggil dan mengelola biaya, latensi, dan kualitas.
  • Properti kustom yang mengontrol perutean, pemilihan sumber, format output, dan enkripsi objek.

Setelah membuat pangkalan pengetahuan, Anda dapat memperbarui propertinya kapan saja. Jika pangkalan pengetahuan sedang digunakan, pembaruan akan berlaku pada pengambilan berikutnya.

Penting

2025-11-01-pratinjau mengganti nama "agen pengetahuan" dari pratinjau 2025-08-01 menjadi "pangkalan pengetahuan." Ini adalah perubahan yang mengganggu kompatibilitas. Sebaiknya migrasikan kode yang ada ke API baru sesegera mungkin.

Prasyarat

Model yang didukung

Gunakan salah satu LLM berikut dari Azure OpenAI atau model sumber terbuka yang setara. Untuk instruksi penyebaran, lihat Menyebarkan model Azure OpenAI dengan Microsoft Foundry.

  • gpt-4o
  • gpt-4o-mini
  • gpt-4.1
  • gpt-4.1-nano
  • gpt-4.1-mini
  • gpt-5
  • gpt-5-nano
  • gpt-5-mini

Mengonfigurasi akses

Pencarian Azure AI memerlukan akses ke LLM dari Azure OpenAI. Kami merekomendasikan ID Microsoft Entra untuk autentikasi dan akses berbasis peran untuk otorisasi. Untuk menetapkan peran, Anda harus menjadi Pemilik atau Administrator Akses Pengguna. Jika Anda tidak dapat menggunakan peran, gunakan autentikasi berbasis kunci sebagai gantinya.

  1. Konfigurasikan Azure AI Search untuk menggunakan identitas terkelola.

  2. Pada penyedia model Anda, seperti Model Foundry, tetapkan Pengguna Cognitive Services ke identitas terkelola layanan pencarian Anda. Jika Anda menguji secara lokal, tetapkan peran yang sama ke akun pengguna Anda.

  3. Untuk pengujian lokal, ikuti langkah-langkah di Mulai Cepat: Sambungkan tanpa kunci untuk mendapatkan token akses pribadi untuk langganan dan penyewa tertentu. Tentukan token akses Anda di setiap permintaan, yang akan terlihat mirip dengan contoh berikut:

    # List indexes using roles
GET https://{{search-url}}/indexes?api-version=2025-11-01-preview
Content-Type: application/json
Authorization: Bearer {{access-token}}

Penting

Cuplikan kode dalam artikel ini menggunakan kunci API. Jika Anda menggunakan autentikasi berbasis peran, perbarui setiap permintaan yang sesuai. Dalam permintaan yang menentukan kedua pendekatan, kunci API lebih diutamakan.

Periksa pangkalan pengetahuan yang ada

Pangkalan pengetahuan adalah objek tingkat atas yang dapat digunakan kembali. Mengetahui tentang pangkalan pengetahuan yang ada sangat membantu untuk menggunakan kembali atau memberi nama objek baru. Setiap agen informasi pratinjau versi 2025-08-01 dikembalikan dalam koleksi basis pengetahuan.

Gunakan Pangkalan Pengetahuan - Daftar (REST API) untuk mencantumkan pangkalan pengetahuan berdasarkan nama dan jenis.

# List knowledge bases
GET {{search-url}}/knowledgebases?api-version=2025-11-01-preview&$select=name
Content-Type: application/json
api-key: {{search-api-key}}

Anda juga dapat mengembalikan satu pangkalan pengetahuan berdasarkan nama untuk meninjau definisi JSON-nya.

# Get knowledge base
GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

JSON berikut adalah contoh respons untuk pangkalan pengetahuan.

{
  "name": "my-kb",
  "description": "A sample knowledge base.",
  "retrievalInstructions": null,
  "answerInstructions": null,
  "outputMode": null,
  "knowledgeSources": [
    {
      "name": "my-blob-ks"
    }
  ],
  "models": [],
  "encryptionKey": null,
  "retrievalReasoningEffort": {
    "kind": "low"
  }
}

Membuat basis pengetahuan

Pangkalan pengetahuan mendorong alur pengambilan agenik. Dalam kode aplikasi, agen atau chatbot lain memanggilnya.

Pangkalan pengetahuan menghubungkan sumber pengetahuan (konten yang dapat dicari) ke penyebaran LLM dari Azure OpenAI. Properti pada LLM membuat koneksi, sementara properti pada kumpulan sumber pengetahuan mengatur default yang memandu eksekusi kueri dan respons.

Gunakan Pangkalan Pengetahuan - Buat atau Perbarui (REST API) untuk merumuskan permintaan.

# Create a knowledge base
PUT {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

{
    "name" : "my-kb",
    "description": "This knowledge base handles questions directed at two unrelated sample indexes.",
    "retrievalInstructions": "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    "answerInstructions": null,
    "outputMode": "answerSynthesis",
    "knowledgeSources": [
        {
            "name": "hotels-ks"
        },
        {
            "name": "earth-at-night-ks"
        }
    ],
    "models" : [ 
        {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "{{model-provider-url}}",
                "apiKey": "{{model-api-key}}",
                "deploymentId": "gpt-4.1-mini",
                "modelName": "gpt-4.1-mini"
            }
        }
    ],
    "encryptionKey": null,
    "retrievalReasoningEffort": {
        "kind": "low"
    }
}

Properti pangkalan pengetahuan

Teruskan properti berikut untuk membuat pangkalan pengetahuan.

Nama Description Tipe Diperlukan
name Nama basis pengetahuan. Ini harus unik dalam koleksi pangkalan pengetahuan dan mengikuti panduan penamaan untuk objek di Azure AI Search. String Yes
description Deskripsi pangkalan pengetahuan. LLM menggunakan deskripsi untuk menginformasikan perencanaan kueri. String Tidak.
retrievalInstructions Permintaan agar LLM menentukan apakah sumber pengetahuan harus berada dalam cakupan kueri. Sertakan perintah ini saat Anda memiliki beberapa sumber pengetahuan. Bidang ini memengaruhi pemilihan sumber pengetahuan dan rumusan kueri. Misalnya, instruksi dapat menambahkan informasi atau memprioritaskan sumber pengetahuan. Anda meneruskan instruksi langsung ke LLM, yang berarti dimungkinkan untuk memberikan instruksi yang melanggar perencanaan pencarian, seperti instruksi yang mengakibatkan mengabaikan sumber pengetahuan penting. String Yes
answerInstructions Instruksi kustom untuk membentuk jawaban yang disintesis. Defaultnya adalah null. Untuk informasi selengkapnya, lihat Menggunakan sintesis jawaban untuk respons yang didukung kutipan. String Yes
outputMode Nilai yang valid adalah answerSynthesis untuk jawaban yang diformulasikan oleh LLM atau extractedData untuk hasil pencarian lengkap yang dapat Anda teruskan ke LLM sebagai langkah berikutnya. String Yes
knowledgeSources Satu atau beberapa sumber pengetahuan yang didukung. Array Yes
models Koneksi ke LLM yang didukung yang digunakan dalam formulasi jawaban atau perencanaan kueri. Dalam pratinjau ini, models hanya boleh berisi satu model, dan penyedia model harus Azure OpenAI. Dapatkan informasi model dari portal Foundry atau permintaan baris perintah. Anda dapat menggunakan kontrol akses berbasis peran alih-alih kunci API untuk koneksi Azure AI Search ke model. Untuk informasi selengkapnya, lihat Cara menyebarkan model Azure OpenAI dengan Foundry. Objek Tidak.
encryptionKey Kunci yang dikelola pelanggan untuk mengenkripsi informasi sensitif di pangkalan pengetahuan dan objek yang dihasilkan. Objek Tidak.
retrievalReasoningEffort.kind Menentukan tingkat pemrosesan kueri terkait LLM. Nilai yang valid adalah minimal, low (default), dan medium. Untuk informasi selengkapnya, lihat Mengatur usaha penalaran pengambilan data. Objek Tidak.

Meminta pangkalan pengetahuan

retrieve Panggil tindakan pada pangkalan pengetahuan untuk memverifikasi koneksi LLM dan mengembalikan hasil. Untuk informasi selengkapnya tentang retrieve skema permintaan dan respons, lihat Mengambil data menggunakan pangkalan pengetahuan di Azure AI Search.

Gunakan Knowledge Retrieval - Retrieve (REST API) untuk merumuskan permintaan. Ganti "Di mana laut terlihat hijau?" dengan string kueri yang valid untuk sumber pengetahuan Anda.

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

{
    "messages" : [
        { "role" : "assistant",
                "content" : [
                  { "type" : "text", "text" : "Use the earth at night index to answer the question. If you can't find relevant content, say you don't know." }
                ]
        },
        {
            "role" : "user",
            "content" : [
                {
                    "text" : "Where does the ocean look green?",
                    "type" : "text"
                }
            ]
        }
    ],
    "includeActivity": true,
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "earth-at-night-ks",
            "kind": "searchIndex",
            "includeReferences": true,
            "includeReferenceSourceData": true,
            "alwaysQuerySource": false
        }
  ]
}

Poin-poin penting:

  • messages diperlukan, tetapi Anda dapat menjalankan contoh ini dengan menggunakan peran user yang menyediakan kueri saja.

  • knowledgeSourceParams menentukan satu atau beberapa target kueri. Untuk setiap sumber pengetahuan, Anda dapat menentukan berapa banyak informasi yang akan disertakan dalam output.

Respons terhadap kueri sampel mungkin terlihat seperti contoh berikut:

  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica’s Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
        }
      ]
    }
  ]

Menghapus pangkalan pengetahuan

Jika Anda tidak lagi memerlukan pangkalan pengetahuan atau perlu membangunnya kembali di layanan pencarian Anda, gunakan permintaan ini untuk menghapus objek.

# Delete a knowledge base
DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
api-key: {{search-api-key}}

Konten terkait

  • Last updated on