Einrichten privater Netzwerke für den Foundry-Agent-Dienst

Hintergrundinformationen zur Netzwerkarchitektur, zur Subnetzgröße und zum IP-Zuordnungsmodell hinter diesen Schritten finden Sie unter Deep dive into Foundry Agent Service Networking.

Der Foundry Agent Service bietet ein Standardsetup mit privater Netzwerkumgebung . Dieses Setup erstellt eine isolierte Netzwerkumgebung, die den sicheren Zugriff auf Daten ermöglicht und gleichzeitig die vollständige Kontrolle über Ihre Netzwerkinfrastruktur erhält.

Standardmäßig stellt das Standardsetup mit privaten Netzwerken folgendes sicher:

• Kein öffentlicher Ausgang: Die foundationale Infrastruktur bietet die richtige Authentifizierung und Sicherheit für Ihre Agents und Tools, ohne dass eine vertrauenswürdige Dienstumgehung erforderlich ist.
• Subnetzintegration: Sie stellen ein delegiertes Subnetz aus Ihrem virtuellen Netzwerk bereit. Die Plattform verbindet agent compute mit diesem Subnetz und ermöglicht die lokale Kommunikation mit Ihren Azure Ressourcen innerhalb desselben virtuellen Netzwerks.
• Zugriff auf private Ressourcen: Wenn Ihre Ressourcen im Internet als privat und nicht erkennbar gekennzeichnet sind, kann das Plattformnetzwerk weiterhin darauf zugreifen, wenn die erforderlichen Anmeldeinformationen und Autorisierung vorhanden sind.

Wenn Sie nicht über ein vorhandenes virtuelles Netzwerk verfügen, kann das Standardsetup mit privatem Netzwerkfluss die erforderliche Netzwerkinfrastruktur für Sie bereitstellen.

Voraussetzungen

• Ein Azure-Abonnement – Create one for free.

• Stellen Sie sicher, dass die Person, die das Konto und das Projekt erstellt, über die Rolle Azure AI-Kontobesitzer auf Abonnementebene verfügt.

• Der Benutzer, der dieses Setup erstellt, muss auch über Berechtigungen zum Zuweisen von Rollen zu erforderlichen Ressourcen verfügen (Azure Cosmos DB, Azure KI-Suche, Azure Storage).

  • Die integrierte Rolle ist rollenbasierter Zugriffsadministrator.
  • Alternativ erfüllt auch die Rolle " Besitzer " auf Abonnementebene diese Anforderung.
  • Die erforderliche Schlüsselberechtigung lautet: Microsoft.Authorization/roleAssignments/write

• Python 3,9 oder höher

• Stellen Sie nach der Konfiguration der Agentumgebung sicher, dass jedem Teammitglied, das den Agent-Playground oder das SDK zum Erstellen oder Bearbeiten von Agents verwenden möchte, die integrierte Azure AI UserRBAC-Rolle für das Projekt zugewiesen wurde.

  • Die mindeste Anzahl der erforderlichen Berechtigungen ist: Agents/*/read, agents/*/action, agents/*/delete

• Registrieren Sie Anbieter. Die folgenden Anbieter müssen registriert werden:

  • Microsoft.KeyVault
  • Microsoft.CognitiveServices
  • Microsoft.Storage
  • Microsoft.MachineLearningServices
  • Microsoft.Search
  • Microsoft.Network
  • Microsoft.App
  • Microsoft.ContainerService
  • So verwenden Sie das Bing Search-Tool: Microsoft.Bing

     az provider register --namespace 'Microsoft.KeyVault'
     az provider register --namespace 'Microsoft.CognitiveServices'
     az provider register --namespace 'Microsoft.Storage'
     az provider register --namespace 'Microsoft.MachineLearningServices'
     az provider register --namespace 'Microsoft.Search'
     az provider register --namespace 'Microsoft.Network'
     az provider register --namespace 'Microsoft.App'
     az provider register --namespace 'Microsoft.ContainerService'
     # only to use Grounding with Bing Search tool
     az provider register --namespace 'Microsoft.Bing'
  

Konfigurieren einer netzwerksicherten Umgebung

Sie können dieses Setup im Azure Portal erstellen oder mit Bicep oder Terraform bereitstellen.

Auf einer übergeordneten Ebene umfasst die Bereitstellung die folgenden Schritte:

1. Wählen Sie die Ziel-Azure-Region für Ihre Foundry-Ressourcen aus.
2. Entscheiden Sie, ob Sie Ihr eigenes VNet und Subnetz verwenden oder automatisch bereitgestellte Netzwerke verwenden möchten.
3. Wenn Sie Ihr eigenes VNet mitbringen, sammeln Sie Ihre VNet- und Subnetzressourcen-IDs.
4. Erstellen Sie das Setup im Azure-Portal, oder stellen Sie es mithilfe von Bicep oder Terraform bereit.
5. Überprüfen Sie die Bereitstellung (siehe Überprüfen der Bereitstellung).

Die Einrichtung stellt die folgenden Ressourcen bereit, sofern Sie nicht Ihre eigenen Ressourcen mitbringen:

• Ein Foundry-Konto und ein Foundry-Projekt.
• Die Bereitstellung eines gpt-4o-Modells.
• Azure Storage, Azure Cosmos DB und Azure KI-Suche zum Speichern von Dateien, Threads und Vektordaten.
• Diese Ressourcen sind mit Ihrem Projekt verbunden.
• Von Microsoft verwaltete Verschlüsselungsschlüssel für das Speicherkonto und das kognitive Konto (Foundry) werden standardmäßig verwendet.

Wählen Sie Ihre bevorzugte Bereitstellungsmethode mithilfe der folgenden Registerkarten aus.

Überprüfen Sie die Bereitstellung

Überprüfen Sie nach Abschluss der Bereitstellung, ob alle Ressourcen ordnungsgemäß konfiguriert sind:

1. Navigieren Sie im Azure-Portal zu Ihrem VNet >Subnets und überprüfen Sie, ob das Agent-Subnetz die Delegierung an Microsoft.App/environments anzeigt.
2. Öffentlichen Netzwerkzugriff überprüfen: Öffnen Sie jede Ressource (Foundry, Azure KI-Suche, Azure Storage, Azure Cosmos DB) und bestätigen Sie, dass der Öffentliche Netzwerkzugriff auf Deaktiviert gesetzt ist.
3. Überprüfen der DNS-Auflösung des privaten Endpunkts: Von einem Computer, der mit dem VNet verbunden ist, führen Sie die Ausführung nslookup für jeden Endpunkt aus, der in der Zusammenfassung der DNS-Zonenkonfigurationen aufgeführt ist. Stellen Sie sicher, dass jeder Name in eine private IP-Adresse aufgelöst wird (10.x, 172.16-31.x oder 192.168.x).
4. Testen Sie die Agentkonnektivität: Greifen Sie über das VNet auf Ihr Foundry-Projekt zu (siehe Zugriff auf Ihre gesicherten Agents), und bestätigen Sie, dass Sie einen Agent erstellen und ausführen können.

Einschränkungen

• Beschränkung der Subnetz-IP-Adresse: Beide Subnetze müssen IP-Bereiche innerhalb gültiger RFC1918 privaten IPv4-Bereiche aufweisen: 10.0.0.0/8, , 172.16-31.0.0/12oder 192.168.0.0/16. Öffentliche IP- und CGNAT-Adressbereiche 100.64.0.0–100.127.255.255 werden nicht unterstützt.
• Exklusivität des Agent-Subnetzs: Das Agent-Subnetz kann nicht von mehreren Foundry-Ressourcen gemeinsam genutzt werden. Jede Foundry-Ressource muss ein dediziertes Agent-Subnetz verwenden.
• Agent-Subnetzgröße: Die empfohlene Größe des delegierten Agent-Subnetzes ist /24 (256 Adressen) aufgrund der Delegierung des Subnetzes an Microsoft.App/environments. Weitere Informationen zur Subnetzgröße finden Sie unter Configuring virtual networks for Azure Container Apps.
• Egress-Firewall-Zulassungsliste für Agenten: Wenn Sie eine Azure Firewall in Ihren netzwerkintegrierten standardmäßigen sicheren Agenten integrieren, tragen Sie die unter Managed Identity im Artikel Integration mit Azure Firewall aufgeführten vollqualifizierten Domänennamen (FQDNs) in die Zulassungsliste ein oder fügen Sie das Servicetag AzureActiveDirectory hinzu.
  • Stellen Sie sicher, dass in der Firewall keine TLS-Überprüfung erfolgt, die ein selbstsigniertes Zertifikat hinzufügen kann. Überprüfen Sie bei Fehlern, ob Datenverkehr in der Firewall landet und welcher Datenverkehr blockiert wird.
• Die Foundry-Ressource muss in derselben Region wie das virtuelle Netzwerk (VNet) bereitgestellt werden. Andere Azure Ressourcen wie Azure Cosmos DB, Azure KI-Suche und Azure Storage können in verschiedenen Regionen bereitgestellt werden. Berücksichtigen Sie die Kostenauswirkungen von regionsübergreifenden Bereitstellungen.
• Verfügbarkeit der Region:
  • Unterstützte Regionen für Modellbereitstellungen finden Sie unter: Azure Unterstützung der OpenAI-Modellregion.
• Azure Blob Storage: Die Verwendung von Azure Blob Storage Dateien mit dem Tool "Dateisuche" wird nicht unterstützt.
• Bodenierung mit Bing Search: Nur die folgenden Regionen werden unterstützt: Westeuropa, Kanada Ost, Schweiz Nord, Spanien Zentral, VAE Nord, Korea Zentral, Polen Zentral, Südostasien, West-USA, West-USA 2, West-USA 3, Ost-USA, Ost-USA 2, Zentral-USA, Südindien, Japan Ost, VEREINIGTEs Königreich Süd, Frankreich Zentral, Norwegen Ost, Australien, Kanada, Zentral, Schweden, Südafrika Nord, Italien Nord, Brasilien Süd
• Löschen Sie die Netzwerkeinfügung: Wenn Sie Die Foundry-Ressource und den Standard-Agent mit gesicherter Netzwerkeinrichtung löschen möchten, löschen Sie die Foundry-Ressource und das virtuelle Netzwerk zuletzt. Bevor Sie das virtuelle Netzwerk löschen, löschen und bereinigen Sie Ihre Foundry-Ressource.
• Virtual Network Injection bei gehosteten Agents: Für gehostete Agents muss die virtuelle Netzwerkkonfiguration (Virtual Network Injection) einbezogen werden, wenn Sie das Foundry-Konto zum ersten Mal erstellen. Das Hinzufügen der Netzwerkinjektion zu einem vorhandenen Foundry-Konto nach der Erstellung wird für gehostete Agenten nicht unterstützt.
• Hosted-Agent-Containerregistrierung hinter einem privaten Netzwerk: Für gehostete Agents kann der Azure Container Registry (ACR), der das Containerimage des Agents speichert, derzeit nicht hinter einem privaten Netzwerk platziert werden (privater Endpunkt mit deaktiviertem öffentlichem Netzwerkzugriff). Der ACR muss über seinen öffentlichen Endpunkt erreichbar sein, damit die Plattform das Image abrufen kann.

Architekturdiagramm

Überprüfen der bereitgestellten Netzwerkressourcen

Die folgenden Ressourcen werden automatisch bereitgestellt, wenn Sie Standardsetup mit privaten Netzwerken verwenden, es sei denn, Sie bringen eigene:

Netzwerkinfrastruktur

• Ein virtuelles Netzwerk (192.168.0.0/16)
• Agent-Subnetz (192.168.0.0/24): Hosts mit Agent-Client
• Subnetz des privaten Endpunkts (192.168.1.0/24): Hosting privater Endpunkte

Virtuelle Netzwerkfunktionen

Ihr virtuelles Netzwerk steuert, welche Endpunkte API-Aufrufe an Ihre Ressourcen tätigen können. Der Azure-Dienst lehnt API-Aufrufe von Geräten außerhalb Ihres definierten Netzwerks automatisch ab.

Netzwerkregeln

Alle Konten und ihre entsprechenden Projekte sind standardmäßig mit dem Flag "Deaktiviert" des öffentlichen Netzwerks geschützt, das explizite Konfiguration erfordert, um den Zugriff über private Endpunkte zu ermöglichen. Diese Regeln gelten für alle Protokolle, einschließlich REST und WebSocket.

Zusammenfassung der DNS-Zonenkonfigurationen

Verwenden Sie zum Erstellen einer bedingten Weiterleitung im DNS-Server an den Azure DNS Virtual Server die Liste der in der obigen Tabelle erwähnten Zonen. Die AZURE DNS IP-Adresse des virtuellen Servers ist 168.63.129.16.

Zugriff auf Ihre gesicherten Agents

Nachdem die Bereitstellung abgeschlossen ist, können Sie auf Ihr Foundry-Projekt hinter einem virtuellen Netzwerk zugreifen, indem Sie eine der folgenden Methoden verwenden:

• Azure VPN Gateway: Verbindet lokale Netzwerke über eine private Verbindung mit dem virtuellen Netzwerk. Die Verbindung erfolgt über das öffentliche Internet. Es gibt zwei Arten von VPN-Gateways, die Sie verwenden können:
  • Point-to-Site: Jeder Clientcomputer verwendet einen VPN-Client, um eine Verbindung mit dem virtuellen Netzwerk herzustellen.
  • Standort-zu-Standort: Ein VPN-Gerät verbindet das virtuelle Netzwerk mit Ihrem lokalen Netzwerk.
• ExpressRoute: Verbindet lokale Netzwerke über eine private Verbindung mit der Cloud. Die Verbindung erfolgt über einen Verbindungsanbieter.
• Azure Bastion: In diesem Szenario erstellen Sie einen Azure virtuellen Computer (manchmal als Sprungfeld bezeichnet) innerhalb des virtuellen Netzwerks. Anschließend stellen Sie mithilfe von Azure Bastion eine Verbindung mit dem virtuellen Computer her. Bastion ermöglicht es Ihnen, eine Verbindung mit dem virtuellen Computer über eine RDP- oder SSH-Sitzung über Ihren lokalen Webbrowser herzustellen. Anschließend verwenden Sie das Sprungfeld als Entwicklungsumgebung. Da es sich im virtuellen Netzwerk befindet, kann er direkt auf den Arbeitsbereich zugreifen.

Häufig gestellte Fragen

Welchen Adressbereich sollte ich für das virtuelle Gesamtnetzwerk verwenden?

Der Adressbereich des virtuellen Netzwerks kann ein beliebiger privater IP-Bereich sein, der ausreichend Adressraum sowohl für das Subnetz des delegierten Agents als auch für das private Endpunkt-Subnetz bietet.

Kann ich peering-verbundene virtuelle Netzwerke verwenden oder Ressourcen in verschiedenen virtuellen Netzwerken unterbringen?

Gekoppelte virtuelle Netzwerke werden unterstützt, aber die Datenübertragungskosten können steigen.

Können mehrere Foundry-Ressourcen dasselbe virtuelle Netzwerk und dasselbe Subnetz wiederverwenden?

Ja, dasselbe VNET, aber nicht dasselbe Subnetz. Mehrere Foundry-Ressourcen können dasselbe virtuelle Netzwerk wiederverwenden. Jede Foundry-Ressource erfordert jedoch ein eigenes dediziertes Agent-Laufzeit-Subnetz. Das Agent-Subnetz kann nicht für mehrere Foundry-Ressourcen freigegeben werden.

Muss sich das virtuelle Netzwerk in derselben Ressourcengruppe wie die Foundry-Ressource befinden?

Nein. Das virtuelle Netzwerk und die Foundry-Ressource müssen sich nicht in derselben Ressourcengruppe befinden, sie müssen sich jedoch in derselben Region befinden.

Handbuch zur Problembehandlung

In diesem Leitfaden finden Sie Informationen zum Beheben von Fehlern während oder nach einer Standard-Agent-Bereitstellung, unabhängig davon, ob Sie das Azure-Portal, Bicep oder Terraform verwendet haben.

Bereitstellungsfehler

"CreateCapabilityHostRequestDto is invalid: Agents CapabilityHost supports a single, non empty value for vectorStoreConnections property."

"Agents CapabilityHost supports a single, non empty value for storageConnections property."

"Agents CapabilityHost supports a single, non empty value for threadStorageConnections property."

Lösung: Die Bereitstellung aller Verbindungen mit allen Bring-your-Own-Ressourcen (BYO) erfordert Verbindungen mit allen BYO-Ressourcen. Sie können keinen gesicherten Standard-Agent in Foundry erstellen, ohne dass alle drei Ressourcen bereitgestellt wurden.

"Provided subnet must be of the proper address space. Please provide a subnet which has address space in the range of 172 or 192."

Lösung: Sie verwenden keinen geeigneten IP-Bereich für Ihr delegiertes Agent-Subnetz. Stellen Sie sicher, dass Sie einen gültigen privaten IP-Adressraum verwenden. Gültige RFC1918 Bereiche umfassen 10.0.0.0/8, 172.16-31.0.0/12und 192.168.0.0/16. Der Text der Fehlermeldung listet möglicherweise nicht alle gültigen Bereiche auf.

"Subscripton is not registered with the required resource providers, please register with the resource providers Microsoft.App and Microsoft.ContainerService."

Lösung: Sie fehlen die richtige Ressourcenregistrierung. Stellen Sie sicher, dass die erforderlichen Ressourcen in Ihrem Mandanten registriert sind.

"Failed to create Aml RP virtual workspace due to System.Exception: Failed async operation." Oder "The resource operation completed with terminal provisioning state 'Failed'. Capability host operation failed."

Lösung: Dies ist ein Catch-All-Fehler. Erstellen Sie eine Supportticketanfrage, um Ihr Setup zu untersuchen. Überprüfen Sie den Funktionshost auf den Fehler.

"Subnet requires any of the following delegation(s) [Microsoft.App/environments] to reference service association link /subscriptions/11111-aaaaa-2222-bbbb-333333333/resourceGroups/agentRANGEChange/providers/Microsoft.Network/virtualNetworks/my-agent-vnet/subnets/agent-subnet/serviceAssociationLinks/legionservicelink."

Solution: Dieser Fehler wird angezeigt, wenn Sie versuchen, das gesicherte Standardvorlagensetup in Azure zu löschen und nicht ordnungsgemäß alle Ressourcen zu löschen. Eine Lösung besteht darin, im Azure Portal zur Seite "Foundry"-Ressource zu navigieren und Gelöschte Ressourcen verwalten auszuwählen. Löschen Sie von dort aus die Ressource, mit der der Agent für dieses virtuelle Netzwerk verknüpft war. Die andere Option besteht darin, das deleteCaphost.sh Skript in der gesicherten Standardvorlage auszuführen.

"Timeout of 60000ms exceeded" error when loading the Agent pages in the Foundry project

Solution: Das Foundry-Projekt hat Probleme bei der Kommunikation mit Azure Cosmos DB zum Erstellen von Agents. Überprüfen Sie die Verbindung mit Azure Cosmos DB (Privater Endpunkt und DNS).

DNS-Auflösung des privaten Endpunkts schlägt fehl

Lösung: Wenn Ressourcen nicht über private Endpunkte erreichbar sind, überprüfen Sie, ob jede private DNS-Zone mit Ihrem virtuellen Netzwerk verknüpft ist. Bestätigen Sie, dass bedingte Weiterleitungen auf die AZURE DNS IP-Adresse des virtuellen Servers 168.63.129.16 verweisen. Führen Sie auf einer Maschine, die mit dem VNet verbunden ist, nslookup <resource-fqdn> aus und stellen Sie sicher, dass jeder Name in eine private IP-Adresse aufgelöst wird.

Nächste Schritte

Sie haben jetzt erfolgreich ein netzwerksicheres Konto und projekt konfiguriert. Verwenden Sie die Schnellstartanleitung , um Ihren ersten Agent zu erstellen.

Weitere Informationen zur Konfiguration und Optionen für die Netzwerkisolation finden Sie unter Konfigurieren der Netzwerkisolation.