Knowledge Retrieval - Retrieve

Layanan:: Search Service

Versi API:: 2025-08-01-preview

KnowledgeAgent mengambil data yang relevan dari penyimpanan pendukung.

POST {endpoint}/agents('{agentName}')/retrieve?api-version=2025-08-01-preview

Parameter URI

Nama	Dalam	Diperlukan	Jenis	Deskripsi
agentName	path	True	string	Nama agen.
endpoint	path	True	string (url)	URL titik akhir layanan pencarian.
api-version	query	True	string	Versi API Klien.

Header Permintaan

Nama	Diperlukan	Jenis	Deskripsi
x-ms-client-request-id		string (uuid)	ID pelacakan yang dikirim dengan permintaan untuk membantu penelusuran kesalahan.
x-ms-query-source-authorization		string	Token yang mengidentifikasi pengguna tempat kueri sedang dijalankan. Token ini digunakan untuk menegakkan pembatasan keamanan pada dokumen.

Isi Permintaan

Nama	Diperlukan	Jenis	Deskripsi
messages	True	KnowledgeAgentMessage[]	Objek gaya pesan bahasa alami.
knowledgeSourceParams		KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]

Respons

Nama	Jenis	Deskripsi
200 OK	KnowledgeAgentRetrievalResponse	Respons pengambilan berhasil dikembalikan.
Other Status Codes	ErrorResponse	Respons kesalahan.

Contoh

KnowledgeAgentRetrieve

Permintaan sampel

HTTP

POST https://previewexampleservice.search.windows.net/agents('agent-preview-test')/retrieve?api-version=2025-08-01-preview



{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "text": "hello world",
          "type": "text"
        }
      ]
    }
  ],
  "knowledgeSourceParams": [
    {
      "filterAddOn": "foo eq bar",
      "knowledgeSourceName": "ks-preview-test",
      "kind": "searchIndex"
    }
  ]
}

Respon sampel

Kode status:: 200

{
  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "[{...}]"
        }
      ]
    }
  ],
  "activity": [
    {
      "type": "modelQueryPlanning",
      "id": 0,
      "inputTokens": 11,
      "outputTokens": 22,
      "elapsedMs": 10
    },
    {
      "type": "searchIndex",
      "id": 1,
      "knowledgeSourceName": "ks-preview-test",
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234,
      "searchIndexArguments": {
        "search": "hello world",
        "filter": "foo eq bar"
      }
    },
    {
      "type": "searchIndex",
      "id": 2,
      "knowledgeSourceName": "ks-preview-test",
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234,
      "searchIndexArguments": {
        "search": "hello world two",
        "filter": "foo eq bar"
      }
    },
    {
      "type": "semanticReranker",
      "id": 3,
      "inputTokens": 74,
      "elapsedMs": 0
    }
  ],
  "references": [
    {
      "type": "searchIndex",
      "id": "83dd7d40",
      "activitySource": 1,
      "sourceData": {
        "id": "myDocKey1",
        "title": "high_doc",
        "content": "hello world"
      },
      "rerankerScore": 3.5,
      "docKey": "myDocKey1"
    },
    {
      "type": "searchIndex",
      "id": "83dd7d41",
      "activitySource": 1,
      "sourceData": {
        "id": "myDocKey2",
        "title": "low_doc",
        "content": "goodbye world"
      },
      "rerankerScore": 2.7,
      "docKey": "myDocKey2"
    }
  ]
}

Definisi

Nama	Deskripsi
ErrorAdditionalInfo	Info tambahan kesalahan manajemen sumber daya.
ErrorDetail	Detail kesalahan.
ErrorResponse	Tanggapan kesalahan
Image
KnowledgeAgentAzureBlobActivityArguments	Mewakili argumen yang digunakan aktivitas pengambilan blob Azure.
KnowledgeAgentAzureBlobActivityRecord	Mewakili rekaman aktivitas pengambilan blob Azure.
KnowledgeAgentAzureBlobReference	Mewakili referensi dokumen Azure Blob Storage.
KnowledgeAgentMessage	Objek gaya pesan bahasa alami.
KnowledgeAgentMessageContentType	Jenis konten pesan.
KnowledgeAgentMessageImageContent	Jenis pesan teks.
KnowledgeAgentMessageTextContent	Jenis pesan teks.
KnowledgeAgentModelAnswerSynthesisActivityRecord	Mewakili rekaman aktivitas sintesis jawaban LLM.
KnowledgeAgentModelQueryPlanningActivityRecord	Mewakili rekaman aktivitas perencanaan kueri LLM.
KnowledgeAgentRetrievalRequest	Kontrak input untuk permintaan pengambilan.
KnowledgeAgentRetrievalResponse	Kontrak keluaran untuk respons pengambilan.
KnowledgeAgentSearchIndexActivityArguments	Mewakili argumen yang digunakan untuk menjalankan aktivitas pengambilan indeks pencarian.
KnowledgeAgentSearchIndexActivityRecord	Mewakili rekaman aktivitas pengambilan indeks pencarian.
KnowledgeAgentSearchIndexReference	Mewakili referensi dokumen Azure Search.
KnowledgeAgentSemanticRerankerActivityRecord	Mewakili rekaman aktivitas peringkat semantik.
KnowledgeSourceKind	Jenis sumber pengetahuan.
SearchIndexKnowledgeSourceParams	Menentukan parameter runtime untuk sumber pengetahuan indeks pencarian

ErrorAdditionalInfo

Objek

Info tambahan kesalahan manajemen sumber daya.

Nama	Jenis	Deskripsi
info	object	Info tambahan.
type	string	Jenis info tambahan.

ErrorDetail

Objek

Detail kesalahan.

Nama	Jenis	Deskripsi
additionalInfo	ErrorAdditionalInfo[]	Info tambahan kesalahan.
code	string	Kode kesalahan.
details	ErrorDetail[]	Detail kesalahan.
message	string	Pesan kesalahan.
target	string	Target kesalahan.

ErrorResponse

Objek

Tanggapan kesalahan

Nama	Jenis	Deskripsi
error	ErrorDetail	Objek kesalahan.

Image

Objek

Nama	Jenis	Deskripsi
url	string (uri)	Url gambar.

KnowledgeAgentAzureBlobActivityArguments

Objek

Mewakili argumen yang digunakan aktivitas pengambilan blob Azure.

Nama	Jenis	Deskripsi
search	string	String pencarian yang digunakan untuk mengkueri konten blob.

KnowledgeAgentAzureBlobActivityRecord

Objek

Mewakili rekaman aktivitas pengambilan blob Azure.

Nama	Jenis	Deskripsi
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	Argumen blob azure untuk aktivitas pengambilan.
count	integer (int32)	Jumlah dokumen yang diambil yang cukup relevan untuk melewati ambang batas reranker.
elapsedMs	integer (int32)	Waktu yang berlalu dalam milidetik untuk aktivitas pengambilan.
id	integer (int32)	ID rekaman aktivitas.
knowledgeSourceName	string	Sumber pengetahuan untuk aktivitas pengambilan.
queryTime	string (date-time)	Waktu kueri untuk aktivitas pengambilan ini.
type	string: azureBlob	Jenis rekaman aktivitas.

KnowledgeAgentAzureBlobReference

Objek

Mewakili referensi dokumen Azure Blob Storage.

Nama	Jenis	Deskripsi
activitySource	integer (int32)	ID aktivitas sumber untuk referensi.
blobUrl	string	URL blob untuk referensi.
id	string	ID referensi.
rerankerScore	number (float)	Skor reranker untuk referensi dokumen.
sourceData	object
type	string: azureBlob	Jenis referensi.

KnowledgeAgentMessage

Objek

Objek gaya pesan bahasa alami.

Nama	Jenis	Deskripsi
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	Menentukan jenis konten pesan.
role	string	Peran respons alat.

KnowledgeAgentMessageContentType

Enumerasi

Jenis konten pesan.

Nilai	Deskripsi
text	Jenis konten pesan teks.
image	Jenis konten pesan gambar.

KnowledgeAgentMessageImageContent

Objek

Jenis pesan teks.

Nama	Jenis	Deskripsi
image	Image
type	string: image	Jenis pesan

KnowledgeAgentMessageTextContent

Objek

Jenis pesan teks.

Nama	Jenis	Deskripsi
text	string
type	string: text	Jenis pesan

KnowledgeAgentModelAnswerSynthesisActivityRecord

Objek

Mewakili rekaman aktivitas sintesis jawaban LLM.

Nama	Jenis	Deskripsi
elapsedMs	integer (int32)	Waktu yang berlalu dalam milidetik untuk aktivitas pengambilan.
id	integer (int32)	ID rekaman aktivitas.
inputTokens	integer (int32)	Jumlah token input untuk aktivitas sintesis jawaban LLM.
outputTokens	integer (int32)	Jumlah token keluaran untuk aktivitas sintesis jawaban LLM.
type	string: modelAnswerSynthesis	Jenis rekaman aktivitas.

KnowledgeAgentModelQueryPlanningActivityRecord

Objek

Mewakili rekaman aktivitas perencanaan kueri LLM.

Nama	Jenis	Deskripsi
elapsedMs	integer (int32)	Waktu yang berlalu dalam milidetik untuk aktivitas pengambilan.
id	integer (int32)	ID rekaman aktivitas.
inputTokens	integer (int32)	Jumlah token input untuk aktivitas perencanaan kueri LLM.
outputTokens	integer (int32)	Jumlah token output untuk aktivitas perencanaan kueri LLM.
type	string: modelQueryPlanning	Jenis rekaman aktivitas.

KnowledgeAgentRetrievalRequest

Objek

Kontrak input untuk permintaan pengambilan.

Nama	Jenis	Deskripsi
knowledgeSourceParams	KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]
messages	KnowledgeAgentMessage[]	Objek gaya pesan bahasa alami.

KnowledgeAgentRetrievalResponse

Objek

Kontrak keluaran untuk respons pengambilan.

Nama	Jenis	Deskripsi
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentAzureBlobActivityRecord[] KnowledgeAgentModelAnswerSynthesisActivityRecord[] KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchIndexActivityRecord[] KnowledgeAgentSemanticRerankerActivityRecord[]	Catatan aktivitas untuk melacak kemajuan dan implikasi penagihan.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureBlobReference[] KnowledgeAgentSearchIndexReference[]	Referensi untuk data pengambilan yang digunakan dalam respons.
response	KnowledgeAgentMessage[]	Objek gaya pesan bahasa alami.

KnowledgeAgentSearchIndexActivityArguments

Objek

Mewakili argumen yang digunakan untuk menjalankan aktivitas pengambilan indeks pencarian.

Nama	Jenis	Deskripsi
filter	string	String filter.
search	string	String pencarian yang digunakan untuk mengkueri indeks pencarian.

KnowledgeAgentSearchIndexActivityRecord

Objek

Mewakili rekaman aktivitas pengambilan indeks pencarian.

Nama	Jenis	Deskripsi
count	integer (int32)	Jumlah dokumen yang diambil yang cukup relevan untuk melewati ambang batas reranker.
elapsedMs	integer (int32)	Waktu yang berlalu dalam milidetik untuk aktivitas pengambilan.
id	integer (int32)	ID rekaman aktivitas.
knowledgeSourceName	string	Sumber pengetahuan untuk aktivitas pengambilan.
queryTime	string (date-time)	Waktu kueri untuk aktivitas pengambilan ini.
searchIndexArguments	KnowledgeAgentSearchIndexActivityArguments	Argumen indeks pencarian untuk aktivitas pengambilan.
type	string: searchIndex	Jenis rekaman aktivitas.

KnowledgeAgentSearchIndexReference

Objek

Mewakili referensi dokumen Azure Search.

Nama	Jenis	Deskripsi
activitySource	integer (int32)	ID aktivitas sumber untuk referensi.
docKey	string	Kunci dokumen untuk referensi.
id	string	ID referensi.
rerankerScore	number (float)	Skor reranker untuk referensi dokumen.
sourceData	object
type	string: searchIndex	Jenis referensi.

KnowledgeAgentSemanticRerankerActivityRecord

Objek

Mewakili rekaman aktivitas peringkat semantik.

Nama	Jenis	Deskripsi
elapsedMs	integer (int32)	Waktu yang berlalu dalam milidetik untuk aktivitas pengambilan.
id	integer (int32)	ID rekaman aktivitas.
inputTokens	integer (int32)	Jumlah token input untuk aktivitas ranker semantik.
type	string: semanticReranker	Jenis rekaman aktivitas.

KnowledgeSourceKind

Enumerasi

Jenis sumber pengetahuan.

Nilai	Deskripsi
searchIndex	Sumber pengetahuan yang membaca data dari Indeks Pencarian.
azureBlob	Sumber pengetahuan yang membaca dan menyerap data dari Azure Blob Storage ke Indeks Pencarian.

SearchIndexKnowledgeSourceParams

Objek

Menentukan parameter runtime untuk sumber pengetahuan indeks pencarian

Nama	Jenis	Deskripsi
filterAddOn	string	Kondisi filter yang diterapkan ke indeks (misalnya, 'State eq VA').
kind	string: searchIndex	Jenis sumber pengetahuan.
knowledgeSourceName	string	Nama indeks yang diterapkan param.