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

Versione del router modello 2025-11-18 (ultima versione)

Distribuire un modello di router modello

Il router modello è dato da un unico modello Foundry da distribuire. 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 gestione di Azure. 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 il menu a tendina Modalità di routing per selezionare un profilo di routing. 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 a un subset 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.

Screenshot della selezione del subset di modelli di router.

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.6-sol", "version": "2026-07-09"},
                {"format": "Meta", "name": "Llama-4-Maverick-17B-128E-Instruct-FP8", "version": "1"}
            ]
        }
    }
}'

Testare il router modello con Risposte Fonderia e Completamenti chat

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

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.",
    )

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";

const project = new AIProjectClient(
  process.env["FOUNDRY_PROJECT_ENDPOINT"]!,
  new DefaultAzureCredential(),
);

// Get an OpenAI-compatible client that works with all Foundry models
const client = project.getOpenAIClient();

const response = await client.responses.create({
  model: process.env["MODEL_ROUTER_DEPLOYMENT_NAME"] || "model-router",
  input: "Explain retrieval-augmented generation in one sentence.",
});

// The "model" field reveals which underlying model was selected
console.log(`Responded model: ${response.model}`);
console.log(response.output_text);

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.",
        },
    ],
)

import { AzureOpenAI } from "openai";
import {
  DefaultAzureCredential,
  getBearerTokenProvider,
} from "@azure/identity";

const endpoint = process.env["AZURE_OPENAI_ENDPOINT"]!;
const deploymentName =
  process.env["MODEL_ROUTER_DEPLOYMENT_NAME"] || "model-router";
const apiVersion = "2025-11-18";

const credential = new DefaultAzureCredential();
const azureADTokenProvider = getBearerTokenProvider(
  credential,
  "https://cognitiveservices.azure.com/.default",
);

const client = new AzureOpenAI({
  endpoint,
  azureADTokenProvider,
  apiVersion,
  deployment: deploymentName,
});

const completion = await client.chat.completions.create({
  model: deploymentName,
  messages: [
    {
      role: "user",
      content: "Explain retrieval-augmented generation in one sentence.",
    },
  ],
});

// The "model" field reveals which underlying model was selected
console.log(`Responded model: ${completion.model}`);
console.log(completion.choices[0].message.content);

• Riferimento: OpenAI Responses API (responses.create, entrambe le lingue)
• Riferimento: OpenAI Chat Completions API (chat.completions.createin entrambe le lingue)
• Riferimento: AIProjectClient (Python)
• Riferimento: AIProjectClient (JavaScript/TypeScript)
• Riferimento: AzureOpenAI (OpenAI Python SDK)
• Riferimento: AzureOpenAI (OpenAI JavaScript/TypeScript SDK)

Testare il router modello nell'ambiente di prova

Nel Portale Foundry, passare alla distribuzione del router modello nella pagina Modelli ed endpoint e selezionarla 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 è stato creato un agente IA in Foundry, è possibile connettere la distribuzione del router modello per usarlo come base per il modello dell'agente. Selezionarlo dal menu a discesa modello nel playground dell'agente. L'agente avrà tutti gli strumenti e le istruzioni che hai configurato per esso, ma il modello sottostante che elabora le sue risposte verrà selezionato dal gestore dei modelli.

Per indicazioni dettagliate sui modelli di routing, sui tipi di strumenti supportati, sulle implicazioni sui costi e sugli esempi di codice per gli agenti, vedere Usare il router del modello con gli agenti Foundry.

Formato di output

La risposta standard di completamento della chat include un "model" campo che identifica il modello sottostante che ha gestito la richiesta. Puoi anche scegliere di visualizzare in anteprima i metadati per richiesta relativi ai tentativi di instradamento, allo stato e alla latenza segnalata. Per ulteriori informazioni, vedere Router del modello Monitor.

La seguente risposta di esempio è stata generata utilizzando la versione del modello router 2025-11-18:

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

Gestire le distribuzioni di router del modello con Criteri di Azure

Se l'organizzazione limita i modelli che gli sviluppatori possono distribuire, il router del modello rispetta gli stessi criteri di distribuzione del modello Foundry predefiniti che regolano le distribuzioni di modelli standard. Il criterio viene applicato in fase di distribuzione nel portale Foundry, nell'API REST, in interfaccia della riga di comando di Azure e nei modelli ARM. Per i passaggi per l'assegnazione dell'amministratore IT e l'esperienza degli sviluppatori, vedere Govern model router deployments with Criteri di Azure.

Valuta l'instradatore di modelli per il carico di lavoro

Considera la distribuzione iniziale come punto di partenza per la configurazione. Prima di inviare il traffico di produzione al router del modello, eseguirne il benchmark rispetto al modello corrente per la qualità della risposta, i costi stimati e la latenza. Usare i risultati per decidere se mantenere la configurazione, modificare una leva di routing o mantenere una distribuzione diretta del modello per parte del carico di lavoro. Per indicazioni, vedere Valutare il router modello per il carico di lavoro.

Monitorare le metriche dei modelli di router

Per esaminare il modello di gestione, i tentativi di routing, lo stato e la latenza segnalata per una singola richiesta di completamento della chat, vedere Monitorare il router del 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. Filtra in base al nome di distribuzione del router modello.
3. Suddividere le metriche in base ai modelli sottostanti, se necessario.

Monitorare i costi

È possibile monitorare i costi del router 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.

Risolvere i problemi relativi al router del modello

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 repository open source seguenti illustrano il modello di routing in diversi scenari. Ogni repository si trova su GitHub: impara, fai il fork ed estendi per accelerare l'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
• Crea un agente - Usa il modello router con gli Agenti Foundry