feat(ai-proxy): add protocol-aware request body override

Adds override.request_body to ai-proxy and ai-proxy-multi, letting
operators set arbitrary nested fields on the outgoing request body,
keyed by target protocol.

The existing options field can only overwrite top-level fields and
is protocol-agnostic, so it cannot express protocol-specific params
like max_tokens vs max_output_tokens vs generationConfig.maxOutputTokens.

request_body is keyed by target protocol (openai-chat, openai-responses,
openai-embeddings, anthropic-messages) because converters only do
structural format conversion, not per-parameter semantic normalization.
The override is applied after converter + options, deep-merged into
the body: objects recursive, scalars/arrays replace wholesale.

Examples:

    override:
      request_body:
        openai-chat:        { max_tokens: 500 }
        openai-responses:   { max_output_tokens: 500 }
        anthropic-messages: { max_tokens: 500, stop_sequences: ['Human:'] }

Author: nic-6443

apisix/plugins/ai-protocols/init.lua

@@ -22,6 +22,7 @@
 
 local converters = require("apisix.plugins.ai-protocols.converters")
 local ipairs = ipairs
+local pairs = pairs
 
 local _M = {}
 
@@ -65,6 +66,17 @@ function _M.get(name)
 end
 
 
+--- Get the list of all registered protocol names.
+-- @return table Array of protocol names
+function _M.names()
+    local names = {}
+    for name in pairs(registered) do
+        names[#names + 1] = name
+    end
+    return names
+end
+
+
 --- Find a converter that can bridge from client_protocol to a protocol
 -- supported by the driver. Delegates to the converters registry.
 -- @param client_protocol string The detected client protocol

apisix/plugins/ai-providers/base.lua

@@ -36,6 +36,7 @@ local transport_http = require("apisix.plugins.ai-transport.http")
 local transport_auth = require("apisix.plugins.ai-transport.auth")
 local log_sanitize = require("apisix.utils.log-sanitize")
 local protocols = require("apisix.plugins.ai-protocols")
+local deep_merge = require("apisix.plugins.ai-proxy.merge").deep_merge
 local ngx = ngx
 local ngx_now = ngx.now
 
@@ -172,7 +173,7 @@ function _M.build_request(self, ctx, conf, request_body, opts)
                           or opts.target_host or self.host,
     }
 
-    -- Inject model options
+    -- Inject model options (flat overwrite)
     if opts.model_options then
         for opt, val in pairs(opts.model_options) do
             if request_body[opt] ~= nil then
@@ -181,6 +182,16 @@ function _M.build_request(self, ctx, conf, request_body, opts)
             request_body[opt] = val
         end
     end
+
+    -- Inject per-target-protocol request body override (deep merge)
+    if opts.request_body_override_map then
+        local patch = opts.request_body_override_map[ctx.ai_target_protocol]
+        if patch then
+            core.log.info("applying request_body override for target protocol '",
+                          ctx.ai_target_protocol, "'")
+            deep_merge(request_body, patch)
+        end
+    end
     params.body = request_body
 
     if self.remove_model then

apisix/plugins/ai-proxy/base.lua

@@ -125,8 +125,9 @@ function _M.before_proxy(conf, ctx, on_error)
             model_options = ai_instance.options,
             conf = ai_instance.provider_conf or {},
             auth = ai_instance.auth,
+            request_body_override_map =
+                core.table.try_read_attr(ai_instance, "override", "request_body"),
         }
-
         -- Step 1: Route client protocol to driver capability
         local client_protocol = ctx.ai_client_protocol
         local client_proto = protocols.get(client_protocol)

apisix/plugins/ai-proxy/merge.lua

@@ -0,0 +1,66 @@
+--
+-- Licensed to the Apache Software Foundation (ASF) under one or more
+-- contributor license agreements.  See the NOTICE file distributed with
+-- this work for additional information regarding copyright ownership.
+-- The ASF licenses this file to You under the Apache License, Version 2.0
+-- (the "License"); you may not use this file except in compliance with
+-- the License.  You may obtain a copy of the License at
+--
+--     http://www.apache.org/licenses/LICENSE-2.0
+--
+-- Unless required by applicable law or agreed to in writing, software
+-- distributed under the License is distributed on an "AS IS" BASIS,
+-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+-- See the License for the specific language governing permissions and
+-- limitations under the License.
+--
+
+--- Deep-merge helper for ai-proxy request body overrides.
+-- Semantics:
+--   * Both sides are plain objects (string-keyed tables) -> recursive merge.
+--   * Otherwise (scalar, array, type mismatch, cjson.empty_array/empty_object)
+--     -> patch value replaces target value wholesale.
+-- This matches RFC 7396 JSON Merge Patch minus null-deletion.
+
+local core = require("apisix.core")
+local pairs = pairs
+local next = next
+local type = type
+local getmetatable = getmetatable
+
+local _M = {}
+
+
+-- Returns true when tbl is a plain object (string keys only) that we should
+-- recurse into. Empty tables, arrays, and cjson sentinels are treated as
+-- "replace wholesale" to avoid ambiguity.
+local function is_plain_object(tbl)
+    if type(tbl) ~= "table" then
+        return false
+    end
+    local mt = getmetatable(tbl)
+    if mt == core.json.array_mt then
+        return false
+    end
+    local k = next(tbl)
+    if k == nil then
+        -- Empty table: ambiguous; treat as "not an object" so patch replaces it.
+        return false
+    end
+    return type(k) == "string"
+end
+
+
+local function deep_merge(target, patch)
+    if not is_plain_object(target) or not is_plain_object(patch) then
+        return patch
+    end
+    for k, v in pairs(patch) do
+        target[k] = deep_merge(target[k], v)
+    end
+    return target
+end
+_M.deep_merge = deep_merge
+
+
+return _M

apisix/plugins/ai-proxy/schema.lua

@@ -16,6 +16,8 @@
 --
 local schema_def = require("apisix.schema_def")
 local ai_providers_schema = require("apisix.plugins.ai-providers.schema")
+local protocols = require("apisix.plugins.ai-protocols")
+local pairs = pairs
 
 local _M = {}
 
@@ -72,6 +74,40 @@ local model_options_schema = {
     additionalProperties = true,
 }
 
+-- Build per-target-protocol request body override schema.
+-- Each registered protocol gets an optional "any-shape object" entry.
+-- Values are applied via deep-merge after the model_options flat overwrite.
+local request_body_override_properties = {}
+for _, proto_name in pairs(protocols.names()) do
+    request_body_override_properties[proto_name] = {
+        type = "object",
+        description = "Deep-merged into the outgoing request body when the "
+            .. "target protocol is '" .. proto_name .. "'.",
+        additionalProperties = true,
+    }
+end
+
+local request_body_override_schema = {
+    type = "object",
+    description = "Per target-protocol request body overrides. Keys are target "
+        .. "protocol names; values are partial request bodies that are "
+        .. "deep-merged into the outgoing body (objects merged recursively, "
+        .. "arrays and scalars replaced wholesale).",
+    properties = request_body_override_properties,
+    additionalProperties = false,
+}
+
+local override_schema = {
+    type = "object",
+    properties = {
+        endpoint = {
+            type = "string",
+            description = "To be specified to override the endpoint of the AI Instance",
+        },
+        request_body = request_body_override_schema,
+    },
+}
+
 local provider_vertex_ai_schema = {
     type = "object",
     properties = {
@@ -115,15 +151,7 @@ local ai_instance_schema = {
             },
             auth = auth_schema,
             options = model_options_schema,
-            override = {
-                type = "object",
-                properties = {
-                    endpoint = {
-                        type = "string",
-                        description = "To be specified to override the endpoint of the AI Instance",
-                    },
-                },
-            },
+            override = override_schema,
             checks = {
                 type = "object",
                 properties = {
@@ -192,15 +220,7 @@ _M.ai_proxy_schema = {
         },
         keepalive_pool = {type = "integer", minimum = 1, default = 30},
         ssl_verify = {type = "boolean", default = true },
-        override = {
-            type = "object",
-            properties = {
-                endpoint = {
-                    type = "string",
-                    description = "To be specified to override the endpoint of the AI Instance",
-                },
-            },
-        },
+        override = override_schema,
     },
     required = {"provider", "auth"},
     encrypt_fields = {"auth.header", "auth.query", "auth.gcp.service_account_json"},

docs/en/latest/plugins/ai-proxy-multi.md

@@ -81,6 +81,7 @@ In addition, the Plugin also supports logging LLM request information in the acc
 | logging.payloads                    | boolean        | False    | false                           |              | If true, log request and response payload. |
 | instances.override                    | object         | False    |                                   |              | Override setting. |
 | instances.override.endpoint           | string         | False    |                                   |              | LLM provider endpoint to replace the default endpoint with. If not configured, the Plugin uses the default OpenAI endpoint `https://api.openai.com/v1/chat/completions`. |
+| instances.override.request_body       | object         | False    |                                   |              | Per target-protocol request body overrides. Keys are target protocol names (`openai-chat`, `openai-responses`, `openai-embeddings`, `anthropic-messages`); each value is a partial request body that is **deep-merged** into the outgoing body sent to the provider after protocol conversion. Use this when the override field name is protocol-specific (for example `max_tokens` vs `max_output_tokens`). Objects merge recursively; scalars and arrays replace wholesale. Applied after `instances.options`, so a field set in both places takes the value from `request_body`. |
 | instances.checks                              | object         | False    |                                   |              | Health check configurations. Note that at the moment, OpenAI, DeepSeek, and AIMLAPI do not provide an official health check endpoint. Other LLM services that you can configure under `openai-compatible` provider may have available health check endpoints. |
 | instances.checks.active                       | object         | True     |                                   |              | Active health check configurations. |
 | instances.checks.active.type                  | string         | False    | http                            | [http, https, tcp] | Type of health check connection. |

docs/en/latest/plugins/ai-proxy.md

@@ -66,6 +66,7 @@ In addition, the Plugin also supports logging LLM request information in the acc
 | options.model   | string  | False    |         |                                          | Name of the LLM model, such as `gpt-4` or `gpt-3.5`. Refer to the LLM provider's API documentation for available models. |
 | override        | object  | False    |         |                                          | Override setting. |
 | override.endpoint | string | False    |         |                                          | Custom LLM provider endpoint, required when `provider` is `openai-compatible`. |
+| override.request_body | object | False  |         |                                          | Per target-protocol request body overrides. Keys are target protocol names (`openai-chat`, `openai-responses`, `openai-embeddings`, `anthropic-messages`); each value is a partial request body that is **deep-merged** into the outgoing body sent to the provider after protocol conversion. Use this when the override field name is protocol-specific (for example `max_tokens` vs `max_output_tokens`). Objects merge recursively; scalars and arrays replace wholesale. Applied after `options`, so a field set in both places takes the value from `request_body`. |
 | logging        | object  | False    |         |                                          | Logging configurations. Does not affect `error.log`. |
 | logging.summaries | boolean | False | false |                                          | If true, logs request LLM model, duration, request, and response tokens. |
 | logging.payloads  | boolean | False | false |                                          | If true, logs request and response payload. |

docs/zh/latest/plugins/ai-proxy-multi.md

@@ -78,6 +78,7 @@ import TabItem from '@theme/TabItem';
 | instances.options.model             | string         | 否    |                                   |              | LLM 模型的名称，如 `gpt-4` 或 `gpt-3.5`。有关更多可用模型，请参阅您的 LLM 提供商的 API 文档。 |
 | instances.override                  | object         | 否    |                                   |              | 覆盖设置。 |
 | instances.override.endpoint         | string         | 否    |                                   |              | 用于替换默认端点的 LLM 提供商端点。如果未配置，插件使用默认的 OpenAI 端点 `https://api.openai.com/v1/chat/completions`。 |
+| instances.override.request_body     | object         | 否    |                                   |              | 按目标协议（`openai-chat`、`openai-responses`、`openai-embeddings`、`anthropic-messages`）配置的请求体覆盖。每个 key 对应一份部分请求体，会在协议转换后以**深度合并**的方式注入到发给上游的请求体中。适用于参数名因协议而异的场景（例如 `max_tokens` vs `max_output_tokens`）。对象递归合并，数组与标量整体替换。在 `instances.options` 之后应用，同名字段以 `request_body` 为准。 |
 | logging                             | object         | 否    |                                   |              | 日志配置。不影响 `error.log`。 |
 | logging.summaries                   | boolean        | 否    | false                           |              | 如果为 true，记录请求 LLM 模型、持续时间、请求和响应令牌。 |
 | logging.payloads                    | boolean        | 否    | false                           |              | 如果为 true，记录请求和响应负载。 |

docs/zh/latest/plugins/ai-proxy.md

@@ -66,6 +66,7 @@ description: ai-proxy 插件通过将插件配置转换为所需的请求格式
 | options.model   | string  | 否    |         |                                          | LLM 模型的名称，如 `gpt-4` 或 `gpt-3.5`。请参阅 LLM 提供商的 API 文档以了解可用模型。 |
 | override        | object  | 否    |         |                                          | 覆盖设置。 |
 | override.endpoint | string | 否    |         |                                          | 自定义 LLM 提供商端点，当 `provider` 为 `openai-compatible` 时必需。 |
+| override.request_body | object | 否  |         |                                          | 按目标协议（`openai-chat`、`openai-responses`、`openai-embeddings`、`anthropic-messages`）配置的请求体覆盖。每个 key 对应一份部分请求体，会在协议转换后以**深度合并**的方式注入到发给上游的请求体中。适用于参数名因协议而异的场景（例如 `max_tokens` vs `max_output_tokens`）。对象递归合并，数组与标量整体替换。在 `options` 之后应用，同名字段以 `request_body` 为准。 |
 | logging        | object  | 否    |         |                                          | 日志配置。不影响 `error.log`。 |
 | logging.summaries | boolean | 否 | false |                                          | 如果为 true，记录请求 LLM 模型、持续时间、请求和响应令牌。 |
 | logging.payloads  | boolean | 否 | false |                                          | 如果为 true，记录请求和响应负载。 |