Apache APISIX 插件 ai-proxy-multi 配置问题解析与解决方案

问题背景

在使用 Apache APISIX 的 ai-proxy-multi 插件时，用户按照官方文档配置后遇到了两个主要问题：

1. 初始配置报错："property 'instances' is required"
2. 修改配置后出现运行时错误："attempt to concatenate local 'request_host' (a nil value)"

问题分析

配置结构变更

最新版本的 ai-proxy-multi 插件对配置结构进行了调整，不再使用文档中描述的 providers 字段，而是要求使用 instances 字段。这是一个典型的文档滞后于代码更新的情况。

运行时错误原因

当用户将配置修改为使用 instances 后，虽然路由创建成功，但在实际调用时出现了运行时错误。这是因为在配置端点时，直接使用了 endpoint 字段，而新版插件要求使用 override 对象来包装端点配置。

正确配置方案

经过验证，正确的配置结构应如下所示：

{
    "id": "ai-proxy-multi-route",
    "uri": "/chat/completions",
    "methods": ["POST"],
    "plugins": {
        "ai-proxy-multi": {
            "instances": [
                {
                    "name": "openai-compatible",
                    "provider": "openai-compatible",
                    "model": "deepseek/deepseek-chat-v3-0324:free",
                    "weight": 1,
                    "priority": 1,
                    "auth": {
                        "header": {
                            "Authorization": "Bearer xxx"
                        }
                    },
                    "override": {
                        "endpoint": "https://openrouter.ai/api/v1/chat/completions"
                    }
                }
            ],
            "passthrough": false
        }
    },
    "upstream": {
        "type": "roundrobin",
        "scheme": "https",
        "nodes": {
            "openrouter.ai:443": 1
        }
    }
}

关键配置说明

1. instances 数组：取代了原来的 providers 字段，每个实例代表一个AI服务提供者
2. override 对象：用于指定自定义端点，必须将端点URL包装在此对象中
3. provider 字段：指明使用的AI服务提供商类型，如"openai-compatible"
4. auth 配置：用于设置API密钥等认证信息

最佳实践建议

1. 对于生产环境，建议配置多个实例以实现负载均衡和故障转移
2. 合理设置 weight 和 priority 参数以优化流量分配
3. 定期检查插件更新，关注配置变更
4. 在升级插件版本时，注意测试现有配置的兼容性

总结

Apache APISIX 的 ai-proxy-multi 插件为集成多种AI服务提供了便利的解决方案，但在使用时需要注意其配置结构的特殊性。通过正确的实例配置和端点覆盖设置，可以充分发挥该插件在多AI服务代理方面的优势。建议用户在使用前仔细阅读最新版本文档，并在测试环境充分验证配置。