Convalidare il recupero agentico privato end-to-end

Questo articolo è la terza parte di una serie di esercitazioni in tre parti. In questa parte del tutorial, si crea un'origine dati e una base di conoscenza, si registra l'endpoint MCP come connessione del progetto e si esegue un prompt di convalida tramite un agente per confermare risposte fondate sul contenuto privato e corredate di citazioni. A questo punto, i livelli di rete, identità e recupero convergono nello stesso percorso di esecuzione.

Prerequisites

• Completamento di Configurare la connettività in ingresso privata e Configurare la connettività in uscita privata.

• Owner, User Access Administratoro Role Based Controllo di accesso Administrator in ambiti in cui si assegnano ruoli all'account utente.

• Distribuzioni di modelli Foundry per text-embedding-3-large e un modello della famiglia GPT-5 (ad esempio gpt-5-turbo). Il template usato nella parte uno esegue il deployment di un modello della famiglia GPT-5, ma non esegue il deployment di text-embedding-3-large. Distribuisci text-embedding-3-large, quindi verifica entrambe le distribuzioni prima di continuare. Per le istruzioni di distribuzione, vedere Distribuire i modelli di Microsoft Foundry nel portale Foundry.

• Visual Studio Code con l'estensione client REST.

• Lo stesso client nella VNet che hai usato nella prima parte, ad esempio un jumpbox, una macchina virtuale, un dev box o una workstation connessa tramite Azure Bastion, connesso al percorso di rete privata del distribuzione e in grado di raggiungere gli endpoint privati.

• L'impostazione Consenti i servizi di Azure della risorsa Foundry nell'elenco dei servizi attendibili rimane abilitata. La seconda parte spiega perché l'acquisizione delle fonti di conoscenza dipende ancora da questo bypass per la chiamata di embedding.

Verificare le distribuzioni dei modelli

Verifica che la risorsa di Foundry includa le distribuzioni utilizzate più avanti in questo articolo.

1. Elencare le distribuzioni del modello nella risorsa Foundry.

   az cognitiveservices account deployment list \
      --name <foundry-resource-name> \
      --resource-group rg-private-retrieval \
      --query "[].{deployment:name,model:properties.model.name,status:properties.provisioningState}" \
      -o table
   

2. Verificare che text-embedding-3-large e un modello della famiglia GPT-5 appaiano entrambi con stato Succeeded.

   Se non è ancora stato distribuito un modello di famiglia GPT-5, distribuirne uno prima di creare l'agente più avanti in questo articolo.

Assegnare i ruoli dell'account utente

La seconda parte dell'esercitazione concede l'accesso in fase di esecuzione a Azure AI Search. In questa sezione, concedi al tuo account utente le autorizzazioni necessarie per caricare contenuti di esempio, creare oggetti di recupero agentico, configurare la connessione al progetto ed eseguire le operazioni dell'agente.

Per assegnare i ruoli all'account utente:

1. Ottieni l'ID oggetto del tuo account da usare come <principal-object-id> nei comandi seguenti.

   az ad signed-in-user show --query id -o tsv
   

2. Assegnare un ruolo nell'ambito dell'account Archiviazione di Azure.

   Storage Blob Data Contributor è necessario per creare il contenitore BLOB e caricare il contenuto di esempio nella sezione successiva.

   az role assignment create \
      --assignee-object-id <principal-object-id> \
      --assignee-principal-type User \
      --role "Storage Blob Data Contributor" \
      --scope "/subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.Storage/storageAccounts/<storage-account-name>"
   

3. Assegnare ruoli nell'ambito del servizio Azure AI Search.

   Search Service Contributor è necessario per gestire la fonte di conoscenza e la knowledge base. Search Index Data Contributor è necessario per il recupero della Knowledge Base durante la convalida.

   az role assignment create \
      --assignee-object-id <principal-object-id> \
      --assignee-principal-type User \
      --role "Search Service Contributor" \
      --scope "/subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.Search/searchServices/<search-service-name>"
   
   az role assignment create \
      --assignee-object-id <principal-object-id> \
      --assignee-principal-type User \
      --role "Search Index Data Contributor" \
      --scope "/subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.Search/searchServices/<search-service-name>"
   

4. Assegnare ruoli nell'ambito della risorsa Foundry.

   Foundry Project Manager è necessario per creare la connessione al progetto. Foundry User è necessario per creare l'agente ed eseguire la conversazione di convalida nel progetto Foundry.

   Importante

   I ruoli di Controllo degli accessi in base al ruolo di Foundry sono stati recentemente rinominati. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager erano precedentemente denominati Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. È possibile che i nomi precedenti vengano visualizzati in alcune posizioni durante l'esecuzione della ridenominazione. Gli ID ruolo e le autorizzazioni di base sono invariati dalla ridenominazione.

   az role assignment create \
      --assignee-object-id <principal-object-id> \
      --assignee-principal-type User \
      --role "Foundry Project Manager" \
      --scope "/subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.CognitiveServices/accounts/<foundry-resource-name>"
   
   az role assignment create \
      --assignee-object-id <principal-object-id> \
      --assignee-principal-type User \
      --role "Foundry User" \
      --scope "/subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.CognitiveServices/accounts/<foundry-resource-name>"
   

5. Verificare le assegnazioni di ruolo.

   az role assignment list \
      --assignee-object-id <principal-object-id> \
      --query "[].{role:roleDefinitionName,scope:scope}" \
      -o table
   

   Verranno visualizzati Search Service Contributor, Search Index Data Contributor, Foundry Project Manager, Foundry User e Storage Blob Data Contributor negli ambiti previsti.

Caricare contenuto di esempio

Caricare documenti JSON di esempio in un contenitore in Archiviazione BLOB di Azure. Il prompt di convalida più avanti in questo articolo basa le proprie risposte sul contenuto di questo BLOB, pertanto i documenti devono essere già presenti prima che l'origine dati li acquisisca.

Per caricare il contenuto di esempio:

1. Scaricare i documenti JSON di esempio nel client nella rete virtuale.

   git clone --depth 1 https://github.com/Azure-Samples/azure-search-sample-data.git
   

2. Crea il contenitore earth-at-night-json BLOB.

   az storage container create \
      --name earth-at-night-json \
      --account-name <storage-account-name> \
      --auth-mode login
   

3. Suddividere il file di esempio in un blob per ogni record.

   L'esempio scaricato archivia tutti i record in un unico documents.json file. Il caricamento di tale file come singolo BLOB può ritardare o bloccarne l'inserimento, quindi suddividerlo prima del caricamento.

   mkdir -p earth-at-night-split
   python - <<'PY'
   import json
   from pathlib import Path
   
   source = Path("azure-search-sample-data/nasa-e-book/earth-at-night-json/documents.json")
   target = Path("earth-at-night-split")
   target.mkdir(exist_ok=True)
   
   for doc in json.loads(source.read_text()):
       (target / f"{doc['id']}.json").write_text(json.dumps(doc))
   PY
   

   Se Python non è disponibile nel client nella rete virtuale, usare un altro strumento compatibile con JSON per creare un BLOB per ogni record prima di continuare.

4. Caricare i documenti di esempio suddivisi nel contenitore.

   az storage blob upload-batch \
      --destination earth-at-night-json \
      --source earth-at-night-split \
      --account-name <storage-account-name> \
      --auth-mode login
   

5. Verificare che i documenti siano stati caricati correttamente.

   az storage blob list \
      --container-name earth-at-night-json \
      --account-name <storage-account-name> \
      --auth-mode login \
      --query "[].name" -o tsv
   

   L'output elenca i file JSON del set di esempi Earth at Night. Questi blob associati a ciascun record diventano il contenuto privato che la fonte di conoscenza acquisisce nella sezione seguente.

Creare una fonte di conoscenza e una base di conoscenza

In Azure AI Search, il recupero agentico prevede due oggetti: un'origine dati e una base di conoscenza. Questa sezione crea un'origine dati di conoscenza BLOB, che genera una pipeline di acquisizione che suddivide in blocchi il contenuto del BLOB privato, usa il modello distribuito text-embedding-3-large per la vettorizzazione e archivia il contenuto arricchito in un indice di ricerca. La knowledge base coordina quindi il recupero dalla fonte di conoscenza ed espone i risultati tramite un endpoint MCP, che diventa il target che l'agente richiama in una sezione successiva.

Per creare l'origine dati e la base di conoscenza:

1. Ottieni un token bearer di Azure AI Search da usare come <search-access-token> nelle richieste seguenti.

   az account get-access-token --scope https://search.azure.com/.default --query accessToken -o tsv
   

2. Aprire Visual Studio Code e creare un file denominato private-agentic-retrieval.rest.

3. Creare un'origine dati conoscitiva BLOB.

   PUT https://<search-service-name>.search.windows.net/knowledgesources/ks-private-retrieval?api-version=2026-08-01-preview
   Authorization: Bearer <search-access-token>
   Content-Type: application/json
   
   {
     "name": "ks-private-retrieval",
      "kind": "azureBlob",
      "description": "Private blob-backed knowledge source for tutorial content.",
      "azureBlobParameters": {
         "connectionString": "ResourceId=/subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.Storage/storageAccounts/<storage-account-name>;",
         "containerName": "earth-at-night-json",
         "isADLSGen2": false,
         "ingestionParameters": {
            "embeddingModel": {
               "kind": "azureOpenAI",
               "azureOpenAIParameters": {
                  "resourceUri": "https://<foundry-resource-name>.openai.azure.com/",
                  "deploymentId": "text-embedding-3-large",
                  "modelName": "text-embedding-3-large"
               }
            },
            "contentExtractionMode": "minimal",
            "disableImageVerbalization": true
         }
      }
   }
   

4. Creare una knowledge base che faccia riferimento all'origine della knowledge base.

   PUT https://<search-service-name>.search.windows.net/knowledgebases/kb-private-retrieval?api-version=2026-08-01-preview
   Authorization: Bearer <search-access-token>
   Content-Type: application/json
   
   {
     "name": "kb-private-retrieval",
      "description": "Knowledge base grounded in private blob tutorial content.",
      "knowledgeSources": [
         {
            "name": "ks-private-retrieval"
         }
      ],
      "outputMode": "extractiveData",
      "retrievalReasoningEffort": {
         "kind": "minimal"
      }
   }
   

5. Verificare che l'origine delle informazioni sia stata creata correttamente.

   GET https://<search-service-name>.search.windows.net/knowledgesources/ks-private-retrieval?api-version=2026-08-01-preview
   Authorization: Bearer <search-access-token>
   

   Questa richiesta deve restituire HTTP 200. Il payload della risposta deve includere "name": "ks-private-retrieval".

6. Verificare che la knowledge base sia stata creata correttamente.

   GET https://<search-service-name>.search.windows.net/knowledgebases/kb-private-retrieval?api-version=2026-08-01-preview
   Authorization: Bearer <search-access-token>
   

   Questa richiesta deve restituire HTTP 200. Il payload della risposta deve includere "name": "kb-private-retrieval" e elencare "name": "ks-private-retrieval" sotto knowledgeSources.

   Note

   La creazione dell'origine dati di conoscenza avvia l'acquisizione asincrona del contenuto BLOB. La prima acquisizione può richiedere diversi minuti per essere completata. Riesegui in questa sezione le richieste relative all'origine dati e alla knowledge base GET prima di creare l'agente e verifica che restituiscano ancora un codice HTTP 200. Se si esegue la richiesta di convalida troppo presto, la risposta può non riuscire prima che vengano visualizzate le citazioni. Attendere da 30 a 60 secondi e riprovare. Se l'acquisizione si blocca, verificare di avere caricato BLOB suddivisi per singolo record invece di un unico file documents.json di grandi dimensioni e confermare che il bypass del servizio attendibile di Foundry descritto nella seconda parte sia ancora abilitato.

Creare una connessione al progetto

Registrare l'endpoint MCP della Knowledge Base come connessione al progetto in Foundry. Questa connessione consente all'agente di chiamare l'endpoint MCP usando l'identità gestita del progetto anziché i segreti incorporati. Al termine di questa sezione, si dispone di un nome di connessione riutilizzabile a cui fa riferimento la definizione dell'agente.

Per creare la connessione al progetto:

1. Ottenere un token Azure Resource Manager da usare come <management-access-token> nelle richieste seguenti.

   az account get-access-token --scope https://management.azure.com/.default --query accessToken -o tsv
   

2. Ottenere l'ID risorsa del progetto da usare come <project-resource-id> nelle richieste seguenti.

   az rest --method get \
     --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.CognitiveServices/accounts/<foundry-resource-name>/projects?api-version=2025-10-01-preview" \
     --query "value[0].id" -o tsv
   

3. Creare la connessione al progetto usando Azure Resource Manager.

   PUT https://management.azure.com/<project-resource-id>/connections/conn-kb-private-retrieval?api-version=2025-10-01-preview
   Authorization: Bearer <management-access-token>
   Content-Type: application/json
   
   {
     "name": "conn-kb-private-retrieval",
      "type": "Microsoft.MachineLearningServices/workspaces/connections",
      "properties": {
         "authType": "ProjectManagedIdentity",
         "category": "RemoteTool",
         "target": "https://<search-service-name>.search.windows.net/knowledgebases/kb-private-retrieval/mcp?api-version=2026-08-01-preview",
         "isSharedToAll": true,
         "audience": "https://search.azure.com/",
         "metadata": {
            "ApiType": "Azure"
         }
      }
   }
   

4. Verificare che la connessione sia stata creata.

   GET https://management.azure.com/<project-resource-id>/connections/conn-kb-private-retrieval?api-version=2025-10-01-preview
   Authorization: Bearer <management-access-token>
   

   Questa richiesta restituisce HTTP 200. Verificare authType che sia ProjectManagedIdentity, target corrisponda all'URL MCP della Knowledge Base e name che sia conn-kb-private-retrieval. È necessario concedere a ProjectManagedIdentity l'accesso al servizio servizio di ricerca AI Search di Azure tramite i ruoli "Search Index Data Reader" (e "Search Index Data Contributor" se è necessario l'accesso in scrittura). Per informazioni, vedere Creare una connessione al progetto.

Creare un agente e convalidare le citazioni

Creare un agente che usa la connessione al progetto per chiamare lo strumento MCP della Knowledge Base e quindi eseguire una richiesta di convalida tramite una conversazione. L'obiettivo è confermare il comportamento del recupero end-to-end: l'agente risponde sulla base di contenuti privati e restituisce citazioni basate sulle fonti anziché affidarsi alla conoscenza generale del modello.

Per creare l'agente e convalidare le citazioni:

1. Ottieni un token di accesso Foundry da usare come <foundry-access-token> nelle richieste successive.

   az account get-access-token --scope https://ai.azure.com/.default --query accessToken -o tsv
   

2. Ottieni l'endpoint del tuo progetto da usare come <project-endpoint> nelle richieste seguenti.

   az rest --method get \
     --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/rg-private-retrieval/providers/Microsoft.CognitiveServices/accounts/<foundry-resource-name>/projects?api-version=2025-10-01-preview" \
     --query "value[0].properties.endpoints.* | [0]" -o tsv
   

3. Crea un agente prompt che utilizza la tua connessione MCP.

   POST <project-endpoint>/agents?api-version=v1
   Authorization: Bearer <foundry-access-token>
   Content-Type: application/json
   
   {
     "name": "agent-private-retrieval",
      "definition": {
         "model": "<gpt-5-model-deployment-name>",
         "instructions": "Use the knowledge base for every answer. Return grounded citations. If the answer is not in the knowledge base, say that you do not know.",
         "tools": [
            {
               "type": "mcp",
               "server_label": "knowledge-base",
               "server_url": "https://<search-service-name>.search.windows.net/knowledgebases/kb-private-retrieval/mcp?api-version=2026-08-01-preview",
               "project_connection_id": "conn-kb-private-retrieval",
               "require_approval": "never",
               "allowed_tools": ["knowledge_base_retrieve"]
            }
         ],
         "kind": "prompt"
      }
   }
   

4. Creare una conversazione e quindi copiare il id valore dalla risposta da usare come <conversation-id> nel passaggio successivo.

   POST <project-endpoint>/openai/v1/conversations
   Authorization: Bearer <foundry-access-token>
   Content-Type: application/json
   
   {}
   

5. Esegui un prompt di convalida tramite l'agente.

   POST <project-endpoint>/openai/v1/responses
   Authorization: Bearer <foundry-access-token>
   Content-Type: application/json
   
   {
      "conversation": "<conversation-id>",
      "input": "Summarize the key findings from the Earth at Night sample documents and cite the source content.",
      "agent_reference": {
         "type": "agent_reference",
         "name": "agent-private-retrieval"
      }
   }
   

   Risultato previsto:

   • L'agente restituisce una risposta basata sul contenuto del blob caricato.
   • La risposta include citazioni che fanno riferimento al contenuto della sorgente earth at Night.
   • La richiesta ha esito positivo dal client di rete privato usando lo stesso percorso privato configurato nelle parti 1 e due.

Risoluzione dei problemi

Utilizzare la tabella seguente per isolare i guasti nel flusso di recupero e convalida.

Pulire le risorse

Quando si lavora nella propria sottoscrizione, è consigliabile completare un progetto rimuovendo le risorse non più necessarie. Le risorse che rimangono in esecuzione hanno un costo.

In questa esercitazione è stato usato un gruppo di risorse dedicato denominato rg-private-retrieval. Se il gruppo di risorse non è più necessario, eliminarlo:

az group delete \
   --name rg-private-retrieval \
   --yes \
   --no-wait

Learn more

Per altre informazioni sugli argomenti trattati in questa parte dell'esercitazione, vedere gli articoli seguenti:

• Assegnare ruoli di Azure usando interfaccia della riga di comando di Azure
• Creare una fonte delle informazioni da Archiviazione BLOB di Azure o ADLS Gen2
• Creare una knowledge base
• Aggiungere una nuova connessione al progetto
• Guida introduttiva: Creare un prototipo di agente
• Connettere una knowledge base Foundry IQ al servizio Foundry Agent