API7 网关 AI Agent Skill：ai-proxy 插件

概览

ai-proxy 插件将 API7 企业版变为 AI 网关。它以 OpenAI 兼容格式将请求代理到模型服务提供方，并处理身份验证、端点路由和响应流式传输。客户端发送标准聊天补全请求；插件会转换请求并转发给已配置的模型服务提供方。

适用场景

• 将聊天补全或嵌入请求代理到任意受支持的 LLM 提供方
• 将 API Key 集中保存在网关侧，而不是分发给客户端
• 为 LLM 调用添加可观测性（Token 用量和延迟）
• 与 ai-prompt-template、ai-prompt-decorator 或内容 审核插件组合，构建完整的 AI 网关流水线
• 直接在服务或路由上应用一致的 ai-proxy 配置

支持的服务提供方

服务提供方	值	默认端点
OpenAI	openai	https://api.openai.com/v1/chat/completions
DeepSeek	deepseek	https://api.deepseek.com/chat/completions
Azure OpenAI	azure-openai	通过 override.endpoint 自定义
Anthropic	anthropic	https://api.anthropic.com/v1/chat/completions
AIMLAPI	aimlapi	https://api.aimlapi.com/v1/chat/completions
OpenRouter	openrouter	https://openrouter.ai/api/v1/chat/completions
Gemini	gemini	https://generativelanguage.googleapis.com/v1beta/openai/chat/completions
Vertex AI	vertex-ai	https://aiplatform.googleapis.com
OpenAI 兼容	openai-compatible	通过 override.endpoint 自定义

插件配置参考

字段	类型	是否必填	默认值	说明
provider	string	是	—	9 个受支持提供方之一
auth	object	是	—	认证配置（见下文）
options	object	否	—	模型和生成参数
options.model	string	否	—	模型名称（提供方相关）
options.temperature	number	否	—	采样温度
options.top_p	number	否	—	核采样
options.max_tokens	integer	否	—	生成的最大 Token 数
options.stream	boolean	否	false	启用 SSE 流式传输
override	object	否	—	覆盖默认端点
override.endpoint	string	否	—	提供方 API 的完整 URL
provider_conf	object	否	—	提供方特定配置（Vertex AI）
provider_conf.project_id	string	否	—	GCP project ID（Vertex AI）
provider_conf.region	string	否	—	GCP 区域（Vertex AI）
logging	object	否	—	日志选项
logging.summaries	boolean	否	false	记录模型、耗时和 Token
logging.payloads	boolean	否	false	记录请求/响应体
timeout	integer	否	30000	请求超时时间（毫秒）
keepalive	boolean	否	true	保持连接
keepalive_timeout	integer	否	60000	Keepalive 超时时间（毫秒）
keepalive_pool	integer	否	30	Keepalive 连接池大小
ssl_verify	boolean	否	true	校验 SSL 证书

按服务提供方配置身份认证

OpenAI / DeepSeek / Anthropic / AIMLAPI / OpenRouter

{
  "auth": {
    "header": {
      "Authorization": "Bearer sk-your-api-key"
    }
  }
}

Azure OpenAI

{
  "auth": {
    "header": {
      "api-key": "your-azure-key"
    }
  },
  "override": {
    "endpoint": "https://YOUR-RESOURCE.openai.azure.com/openai/deployments/gpt-4/chat/completions?api-version=2024-02-15-preview"
  }
}

Vertex AI（GCP 服务账号）

{
  "auth": {
    "gcp": {
      "service_account_json": "{ ... }",
      "max_ttl": 3600,
      "expire_early_secs": 60
    }
  },
  "provider_conf": {
    "project_id": "your-project-id",
    "region": "us-central1"
  }
}

分步操作：路由到 OpenAI

1. 创建启用 ai-proxy 的路由

路由等所有运行时资源都必须使用 --gateway-group 或 -g 指定网关组作用域。

a7 route create -g default -f - <<'EOF'
{
  "id": "openai-chat",
  "uri": "/v1/chat/completions",
  "methods": ["POST"],
  "plugins": {
    "ai-proxy": {
      "provider": "openai",
      "auth": {
        "header": {
          "Authorization": "Bearer sk-your-openai-key"
        }
      },
      "options": {
        "model": "gpt-4",
        "temperature": 0.7,
        "max_tokens": 1024
      }
    }
  }
}
EOF

2. 发送请求

curl http://127.0.0.1:9080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is 1+1?"}
    ]
  }'

使用服务

在 API7 企业版中，可直接在服务或路由上配置 ai-proxy。服务更适合承载可复用的上游和插件配置。

a7 service create -g default -f - <<'EOF'
{
  "id": "standard-ai-proxy",
  "name": "Standard AI Proxy",
  "plugins": {
    "ai-proxy": {
      "provider": "openai",
      "auth": {
        "header": {
          "Authorization": "Bearer sk-global-key"
        }
      },
      "options": {
        "model": "gpt-4"
      }
    }
  }
}
EOF

常见模式

流式响应

{
  "plugins": {
    "ai-proxy": {
      "provider": "openai",
      "auth": {
        "header": {
          "Authorization": "Bearer sk-your-key"
        }
      },
      "options": {
        "model": "gpt-4",
        "stream": true
      }
    }
  }
}

使用多个路由进行模型路由

该插件不会原生按模型路由。请使用不同路由，并通过 vars 匹配请求体字段：

# 将 gpt-4 请求路由到 OpenAI
a7 route create -g default -f - <<'EOF'
{
  "id": "openai-gpt4",
  "uri": "/v1/chat/completions",
  "methods": ["POST"],
  "vars": [["post_arg.model", "==", "gpt-4"]],
  "plugins": {
    "ai-proxy": {
      "provider": "openai",
      "auth": { "header": { "Authorization": "Bearer sk-openai-key" } },
      "options": { "model": "gpt-4" }
    }
  }
}
EOF

访问日志变量

变量	说明
$request_type	traditional_http、ai_chat 或 ai_stream
$llm_time_to_first_token	首个 Token 返回耗时（毫秒）
$llm_model	提供方实际使用的模型
$request_llm_model	客户端请求的模型
$llm_prompt_tokens	提示词 Token 数量
$llm_completion_tokens	补全 Token 数量

配置同步示例

配置同步以网关组为作用域：

a7 config sync -f config.yaml --gateway-group default

version: "1"
routes:
  - id: openai-chat
    uri: /v1/chat/completions
    methods:
      - POST
    plugins:
      ai-proxy:
        provider: openai
        auth:
          header:
            Authorization: Bearer sk-your-openai-key
        options:
          model: gpt-4
          max_tokens: 1024
          temperature: 0.7

故障排查

现象	原因	修复方式
502 Bad Gateway	端点或 provider 值错误	确认 provider 匹配，并检查 override.endpoint
上游返回 401	API Key 无效	检查 auth.header 值
404 Not Found	缺少 --gateway-group	确保所有运行时命令都包含 -g <group>
Azure 404	URL 中缺少 api-version	在 override.endpoint 中包含 ?api-version=YYYY-MM-DD-preview

---

本页面由 api7/a7 仓库中的 a7-plugin-ai-proxy/SKILL.md 生成。你可以在 AI Agent Skills 页面查看所有技能。