Traga o seu próprio modelo para o Serviço de Agentes da Foundry

** O Serviço de Agente Foundry permite-lhe ligar e usar modelos alojados atrás dos seus gateways de IA, como API Management do Azure ou outros gateways de modelos de IA não geridos pela Azure. Esta capacidade, chamada traga o seu próprio modelo, permite-lhe manter o controlo sobre os endpoints do seu modelo enquanto utiliza as capacidades do agente Foundry.

Importante

Para efeitos desta documentação, BYOM modelos refere-se a modelos de terceiros que traz para a Foundry e não inclui Modelos Diretos do Azure. O Foundry Agent Service apoia a capacidade de trazer o seu próprio modelo (BYOM). Se usar o Foundry Agent Service para interagir com modelos BYOM, fá-lo por sua conta e risco. Os modelos BYOM são considerados Produtos Não Microsoft ao abrigo dos Termos do Produto Microsoft e são regidos pelos seus próprios termos de licença.

Se usar o Foundry Agent Service para interagir com modelos BYOM, é responsável por implementar as suas próprias mitigações de IA responsáveis dentro do Foundry Agent Service, como metaprompt, filtros de conteúdo ou outros sistemas de segurança.

Se utilizar o Foundry Agent Service para interagir com modelos BYOM, é responsável por garantir que a utilização do modelo BYOM cumpre os seus requisitos de tratamento de dados. É responsável por rever todos os dados partilhados com os modelos BYOM e por compreender as práticas de terceiros para retenção e localização dos dados. É sua responsabilidade gerir se os seus dados irão fluir para além da conformidade com o Azure e dos limites geográficos da sua organização, bem como quaisquer implicações relacionadas ao utilizar modelos BYOM.

Esta capacidade permite às organizações:

  • Mantenha o controlo sobre os endpoints do modelo por detrás da infraestrutura empresarial existente.
  • Integre de forma segura com gateways empresariais utilizando as políticas de segurança existentes.
  • Crie agentes que usem modelos sem os expor publicamente.
  • Aplicar os requisitos de conformidade e governação ao acesso a modelos de IA.

Diagrama que mostra a arquitetura do gateway de IA com fluxos do Serviço de Agente para o seu gateway e os modelos que o suportam.

Neste artigo, cria uma ligação de gateway ao endpoint do seu modelo de IA, implanta um agente de solicitação que encaminha pedidos através do gateway e verifica o fluxo de ponta a ponta.

Pré-requisitos

  • Uma subscrição do Azure. Crie um gratuitamente.
  • Um projeto Microsoft Foundry.
  • Acede às credenciais do seu gateway de IA empresarial, como uma chave de subscrição de Gestão de APIs, uma chave API para outro gateway de modelo de IA que não seja do Azure, ou credenciais de um fornecedor OAuth 2.0 usando credenciais do cliente.
  • Para gerir ligações através da linha de comandos:

Permissões necessárias

Precisa das seguintes atribuições de funções:

Recurso Função obrigatória
Projeto da fundição Utilizador do Azure AI ou superior
Grupo de recursos (para implementação de ligações) Colaborador

Criar uma ligação de modelo

Use o portal Foundry para criar uma ligação ao seu modelo.

Pode escolher modelos atrás de um recurso existente do API Management do Azure ou de um gateway de modelos de IA que não seja do Azure. Ao utilizar estes passos, pode adicionar vários modelos que implementam a API de completação de chats OpenAI.

Para adicionar uma ligação ao modelo no portal Foundry:

  1. Iniciar sessão no Microsoft Foundry.

  2. Selecione Operar>Consola de Administração.

  3. Abra a aba Todos os projetos.

  4. Na lista de projetos, encontre o seu projeto e selecione o link na coluna Recurso Pai.

  5. Selecione o separador Modelos ligados ao administrador e depois selecione Adicionar. Captura de ecrã de modelos externos no portal da Foundry.

    O assistente para adicionar ligação de modelo abre-se.

  6. Na página Tipo de Ligação, selecione API Management do Azure e depois selecione o nome de um recurso de Gestão de API existente e a implementação do modelo. O modelo deve implementar a API de completação de chat compatível com OpenAI.

    Captura de ecrã da seleção de um recurso de Gestão de API no portal Foundry.

  7. Na página de Autenticação , selecione uma opção para autenticação na API Management.

    Selecione uma chave API , como uma chave de subscrição de Gestão de APIs, ou Identidade Gerida , se estiver configurada no seu projeto Foundry.

    • Chave API: Insira o valor da chave no campo fornecido. Opcionalmente, especifique um nome de cabeçalho de chave API para usar ao passar a chave API se o seu gateway exigir um cabeçalho personalizado.

    • Identidade Gerida: Na Audiência, introduza o serviço-alvo para o token de identidade gerida, como https://cognitiveservices.azure.com/. Para a configuração necessária de Gestão de APIs, consulte Configurar autenticação de identidade gerida para Gestão de APIs.

  8. Na página de configuração do modelo , configure pelo menos uma implementação de modelo que apareça no Foundry para utilização com agentes.

    1. Selecionar + Adicionar modelo.
    2. Insira um nome de implementação (usado nas chamadas API) e o nome correspondente, e o nome de visualização.
    3. Guarde a configuração do modelo.

    Repita os passos anteriores para adicionar mais modelos à ligação, se necessário.

  9. Na página Avançada , faça opcionalmente os seguintes passos:

    1. Introduza uma versão da API , se exigido pelas implementações do seu modelo.
    2. Ative a definição Incluir o nome da implementação no caminho da URL se o seu gateway expor a API de completação de chat num caminho ao estilo Azure OpenAI que inclua o nome da implementação (por exemplo, /deployments/{deploymentName}/chat/completions). Deixe a configuração desativada se o seu gateway usar um caminho ao estilo OpenAI sem o nome da implementação (por exemplo, /chat/completions) e depender de outros mecanismos de encaminhamento para direcionar as requisições para a implementação do modelo correto.
    3. Selecionar + Adicionar cabeçalho para adicionar um cabeçalho estático que deve ser incluído nos pedidos ao gateway. Repita para adicionar vários cabeçalhos se necessário.

  10. Selecionar Adicionar.

Configurar autenticação de identidade gerida para a Gestão de APIs

Para configurar a autenticação Managed Identity para a API Management, complete a seguinte configuração em Azure:

  1. Ativar a identidade gerida no recurso do projeto Foundry.

    1. No Azure portal, aceda ao seu recurso Foundry.

    2. Vá a Projetos>, selecione > do seu projeto.

    3. Ative um dos

      • Identidade gerida atribuída pelo sistema , ou
      • Identidade gerida atribuída ao utilizador.

    4. Para a validação de tokens no API Management, obtenha o ID do aplicativo (cliente) da identidade gerida.

      1. Primeiro, obtenha o ID do objeto da identidade gerida a partir da configuração desta no seu projeto.
      2. Pesquise esse ID de objeto nas aplicações empresariais do Microsoft Entra ID para localizar o ID correspondente da aplicação (cliente).

  2. Valide o token de identidade gerida na API Management.

    Na sua política de entrada de Gestão de APIs, use a política validate-azure-ad-token para impor validação de tokens para pedidos da Microsoft Foundry.

    • Defina o audience elemento para o mesmo valor que configurou no campo Audience da ligação Foundry.
    • Defina o ID da aplicação de identidade gerida em client-application-ids.

    Exemplo:

    <validate-azure-ad-token tenant-id="{{your-tenant-id}}" header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized">
   <client-application-ids>
      <application-id>{{managed-identity-client-id}}</application-id>
   </client-application-ids>
   <audiences>
      <audience>{{audience-configured-in-foundry-connection}}</audience>
   </audiences>
</validate-azure-ad-token>

A ligação é criada e aparece na lista no separador Modelos ligados ao administrador .

Implementações de modelos ligados ao administrador

O Foundry implementa automaticamente os modelos que adicionas através de uma ligação, para que possas usá-los nos teus projetos.

  • Cada modelo que adicionas no assistente de ligação corresponde a uma implementação no Foundry.

  • Pode selecionar uma implementação ligada ao administrador ao configurar o modelo de um agente. O Foundry encaminha automaticamente os pedidos dos agentes para estas implementações através do gateway conectado.

Criar uma ligação de modelo

Use a CLI do Azure para criar uma ligação a modelos atrás do seu gateway de IA.

O Serviço Agente suporta dois tipos de ligações: ligações de Gestão de API e ligações Model Gateway .

Escolha o tipo de ligação que corresponde ao seu gateway:

Tipo de ligação Utilização quando Valor de categoria
Gestão de APIs Já usas o API Management do Azure para encaminhamento de modelos e queres padrões inteligentes de gestão de APIs. ApiManagement
Gateway de Modelo Usa OpenAI, MuleSoft ou um gateway personalizado e precisa de descoberta estática ou dinâmica de modelos. ModelGateway

Para especificações detalhadas de ligação, consulte os exemplos de ligação em GitHub.

Implantar a ligação

  1. Clone ou descarregue o repositório de amostras Foundry e localize o modelo de Bicep para o seu tipo de ligação em infrastructure/infrastructure-setup-bicep/01-connections/. O diretório contém ficheiros Bicep e ficheiros de parâmetros separados para Gestão de APIs e ligações Model Gateway.

  2. Implemente a ligação executando az deployment group create com o seu grupo de recursos, o ficheiro modelo Bicep e o ficheiro de parâmetros correspondente. Substitua os valores provisórios no ficheiro de parâmetros pelo URL e credenciais do endpoint do gateway antes de implementar. Para a referência completa de comandos, veja az group deployment create.

    Dica

    Uma implementação bem-sucedida retorna provisioningState: Succeeded na saída do comando.

  3. Verifica a ligação no portal da Foundry. Vai ao portal da Foundry e seleciona o teu projeto. Navegue até Recursos Conectados nas definições do seu projeto. A nova ligação aparece com um estado Ativo e o URL do endpoint do gateway que especificaste.

Crie um agente de prompt com a conexão do modelo

Depois de criar a ligação, crie e execute um agente de prompts que utilize modelos por detrás do seu gateway. A principal diferença em relação a um agente padrão é o formato do nome de implementação do modelo: <connection-name>/<model-name>.

  1. Defina as seguintes variáveis de ambiente:

    Variável Valor Exemplo
    FOUNDRY_PROJECT_ENDPOINT URL do endpoint do seu projeto https://<your-ai-services-account>.services.ai.azure.com/api/projects/<project-name>
    FOUNDRY_MODEL_DEPLOYMENT_NAME <connection-name>/<model-name> my-apim-connection/gpt-4o

  2. Inicialize um AIProjectClient com o seu endpoint e DefaultAzureCredential, a seguir, chame agents.create_version() com um PromptAgentDefinition. Defina o model parâmetro para o FOUNDRY_MODEL_DEPLOYMENT_NAME valor.

    Uma chamada bem-sucedida devolve um objeto agente com os seus id, name, e version campos preenchidos.

  3. Obtenha o cliente OpenAI com project.get_openai_client(), crie uma conversa com conversations.create(), e envie um pedido com responses.create(). Passe a referência do agente em extra_body como {"agent_reference": {"name": agent.name, "type": "agent_reference"}}.

    Uma resposta bem-sucedida devolve o texto de resposta do modelo, confirmando que o agente está a enviar pelo seu gateway.

    Nota

    Se a resposta falhar com um model not found erro, verifique se o FOUNDRY_MODEL_DEPLOYMENT_NAME valor usa o formato <connection-name>/<model-name>.

  4. Limpe ao eliminar a conversa e a versão do agente após os testes serem concluídos.

Para um exemplo completo e funcional, veja as amostras do SDK agent em GitHub. Para detalhes da API, consulte AIProjectClient e PromptAgentDefinition.

Verificar a implementação

Depois de implementar o seu agente, confirme que todo o pipeline funciona corretamente:

  1. Verifique o estado da ligação — No portal Foundry, vá a Recursos Ligados nas definições do seu projeto. Verifica se a ligação mostra um estado Ativo . Se o estado for Inativo, verifique a URL e as credenciais do endpoint do gateway.

  2. Enviar um prompt de teste — Use o SDK para criar uma conversa e enviar um pedido conforme descrito na secção anterior. Uma resposta bem-sucedida devolve o texto de resposta do modelo, confirmando que o agente pode aceder ao modelo através do seu gateway.

  3. Revise os registos do gateway — Confirme que os pedidos foram encaminhados corretamente. Para Gestão de APIs, consulte API Management analytics no portal Azure. Para outros gateways, reveja o registo de pedidos do seu gateway. Deverias ver pedidos recebidos do endpoint do Serviço de Agente.

Dica

Se algum passo falhar, consulte a secção Resolução de problemas comuns para os passos de resolução.

Detalhes do tipo de ligação

Esta secção fornece detalhes de referência sobre cada tipo de ligação e as suas opções de configuração.

Conexão de Gestão de API

As ligações de Gestão de API fornecem padrões inteligentes e seguem as convenções padrão da Gestão de API.

Configuração Valor padrão
Endpoint para a Listagem de Implementações /deployments
Obter endpoint de implementação /deployments/{deploymentName}
Fornecedor AzureOpenAI

Prioridade de configuração:

  1. Valores explícitos de metadados (prioridade máxima).
  2. Padrões padrão de gestão de API (recurso).

Métodos de autenticação:

  • API Key — Autenticação padrão da chave de subscrição.
  • Microsoft Entra ID — Integração de identidade empresarial.

Conexão do Model Gateway

As ligações Model Gateway fornecem uma interface unificada para ligar a vários fornecedores de modelos de IA. Estas ligações suportam tanto a descoberta de modelos estáticos como dinâmicos:

  • Descoberta estática — Os modelos são pré-definidos nos metadados da ligação. Ideal para implementações fixas e listas de modelos aprovadas por empresas.
  • Descoberta dinâmica — Os modelos são descobertos em tempo de execução usando endpoints da API. Ideal para implementações em constante mudança e catálogos geridos pelo fornecedor.

Os tipos de autenticação suportados são a chave API e o OAuth 2.0. As chaves API são armazenadas de forma segura e referenciadas através do sistema de credenciais.

Resolver problemas comuns

Problema Resolução
A ligação mostra o estado de Inativo Verifique se o URL do endpoint do gateway é acessível e as credenciais de autenticação são válidas.
O agente retorna o erro model not found Confirme que o FOUNDRY_MODEL_DEPLOYMENT_NAME valor usa o formato correto: <connection-name>/<model-name>.
Erros de tempo limite do gateway Verifique se os endpoints do seu gateway são acessíveis a partir da rede de Serviços de Agentes. Para redes privadas, consulte a orientação de isolamento de rede na secção de Limitações.
Falhas de autenticação Para a gestão de APIs, verifique a sua chave de subscrição. Para o Model Gateway, verifique a chave API ou a configuração OAuth 2.0.

Configurações suportadas

  • Apenas os agentes de prompt no Agent SDK suportam esta funcionalidade.
  • Ferramentas de agentes suportadas: Interpretador de Código, Funções, Pesquisa de Ficheiros, OpenAPI, Foundry IQ, Grounding SharePoint, Agente de Dados Fabric, MCP e Automação de Navegador.
  • Configurações de rede suportadas:
    • A rede pública é suportada tanto para Gestão de APIs como para gateways auto-hospedados.
    • Para isolamento total da rede:
      • API Management como o seu gateway de IA: Implemente o Foundry e a API Management juntos usando this GitHub template.
      • Gateway auto-hospedado: Certifique-se de que os endpoints do seu gateway são acessíveis dentro da rede virtual usada pelo Serviço de Agentes.

Conteúdo relacionado

  • Last updated on