开源 AISIX 网关快速入门

使用本快速入门，在单个 Docker 容器中运行开源 AISIX 网关，并通过该网关发送第一个 AI 请求。你将在一个 resources.yaml 文件中声明必需的模型服务提供方密钥、模型和调用方 API Key，启动网关，再通过兼容 OpenAI 的 API 验证请求。

此设置不需要控制台、控制面或独立配置存储，是在本地评估网关的最快方式。示例使用 OpenAI 作为上游服务提供方。客户端使用调用方 API Key 向 AISIX 认证，网关则使用单独的模型服务提供方密钥向 OpenAI 认证。

请求遵循以下路径：

当客户端请求 AISIX 模型名称 gpt-4o-mini 时，网关会使用调用方 API Key 认证请求，并使用已保存的模型服务提供方密钥调用 OpenAI。上游 OpenAI Key 绝不会暴露给客户端。

前提条件

安装 Docker，用于运行 AISIX AI 网关容器。
安装 cURL，用于向网关发送请求。
准备一个可以访问 gpt-4o-mini 且有可用配额的 OpenAI API Key。

创建资源文件

首先创建工作目录：

mkdir aisix-quickstart
cd aisix-quickstart

模型服务提供方密钥、模型和调用方 API Key 统一声明在一个 resources.yaml 文件中。创建该文件：

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: openai-main
    provider: openai
    adapter: openai
    api_key: ${OPENAI_API_KEY}
    api_base: https://api.openai.com/v1

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

api_keys:
  - display_name: quickstart-caller
    key_env: CALLER_API_KEY
    allowed_models:
      - gpt-4o-mini

❶ _format_version: "1" 为必填项，且必须是带引号的字符串。它会固定文件格式，避免未来版本悄然错误解读此文件。

❷ 加载文件时会从网关环境中解析 ${OPENAI_API_KEY}，因此文件本身不会包含上游凭证。引用的变量未设置或为空会导致加载失败。

❸ provider_key 通过 display_name 引用上方的模型服务提供方密钥。引用未定义名称会导致加载失败，因此拼写错误不会变成无提示的运行时故障。

❹ key_env 指定保存明文调用方 API Key 的环境变量。网关会在加载时计算该值的哈希，并且只存储哈希。变量名不要以 AISIX_ 开头，因为该前缀保留给启动配置覆盖项。如需提供预先计算的 SHA-256 哈希，请使用 key_hash 代替 key_env。

网关会根据资源名称生成稳定 ID，因此每个名称在其集合中必须唯一。

创建启动配置

创建 config.yaml 文件，使网关指向资源文件：

config.yaml
resources_file: /etc/aisix/resources.yaml

proxy:
  addr: "0.0.0.0:3000"

admin:
  enabled: false

❶ resources_file 将该文件选作网关的资源来源。使用此设置时，网关不使用外部配置存储，因此省略 etcd 部分。两者互斥。

❷ proxy.addr 监听所有容器接口上的 3000 端口。下方 Docker 命令会把该端口发布到主机的 http://127.0.0.1:3000。

其他启动选项请参阅启动配置参考。

启动 AISIX AI 网关

导出 resources.yaml 引用的两个值和本地网关源站地址：

# 替换为你的 OpenAI API Key。
export OPENAI_API_KEY="YOUR_PROVIDER_API_KEY"

# 为客户端请求选择调用方 API Key。
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

# 本快速入门将网关发布在此源站地址。
export AISIX_PROXY="http://127.0.0.1:3000"

启动网关前，请在短生命周期容器中验证 resources.yaml。这样可以在不启动监听器的情况下发现插值、引用和 schema 错误：

docker run --rm \
  -v "$(pwd):/etc/aisix:ro" \
  -e OPENAI_API_KEY \
  -e CALLER_API_KEY \
  --entrypoint /usr/local/bin/aisix \
  ghcr.io/api7/aisix:latest \
  validate --resources /etc/aisix/resources.yaml

该命令应报告文件已加载三个资源。然后启动网关，并挂载整个工作目录，使后续编辑仍可在正在运行的容器中看到：

docker run -d --name aisix-quickstart \
  -v "$(pwd):/etc/aisix:ro" \
  -e OPENAI_API_KEY \
  -e CALLER_API_KEY \
  -p 3000:3000 -p 9090:9090 \
  ghcr.io/api7/aisix:latest

如果任何资源条目无效，容器会在启动时退出。docker logs aisix-quickstart 会报告所有无效的资源类型、条目和字段，而不是在第一个错误处停止。

验证网关

检查代理监听器是否存活：

curl -sS "$AISIX_PROXY/livez"

该命令应返回 ok。

列出该调用方 API Key 可见的模型：

curl -sS "$AISIX_PROXY/v1/models" \
  -H "Authorization: Bearer ${CALLER_API_KEY}"

data 数组应包含 gpt-4o-mini。

通过网关发送聊天请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${CALLER_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Say hello from AISIX AI Gateway."}
    ]
  }'

响应应采用 OpenAI Chat Completions 格式，并在 choices[0].message 中包含助手消息。

更新并重新加载配置

运行中的网关不会监听 resources.yaml。如需在不重启容器的情况下应用变更，请编辑已挂载的文件、验证它，然后向网关进程发送 SIGHUP。

例如，更新 resources.yaml，添加第二个模型，并允许现有调用方 API Key 使用该模型：

resources.yaml (updated)
_format_version: "1"

provider_keys:
  - display_name: openai-main
    provider: openai
    adapter: openai
    api_key: ${OPENAI_API_KEY}
    api_base: https://api.openai.com/v1

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

api_keys:
  - display_name: quickstart-caller
    key_env: CALLER_API_KEY
    allowed_models:
      - gpt-4o-mini
      - gpt-4o

在正在运行的容器中验证编辑后的文件：

docker exec aisix-quickstart \
  /usr/local/bin/aisix validate --resources /etc/aisix/resources.yaml

该命令应报告文件已加载四个资源。如果验证失败，请先修正报告的条目再继续。

重新加载文件：

docker kill --signal=HUP aisix-quickstart

确认调用方可以看到两个模型：

curl -sS "$AISIX_PROXY/v1/models" \
  -H "Authorization: Bearer ${CALLER_API_KEY}"

data 数组应同时包含 gpt-4o-mini 和 gpt-4o。有关配置状态、被拒绝资源的详细信息和其它资源来源，请参阅配置传播。

清理

完成后停止并删除快速入门网关：

docker rm -f aisix-quickstart

工作目录中的 config.yaml 和 resources.yaml 文件不会被修改。

下一步

你现在已经通过一个声明式文件运行了开源 AISIX 网关，并通过它发送了由模型服务提供方处理的请求。接下来可以：

阅读资源模型，了解模型服务提供方密钥、模型和调用方 API Key 如何配合工作。
使用 CLI 参考在 CI 中检查资源文件。
按照 OpenAI SDK 或 Anthropic SDK 指南，在应用代码中调用同一个网关。
在部署网关承载生产流量前，查看生产就绪。

前提条件​

创建资源文件​

创建启动配置​

启动 AISIX AI 网关​

验证网关​

更新并重新加载配置​

清理​

下一步​