Implementar e usar modelos MAI no Microsoft Foundry (pré-visualização)

MAI-Image-2 e MAI-Image-2e são modelos de geração texto-para-imagem que criam imagens de alta qualidade e visualmente ricas a partir de prompts em linguagem natural.

Neste artigo, aprende como:

  • Implementar modelos de geração de imagem MAI no Microsoft Foundry
  • Autentique usando o Microsoft Entra ID ou chaves API
  • Gerar imagens usando a API de geração de imagens MAI

Pré-requisitos

  • Uma subscrição do Azure com um método de pagamento válido. Se não tiver uma subscrição Azure, crie uma conta Azure pago.
  • Acesso ao Microsoft Foundry com as permissões adequadas para criar e gerir recursos.
  • Um projeto Microsoft Foundry. O MAI-Image-2 e o MAI-Image-2e estão disponíveis para implementação em padrões globais (Centro Ocidental dos EUA, Leste dos EUA, Oeste dos EUA, Europa Ocidental, Suécia Central e Sul da Índia).
  • Contribuidor de Serviços Cognitivos papel no recurso Azure AI Foundry para implementar modelos. Para mais informações, consulte funções de RBAC do Azure.

Implementação de modelos de geração de imagem MAI

O MAI-Image-2 e o MAI-Image-2e estão disponíveis para implantação em padrões globais no Centro Ocidental dos EUA, Leste dos EUA, Oeste dos EUA, Europa Ocidental, Suécia Central e Sul da Índia. Para implementar um modelo, siga as instruções em Deploy Microsoft Foundry Models no portal Foundry.

Em alternativa, pode implementar um modelo usando a CLI do Azure. O código seguinte mostra a implementação do MAI-Image-2e. Para implementar MAI-Image-2 em vez disso, substitua --model-name MAI-Image-2e por --model-name MAI-Image-2 e --model-version 2026-04-09 por --model-version 2026-02-20.

az cognitiveservices account deployment create \
  --name <ACCOUNT_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --deployment-name <DEPLOYMENT_NAME> \
  --model-name MAI-Image-2e \
  --model-format Microsoft \
  --model-version 2026-04-09 \
  --sku-name GlobalStandard \
  --sku-capacity 1

Referência:az cognitiveservices account deployment create

Após a implementação, use o Foundry Playground para testar interativamente o modelo com prompts de texto.

Modelos disponíveis de geração de imagem MAI

O Foundry suporta o uso do MAI-Image-2 (Prévia) e MAI-Image-2e (Prévia). Cada um destes modelos possui capacidades chave que incluem:

  • Geração de texto para imagem: Gerar imagens de alta qualidade a partir de prompts em linguagem natural, permitindo aos utilizadores traduzir descrições textuais em resultados visualmente coerentes, adequados para uma vasta gama de casos de uso criativos e de design.
  • Síntese fotorrealista de imagem: Capaz de gerar imagens realistas com uma estrutura visual consistente, tornando-a adequada para visualização de conceitos e cenários de criação de conteúdo.
  • Produto, imagem de marca e design comercial: Ideal para imagens de produtos, visuais de marketing, elementos de marca e fluxos de trabalho criativos comerciais.

Para mais detalhes sobre as capacidades dos modelos, consulte as capacidades dos modelos Microsoft em Foundry Models vendidos diretamente por Azure.

MAI-Imagem-2 (Pré-visualização)

MAI-Image-2 (Pré-visualização) é um modelo de geração texto-para-imagem concebido para criar imagens de alta qualidade e visualmente ricas a partir de prompts em linguagem natural. Utiliza uma abordagem generativa baseada em difusão para refinar progressivamente as imagens, permitindo um forte alinhamento entre o texto de entrada e a saída gerada. O modelo está otimizado para produzir imagens diversas e coerentes numa vasta gama de cenários criativos e de design, tornando-o adequado para tarefas como visualização de conceitos, geração de conteúdos criativos e fluxos de trabalho de design de imagens.

MAI-Imagem-2e (Pré-visualização)

O MAI-Image-2e (Pré-visualização) oferece geração de imagem de alta qualidade – tal como o MAI-Image-2 – mas até 22% mais rápida e quatro vezes mais eficiente do que o MAI-Image-2, tornando-o a escolha mais inteligente para desenvolvedores que desenvolvem em grande escala. O MAI-Image-2e é mais indicado para cenários de grande volume e resposta rápida — por exemplo, imagens de produtos em escala, variações de marketing, ativos de marca ou qualquer fluxo de trabalho onde a eficiência e o custo por imagem sejam fundamentais.

Visão geral da geração de imagens com modelos de geração de imagens MAI

Depois de implementares um modelo de geração de imagens MAI, usa a API de geração de imagens MAI para gerar imagens. Este é um endpoint gerido pela Microsoft que aceita um prompt de texto e devolve uma imagem PNG.

Endpoint API

O endpoint da API tem a seguinte forma:

https://<resource-name>.services.ai.azure.com/mai/v1/images/generations

Para autenticar, precisa do seu endpoint resource e de um token Microsoft Entra ID ou de uma chave API. Pode encontrar estes valores na secção Keys e Endpoint do seu recurso no portal Azure, ou na página de detalhes de implementação no portal Foundry.

Capacidades do modelo

Ambos os modelos aceitam entrada de texto (32.000 tokens) e produzem uma imagem PNG. Ambos width e height devem ter pelo menos 768 píxeis cada. A contagem total de píxeis (width × height) não deve exceder 1.048.576 (equivalente a 1024×1024). Como a restrição está no total de píxeis e não em cada dimensão individualmente, uma dimensão pode exceder 1024 desde que o total se mantenha dentro do limite. Por exemplo, uma imagem de 768×1365 tem 1.048.320 píxeis totais, o que está dentro do máximo permitido de píxeis.

A tabela seguinte lista os parâmetros do pedido:

Parâmetro Tipo Descrição
model cadeia (de caracteres) O nome de implementação que atribuiste quando implementaste o modelo.
prompt cadeia (de caracteres) O prompt de texto que descreve a imagem a gerar. Comprimento máximo do contexto: 32.000 tokens.
width número inteiro Largura da imagem de saída em pixels. Mínimo: 768. O produto de width × height não deve exceder 1.048.576.
height número inteiro Altura da imagem de saída em pixels. Mínimo: 768. O produto de width × height não deve exceder 1.048.576.

Nota

O formato de saída é sempre PNG. A contagem máxima total de píxeis é de 1.048.576 (equivalente a 1024×1024). Ambos width e height devem ter pelo menos 768 píxeis cada. Qualquer uma das dimensões pode exceder 1024 desde que a contagem total de pixels se mantenha dentro do limite.

Gerar imagens

Os exemplos seguintes mostram como gerar uma imagem a partir de um prompt de texto usando modelos de geração de imagem MAI com a API de geração de imagens MAI.

Utilizar autenticação por chave API

  1. Instalar a requests biblioteca:

    pip install requests

  2. Definir variáveis do ambiente:

    export AZURE_ENDPOINT="https://<resource-name>.services.ai.azure.com"
export AZURE_API_KEY="<your-api-key>"
export DEPLOYMENT_NAME="<your-deployment-name>"

  3. Execute o seguinte código:

    import os
import base64
import requests

endpoint = os.environ["AZURE_ENDPOINT"]
api_key = os.environ["AZURE_API_KEY"]
deployment_name = os.environ["DEPLOYMENT_NAME"]

width = 1024
height = 1024

url = f"{endpoint}/mai/v1/images/generations"

payload = {
    "model": deployment_name,
    "prompt": "A photorealistic image of a mountain lake at sunrise",
    "width": width,
    "height": height
}

response = requests.post(
    url,
    headers={
        "Content-Type": "application/json",
        "api-key": api_key,
    },
    json=payload,
)
response.raise_for_status()

result = response.json()
print(result)

image_data = [
    output
    for output in result.get("data", [])
    if "b64_json" in output
]

if image_data:
    image_base64 = image_data[0]["b64_json"]
    output_path = "output.png"
    with open(output_path, "wb") as f:
        f.write(base64.b64decode(image_base64))
    print(f"Image saved to {output_path}")
else:
    print("Unexpected response format:", result)

    Produção esperada: Uma resposta JSON contendo os dados da imagem gerados em formato base64. A imagem é decodificada e guardada como output.png no diretório atual.

Use autenticação Microsoft Entra ID

Para usar Microsoft Entra ID em vez de uma chave API, substitua o cabeçalho api-key por um token portador obtido usando o DefaultAzureCredential:

  1. Instale a biblioteca Azure Identity:

    pip install azure-identity

  2. Atualize os cabeçalhos dos pedidos no código anterior:

    from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)
token = token_provider()

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}",
}

    Referência:DefaultAzureCredential

Quotas e limites da API

Os modelos de geração de imagem MAI têm os seguintes limites de taxa medidos em Pedidos Por Minuto (RPM). O nível disponível para si depende da sua subscrição e configuração de implementação.

Tipo de Implantação Tier MAI-Imagem-2e RPM MAI-Imagem-2 RPM
Padrão Global 1 18 9
Padrão Global 2 30 15
Padrão Global 3 60 30
Padrão Global 4 90 45
Padrão Global 5 120 60
Padrão Global 6 180 90

Para solicitar um aumento de quota, submeta o formulário de pedido de aumento de quota. Os pedidos são processados pela ordem em que são recebidos, e a prioridade vai para os clientes que utilizam ativamente a quota que já utilizam.

Resolução de problemas

Use a tabela seguinte para resolver erros comuns ao trabalhar com modelos de geração de imagem MAI:

Erro Causa Corrigir
401 Unauthorized Chave API inválida ou token expirado Regenerar a chave no portal Azure. Para a autenticação do Entra ID, assegure-se de que o âmbito do token é https://cognitiveservices.azure.com/.default.
404 Not Found Nome de implementação ou URL de endpoint incorreto Verifique o nome da implementação e o endpoint no portal Foundry em Implementações.
400 Bad Request width ou height abaixo do mínimo, ou o número total de pixels excede o máximo Certifique-se width e height cada um tem pelo menos 768, e que width × height ≤ 1.048.576.
429 Too Many Requests Limite de taxa ultrapassado Espere e tente novamente, ou peça um aumento da quota.

Considerações sobre IA responsável

Ao utilizar modelos de geração de imagens MAI no Foundry, considere estas práticas responsáveis de IA:

  • Esteja atento às limitações conhecidas: Apesar de mitigações técnicas como filtragem de dados e classificadores de conteúdo aplicados ao nível do sistema, os modelos de geração de imagens podem produzir conteúdos prejudiciais ou inesperados com base nos pedidos dos utilizadores. As áreas de risco comuns incluem conteúdo violento ou sangrento, conteúdo sexual ou nudez, representações de figuras públicas e replicação de material registado ou outro material protegido.
  • Configure a segurança do conteúdo: Aplique mitigações adicionais apropriadas ao seu caso de uso, pois nenhum modelo generativo está imune a prompts adversariais.
  • Cumprir os termos aplicáveis: Garantir que a utilização das imagens geradas cumpre os termos de serviço da Microsoft >
  • Seja transparente: Revele que o conteúdo é gerado por IA ao partilhar ou publicar imagens.
  • Evite conteúdos prejudiciais: Não gere conteúdos que possam ser prejudiciais, enganadores ou que violem a privacidade.

Conteúdo relacionado

  • Last updated on