Knowledge Retrieval - Retrieve

Layanan:: Search Service

Versi API:: 2025-05-01-preview

KnowledgeAgent mengambil data yang relevan dari penyimpanan pendukung.

POST {endpoint}/agents('{agentName}')/retrieve?api-version=2025-05-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.
targetIndexParams		KnowledgeAgentIndexParams[]

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-05-01-preview



{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "text": "hello world",
          "type": "text"
        }
      ]
    }
  ],
  "targetIndexParams": [
    {
      "indexName": "preview-test",
      "filterAddOn": "foo eq bar",
      "maxDocsForReranker": 100,
      "rerankerThreshold": 2.5,
      "includeReferenceSourceData": true
    }
  ]
}

Respon sampel

Kode status:: 200

{
  "response": [
    {
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "[{...}]"
        }
      ]
    }
  ],
  "activity": [
    {
      "type": "ModelQueryPlanning",
      "id": 0,
      "inputTokens": 11,
      "outputTokens": 22
    },
    {
      "type": "AzureSearchQuery",
      "id": 1,
      "targetIndex": "preview-test",
      "query": {
        "search": "hello world",
        "filter": "foo eq bar"
      },
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234
    },
    {
      "type": "AzureSearchQuery",
      "id": 2,
      "targetIndex": "preview-test",
      "query": {
        "search": "hello world two",
        "filter": "foo eq bar"
      },
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234
    },
    {
      "type": "AzureSearchSemanticRanker",
      "id": 3,
      "inputTokens": 74
    }
  ],
  "references": [
    {
      "type": "AzureSearchDoc",
      "id": "83dd7d40",
      "activitySource": 1,
      "docKey": "myDocKey1",
      "sourceData": {
        "id": "myDocKey1",
        "title": "high_doc",
        "content": "hello world"
      }
    },
    {
      "type": "AzureSearchDoc",
      "id": "83dd7d41",
      "activitySource": 1,
      "docKey": "myDocKey2",
      "sourceData": {
        "id": "myDocKey2",
        "title": "low_doc",
        "content": "goodbye world"
      }
    }
  ]
}

Definisi

Nama	Deskripsi
ErrorAdditionalInfo	Info tambahan kesalahan manajemen sumber daya.
ErrorDetail	Detail kesalahan.
ErrorResponse	Tanggapan kesalahan
Image
KnowledgeAgentAzureSearchDocReference	Mewakili referensi dokumen Azure Search.
KnowledgeAgentIndexParams
KnowledgeAgentMessage	Objek gaya pesan bahasa alami.
KnowledgeAgentMessageContentType	Jenis konten pesan.
KnowledgeAgentMessageImageContent	Jenis pesan teks.
KnowledgeAgentMessageTextContent	Jenis pesan teks.
KnowledgeAgentModelQueryPlanningActivityRecord	Mewakili rekaman aktivitas perencanaan kueri LLM.
KnowledgeAgentRetrievalRequest	Kontrak input untuk permintaan pengambilan.
KnowledgeAgentRetrievalResponse	Kontrak keluaran untuk respons pengambilan.
KnowledgeAgentSearchActivityRecord	Mewakili rekaman aktivitas pengambilan.
KnowledgeAgentSemanticRankerActivityRecord	Mewakili rekaman aktivitas peringkat semantik.
Query	Detail kueri untuk aktivitas pengambilan.

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	Url gambar.

KnowledgeAgentAzureSearchDocReference

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.
sourceData	object
type	string: AzureSearchDoc	Jenis referensi.

KnowledgeAgentIndexParams

Objek

Nama	Jenis	Deskripsi
filterAddOn	string	Kondisi filter yang diterapkan ke indeks (misalnya, 'State eq VA').
includeReferenceSourceData	boolean	Menunjukkan apakah data sumber referensi harus disertakan.
indexName	string	Nama indeks yang diterapkan param.
maxDocsForReranker	integer (int32)	Membatasi jumlah dokumen yang dipertimbangkan untuk peringkat.
rerankerThreshold	number (float) minimum: 0 maximum: 4	Ambang batas untuk menentukan ulang hasil (rentang: 0-4).

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

KnowledgeAgentModelQueryPlanningActivityRecord

Objek

Mewakili rekaman aktivitas perencanaan kueri LLM.

Nama	Jenis	Deskripsi
elapsedMs	integer (int32)	Waktu yang berlalu dalam milidetik untuk aktivitas model.
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
messages	KnowledgeAgentMessage[]	Objek gaya pesan bahasa alami.
targetIndexParams	KnowledgeAgentIndexParams[]

KnowledgeAgentRetrievalResponse

Objek

Kontrak keluaran untuk respons pengambilan.

Nama	Jenis	Deskripsi
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchActivityRecord[] KnowledgeAgentSemanticRankerActivityRecord[]	Catatan aktivitas untuk melacak kemajuan dan implikasi penagihan.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureSearchDocReference[]	Referensi untuk data pengambilan yang digunakan dalam respons.
response	KnowledgeAgentMessage[]	Objek gaya pesan bahasa alami.

KnowledgeAgentSearchActivityRecord

Objek

Mewakili rekaman aktivitas pengambilan.

Nama	Jenis	Deskripsi
count	integer (int32)	Jumlah dokumen yang diambil.
elapsedMs	integer (int32)	Waktu yang berlalu dalam milidetik untuk aktivitas pengambilan.
id	integer (int32)	ID rekaman aktivitas.
query	Query	Detail kueri untuk aktivitas pengambilan.
queryTime	string (date-time)	Waktu kueri untuk aktivitas pengambilan ini.
targetIndex	string	Indeks target untuk aktivitas pengambilan.
type	string: AzureSearchQuery	Jenis rekaman aktivitas.

KnowledgeAgentSemanticRankerActivityRecord

Objek

Mewakili rekaman aktivitas peringkat semantik.

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

Query

Objek

Detail kueri untuk aktivitas pengambilan.

Nama	Jenis	Deskripsi
filter	string	String filter.
search	string	String pencarian.