Knowledge Retrieval - Retrieve

Szolgáltatás:: Search Service

API-verzió:: 2025-08-01-preview

A KnowledgeAgent lekéri a releváns adatokat a háttértárolókból.

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

URI-paraméterek

Name	In	Kötelező	Típus	Description
agentName	path	True	string	Az ügynök neve.
endpoint	path	True	string (url)	A keresési szolgáltatás végpontjának URL-címe.
api-version	query	True	string	Ügyfél API verziója.

Kérelem fejléce

Name	Kötelező	Típus	Description
x-ms-client-request-id		string (uuid)	A hibakeresési kérelemmel küldött nyomkövetési azonosító.
x-ms-query-source-authorization		string	A lekérdezés végrehajtásához használt felhasználót azonosító jogkivonat. Ez a jogkivonat a dokumentumokra vonatkozó biztonsági korlátozások érvényesítésére szolgál.

Kérelem törzse

Name	Kötelező	Típus	Description
messages	True	KnowledgeAgentMessage[]	A természetes nyelvű üzenetstílus-objektum.
knowledgeSourceParams		KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]

Válaszok

Name	Típus	Description
200 OK	KnowledgeAgentRetrievalResponse	A lekérési válasz sikeresen visszaküldésre került.
Other Status Codes	ErrorResponse	Hibaválasz.

Példák

KnowledgeAgentRetrieve

Mintakérelem

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"
    }
  ]
}

Mintaválasz

Állapotkód:: 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"
    }
  ]
}

Definíciók

Name	Description
ErrorAdditionalInfo	Az erőforrás-kezelési hiba további információi.
ErrorDetail	A hiba részletei.
ErrorResponse	Hibaválasz
Image
KnowledgeAgentAzureBlobActivityArguments	Az Azure Blob lekérési tevékenység argumentumait jelöli.
KnowledgeAgentAzureBlobActivityRecord	Egy Azure Blob lekérési tevékenységrekordot jelöl.
KnowledgeAgentAzureBlobReference	Egy Azure Blob Storage-dokumentumhivatkozást jelöl.
KnowledgeAgentMessage	A természetes nyelvű üzenetstílus-objektum.
KnowledgeAgentMessageContentType	Az üzenet tartalmának típusa.
KnowledgeAgentMessageImageContent	Szöveges üzenet típusa.
KnowledgeAgentMessageTextContent	Szöveges üzenet típusa.
KnowledgeAgentModelAnswerSynthesisActivityRecord	Egy LLM-válaszszintézis tevékenységrekordot jelöl.
KnowledgeAgentModelQueryPlanningActivityRecord	Egy LLM-lekérdezéstervezési tevékenységrekordot jelöl.
KnowledgeAgentRetrievalRequest	A lekérési kérelem bemeneti szerződése.
KnowledgeAgentRetrievalResponse	A lekérési válasz kimeneti szerződése.
KnowledgeAgentSearchIndexActivityArguments	A keresési index lekérési tevékenységét futtató argumentumokat jelöli.
KnowledgeAgentSearchIndexActivityRecord	A keresési index lekérési tevékenységrekordját jelöli.
KnowledgeAgentSearchIndexReference	Egy Azure Search-dokumentumhivatkozást jelöl.
KnowledgeAgentSemanticRerankerActivityRecord	Egy szemantikai rangsorolási tevékenységrekordot jelöl.
KnowledgeSourceKind	A tudásforrás fajtája.
SearchIndexKnowledgeSourceParams	Futásidejű paramétereket ad meg egy keresési index tudásforráshoz

ErrorAdditionalInfo

Tárgy

Az erőforrás-kezelési hiba további információi.

Name	Típus	Description
info	object	A további információk.
type	string	A további információtípus.

ErrorDetail

Tárgy

A hiba részletei.

Name	Típus	Description
additionalInfo	ErrorAdditionalInfo[]	A hiba további információi.
code	string	A hibakód.
details	ErrorDetail[]	A hiba részletei.
message	string	A hibaüzenet.
target	string	A hibacél.

ErrorResponse

Tárgy

Hibaválasz

Name	Típus	Description
error	ErrorDetail	A hibaobjektum.

Image

Tárgy

Name	Típus	Description
url	string (uri)	A kép URL-címe.

KnowledgeAgentAzureBlobActivityArguments

Tárgy

Az Azure Blob lekérési tevékenység argumentumait jelöli.

Name	Típus	Description
search	string	A blob tartalmának lekérdezéséhez használt keresési sztring.

KnowledgeAgentAzureBlobActivityRecord

Tárgy

Egy Azure Blob lekérési tevékenységrekordot jelöl.

Name	Típus	Description
azureBlobArguments	KnowledgeAgentAzureBlobActivityArguments	A lekérési tevékenység Azure Blob-argumentumai.
count	integer (int32)	A visszakeresett dokumentumok száma, amelyek kellően relevánsak voltak ahhoz, hogy átlépjék a reranker küszöbértéket.
elapsedMs	integer (int32)	A lekérési tevékenység eltelt ideje ezredmásodpercben.
id	integer (int32)	A tevékenységrekord azonosítója.
knowledgeSourceName	string	A lekérési tevékenység tudásforrása.
queryTime	string (date-time)	A lekérési tevékenység lekérdezési ideje.
type	string: azureBlob	A tevékenységrekord típusa.

KnowledgeAgentAzureBlobReference

Tárgy

Egy Azure Blob Storage-dokumentumhivatkozást jelöl.

Name	Típus	Description
activitySource	integer (int32)	A hivatkozás forrástevékenység-azonosítója.
blobUrl	string	A referencia blob URL-címe.
id	string	A hivatkozás azonosítója.
rerankerScore	number (float)	A dokumentumhivatkozás reranker pontszáma.
sourceData	object
type	string: azureBlob	A hivatkozás típusa.

KnowledgeAgentMessage

Tárgy

A természetes nyelvű üzenetstílus-objektum.

Name	Típus	Description
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	Megadja az üzenet tartalmának típusát.
role	string	Az eszközválasz szerepe.

KnowledgeAgentMessageContentType

Felsorolás

Az üzenet tartalmának típusa.

Érték	Description
text	Szöveges üzenet tartalomtípusa.
image	Képüzenet tartalma típus.

KnowledgeAgentMessageImageContent

Tárgy

Szöveges üzenet típusa.

Name	Típus	Description
image	Image
type	string: image	Az üzenet típusa

KnowledgeAgentMessageTextContent

Tárgy

Szöveges üzenet típusa.

Name	Típus	Description
text	string
type	string: text	Az üzenet típusa

KnowledgeAgentModelAnswerSynthesisActivityRecord

Tárgy

Egy LLM-válaszszintézis tevékenységrekordot jelöl.

Name	Típus	Description
elapsedMs	integer (int32)	A lekérési tevékenység eltelt ideje ezredmásodpercben.
id	integer (int32)	A tevékenységrekord azonosítója.
inputTokens	integer (int32)	Az LLM-válaszszintézis tevékenység bemeneti tokenjeinek száma.
outputTokens	integer (int32)	Az LLM-válaszszintézis tevékenység kimeneti jogkivonatainak száma.
type	string: modelAnswerSynthesis	A tevékenységrekord típusa.

KnowledgeAgentModelQueryPlanningActivityRecord

Tárgy

Egy LLM-lekérdezéstervezési tevékenységrekordot jelöl.

Name	Típus	Description
elapsedMs	integer (int32)	A lekérési tevékenység eltelt ideje ezredmásodpercben.
id	integer (int32)	A tevékenységrekord azonosítója.
inputTokens	integer (int32)	Az LLM-lekérdezés tervezési tevékenységének bemeneti jogkivonatainak száma.
outputTokens	integer (int32)	Az LLM-lekérdezés tervezési tevékenységének kimeneti jogkivonatainak száma.
type	string: modelQueryPlanning	A tevékenységrekord típusa.

KnowledgeAgentRetrievalRequest

Tárgy

A lekérési kérelem bemeneti szerződése.

Name	Típus	Description
knowledgeSourceParams	KnowledgeSourceParams[]: SearchIndexKnowledgeSourceParams[]
messages	KnowledgeAgentMessage[]	A természetes nyelvű üzenetstílus-objektum.

KnowledgeAgentRetrievalResponse

Tárgy

A lekérési válasz kimeneti szerződése.

Name	Típus	Description
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentAzureBlobActivityRecord[] KnowledgeAgentModelAnswerSynthesisActivityRecord[] KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchIndexActivityRecord[] KnowledgeAgentSemanticRerankerActivityRecord[]	A tevékenységrekordok az előrehaladás és a számlázási következmények nyomon követésére.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureBlobReference[] KnowledgeAgentSearchIndexReference[]	A válaszban használt lekérési adatok hivatkozásai.
response	KnowledgeAgentMessage[]	A természetes nyelvű üzenetstílus-objektum.

KnowledgeAgentSearchIndexActivityArguments

Tárgy

A keresési index lekérési tevékenységét futtató argumentumokat jelöli.

Name	Típus	Description
filter	string	A szűrősztring.
search	string	A keresési index lekérdezéséhez használt keresési sztring.

KnowledgeAgentSearchIndexActivityRecord

Tárgy

A keresési index lekérési tevékenységrekordját jelöli.

Name	Típus	Description
count	integer (int32)	A visszakeresett dokumentumok száma, amelyek kellően relevánsak voltak ahhoz, hogy átlépjék a reranker küszöbértéket.
elapsedMs	integer (int32)	A lekérési tevékenység eltelt ideje ezredmásodpercben.
id	integer (int32)	A tevékenységrekord azonosítója.
knowledgeSourceName	string	A lekérési tevékenység tudásforrása.
queryTime	string (date-time)	A lekérési tevékenység lekérdezési ideje.
searchIndexArguments	KnowledgeAgentSearchIndexActivityArguments	A lekérési tevékenység keresési indexargumentumai.
type	string: searchIndex	A tevékenységrekord típusa.

KnowledgeAgentSearchIndexReference

Tárgy

Egy Azure Search-dokumentumhivatkozást jelöl.

Name	Típus	Description
activitySource	integer (int32)	A hivatkozás forrástevékenység-azonosítója.
docKey	string	A hivatkozás dokumentumkulcsa.
id	string	A hivatkozás azonosítója.
rerankerScore	number (float)	A dokumentumhivatkozás reranker pontszáma.
sourceData	object
type	string: searchIndex	A hivatkozás típusa.

KnowledgeAgentSemanticRerankerActivityRecord

Tárgy

Egy szemantikai rangsorolási tevékenységrekordot jelöl.

Name	Típus	Description
elapsedMs	integer (int32)	A lekérési tevékenység eltelt ideje ezredmásodpercben.
id	integer (int32)	A tevékenységrekord azonosítója.
inputTokens	integer (int32)	A szemantikai rangsorolási tevékenység bemeneti jogkivonatainak száma.
type	string: semanticReranker	A tevékenységrekord típusa.

KnowledgeSourceKind

Felsorolás

A tudásforrás fajtája.

Érték	Description
searchIndex	Olyan tudásforrás, amely adatokat olvas be egy keresési indexből.
azureBlob	Olyan tudásforrás, amely adatokat olvas és tölt be az Azure Blob Storage-ból egy keresési indexbe.

SearchIndexKnowledgeSourceParams

Tárgy

Futásidejű paramétereket ad meg egy keresési index tudásforráshoz

Name	Típus	Description
filterAddOn	string	Az indexre alkalmazott szűrési feltétel (pl. "State eq VA").
kind	string: searchIndex	A tudásforrás típusa.
knowledgeSourceName	string	Annak az indexnek a neve, amelyre a paraméterek vonatkoznak.