Knowledge Retrieval - Retrieve

Szolgáltatás:: Search Service

API-verzió:: 2025-05-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-05-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égponti 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 kéréssel együtt küldött nyomkövetési azonosító, amely segít a hibakeresésben.
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.
targetIndexParams		KnowledgeAgentIndexParams[]

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

Mintaválasz

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

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
KnowledgeAgentAzureSearchDocReference	Egy Azure Search-dokumentumhivatkozást jelöl.
KnowledgeAgentIndexParams
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.
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.
KnowledgeAgentSearchActivityRecord	Egy lekérési tevékenységrekordot jelöl.
KnowledgeAgentSemanticRankerActivityRecord	Egy szemantikai rangsorolási tevékenységrekordot jelöl.
Query	A lekérdezési tevékenység részletei.

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	A kép URL-címe.

KnowledgeAgentAzureSearchDocReference

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.
sourceData	object
type	string: AzureSearchDoc	A hivatkozás típusa.

KnowledgeAgentIndexParams

Tárgy

Name	Típus	Description
filterAddOn	string	Az indexre alkalmazott szűrési feltétel (pl. "State eq VA").
includeReferenceSourceData	boolean	Azt jelzi, hogy a referenciaforrás adatait bele kell-e foglalni.
indexName	string	Annak az indexnek a neve, amelyre a paraméterek vonatkoznak.
maxDocsForReranker	integer (int32)	Korlátozza a rangsoroláshoz figyelembe vett dokumentumok számát.
rerankerThreshold	number (float) minimum: 0 maximum: 4	Az eredmények újrarangsorolásának küszöbértéke (tartomány: 0–4).

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

KnowledgeAgentModelQueryPlanningActivityRecord

Tárgy

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

Name	Típus	Description
elapsedMs	integer (int32)	A modelltevé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
messages	KnowledgeAgentMessage[]	A természetes nyelvű üzenetstílus-objektum.
targetIndexParams	KnowledgeAgentIndexParams[]

KnowledgeAgentRetrievalResponse

Tárgy

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

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

KnowledgeAgentSearchActivityRecord

Tárgy

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

Name	Típus	Description
count	integer (int32)	A visszakeresett dokumentumok száma.
elapsedMs	integer (int32)	A lekérési tevékenység eltelt ideje ezredmásodpercben.
id	integer (int32)	A tevékenységrekord azonosítója.
query	Query	A lekérdezési tevékenység részletei.
queryTime	string (date-time)	A lekérési tevékenység lekérdezési ideje.
targetIndex	string	A lekérési tevékenység célindexe.
type	string: AzureSearchQuery	A tevékenységrekord típusa.

KnowledgeAgentSemanticRankerActivityRecord

Tárgy

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

Name	Típus	Description
elapsedMs	integer (int32)	A modelltevé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: AzureSearchSemanticRanker	A tevékenységrekord típusa.

Query

Tárgy

A lekérdezési tevékenység részletei.

Name	Típus	Description
filter	string	A szűrő karakterlánc.
search	string	A keresési karakterlánc.