自托管快速开始

本页带你在本地启动 AISIX，配置一个服务提供方密钥、一个模型别名和一个调用方 API Key，然后发送第一条代理请求。

在这个自托管快速开始中，你将在本地运行 AISIX AI 网关，创建代理流量所需的最小资源，并通过兼容 OpenAI 的代理 API 发送一次请求。

自托管部署的 AISIX AI 网关使用 etcd 存储配置。本快速开始会通过 Docker Compose 启动本地 etcd 容器和本地 AISIX AI 网关容器。

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

请求链路如下：

客户端发送调用方 API Key 和 AISIX 模型别名 gpt-4o-mini。AISIX 会认证客户端，并使用已保存的服务提供方密钥调用同名的 OpenAI 上游模型。客户端不需要、也不会直接发送上游 OpenAI 密钥。

准备工作

安装带有 Docker Compose 的 Docker，用于启动本地 etcd 和 AISIX AI 网关容器。
安装 cURL，用于向 Admin API 和代理 API 发送请求。
安装 jq，用于从 Admin API 响应中读取 ID。
准备一个可访问 gpt-4o-mini 且有可用额度的 OpenAI API Key。

获取 AISIX AI 网关

首先创建本地文件，并使用 Docker Compose 启动 AISIX AI 网关。

创建工作目录

创建一个目录用于保存本地配置文件：

mkdir aisix-quickstart
cd aisix-quickstart

创建本地配置

为本地网关容器创建 config.yaml 文件：

config.yaml
etcd:
  endpoints:
    - "http://etcd:2379"
  prefix: "/aisix"
  dial_timeout_ms: 5000
  request_timeout_ms: 5000

proxy:
  addr: "0.0.0.0:3000"

admin:
  addr: "0.0.0.0:3001"
  admin_keys:
    - "admin-local-only-change-me"

observability:
  service_name: "aisix"
  log_level: "info"

cache:
  backend: "memory"

创建 Compose 编排

创建 docker-compose.yml 文件：

docker-compose.yml
services:
  etcd:
    image: quay.io/coreos/etcd:v3.5.18
    command:
      - /usr/local/bin/etcd
      - --advertise-client-urls=http://etcd:2379
      - --listen-client-urls=http://0.0.0.0:2379

  aisix:
    image: ghcr.io/api7/aisix:0.1.0
    volumes:
      - ./config.yaml:/etc/aisix/config.yaml:ro
    ports:
      - "3000:3000"
      - "3001:3001"
    depends_on:
      - etcd

本指南使用 GitHub Container Registry 镜像。发布镜像也会同步到 Docker Hub，例如 docker.io/api7/aisix:0.1.0。

启动 AISIX AI 网关

启动本地编排：

docker compose up -d

网关会在 http://127.0.0.1:3000 暴露代理监听器，并在 http://127.0.0.1:3001 暴露 Admin 监听器。检查这两个监听器：

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

两个命令都应该返回 ok。

创建网关资源

接下来创建 AISIX 代理流量前所需的服务提供方密钥、模型和调用方 API Key。

导出本地变量

导出后续命令要使用的变量：

# 来自 config.yaml 的本地 Admin Key。
export AISIX_ADMIN_KEY="admin-local-only-change-me"

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

# 客户端请求使用的示例调用方 API Key。
export AISIX_API_KEY="sk-demo-caller"

创建服务提供方密钥

创建一个保存 OpenAI 凭证的服务提供方密钥。该命令会打印响应，并保存返回的 ID 供下一步使用：

PROVIDER_KEY_RESPONSE=$(curl -sS -X POST "http://127.0.0.1:3001/admin/v1/provider_keys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "openai-upstream",
    "provider": "openai",
    "adapter": "openai",
    "secret": "'"${OPENAI_API_KEY}"'",
    "api_base": "https://api.openai.com/v1"
  }')

printf '%s\n' "${PROVIDER_KEY_RESPONSE}" | jq .
PROVIDER_KEY_ID=$(jq -r '.id // empty' <<< "${PROVIDER_KEY_RESPONSE}")

关于服务提供方、适配器和 base URL 设置，参见服务提供方凭证。

创建模型

该资源会把面向客户端的 AISIX 模型别名连接到上游 OpenAI 模型。在本示例中，两者都叫 gpt-4o-mini。

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/models" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gpt-4o-mini",
    "provider": "openai",
    "model_name": "gpt-4o-mini",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }'

客户端在代理 API 中使用 gpt-4o-mini 作为 model 值。上游服务提供方会收到相同的 model 值。

创建客户端 API Key

AISIX 只保存调用方 API Key 的 SHA-256 哈希值。写入 API Key 资源前，先生成该哈希：

AISIX_API_KEY_HASH=$(printf '%s' "${AISIX_API_KEY}" | shasum -a 256 | awk '{print $1}')

然后创建 API Key 资源，允许该调用方 API Key 使用 gpt-4o-mini：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${AISIX_API_KEY_HASH}"'",
    "allowed_models": ["gpt-4o-mini"]
  }'

验证流量

网关资源写入 etcd 后，代理会读取这些资源。列出该调用方 API Key 可见的模型：

curl -sS "http://127.0.0.1:3000/v1/models" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  | jq -r '.data[].id'

输出中应该包含 gpt-4o-mini。此时网关已经运行，代理也能看到配置好的模型。

向网关发送请求：

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

你应该会收到类似下面的 OpenAI Chat Completions 响应：

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

下一步

你已经配置好了本地网关、调用方 API Key 和 AISIX 模型别名，可以通过 AISIX 发送由服务提供方承载的请求。接下来可以阅读资源模型，了解这些网关资源如何配合工作。

如果要从应用代码调用同一个网关，可以继续阅读 OpenAI SDK 快速开始或 Anthropic SDK 快速开始。

准备工作​

获取 AISIX AI 网关​

创建工作目录​

创建本地配置​

创建 Compose 编排​

启动 AISIX AI 网关​

创建网关资源​

导出本地变量​

创建服务提供方密钥​

创建模型​

创建客户端 API Key​

验证流量​

下一步​