Migrar do portal Foundry (clássico)

Microsoft Foundry evoluiu por meio de várias alterações de nomenclatura e arquitetura. Se você estiver migrando da experiência clássica do portal, este artigo ajudará você a planejar e executar a transição com mapeamentos de referência para terminologia, funcionalidades, SDKs e navegação no portal.

Nota

Denominação do produto: a Plataforma de IA da Microsoft evoluiu de Azure AI Studio → Fábrica de IA do Azure → para Microsoft Foundry (atual). Da mesma forma, nosso portfólio de serviços de IA evoluiu com a plataforma desde Azure Serviços Cognitivos → Serviços de IA do Azure → para Foundry Tools (atual). Apesar da evolução da plataforma, o tipo de recurso Azure permanece Microsoft.CognitiveServices/accounts. Todos os nomes nesta documentação referem-se à mesma plataforma em evolução.

Pré-requisitos

  • Uma conta Azure com uma assinatura ativa. Crie um gratuitamente.
  • Um projeto do Foundry.
  • Para migração do SDK: Python 3.9+ ou .NET 8+, com azure-ai-projects pacotes 2.x e openai instalados.
  • Para atualização de recursos: função proprietário ou colaborador no recurso Azure OpenAI que você planeja atualizar.

Importante

Datas principais de migração:

Planejar sua migração

Siga estas etapas para passar da experiência do portal clássico para o portal do Foundry atual:

  1. Examine as alterações de terminologia. Examine o mapeamento de terminologia para entender conceitos renomeados e novos tipos de recursos.
  2. Verifique a comparação de funcionalidades. Use a tabela de comparação de recursos para identificar recursos novos, aprimorados ou somente clássicos.
  3. Atualize seus pacotes do SDK. Substitua pacotes preteridos usando a tabela de mapeamento do SDK .
  4. Migrar agentes para a API de Respostas. Reescreva agentes que usam a API de assistentes para usar a API de respostas antes do pôr do sol de agosto de 2026.
  5. Verifique se a região de recursos do Foundry dá suporte à API de Respostas. A API de Respostas e o Serviço do Agente do Foundry não estão disponíveis em todas as regiões Azure. Se o recurso Foundry estiver em uma região sem suporte, os agentes e outros recursos da API de Respostas não funcionarão no portal atual. Verifique a lista de disponibilidade da região da API de Respostas antes de migrar.
  6. Valide no novo portal. Use a referência de navegação do portal para verificar seus fluxos de trabalho na experiência atual.

Importante

A API de Respostas não está disponível em todas as regiões Azure. Se o recurso Foundry estiver em uma região sem suporte, você não poderá criar ou executar agentes no portal do Foundry atual. Antes de migrar, verifique se o recurso está em uma região com suporte. Se não estiver, crie um novo recurso do Foundry em uma região com suporte.

Mapeamento de terminologia

A tabela a seguir mapeia conceitos clássicos para seus equivalentes atuais.

Conceito Termo clássico Termo atual Notas
Portal (principal) Portal do Foundry (clássico) Portal de fundição Mudar no banner do portal alterna entre eles.
Configurações do portal Centro de Gerenciamento Seção de Operação Navegação reorganizada.
Tipo de recurso Azure OpenAI + Hub Recurso do Foundry Tipo único AIServices com projetos filho.
Serviços de IA Serviços de IA do Azure Ferramentas de Fundição Fala, Visão, Linguagem, Segurança de Conteúdo, Compreensão de Conteúdo.
Faturamento de modelos MaaS (Model-as-a-Service) Modelos do Foundry Direct Modelos de primeira parte cobrados diretamente através dos medidores do Azure.
Funções RBAC Usuário dos Serviços Cognitivos OpenAI Usuário do Foundry, Gerente de Projeto do Foundry, Proprietário do Foundry Novas funções com separação de controle/plano de dados.
Protocolo de rede de API API de assistentes API de Respostas Desativação da API de Assistentes: 26 de agosto de 2026.
Controle de versão da API Parâmetros mensais api-version Rotas estáveis v1 Nenhum parâmetro de versão é necessário.
Estado da conversa Threads Conversas Conversas armazenam itens (mensagens, chamadas de ferramenta, saídas), não apenas mensagens.
Mensagens de chat Mensagens Itens Os itens são um superconjunto de mensagens.
Execução Execuções (assíncronas, sondadas) Respostas (sincronização por padrão) Nenhum loop de sondagem é necessário.
Definição do agente Assistentes/Agentes Versões do agente Versionado, com tipo explícito (prompt, fluxo de trabalho, hospedado).
Criação de agente create_agent() create_version() Usa PromptAgentDefinition.
Pontos de extremidade Múltiplo (openai, azureml, cognitiveservices, pesquisa, voz) Endpoint de projeto único + endpoint OpenAI v1 Gerenciamento simplificado de dispositivos.
Documentação Documentos clássicos Documentos atuais Conteúdo em dois conjuntos de documentos separados.

Importante

As funções RBAC do Foundry foram renomeadas recentemente. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager eram anteriormente chamados de Usuário do Azure AI, Proprietário do Azure AI, Proprietário da conta do Azure AI e Gerente de Projeto do Azure AI. Você ainda pode ver os nomes anteriores em alguns lugares enquanto essa mudança de nome está sendo implementada. Os IDs das funções e as permissões principais não são alterados com a mudança de nome.

Mapeamento do SDK

Use a tabela a seguir para identificar a quais pacotes do SDK correspondem à experiência atual do Foundry e quais substituem.

Pacote do SDK Equivalente clássico Status Notas
openai azure-ai-inference Usar para inferência de modelo azure-ai-inference será descontinuado em 26 de agosto de 2026.
OpenAI() por base_url AzureOpenAI() Usar o cliente padrão Código específico do Azure eliminado.
azure-ai-projects 2.x azure-ai-projects 1.x Estável — direcionado ao novo portal 1.x foca na experiência clássica do portal.
azure-ai-projects 2.x azure-ai-generative Estável Funcionalidades mescladas no cliente de projeto.
azure-ai-projects 2.x azure-ai-ml Estável Para cenários de migração de hub para projeto.
azure-ai-projects (remoto) + azure-ai-evaluation (local) azure-ai-evaluation (autônomo) Estável Avaliações remotas por meio do cliente do projeto; avaliações locais inalteradas.
azure-search-documents (por meio de conexões de projeto) azure-search-documents Estável Pacote separado, detectável por meio do cliente do projeto.

Aviso

Verifique se a versão do SDK corresponde à experiência do portal. Usar um exemplo de SDK 2.x com uma configuração 1.x (ou vice-versa) causa erros.

O exemplo a seguir mostra a migração mais comum do SDK , substituindo o cliente AzureOpenAI específico de Azure pelo cliente OpenAI padrão.

Clássico (antes):

from openai import AzureOpenAI

client = AzureOpenAI(
    azure_endpoint="https://my-resource.openai.azure.com",
    api_key="my-key",
    api_version="2024-12-01-preview"
)

Atual (depois):

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

client = OpenAI(
    base_url="https://my-project.services.ai.azure.com/openai/v1",
    default_headers={"Authorization": f"Bearer {get_bearer_token_provider(DefaultAzureCredential(), 'https://cognitiveservices.azure.com/.default')()}"}
)

Comparação de funcionalidades

As tabelas a seguir comparam a disponibilidade de recursos entre as experiências clássicas e atuais do portal.

Disponível em ambos os portais

Funcionalidade Clássico Atual Notas
Projetos de fundimento ✅ ✅
Finalizações de chat ✅ ✅
Ajuste fino ✅ ✅
Avaliações ✅ ✅ Portal atual melhorado
Catálogo de modelos ✅ ✅ Expandido no portal atual

Novidades no portal atual

Esses recursos estão disponíveis apenas no portal do Foundry atual:

Funcionalidade Status
API de Respostas GA
Agentes v2 (API de Respostas) GA
Catálogo de ferramentas (mais de 1.400 ferramentas) GA (verifique o rótulo em ferramentas individuais no catálogo para determinar se elas são GA ou Versão Prévia)
Fluxos de trabalho de vários agentes Visualizar
Memória do agente Visualizar
Publicação de agente no Microsoft 365/Teams GA
Fundição IQ Visualizar
Agentes hospedados GA
Protocolo A2A Visualizar
Plano de controle de fundimento Visualizar

Apenas versão clássica (necessária migração)

Funcionalidade Clássico Atual Ação de migração
Recursos do Azure OpenAI ✅ Usar o recurso Foundry Fazer upgrade para um recurso do Foundry
Projetos baseados em hub ✅ Não visível Alternar para o portal clássico ou migrar para projetos do Foundry

O portal clássico usa um único painel esquerdo personalizável para toda a navegação, com o Centro de Gerenciamento na parte inferior. O portal atual divide os recursos em seis seções de nível superior, cada uma com seu próprio painel esquerdo.

Captura de tela da home page do portal do Foundry atual.

Seção Scope O que você encontra lá
Casa Projeto selecionado Visão geral do projeto e ações rápidas
Descobrir Projeto selecionado Catálogo de modelos e referências de modelos
Construir Projeto selecionado Agentes, modelos, áreas de teste, avaliações, otimização
Operar Todos os projetos Conformidade, integridade da frota, rastreamento, ativos
Gerenciar Projeto selecionado e seu recurso Cota, Gateway de IA, detalhes do recurso, detalhes do projeto
Docs N/A Links de documentação

No Build, os itens são agrupados em cabeçalhos de seção Criar (Agentes, Modelos, Serviços, Ferramentas, Conhecimento, Memória, Guardrails, Dados) e Otimizar (Avaliações, Ajustar) no painel esquerdo.

A tabela a seguir mapeia os locais do portal clássico usados com frequência para seus equivalentes atuais.

Tarefa Local do portal clássico Local do portal atual
Exibir implantações de modelo Modelos + pontos de extremidade no painel esquerdo Construir>Modelos
Abrir um playground Playgrounds no painel esquerdo Construir>Modelos> selecionar um modelo
Agente de compilação Agentes no painel esquerdo Construir>Agentes
Navegar pelo catálogo de modelos Catálogo de modelos no painel esquerdo Descobrir>Catálogo de modelos
Exibir avaliações Avaliação no painel esquerdo Construir>Avaliações
Ajustar um modelo Ajuste fino no painel esquerdo Construir>Ajuste fino
Rastreamento e monitoramento Rastreamento no painel esquerdo Operar>Rastreamento
Gerenciar cotas Centro de gerenciamento>Quota Gerenciar>Cota
Gerenciar usuários e permissões Centro >Usuários Gerenciar>Detalhes do projeto>Usuários
Exibir todos os projetos e recursos Centro >Todos os recursos Menu suspenso do projeto >Exibir todos os projetos
Recursos conectados Centro >Recursos conectados Gerenciar>Detalhes do projeto>Recursos conectados
Guardrails e filtros de conteúdo Guardrails + controles no painel esquerdo Operar>Conformidade

Alternar entre experiências do portal

Você pode alternar entre as experiências clássicas e atuais do portal a qualquer momento. O alternador preserva o seu contexto atual, como o projeto em que você está trabalhando.

Dica

O portal atual mostra apenas projetos do Foundry. Se você precisar acessar projetos baseados em hub ou outros tipos de recursos, volte para o portal clássico.

  1. Procure a opção Novo Foundry no banner superior.
  2. Selecione o alternador para mudar entre a experiência clássica e a atual.
  3. A página é recarregada com a interface do portal selecionada.

Solucionar problemas comuns de migração

Sintoma Causa Resolução
ModuleNotFoundError ou comportamento inesperado da API A versão do SDK não corresponde ao destino do portal Verifique a tabela de mapeamento do SDK e instale a versão correta do pacote
Projetos ausentes do novo portal Projetos baseados em hub não estão visíveis no portal atual Alterne para o portal clássico para acessar projetos baseados em hub ou migre para projetos do Foundry (o artigo aparece na documentação clássica)
Falhas na conexão do endpoint URLs antigos com vários pontos de extremidade não são mais resolvidos Atualizar para o formato de ponto de extremidade de projeto único (https://<project>.services.ai.azure.com)
AuthenticationError com novo cliente Chave de API usada com OpenAI() cliente sem o cabeçalho adequado Usar DefaultAzureCredential com um provedor de token de portador, conforme mostrado no exemplo de migração do SDK
O código do agente retorna 404 ou MethodNotAllowed Chamadas de Assistants API enviadas para um endpoint da Responses API Reescreva o código do agente para usar a API de Respostas (create_version() em vez de create_agent())
Agentes indisponíveis no portal atual O recurso foundry está em uma região que não dá suporte à API de Respostas Criar um recurso do Foundry em uma região com suporte

Conteúdo relacionado

  • Last updated on