Durchgängigen privaten agentenbasierten Informationsabruf validieren

Dieser Artikel ist Teil drei einer dreiteiligen Lernprogrammreihe. In diesem Teil des Lernprogramms erstellen Sie eine Wissensquelle und Wissensbasis, registrieren den MCP-Endpunkt als Projektverbindung und führen eine Überprüfungsaufforderung über einen Agent aus, um geerdete, zitierte Antworten aus privaten Inhalten zu bestätigen. An diesem Punkt werden die Netzwerk-, Identitäts- und Abrufebenen im gleichen Laufzeitpfad zusammengeführt.

Voraussetzungen

• Abschluss der Einrichtung privater eingehender Verbindungen und Einrichten der privaten ausgehenden Konnektivität.

• Owner, User Access Administratoroder Role Based Access Control Administrator in Bereichen, in denen Sie Ihrem Benutzerkonto Rollen zuweisen.

• Foundry-Modellbereitstellungen für text-embedding-3-large und ein Modell der GPT-5-Familie (z. B. gpt-5-turbo). Die in Teil 1 verwendete Vorlage stellt ein Modell der GPT-5-Familie bereit, stellt jedoch text-embedding-3-large nicht bereit. Stellen Sie text-embedding-3-large bereit, und überprüfen Sie dann beide Bereitstellungen, bevor Sie fortfahren. Anweisungen zur Bereitstellung finden Sie unter Bereitstellen von Microsoft Foundry Models im Foundry-Portal.

• Visual Studio Code mit der REST-Clienterweiterung.

• Der gleiche In-VNet-Client, den Sie in Teil 1 verwendet haben, z. B. eine Jumpbox, eine VM, eine Dev Box oder eine über Azure Bastion verbundene Arbeitsstation, der mit dem privaten Netzwerkpfad in Ihrer Bereitstellung verbunden ist und Ihre privaten Endpunkte erreichen kann.

• Die Einstellung der Foundry-Ressource „Azure-Dienste in der Liste der vertrauenswürdigen Dienste zulassen“ bleibt aktiviert. Teil 2 erläutert, warum die Erfassung von Wissensquellen immer noch von dieser Umgehung für den Einbettungsaufruf abhängt.

Überprüfen von Modellbereitstellungen

Überprüfen Sie, ob Ihre Foundry-Ressource die Bereitstellungen enthält, die weiter unten in diesem Artikel verwendet werden.

1. Listen Sie die Modellimplementierungen auf der Foundry-Ressource auf.

   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. Vergewissern Sie sich, dass sowohl text-embedding-3-large als auch ein GPT-5-Familienmodell mit einem Succeeded-Status angezeigt werden.

   Wenn ein GPT-5-Familienmodell noch nicht bereitgestellt wird, stellen Sie es bereit, bevor Sie den Agent weiter unten in diesem Artikel erstellen.

Zuweisen von Benutzerkontenrollen

Teil 2 des Lernprogramms gewährt Laufzeitzugriff auf Azure KI-Suche. In diesem Abschnitt erteilen Sie Ihrem Benutzerkonto die Zum Hochladen von Beispielinhalten erforderlichen Berechtigungen, erstellen agentische Abrufobjekte, Konfigurieren der Projektverbindung und Ausführen von Agent-Vorgängen.

So weisen Sie Ihrem Benutzerkonto die Rollen zu:

1. Rufen Sie Ihre Kontoobjekt-ID ab, um sie wie <principal-object-id> in den folgenden Befehlen zu verwenden.

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

2. Weisen Sie eine Rolle im Bereich des Azure Storage-Kontos zu.

   Storage Blob Data Contributor ist erforderlich, um den BLOB-Container zu erstellen und den Beispielinhalt im nächsten Abschnitt hochzuladen.

   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. Zuweisen von Rollen im Azure KI-Suche Dienstbereich.

   Search Service Contributor ist erforderlich, um die Wissensquelle und die Wissensbasis zu verwalten. Search Index Data Contributor ist für den Abruf der Wissensbasis während der Überprüfung erforderlich.

   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. Weisen Sie Rollen im Ressourcenbereich „Foundry“ zu.

   Foundry Project Manager ist erforderlich, um die Projektverbindung zu erstellen. Foundry User ist erforderlich, um den Agent zu erstellen und das Validierungsgespräch im Foundry-Projekt auszuführen.

   Wichtig

   Die Foundry-RBAC-Rollen wurden kürzlich umbenannt. Foundry User, Foundry Owner, Foundry Account Owner und Foundry Project Manager wurden zuvor Azure KI-Benutzer, Azure KI-Besitzer, Azure KI-Kontobesitzer und Azure AI Project Manager benannt. Möglicherweise werden die vorherigen Namen an einigen Stellen weiterhin angezeigt, während der Umbenennungsrollout ausgeführt wird. Die Rollen-IDs und Kernberechtigungen bleiben durch die Umbenennung unverändert.

   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. Überprüfen Sie Rollenzuweisungen.

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

   Sie sollten Search Service Contributor, Search Index Data Contributor, Foundry Project Manager, Foundry User und Storage Blob Data Contributor in den erwarteten Bereichen sehen.

Hochladen von Beispielinhalten

Laden Sie JSON-Beispieldokumente in einen Container in Azure Blob Storage hoch. Die Validierungsaufforderung weiter unten in diesem Artikel stützt ihre Antworten auf den Inhalt dieses Blobs, daher müssen die Dokumente vorhanden sein, bevor die Wissensquelle sie erfasst.

So laden Sie den Beispielinhalt hoch:

1. Laden Sie die JSON-Beispieldokumente auf Ihren In-VNet-Client herunter.

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

2. Erstellen Sie den earth-at-night-json Blobcontainer.

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

3. Teilen Sie die Beispieldatei in ein Blob pro Datensatz auf.

   Im heruntergeladenen Beispiel werden alle Datensätze in einer documents.json Datei gespeichert. Das Hochladen dieser Datei als einzelnes Blob kann die Erfassung verzögern oder zum Stillstand bringen; teilen Sie sie daher vor dem Hochladen auf.

   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
   

   Wenn Python auf Ihrem In-VNet-Client nicht verfügbar ist, verwenden Sie ein weiteres JSON-fähiges Tool, um ein BLOB pro Datensatz zu erstellen, bevor Sie fortfahren.

4. Laden Sie die geteilten Beispieldokumente in den Container hoch.

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

5. Überprüfen Sie, ob die Dokumente erfolgreich hochgeladen wurden.

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

   Die Ausgabe listet die JSON-Dateien aus dem Earth at Night-Beispielsatz auf. Diese Blobs pro Datensatz bilden die privaten Inhalte, die die Wissensquelle im nächsten Abschnitt aufnimmt.

Erstellen einer Wissensquelle und Wissensbasis

In Azure KI-Suche umfasst der agentische Abruf zwei Objekte: eine Wissensquelle und eine Wissensbasis. In diesem Abschnitt wird eine Blob-Wissensquelle erstellt, die eine Aufnahmepipeline generiert, die Ihren privaten BLOB-Inhalt aufschlüsselt, das bereitgestellte text-embedding-3-large Modell für die Vektorisierung verwendet und den erweiterten Inhalt in einem Suchindex speichert. Die Wissensbasis koordiniert dann den Abruf aus der Wissensquelle und macht Ergebnisse über einen MCP-Endpunkt verfügbar, der zum Ziel wird, das der Agent in einem späteren Abschnitt aufruft.

So erstellen Sie die Wissensquelle und die Wissensbasis:

1. Rufen Sie ein Azure KI-Suche Bearer-Token ab, das in den folgenden Anfragen als <search-access-token> verwendet wird.

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

2. Öffnen Sie Visual Studio Code, und erstellen Sie eine Datei mit dem Namen private-agentic-retrieval.rest.

3. Erstellen Sie eine Blob-Wissensquelle.

   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. Erstellen Sie eine Wissensbasis, die auf die Wissensquelle verweist.

   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. Bestätigen Sie, dass die Wissensquelle erfolgreich erstellt wurde.

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

   Diese Anforderung sollte HTTP 200 zurückgeben. Die Antwort-Payload sollte "name": "ks-private-retrieval" enthalten.

6. Vergewissern Sie sich, dass die Wissensbasis erfolgreich erstellt wurde.

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

   Diese Anforderung sollte HTTP 200 zurückgeben. Die Antwortnutzlast sollte "name": "kb-private-retrieval" enthalten und "name": "ks-private-retrieval" unter knowledgeSources auflisten.

   Hinweis

   Das Erstellen der Wissensquelle startet die asynchrone Aufnahme Ihres Blob-Inhalts. Die erstmalige Erfassung kann mehrere Minuten in Anspruch nehmen. Führen Sie die Knowledge Source- und Knowledge Base-Anforderungen GET in diesem Abschnitt erneut aus, bevor Sie den Agent erstellen, und bestätigen Sie, dass sie weiterhin HTTP 200 zurückgeben. Wenn Sie die Überprüfungsaufforderung zu früh ausführen, kann die Antwort fehlschlagen, bevor Zitate angezeigt werden. Warten Sie 30 bis 60 Sekunden, und versuchen Sie es dann erneut. Wenn die Datenerfassung ins Stocken gerät, prüfen Sie, ob Sie aufgeteilte Blobs pro Datensatz anstelle einer einzelnen großen Datei documents.json hochgeladen haben, und vergewissern Sie sich, dass die in Teil zwei beschriebene Foundry-Ausnahme für vertrauenswürdige Dienste weiterhin aktiviert ist.

Erstellen Sie eine Projektverbindung

Registrieren Sie den MCP-Endpunkt der Knowledge Base als Projektverbindung in Foundry. Mit dieser Verbindung kann der Agent den MCP-Endpunkt mithilfe der vom Projekt verwalteten Identität anstelle eingebetteter geheimer Schlüssel aufrufen. Wenn Sie diesen Abschnitt fertig stellen, verfügen Sie über einen wiederverwendbaren Verbindungsnamen, auf den die Agentdefinition verweist.

So erstellen Sie die Projektverbindung:

1. Rufen Sie ein Azure Resource Manager Token ab, das wie <management-access-token> in den folgenden Anforderungen verwendet werden soll.

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

2. Rufen Sie die Ressourcen-ID Ihres Projekts ab, um sie in den folgenden Anfragen als <project-resource-id> zu verwenden.

   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. Erstellen Sie die Projektverbindung mithilfe von 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. Bestätigen Sie, dass die Verbindung erstellt wurde.

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

   Diese Anforderung gibt HTTP 200 zurück. Stellen Sie sicher, dass authTypeProjectManagedIdentity ist, target mit der MCP-URL Ihrer Wissensdatenbank übereinstimmt und nameconn-kb-private-retrieval ist. Sie müssen ProjectManagedIdentity mithilfe der Rollen „Suchindex-Datenleser“ (und „Suchindex-Datenmitwirkender“, falls Schreibzugriff erforderlich ist) Autorisierungszugriff auf Ihren Azure KI-Suche-Dienst gewähren. Hilfe finden Sie unter Erstellen einer Projektverbindung.

Erstellen eines Agents und Überprüfen von Zitaten

Erstellen Sie einen Agent, der die Projektverbindung verwendet, um das Knowledge Base MCP-Tool aufzurufen, und führen Sie dann eine Überprüfungsaufforderung über eine Unterhaltung aus. Ziel ist es, das End-to-End-Abrufverhalten zu bestätigen: Der Agent antwortet von privaten Inhalten und gibt geerdete Zitate zurück, anstatt auf allgemeines Modellwissen zu vertrauen.

So erstellen Sie den Agent und überprüfen Zitate:

1. Rufen Sie ein Foundry-Zugriffstoken ab, um es in den folgenden Anfragen als <foundry-access-token> zu verwenden.

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

2. Rufen Sie Ihren Projektendpunkt ab, um ihn in den folgenden Anfragen als <project-endpoint> zu verwenden.

   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. Erstellen Sie einen Eingabeaufforderungs-Agent, der Ihre MCP-Verbindung verwendet.

   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. Erstellen Sie eine Konversation und kopieren Sie dann den Wert id aus der Antwort, um ihn im nächsten Schritt als <conversation-id> zu verwenden.

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

5. Führen Sie einen Überprüfungsprompt über den Agenten aus.

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

   Erwartetes Ergebnis:

   • Der Agent liefert eine Antwort, die auf Ihren hochgeladenen Blob-Inhalten basiert.
   • Die Antwort enthält Zitate, die auf den Inhalt der Earth at Night-Quelle verweisen.
   • Die Anforderung wird von Ihrem Client im privaten Netzwerk aus erfolgreich ausgeführt, wenn derselbe private Pfad verwendet wird, der in Teil 1 und 2 konfiguriert wurde.

Problembehandlung

Verwenden Sie die folgende Tabelle, um Fehler im Abrufüberprüfungsfluss zu isolieren.

Bereinigen von Ressourcen

Wenn Sie in Ihrem eigenen Abonnement arbeiten, ist es eine gute Idee, ein Projekt abzuschließen, indem Sie die Ressourcen entfernen, die Sie nicht mehr benötigen. Ressourcen, die nicht genutzt aber ausgeführt werden, können Sie Geld kosten.

In diesem Lernprogramm wurde eine dedizierte Ressourcengruppe mit dem Namen rg-private-retrievalverwendet. Wenn Sie die Ressourcengruppe nicht mehr benötigen, löschen Sie sie:

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

Learn more

Weitere Informationen zu den themen, die in diesem Teil des Lernprogramms behandelt werden, finden Sie in den folgenden Artikeln:

• Azure-Rollen mithilfe der Azure CLI zuweisen
• Erstellen einer Blob-Wissensquelle aus Azure Blob Storage oder ADLS Gen2
• Erstellen einer Wissensbasis
• Fügen Sie eine neue Verbindung zu Ihrem Projekt hinzu
• Schnellstart: Erstellen eines Prompt-Agents
• Verbinden einer Foundry IQ Knowledge Base mit dem Foundry Agent Service