Reasoning Effort Mapping

Reasoning-capable models do not always use the same effort vocabulary. A client might send medium, while a selected upstream model accepts only high or max. Configure effort_mapping on a direct model to rewrite those values at the gateway.

The mapping is disabled by default. AISIX changes a request only when it contains an effort string that exactly matches a configured key.

How Mapping Works

AISIX reads the effort from the normalized endpoint the caller uses:

Endpoint	Request field
POST /v1/chat/completions	reasoning_effort
POST /v1/responses	reasoning.effort
POST /v1/messages	output_config.effort
POST /v1/messages/count_tokens	output_config.effort

It applies one exact, case-sensitive lookup after selecting the final direct model and before serializing the provider request. The same behavior applies to streaming and non-streaming requests and when AISIX translates between OpenAI and Anthropic request formats.

For this mapping:

{
  "medium": "high",
  "high": "max"
}

• medium becomes high. AISIX does not look up the resulting high again, so it does not become max.
• high becomes max.
• An unmapped value such as low remains low.
• A request with no effort field remains unchanged; the mapping does not add one.

The mapping belongs to the direct target, not the alias the caller addressed. When a routing model or semantic router selects a direct model, that target's mapping applies. Each ensemble panel member uses its own mapping, and the direct judge model uses its own mapping for the synthesis request. Configure no mapping on routing, semantic, ensemble, or embedding model resources; AISIX rejects it on those kinds.

Provider and model support still applies after the rewrite. Use only target values that the selected upstream model accepts. A provider adapter can translate, omit, or reject an unsupported value according to that provider's normalized endpoint behavior. Passthrough routes do not use model resources and do not apply effort mapping.

Configure AISIX Cloud

In the Dashboard, create or edit a direct model, expand Reasoning effort mapping, and add each requested value and upstream value pair. Remove every row and save to disable the mapping.

You can also set the mapping with the Admin API. The following request creates a direct model that changes medium to high and high to max:

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "direct",
    "display_name": "reasoning-prod",
    "model_name": "YOUR_UPSTREAM_MODEL",
    "provider_key_id": "'"$PROVIDER_KEY_ID"'",
    "effort_mapping": {
      "medium": "high",
      "high": "max"
    }
  }'

On update, omit effort_mapping to leave it unchanged. Send null or an empty object to clear it:

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/models/$MODEL_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"effort_mapping": null}'

Configure the Open-Source Gateway

Add effort_mapping to a direct model in the complete resources.yaml snapshot:

resources.yaml (direct model)

models:
  - display_name: reasoning-prod
    provider: openai
    model_name: YOUR_UPSTREAM_MODEL
    provider_key: openai-prod
    effort_mapping:
      medium: high
      high: max

Omit effort_mapping, or set it to an empty object, to disable the rewrite.

Send a Request

Call the model normally. Applications do not need provider-specific effort settings:

export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"

curl -sS "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer $AISIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "reasoning-prod",
    "messages": [{"role": "user", "content": "Solve this problem."}],
    "reasoning_effort": "medium"
  }'

AISIX sends high to the selected direct model for this request.