Knowledge Retrieval - Retrieve

Tjänst:: Search Service

API-version:: 2025-05-01-preview

KnowledgeAgent hämtar relevanta data från säkerhetskopieringsbutiker.

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

URI-parametrar

Name	I	Obligatorisk	Typ	Description
agentName	path	True	string	Namnet på agenten.
endpoint	path	True	string (url)	Slutpunkts-URL:en för söktjänsten.
api-version	query	True	string	Klient-API-version.

Begärandehuvud

Name	Obligatorisk	Typ	Description
x-ms-client-request-id		string (uuid)	Spårnings-ID:t som skickas med begäran för att hjälpa till med felsökning.
x-ms-query-source-authorization		string	Token som identifierar den användare som frågan körs för. Denna token används för att framtvinga säkerhetsbegränsningar för dokument.

Begärandetext

Name	Obligatorisk	Typ	Description
messages	True	KnowledgeAgentMessage[]	Objektet för meddelandeformat på naturligt språk.
targetIndexParams		KnowledgeAgentIndexParams[]

Svar

Name	Typ	Description
200 OK	KnowledgeAgentRetrievalResponse	Hämtningssvaret returneras.
Other Status Codes	ErrorResponse	Felsvar.

Exempel

KnowledgeAgentRetrieve

Exempelbegäran

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

Exempelsvar

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

Definitioner

Name	Description
ErrorAdditionalInfo	Ytterligare information om resurshanteringsfelet.
ErrorDetail	Felinformationen.
ErrorResponse	Felsvar
Image
KnowledgeAgentAzureSearchDocReference	Representerar en referens för ett Azure Search-dokument.
KnowledgeAgentIndexParams
KnowledgeAgentMessage	Objektet för meddelandeformat på naturligt språk.
KnowledgeAgentMessageContentType	Typ av meddelandeinnehåll.
KnowledgeAgentMessageImageContent	Textmeddelandetyp.
KnowledgeAgentMessageTextContent	Textmeddelandetyp.
KnowledgeAgentModelQueryPlanningActivityRecord	Representerar en LLM-frågeplaneringsaktivitetspost.
KnowledgeAgentRetrievalRequest	Indatakontraktet för hämtningsbegäran.
KnowledgeAgentRetrievalResponse	Utdatakontraktet för hämtningssvaret.
KnowledgeAgentSearchActivityRecord	Representerar en post för hämtningsaktivitet.
KnowledgeAgentSemanticRankerActivityRecord	Representerar en semantisk rankningsaktivitetspost.
Query	Frågeinformation för hämtningsaktiviteten.

ErrorAdditionalInfo

Objekt

Ytterligare information om resurshanteringsfelet.

Name	Typ	Description
info	object	Ytterligare information.
type	string	Ytterligare informationstyp.

ErrorDetail

Objekt

Felinformationen.

Name	Typ	Description
additionalInfo	ErrorAdditionalInfo[]	Ytterligare information om felet.
code	string	Felkoden.
details	ErrorDetail[]	Felinformationen.
message	string	Felmeddelandet.
target	string	Felmålet.

ErrorResponse

Objekt

Felsvar

Name	Typ	Description
error	ErrorDetail	Felobjektet.

Image

Objekt

Name	Typ	Description
url	string	Webbadressen till bilden.

KnowledgeAgentAzureSearchDocReference

Objekt

Representerar en referens för ett Azure Search-dokument.

Name	Typ	Description
activitySource	integer (int32)	Källaktivitets-ID:t för referensen.
docKey	string	Dokumentnyckeln för referensen.
id	string	ID för referensen.
sourceData	object
type	string: AzureSearchDoc	Typen av referens.

KnowledgeAgentIndexParams

Objekt

Name	Typ	Description
filterAddOn	string	Ett filtervillkor som tillämpas på indexet (t.ex. "State eq VA").
includeReferenceSourceData	boolean	Anger om referenskälldata ska inkluderas.
indexName	string	Namnet på det index som parametrarna gäller för.
maxDocsForReranker	integer (int32)	Begränsar antalet dokument som övervägs för rangordning.
rerankerThreshold	number (float) minimum: 0 maximum: 4	Ett tröskelvärde för omrankningsresultat (intervall: 0–4).

KnowledgeAgentMessage

Objekt

Objektet för meddelandeformat på naturligt språk.

Name	Typ	Description
content	KnowledgeAgentMessageContent[]: KnowledgeAgentMessageImageContent[] KnowledgeAgentMessageTextContent[]	Anger typen av meddelandeinnehåll.
role	string	Rollen för verktygets svar.

KnowledgeAgentMessageContentType

Uppräkning

Typ av meddelandeinnehåll.

Värde	Description
text	Typ av textmeddelandeinnehåll.
image	Typ av innehåll i bildmeddelanden.

KnowledgeAgentMessageImageContent

Objekt

Textmeddelandetyp.

Name	Typ	Description
image	Image
type	string: image	Typ av meddelande

KnowledgeAgentMessageTextContent

Objekt

Textmeddelandetyp.

Name	Typ	Description
text	string
type	string: text	Typ av meddelande

KnowledgeAgentModelQueryPlanningActivityRecord

Objekt

Representerar en LLM-frågeplaneringsaktivitetspost.

Name	Typ	Description
elapsedMs	integer (int32)	Den förflutna tiden i millisekunder för modellaktiviteten.
id	integer (int32)	ID för aktivitetsposten.
inputTokens	integer (int32)	Antalet indatatoken för LLM-frågeplaneringsaktiviteten.
outputTokens	integer (int32)	Antalet utdatatoken för LLM-frågeplaneringsaktiviteten.
type	string: ModelQueryPlanning	Typ av aktivitetspost.

KnowledgeAgentRetrievalRequest

Objekt

Indatakontraktet för hämtningsbegäran.

Name	Typ	Description
messages	KnowledgeAgentMessage[]	Objektet för meddelandeformat på naturligt språk.
targetIndexParams	KnowledgeAgentIndexParams[]

KnowledgeAgentRetrievalResponse

Objekt

Utdatakontraktet för hämtningssvaret.

Name	Typ	Description
activity	KnowledgeAgentActivityRecord[]: KnowledgeAgentModelQueryPlanningActivityRecord[] KnowledgeAgentSearchActivityRecord[] KnowledgeAgentSemanticRankerActivityRecord[]	Aktivitetsposterna för att spåra förlopp och faktureringskonsekvenser.
references	KnowledgeAgentReference[]: KnowledgeAgentAzureSearchDocReference[]	Referenserna för de hämtningsdata som används i svaret.
response	KnowledgeAgentMessage[]	Objektet för meddelandeformat på naturligt språk.

KnowledgeAgentSearchActivityRecord

Objekt

Representerar en post för hämtningsaktivitet.

Name	Typ	Description
count	integer (int32)	Antalet dokument som hämtats.
elapsedMs	integer (int32)	Den förflutna tiden i millisekunder för hämtningsaktiviteten.
id	integer (int32)	ID för aktivitetsposten.
query	Query	Frågeinformation för hämtningsaktiviteten.
queryTime	string (date-time)	Frågetiden för den här hämtningsaktiviteten.
targetIndex	string	Målindexet för hämtningsaktiviteten.
type	string: AzureSearchQuery	Typ av aktivitetspost.

KnowledgeAgentSemanticRankerActivityRecord

Objekt

Representerar en semantisk rankningsaktivitetspost.

Name	Typ	Description
elapsedMs	integer (int32)	Den förflutna tiden i millisekunder för modellaktiviteten.
id	integer (int32)	ID för aktivitetsposten.
inputTokens	integer (int32)	Antalet indatatoken för den semantiska rangordningsaktiviteten.
type	string: AzureSearchSemanticRanker	Typ av aktivitetspost.

Query

Objekt

Frågeinformation för hämtningsaktiviteten.

Name	Typ	Description
filter	string	Filtersträngen.
search	string	Söksträngen.