开源 AISIX 网关快速入门

本快速入门只运行网关，在单个容器中启动开源 AISIX 网关。你将在一个 resources.yaml 文件中声明所有网关资源，使用 Docker 启动网关，并通过兼容 OpenAI 的代理 API 发送一次请求。它不需要控制台、控制面或独立配置存储，是发送第一个代理请求的最快方式。

本快速入门使用 OpenAI 作为示例上游模型服务提供方。在 AISIX 中，客户端发送调用方 API Key，网关在调用上游模型服务提供方时使用已配置的模型服务提供方密钥。

请求遵循以下路径：

客户端发送调用方 API Key 和 AISIX 模型名称 gpt-4o-mini。AISIX 对客户端进行身份认证，并使用已保存的模型服务提供方密钥调用同名 OpenAI 上游模型。客户端绝不会发送上游 OpenAI API 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 字段。网关会根据每个条目的名称生成稳定 ID，因此名称在各自集合中必须唯一。

除上述三种资源外，同一文件还可以声明 guardrails、mcp_servers、a2a_agents、cache_policies、observability_exporters 和 rate_limit_policies。

创建启动配置

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

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

proxy:
  addr: "0.0.0.0:3000"

admin:
  enabled: false

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

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

启动 AISIX AI 网关

启动网关容器，挂载这两个文件，并传入资源文件引用的两个环境变量：

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

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

docker run -d --name aisix-quickstart \
  -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 9090:9090 \
  ghcr.io/api7/aisix:latest

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

验证网关

网关在端口 3000 上暴露代理监听器。检查其存活状态：

curl -sS "http://127.0.0.1:3000/livez"

该命令应返回 ok。

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

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

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

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o-mini",
      "object": "model",
      "created": 1784186096,
      "owned_by": "openai"
    }
  ]
}

通过网关发送聊天请求：

curl -sS -X POST "http://127.0.0.1:3000/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 响应：

{
  "id": "chatcmpl-DnHR8vV2AmxQioGhIXRVvEGcf22hC",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello from AISIX AI Gateway! How can I assist you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 14,
    "total_tokens": 29
  }
}

更新并重新加载配置

运行中的网关不会监听 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

重新加载前，请使用 aisix validate 检查编辑后的文件。它会运行相同的加载流水线，包括 ${VAR} 插值、名称引用解析和 schema 验证，但不会启动监听器。如果存在任何错误，它会以非零状态退出并提供完整错误报告：

docker run --rm \
  -v "$(pwd)/resources.yaml:/etc/aisix/resources.yaml: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

预期输出：

OK: /etc/aisix/resources.yaml loaded 4 resource(s)

然后向网关进程发送 SIGHUP 以重新加载文件：

docker kill --signal=HUP aisix-quickstart

在专用指标监听器上查询 GET /status/config，确认新配置已应用：

curl -sS "http://127.0.0.1:9090/status/config"

重新加载成功后会报告 "state": "synced" 和更新后的资源数量：

{
  "state": "synced",
  "source": {
    "type": "file",
    "source_hash": "…",
    "observed_at": "2026-07-16T07:15:34Z"
  },
  "applied": {
    "config_hash": "…",
    "apply_seq": 2,
    "applied_at": "2026-07-16T07:15:34Z",
    "resource_counts": {
      "api_keys": 1,
      "models": 2,
      "provider_keys": 1
    }
  },
  "last_reload": {
    "successful": true,
    "at": "2026-07-16T07:15:34Z"
  },
  "last_failure": null,
  "rejected": []
}

如果重新加载失败，网关会继续使用最后一个有效配置提供服务；state 会报告 out_of_sync，rejected 数组会列出每个有问题的条目。该端点所有字段的说明请参阅配置状态。

清理

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

docker rm -f aisix-quickstart

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

下一步

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

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

前提条件​

创建资源文件​

创建启动配置​

启动 AISIX AI 网关​

验证网关​

更新并重新加载配置​

清理​

下一步​