Interrogare una base di conoscenza usando l'azione di recupero o l'endpoint MCP.

Nota

Azure AI Search è disponibile tramite il portale di Azure, le API REST e Azure SDK. È inoltre alla base di Foundry IQ, il livello di conoscenza gestito che trasforma il contenuto aziendale in knowledge base riutilizzabili e con riconoscimento delle autorizzazioni per gli agenti nel portale di Microsoft Foundry.

Nota

Questa funzionalità agentic di recupero è generalmente disponibile nell'API REST versione 2026-04-01 tramite accesso programmatico. Il portale di Azure e il portale Foundry di Microsoft continueranno a fornire l'accesso in anteprima a tutte le funzionalità di recupero agentico. Per indicazioni sulla migrazione, vedere Eseguire la migrazione del codice di recupero agentico alla versione più recente.

Se si sceglie di usare un'API REST di anteprima, è possibile accedere alle funzionalità non ancora disponibili a livello generale per questa funzionalità. Le funzionalità di anteprima vengono fornite senza un contratto di servizio e non sono consigliate per i carichi di lavoro di produzione. Per ulteriori informazioni, consultare Condizioni aggiuntive per l'utilizzo di Microsoft Azure per le anteprime.

Importante

Queste funzionalità e funzionalità fanno parte dell'API REST 2026-05-01-preview. L'anteprima 2026-05-01-preview è concessa in licenza all'utente come parte della sottoscrizione Azure ed è soggetta ai termini applicabili alle "Anteprime" nei Microsoft Product Terms, nel Microsoft Products and Services Data Protection Addendum ("DPA") e nei Supplemental Terms of Use for Microsoft Azure Previews.

La versione 2026-05-01-preview supporta le connessioni ad altri servizi di servizi Microsoft e di terze parti. L'utilizzo di questi servizi è soggetto alle rispettive condizioni e potrebbe comportare l'elaborazione o l'archiviazione dei dati al di fuori del limite di conformità Azure, nonché il flusso dei dati nel limite di conformità Azure.

È tua responsabilità gestire l'eventuale trasferimento dei tuoi dati al di fuori dei confini di conformità e geografici della tua organizzazione e le relative implicazioni, nonché garantire che siano predisposte le autorizzazioni, i limiti e le approvazioni appropriati.

L'utente è responsabile di esaminare e testare attentamente le applicazioni compilate nel contesto dei casi d'uso specifici e di prendere tutte le decisioni e le personalizzazioni appropriate. Ciò include l'implementazione di mitigazioni di intelligenza artificiale responsabili, ad esempio metaprompt, filtri di contenuto o altri sistemi di sicurezza, e garantire che le applicazioni soddisfino gli standard di qualità, affidabilità, sicurezza e attendibilità appropriati. Per altre informazioni, vedere la nota sulla trasparenza Azure AI Search.

In una pipeline di recupero agentico, l'azione di recupero richiama l'elaborazione parallela delle query da una Knowledge Base. È possibile chiamare l'azione di recupero direttamente usando le API REST del servizio di ricerca o un Azure SDK. Ogni Knowledge Base espone anche un endpoint MCP (Model Context Protocol) per l'utilizzo da parte di agenti compatibili con MCP.

Questo articolo spiega come chiamare entrambi i metodi di recupero con l'applicazione facoltativa delle autorizzazioni. Copre prima l'azione di recupero e l'endpoint MCP in un secondo momento perché il risultato dello strumento MCP è attualmente diverso dalla forma di risposta REST e SDK. Usa 2026-05-01-preview per il set completo di funzionalità, tra cui messages, la sintesi delle risposte, il livello di sforzo di ragionamento configurabile e i metadati delle etichette di riservatezza nelle risposte di recupero dati.

Se si passa da 2025-11-01-preview, è possibile eseguire l'aggiornamento direttamente a 2026-05-01-preview perché le forme di richiesta e risposta rimangono compatibili. Per indicazioni sulla migrazione, vedere Eseguire la migrazione del codice di recupero agentico alla versione più recente.

Per configurare una pipeline che connette Azure AI Search al servizio Agente Foundry tramite MCP, vedere Tutorial: Creare una soluzione di recupero agenti end-to-end.

Prerequisiti

  • Servizio Azure AI Search con una base di conoscenza.

  • Autorizzazioni per eseguire query sulle knowledge base. Configurare l'autenticazione senza chiave con il ruolo lettore dati dell'indice di ricerca assegnato all'account utente (scelta consigliata) o usare una chiave API.

  • Se la knowledge base specifica un LLM, il servizio di ricerca deve avere una managed identity con permessi Utente di Servizi Cognitivi sulla risorsa Microsoft Foundry.

  • Pacchetto Azure.Search.Documents obbligatorio:

    • Per le funzionalità in anteprima del 1° maggio 2026, l'ultimo pacchetto di anteprima: dotnet add package Azure.Search.Documents --prerelease

    • Per le funzionalità 2026-04-01, il pacchetto stabile più recente: dotnet add package Azure.Search.Documents

  • Pacchetto azure-search-documents obbligatorio:

    • Per le funzionalità in anteprima del 1° maggio 2026, l'ultimo pacchetto di anteprima: pip install --pre azure-search-documents

    • Per le funzionalità 2026-04-01, il pacchetto stabile più recente: pip install azure-search-documents

Limitations

Per le origini dati knowledge dell'indice di ricerca, retrieve usa la configurazione semantica dell'origine dati knowledge, ma non applica i profili di punteggio dell'indice sottostante, inclusi defaultScoringProfile. Anche le risposte di recupero non mostrano @search.rerankerBoostedScore.

Chiamare l'azione di recupero

Specificare l'azione di recupero in una knowledge base. Il corpo della richiesta include l'input della query e un elenco facoltativo di fonti di conoscenza da destinare.

La versione 2026-04-01 dell'API supporta solo l'input intents e un recupero estrattivo minimo. Le capacità di sola anteprima, tra cui l'input messages, la pianificazione delle query, la sintesi delle risposte e il ragionamento configurabile, non sono supportate. Usare 2026-05-01-preview per la funzionalità completa.

using Azure;
using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;

// Create knowledge base retrieval client
var kbClient = new KnowledgeBaseRetrievalClient(
    endpoint: new Uri("<YOUR SEARCH SERVICE URL>"),
    knowledgeBaseName: "<YOUR KNOWLEDGE BASE NAME>",
    tokenCredential: new DefaultAzureCredential()
);

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent(
                "You can answer questions about the Earth at night. "
                + "Sources have a JSON format with a ref_id that must be cited in the answer. "
                + "If you do not have the answer, respond with 'I do not know'."
            )
        }
    ) { Role = "assistant" }
);
retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent(
                "Why is the Phoenix nighttime street grid so sharply visible from space, "
                + "whereas large stretches of the interstate between midwestern cities remain comparatively dim?"
            )
        }
    ) { Role = "user" }
);

var result = await kbClient.RetrieveAsync(retrievalRequest);
Console.WriteLine(
    (result.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent)!.Text
);

Reference:KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

from azure.identity import DefaultAzureCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseMessage,
    KnowledgeBaseMessageTextContent,
    KnowledgeBaseRetrievalRequest,
    SearchIndexKnowledgeSourceParams,
)

# Create knowledge base retrieval client
kb_client = KnowledgeBaseRetrievalClient(
    endpoint="<YOUR SEARCH SERVICE URL>",
    knowledge_base_name="<YOUR KNOWLEDGE BASE NAME>",
    credential=DefaultAzureCredential(),
)

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="assistant",
            content=[
                KnowledgeBaseMessageTextContent(
                    text="You can answer questions about the Earth at night. "
                    "Sources have a JSON format with a ref_id that must be cited in the answer. "
                    "If you do not have the answer, respond with 'I do not know'."
                )
            ],
        ),
        KnowledgeBaseMessage(
            role="user",
            content=[
                KnowledgeBaseMessageTextContent(
                    text="Why is the Phoenix nighttime street grid so sharply visible from space, "
                    "whereas large stretches of the interstate between midwestern cities remain comparatively dim?"
                )
            ],
        ),
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="earth-at-night-blob-ks",
        )
    ],
)

result = kb_client.retrieve(request)
print(result.response[0].content[0].text)

Reference:KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

@search-url = <YOUR SEARCH SERVICE URL> // Example: https://my-service.search.windows.net
@accessToken = <YOUR ACCESS TOKEN> // Run: az account get-access-token --scope https://search.azure.com/.default --query accessToken -o tsv

POST {{search-url}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2026-05-01-preview
Content-Type: application/json
Authorization: Bearer {{accessToken}}

{
    "messages": [
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "You can answer questions about the Earth at night. Sources have a JSON format with a ref_id that must be cited in the answer. If you do not have the answer, respond with 'I do not know'."
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Why is the Phoenix nighttime street grid so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?"
                }
            ]
        }
    ],
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "earth-at-night-blob-ks",
            "kind": "searchIndex"
        }
    ]
}

Riferimento:Recupero della Conoscenza - Recupero

Includere immagini nelle risposte di recupero (anteprima)

Per le fonti di conoscenza blob, OneLake indicizzato e SharePoint indicizzato configurate con un archivio risorse, è possibile restituire le immagini incorporate nei documenti insieme al testo e inserirle nel prompt di sintesi della risposta. Impostare enableImageServing sulla voce corrispondente in knowledgeSourceParams per eseguire l'override dell'impostazione predefinita impostata nella definizione della Knowledge Base.

La gestione delle immagini viene eseguita solo quando outputMode è answerSynthesis e richiede l'API REST 2026-05-01-preview o un pacchetto di anteprima Azure SDK equivalente. Per le istruzioni di configurazione, la tabella delle priorità e le modalità di consultazione delle statistiche relative alla distribuzione delle immagini, consultare Immagini incorporate nei documenti in Surface nel recupero agentico (anteprima).

Comportamento dell'indice di ricerca

Per le origini delle informazioni destinate a un indice di ricerca, il tipo di query implicito è semantice non esiste alcuna modalità di ricerca. L'esecuzione della query usa la definizione dell'origine della conoscenza, inclusi semanticConfigurationName, searchFields e sourceDataFields.

Il recupero agentico non accetta input scoringProfile o scoringParameters. Se hai bisogno di dare priorità ai contenuti più recenti per le fonti di conoscenza indicizzate, usa il recupero orientato alla freschezza anziché un profilo di punteggio dell'indice.

Se l'indice include campi vettoriali, è necessaria una definizione di vettore valida in modo che il motore di recupero agentico possa vettorizzare gli input di query. In caso contrario, i campi vettoriali vengono ignorati.

Per altre informazioni, vedere Creare un indice per il recupero agentico.

Filtrare le origini delle informazioni sugli indici di ricerca in fase di query

Quando si recupera da una fonte di conoscenze dell'indice di ricerca, è possibile applicare un filtro OData al momento della query per restringere i risultati a documenti o campi specifici. L'espressione di filtro usa la sintassi OData e viene passata tramite il filterAddOn parametro .

Sintassi di filtro ed esempi

Il filterAddOn parametro accetta espressioni di filtro OData. I modelli di esempio includono:

  • Campi dei metadati: city eq 'Phoenix', status eq 'active'
  • Intervalli di date: publishDate ge 2024-01-01 and publishDate le 2024-12-31
  • Intervalli numerici: price ge 100 and price le 5000
  • Corrispondenza del testo: substringof('climate', description), indexof(title, 'urgent') ge 0
  • Operatori logici: (category eq 'News' or category eq 'Analysis') and status eq 'published'
using Azure;
using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;

var kbClient = new KnowledgeBaseRetrievalClient(
    endpoint: new Uri("<YOUR SEARCH SERVICE URL>"),
    knowledgeBaseName: "<YOUR KNOWLEDGE BASE NAME>",
    tokenCredential: new DefaultAzureCredential()
);

var retrievalRequest = new KnowledgeBaseRetrievalRequest();

retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent(
                "You are a support agent. Answer questions based on published documentation. "
                + "If you don't know the answer, say so."
            )
        }
    ) { Role = "assistant" }
);

retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent(
                "What is the process for submitting an expense report?"
            )
        }
    ) { Role = "user" }
);

// Apply a filter to search only published documents
var searchIndexParams = new SearchIndexKnowledgeSourceParams(
    knowledgeSourceName: "internal-documentation-ks"
);
searchIndexParams.FilterAddOn = "status eq 'published'";

retrievalRequest.KnowledgeSourceParams.Add(searchIndexParams);

var result = await kbClient.RetrieveAsync(retrievalRequest);
Console.WriteLine(
    (result.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent)!.Text
);

from azure.identity import DefaultAzureCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseMessage,
    KnowledgeBaseMessageTextContent,
    KnowledgeBaseRetrievalRequest,
    SearchIndexKnowledgeSourceParams,
)

kb_client = KnowledgeBaseRetrievalClient(
    endpoint="<YOUR SEARCH SERVICE URL>",
    knowledge_base_name="<YOUR KNOWLEDGE BASE NAME>",
    credential=DefaultAzureCredential(),
)

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="assistant",
            content=[
                KnowledgeBaseMessageTextContent(
                    text="You are a support agent. Answer questions based on published documentation. "
                    "If you don't know the answer, say so."
                )
            ],
        ),
        KnowledgeBaseMessage(
            role="user",
            content=[
                KnowledgeBaseMessageTextContent(
                    text="What is the process for submitting an expense report?"
                )
            ],
        ),
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="internal-documentation-ks",
            # Apply a filter to search only published documents
            filter_add_on="status eq 'published'",
        )
    ],
)

result = kb_client.retrieve(request)
print(result.response[0].content[0].text)

POST https://<YOUR SEARCH SERVICE>.search.windows.net/knowledgebases/<YOUR KNOWLEDGE BASE NAME>/retrieve?api-version=2026-05-01-preview
Content-Type: application/json
Authorization: Bearer <YOUR ACCESS TOKEN>

{
    "messages": [
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "You are a support agent. Answer questions based on published documentation. If you don't know the answer, say so."
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What is the process for submitting an expense report?"
                }
            ]
        }
    ],
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "internal-documentation-ks",
            "kind": "searchIndex",
            "filterAddOn": "status eq 'published'"
        }
    ]
}

Esempio di filtro multiplo

È possibile combinare più filtri per perfezionare ulteriormente i risultati.

searchIndexParams.FilterAddOn = "(status eq 'published' or status eq 'internal') and created ge 2025-01-01";

filter_add_on="(status eq 'published' or status eq 'internal') and created ge 2025-01-01"

{
    "knowledgeSourceName": "internal-documentation-ks",
    "kind": "searchIndex",
    "filterAddOn": "(status eq 'published' or status eq 'internal') and created ge 2025-01-01"
}

Applicazione delle autorizzazioni al momento della query (anteprima)

Le modifiche ai permessi di accesso impostati al di fuori di 2026-05-01-preview possono richiedere del tempo prima di comparire nei risultati di recupero di 2026-05-01-preview.

Se le origini conoscenze contengono contenuto protetto da autorizzazioni, il motore di recupero può filtrare i risultati in modo che ogni utente visualizzi solo i documenti a cui è autorizzato ad accedere. Per abilitare questo filtro, passare l'identità dell'utente finale nell'ambito della richiesta di recupero. Senza il token di identità, i risultati delle fonti di conoscenza con autorizzazioni abilitate sono restituiti senza filtro.

L'applicazione delle autorizzazioni ha due parti:

  • Tempo di inserimento: Solo per le origini della conoscenza indicizzate, impostare ingestionPermissionOptions per ingerire i metadati delle autorizzazioni insieme al contenuto.

  • Tempo di query: Passare il token di accesso dell'utente nell'intestazione x-ms-query-source-authorization.

Configurazione al momento dell'ingestione

La tabella seguente illustra le origini delle informazioni che richiedono la configurazione in fase di inserimento e il modo in cui ogni origine applica le autorizzazioni.

Origine delle conoscenze Richiede ingestionPermissionOptions Modalità di applicazione delle autorizzazioni
BLOB o ADLS Gen2 ✅ Ambiti RBAC, ACL o Microsoft Purview importati e confrontati con l'identità dell'utente.
OneLake ✅ I livelli di riservatezza di Microsoft Purview associati al documento importato sono stati confrontati con l'identità dell'utente.
SharePoint indicizzato ✅ ACL di SharePoint o etichette di riservatezza di Microsoft Purview importate e confrontate con l'identità dell'utente.
SharePoint remoto ❌ L'API di recupero di Copilot interroga direttamente SharePoint usando il token dell'utente.
Agente dati di Fabric ❌ Il motore di recupero sostituisce il token dell'utente con un token valido per Microsoft Fabric ed esegue le interrogazioni all'agente dati per conto dell'utente.
Ontologia del fabric ❌ Il motore di recupero sostituisce il token dell'utente con un token limitato a Microsoft Fabric e interroga l'elemento dell'ontologia per conto dell'utente.
IQ lavoro ❌ Il motore di recupero dati scambia il token dell'utente con un token con ambito Work IQ e interroga Work IQ per conto dell'utente.

Se non si configura ingestionPermissionOptions quando si crea l'origine knowledge indicizzata, l'indice non contiene metadati di autorizzazione. Il sistema restituisce i risultati non filtrati, indipendentemente dall'intestazione. Per risolvere questo problema, ricreare l'origine dati con i valori appropriati ingestionPermissionOptions.

Autorizzazione in fase di query

Per passare l'identità dell'utente finale, includere un token di accesso con https://search.azure.com/.default ambito nella richiesta di recupero. Questo token è separato dalle credenziali del servizio usate per accedere al servizio di ricerca. Non sono necessarie autorizzazioni del servizio di ricerca e rappresenta solo l'utente il cui accesso al contenuto viene valutato. Per ulteriori informazioni, consultare l'applicazione di ACL e RBAC durante la fase di interrogazione.

Nell'SDK di .NET passare il token come parametro xMsQuerySourceAuthorization in RetrieveAsync:

using Azure;
using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;

// Service credential: Authenticates to the search service
var serviceCredential = new DefaultAzureCredential();

// User identity token: Represents the end user for document-level permissions filtering
var userTokenContext = new Azure.Core.TokenRequestContext(
    new[] { "https://search.azure.com/.default" }
);
string userToken = (await serviceCredential.GetTokenAsync(userTokenContext)).Token;

// Create the retrieval client with the service credential
var kbClient = new KnowledgeBaseRetrievalClient(
    endpoint: new Uri("<YOUR SEARCH SERVICE URL>"),
    knowledgeBaseName: "<YOUR KNOWLEDGE BASE NAME>",
    tokenCredential: serviceCredential
);

var request = new KnowledgeBaseRetrievalRequest();
request.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent(
                "What companies are in the financial sector?")
        }
    ) { Role = "user" }
);

// Pass the user identity token for permissions filtering
var result = await kbClient.RetrieveAsync(
    request, xMsQuerySourceAuthorization: userToken);

var text = (result.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent)!.Text;
Console.WriteLine(text);

Reference:KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

Nell'SDK di Python passare il token come parametro x_ms_query_source_authorization in retrieve:

from azure.identity import DefaultAzureCredential
from azure.core.credentials import get_bearer_token_provider
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseMessage, KnowledgeBaseMessageTextContent,
    KnowledgeBaseRetrievalRequest,
)

# Service credential: Authenticates to the search service
service_credential = DefaultAzureCredential()

# User identity token: Represents the end user for document-level permissions filtering
user_token_provider = get_bearer_token_provider(
    service_credential, "https://search.azure.com/.default")
user_token = user_token_provider()

# Create the retrieval client with the service credential
kb_client = KnowledgeBaseRetrievalClient(
    endpoint="<YOUR SEARCH SERVICE URL>",
    knowledge_base_name="<YOUR KNOWLEDGE BASE NAME>",
    credential=service_credential,
)

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[KnowledgeBaseMessageTextContent(
                text="What companies are in the financial sector?")],
        )
    ]
)

# Pass the user identity token for permissions filtering
result = kb_client.retrieve(
    retrieval_request=request, x_ms_query_source_authorization=user_token)
print(result.response[0].content[0].text)

Reference:KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

Nell'API REST includere l'intestazione x-ms-query-source-authorization con il token di accesso dell'utente:

@search-url = <YOUR SEARCH SERVICE URL>
@accessToken = <YOUR ACCESS TOKEN> // Service credential
@userAccessToken = <USER ACCESS TOKEN> // User identity token

POST {{search-url}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2026-05-01-preview
Authorization: Bearer {{accessToken}}
Content-Type: application/json
x-ms-query-source-authorization: {{userAccessToken}}

{
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What companies are in the financial sector?"
                }
            ]
        }
    ]
}

Riferimento:Recupero della Conoscenza - Recupero

Esaminare la risposta

Un recupero eseguito con successo restituisce un codice di stato 200 OK. Se la Knowledge Base non riesce a recuperare da una o più origini informazioni, il servizio restituisce un 206 Partial Content codice di stato. La risposta include solo i risultati delle fonti di successo. La matrice di attività contiene informazioni dettagliate sulla risposta parziale come errori.

L'azione di recupero restituisce tre componenti principali:

Risposta estratta

La risposta estratta è una singola stringa unificata che in genere viene passata a un LLM. LLM utilizza la stringa come dati di base e la usa per formulare una risposta. La chiamata API al modello linguistico di grandi dimensioni include la stringa unificata e le istruzioni per il modello, ad esempio se utilizzare il grounding in modo esclusivo o come integrazione.

Il corpo della risposta è strutturato nel formato dello stile del messaggio della chat e il contenuto viene serializzato IN FORMATO JSON.

"response": [
    {
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "[{\"ref_id\":\"0\",\"title\":\"Urban Structure\",\"terms\":\"Location of Phoenix, Grid of City Blocks, Phoenix Metropolitan Area at Night\",\"content\":\"<content chunk redacted>\"}]"
            }
        ]
    }
]

Punti chiave:

  • content.type ha un valore valido: text.

  • content.text è una stringa con codifica JSON contenente i documenti più rilevanti (o blocchi) trovati nell'indice di ricerca, in base agli input della query e della cronologia delle chat. Questa stringa è i dati di base usati da un LLM per formulare una risposta alla domanda dell'utente.

    • Questa parte della risposta è costituita da 200 blocchi o meno, escludendo eventuali risultati che non soddisfano la soglia minima di un punteggio di 2,5 reranker.

    • La stringa inizia con l'ID di riferimento del blocco (usato per scopi di citazione) ed eventuali campi specificati nella configurazione semantica dell'indice di destinazione. In questo esempio si supponga che la configurazione semantica nell'indice di destinazione abbia un campo "title", un campo "terms" e un campo "content".

  • Recupera le risposte che non includono @search.rerankerBoostedScore.

  • La maxOutputSizeInTokens proprietà (maxOutputSize in 2026-05-01-preview) nella richiesta di recupero determina la lunghezza della stringa.

    • Un documento che supera il maxOutputSizeInTokens budget di output può essere omesso dalla risposta. La matrice di attività include un avviso quando il documento più rilevante supera le dimensioni massime di output. Per conservare più contenuto, aumentare maxOutputSizeInTokens. Per altre informazioni, vedere Risolvere i problemi relativi alle risposte vuote.

Matrice di attività

La matrice di attività restituisce il piano di query, che fornisce trasparenza operativa per tenere traccia delle operazioni, delle implicazioni di fatturazione e delle chiamate alle risorse. Include anche le sottoquery inviate alla pipeline di recupero e gli errori per eventuali guasti di recupero, ad esempio fonti di conoscenza inaccessibili.

L'output include i componenti seguenti.

Sezione Descrizione
modelQueryPlanning Per le knowledge base che usano un LLM per la pianificazione delle query, in questa sezione vengono riportati i conteggi dei token usati per l'input e il numero di token per le sottoquery. Include un modelName campo con il nome del modello pubblico (non il nome della distribuzione) del modello che ha eseguito l'attività.
Attività specifica della sorgente Per ogni fonte di conoscenza inclusa nella query, in questa sezione viene riportato il tempo trascorso e gli argomenti usati nella query, incluso il ranker semantico. I tipi di origine delle informazioni includono searchIndex, azureBlobe altre origini di conoscenza supportate.
agenticReasoning In questa sezione viene riportato il consumo di token per il ragionamento agentico durante il recupero, che dipende dall'impegno di ragionamento del recupero specificato.
modelAnswerSynthesis Per le knowledge base che usano la sintesi delle risposte, questa sezione riporta il numero di token per la simulazione della risposta e il numero di token dell'output della risposta. Include un modelName campo con il nome del modello pubblico (non il nome della distribuzione) del modello che ha eseguito l'attività.
modelWebSummarization Per le knowledge base che usano il riepilogo Web, in questa sezione viene riportato l'utilizzo di token per riepilogare i risultati Web. Include un modelName campo con il nome del modello pubblico (non il nome della distribuzione) del modello che ha eseguito l'attività.
imageServing Per le fonti di conoscenza per cui è abilitata la pubblicazione delle immagini, questa sezione riporta imagesRetrieved, imagesSentToModel, totalImageSizeBytes e se verbalizationUsed in fase di indicizzazione era attivo. Per trovare il numero di immagini eliminate, sottrarre imagesSentToModel da imagesRetrieved.

Ecco un esempio della matrice di attività:

  "activity": [
    {
      "type": "modelQueryPlanning",
      "id": 0,
      "inputTokens": 2302,
      "outputTokens": 109,
      "elapsedMs": 2396
    },
    {
      "type": "searchIndex",
      "id": 1,
      "knowledgeSourceName": "demo-financials-ks",
      "queryTime": "2025-11-04T19:25:23.683Z",
      "count": 26,
      "elapsedMs": 1137,
      "searchIndexArguments": {
        "search": "List of companies in the financial sector according to SEC GICS classification",
        "filter": null,
        "sourceDataFields": [ ],
        "searchFields": [ ],
        "semanticConfigurationName": "en-semantic-config"
      }
    },
    {
      "type": "searchIndex",
      "id": 2,
      "knowledgeSourceName": "demo-healthcare-ks",
      "queryTime": "2025-11-04T19:25:24.186Z",
      "count": 17,
      "elapsedMs": 494,
      "searchIndexArguments": {
        "search": "List of companies in the financial sector according to SEC GICS classification",
        "filter": null,
        "sourceDataFields": [ ],
        "searchFields": [ ],
        "semanticConfigurationName": "en-semantic-config"
      }
    },
    {
      "type": "agenticReasoning",
      "id": 3,
      "retrievalReasoningEffort": {
        "kind": "low"
      },
      "reasoningTokens": 103368
    },
    {
      "type": "modelAnswerSynthesis",
      "id": 4,
      "inputTokens": 5821,
      "outputTokens": 344,
      "elapsedMs": 3837
    }
  ]

Array di riferimenti

La matrice di riferimenti proviene direttamente dai dati di terra sottostanti. Include l'oggetto sourceData usato per generare la risposta ed è costituito da ogni documento che il motore di recupero agentica trova e classifica semanticamente. I campi nell'oggetto sourceData includono un campo id e campi semantici: title, terms, e content.

funge id da ID riferimento per un elemento all'interno di una risposta specifica. Non è la chiave del documento nell'indice di ricerca. Lo usi per fornire citazioni. Il campo activitySource fa riferimento incrociato al id della voce dell'attività che ha prodotto il riferimento, il che è utile per il collegamento di citazione.

Ecco un esempio della matrice di riferimenti:

  "references": [
    {
      "type": "searchIndex",
      "id": "0",
      "activitySource": 2,
      "docKey": "earth_at_night_508_page_104_verbalized",
      "sourceData": null
    },
    {
      "type": "searchIndex",
      "id": "1",
      "activitySource": 2,
      "docKey": "earth_at_night_508_page_105_verbalized",
      "sourceData": null
    }
  ]

Controlla i metadati dell'etichetta di riservatezza nella risposta (anteprima)

Lo stesso comportamento di temporizzazione descritto in Applicare le autorizzazioni in fase di query si applica qui: le modifiche alle autorizzazioni di accesso impostate al di fuori di 2026-05-01-preview possono richiedere tempo per essere visualizzate nelle 2026-05-01-preview risposte di recupero.

Quando si esegue una query su una knowledge base che acquisisce etichette di riservatezza di Microsoft Purview, la risposta di recupero include i metadati delle etichette a due livelli:

Posizione Campo Descrizione
Per riferimento sensitivityLabelInfo L'etichetta di riservatezza applicata a ogni documento restituito nell'array references.
Risposta metadata.responseSensitivityLabelInfo Etichetta di aggregazione che rappresenta l'etichetta di riservatezza con priorità più alta in tutti i documenti a cui si fa riferimento nella risposta. Utile per banner visualizzati lato client e per l'applicazione delle policy.

Microsoft Graph calcola l'etichetta a livello della risposta dalle etichette relative a ciascun riferimento in base alle regole di ereditarietà delle etichette di Microsoft Purview. In genere, l'etichetta più restrittiva vince.

L'esempio seguente mostra una risposta di recupero con due documenti di riferimento (uno Confidential, uno Internal) e l'etichetta a livello di risposta risultante.

{
  "response": [
    {
      "role": "assistant",
      "content": [
        { "type": "text", "text": "[ ... grounding data ... ]" }
      ]
    }
  ],
  "references": [
    {
      "type": "azureBlob",
      "id": "0",
      "activitySource": 1,
      "docKey": "contract-2026.pdf",
      "sensitivityLabelInfo": {
        "labelId": "<label-guid>",
        "labelName": "Confidential",
        "color": "#FF0000",
        "tooltip": "Confidential — Recipients can read but not forward.",
        "isEncrypted": true,
        "priority": 3
      },
      "sourceData": null
    },
    {
      "type": "azureBlob",
      "id": "1",
      "activitySource": 1,
      "docKey": "policy-overview.pdf",
      "sensitivityLabelInfo": {
        "labelId": "<label-guid>",
        "labelName": "Internal",
        "color": "#FFA500",
        "tooltip": "For internal use only.",
        "isEncrypted": false,
        "priority": 1
      },
      "sourceData": null
    }
  ],
  "metadata": {
    "responseSensitivityLabelInfo": {
      "labelId": "<label-guid>",
      "labelName": "Confidential",
      "color": "#FF0000",
      "tooltip": "Confidential — Recipients can read but not forward.",
      "isEncrypted": true,
      "priority": 3
    }
  }
}

Tipi di riferimento che espongono etichette di sensibilità

Il nome del campo e la disponibilità dei metadati dell'etichetta dipendono dal tipo di origine della knowledge base che ha prodotto ogni riferimento.

Riferimento type Campo Etichetta Disponibile quando...
azureBlob sensitivityLabelInfo La fonte di conoscenza "blob" include sensitivityLabel all'interno di ingestionPermissionOptions.
indexedOneLake sensitivityLabelInfo La fonte di conoscenza OneLake include sensitivityLabel in ingestionPermissionOptions.
indexedSharePoint sensitivityLabelInfo La fonte di conoscenza indicizzata da SharePoint include sensitivityLabel all'interno di ingestionPermissionOptions.
searchIndex sensitivityLabelInfo L'indice sottostante è purviewEnabled impostato su true e un campo contrassegnato con sensitivityLabel: true.

Visualizzare e controllare le raccomandazioni

Comportamento del server MCP

L'endpoint MCP esposto da ogni Knowledge Base espone gli stessi campi di etichetta di riservatezza dell'API REST. Quando un client compatibile con MCP richiama lo strumento knowledge_base_retrieve, il risultato dello strumento contiene gli stessi elementi sensitivityLabelInfo per riferimento e metadata.responseSensitivityLabelInfo a livello di risposta documentati in precedenza in questa sezione. I client MCP applicano controlli di visualizzazione e di policy basati su questi campi.

Recuperare esempi di azioni (anteprima)

Gli esempi seguenti illustrano diversi modi per chiamare l'azione di recupero usando la versione dell'API 2026-05-01-preview, che supporta il set di funzionalità completo, inclusa la sintesi delle risposte e un tentativo di ragionamento configurabile. Per l'utilizzo 2026-04-01, vedere le sezioni precedenti.

Esamina i nomi dei modelli nei registri attività

I record di attività basati su modello includono un modelName campo quando includeActivity è abilitato. Usare questo campo per verificare quale modello configurato gestisce la pianificazione delle query, la sintesi delle risposte o il riepilogo Web durante una richiesta di recupero.

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent("Which policy applies to returns?")
        }
    ) { Role = "user" }
);
retrievalRequest.IncludeActivity = true;

var result = await kbClient.RetrieveAsync(retrievalRequest);
foreach (var entry in result.Value.Activity)
{
    Console.WriteLine($"{entry.Type} modelName={entry.ModelName}");
}

Reference:KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[KnowledgeBaseMessageTextContent(text="Which policy applies to returns?")],
        )
    ],
    include_activity=True,
)

result = kb_client.retrieve(request)
for entry in result.activity:
    print(entry.type, "modelName=", getattr(entry, "model_name", None))

Reference:KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

POST {{search-url}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2026-05-01-preview
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "Which policy applies to returns?" }
            ]
        }
    ],
    "includeActivity": true
}

Riferimento:Recupero della Conoscenza - Recupero

L'estratto di risposta seguente mostra i record di attività con modelName.

{
  "activity": [
    {
      "type": "modelQueryPlanning",
      "id": 0,
      "modelName": "gpt-5-mini",
      "inputTokens": 1842,
      "outputTokens": 87,
      "elapsedMs": 1923
    },
    {
      "type": "searchIndex",
      "id": 1,
      "knowledgeSourceName": "operations-ks",
      "count": 12,
      "elapsedMs": 234
    },
    {
      "type": "modelAnswerSynthesis",
      "id": 2,
      "modelName": "gpt-5-mini",
      "inputTokens": 2418,
      "outputTokens": 179,
      "elapsedMs": 931
    }
  ]
}

Per avere successo è necessario disporre di una fonte di conoscenza

Impostare failOnError in knowledgeSourceParams per contrassegnare una fonte di conoscenza come obbligatoria. Usare questo parametro quando una risposta parziale potrebbe essere fuorviante o non conforme se tale origine non è disponibile.

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent("Which HR policy applies?")
        }
    ) { Role = "user" }
);
retrievalRequest.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams("hr-policy-ks")
    {
        FailOnError = true,
        AlwaysQuerySource = true
    }
);
retrievalRequest.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams("hr-faq-ks")
);

var result = await kbClient.RetrieveAsync(retrievalRequest);

Riferimento:SearchIndexKnowledgeSourceParams

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[KnowledgeBaseMessageTextContent(text="Which HR policy applies?")],
        )
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="hr-policy-ks",
            fail_on_error=True,
            always_query_source=True,
        ),
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="hr-faq-ks",
        ),
    ],
)

result = kb_client.retrieve(request)

Riferimento:SearchIndexKnowledgeSourceParams

POST {{search-url}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2026-05-01-preview
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "Which HR policy applies?" }
            ]
        }
    ],
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "hr-policy-ks",
            "kind": "searchIndex",
            "failOnError": true,
            "alwaysQuerySource": true
        },
        {
            "knowledgeSourceName": "hr-faq-ks",
            "kind": "searchIndex"
        }
    ]
}

Riferimento:Recupero della Conoscenza - Recupero

Ottimizza i documenti candidati per ciascuna fonte di conoscenza

Impostare maxOutputDocuments in knowledgeSourceParams per limitare il numero di documenti candidati che una specifica fonte di conoscenza può fornire prima della selezione del risultato finale. Usare questo parametro quando si vuole associare l'input di un'origine alla pipeline senza influire sugli altri.

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent("What safety procedures apply?")
        }
    ) { Role = "user" }
);
retrievalRequest.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams("operations-ks")
    {
        MaxOutputDocuments = 50
    }
);

var result = await kbClient.RetrieveAsync(retrievalRequest);

Riferimento:SearchIndexKnowledgeSourceParams

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[KnowledgeBaseMessageTextContent(text="What safety procedures apply?")],
        )
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="operations-ks",
            max_output_documents=50,
        ),
    ],
)

result = kb_client.retrieve(request)

Riferimento:SearchIndexKnowledgeSourceParams

POST {{search-url}}/knowledgebases/operations-kb/retrieve?api-version=2026-05-01-preview
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What safety procedures apply?" }
            ]
        }
    ],
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "operations-ks",
            "kind": "searchIndex",
            "maxOutputDocuments": 50
        }
    ]
}

Riferimento:Recupero della Conoscenza - Recupero

Limitare i documenti di base finali

Il parametro di primo livello maxOutputDocuments delimita il numero di documenti di base restituiti nella risposta di recupero finale. Usare questo parametro quando l'applicazione richiede una citazione o un conteggio dei riferimenti prevedibili.

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent("What is the return policy?")
        }
    ) { Role = "user" }
);
retrievalRequest.OutputMode = "extractedData";
retrievalRequest.MaxOutputDocuments = 3;
retrievalRequest.MaxOutputSize = 6000;

var result = await kbClient.RetrieveAsync(retrievalRequest);

Reference:KnowledgeBaseRetrievalRequest

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[KnowledgeBaseMessageTextContent(text="What is the return policy?")],
        )
    ],
    output_mode="extractedData",
    max_output_documents=3,
    max_output_size=6000,
)

result = kb_client.retrieve(request)

Reference:KnowledgeBaseRetrievalRequest

POST {{search-url}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2026-05-01-preview
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What is the return policy?" }
            ]
        }
    ],
    "outputMode": "extractedData",
    "maxOutputDocuments": 3,
    "maxOutputSize": 6000
}

Riferimento:Recupero della Conoscenza - Recupero

Nella tabella seguente viene illustrato come maxOutputDocuments e maxOutputSize interagire tra tutte e quattro le combinazioni.

maxOutputDocuments maxOutputSize Behavior
Non specificato Non specificato Usa il comportamento predefinito maxOutputSize del limite di risposta.
Non specificato Specificato Rimuove i documenti dopo il raggiungimento del limite di dimensioni del payload.
Specificato Non specificato Restituisce fino al numero specificato di documenti di messa a terra e non applica il limite maxOutputSize.
Specificato Specificato Restituisce fino a maxOutputDocuments documenti o comunque tutti i documenti che rientrano entro maxOutputSize, a seconda di quale limite venga raggiunto per primo.

Eseguire l'override del ragionamento predefinito e impostare i limiti delle richieste

In questo esempio viene specificata la sintesi delle risposte, pertanto l'impegno di ragionamento del recupero deve essere low o medium. Imposta anche il maxRuntimeInSeconds limite di latenza totale delle richieste e maxOutputSize il limite del payload della risposta.

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent("What companies are in the financial sector?")
        }
    ) { Role = "user" }
);
retrievalRequest.RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort();
retrievalRequest.OutputMode = "answerSynthesis";
retrievalRequest.MaxRuntimeInSeconds = 30;
retrievalRequest.MaxOutputSize = 6000;

var result = await kbClient.RetrieveAsync(retrievalRequest);
Console.WriteLine(
    (result.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent)!.Text
);

Reference:KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

from azure.search.documents.knowledgebases.models import KnowledgeRetrievalLowReasoningEffort

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[KnowledgeBaseMessageTextContent(text="What companies are in the financial sector?")],
        )
    ],
    retrieval_reasoning_effort=KnowledgeRetrievalLowReasoningEffort(),
    output_mode="answerSynthesis",
    max_runtime_in_seconds=30,
    max_output_size=6000,
)

result = kb_client.retrieve(request)
print(result.response[0].content[0].text)

Reference:KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

POST {{search-url}}/knowledgebases/kb-override/retrieve?api-version=2026-05-01-preview
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What companies are in the financial sector?" }
            ]
        }
    ],
    "retrievalReasoningEffort": { "kind": "low" },
    "outputMode": "answerSynthesis",
    "maxRuntimeInSeconds": 30,
    "maxOutputSize": 6000
}

Riferimento:Recupero della Conoscenza - Recupero

Impostare i riferimenti per ogni origine delle informazioni

Usare includeReferences e includeReferenceSourceData in knowledgeSourceParams per controllare quali origini vengono visualizzate nella matrice dei riferimenti e la quantità di dati di origine inclusi in ogni voce. In questo esempio viene utilizzata l'attività di ragionamento predefinita della Knowledge Base.

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent("What companies are in the financial sector?")
        }
    ) { Role = "user" }
);
retrievalRequest.IncludeActivity = true;
retrievalRequest.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams("demo-financials-ks")
    {
        IncludeReferences = true,
        IncludeReferenceSourceData = true
    }
);

retrievalRequest.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams("demo-communicationservices-ks")
    {
        IncludeReferences = false,
        IncludeReferenceSourceData = false
    }
);

retrievalRequest.KnowledgeSourceParams.Add(
    new SearchIndexKnowledgeSourceParams("demo-healthcare-ks")
    {
        IncludeReferences = true,
        IncludeReferenceSourceData = false,
        AlwaysQuerySource = true
    }
);

var result = await kbClient.RetrieveAsync(retrievalRequest);
Console.WriteLine(
    (result.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent)!.Text
);

Reference:KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

from azure.search.documents.knowledgebases.models import SearchIndexKnowledgeSourceParams

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[KnowledgeBaseMessageTextContent(text="What companies are in the financial sector?")],
        )
    ],
    include_activity=True,
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="demo-financials-ks",
            include_references=True,
            include_reference_source_data=True,
        ),
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="demo-communicationservices-ks",
            include_references=False,
            include_reference_source_data=False,
        ),
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="demo-healthcare-ks",
            include_references=True,
            include_reference_source_data=False,
            always_query_source=True,
        ),
    ],
)

result = kb_client.retrieve(request)
print(result.response[0].content[0].text)

Reference:KnowledgeBaseRetrievalClient, SearchIndexKnowledgeSourceParams

POST {{search-url}}/knowledgebases/kb-medium-example/retrieve?api-version=2026-05-01-preview
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What companies are in the financial sector?" }
            ]
        }
    ],
    "includeActivity": true,
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "demo-financials-ks",
            "kind": "searchIndex",
            "includeReferences": true,
            "includeReferenceSourceData": true
        },
        {
            "knowledgeSourceName": "demo-communicationservices-ks",
            "kind": "searchIndex",
            "includeReferences": false,
            "includeReferenceSourceData": false
        },
        {
            "knowledgeSourceName": "demo-healthcare-ks",
            "kind": "searchIndex",
            "includeReferences": true,
            "includeReferenceSourceData": false,
            "alwaysQuerySource": true
        }
    ]
}

Riferimento:Recupero della Conoscenza - Recupero

Usare uno sforzo minimo di ragionamento

In questo esempio non esiste alcun LLM per la pianificazione intelligente delle query o la sintesi delle risposte. La stringa di query passa al motore di recupero agentico per la ricerca di parole chiave o la ricerca ibrida.

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Intents.Add(
    new KnowledgeRetrievalSemanticIntent("what is a brokerage")
);

var result = await kbClient.RetrieveAsync(retrievalRequest);
Console.WriteLine(
    (result.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent)!.Text
);

Reference:KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseRetrievalRequest,
    KnowledgeRetrievalSemanticIntent,
)

request = KnowledgeBaseRetrievalRequest(
    intents=[
        KnowledgeRetrievalSemanticIntent(
            search="what is a brokerage",
        )
    ]
)

result = kb_client.retrieve(request)
print(result.response[0].content[0].text)

Reference:KnowledgeBaseRetrievalClient, KnowledgeBaseRetrievalRequest

POST {{search-url}}/knowledgebases/kb-minimal/retrieve?api-version=2026-05-01-preview
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
    "intents": [
        {
            "type": "semantic",
            "search": "what is a brokerage"
        }
    ]
}

Riferimento:Recupero della Conoscenza - Recupero

Risolvere i problemi relativi alle risposte vuote

È possibile trovare un documento durante il passaggio di ricerca, ma può comunque essere omesso dalla risposta finale se il contenuto di base supera il budget di output maxOutputSizeInTokens (maxOutputSize in 2026-05-01-preview). Quando questo accade, l'array di attività mostra che sono state trovate corrispondenze e il record di attività include un avviso che segnala che il documento più rilevante ha superato la dimensione massima di output. L'array di riferimenti e il contenuto della risposta basata sui dati forniti sono vuoti per quel documento. Per conservare più contenuto, aumentare maxOutputSizeInTokens.

Per evitare questo comportamento, indicizzare documenti di origine di grandi dimensioni come blocchi più piccoli con identificatori stabili e metadati di origine. Questo vale soprattutto per i manuali lunghi, i criteri o gli articoli della Knowledge Base.

Chiamare l'endpoint MCP

Importante

Le implementazioni MCP sono soggette a rischi, ad esempio attacchi, errori a catena e perdita di supervisione umana. È possibile attenuare questi rischi controllando i server MCP per la sicurezza e l'affidabilità, seguendo le procedure consigliate di Microsoft e industry e implementando meccanismi di approvazione e monitoraggio dei comportamenti a catena.

MCP è un protocollo aperto che standardizza il modo in cui le applicazioni di intelligenza artificiale si connettono a origini dati e strumenti esterni.

In Azure AI Search ogni Knowledge Base è un server MCP autonomo che espone lo strumento knowledge_base_retrieve. Qualsiasi client compatibile con MCP, incluso Foundry Agent Service, GitHub Copilot, Claude e Cursor, può richiamare questo strumento per eseguire query sulla Knowledge Base.

Formato endpoint MCP

Ogni Knowledge Base ha un endpoint MCP nell'URL seguente.

https://<your-service-name>.search.windows.net/knowledgebases/<your-knowledge-base-name>/mcp?api-version=<api-version>

La versione dell'API specificata determina il risultato della connessione. Con 2026-05-01-preview, la base di conoscenza può restituire risposte sintetizzate quando la base di conoscenza sottostante è configurata con un LLM e un sistema di ragionamento compatibile. Con 2026-04-01, il recupero è sempre minimo ed estratto e la connessione restituisce solo i dati di base.

Eseguire l'autenticazione all'endpoint MCP

L'endpoint MCP richiede l'autenticazione tramite header personalizzati. Sono disponibili due opzioni:

  • (Scelta consigliata) Passare un token di tipo bearer nell'header Authorization. L'identità dietro il token deve avere il ruolo Lettore dati indice di ricerca assegnato sul servizio di ricerca. Questo approccio evita di archiviare le chiavi nei file di configurazione. Per altre informazioni, vedere Connettere l'app a Azure AI Search usando identità.

  • Passare una chiave amministratore nell'intestazione api-key. Una chiave di amministrazione fornisce l'accesso in lettura/scrittura completo al servizio di ricerca, quindi usarla con cautela. Per ulteriori informazioni, vedere Connettiti ad Azure AI Search utilizzando le chiavi API.

Tip

Ogni client MCP configura intestazioni personalizzate in modo diverso. Per esempio:

  • In Foundry Agent Service è possibile configurare l'autenticazione tramite una connessione al progetto e aggiungere lo strumento MCP a un agente. Il servizio inserisce automaticamente le intestazioni necessarie nelle richieste MCP.

  • In GitHub Copilot e client simili si configurano le intestazioni nel file JSON del server MCP, ad esempio mcp.json.

Esaminare la risposta MCP

Quando un client MCP richiama knowledge_base_retrieve, riceve un risultato di uno strumento MCP anziché l'involucro response, activity e references dell'azione retrieve. Molti client MCP esecuno il risultato dello strumento in un oggetto di primo livello result , quindi il payload che si dovrebbe prevedere è result.content[].

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"ref_id\":\"0\",\"title\":\"Urban Structure\",\"terms\":\"Location of Phoenix, Grid of City Blocks, Phoenix Metropolitan Area at Night\",\"content\":\"<content chunk redacted>\"}]"
      }
    ]
  }
}

Punti chiave:

  • result.content[] contiene l'output dello strumento MCP restituito dalla Knowledge Base.

  • result.content[].type è text.

  • result.content[].text contiene i dati recuperati come stringa codificata in JSON.

  • A differenza dell'azione retrieve, l'attuale risposta MCP non restituisce array activity o references separati e non popola le voci resource per il contenuto restituito.

Contenuto correlato

  • Last updated on