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

问题背景

在使用 Apache APISIX 的 ai-proxy-multi 插件时，用户按照官方文档配置后遇到了两个主要问题：首先是配置格式不匹配导致的路由创建失败，其次是插件运行时的连接错误。这些问题源于文档与实际代码实现之间的差异。

配置格式差异分析

官方文档示例中使用了 providers 字段来定义AI服务提供者，但实际代码实现中要求的是 instances 字段。这是一个典型的文档与实现不同步的问题。

正确的配置结构应该是：

{
  "instances": [
    {
      "name": "服务实例名称",
      "provider": "服务提供商类型",
      "model": "使用的模型",
      "auth": {
        "header": {
          "Authorization": "Bearer API_KEY"
        }
      },
      "override": {
        "endpoint": "服务端点URL"
      }
    }
  ]
}

连接错误问题解析

当用户修改配置后虽然路由创建成功，但在实际调用时出现了 request_host 为 nil 的错误。这个问题的根源在于端点URL的配置方式不正确。

关键点在于：

1. 端点URL必须通过 override.endpoint 而非直接使用 endpoint 字段配置
2. 端点URL需要包含完整的协议和主机信息

完整解决方案

基于以上分析，正确的配置示例如下：

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

技术原理深入

ai-proxy-multi 插件的工作机制是：

1. 接收客户端请求
2. 根据配置的实例列表选择合适的服务提供者
3. 将请求转发到指定的AI服务端点
4. 处理响应并返回给客户端

当配置不正确时，插件无法正确构建转发请求所需的连接信息，导致 request_host 为 nil 的错误。通过 override.endpoint 正确配置后，插件能够解析出完整的主机信息，建立正确的连接。

最佳实践建议

1. 始终使用最新版本的插件文档
2. 在配置新插件时，先参考插件的schema定义
3. 对于AI服务代理类插件，确保：
   • 认证信息正确
   • 端点URL完整
   • 模型名称与服务提供商匹配
4. 在测试阶段启用详细日志，便于排查问题

总结

本文详细分析了 Apache APISIX 的 ai-proxy-multi 插件配置过程中的常见问题，提供了正确的配置方法和深入的技术原理说明。通过理解插件的工作机制和正确使用配置参数，开发者可以顺利实现AI服务的代理功能。