routing_trace that describes model attempts and a session_affinity object that describes whether model router initialized, retained, or switched a model association.
Both signals appear in the optional model_selection_details response object for the Chat Completions API. These request-level signals complement aggregate metrics and logs. For aggregate monitoring, see Monitor model deployments.
Prerequisites
- Python 3.9 or later.
- The
openai>=1.75.0andpython-dotenvpackages. Install them by runningpip install "openai>=1.75.0" python-dotenv. - A model router deployment that you can access through an Azure OpenAI endpoint.
- The endpoint and API key for your Azure OpenAI resource. The complete sample reads them from the
AZURE_OPENAI_ENDPOINTandAZURE_OPENAI_API_KEYenvironment variables. - Azure OpenAI API version
2024-10-21.
Enable request-level metadata
After your application reads the endpoint and API key intoendpoint and api_key, create the client with the preview feature header:
Foundry-Features: ModelRouterControls=V1Preview header requests per-request routing metadata. Because this feature is in preview, the metadata presence and response schema can vary by request and service version.
- Reference:
AzureOpenAIclass
Understand the response envelope
Use the top-levelmodel field and the optional model_selection_details object together to understand how the model router handled a request:
The
model_selection_details envelope and each child field are optional during preview. Parse fields defensively, and tolerate additional fields in future service versions. Don’t infer routing or affinity details when the corresponding field is absent.
Inspect routing attempts and fallback
Send a Chat Completions request through the model router deployment. The response includes the completion and, when available, routing metadata:- Reference: Chat Completions API
Review the routing trace
The following illustrativemodel_selection_details fragment contains two ordered model attempts:
modeis the routing mode returned for the request.routing_tracecontains the routing entries returned for the request.latency_msis the latency reported for a routing-trace entry.attemptslists model attempts in order.- Each attempt contains a model and an HTTP status in
result.status. - A failed attempt can include an optional
errorwith a code and message.
Parse routing and fallback information
After the Chat Completions request returnsresponse, inspect the serving model and model selection details:
error. Model names, HTTP statuses, attempt counts, and latency can vary by request and service version.
Interpret session affinity metadata
Session affinity asks the model router to try the same eligible model for related Chat Completions requests. Configure an opaque, application-owned session ID and use the same value across conversation turns:- Reference:
AzureOpenAIclass
Send related conversation turns
Send the first request, append its response and a new user message to the conversation history, and send the next request with the same session affinity configuration:- Reference: Chat Completions API
Review session affinity metadata
The first successful request for a new session ID typically returns aninitialize decision. The following illustrative response shows that result:
Parse the affinity decision
Inspect the optionalsession_affinity object for each response:
session_affinity object. Don’t infer an affinity decision when the object or decision field is absent.
Diagnose an affinity switch
Thesession_affinity and routing_trace signals complement each other and can appear in the same response. When decision is switch, check the top-level model field to identify the serving model and routing_trace to understand the attempts or fallback that caused the change: