Trabalhando com modelos

Azure OpenAI no Microsoft Foundry Models é alimentado por um conjunto diversificado de modelos com diferentes funcionalidades e pontos de preço. A disponibilidade do modelo varia de acordo com a região.

Você pode obter uma lista de modelos disponíveis para inferência e ajuste fino pelo recurso Azure OpenAI usando a API de Lista Models.

Este artigo mostra como:

  • Configurar atualizações automáticas de modelo.
  • Exibir e atualizar a política de atualização de versão de uma implantação.
  • Atualize uma versão de modelo implantada usando a API de Azure Resource Manager.
  • Migre implantações provisionadas para uma versão ou família de modelos diferentes.

Pré-requisitos

  • Uma assinatura do Azure com modelos OpenAI do Azure.

Atualizações de modelo

Azure OpenAI dá suporte a atualizações automáticas para implantações de modelo selecionadas. Em modelos em que o suporte à atualização automática está disponível, há uma lista suspensa de política de atualização de versão do modelo.

Você pode saber mais sobre as versões de modelo Azure OpenAI e como elas funcionam no artigo Azure OpenAI model versions.

Nota

As atualizações automáticas de modelo só têm suporte para tipos de implantação Standard. Para obter mais informações sobre como gerenciar atualizações de modelo e migrações em tipos de implantação provisionados, consulte a seção sobre como gerenciar modelos em tipos de implantação provisionados

Atualização automática para padrão

Quando você define sua implantação como atualização automática como padrão, sua implantação de modelo é atualizada automaticamente dentro de duas semanas após uma alteração na versão padrão. Para uma versão prévia, ela é atualizada automaticamente quando uma nova versão prévia está disponível a partir de duas semanas após o lançamento da nova versão prévia.

Se você ainda estiver nas fases iniciais de teste para modelos de inferência, recomendamos implantar modelos com atualização automática para o conjunto padrão sempre que ele estiver disponível.

Versão específica do modelo

À medida que o uso de Azure OpenAI evolui e você começa a criar e integrar aplicativos, talvez queira controlar manualmente as atualizações de modelos. Primeiro, você pode testar e validar se o comportamento do aplicativo é consistente para o caso de uso antes de atualizar.

Quando você seleciona uma versão de modelo específica para uma implantação, essa versão permanece selecionada até que você opte por se atualizar manualmente ou depois de chegar à data de desativação do modelo. Quando a data de desativação for atingida, o modelo será atualizado automaticamente para a versão padrão no momento da desativação.

Configuração de atualização de implantação de modelo

Você pode verificar quais opções de atualização de modelo estão definidas para modelos implantados anteriormente usando REST, CLI do Azure e Azure PowerShell, bem como com o portal do Foundry.

A propriedade correspondente também pode ser acessada por meio de REST, Azure PowerShell e CLI do Azure.

Opção Ler Atualização
REST Sim. Se versionUpgradeOption não for retornado, significa que é null Sim
Azure PowerShell Sim. VersionUpgradeOption pode ser verificado em relação a $null Sim
CLI do Azure Sim. Ele mostra null se versionUpgradeOption não está definido. Não. No momento, não é possível atualizar a opção de atualização de versão.

Há três opções distintas de atualização de implantação de modelo:

Nome Descrição
OnceNewDefaultVersionAvailable Depois que uma nova versão é designada como padrão, a implantação do modelo é atualizada automaticamente para a versão padrão dentro de duas semanas após essa alteração de designação ser feita.
OnceCurrentVersionExpired Depois que a data de desativação for atingida, a implantação do modelo será atualizada automaticamente para a versão padrão atual.
NoAutoUpgrade O modelo de implantação nunca é atualizado automaticamente. Depois que a data de desativação for atingida, a implantação do modelo deixará de funcionar. Você precisa atualizar seu código que referencia essa implantação para apontar para uma implantação de modelo não expirada.

Nota

null é equivalente a OnceCurrentVersionExpired. Se a opção de política de atualização de versão não estiver presente nas propriedades de um modelo que dá suporte a atualizações de modelo, isso indicará que o valor está atualmente null. Depois de modificar explicitamente esse valor, a propriedade ficará visível na página de propriedades do estúdio, bem como por meio da API REST.

Exemplos

Revise o guia de introdução do Azure PowerShell para instalar o Azure PowerShell localmente ou você pode usar o Azure Cloud Shell.

As etapas abaixo demonstram verificar a propriedade de opção VersionUpgradeOption , bem como atualizá-la:

# Step 1: Get deployment
$deployment = Get-AzCognitiveServicesAccountDeployment -ResourceGroupName {ResourceGroupName} -AccountName {AccountName} -Name {DeploymentName}
 
# Step 2: Show VersionUpgradeOption
$deployment.Properties.VersionUpgradeOption
 
# VersionUpgradeOption can be null. One way to check is:
$null -eq $deployment.Properties.VersionUpgradeOption
 
# Step 3: Update VersionUpgradeOption
$deployment.Properties.VersionUpgradeOption = "NoAutoUpgrade"
New-AzCognitiveServicesAccountDeployment -ResourceGroupName {ResourceGroupName} -AccountName {AccountName} -Name {DeploymentName} -Properties $deployment.Properties -Sku $deployment.Sku
 
# Repeat steps 1 and 2 to confirm the change.
# If you aren't sure about the deployment name, list all deployments under an account:
Get-AzCognitiveServicesAccountDeployment -ResourceGroupName {ResourceGroupName} -AccountName {AccountName}

# Update to a new model version

# Step 1: Get deployment
$deployment = Get-AzCognitiveServicesAccountDeployment -ResourceGroupName {ResourceGroupName} -AccountName {AccountName} -Name {DeploymentName}

# Step 2: Show the current model version
$deployment.Properties.Model.Version

# Step 3: Update the model version
$deployment.Properties.Model.Version = "0613"
New-AzCognitiveServicesAccountDeployment -ResourceGroupName {ResourceGroupName} -AccountName {AccountName} -Name {DeploymentName} -Properties $deployment.Properties -Sku $deployment.Sku

# Repeat steps 1 and 2 to confirm the change.

Atualizar &implantar modelos por meio da API

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/deployments/{deploymentName}?api-version=2025-06-01

Parâmetros de caminho

Parâmetro Tipo Necessário? Descrição
accountName cadeia Necessário O nome do seu recurso OpenAI do Azure.
deploymentName cadeia Necessário O nome da implantação que você escolheu quando implantou um modelo existente ou o nome que deseja que uma nova implantação de modelo tenha.
resourceGroupName cadeia Necessário O nome do grupo de recursos associado para essa implantação de modelo.
subscriptionId cadeia Necessário ID da Assinatura para a assinatura associada.
api-version cadeia Necessário A versão da API a ser usada para esta operação. Isso segue o formato YYYY-MM-DD.

Versões com suporte

Corpo da solicitação

Esse é apenas um subconjunto dos parâmetros de corpo da solicitação disponíveis. Para obter a lista completa dos parâmetros, você pode consultar a documentação de referência da API REST.

Parâmetro Tipo Descrição
opçãoDeAtualizaçãoDeVersão String Opções de atualização de versão do modelo de implantação:
OnceNewDefaultVersionAvailable
OnceCurrentVersionExpired
NoAutoUpgrade
capacidade inteiro Isso representa a quantidade de cota que você está atribuindo a essa implantação. Um valor de 1 é igual a 1.000 tokens por minuto (TPM)

Solicitação de exemplo

curl -X PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/resource-group-temp/providers/Microsoft.CognitiveServices/accounts/docs-openai-test-001/deployments/gpt-35-turbo?api-version=2025-06-01 \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  -d '{"sku":{"name":"Standard","capacity":120},"properties": {"model": {"format": "OpenAI","name": "gpt-35-turbo","version": "0613"},"versionUpgradeOption":"OnceCurrentVersionExpired"}}'

Nota

Há várias maneiras de gerar um token de autorização. O método mais fácil para o teste inicial é iniciar o Cloud Shell do Azure portal. Em seguida, execute az account get-access-token. Você pode usar esse token como seu token de autorização temporária para teste de API.

Resposta de exemplo

 {
  "id": "/subscriptions/{subscription-id}/resourceGroups/resource-group-temp/providers/Microsoft.CognitiveServices/accounts/docs-openai-test-001/deployments/gpt-35-turbo",
  "type": "Microsoft.CognitiveServices/accounts/deployments",
  "name": "gpt-35-turbo",
  "sku": {
    "name": "Standard",
    "capacity": 120
  },
  "properties": {
    "model": {
      "format": "OpenAI",
      "name": "gpt-35-turbo",
      "version": "0613"
    },
    "versionUpgradeOption": "OnceCurrentVersionExpired",
    "capabilities": {
      "chatCompletion": "true"
    },
    "provisioningState": "Succeeded",
    "rateLimits": [
      {
        "key": "request",
        "renewalPeriod": 10,
        "count": 120
      },
      {
        "key": "token",
        "renewalPeriod": 60,
        "count": 120000
      }
    ]
  },
  "systemData": {
    "createdBy": "docs@contoso.com",
    "createdByType": "User",
    "createdAt": "2023-02-28T02:57:15.8951706Z",
    "lastModifiedBy": "docs@contoso.com",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2023-10-31T15:35:53.082912Z"
  },
  "etag": "\"GUID\""
}

Gerenciando modelos em tipos de implantação provisionados

As implantações provisionadas dão suporte a práticas de gerenciamento de modelos distintas. As práticas de gerenciamento de modelos de implantação provisionadas destinam-se a fornecer o maior controle sobre quando e como você migra entre versões de modelo e famílias de modelos. Atualmente, há duas abordagens disponíveis para gerenciar modelos em implantações provisionadas: (1) migrações locais e (2) migrações entre múltiplas implantações.

Pré-requisitos

  • Valide se a versão do modelo de destino ou a família de modelos tem suporte para o tipo de implantação existente. As migrações só podem ocorrer entre implantações provisionadas do mesmo tipo de implantação. Para obter mais informações sobre tipos de implantação, examine a documentação do tipo de implantação.
  • Valide a disponibilidade de capacidade para sua versão de modelo de destino ou família de modelos antes de tentar uma migração. Para obter mais informações sobre como determinar a disponibilidade da capacidade, examine a documentação de transparência de capacidade.
  • Para migrações de várias implantações, valide se você tem cota suficiente para dar suporte a várias implantações simultaneamente. Para obter mais informações sobre como validar a cota para cada tipo de implantação provisionada, examine a documentação de custo de taxa de transferência provisionada.

Migrações in-loco para implantações provisionadas

As migrações in-loco permitem manter o mesmo nome e tamanho de implantação provisionados ao alterar a versão do modelo ou a família de modelos atribuída a essa implantação. Com as migrações no local, o Azure OpenAI cuida da migração do tráfego existente entre diferentes versões de modelos ou famílias de modelos dentro de uma janela de 20 a 30 minutos. Durante toda a janela de migração, sua implantação provisionada exibirá um estado provisionado de "atualização". Você pode continuar usando sua implantação provisionada normalmente. Depois que a migração local for concluída, o estado provisionado será atualizado para "bem-sucedido", indicando que todo o tráfego foi migrado para a versão de modelo ou família de modelos alvo.

Migração no local: atualização de versão do modelo

As migrações in-loco destinadas à atualização de uma implantação provisionada existente para uma nova versão de modelo dentro da mesma família de modelos têm suporte por meio da Foundry, da API REST e do CLI do Azure. Para executar uma migração no local focada em uma atualização de versão do modelo no Foundry, selecione Implantações> e, em seguida, na coluna de nome de implantação, escolha o nome da implantação provisionada que você deseja migrar.

Selecionar um nome de implantação abre as Propriedades para a implantação do modelo. Nesse modo de exibição, selecione o botão Editar , que mostrará a caixa de diálogo Atualizar implantação . Selecione a lista suspensa da versão do modelo para definir uma nova versão do modelo para a implantação provisionada. Como observado, o estado do provisionamento mudará para "atualizando" durante a migração e retornará para "concluído" assim que a migração for finalizada.

Migração in-loco: alteração da família do modelo

As migrações in-loco destinadas à atualização de uma implantação provisionada existente para uma nova família de modelos têm suporte por meio da API REST e CLI do Azure. Para executar uma migração in-loco direcionada a uma alteração de família de modelo, use a solicitação de exemplo abaixo como guia. Na solicitação, você precisará atualizar o nome do modelo e a versão do modelo para o qual você está migrando.

curl -X PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/resource-group-temp/providers/Microsoft.CognitiveServices/accounts/docs-openai-test-001/deployments/gpt-4o-ptu-deployment?api-version=2024-10-01 \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  -d '{"sku":{"name":"GlobalProvisionedManaged","capacity":100},"properties": {"model": {"format": "OpenAI","name": "gpt-4o-mini","version": "2024-07-18"}}}'

Resposta de exemplo

{
  "id": "/subscriptions/{subscription-id}/resourceGroups/resource-group-temp/providers/Microsoft.CognitiveServices/accounts/docs-openai-test-001/deployments/gpt-4o-ptu-deployment",
  "type": "Microsoft.CognitiveServices/accounts/deployments",
  "name": "gpt-4o-ptu-deployment",
  "sku": {
    "name": "GlobalProvisionedManaged",
    "capacity": 100
  },
  "properties": {
    "model": {
      "format": "OpenAI",
      "name": "gpt-4o-mini",
      "version": "2024-07-18"
    },
    "versionUpgradeOption": "OnceCurrentVersionExpired",
    "currentCapacity": 100,
    "capabilities": {
      "area": "EUR",
      "chatCompletion": "true",
      "jsonObjectResponse": "true",
      "maxContextToken": "128000",
      "maxOutputToken": "16834",
      "assistants": "true"
    },
    "provisioningState": "Updating",
    "rateLimits": [
      {
        "key": "request",
        "renewalPeriod": 10,
        "count": 300
      }
    ]
  },
  "systemData": {
    "createdBy": "docs@contoso.com",
    "createdByType": "User",
    "createdAt": "2025-01-28T02:57:15.8951706Z",
    "lastModifiedBy": "docs@contoso.com",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2025-01-29T15:35:53.082912Z"
  },
  "etag": "\"GUID\""
}

Nota

Há várias maneiras de gerar um token de autorização. O método mais fácil para o teste inicial é iniciar o Cloud Shell do Azure portal. Em seguida, execute az account get-access-token. Você pode usar esse token como seu token de autorização temporária para teste de API.

Migrações multilocais para implantações provisionadas

As migrações de várias implantações permitem que você tenha maior controle sobre o processo de migração de modelo. Com migrações de várias implantações, você pode definir a velocidade com que deseja migrar seu tráfego existente para a versão ou família de modelos de destino em uma nova implantação provisionada. O processo para migrar para uma nova versão de modelo ou família de modelos usando a abordagem de migração de várias implantações é o seguinte:

  • Crie uma nova implantação provisionada. Para essa nova implantação, você pode optar por manter o mesmo tipo de implantação provisionada que a implantação existente ou selecionar um novo tipo de implantação, se desejado.
  • Transicione o tráfego da configuração provisionada existente para a nova configuração provisionada criada com sua versão de modelo alvo ou família de modelos até que todo o tráfego seja transferido da configuração original.
  • Depois que o tráfego for migrado para a nova implantação, valide se não há nenhuma solicitação de inferência sendo processada na implantação provisionada anterior, garantindo que a métrica Azure solicitações openai não mostre nenhuma chamada de API feita dentro de 5 a 10 minutos após o tráfego de inferência ser migrado para a nova implantação. Para obter mais informações sobre essa métrica, veja a documentação do Monitor Azure OpenAI.
  • Depois de confirmar que nenhuma chamada de inferência foi feita, exclua a implantação provisionada original.

Solucionando problemas

Você obtém 401 ou 403 respostas da API de Azure Resource Manager

  • Confirme se o token de acesso é válido e não expirado.
  • Confirme se você tem permissão para ler e atualizar implementações para o recurso.
  • Last updated on