feat(ai-proxy): add provider-aware max_tokens override with priority control

[nic-6443]

Description

Add override.request_body.max_tokens to ai-proxy and ai-proxy-multi plugins. Users set a single max_tokens value and APISIX automatically maps it to the correct field name for each provider via rewrite_request_body hooks in provider capabilities.

Config example

{
  "override": {
    "request_body": { "max_tokens": 500 },
    "request_body_force_override": false
  }
}

Provider field mapping

Provider	openai-chat	openai-responses
openai	max_completion_tokens	max_output_tokens
openai-compatible	max_tokens	max_output_tokens
deepseek	max_tokens	—
anthropic	max_tokens	—
gemini	max_completion_tokens	—
azure-openai	max_tokens	—
openrouter	max_tokens	—
aimlapi	max_tokens	—
vertex-ai	max_completion_tokens	—

Priority control

• request_body_force_override: false (default): client request fields take priority, override only fills missing fields
• request_body_force_override: true: override forcefully overwrites client fields

Design

Each provider capability entry has an optional rewrite_request_body(body, override, force) hook function. This is called in build_request() after protocol conversion and prepare_outgoing_request(). The hook directly mutates the request body, making it easy to extend for nested objects or future fields.

[Copilot]

Pull request overview

Adds a new override.request_body configuration to ai-proxy and ai-proxy-multi to allow protocol-specific, deep-merged request body overrides after protocol conversion (and after options), enabling operators to set nested/provider-specific parameters reliably.

Changes:

• Introduces a deep-merge helper and applies per-target-protocol request body patches in the provider request build path.
• Extends ai-proxy schemas to validate override.request_body keys against the registered protocol set (dynamic via ai-protocols.names()).
• Adds a dedicated test suite covering schema validation, deep-merge semantics, precedence, multi-instance behavior, and converter (client→target protocol) behavior; updates EN/ZH docs.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
apisix/plugins/ai-proxy/merge.lua	Adds deep-merge helper used for request body overrides.
apisix/plugins/ai-proxy/schema.lua	Adds override.request_body schema and reuses a shared override_schema.
apisix/plugins/ai-proxy/base.lua	Passes override.request_body into provider build options (extra_opts).
apisix/plugins/ai-providers/base.lua	Applies protocol-keyed deep-merge into outgoing request body after options.
apisix/plugins/ai-protocols/init.lua	Exposes names() to enumerate registered protocol names.
t/plugin/ai-proxy-request-body-override.t	Adds coverage for schema rejection, merge semantics, precedence, converter path, and backward compatibility.
docs/en/latest/plugins/ai-proxy.md	Documents override.request_body for ai-proxy.
docs/en/latest/plugins/ai-proxy-multi.md	Documents instances.override.request_body for ai-proxy-multi.
docs/zh/latest/plugins/ai-proxy.md	Documents override.request_body for ai-proxy (ZH).
docs/zh/latest/plugins/ai-proxy-multi.md	Documents instances.override.request_body for ai-proxy-multi (ZH).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[membphis]

I think this this plugin design is bad, it is not easy to control and understand

      request_body:
        openai-chat:        { max_tokens: 500, temperature: 0.2 }
        openai-responses:   { max_output_tokens: 500 }

The better one:

      request_body: { max_tokens: 500, temperature: 0.2 }

APISIX intelligently sets the corresponding fields based on the different upstream protocols.

We can include the mappings for which fields APISIX has built-in in the documentation to inform users.

(Using OpenAI's field naming conventions is recommended.)

[nic-6443]

CI failures are all unrelated to this PR:

• t/plugin/log-rotate.t, t/plugin/openwhisk.t — log rotation and OpenWhisk tests
• t/admin/plugins-reload.t, t/discovery/nacos2.t — admin reload and Nacos discovery
• linux_apisix_current_luarocks_in_customed_nginx — prometheus stream subsystem (pre-existing)

The t/plugin/[a-k]*.t job (which contains our ai-proxy-request-body-override.t) is still running.