Distribuire e usare modelli MAI in Microsoft Foundry (anteprima)

MAI-Image-2 e MAI-Image-2e sono modelli di generazione da testo a immagine che creano immagini di alta qualità e visivamente avanzate dai prompt del linguaggio naturale.

Questo articolo illustra come:

Distribuire modelli di generazione di immagini MAI in Microsoft Foundry
Eseguire l'autenticazione con Microsoft Entra ID o chiavi API
Generare immagini usando l'API di generazione di immagini MAI

Prerequisiti

Sottoscrizione Azure con un metodo di pagamento valido. Se non si ha un abbonamento Azure, creare un account Azure a pagamento.
Accesso a Microsoft Foundry con le autorizzazioni appropriate per creare e gestire le risorse.
Progetto Microsoft Foundry. MAI-Image-2 e MAI-Image-2e sono disponibili per la distribuzione standard globale (Stati Uniti centro-occidentali, Stati Uniti orientali, Stati Uniti occidentali, Europa occidentale, Svezia centrale e India meridionale).
Collaboratore servizi cognitivi ruolo nella risorsa Azure AI Foundry per distribuire i modelli. Per altre informazioni, vedere ruoli RBAC di Azure.

Distribuire modelli di generazione di immagini MAI

MAI-Image-2 e MAI-Image-2e sono disponibili per la distribuzione standard globale negli Stati Uniti centro-occidentali, Stati Uniti orientali, Stati Uniti occidentali, Europa occidentale, Svezia centrale e India meridionale. Per distribuire un modello, seguire le istruzioni riportate in Deploy Microsoft Foundry Models nel portale Foundry.

In alternativa, è possibile distribuire un modello usando il interfaccia della riga di comando di Azure. Il codice seguente illustra la distribuzione di MAI-Image-2e. Per distribuire invece MAI-Image-2, sostituire --model-name MAI-Image-2e con --model-name MAI-Image-2 e --model-version 2026-04-09 con --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

Reference:az cognitiveservices account deployment create

Dopo la distribuzione, usare il playground Foundry per testare in modo interattivo il modello con richieste di testo.

Modelli di generazione di immagini MAI disponibili

Foundry supporta l'uso di MAI-Image-2 (anteprima) e MAI-Image-2e (anteprima). Ognuno di questi modelli ha funzionalità chiave che includono:

Generazione da testo a immagine: Generare immagini di alta qualità dai prompt del linguaggio naturale, consentendo agli utenti di tradurre descrizioni testuali in output visivamente coerenti adatti a un'ampia gamma di casi d'uso creativi e di progettazione.
Sintesi fotorealistica dell'immagine: In grado di generare immagini realistiche con una struttura visiva coerente, rendendola adatta agli scenari di visualizzazione dei concetti e creazione di contenuti.
Prodotto, branding e design commerciale: ideale per immagini di prodotto, contenuti visivi di marketing, asset del brand e flussi di lavoro creativi in ambito commerciale.

Per altri dettagli sulle funzionalità del modello, vedere le funzionalità dei modelli di Microsoft in Foundry Models vendute direttamente da Azure.

MAI-Image-2 (anteprima)

MAI-Image-2 (anteprima) è un modello di generazione da testo a immagine progettato per creare immagini di alta qualità e visivamente avanzate dai prompt del linguaggio naturale. Usa un approccio generativo basato sulla diffusione per perfezionare progressivamente le immagini, consentendo un allineamento forte tra il testo di input e l'output generato. Il modello è ottimizzato per produrre immagini diverse e coerenti in un'ampia gamma di scenari creativi e di progettazione, rendendolo adatto per attività come la visualizzazione dei concetti, la generazione di contenuti creativi e i flussi di lavoro di progettazione delle immagini.

MAI-Image-2e (anteprima)

MAI-Image-2e (anteprima) offre una generazione di immagini di alta qualità, proprio come MAI-Image-2, ma fino a 22% più veloce e quattro volte più efficiente di MAI-Image-2, rendendola la scelta più intelligente per gli sviluppatori che creano su larga scala. MAI-Image-2e è più adatto per scenari a volume elevato e rapido, ad esempio immagini di prodotto su larga scala, variazioni di marketing, asset di marca o qualsiasi flusso di lavoro in cui l'efficienza e il costo per ogni immagine sono fondamentali.

Panoramica della generazione di immagini con modelli di generazione di immagini MAI

Dopo aver distribuito un modello di generazione di immagini MAI, usare l'API di generazione di immagini MAI per generare immagini. Si tratta di un endpoint gestito da Microsoft che accetta una richiesta di testo e restituisce un'immagine PNG.

Endpoint API

L'endpoint API ha il formato seguente:

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

Per eseguire l'autenticazione, è necessario l'endpoint resource e un token Microsoft Entra ID o una chiave API. È possibile trovare questi valori nella sezione Keys e Endpoint della risorsa nel portale di Azure oppure nella pagina dei dettagli della distribuzione nel portale Foundry portal.

Funzionalità del modello

Entrambi i modelli accettano input di testo (32.000 token) e generano un'immagine PNG. Entrambi width e height devono essere almeno 768 pixel ciascuno. Il numero totale di pixel (width × height) non deve superare 1.048.576 (equivalente a 1024×1024). Poiché il vincolo si trova su pixel totali anziché su ogni dimensione singolarmente, una dimensione può superare 1024 purché il totale rimanga entro il limite. Ad esempio, un'immagine 768×1365 ha 1.048.320 pixel totali, che si trova all'interno dei pixel totali consentiti.

Nella tabella seguente sono elencati i parametri della richiesta:

Parametro	Digitare	Descrizione
`model`	Stringa	Nome della distribuzione assegnato quando è stato distribuito il modello.
`prompt`	Stringa	Richiesta di testo che descrive l'immagine da generare. Lunghezza massima del contesto: 32.000 token.
`width`	Intero	Larghezza dell'immagine di output in pixel. Minimo: 768. Il prodotto di `width` × `height` non deve superare 1.048.576.
`height`	Intero	Altezza dell'immagine di output in pixel. Minimo: 768. Il prodotto di `width` × `height` non deve superare 1.048.576.

Nota

Il formato di output è sempre PNG. Il numero massimo di pixel è 1.048.576 (equivalente a 1024×1024). Entrambi width e height devono essere almeno 768 pixel ciascuno. Entrambe le dimensioni possono superare 1024 purché il numero totale di pixel rimanga entro il limite.

Generare immagini

Gli esempi seguenti illustrano come generare un'immagine da un prompt di testo usando modelli di generazione di immagini MAI con l'API di generazione di immagini MAI.

Python
API REST

Usare l'autenticazione con chiave API

Installare la requests libreria:
```
pip install requests
```

Impostare le variabili di ambiente:

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

Eseguire il codice seguente:

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)

Output previsto: Risposta JSON contenente i dati dell'immagine generati in formato Base64. L'immagine viene decodificata e salvata come output.png nella directory corrente.

Usare l'autenticazione Microsoft Entra ID

Per usare Microsoft Entra ID anziché una chiave API, sostituire l'intestazione api-key con un token di connessione ottenuto usando il DefaultAzureCredential:

Installare la libreria di identità Azure:
```
pip install azure-identity
```

Aggiornare le intestazioni della richiesta nel codice precedente:

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}",
}

Riferimento:DefaultAzureCredential

Usare l'autenticazione con chiave API

Esportare l'endpoint e la chiave API, quindi eseguire il comando cURL seguente:

export AZURE_API_KEY="<your-api-key>"
export DEPLOYMENT_NAME="<your-deployment-name>"

curl -X POST "https://<resource-name>.services.ai.azure.com/mai/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_API_KEY" \
  -d '{
      "model": "'"$DEPLOYMENT_NAME"'",
      "prompt": "A photorealistic image of a mountain lake at sunrise",
      "width": 1024,
      "height": 1024
    }' \
  | jq -r '.data[0].b64_json' \
  | base64 --decode > output.png

Output previsto: Risposta JSON contenente i dati dell'immagine generati in formato Base64. L'immagine viene decodificata e salvata come output.png nella directory corrente.

Usare l'autenticazione Microsoft Entra ID

Sostituire l'intestazione api-key con un'intestazione Authorization :

-H "Authorization: Bearer $AZURE_AUTH_TOKEN"

Dove AZURE_AUTH_TOKEN è un token valido di Microsoft Entra ID con ambito definito da https://cognitiveservices.azure.com/.default.

Quote e limiti dell'API

I modelli di generazione di immagini MAI hanno i limiti di frequenza seguenti misurati in Richieste al minuto (RPM). Il livello disponibile dipende dalla sottoscrizione e dalla configurazione della distribuzione.

Tipo di distribuzione	Livello	RPM MAI-Image-2e	RPM MAI-Image-2
Standard globale	1	18	9
Standard globale	2	30	15
Standard globale	3	60	30
Standard globale	4	90	45
Standard globale	5	120	60
Standard globale	6	180	90

Per richiedere un aumento della quota, inviare il modulo di richiesta di aumento della quota. Le richieste vengono elaborate nell'ordine in cui vengono ricevute e la priorità passa ai clienti che usano attivamente l'allocazione di quote esistente.

Risoluzione dei problemi

Usare la tabella seguente per risolvere gli errori comuni quando si usano i modelli di generazione di immagini MAI:

Errore	Causa	Correzione
`401 Unauthorized`	Chiave API o token scaduto non valido	Rigenerare la chiave nel portale di Azure. Per l'autenticazione Entra ID, verificare che l'ambito del token sia `https://cognitiveservices.azure.com/.default`.
`404 Not Found`	Nome della distribuzione o URL dell'endpoint non corretto	Verificare il nome della distribuzione e l'endpoint nel portale Foundry in Distribuzioni.
`400 Bad Request`	`width` o `height` al di sotto del valore minimo o il conteggio totale dei pixel supera il valore massimo	Assicurarsi che `width` e `height` siano almeno 768 e che `width` × `height` ≤ 1,048,576.
`429 Too Many Requests`	Limite di velocità superato	Attendere e riprovare oppure richiedere un aumento della quota.

Considerazioni sull'IA responsabile

Quando si usano modelli di generazione di immagini MAI in Foundry, considerare queste procedure di IA responsabili:

Tenere presente le limitazioni note: nonostante le mitigazioni tecniche, ad esempio il filtro dei dati e i classificatori di contenuto applicati a livello di sistema, i modelli di generazione di immagini possono produrre contenuto dannoso o imprevisto in base alle richieste degli utenti. Le aree di rischio comuni includono contenuti violenti o gory, contenuti sessuali o nudità, rappresentazioni di figure pubbliche e replica di materiale registrato o altro materiale protetto.
Configurare la sicurezza del contenuto: applicare misure di mitigazione aggiuntive appropriate al caso d'uso, perché nessun modello generativo è immune alle richieste antagoniste.
Rispettare le condizioni applicabili: assicurati che l'uso delle immagini generate sia conforme alle condizioni del servizio di Microsoft e alle leggi applicabili sul copyright e la proprietà intellettuale.
Essere trasparenti: divulgare il contenuto generato dall'intelligenza artificiale durante la condivisione o la pubblicazione di immagini.
Evitare contenuti dannosi: non generare contenuto dannoso, fuorviante o violazione della privacy.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-04-14

Distribuire e usare modelli MAI in Microsoft Foundry (anteprima)

Prerequisiti

Distribuire modelli di generazione di immagini MAI

Modelli di generazione di immagini MAI disponibili

MAI-Image-2 (anteprima)

MAI-Image-2e (anteprima)

Panoramica della generazione di immagini con modelli di generazione di immagini MAI

Endpoint API

Funzionalità del modello

Generare immagini

Usare l'autenticazione con chiave API

Usare l'autenticazione Microsoft Entra ID

Quote e limiti dell'API

Risoluzione dei problemi

Considerazioni sull'IA responsabile

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive