Knowledge Retrieval - Retrieve

Služba:: Search Service

Verze rozhraní API:: 2025-05-01-preview

KnowledgeAgent získává relevantní data ze záložních obchodů.

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

Parametry identifikátoru URI

Name	V	Vyžadováno	Typ	Description
agentName	path	True	string	Název agenta.
endpoint	path	True	string (url)	Adresa URL koncového bodu vyhledávací služby.
api-version	query	True	string	Verze rozhraní API klienta.

Hlavička požadavku

Name	Vyžadováno	Typ	Description
x-ms-client-request-id		string (uuid)	ID sledování odeslané s požadavkem, které vám pomůže s laděním.
x-ms-query-source-authorization		string	Token identifikující uživatele, pro kterého je dotaz prováděn. Tento token se používá k vynucení bezpečnostních omezení dokumentů.

Text požadavku

Name	Vyžadováno	Typ	Description
messages	True	KnowledgeAgentMessage[]	Objekt stylu zprávy v přirozeném jazyce.
targetIndexParams		KnowledgeAgentIndexParams[]

Odpovědi

Name	Typ	Description
200 OK	KnowledgeAgentRetrievalResponse	Odpověď na načtení je úspěšně vrácena.
Other Status Codes	ErrorResponse	Chybová odpověď.

Příklady

KnowledgeAgentRetrieve

Ukázkový požadavek

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

Ukázková odpověď

Stavový kó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"
      }
    }
  ]
}

Definice

Name	Description
ErrorAdditionalInfo	Další informace o chybě správy prostředků
ErrorDetail	Podrobnosti o chybě.
ErrorResponse	Chybová odpověď
Image
KnowledgeAgentAzureSearchDocReference	Představuje referenční dokument Azure Search.
KnowledgeAgentIndexParams
KnowledgeAgentMessage	Objekt stylu zprávy v přirozeném jazyce.
KnowledgeAgentMessageContentType	Typ obsahu zprávy.
KnowledgeAgentMessageImageContent	Typ textové zprávy
KnowledgeAgentMessageTextContent	Typ textové zprávy
KnowledgeAgentModelQueryPlanningActivityRecord	Představuje záznam aktivity plánování dotazu LLM.
KnowledgeAgentRetrievalRequest	Vstupní kontrakt pro požadavek na načtení.
KnowledgeAgentRetrievalResponse	Výstupní kontrakt pro odpověď na načtení.
KnowledgeAgentSearchActivityRecord	Představuje záznam o aktivitě načítání.
KnowledgeAgentSemanticRankerActivityRecord	Představuje záznam aktivity sémantického hodnoticího nástroje.
Query	Podrobnosti dotazu pro aktivitu načítání.

ErrorAdditionalInfo

Objekt

Další informace o chybě správy prostředků

Name	Typ	Description
info	object	Další informace.
type	string	Další typ informací.

ErrorDetail

Objekt

Podrobnosti o chybě.

Name	Typ	Description
additionalInfo	ErrorAdditionalInfo[]	Další informace o chybě.
code	string	Kód chyby.
details	ErrorDetail[]	Podrobnosti o chybě.
message	string	Chybová zpráva.
target	string	Cíl chyby.

ErrorResponse

Objekt

Chybová odpověď

Name	Typ	Description
error	ErrorDetail	Objekt chyby.

Image

Objekt

Name	Typ	Description
url	string	Adresa URL obrázku.

KnowledgeAgentAzureSearchDocReference

Objekt

Představuje referenční dokument Azure Search.

Name	Typ	Description
activitySource	integer (int32)	ID zdrojové aktivity odkazu.
docKey	string	Klíč dokumentu pro odkaz.
id	string	ID odkazu.
sourceData	object
type	string: AzureSearchDoc	Typ odkazu.

KnowledgeAgentIndexParams

Objekt

Name	Typ	Description
filterAddOn	string	Podmínka filtru aplikovaná na index (např. 'State eq VA').
includeReferenceSourceData	boolean	Označuje, zda mají být zahrnuta referenční zdrojová data.
indexName	string	Název indexu, na který se parametry vztahují.
maxDocsForReranker	integer (int32)	Omezuje počet dokumentů zvažovaných pro pořadí.
rerankerThreshold	number (float) minimum: 0 maximum: 4	Práh pro změnu pořadí výsledků (rozsah: 0–4).

KnowledgeAgentMessage

Objekt

Objekt stylu zprávy v přirozeném jazyce.

Name	Typ	Description
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	Určuje typ obsahu zprávy.
role	string	Role odezvy nástroje.

KnowledgeAgentMessageContentType

Výčet

Typ obsahu zprávy.

Hodnota	Description
text	Druh obsahu textové zprávy.
image	Druh obsahu obrazové zprávy.

KnowledgeAgentMessageImageContent

Objekt

Typ textové zprávy

Name	Typ	Description
image	Image
type	string: image	Typ zprávy

KnowledgeAgentMessageTextContent

Objekt

Typ textové zprávy

Name	Typ	Description
text	string
type	string: text	Typ zprávy

KnowledgeAgentModelQueryPlanningActivityRecord

Objekt

Představuje záznam aktivity plánování dotazu LLM.

Name	Typ	Description
elapsedMs	integer (int32)	Čas, který uplynul pro aktivitu modelu v milisekundách.
id	integer (int32)	ID záznamu aktivity.
inputTokens	integer (int32)	Počet vstupních tokenů pro aktivitu plánování dotazů LLM.
outputTokens	integer (int32)	Počet výstupních tokenů pro aktivitu plánování dotazů LLM.
type	string: ModelQueryPlanning	Typ záznamu aktivity.

KnowledgeAgentRetrievalRequest

Objekt

Vstupní kontrakt pro požadavek na načtení.

Name	Typ	Description
messages	KnowledgeAgentMessage[]	Objekt stylu zprávy v přirozeném jazyce.
targetIndexParams	KnowledgeAgentIndexParams[]

KnowledgeAgentRetrievalResponse

Objekt

Výstupní kontrakt pro odpověď na načtení.

Name	Typ	Description
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchActivityRecord[] KnowledgeAgentSemanticRankerActivityRecord[]	Záznamy o aktivitách pro sledování průběhu a důsledků fakturace.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureSearchDocReference[]	Odkazy na načítání dat použitých v odpovědi.
response	KnowledgeAgentMessage[]	Objekt stylu zprávy v přirozeném jazyce.

KnowledgeAgentSearchActivityRecord

Objekt

Představuje záznam o aktivitě načítání.

Name	Typ	Description
count	integer (int32)	Počet načtených dokumentů.
elapsedMs	integer (int32)	Čas, který uplynul v milisekundách pro aktivitu načítání.
id	integer (int32)	ID záznamu aktivity.
query	Query	Podrobnosti dotazu pro aktivitu načítání.
queryTime	string (date-time)	Čas dotazu pro tuto aktivitu načítání.
targetIndex	string	Cílový index pro aktivitu načítání.
type	string: AzureSearchQuery	Typ záznamu aktivity.

KnowledgeAgentSemanticRankerActivityRecord

Objekt

Představuje záznam aktivity sémantického hodnoticího nástroje.

Name	Typ	Description
elapsedMs	integer (int32)	Čas, který uplynul pro aktivitu modelu v milisekundách.
id	integer (int32)	ID záznamu aktivity.
inputTokens	integer (int32)	Počet vstupních tokenů pro aktivitu sémantického řazení.
type	string: AzureSearchSemanticRanker	Typ záznamu aktivity.

Query

Objekt

Podrobnosti dotazu pro aktivitu načítání.

Name	Typ	Description
filter	string	Řetězec filtru.
search	string	Hledaný řetězec.