Nastavení privátních sítí pro službu Foundry Agent Service

Základní informace o síťové architektuře, nastavení velikosti podsítě a modelu přidělování IP adres za těmito kroky najdete v podrobných informacích o sítích služby Foundry Agent Service.

Tento článek popisuje dva přístupy. Pomocí portálu nebo šablon nasaďte síťově zabezpečené prostředí Foundry pomocí Bicepu nebo Terraformu. Použijte postup Azure Developer CLI k umístění závislostí projektu hostovaného agenta azd za privátní koncové body. Zvolte metodu selektorem.

Služba Foundry Agent nabízí standardní nastavení s privátním síťovým prostředím . Toto nastavení vytvoří izolované síťové prostředí, které umožňuje zabezpečený přístup k datům při zachování úplné kontroly nad vaší síťovou infrastrukturou.

Standardní nastavení s privátními sítěmi ve výchozím nastavení zajišťuje:

  • Žádné veřejné výchozí přenosy dat: Základní infrastruktura poskytuje správné ověřování a zabezpečení pro vaše agenty a nástroje, aniž by bylo nutné obejít důvěryhodné služby.
  • Integrace podsítě: Zadáte delegovanou podsíť z vaší virtuální sítě. Platforma připojuje výpočetní prostředky agenta k této podsíti a umožňuje místní komunikaci s vašimi Azure prostředky ve stejné virtuální síti.
  • Privátní přístup k prostředkům: Pokud jsou vaše prostředky označené jako soukromé a nepoužívatelné z internetu, může k nim síť platformy přistupovat i v případě, že jsou potřebné přihlašovací údaje a autorizace zavedené.

Pokud nemáte existující virtuální síť, standardní nastavení s tokem privátní sítě vám může zřídit potřebnou síťovou infrastrukturu.

Požadavky

  • Předplatné Azure – Kreate si ho zdarma.

  • Ujistěte se, že osoba, která vytváří účet a projekt, má v rozsahu předplatného roli Vlastník účtu Foundry.

    Důležité

    Nedávno byly přejmenovány role Foundry RBAC. Foundry User, Foundry Owner, Foundry Account Owner a Foundry Project Manager se dříve nazývaly Uživatel Azure AI, Vlastník Azure AI, Vlastník účtu Azure AI a Správce projektů Azure AI. Během zavádění přejmenování se stále můžou zobrazovat předchozí názvy na některých místech. ID rolí a základní oprávnění se při přejmenování nezmění.

  • Uživatel, který vytváří toto nastavení, musí mít také oprávnění k přiřazování rolí požadovaným prostředkům (Azure Cosmos DB, Azure AI Vyhledávač, Azure Storage).

    • Předdefinovaná role potřebná je Role Based Access Administrator.
    • Alternativně také požadavek splňuje role Vlastník na úrovni předplatného.
    • Potřebné oprávnění ke klíči je: Microsoft.Authorization/roleAssignments/write

  • Python 3.9 nebo novější

  • Jakmile je prostředí agenta nakonfigurované, ujistěte se, že každý člen týmu, který chce k vytvoření nebo úpravě agentů použít Agent Playground nebo SDK, má přiřazenou předdefinovanou roli RBACuživatele Foundry pro daný projekt.

    • Minimální požadovaná sada oprávnění je: agents/*/read, agents/*/action, agents/*/delete.

  • Zaregistrujte poskytovatele. Musí být zaregistrovaní následující poskytovatelé:

    • Microsoft.KeyVault
    • Microsoft.CognitiveServices
    • Microsoft.Storage
    • Microsoft.MachineLearningServices
    • Microsoft.Search
    • Microsoft.Network
    • Microsoft.App
    • Microsoft.ContainerService
    • Použití nástroje Bingu pro vyhledávání: 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'

Důležité

Standardní nastavení vyžadují, abyste si přinesli vlastní prostředky (BYO), aby všechna data agenta zůstala ve vašem Azure tenantu.

Prostředky BYO zahrnují: Azure Storage, Azure AI Vyhledávač a Azure Cosmos DB.

Všechna data zpracovávaná službou Foundry Agent Service se v těchto prostředcích automaticky ukládají v klidovém stavu, což vám pomůže splnit požadavky na dodržování předpisů a standardy zabezpečení podniku.

Konfigurace prostředí zabezpečeného sítí

Toto nastavení můžete vytvořit na portálu Azure nebo ho nasadit pomocí Bicep nebo Terraformu.

Nasazení na vysoké úrovni zahrnuje tyto kroky:

  1. Zvolte cílovou Azure oblast pro vaše prostředky Foundry.
  2. Rozhodněte se, jestli chcete použít vlastní virtuální síť a podsíť, nebo použít automaticky zřízené sítě.
  3. Pokud přinášíte svou vlastní virtuální síť (VNet), shromážděte ID prostředků virtuální sítě a podsítě.
  4. Vytvořte nastavení na portálu Azure nebo ho nasaďte pomocí Bicep nebo Terraformu.
  5. Ověřte nasazení (viz Ověření nasazení).

Nastavení zřídí následující prostředky (pokud nepřinesete vlastní prostředky):

  • Účet Foundry a projekt Foundry.
  • Nasazení modelu gpt-4o.
  • Azure Storage, Azure Cosmos DB a Azure AI Vyhledávač pro ukládání souborů, vláken a vektorových dat.
  • Tyto zdroje jsou připojené k vašemu projektu.
  • Šifrovací klíče spravované Microsoftem pro účet úložiště a účet Cognitive (Foundry) se používají ve výchozím nastavení.

Pomocí následujících karet vyberte upřednostňovanou metodu nasazení:

  1. Na portálu Azure vyhledejte Foundry a vyberte Vytvořit prostředek.
  2. Po nakonfigurování karty Základy vyberte kartu Úložiště a pak v části Agentní služba vyberte Vybrat prostředky.
    • Vyberte nebo vytvořte účet úložiště, prostředek Azure AI Vyhledávač a prostředek Azure Cosmos DB. Pokud používáte injektáž virtuální sítě, musíte použít vlastní úložiště, Azure AI Vyhledávač a Azure Cosmos DB prostředky k vytvoření standardního agenta s kompletní izolací virtuální sítě.
  3. Po nakonfigurování karty Úložiště vyberte kartu Síť a pak vyberte možnost Zakázáno pro veřejný přístup.
  4. V části Privátní koncový bod vyberte + Přidat privátní koncový bod.
  5. Při procházení formulářů pro vytvoření privátního koncového bodu nezapomeňte:
    • V části Základy vyberte stejnou oblast jako vaše virtuální síť.
    • Ve formuláři Virtual Network vyberte virtual network a podsíť, ke které se chcete připojit.

    Poznámka

    V uživatelském rozhraní portálu by měl být cíl, na který vytvoříte privátní koncový bod, označený jako "účet". Po zobrazení výzvy vyberte zdroj Foundry.

  6. Po nastavení příchozího privátního koncového bodu se zobrazí nový rozevírací seznam pro nastavení injektáže virtuální sítě. V prvním rozevíracím seznamu vyberte virtuální síť a poté vyberte subnet delegovaný na Microsoft.App/environments s velikostí podsítě /27 nebo větší. Pro injektáž se vyžaduje toto delegování a velikost podsítě.
  7. Pokračujte ve formulářích a vytvořte projekt. Až se dostanete na kartu Zkontrolovat a vytvořit , zkontrolujte nastavení a vyberte Vytvořit a vytvořte projekt.
  8. Pokračujte v kontrolách v části Ověření nasazení.

Poznámka

Privátní koncové body pro Azure AI Vyhledávač, Azure Storage a Azure Cosmos DB se při nasazení prostředku Foundry nevytvořily automaticky. Na stránkách jednotlivých prostředků na portálu Azure se ujistěte, že vytváříte pro tyto prostředky privátní koncové body samostatně.

Ověření nasazení

Po dokončení nasazení ověřte, že jsou všechny prostředky správně nakonfigurované:

  1. Potvrďte delegování podsítě: Na portálu Azure přejděte na vaši VNet >podsítě a ověřte, že podsíť agenta zobrazuje delegování na Microsoft.App/environments.
  2. Zkontrolujte přístup k veřejné síti: Otevřete každý prostředek (Foundry, Azure AI Vyhledávač, Azure Storage, Azure Cosmos DB) a potvrďte, že přístup k veřejné síti je nastaven na Zakázáno.
  3. Ověřte vyřešení DNS privátního koncového bodu: Z počítače připojeného k virtuální síti spusťte příkaz nslookup pro každý koncový bod uvedený v souhrnu konfigurací zóny DNS.
  4. Připojení testovacího agenta: Přístup k projektu Foundry z virtuální sítě (viz Přístup k zabezpečeným agentům) a potvrzení, že můžete vytvořit a spustit agenta.
  5. Konfigurace přiřazení rolí: Spuštěním následujících příkazů přiřaďte požadované role. První přiřazení uděluje roli Managed Identity Operator uživatelem přiřazené spravované identitě a druhé uděluje roli Network Contributor ve vzdálené síti VNet pro přístup mezi tenanty.
az role assignment create \
   --assignee <your-principal-id> \
   --role "Managed Identity Operator" \
   --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<id>"

 az role assignment create \
   --assignee <service-principal-object-id-in-remote-tenant> \
   --role "Network Contributor" \
   --scope "/subscriptions/<remote-subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Network/virtualNetworks/<vnet-name>"

Omezení

  • Omezení IP adres virtuální sítě a podsítě:
    • Delegovaná podsíť služby agenta musí mít rozsahy IP adres v rámci platných RFC1918 privátních rozsahů IPv4: 10.0.0.0/8, 172.16-31.0.0/12nebo 192.168.0.0/16 označované také jako privátní třída A, třída B a rozsahy IP adres třídy C.
    • Rozsahy IP adres privátní třídy A (10.0.0.0/8) se podporují jenom v konkrétních oblastech. Seznam oblastí, které podporují rozsahy třídy A, najdete v tématu Podporované oblasti. Pomocí rozsahů třídy B (172.16.x.x) nebo C (192.168.x.x) nasaďte službu agenta v jiných oblastech.
    • Rozsahy veřejných IP adres jako 44.x.x.x a rozsahy 100.64.0.0adres CGNAT –100.127.255.255 nejsou podporované pro delegovanou podsíť služby agenta.
    • Ujistěte se, že adresní prostory vaší virtuální sítě se nepřekrývají s žádnými existujícími sítěmi ve vašem prostředí Azure nebo vyhrazenými rozsahy IP adres, například: 169.254.0.0/16, , 172.30.0.0/16, 172.31.0.0/16192.0.2.0/240.0.0.0/8127.0.0.0/8100.100.0.0/17100.100.192.0/19100.100.224.0/19. 100.64.0.0/11 Tento požadavek zahrnuje všechny adresní prostory, které máte ve vaší virtuální síti, a pokud jich máte více než jeden, také propojené virtuální sítě.
  • Výlučnost podsítě agenta: Podsíť agenta nemůže být sdílena více zdroji Foundry. Každý prostředek Foundry musí používat vyhrazenou podsíť pro agenta.
  • : Doporučená velikost delegované podsítě agenta je /24 (256 adres) kvůli delegování podsítě na Microsoft.App/environments. Další informace o velikosti podsítě najdete v tématu Konfigurování virtuálních sítí pro Azure Container Apps.
  • Povolení odchozího provozu agenta v podsíti: Pokud integrujete Azure Firewall se standardním agentem zabezpečeným privátní sítí, zařaďte do seznamu povolených plně kvalifikované názvy domén (FQDN) uvedené v části Managed Identity v článku Integrace s Azure Firewall, nebo přidejte značku služby AzureActiveDirectory.
    • Ověřte, že v bráně firewall nedochází k žádné kontrole TLS, která by mohla přidat samopodepsaný certifikát. Během selhání zkontrolujte, jestli do brány firewall přichází nějaký provoz a jaký provoz je blokován.
    • U nasazení agenta zdrojového kódu povolte také koncové body nasazení uvedené v požadavcích brány firewall pro privátní virtuální sítě.
  • Prostředek Foundry musí být nasazen ve stejné oblasti jako virtuální síť. Další Azure prostředky, jako jsou Azure Cosmos DB, Azure AI Vyhledávač a Azure Storage, je možné nasadit v různých oblastech. Vezměte v úvahu náklady na nasazení mezi oblastmi.
  • Dostupnost oblastí:
  • Azure Blob Storage: Použití souborů Azure Blob Storage pomocí nástroje Hledání souborů není podporované.
  • Omezení souboru interpretu kódu: V konfiguraci privátní sítě (BYO) funguje interpret kódu pouze ve scénářích, které nezahrnují nahrávání nebo stahování souborů. Nástroj nemůže načíst soubory z účtu úložiště v tomto nastavení. Pokud potřebujete použít soubory s interpretem kódu, musíte pomocí sady SDK vytvořit kontejner explicitně s požadovanými soubory a pak předat interpretu container_id kódu. Toto alternativní řešení je dostupné pouze prostřednictvím sady SDK; Uživatelské rozhraní portálu Foundry ho nepodporuje.
  • Vyhledávání Bingem: Podporují se pouze následující oblasti: Západní Evropa, Kanada – východ, Švýcarsko – sever, Španělsko – střed, Spojené arabské emiráty, Korea – střed, Polsko – střed, Jihovýchodní Asie, USA – západ, USA – západ 2, USA – západ 3, USA – východ, USA – východ 2, USA – střed, Indie – střed, Japonsko – východ, Velká Británie – jih, Francie – střed, Norsko – východ, Austrálie – východ, Kanada – střed, Švédsko – střed, Švédsko – střed, Jihoafrická republika – sever, Itálie – sever, Brazílie – jih
  • Odstranění síťové injekce: Pokud chcete odstranit prostředek Foundry a agenta Standard se zabezpečeným nastavením sítě, nejdříve odstraňte agenta Standard, pak prostředek Foundry, a nakonec virtuální síť. Před odstraněním virtuální sítě odstraňte a vyprázdněte prostředek Foundry.
  • Injektáž virtuální sítě hostovaného agenta: Pro hostované agenty musí být při prvním vytvoření účtu Foundry zahrnuta konfigurace virtuální sítě (injektáž sítě). Přidání síťové injektáže k existujícímu účtu Foundry po jeho vytvoření není pro hostované agenty podporováno.
  • Registr kontejneru hostovaného agenta za privátní sítí: Podpora Azure Container Registry (ACR) za privátní sítí (privátní koncový bod se zakázaným přístupem k veřejné síti) závisí na tom, kdy byl vytvořen projekt Foundry. Projekty vytvořené po 25. červnu 2026 podporují privátní ACR. Projekty vytvořené před tímto datem vyžadují, aby služba ACR byla dostupná přes jeho veřejný koncový bod, aby platforma mohl image stáhnout. Stávající projekty nejsou ovlivněné a nadále používají přístup k veřejné síti.

Diagram architektury

Diagram znázorňující architekturu virtuální sítě pro privátní sítě Služby agenta Foundry, včetně podsítě agenta, podsítě privátního koncového bodu a privátních zón DNS

Kontrola zřízených síťových prostředků

Při použití standardního nastavení s privátním síťováním se automaticky zřídí následující prostředky, pokud si nepřinášíte vlastní prostředky:

Síťová infrastruktura

  • Virtuální síť (192.168.0.0/16)
  • Podsíť agenta (192.168.0.0/24): Hostuje klienta agenta
  • Podsíť privátního koncového bodu (192.168.1.0/24): Hostuje privátní koncové body

Možnosti virtuální sítě

Vaše virtuální síťe řídí, které koncové body můžou provádět požadavky na rozhraní API k vašim prostředkům. Služba Azure automaticky odmítne volání rozhraní API ze zařízení mimo vaši definovanou síť.

Pravidla sítě

Všechny účty a jejich odpovídající projekty jsou ve výchozím nastavení chráněny příznakem Zakázaný přístup k veřejné síti , který vyžaduje explicitní konfiguraci pro povolení přístupu prostřednictvím privátních koncových bodů. Tato pravidla platí pro všechny protokoly, včetně REST a WebSocket.

Souhrn konfigurací zón DNS

typ prostředku Private Link Dílčí zdroj název zóny Privátní DNS Veřejné služby pro předávání zón DNS
Slévárna účet privatelink.cognitiveservices.azure.com
privatelink.openai.azure.com
privatelink.services.ai.azure.com		 cognitiveservices.azure.com
openai.azure.com
services.ai.azure.com
Azure AI Vyhledávač vyhledávací služba privatelink.search.windows.net search.windows.net
Azure Cosmos DB Sql privatelink.documents.azure.com documents.azure.com
Azure Storage objekt blob privatelink.blob.core.windows.net blob.core.windows.net

Chcete-li vytvořit podmíněný předávací nástroj na serveru DNS na virtuální server Azure DNS, použijte seznam zón uvedených v předchozí tabulce. IP adresa virtuálního serveru Azure DNS je 168.63.129.16.

Přístup k zabezpečeným agentům

Po dokončení nasazení můžete k projektu Foundry za virtuální sítí přistupovat pomocí jedné z následujících metod:

  • Službu Azure VPN Gateway: Připojí místní sítě k virtuální síti přes privátní připojení. Připojení se provádí přes veřejný internet. Existují dva typy bran VPN, které můžete použít:
    • Point-to-site: Každý klientský počítač používá klienta VPN pro připojení k virtuální síti.
    • Site-to-site: Zařízení VPN připojí virtuální síť k místní síti.
  • ExpressRoute: Připojí místní sítě k cloudu přes privátní připojení. Připojení se provádí pomocí poskytovatele připojení.
  • Azure Bastion: V tomto scénáři vytvoříte virtuální počítač Azure (někdy označovaný jako jump box) ve virtuální síti. Pak se k virtuálnímu počítači připojíte pomocí Azure Bastion. Bastion umožňuje připojení k virtuálnímu počítači pomocí relace RDP nebo SSH z místního webového prohlížeče. Pak jako vývojové prostředí použijete jump box. Vzhledem k tomu, že je uvnitř virtuální sítě, má přímý přístup k pracovnímu prostoru.

časté otázky

Jaký rozsah adres mám použít pro celkovou virtuální síť?

Rozsah adres virtuální sítě může být libovolný rozsah privátních IP adres, který ponechá dostatek adresního prostoru pro podsíť delegovaného agenta i podsíť privátního koncového bodu.

Můžu použít partnerské virtuální sítě nebo umístit prostředky do různých virtuálních sítí?

Partnerské virtuální sítě jsou podporované, ale můžou se zvýšit náklady na přenos dat.

Může více prostředků Foundry znovu použít stejnou virtuální síť a podsíť?

Ano, stejná virtuální síť, ale ne stejná podsíť. Více prostředků Foundry může znovu použít stejnou virtuální síť. Každý prostředek Foundry ale vyžaduje vlastní vyhrazenou podsíť pro běhové prostředí agenta. Podsíť agenta se nedá sdílet napříč několika prostředky Foundry.

Musí být virtuální síť ve stejné skupině prostředků jako prostředek Foundry?

Ne. Virtuální síť a prostředek Foundry nemusí být ve stejné skupině prostředků, ale musí být ve stejné oblasti.

Průvodce odstraňováním potíží

V tomto průvodci najdete informace o řešení chyb během nebo po nasazení agenta Standard, ať už jste použili portál Azure, Bicep nebo Terraform.

Chyby nasazení

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

Řešení: Poskytování všech připojení ke všem prostředkům BYO (Bring-your-Own) vyžaduje připojení ke všem prostředkům BYO. V Foundry nemůžete vytvořit zabezpečeného standardního agenta bez všech tří zadaných prostředků.

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

Řešení: Pro vaši podsíť delegovaného agenta nepoužíváte správný rozsah IP adres. Ověřte, že používáte platní prostor pro privátní IP adresy. Platné RFC1918 rozsahy zahrnují 10.0.0.0/8, 172.16-31.0.0/12a 192.168.0.0/16. Další podrobnosti jsou uvedené výše v omezeních .

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

Řešení: Chybí správná registrace prostředku. Ujistěte se, že jsou požadované prostředky zaregistrované ve vašem tenantovi.

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

Řešení: Jedná se o obecnou chybu. Vytvořte žádost o podporu pro prozkoumání vašeho nastavení. Zkontrolujte server funkcí kvůli chybě.

"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: Tato chyba se zobrazí při pokusu o odstranění zabezpečeného standardního nastavení šablony v Azure, pokud nebyly správně odstraněny všechny prostředky. Jedním z řešení je přejít na stránku prostředků Foundry na portálu Azure a vybrat Spravovat odstraněné prostředky. Odtud vyprázdněte prostředek, ke kterému byl agent přidružený pro tuto virtuální síť. Druhou možností je spustit deleteCaphost.sh skript v zabezpečené standardní šabloně.

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

Solution: Projekt Foundry má problémy s komunikací s Azure Cosmos DB při vytváření agentů. Ověřte připojení k Azure Cosmos DB (privátní koncový bod a DNS).

Selhání překladu DNS privátního koncového bodu

Řešení: Pokud prostředky nejsou dostupné prostřednictvím privátních koncových bodů, ověřte, že je každá zóna privátního DNS propojená s vaší virtuální sítí. Potvrďte, že podmíněné předávací servery ukazují na IP adresu virtuálního serveru Azure DNS 168.63.129.16. Z počítače připojeného k virtuální síti spusťte nslookup <resource-fqdn> a ověřte, že se každý název překládá na privátní IP adresu.

Další kroky

Teď jste úspěšně nakonfigurovali účet a projekt zabezpečení sítě. Pomocí rychlého startu vytvořte prvního agenta.

Další informace o konfiguraci a možnostech izolace sítě najdete v tématu Konfigurace izolace sítě.

Mnoho podnikových prostředí vyžaduje, aby Foundry, registr kontejneru a závislé služby, jako jsou Application Insights a Storage, byly dostupné jenom z privátní sítě. Tato část vysvětluje, jak zřídit a nasadit azd hostované agenty, jejichž závislosti se nacházejí za privátními koncovými body ve virtuální síti.

Integraci s VNet zajistíte přizpůsobením vygenerovaných infra/ šablon Bicep a spuštěním azd z prostředí uvnitř VNet (nebo z prostředí, které k němu má přístup).

Požadavky

Co znamená ochrana VNet pro nasazení azd

Projekt hostovaného agenta zřizuje několik prostředků Azure. Přístup k veřejné síti můžete zakázat na každém z nich a umístit do virtuální sítě privátní koncový bod.

Resource Lze chránit pomocí sítě VNet? Co znamená soukromý režim
Účet AI Services Ano Účet Foundry je dostupný pouze prostřednictvím privátního koncového bodu, a to jak pro volání roviny dat, tak pro volání ARM.
Projekt slévárny Ano, s účtem Přebírá stav zabezpečení sítě účtu.
Azure Container Registry Ano publicNetworkAccess: Disabled. Sestavení, odesílání a stahování probíhají přes soukromý koncový bod.
Application Insights Ano, prostřednictvím služby Azure Monitor Private Link Scope Příjem telemetrie probíhá přes rozsah privátního propojení.
Azure Storage Ano Služby Blob, Files a Queue se nacházejí za privátními koncovými body.
Samotný koncový bod agenta Ne, v této verzi Preview Adresa URL nasazeného koncového bodu agenta zůstane veřejně adresovatelná. Relace každého uživatele jsou oddělené podle identity uživatele. Viz Izolace relací hostovaného agenta pro každého uživatele.

Pokud potřebujete, aby samotný koncový bod agenta byl privátní, jedná se o funkci na straně platformy mimo rozsah tohoto rozšíření.

Co rozšíření dělá a nedělá

Schopnost Stav
Příznak CLI pro povolení integrace s VNet Není podporováno. Ve výchozím nastavení není k dispozici příznak --vnet ani --private-endpoint.
Opětovné použití existujícího privátního ACR Podporováno prostřednictvím AZURE_CONTAINER_REGISTRY_RESOURCE_ID a AZURE_CONTAINER_REGISTRY_ENDPOINT. Viz Nasazení hostovaného agenta s privátním Azure Container Registry.
Opakované použití existujícího účtu Foundry Podporováno prostřednictvím AZURE_AI_ACCOUNT_NAME a USE_EXISTING_AI_PROJECT=true.
Vlastní moduly Bicep v infra/ Plně podporováno. Adresář infra/ obsahuje standardní azd Bicep, které vlastníte.
azd ai agent doctor zevnitř sítě VNet Funguje. Vzdálené kontroly vyžadují překlad DNS koncového bodu roviny dat Foundry. Použijte --local-only k jejich přeskočení.
Místní GitHub spouštěče nebo agenty Azure DevOps ve virtuální síti Doporučený vzor. CI zajišťuje provisioning a nasazení zevnitř sítě.

Rozhodnutí o topologii

Většina nasazení chráněných pomocí VNetu spadá do jedné z těchto podob. Před úpravou Bicepu vyberte jednu možnost:

  • Greenfield, všechno uvnitř nové virtuální sítě. Spusťte příkaz azd ai agent init, poté přidejte moduly pro privátní koncové body do vygenerovaného infra/. V rámci jednoho spuštění Bicepu nasadíte jak síť VNet, tak prostředky.
  • Brownfield, připojte se k existující virtuální síti. Stejné jako u greenfield přístupu, ale místo vytvoření nové virtuální sítě (VNet) odkazujete na existující VNet pomocí parametrů. To je užitečné, když jiný tým vlastní síť.
  • Znovu použijte všechny existující prostředky. Tým platformy předem zřizoval účet Foundry, ACR a Application Insights v privátních koncových bodech. Stačí dodat pouze definici agenta a nastavit proměnné prostředí tak, aby odkazovaly na existující zdroje. main.bicep vytvoří pouze to, co chybí.

Topologie 2 a 3 jsou nejběžnější v regulovaných podnicích. Topologie 1 je vhodná pro samostatná pilotní nasazení.

Přizpůsobte vygenerovanou šablonu Bicep

Adresář infra/, který vygeneruje azd ai agent init, je standardní azd Bicep. Je vaše a změny zůstanou zachovány i po opakovaném nasazení. Výchozí šablony vytvářejí veřejné prostředky, takže je nahradíte nebo rozšíříte přidáním privátních koncových bodů.

Přidání parametrů virtuální sítě a podsítě

Přidejte parametry do infra/main.bicep a navažte je v infra/main.parameters.json:

// infra/main.bicep (excerpt)

@description('Resource ID of the existing virtual network. If empty, a new VNet is created.')
param vnetResourceId string = ''

@description('Name of the subnet hosting private endpoints.')
param privateEndpointSubnetName string = 'snet-pe'

@description('Disable public network access on data-plane resources.')
param disablePublicNetworkAccess bool = true

// infra/main.parameters.json (excerpt)
{
  "vnetResourceId":              { "value": "${AZURE_VNET_RESOURCE_ID=}" },
  "privateEndpointSubnetName":   { "value": "${AZURE_PE_SUBNET_NAME=snet-pe}" },
  "disablePublicNetworkAccess":  { "value": "${DISABLE_PUBLIC_NETWORK=true}" }
}

Nastavte proměnné prostředí před azd provision:

azd env set AZURE_VNET_RESOURCE_ID \
  /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Network/virtualNetworks/<vnet>
azd env set AZURE_PE_SUBNET_NAME snet-pe
azd env set DISABLE_PUBLIC_NETWORK true

Uzamknout jednotlivé prostředky

Pro každý prostředek, který šablony vytvářejí, nastavte publicNetworkAccess: 'Disabled' a přidejte modul privátního koncového bodu. Následující vzor je ilustrativní. Přizpůsobte typy prostředků a zóny DNS vašemu prostředí.

// infra/core/ai/account.bicep (excerpt)
resource aiAccount 'Microsoft.CognitiveServices/accounts@2024-10-01' = {
  // ...existing properties...
  properties: {
    // ...existing properties...
    publicNetworkAccess: disablePublicNetworkAccess ? 'Disabled' : 'Enabled'
    networkAcls: {
      defaultAction: disablePublicNetworkAccess ? 'Deny' : 'Allow'
    }
  }
}

Přidejte modul privátního koncového bodu, který účet propoíná do virtuální sítě:

module aiAccountPrivateEndpoint '../network/private-endpoint.bicep' = if (disablePublicNetworkAccess) {
  name: 'pe-ai-account'
  params: {
    name: 'pe-${aiAccount.name}'
    location: location
    subnetId: '${vnetResourceId}/subnets/${privateEndpointSubnetName}'
    privateLinkServiceId: aiAccount.id
    groupId: 'account'
    privateDnsZoneId: privateDnsZones.cognitiveServices
  }
}

Tento vzor opakujte u prostředků, které chcete nastavit jako soukromé:

  • Účet AI Services: ID skupiny account. Zóny DNS zahrnují privatelink.cognitiveservices.azure.com, privatelink.openai.azure.coma privatelink.services.ai.azure.comv závislosti na rovině dat.
  • Container Registry: ID skupiny registry. Zóna DNS privatelink.azurecr.io. Přidá koncový bod dat pro každou oblast.
  • Application Insights: prostřednictvím oboru Azure Monitor Private Link. Mezi zóny DNS patří privatelink.monitor.azure.com, privatelink.ods.opinsights.azure.com, privatelink.oms.opinsights.azure.coma privatelink.agentsvc.azure-automation.net.
  • Účet úložiště: ID skupin blob, file, queue a table podle potřeby. Zóny DNS na službu, například privatelink.blob.core.windows.net.

Úložiště azd-ai-starter-basic, ze kterého rozšíření agenta vytvoří základ projektu, je užitečnou referencí k tomu, co se ve výchozím nastavení vytvoří. Rozšiřte tyto moduly a nenahraďte je.

Zajištění prostředků

azd provision

Po zprovoznění je každá závislost ve vašem seznamu dosažitelná pouze prostřednictvím privátního koncového bodu. Veřejný překlad DNS stále vrací název veřejného hostitele, ale privátní zóny DNS ho přepíší uvnitř virtuální sítě.

Spustit příkaz azd up z prostředí virtuální sítě

Po zakázání přístupu k veřejné síti nemůžete spustit azd up nebo azd deploy z pracovní stanice veřejného internetu. Řídicí rovina ARM je dosažitelná, ale volání do datové roviny pro Foundry a operace push do ACR selhávají s chybami 403 nebo typu „connection refused“. Použijte jeden z následujících vzorů.

GitHub Actions Runner v místním prostředí

Zřiďte virtuální počítač runneru nebo runner hostovaný v AKS v podsíti stejné virtuální sítě. Nasměrujte svůj workflow na tento runner pomocí runs-on: [self-hosted, agent-vnet]. Každý azd ai krok pak správně přeloží privátní názvy DNS a odešle ho přes privátní koncový bod.

jobs:
  deploy:
    runs-on: [self-hosted, agent-vnet]
    steps:
      - uses: actions/checkout@v4
      - uses: Azure/setup-azd@v2
      - run: azd ext install microsoft.foundry
      - run: azd auth login --client-id ${{ secrets.AZURE_CLIENT_ID }} \
          --federated-credential-provider github \
          --tenant-id ${{ secrets.AZURE_TENANT_ID }}
      - run: azd up --no-prompt

Místně hostovaný agent Azure DevOps

Stejný vzor použijte pro Azure DevOps. Nainstalujte agenta do podsítě virtuální sítě a zacílte ho na direktivu pool: name: agent-vnet . azd CLI a rozšíření Foundry fungují beze změny.

Bastion nebo jump host pro jednorázové spuštění

Pro jednorázová spuštění, jako je ruční reakce na incident nebo nasazení mimo plánovaný cyklus, se přes Azure Bastion připojte k přechodovému hostiteli ve virtuální síti, nainstalujte tam azd a rozšíření a z tohoto hostitele spusťte azd. Ponechte hostitele jumpů minimální. Dlouhodobá odpověď je CI.

Vyvíjejte lokálně s privátním koncovým bodem Foundry

Místní vývoj (azd ai agent run a azd ai agent invoke) komunikuje s místním procesem agenta přes loopback a s datovou vrstvou Foundry kvůli nástrojům, modelům a relacím během invoke. Pokud je koncový bod Foundry jen pro virtuální síť, potřebujete dostupnost sítě z vývojového počítače. K dispozici jsou následující možnosti:

  • Síť VPN typu point-to-site nebo always-on, která vás zasadí do oboru DNS virtuální sítě.
  • Azure Bastion k vývojovému virtuálnímu počítači uvnitř virtuální sítě. Spusťte azd ai agent run na daném virtuálním počítači a přes tunel Bastion přesměrujte port 8088 a pro inspektor i port 8087.
  • Pracovní stanice v podnikové síti s cestou ExpressRoute nebo hub-VNet k paprsku, který je hostitelem privátních koncových bodů.

Řešení FOUNDRY_PROJECT_ENDPOINT se nezmění. Hodnota stále pochází z aktivního azd prostředí nebo globální konfigurace. Záleží na tom, že DNS přeloží koncový bod na privátní IP adresu, nikoli na veřejnou IP adresu.

Kombinovat s privátním ACR

Pokud jsou koncový bod Foundry i ACR na privátních koncových bodech ve stejné virtuální síti, postupujte takto:

  1. Spusťte azd up z virtuální sítě.
  2. Nastavte AZURE_CONTAINER_REGISTRY_ENDPOINT a AZURE_CONTAINER_REGISTRY_RESOURCE_ID tak, aby odkazovaly na stávající privátní ACR, aby Bicep přeskočil vytvoření nového veřejného ACR.
  3. Ujistěte se, že identita agenta má v registru roli AcrPull . azd deploy se o to automaticky postará poté, co vytvoří identitu agenta.

Podrobnosti týkající se registru najdete v tématu Nasazení hostovaného agenta s privátním Azure Container Registry.

Diagnostika problémů se sítěmi

  • azd ai agent doctor spouští kontroly dostupnosti sítě v rovině dat Foundry. Z prostředí VNet kontroly proběhnou úspěšně. Zvenčí selhávají jasně. Použijte --local-only, chcete-li při ladění problémů, které nesouvisejí se sítí, přeskočit vzdálené kontroly.
  • azd ai agent invoke --output raw "ping" vypíše celou odpověď HTTP. Chyba „connection refused“ nebo „no such host“ zde znamená problém s DNS nebo směrováním, nikoli problém s autentizací.
  • Při selhání operace push do ACR rozhraní příkazového řádku vypíše příkaz az role assignment create, který lze rovnou vložit, pokud je příčinou chybějící role, nikoli problém se sítí.

Známá omezení

  • Žádný příznak rozhraní příkazového řádku první třídy. Veškerá konfigurace VNet spočívá v ručních úpravách v Bicepu a v provozní disciplíně při umístění runneru, nastavení DNS a RBAC.
  • Koncový bod agenta zůstává v této verzi veřejně přístupný. Izolace tenantů na veřejném koncovém bodu se provádí izolací relací pro každého uživatele, nikoli síťovým soukromím.
  • Platí omezení oblastí. Hostovaní agenti jsou k dispozici v pevné sadě oblastí. VNet, ACR a účet Foundry by měly být umístěny v jedné z těchto oblastí nebo s jednou z nich mít navázané partnerské propojení. Požadavky na stejnou oblast mezi prostředkem Foundry a jeho virtuální sítí najdete v tématu Regionální podpora privátních sítí. Spusťte azd ai agent doctor pro ověření.
  • DNS je nejběžnější režim selhání. Než budete předpokládat, že problém souvisí s RBAC, ověřte end-to-end překlad privátních názvů DNS, například pomocí nslookup <endpoint> z runneru nebo z vývojového virtuálního počítače.

Související obsah

  • Last updated on