AISIX Cloud 快速入门

在本快速入门中，你将在一台机器上使用 Docker Compose、随附的 PostgreSQL 数据库和本地端点评估 AISIX Cloud。你将启动控制面和控制台、连接 AISIX 网关、配置模型并发送请求。

资源创建步骤使用 AISIX Cloud Admin API，便于复制、粘贴和自动化。你只需在控制台中连接一次网关。控制台也可以创建本快速入门中使用的每种资源。

许可证

AISIX Cloud 控制面和控制台是商业软件。开发、测试和评估可以免费使用部分功能，但生产使用需要商业许可证。如需在生产环境运行控制面，请联系 API7或发送邮件至 support@api7.ai。

此部署包含两个部分：

管理栈包含控制面服务（cp-api 和 dp-manager）、控制台及随附的 PostgreSQL 数据库。你可以通过一条命令安装该栈，并用它管理网关。
一个或多个 AISIX 网关作为数据面连接控制面并承载 AI 流量。

准备工作

安装带有 Docker Compose V2 的 Docker。
安装 cURL、jq、tar 和 OpenSSL。引导脚本使用 cURL、tar 和 OpenSSL，资源步骤使用 cURL 和 jq。
确保安装主机可以访问 run.api7.ai 和 Docker Hub。
确保安装主机上的 5432、8080、7944 和 3000 端口可用。
使用可以访问安装主机 8080 端口的浏览器。
准备用于本快速入门所配置模型的 OpenAI API Key。

启动控制面

在安装了 Docker 且可以访问互联网的主机上运行：

curl -fsSL "https://run.api7.ai/aisix-self-hosted/quickstart" | bash

脚本会将 On-Premises 软件包下载到 ./aisix-self-hosted，生成包含全新 Secret 的 .env 文件，从 Docker Hub 拉取容器镜像并启动管理栈。启动完成后，它会打印控制台 URL，默认为 http://localhost:8080。使用 ./aisix-self-hosted/run.sh 管理运行中的管理栈（logs、stop、down）。

对于本单主机快速入门，请打开 ./aisix-self-hosted/.env，并将数据面管理器 URL 设置为：

AISIX_CLOUD_DPMGR_BASE_URL=https://host.docker.internal:7944

重新创建 api 和 dpm Docker Compose 服务，使控制台使用更新后的端点，并让 dp-manager 为该端点签发 TLS 证书：

cd aisix-self-hosted
docker compose up -d api dpm
cd ..

创建 Admin Token

AISIX Cloud Admin API 使用组织级 Admin Token 进行身份认证。请在控制台中创建 Token：

打开控制台（默认为 http://localhost:8080），选择 Create an account 注册第一个用户，然后创建第一个组织。
前往 Admin tokens，选择 New token，启用创建资源所需的 write 权限范围，然后创建 Token。
复制 Token（aisix_pat_...）。明文值只显示一次。

设置 API base URL 和 Token：

export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"

创建网关资源

通过 AISIX Cloud Admin API 创建网关所需的资源。每条命令都会保存供下一步使用的 ID。如果 curl 或 jq 报错，请先停止并解决问题；缺少 ID 会导致后续命令失败。

创建用于限定资源作用域的环境：

ENV=$(curl -fsS -X POST "$AISIX_CP/environments" \
  -H "Authorization: Bearer $AISIX_TOKEN" -H "Content-Type: application/json" \
  -d '{"display_name": "prod"}')
ENV_ID=$(echo "$ENV" | jq -er '.environment.id')
export ENV_ID

创建一个保存 OpenAI 凭证且允许在该环境中使用的模型服务提供方密钥：

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

PROVIDER_KEY=$(curl -fsS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "display_name": "OpenAI",
    "api_key": "'"${OPENAI_API_KEY}"'",
    "api_base": "https://api.openai.com/v1",
    "allowed_environments": ["'"$ENV_ID"'"]
  }')
PROVIDER_KEY_ID=$(echo "$PROVIDER_KEY" | jq -er '.provider_key.id')
export PROVIDER_KEY_ID

创建由该模型服务提供方密钥支持的 gpt-4o-mini 模型。客户端发送 gpt-4o-mini，AISIX AI 网关使用同一个上游模型调用 OpenAI：

MODEL=$(curl -fsS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "display_name": "gpt-4o-mini",
    "model_name": "gpt-4o-mini",
    "provider_key_id": "'"$PROVIDER_KEY_ID"'"
  }')
MODEL_ID=$(echo "$MODEL" | jq -er '.model.id')
export MODEL_ID

创建允许使用该模型的调用方 API Key。明文密钥只返回一次，请将其保存：

API_KEY=$(curl -fsS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "display_name": "quickstart-caller",
    "allowed_models": ["'"$MODEL_ID"'"]
  }')
AISIX_API_KEY=$(echo "$API_KEY" | jq -er '.plaintext')
export AISIX_API_KEY
echo "$AISIX_API_KEY"

继续前，请确认每个资源都已成功创建。值为空或 null 表示创建调用失败。请重新运行命令并查看响应；常见原因是 Admin Token 没有 write 权限范围，从而收到 401 或 403 响应。

printf 'ENV_ID=%s\n' "$ENV_ID"
printf 'PROVIDER_KEY_ID=%s\n' "$PROVIDER_KEY_ID"
printf 'MODEL_ID=%s\n' "$MODEL_ID"
printf 'AISIX_API_KEY=%s\n' "$AISIX_API_KEY"

连接网关

控制面本身不承载流量。请将 AISIX AI 网关连接到你的环境：

在控制台中打开环境的 Data planes 视图，签发网关证书，并复制生成的安装命令片段。请参阅连接 AISIX 网关。
在 Linux 上，将 --add-host host.docker.internal:host-gateway 添加到生成的 docker run 命令，使网关容器能够访问主机上的 dp-manager。Docker Desktop 会自动解析 host.docker.internal。
在本地机器上使用该命令片段运行网关。连接 AISIX Cloud 的 AISIX 网关默认将代理监听器绑定到端口 3000。

等待控制台显示网关已成为该环境的健康数据面。随后，gpt-4o-mini 模型会投射到该网关。

发送请求

网关在 http://127.0.0.1:3000 上提供服务时，使用之前创建的调用方 API Key 发送请求：

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 Gateway."}
    ]
  }'

验证请求和用量

你应该会收到包含 Assistant 消息的兼容 OpenAI Chat Completions 响应。该请求的用量会显示在控制台中的对应环境下，确认请求已经通过 AISIX AI 网关。

清理

不再需要示例资源时，请在控制台中删除调用方 API Key、模型和模型服务提供方密钥。

如需停止本地容器但不删除它们，请运行：

./aisix-self-hosted/run.sh stop

如需停止并删除容器，同时保留 PostgreSQL 数据卷，请运行：

./aisix-self-hosted/run.sh down

下一步

你现在已经通过连接本地控制面的网关发送了请求。接下来可以：

按照 On-Premises 安装选择安装方式，并准备持久化环境。
阅读资源模型，了解模型服务提供方密钥、模型和调用方 API Key 如何配合工作。
通过 OpenAI SDK 或 Anthropic SDK 指南，在应用代码中调用网关。

准备工作​

启动控制面​

创建 Admin Token​

创建网关资源​

连接网关​

发送请求​

验证请求和用量​

清理​

下一步​