Configurar uma rede privada para o Serviço de Agente da Fundição

A Foundry Agent Service oferece uma configuração padrão com ambiente de rede privado . Esta configuração cria um ambiente de rede isolado que permite o acesso seguro aos dados, mantendo ao mesmo tempo o controlo total sobre a sua infraestrutura de rede.

Por defeito, a Configuração Padrão com rede privada assegura:

• Sem saída pública: A infraestrutura fundamental fornece a autenticação e segurança corretas para os seus agentes e ferramentas, sem exigir bypass de serviço confiável.
• Integração de sub-rede: Você fornece uma sub-rede delegada da sua rede virtual. A plataforma liga o computo do agente a esta sub-rede, permitindo a comunicação local com os seus recursos do Azure dentro da mesma rede virtual.
• Acesso privado a recursos: Se os seus recursos estiverem marcados como privados e não detectáveis na internet, a rede da plataforma ainda pode aceder a eles quando as credenciais e autorizações necessárias estiverem em vigor.

Se não tiver uma rede virtual existente, a Configuração Padrão com fluxo de rede privada pode fornecer a infraestrutura de rede necessária para si.

Pré-requisitos

• Uma subscrição Azure - Crie uma gratuitamente.

• Certifique-se de que a pessoa que cria a conta e o projeto tem a função de Proprietário da Conta Azure AI no âmbito da subscrição.

• O utilizador que cria esta configuração deve também ter permissões para atribuir funções aos recursos necessários (Azure Cosmos DB, Pesquisa de IA do Azure, Armazenamento do Azure).

  • O papel integrado necessário é Administrador de Acesso Baseado em Funções.
  • Alternativamente, ter o papel de Proprietário ao nível da subscrição também satisfaz este requisito.
  • A permissão chave necessária é: Microsoft.Authorization/roleAssignments/write

• Python 3.9 ou posterior

• Depois de configurado o ambiente do agente, certifique-se de que cada membro da equipa que pretende usar o Agent Playground ou SDK para criar ou editar agentes recebeu a função incorporada de Azure AI UserRBAC para o projeto.

  • O conjunto mínimo de permissões exigidas é: agents/*/read, agents/*/action, agents/*/delete

• Registe os prestadores. Os seguintes prestadores devem estar registados:

  • Microsoft.KeyVault
  • Microsoft.CognitiveServices
  • Microsoft.Storage
  • Microsoft.MachineLearningServices
  • Microsoft.Search
  • Microsoft.Network
  • Microsoft.App
  • Microsoft.ContainerService
  • Para usar a ferramenta de pesquisa do Bing: 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'
  

Configurar um ambiente seguro em rede

Podes criar esta configuração no portal do Azure ou implementá-la usando o Bicep ou o Terraform.

A um nível geral, a implementação envolve estes passos:

1. Escolha a região Azure de destino para os seus recursos da Foundry.
2. Decide se trazes o teu próprio VNet e sub-rede, ou se usas rede auto-provisionada.
3. Se trouxeres o teu próprio VNet, reúne os IDs do teu VNet e dos recursos de sub-rede.
4. Crie a configuração no portal Azure, ou implemente-a usando Bicep ou Terraform.
5. Verifique a implementação (veja Verificar a implementação).

A configuração disponibiliza os seguintes recursos (a menos que traga os seus próprios):

• Uma conta Foundry e um projeto Foundry.
• Uma implantação de modelo GPT-4o.
• Armazenamento do Azure, Azure Cosmos DB e Pesquisa de IA do Azure para armazenar ficheiros, threads e dados vetoriais.
• Estes recursos estão ligados ao seu projeto.
• As chaves de encriptação geridas pela Microsoft para Conta de Armazenamento e Conta Cognitiva (Foundry) são usadas por defeito.

Selecione o seu método de implementação preferido usando os seguintes separadores:

Verificar a implementação

Após a implementação terminar, verifique se todos os recursos estão configurados corretamente:

1. Confirmar delegação de sub-rede: No portal Azure, navegue até à sua VNet >Sub-redes e verifique se a sub-rede do agente apresenta delegação para Microsoft.App/environments.
2. Verifique o acesso à rede pública: Abra cada recurso (Foundry, Pesquisa de IA do Azure, Armazenamento do Azure, Azure Cosmos DB) e confirme que Acesso à rede pública está definido como Desabilitado.
3. Validar a resolução DNS do endpoint privado: De uma máquina conectada à VNet, execute nslookup para cada endpoint listado no resumo das configurações da zona DNS. Verifique se cada nome resolve para um endereço IP privado (10.x, 172.16-31.x ou 192.168.x).
4. Conectividade do agente de teste: Acede ao seu projeto Foundry a partir do VNet (veja Aceder aos seus agentes protegidos) e confirme que pode criar e executar um agente.

Limitações

• Limitação de endereços IP de sub-rede: Ambas as sub-redes devem ter intervalos de IP dentro de intervalos RFC1918 IPv4 privados válidos: 10.0.0.0/8, 172.16-31.0.0/12, ou 192.168.0.0/16. O intervalo de endereços IP públicos e CGNAT 100.64.0.0–100.127.255.255 não é suportado.
• Exclusividade da sub-rede do agente: A sub-rede do agente não pode ser partilhada por múltiplos recursos da Foundry. Cada recurso da Foundry deve usar uma sub-rede de agente dedicada.
• Tamanho da sub-rede do Agente: O tamanho recomendado da sub-rede do Agente delegado é /24 (256 endereços) devido à delegação da sub-rede para Microsoft.App/environments. Para mais informações sobre dimensionamento de sub-redes, veja Configurar redes virtuais para Azure Container Apps.
• Listagem de permissões no firewall de saída da sub-rede do agente: Se estiver a integrar um Azure Firewall com o seu agente padrão de rede privada segura, defina como permitido na lista os Nomes de Domínio Totalmente Qualificados (FQDNs) indicados em Managed Identity no artigo Integrar com Azure Firewall ou adicione a Tag de Serviço AzureActiveDirectory.
  • Verifica se não há inspeção TLS no Firewall que possa adicionar um certificado auto-assinado. Durante falhas, inspecione se há tráfego a chegar ao Firewall e que tráfego está a ser bloqueado.
• O recurso Foundry deve ser implementado na mesma região da rede virtual (VNet). Outros recursos do Azure, como Azure Cosmos DB, Pesquisa de IA do Azure e Armazenamento do Azure, podem ser implementados em diferentes regiões. Considere as implicações de custo das implementações interregionais.
• Disponibilidade da região:
  • Para regiões suportadas para implementações de modelos, veja: Azure OpenAI suporte à região do modelo.
• Armazenamento de Blobs do Azure: A utilização de ficheiros Armazenamento de Blobs do Azure com a ferramenta de Pesquisa de Ficheiros não é suportada.
• Grounding com Bing Search: Apenas as seguintes regiões são suportadas: Europa Ocidental, Canadá Este, Suíça Norte, Espanha Central, Norte dos Emirados Árabes Unidos, Coreia Central, Polónia Central, Sudeste da Ásia, EUA Oeste, EUA Oeste 2, EUA Oeste 3, EUA Leste, EUA Leste 2, Centro EUA, Sul da Índia, Japão Este, Reino Unido Sul, França Central, Noruega Este, Austrália Este, Canadá Central, Suécia Central, África do Sul Norte, Itália Norte, Brasil Sul
• Eliminar injeção de rede: Se quiser eliminar o seu recurso Foundry e o Standard Agent com configuração de rede segura, elimine o seu recurso Foundry e a rede virtual por último. Antes de eliminar a rede virtual, apague e elimine o seu recurso Foundry.
• Injeção de rede virtual de agente alojado: Para agentes alojados, a configuração da rede virtual (injeção de rede) deve ser incluída quando criar pela primeira vez a conta Foundry. Adicionar injeção de rede a uma conta Foundry existente após a criação não é suportado para agentes alojados.
• Registo de contentores de agentes hospedados atrás de uma rede privada: Para agentes hospedados, o Azure Container Registry (ACR), que armazena a imagem do contentor do agente, atualmente não pode ser colocado atrás de uma rede privada (endpoint privado com acesso à rede pública desativada). O ACR deve estar acessível através do seu endpoint público para que a plataforma possa extrair a imagem.

Diagrama de arquitetura

Revise os recursos de rede provisionados

Os seguintes recursos são automaticamente disponibilizados quando utiliza o Standard Setup com rede privada, a menos que leve o seu próprio:

Infraestrutura de rede

• Uma rede virtual (192.168.0.0/16)
• Subrede de Agente (192.168.0.0/24): Clientes alojados pelo Agente
• Subnet de endpoint privado (192.168.1.0/24): Aloja endpoints privados

Capacidades da rede virtual

A sua rede virtual controla quais os endpoints que podem fazer chamadas API aos seus recursos. O serviço Azure rejeita automaticamente chamadas de API de dispositivos fora da sua rede definida.

Regras da rede

Todas as contas e os respetivos projetos estão protegidos por defeito com a bandeira de acesso à rede pública desativada , exigindo uma configuração explícita para permitir o acesso através de endpoints privados. Estas regras aplicam-se a todos os protocolos, incluindo REST e WebSocket.

Resumo das configurações da zona DNS

Para criar um encaminhador condicional no Servidor DNS para o Servidor Virtual DNS do Azure, use a lista de zonas mencionadas na tabela acima. O endereço IP do DNS do Azure Virtual Server é 168.63.129.16.

Aceda aos seus agentes garantidos

Uma vez concluída a implementação, pode aceder ao seu projeto Foundry atrás de uma rede virtual usando um dos seguintes métodos:

• Gateway de VPN do Azure: Liga redes locais à rede virtual através de uma ligação privada. A ligação é feita através da internet pública. Existem dois tipos de gateways VPN que podes usar:
  • Point-to-site: Cada computador cliente utiliza um cliente VPN para se ligar à rede virtual.
  • Site-to-site: Um dispositivo VPN liga a rede virtual à sua rede local.
• ExpressRoute: Liga redes locais à cloud através de uma ligação privada. A ligação é feita através de um fornecedor de conectividade.
• Azure Bastion: Neste cenário, cria-se uma Azure Máquina Virtual (por vezes chamada de jump box) dentro da rede virtual. Depois liga-se à VM usando o Azure Bastion. O Bastion permite-te ligar-te à VM usando uma sessão RDP ou SSH a partir do teu navegador local. Depois usas a jump box como ambiente de desenvolvimento. Como está dentro da rede virtual, pode aceder diretamente ao espaço de trabalho.

FAQ

Que intervalo de endereços devo usar para a rede virtual como um todo?

O intervalo de endereços da rede virtual pode ser qualquer intervalo de IP privado que deixe espaço suficiente para a sub-rede do agente delegado e para a sub-rede do endpoint privado.

Posso usar redes virtuais peered ou colocar recursos em diferentes redes virtuais?

São suportadas redes virtuais peered, mas os custos de transferência de dados podem aumentar.

Podem múltiplos recursos da Foundry reutilizar a mesma rede virtual e sub-rede?

Sim, a mesma VNET, mas não a mesma sub-rede. Múltiplos recursos da Foundry podem reutilizar a mesma rede virtual. No entanto, cada recurso Foundry requer a sua própria sub-rede dedicada de ambiente de execução do agente. A sub-rede do agente não pode ser partilhada entre vários recursos da Foundry.

A rede virtual precisa de estar no mesmo grupo de recursos que o recurso da Foundry?

Não. A rede virtual e o recurso Foundry não precisam de estar no mesmo grupo de recursos, mas têm de estar na mesma região.

Guia de resolução de problemas

Consulte este guia para resolver erros durante ou após a implementação de um Agente Padrão, quer tenha usado o portal Azure, Bicep ou Terraform.

Erros de implementação

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

Solução: Fornecer todas as ligações a todos os recursos Bring-your-Own (BYO) requer ligações a todos os recursos BYO. Não pode criar um agente padrão garantido na Foundry sem fornecer os três recursos.

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

Solução: Não está a usar um intervalo de IP adequado para a sub-rede do seu agente delegado. Verifica se estás a usar um espaço de endereços IP privados válido. Intervalos de RFC1918 válidos incluem 10.0.0.0/8, 172.16-31.0.0/12, e 192.168.0.0/16. O texto da mensagem de erro pode não listar todos os intervalos válidos.

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

Solução: Está a faltar o registo correto de recursos. Certifique-se de que os recursos necessários estão registados no seu inquilino.

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

Solução: Isto é um erro genérico. Crie um pedido de suporte para investigar a sua configuração. Verifica o host de capacidades para identificar o erro.

"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: Este erro aparece quando tenta apagar a configuração do seu modelo padrão seguro no Azure e não apagou corretamente todos os recursos. Uma solução é navegar até à página de recursos do Foundry no portal Azure e selecionar Gerir recursos eliminados. A partir daí, purge o recurso com que o agente estava associado para esta rede virtual. A outra opção é executar o deleteCaphost.sh script no template padrão seguro.

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

Solution: O projeto Foundry tem dificuldades em comunicar com Azure Cosmos DB para criar Agentes. Verifique a conectividade ao Azure Cosmos DB (Private Endpoint e DNS).

Falha na resolução DNS do endpoint privado

Solução: Se os recursos não forem acessíveis através de endpoints privados, verifique se cada zona DNS privada está ligada à sua rede virtual. Confirme que os encaminhadores condicionais apontam para o endereço IP do servidor virtual DNS do Azure 168.63.129.16. A partir de uma máquina ligada ao VNet, execute nslookup <resource-fqdn> e verifique se cada nome resolve para um endereço IP privado.

Próximos passos

Agora configurou com sucesso uma conta e um projeto seguros em rede. Use o quickstart para criar o seu primeiro agente.

Para mais informações sobre configuração e opções de isolamento de rede, consulte Configurar isolamento de rede.