版本：3.10.x

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

概览

ai-proxy 插件将 API7 企业版变为 AI 网关。客户端可以使用受支持的协议向 API7 企业版发送请求，无需自行处理模型服务提供方的身份认证和端点选择。插件会检测客户端协议、选择兼容的服务提供方端点、直接转发原生格式或在适配器可用时转换格式，并处理响应流式传输。

适用场景

将 Chat Completions、Responses API、Embeddings、Anthropic Messages 或 Bedrock Converse 请求代理到兼容的模型服务提供方
将 API Key（API 密钥）集中保存在网关侧，而不是分发给客户端
为 LLM 调用添加可观测性（Token 用量和延迟）
与 ai-prompt-template、ai-prompt-decorator 或内容审核插件组合，构建完整的 AI 网关流水线
直接在服务或路由上应用一致的 ai-proxy 配置

协议检测

API7 网关会将请求 URI 作为协议检测依据之一。Anthropic Messages 请求的 URI 必须以 /v1/messages 结尾，Bedrock Converse 请求的 URI 必须以 /converse 结尾。如果没有这些后缀，请求体可能会被识别为其他协议，例如 OpenAI Chat。

带有 input 字段的 OpenAI Responses 请求必须使用以 /v1/responses 结尾的 URI。否则，API7 网关会将请求体识别为 OpenAI Embeddings；嵌入路由应使用以 /v1/embeddings 结尾的 URI。

对于 Bedrock 流式传输，请保持面向客户端的 URI 以 /converse 结尾，并在请求体中设置 stream: true。API7 网关随后会选择上游 /model/{modelId}/converse-stream 端点。

支持的服务提供方

服务提供方	值	端点行为
OpenAI	`openai`	在 `https://api.openai.com` 上自动选择 `/v1/chat/completions`、`/v1/responses` 或 `/v1/embeddings`
DeepSeek	`deepseek`	`https://api.deepseek.com/chat/completions`
Azure OpenAI	`azure-openai`	通过 `override.endpoint` 自定义
Anthropic	`anthropic`	在 `https://api.anthropic.com` 上自动选择 `/v1/chat/completions` 或 `/v1/messages`
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`
Amazon Bedrock	`bedrock`	与区域和模型相关的 Bedrock Runtime 端点；自 API7 企业版 3.9.12 起可用
OpenAI 兼容	`openai-compatible`	通过 `override.endpoint` 自定义

插件配置参考

字段	类型	是否必填	默认值	说明
`provider`	string	是	—	10 个受支持提供方之一
`auth`	object	是	—	身份认证配置（见下文）
`options`	object	否	—	模型和生成参数
`options.model`	string	否	—	模型名称（提供方相关）
`options.temperature`	number	否	—	采样温度
`options.top_p`	number	否	—	核采样
`options.max_tokens`	integer	否	—	生成的最大 Token 数
`options.stream`	boolean	否	—	覆盖传出请求的 `stream` 字段。对于 Bedrock Converse，在 `/converse` 请求中设置 `stream: true` 会选择 `/model/{modelId}/converse-stream`，并返回未经修改、`Content-Type: application/vnd.amazon.eventstream` 的 AWS EventStream 二进制帧，而不是 SSE；客户端必须解析 EventStream 响应。
`override`	object	否	—	服务提供方端点和请求体覆盖设置
`override.endpoint`	string	否	—	服务提供方的协议和主机，或包含路径及查询参数的完整 URL
`provider_conf`	object	否	—	Vertex AI 或 Amazon Bedrock 的服务提供方特定配置
`provider_conf.project_id`	string	否	—	Vertex AI 的 GCP project ID；除非配置了 `override.endpoint`，否则必须与 `region` 一同设置
`provider_conf.region`	string	否	—	Vertex AI 的 GCP 区域；Amazon Bedrock 必需的 AWS 区域
`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 / AIMLAPI / OpenRouter

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

Anthropic

{
  "auth": {
    "header": {
      "x-api-key": "your-anthropic-api-key",
      "anthropic-version": "2023-06-01"
    }
  }
}

原生 Anthropic Messages 请求需要 anthropic-version 请求头。请按上述方式在 auth.header 中配置，或要求客户端发送该请求头。

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"
  }
}

Gemini

{
  "auth": {
    "header": {
      "Authorization": "Bearer your-gemini-key"
    }
  }
}

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"
  }
}

service_account_json 也可以通过 GCP_SERVICE_ACCOUNT 环境变量设置。

Amazon Bedrock

{
  "auth": {
    "aws": {
      "access_key_id": "your-access-key-id",
      "secret_access_key": "your-secret-access-key",
      "session_token": "your-session-token"
    }
  },
  "provider_conf": {
    "region": "us-east-1"
  },
  "options": {
    "model": "your-model-id"
  }
}

使用临时 AWS 凭证时，必须提供会话令牌。

自定义 OpenAI 兼容 API

{
  "auth": {
    "header": {
      "Authorization": "Bearer your-token"
    }
  },
  "override": {
    "endpoint": "https://your-custom-llm.com/v1/chat/completions"
  }
}

分步操作：路由到 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 页面查看所有技能。

概览​

适用场景​

协议检测​

支持的服务提供方​

插件配置参考​

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

OpenAI / DeepSeek / AIMLAPI / OpenRouter​

Anthropic​

Azure OpenAI​

Gemini​

Vertex AI（GCP 服务账户）​

Amazon Bedrock​

自定义 OpenAI 兼容 API​

分步操作：路由到 OpenAI​

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

2. 发送请求​

使用服务​

常见模式​

流式响应​

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

访问日志变量​

配置同步示例​

故障排查​

概览