跳到主要内容
版本：3.10.x

接入任意 OpenAI 兼容大语言模型

API7 AI 网关支持任何遵循 OpenAI 聊天补全格式的大语言模型 API。使用 openai-compatible 服务提供方可以接入自托管模型（vLLM、Ollama、LMStudio）、小众服务提供方（Together AI、Groq、Fireworks）或内部大语言模型服务。

备注

对于已有专用驱动支持的服务提供方（OpenAI、DeepSeek、Anthropic、Azure OpenAI、Gemini、Vertex AI、OpenRouter），请使用对应的服务提供方类型。专用驱动会自动处理服务提供方特定的身份认证和端点构造。

前置条件​

  • 安装 Docker。

  • 安装 cURL，用于发送请求并验证服务。

  • 拥有一个正在运行的 API7 网关实例。

  • 拥有一个接受 OpenAI 兼容 /v1/chat/completions 请求的大语言模型端点。

  • 从控制台获取令牌，并保存到环境变量：

    export API_KEY=your-dashboard-token   # 请替换为你的控制台令牌

  • 将 {gateway_group_id} 替换为网关组 ID。如果正在按照快速入门操作，请使用 default。

  • 如果使用 Admin API 示例，请创建或复用一个服务。如果尚无服务，请按照创建或复用服务操作，然后保存其 ID：

    export SERVICE_ID=your-service-id         # 请替换为你的服务 ID

为自定义服务提供方配置 AI 代理​

创建一个启用 ai-proxy 插件的路由。openai-compatible 服务提供方必须配置 override.endpoint 字段。

curl -k "https://localhost:7443/apisix/admin/routes?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  --data-binary @- <<EOF
  {
    "id": "custom-llm-route",
    "service_id": "$SERVICE_ID",
    "paths": ["/custom-llm"],
    "plugins": {
      "ai-proxy": {
        "provider": "openai-compatible",
        "auth": {
          "header": {
            "Authorization": "Bearer your-api-key"
          }
        },
        "options": {
          "model": "your-model-name"
        },
        "override": {
          "endpoint": "https://your-llm-endpoint.example.com/v1/chat/completions"
        }
      }
    }
  }
EOF

❶ 将服务提供方设置为 openai-compatible。

❷ 附加服务提供方要求的身份认证请求头。

❸ 按服务提供方要求设置模型名称。

❹ 必填。 指定大语言模型服务的完整端点 URL。

示例：接入自托管 vLLM 实例​

vLLM 为自托管模型提供 OpenAI 兼容 API 服务器：

curl -k "https://localhost:7443/apisix/admin/routes?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  --data-binary @- <<EOF
  {
    "id": "vllm-route",
    "service_id": "$SERVICE_ID",
    "paths": ["/vllm"],
    "plugins": {
      "ai-proxy": {
        "provider": "openai-compatible",
        "auth": {
          "header": {
            "Authorization": "Bearer placeholder"
          }
        },
        "options": {
          "model": "meta-llama/Llama-3.1-8B-Instruct"
        },
        "override": {
          "endpoint": "http://vllm-server:8000/v1/chat/completions"
        }
      }
    }
  }
EOF

配置中始终必须包含 auth 字段。如果 vLLM 服务器本身不要求身份认证，使用占位值即可。

示例：接入 Together AI​

Together AI 提供用于运行开源模型的 OpenAI 兼容 API：

curl -k "https://localhost:7443/apisix/admin/routes?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  --data-binary @- <<EOF
  {
    "id": "together-ai-route",
    "service_id": "$SERVICE_ID",
    "paths": ["/together-ai"],
    "plugins": {
      "ai-proxy": {
        "provider": "openai-compatible",
        "auth": {
          "header": {
            "Authorization": "Bearer $TOGETHER_API_KEY"
          }
        },
        "options": {
          "model": "meta-llama/Llama-3.1-70B-Instruct-Turbo"
        },
        "override": {
          "endpoint": "https://api.together.xyz/v1/chat/completions"
        }
      }
    }
  }
EOF

多模型路由​

使用 ai-proxy-multi 在自托管模型和云服务提供方之间路由流量，实现故障转移：

curl -k "https://localhost:7443/apisix/admin/routes?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  --data-binary @- <<EOF
  {
    "id": "hybrid-route",
    "service_id": "$SERVICE_ID",
    "paths": ["/hybrid"],
    "plugins": {
      "ai-proxy-multi": {
        "fallback_strategy": ["http_429", "http_5xx"],
        "instances": [
          {
            "name": "self-hosted",
            "provider": "openai-compatible",
            "auth": { "header": { "Authorization": "Bearer placeholder" } },
            "options": { "model": "meta-llama/Llama-3.1-8B-Instruct" },
            "override": { "endpoint": "http://vllm-server:8000/v1/chat/completions" },
            "weight": 1,
            "priority": 1
          },
          {
            "name": "cloud-fallback",
            "provider": "openai",
            "auth": { "header": { "Authorization": "Bearer $OPENAI_API_KEY" } },
            "options": { "model": "gpt-4o-mini" },
            "weight": 1,
            "priority": 2
          }
        ]
      }
    }
  }
EOF

❶ fallback_strategy 在出现 HTTP 429（限流）或 5xx（服务器错误）时启用自动故障转移。

❷ 备用实例：自托管实例不可用时使用 OpenAI。

更多路由策略请参阅多模型路由和故障转移。

验证配置​

发送聊天补全请求：

curl "http://127.0.0.1:9080/custom-llm" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Hello, how are you?" }
    ]
  }'

无论使用哪个后端服务提供方，你都应收到标准 OpenAI 聊天补全格式的响应。

要启用流式响应，请在请求体中设置 "stream": true。使用 proxy-buffering 插件禁用 NGINX proxy_buffering，避免服务器发送事件（SSE）被缓冲。

后续步骤​

你已经了解如何将任意 OpenAI 兼容大语言模型接入 API7 网关。