Skip to content

V2: Make Azure OpenAI v1 routing and API-version guidance consistent #1845

Open

Description

@paullizer

Issue

Make model connection setup and runtime routing clearly distinguish Azure OpenAI's v1 protocol from the dated api-version used by the legacy Azure client. A customer reports that Endpoint default (v1) does not work while 2024-10-01-preview returns a response. Their exact connection metadata and error are not yet available, so the customer-specific root cause remains unconfirmed.

The application currently chooses a wire protocol using provider/API type/endpoint shape, not just the API-version selector. A literal v1 on a legacy Azure connection is not a switch to the v1 protocol. Conversely, the normalized Foundry/OpenAI-style /openai/v1/ client deliberately omits all dated api-version query values. Switching the version selector can therefore mean different things on different connection paths.

Steps to Reproduce

  1. Construct the legacy AzureOpenAI client with a resource-root endpoint and api_version="v1", using a mocked HTTP transport.
  2. Observe the SDK request shape /openai/deployments/<deployment>/chat/completions?api-version=v1.
  3. Construct the OpenAI-style client with a /openai/v1/ base URL.
  4. Observe /openai/v1/chat/completions with no dated version query.
  5. Trace the relevant SimpleChat connection/provider/protocol configuration into those builders and compare the guidance shown in the connection editor.

The two SDK wire shapes were reproduced offline. No live assertion was made about the customer's Azure deployment.

Expected Behavior

An admin can tell which inference protocol is selected, enter only settings valid for that protocol, and understand which field controls inference versus Foundry project discovery. Selecting endpoint-default v1 must either select a valid v1 route or be rejected clearly for a dated-version connection.

Actual Behavior

The shared version wording allows v1 to be read as a universal API-version value. An apparently reasonable setting can remain on a legacy Azure SDK path, while dated selections on a normalized v1 path are intentionally not forwarded. A successful basic completion also does not validate every model/tool feature.

Impact

Admins can change versions without changing the actual inference protocol, receive confusing errors, or assume a React UI upgrade alone fixes model/API compatibility.

Acceptance Criteria

  • Document and validate the provider/API-type/endpoint/version combinations for legacy Azure inference and OpenAI-style v1 inference. Keep project discovery versions separate.
  • Prevent literal api-version=v1 from being mistaken for /openai/v1/ routing. Preserve valid existing dated-version configurations and require an explicit supported migration rather than silently rewriting connections.
  • Make V2 connection labels, help, test-connection diagnostics, and runtime construction agree on the effective protocol and version behavior.
  • Surface safe, actionable configuration errors without exposing credentials, raw settings, internal URLs, or provider response secrets to ordinary users.
  • Add mocked SDK request tests for actual paths/query parameters, selected deployment identity, API-key and managed-identity authentication, and relevant custom/APIM prefix behavior.
  • Clearly state that an API-version change does not bypass GPT-5.6's Chat Completions reasoning-plus-tools restriction; coordinate with V2: Support reasoning with tools across agents and orchestration #472 and the explicit-None compatibility work.
  • Publish route-specific current-main and V2 guidance. For the reported legacy setup, the currently working 2024-10-01-preview is an interim configuration, not a universal recommended default; true v1 inference uses its v1 path without a dated query.
  • Update tests/documentation and the application version when implementing.

Notes

Target: paullizer-react-v2-ui. Priority: P1. Assignee: Paul Lizer (@paullizer). Roadmap size: M.

Reviewed main: f5bcae7a4 (0.261.027). Reviewed latest V2: 11daaaa85. The newer V2 timeout/resilience changes do not replace the protocol inference rules.

Relevant areas: connection editor/modal and provider descriptors, model_endpoint_clients.py, functions_model_endpoint_runtime.py, model endpoint validation, and connection documentation. Related configuration/routing work: #1436 and #1518; do not duplicate or regress that work.

Official v1 contract: https://learn.microsoft.com/en-us/azure/foundry/openai/api-version-lifecycle

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

P1Priority 1: urgent, address before P2 workbugSomething isn't working

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions