Enabling the OpenAI v1 API Standard for Embedding and Reranker Calls

Unique AI can call embedding models and reranker models either with the classic Azure OpenAI request format (/openai/deployments/{deployment}/... plus an api-version query parameter) or with the OpenAI v1 API standard (/v1/..., no api-version). Both formats are fully supported and will remain supported — the format is selected per installation with two environment variables.

Enable the v1 standard when your model-serving platform exposes OpenAI-compatible /v1 endpoints (for example a self-hosted inference gateway, an AI gateway such as LiteLLM, or Azure OpenAI v1 endpoints).

Both variables are read by the ingestion service only. All embedding and reranker traffic of the platform originates from that service, so no other service needs to be reconfigured.

Chat completion calls are controlled separately — see the Related settings section at the end of this page.

Availability: Unique AI release 2026.28 and later.

What changes when you enable the variables

USE_OPENAI_V1_EMBEDDINGS

With the variable set to "true", embedding requests change as follows:

Endpoint handling:

• Azure OpenAI endpoints (*.openai.azure.com, *.cognitiveservices.azure.com): /openai/v1 is appended automatically. Keep your configured endpoint as-is (for example https://my-resource.openai.azure.com/). If it already contains /openai/v1, nothing is appended.

• Any other endpoint (self-hosted model serving, gateway, proxy): the configured endpoint is used exactly as provided. It must therefore already point at the OpenAI-compatible base path, for example https://models.example.com/v1, so that requests resolve to https://models.example.com/v1/embeddings.

This applies to every place an embedding endpoint is configured, including the multi-endpoint routing definitions and OAuth-protected endpoints.

USE_OPENAI_V1_RERANKER

This is a global switch for every entry in RERANKER_CONFIGURATION. There is no per-reranker override — when it is on, all configured rerankers are called with the v1 format.

Details:

• model is taken from the model field of the reranker entry, falling back to deploymentName.

• The options of a reranker entry are sent as top-level fields of the request body. top_n and max_chunks_per_doc are converted to integers; all other options are sent as strings.

• index in the response refers to the position in the submitted documents array. Results are re-ordered accordingly and relevance_score (or score) is applied to the search result.

URL composition rules for apiUrl differ from the classic format: the classic format expects the full rerank URL, the v1 format expects the base URL.

Prerequisites

Before enabling either variable:

1. Embeddings — every configured embedding endpoint must accept POST {base}/v1/embeddings (or POST {endpoint}/openai/v1/embeddings for Azure OpenAI) with bearer-token or managed-identity authentication.

2. Reranker — every entry in RERANKER_CONFIGURATION must accept POST {base}/v1/rerank with the { model, query, documents } body and return { results: [{ index, relevance_score }] }. Rerankers that only speak the classic { query, chunks, options } format — including Unique's self-hosted cross-encoder reranker — are not v1-compatible. Migrate or remove them before switching the variable on.

Because USE_OPENAI_V1_RERANKER is global, a mixed setup (one v1 reranker plus one classic reranker) is not supported.

Configuration

Set the variables in the env section of the ingestion service's Helm values, then roll out the service.

Embeddings

env:
  USE_OPENAI_V1_EMBEDDINGS: 'true'

For a non-Azure model-serving platform, make sure the embedding endpoint includes the v1 base path:

env:
  USE_OPENAI_V1_EMBEDDINGS: 'true'
  AZURE_OPENAI_API_ENDPOINT: 'https://models.example.com/v1'

If you use the multi-endpoint embedding routing (EMBEDDING_MODEL_ENDPOINT_DEFINITIONS) or additional embedding models (ADDITIONAL_EMBEDDING_MODELS_JSON), apply the same rule to every endpoint entry in those definitions.

Reranker

env:
  USE_OPENAI_V1_RERANKER: 'true'
  RERANKER_CONFIGURATION: |
    [
      {
        "deploymentName": "crossencoder_reranker",
        "apiUrl": "https://models.example.com",
        "apiKey": "<api-key>",
        "model": "rerank-v3.5",
        "options": { "top_n": "3" }
      }
    ]

• deploymentName is the name selected in the space / assistant configuration — keep it stable when switching formats, otherwise existing configurations stop resolving.

• apiUrl is the base URL (see the URL composition table above).

• apiKey may be omitted for unauthenticated in-cluster endpoints. In v1 mode it can also be set to the literal value WORKLOAD_IDENTITY, which makes the service authenticate with its Azure workload identity instead of a static key.

Values must be the quoted strings 'true' / 'false'.

Verification

After the rollout:

1. Embeddings — upload a document and confirm it reaches the finished ingestion state, then run a search that returns content from it. Both ingestion and search use the same embedding path, so a successful search over a newly uploaded document validates both.

2. Reranker — run a search in a space that has the reranker enabled and confirm the ingestion service logs a reranking call without a fallback warning.

Watch the ingestion service logs for these messages, which indicate the v1 endpoint rejected the request:

OpenAI v1 reranking failed: <status> <statusText> falling back on original search results
Reranking failed on request to reranker falling back on original search results

Important: a failing reranker does not fail the search. Unique AI falls back to the un-reranked result order and the search still returns results. Result quality degrades silently, so verify the logs explicitly after enabling USE_OPENAI_V1_RERANKER. Embedding failures behave differently — they surface as ingestion or search errors.

Rollback

Set the variable back to 'false' and roll out the service. If you changed endpoint URLs for the v1 format, revert those in the same step:

• embedding endpoints: remove the /v1 suffix added for the v1 format

• RERANKER_CONFIGURATION: restore the full classic rerank path (for example https://models.example.com/rerank)

No data migration or re-ingestion is required in either direction: the switch only changes how the models are called, not the vectors that are stored. Re-ingestion is only needed if you also change the embedding model.

Related settings

If your model-serving platform switches to the OpenAI v1 standard for all model types, all three settings need to be enabled — they are independent of each other and can be rolled out one at a time.