AISIX AI Gateway

---

AISIX OSS 是围绕 Rust 原生 AISIX 网关构建的开源产品。该网关在所有大模型提供商前提供一个兼容 OpenAI 的 API——包括 OpenAI、Anthropic、Google Gemini、AWS Bedrock、Azure OpenAI、DeepSeek 以及任何兼容 OpenAI 的端点。它为平台团队提供一个统一入口，用于路由、治理、保护和观测大模型流量，并支持一流的 SSE 流式传输，且网关开销低。

它以单个静态二进制文件运行——冷启动耗时短、配置读取无锁，并可热加载配置而无需重启：在一个 resources.yaml 中声明资源，通过 SIGHUP 重新加载；或者将网关指向 etcd，以构建多副本集群。在你的基础设施中运行网关，或将其连接到 AISIX Enterprise 或 AISIX Cloud，以便通过团队治理、预算、审计和仪表板进行集中管理。

**AISIX OSS（此仓库）**是开源产品。它通过声明式配置或 etcd 运行，无需控制平面。同一个网关二进制文件也作为商业产品中的数据平面：客户通过 AISIX Enterprise 托管控制平面，而 API7 则通过 AISIX Cloud 托管控制平面。在这三种产品中，网关都运行在你的环境中，并直接调用提供商；实时 AI 流量不会经过任何一个控制平面。代理 API 在所有产品中完全一致。 咨询 AISIX Enterprise 或 AISIX Cloud →

⚡ 快速入门

一个容器。无需控制平面、数据库或配置存储——网关从一个声明式 resources.yaml 中读取所有动态资源。

# config.yaml
resources_file: /etc/aisix/resources.yaml
proxy:
  addr: "0.0.0.0:3000"
admin:
  enabled: false          # a declarative gateway needs no admin listener
observability:
  metrics:
    prometheus:
      enabled: true
      addr: "0.0.0.0:9090"

# resources.yaml
_format_version: "1"

provider_keys:
  - display_name: openai-main
    provider: openai
    api_key: ${OPENAI_API_KEY}        # interpolated from the environment

models:
  - display_name: my-model
    provider: openai
    model_name: gpt-4o-mini
    provider_key: openai-main

api_keys:
  - display_name: local-dev
    key_env: CALLER_API_KEY           # hashed at load; the plaintext is never stored
    allowed_models: ["my-model"]

export OPENAI_API_KEY="YOUR_PROVIDER_KEY"
export CALLER_API_KEY="YOUR_CALLER_KEY"

docker run -d --name aisix \
  -v "$(pwd)/config.yaml:/etc/aisix/config.yaml:ro" \
  -v "$(pwd)/resources.yaml:/etc/aisix/resources.yaml:ro" \
  -e OPENAI_API_KEY -e CALLER_API_KEY \
  -p 3000:3000 -p 127.0.0.1:9090:9090 \
  ghcr.io/api7/aisix:latest        # proxy → :3000, metrics + status → :9090
#                                  ^ the metrics/status listener is unauthenticated;
#                                    keep it on loopback or a private network

然后像调用 OpenAI 一样调用网关：

curl http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer $CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"my-model","messages":[{"role":"user","content":"hello"}]}'

编辑 resources.yaml 并发送 SIGHUP（docker kill -s HUP aisix），即可应用更改，无需重启——无效文件会被整体拒绝，网关将继续提供最后一份有效配置。启动前，可使用 aisix validate --resources resources.yaml 检查文件。

完整操作指南： 网关快速入门 · 字段说明：资源文件参考。 对于多副本集群，请改为将网关指向 etcd——resources_file 和 etcd 不能同时使用。

✨ 为什么选择 AISIX

• 一个 API，适配所有模型。 可使用 OpenAI 或 Anthropic 的线路格式发送请求；网关会将请求转换为各模型所指向的提供商所需的格式。将 OpenAI 或 Claude SDK 指向同一个 base_url，即可切换模型而无需更改代码。
• 真正的 Rust 网关。 单个静态二进制文件，冷启动快，热路径上的配置读取无需锁，并支持原生流式传输。
• 开源，永久免费。 采用 Apache-2.0 许可证，可在你的基础设施中运行。需要通过控制平面和仪表板进行集中管理时，可选择 AISIX Enterprise 或 AISIX Cloud。
• 内置生产级控制功能。 路由与故障转移、速率限制、护栏、缓存和可观测性均开箱即用。（预算和支出上限是 AISIX Enterprise 和 AISIX Cloud 的功能——网关负责执行控制平面的决策。）

🧩 功能 — 现已提供

由 183 个端到端场景文件（496 个用例）覆盖，这些文件会针对实际运行的网关进程执行。

• 兼容 OpenAI 的代理（:3000）——chat/completions、completions、responses、 embeddings、rerank、images/{generations,edits}、audio/{speech,transcriptions,translations}、 videos（提交 → 轮询 → 获取）、files、batches、fine_tuning/jobs、realtime、 GET /v1/models，以及根级别的 /passthrough/:provider/* 逃生通道。支持原生 SSE 流式传输、 工具/函数调用、JSON 模式、视觉/多模态输入和推理内容。
• Anthropic Messages API——将 POST /v1/messages 作为一等路由，适用于任何已配置的上游： 当模型指向非 Anthropic 提供商时，请求和响应（包括流式传输）会双向转换。
• 路由与故障转移——虚拟/路由模型支持六种策略：round_robin （平滑加权轮询）、consistent_hash（根据标头 / Cookie / API 密钥 / 客户端 IP 保持会话亲和性）、 failover，以及基于指标的 least_cost、 least_latency 和 least_busy。每个目标可设置 priority 层级（活动/备用池）、 重试预算、冷却时间、按标签条件匹配的目标，以及每次尝试的超时时间。
• 集成模型——将单个请求并发发送给一组模型，再由评判模型综合生成一个答案，并可设置成功响应的最低数量阈值。
• 语义路由——根据每个请求的含义进行分发的虚拟模型：它会对提示词进行嵌入， 根据每条路由的示例语句进行评分，并将请求路由到最匹配的目标（或默认目标）。请参阅 语义路由文档。
• 速率限制与并发控制——RPS/RPM/RPH/RPD + TPM/TPD + 并发上限， 并在调用方密钥、模型和策略范围（api_key / model / team / member / team_member）之间以 AND 方式组合。默认情况下，计数器按进程统计；使用 Redis 后端时，可在多个副本间共享。
• 护栏——对输入和输出执行内容策略，可在进程内执行，也可通过提供商执行：关键词/正则表达式、内置 PII 检测与脱敏、Presidio、Lakera、OpenAI Moderation、AWS Bedrock Guardrails、Azure AI Content Safety（Prompt Shield + 文本 审核），以及两项 Alibaba Cloud 服务。拦截时返回 422 content_filter； 监控模式会记录本应发生的操作，但不会拦截。
• 缓存——精确匹配的响应缓存，支持按策略设置 TTL 和模型/密钥范围匹配器； 支持内存和 Redis 后端；每次命中都会记录节省的成本遥测数据。此外，可为直接 Anthropic 模型单独启用自动提示词缓存，以注入缓存断点，让 调用方无需修改请求即可享受提供商侧的提示词折扣。
• MCP 网关——在 /mcp 前接入已注册的上游 MCP 服务，由网关持有凭据，支持按服务划分工具命名空间，并控制每个调用方的访问权限。无需下游会话，即可提供从 2025-03-26 到无状态 2026-07-28 的所有 Streamable HTTP 版本。上游默认使用 initialize，或使用 protocol_version: "2026-07-28" 调用 server/discover。CI 会运行官方 MCP 套件中适用的纯工具协议场景。还可根据 OpenAPI 描述将 REST API 作为 MCP 工具提供。
• A2A Agent 网关——在 /a2a/:agent 前接入 A2A（Agent-to-Agent）Agent，通过 JSON-RPC 2.0 提供各 Agent 的卡片，并将其中的 URL 重写为指向网关。
• 入站身份验证——调用方 API 密钥（SHA-256 哈希、模型允许列表、过期时间、轮换），或针对已注册提供商（Entra ID、Okta、Google Workspace 或任意 OIDC 颁发者）验证的 OIDC/JWT bearer 令牌，并缓存 JWKS。
• 可观测性——Prometheus /metrics、按请求记录的结构化访问日志、使用情况事件、OTLP/GenAI span 导出（Langfuse、Honeycomb、Grafana Cloud 或任意 OTLP 接收器），以及专用的 Datadog 和 Aliyun SLS 日志导出器与对象存储（S3/GCS/Azure Blob）遥测。
• 声明式配置——单个 resources.yaml 包含全部十类资源集合 （提供商密钥、模型、调用方密钥、护栏、MCP 服务、A2A Agent、缓存策略、可观测性导出器、速率限制策略、OIDC 提供商），并根据网关运行时使用的同一组 JSON Schema 进行验证。aisix validate 可离线检查文件；SIGHUP 可原子化重新加载配置。
• 运维端点——代理监听器上提供 /livez 和 /readyz；专用指标监听器（:9090）上提供 /status/config、 /status/ready、/status/models 和 Prometheus /metrics。管理监听器（:3001）还提供只读 资源接口、带 Scalar UI 的 OpenAPI 3，以及一个演练场。资源通过声明式方式管理——使用 resources_file（通过 SIGHUP 重新加载）或直接写入 etcd——而不是通过管理监听器；此前的写入端点已被移除。

🔌 支持的提供商

AISIX 通过 五种原生适配器系列进行调度——它们是不同的线路协议桥接器，而非统一重命名。无论上游协议是什么，面向客户端的 API 始终采用 OpenAI 格式。

适配器系列	接入对象	线路格式 · 身份验证
openai	OpenAI 及任何兼容 OpenAI 的供应商——DeepSeek、Groq、Mistral、Together、Fireworks、Perplexity、vLLM、Ollama，或可自托管的 OpenAI 兼容端点	OpenAI 聊天补全 · Bearer
anthropic	Anthropic Claude	Anthropic Messages · x-api-key
bedrock	AWS Bedrock——Anthropic、Meta Llama、Mistral、Cohere、Amazon Titan/Nova、AI21	Bedrock Converse + /invoke · SigV4
vertex	Google Vertex AI（Gemini）	Vertex :generateContent · OAuth2
azure-openai	Azure OpenAI	Azure 部署 · api-key / Entra ID

此外，还针对供应商特有问题进行了专门处理（例如 DeepSeek 推理内容），并支持专用的重排序 / 嵌入供应商（Cohere、Jina）。详情请参阅适配器协议系列。

☁️ 选择 AISIX 产品

无论以何种形式部署，网关都在你的环境中运行；网关二进制文件和代理 API 始终相同。AISIX Enterprise 提供由客户托管的商业控制平面。AISIX Cloud 提供由 API7 托管的商业控制平面。

概览 — 一目了然地查看流量、延迟、错误率和支出 模型 — 为每个上游设置一个别名：OpenAI、Anthropic、Bedrock、DeepSeek…… 护栏 — 输入前与输出后的策略，违规时拦截

试验场 — 测试任意模型，实时计量令牌和成本 可观测性 — 将跟踪和日志分发到 OTLP、Datadog 和对象存储 预算 — 硬性停止支出上限，并支持仅警告级别

AISIX Enterprise 和 AISIX Cloud 仪表板——在所有网关中查看概览指标、多提供商模型、护栏、预算和可观测性导出器。

▶ 试用实时仪表板演示 — aisix-demo.api7.ai

| | AISIX OSS（本仓库） | AISIX Enterprise | [AISIX Cloud](https://api7.ai/ai-gateway?utm_source=github&utm_medium=readme&utm_campaign=cloud) | |---|---|---|---| | 许可证 | Apache-2.0 | 商业版 | 商业版 | | 控制平面 | 无 | 客户托管 | API7 托管 | | 配置 | 声明式 `resources.yaml`，或使用 etcd 集群 | 控制面板 + AISIX Cloud Admin API | 控制面板 + AISIX Cloud Admin API | | 多租户 | 单实例 / 命名空间 | 按组织划分的环境、团队和成员 | 按组织划分的环境、团队和成员 | | 提供商密钥 | `resources.yaml` 中的 `${VAR}` 引用；etcd 中的明文凭据 | 静态加密；由操作员触发原地轮换 | 静态加密；由操作员触发原地轮换 | | 预算 | —（仅速率和令牌限制） | 按密钥、提供商、环境、组织和团队设置 | 按密钥、提供商、环境、组织和团队设置 | | RBAC 和审计 | 本地管理密钥；无组织层 | 组织角色、邀请和审计历史 | 组织角色、邀请和审计历史 | | 运维 | 由你运维网关 | 由你运维控制平面和网关 | API7 运维控制平面；你运维网关 |

→ 想要集中式治理、预算和控制面板？ 请**联系 API7，了解 AISIX Enterprise 或 AISIX Cloud，或预约演示**。

🏗️ 架构

单个 Cargo 工作区；aisix-server crate 会构建一个名为 aisix 的二进制文件，将各个 crate 连接起来。

crates/
├── aisix-core           Config, snapshot, resource model, resources.yaml source, errors
├── aisix-etcd           Config provider + watch supervisor
├── aisix-gateway        Hub & bridge, SSE parser, provider trait
├── aisix-proxy          /v1/*, /mcp, /a2a handlers, routing, middleware
├── aisix-admin          Read-only resource surface + playground + OpenAPI
├── aisix-provider-*     openai · anthropic · azure-openai · bedrock · vertex
├── aisix-mcp            MCP gateway — server registry, tool ACL, transports
├── aisix-a2a            A2A agent gateway — agent cards, JSON-RPC bridge
├── aisix-ratelimit      fixed-window + token accounting + concurrency (local | redis)
├── aisix-cache          memory + redis backends
├── aisix-redis          shared Redis connection for cache + rate limits
├── aisix-guardrails     pre/post content-policy hooks
├── aisix-obs            tracing, metrics, access log, exporters
└── aisix-server         the `aisix` binary — bootstrap + CLI

🗺️ 路线图

请查看路线图中的重点内容；进度会实时更新在 issues中：

• 语义（嵌入相似度）响应缓存
• 更多可观测性接收端——Langsmith、Helicone、Slack 告警
• 作为网关资源管理的提示词模板
• 将 Llama-Guard 用作护栏提供商

自上次编写此列表以来已发布：MCP 网关、A2A Agent 网关、OIDC/JWT 入站身份验证、基于 Redis 的分布式速率限制，以及 Lakera、Presidio、PII 和 OpenAI Moderation 护栏——请参阅上方的功能。

🛠️ 开发

前置条件：rust-toolchain.toml 中指定的 Rust 工具链。只有运行涉及 etcd、Redis 或提供商模拟器的测试时才需要 Docker。

cargo check --workspace
cargo fmt --check
cargo clippy --workspace -- -D warnings
cargo test --workspace

# Coverage (matches the CI gate)
cargo llvm-cov --workspace --lcov --output-path lcov.info

# Run locally against a resources.yaml (no etcd needed). Copy the Quickstart's two files
# and change resources_file to the local path, e.g. resources_file: ./resources.yaml
cargo run -p aisix-server --bin aisix -- --config config.local.yaml

# Check a resources file without starting a listener
cargo run -p aisix-server --bin aisix -- validate --resources resources.yaml

💬 社区

• Discord — discord.gg/dUmRZ7Rvf
• 问题与讨论 — github.com/api7/aisix/issues
• 贡献 — CONTRIBUTING.md
• 网站 — api7.ai/ai-gateway

如果 AISIX 对你有帮助，点个 ⭐ 能让其他工程师发现它。

📄 许可证

Apache 2.0。