Usare il router modello per Microsoft Foundry

Il router del modello è un modello linguistico sottoposto a training che seleziona il modello LLM (Large Language Model) migliore per rispondere a una richiesta in tempo reale. Usa modelli preesistenti diversi per offrire prestazioni elevate e risparmiare sui costi di calcolo, tutti in un'unica distribuzione di modelli. Per altre informazioni sul funzionamento del router del modello, sui relativi vantaggi e limitazioni, vedere la guida ai concetti relativi ai router del modello. Per comprendere l'architettura e la logica di routing, vedere Funzionamento del router del modello.

Modelli supportati

• ¹Richiede la registrazione.
• ²Il supporto del router per il modello è disponibile in anteprima.
• ³Il supporto per il router di modello è disponibile in anteprima. Richiede la distribuzione del modello per l'uso con il router del modello.

Distribuire un router modello

Il modello di router viene confezionato come un singolo modello Foundry che distribuisci. Per iniziare, seguire la procedura descritta nella guida alla distribuzione delle risorse.

Per distribuire a livello di codice senza il portale, usare gli esempi di API REST nelle sezioni di distribuzione seguenti.

Per impostazione predefinita, il router modello viene distribuito con la modalità di routing bilanciata e instrada attraverso l'intero set di modelli supportato. È sufficiente modificare la modalità di routing o selezionare un subset di modello quando si vuole un comportamento di routing personalizzato.

Distribuzione predefinita

Passare al portale di Microsoft Foundry e passare al catalogo dei modelli. Trovare model-router nell'elenco Modelli e selezionarlo. Scegliere Impostazioni predefinite per la modalità di routing bilanciato e la route tra tutti i modelli supportati.

Prima di eseguire gli esempi REST, accedere con interfaccia della riga di comando di Azure e salvare un token di connessione del piano di gestione come AZURE_AI_AUTH_TOKEN.

export AZURE_AI_AUTH_TOKEN=$(az account get-access-token --resource https://management.azure.com --query accessToken -o tsv)

Distribuire il router del modello programmaticamente con l'API REST di Azure Management. L'esempio seguente crea una distribuzione predefinita e si basa sulla modalità di routing bilanciata predefinita e sul set di modelli completo supportato.

curl -X PUT "https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/my-resource-group/providers/Microsoft.CognitiveServices/accounts/my-foundry-account/deployments/model-router-deployment?api-version=2025-10-01-preview" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
    -d '{
        "sku": {"name": "GlobalStandard", "capacity": 10},
        "properties": {
                "model": {"format": "OpenAI", "name": "model-router", "version": "2025-11-18"}
        }
}'

Facoltativo: personalizzare le impostazioni di distribuzione

Per abilitare altre opzioni di configurazione, scegliere Impostazioni personalizzate.

Facoltativo: modificare la modalità di routing

Accedere a Microsoft Foundry. Assicurarsi che l'interruttore New Foundry sia attivato. Questi passaggi fanno riferimento a Foundry (nuovo).These steps refer to Foundry (new).

Usare l'elenco a discesa Modalità di instradamento per selezionare un profilo di instradamento. In questo modo viene impostata la logica di routing per la distribuzione.

Quando usare ogni modalità:

• Bilanciato (impostazione predefinita): la maggior parte dei carichi di lavoro. Ottimizza i costi mantenendo la qualità.
• Qualità: attività critiche come revisione legale, riepiloghi medici o ragionamenti complessi.
• Costo: carichi di lavoro sensibili al budget elevati, ad esempio la classificazione dei contenuti o le domande e risposte semplici.

Facoltativo: indirizzare a un subset di modelli

Accedere a Microsoft Foundry. Assicurarsi che l'interruttore New Foundry sia attivato. Questi passaggi fanno riferimento a Foundry (nuovo).These steps refer to Foundry (new).

La versione più recente del router modello supporta subset personalizzati: è possibile specificare quali modelli sottostanti includere nelle decisioni di routing. In questo modo è possibile controllare maggiormente i costi, la conformità e le caratteristiche delle prestazioni.

Nel riquadro di distribuzione del router modello, selezionare Instrada verso un sottoinsieme di modelli. Selezionare quindi i modelli sottostanti da abilitare. È necessario selezionare almeno un modello per il routing. Se non sono selezionati modelli, la distribuzione usa il modello predefinito impostato per la modalità di routing.

I nuovi modelli introdotti in seguito vengono esclusi per impostazione predefinita fino a quando non vengono aggiunti in modo esplicito.

Configurare le impostazioni personalizzate con l'API REST

Usare l'esempio seguente quando si desidera impostare sia la modalità di routing che un subset di modello nella stessa richiesta di distribuzione.

Aggiungere un routing blocco solo quando si desidera eseguire l'override della modalità Bilanciata predefinita o limitare il set di modelli instradati. L'esempio seguente mantiene la richiesta personalizzata combinata con una modalità di routing e un subset di modello.

curl -X PUT "https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/my-resource-group/providers/Microsoft.CognitiveServices/accounts/my-foundry-account/deployments/model-router-deployment?api-version=2025-10-01-preview" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
  -d '{
    "sku": {"name": "GlobalStandard", "capacity": 10},
    "properties": {
        "model": {"format": "OpenAI", "name": "model-router", "version": "2025-11-18"},
        "routing": {
            "mode": "balanced",
            "models": [
                {"format": "OpenAI", "name": "gpt-4.1", "version": "2025-04-14"},
                {"format": "OpenAI", "name": "gpt-5.2-chat", "version": "2025-12-11"},
                {"format": "Meta", "name": "Llama-4-Maverick-17B-128E-Instruct-FP8", "version": "1"}
            ]
        }
    }
}'

Testare il router del modello con risposte di Foundry e completamenti della chat

Chiamare il modello router allo stesso modo in cui si chiama qualsiasi modello di chat OpenAI. Impostare il parametro model al nome del modello della distribuzione del router. È possibile usare Microsoft Foundry SDK con l'API Risposte o OpenAI Python SDK con l'API Completamento chat.

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=project_endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    response = openai_client.responses.create(
        model=deployment,
        input="In one sentence, name the most popular tourist destination in Seattle.",
    )

client = AzureOpenAI(
    azure_endpoint=endpoint,
    api_key=api_key,
    api_version="2024-10-21",
)

response = client.chat.completions.create(
    model=deployment,
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {
            "role": "user",
            "content": "In one sentence, name the most popular tourist destination in Seattle.",
        },
    ],
)

• Riferimento: AzureOpenAI (OpenAI Python SDK)
• Riferimento: AIProjectClient

Testare il modello di router nel campo di prova

Nel portale Foundry, passa alla distribuzione del router per il modello nella pagina Modelli + endpoint e selezionalo per aprire il playground del modello. Nel playground immettere i messaggi e visualizzare le risposte del modello. Ogni risposta mostra il modello sottostante selezionato dal router.

Connettere il router del modello a un agente Foundry

Accedere a Microsoft Foundry. Assicurarsi che l'interruttore New Foundry sia attivato. Questi passaggi fanno riferimento a Foundry (nuovo).These steps refer to Foundry (new).

Se hai creato un agente di intelligenza artificiale in Foundry, puoi connettere la distribuzione del routing del modello da utilizzare come modello base dell'agente. Selezionarlo dal menu a discesa del modello nel playground dell'agente. L'agente avrà tutti gli strumenti e le istruzioni configurate, ma il modello sottostante che elabora le risposte verrà selezionato dall'instradatore del modello.

Formato di output

La risposta JSON ricevuta da un modello di router è identica alla risposta API di completamento della chat standard. Si noti che il "model" campo indica quale modello sottostante è stato selezionato per rispondere alla richiesta.

La risposta di esempio seguente è stata generata usando la versione 2025-11-18dell'API :

{
    "success": true,
    "data": {
        "choices": [
            {
                "content_filter_results": {
                    "hate": {
                        "filtered": false,
                        "severity": "safe"
                    },
                    "protected_material_code": {
                        "filtered": false,
                        "detected": false
                    },
                    "protected_material_text": {
                        "filtered": false,
                        "detected": false
                    },
                    "self_harm": {
                        "filtered": false,
                        "severity": "safe"
                    },
                    "sexual": {
                        "filtered": false,
                        "severity": "safe"
                    },
                    "violence": {
                        "filtered": false,
                        "severity": "safe"
                    }
                },
                "finish_reason": "stop",
                "index": 0,
                "logprobs": null,
                "message": {
                    "annotations": [],
                    "content": "Charismatic and bold—combining brash showmanship and poetic wit with fierce competitiveness, moral conviction, and unwavering activism.",
                    "refusal": null,
                    "role": "assistant"
                }
            }
        ],
        "created": 1774543376,
        "id": "xxxx-yyyy-zzzz",
        "model": "gpt-5-mini-2025-08-07",
        "object": "chat.completion",
        "prompt_filter_results": [
            {
                "prompt_index": 0,
                "content_filter_results": {
                    "hate": {
                        "filtered": false,
                        "severity": "safe"
                    },
                    "jailbreak": {
                        "filtered": false,
                        "detected": false
                    },
                    "self_harm": {
                        "filtered": false,
                        "severity": "safe"
                    },
                    "sexual": {
                        "filtered": false,
                        "severity": "safe"
                    },
                    "violence": {
                        "filtered": false,
                        "severity": "safe"
                    }
                }
            }
        ],
        "system_fingerprint": null,
        "usage": {
            "completion_tokens": 163,
            "completion_tokens_details": {
                "accepted_prediction_tokens": 0,
                "audio_tokens": 0,
                "reasoning_tokens": 128,
                "rejected_prediction_tokens": 0
            },
            "prompt_tokens": 3254,
            "prompt_tokens_details": {
                "audio_tokens": 0,
                "cached_tokens": 3200
            },
            "total_tokens": 3417
        }
    }
}

Monitorare le metriche del router modello

Monitorare le prestazioni

Monitorare le prestazioni della distribuzione del router del modello in Monitoraggio di Azure (AzMon) nel portale di Azure.

1. Passare alla pagina Monitoring>Metrics per la risorsa OpenAI Azure nel portale di Azure.
2. Filtrare in base al nome dell'implementazione del modello di router.
3. Suddividere le metriche in base ai modelli sottostanti, se necessario.

Monitorare i costi

È possibile monitorare i costi del router del modello, ovvero la somma dei costi sostenuti dai modelli sottostanti.

1. Visitare la pagina Resource Management ->Cost analysis nel portale di Azure.
2. Se necessario, filtrare in base alla risorsa di Azure.
3. Filtrare quindi in base al nome della distribuzione: Filtrare in base a "Tag", selezionare Distribuzione come tipo del tag e quindi selezionare il nome della distribuzione del router del modello come valore.

Risoluzione dei problemi del modello di router

Problemi comuni

Codici di errore

Per i codici di errore e la risoluzione dei problemi dell'API, vedere le informazioni di riferimento Azure API REST OpenAI.

Risorse

I seguenti repository open-source mettono in mostra un router modello in diversi scenari. Ogni repository è su GitHub: impara, fai fork ed estendi per accelerare il tuo apprendimento. La maggior parte degli esempi richiede una distribuzione del router modello esistente; vedere Distribuire un modello di router modello per iniziare.

Passaggi successivi

• Concetti relativi al router del modello - Informazioni sul funzionamento delle modalità di routing
• Quote e limiti - Limiti di frequenza per il router del modello
• Creare un agente - Usare il model router con gli agenti Foundry