开发指南 - AI Gateway

前置要求:

Python 3.12+
uv包管理器
至少一个AI平台的API密钥

环境准备

安装uv

uv是一个快速的Python包管理器，推荐用于AI Gateway开发：

# 安装uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 验证安装
uv --version

克隆项目

git clone https://github.com/your-repo/ai-gateway.git
cd ai-gateway

本地开发

1. 安装依赖

使用uv安装项目依赖：

# 创建虚拟环境并安装依赖
uv sync

# 激活虚拟环境
source .venv/bin/activate  # Linux/macOS
# 或
.venv\Scripts\activate     # Windows

2. 配置环境变量

参考快速开始页面中的环境变量配置部分，创建 .env 文件并配置必要的API密钥。

3. 启动开发服务器

# 启动开发服务器（与 Makefile 保持一致）
make run

开发服务器启动后，访问 http://localhost:8000 查看API文档

使用 Makefile 进行本地调试

如果你更偏好通过 Makefile 管理开发与调试流程，项目内置了常用的一站式命令：

# 查看所有可用命令
make help

安装与环境同步

# 安装生产/开发/测试/文档依赖（按需选择其一）
make install
make install-dev
make install-test
make install-docs

# 同步锁定依赖到虚拟环境
make sync-deps

需要已安装 uv，且已在项目根目录执行命令。

认证系统初始化（可选）

# 初始化 .env 与依赖，并检查本机 MongoDB 环境
make setup-auth

# 创建管理员用户（需先完成 setup-auth）
make create-admin

未设置 JWT_SECRET_KEY 时，系统会自动生成安全密钥。若需固定密钥，可在 .env 中设置。

启动与构建

# 启动开发服务器（支持热重载）
make run

# 启动生产服务器
make run-prod

# 构建项目发行物
make build

测试与质量

# 运行测试 / 生成覆盖率报告
make test
make test-cov

# 代码检查与格式化
make lint
make format

API 与文档

# 生成 OpenAPI 规范文件 openapi.json（基于运行时 app.openapi()）
make openapi

# 构建文档（Mintlify 站点）
make docs

完成后可在 openapi.json 中查看接口规范；文档构建产物位于站点输出目录。

调试认证与 API Key（可选）

# 在另一个终端先执行 make run 启动服务后，再运行以下命令
make test-auth
make test-api-keys

上述两个命令会提示“等待服务启动后按任意键继续…”。若在 CI 或无人值守环境，请避免使用，或改为直接运行对应的 Python 测试脚本。

更多常用命令

# 清理构建与缓存
make clean

# 依赖升级与同步
make update-deps

# 预提交检查与安装钩子
make pre-commit
make install-hooks

# 打印项目信息
make info

开发工具

代码格式化

AI Gateway 使用 black 和 isort 进行格式化。可直接使用 Makefile：

# 一键格式化
make format

# 代码检查（flake8 + mypy）
make lint

类型检查

使用 mypy 进行类型检查，可通过 make lint 统一执行，或单独运行：

uv run mypy agent/ api/ auth/ services/ database/ models/

测试

运行项目测试：

# 运行所有测试
make test

# 生成覆盖率报告
make test-cov

# 智能体管理 API 测试
make test-agents

调试技巧

日志配置

在开发环境中，可以设置更详细的日志级别：

# 设置日志级别
export LOG_LEVEL=DEBUG

# 启动服务
make run

调试模式

使用Python调试器进行调试：

import pdb; pdb.set_trace()  # 在代码中添加断点

或者使用VSCode的调试功能：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "AI Gateway Debug",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/main.py",
      "env": {
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  ]
}

开发新Agent

要开发新的AI平台支持，请参考Agent开发指南页面。

文档开发

本地预览文档

AI Gateway 使用Mintlify进行文档管理。要预览文档：

# 安装Mintlify CLI
npm i -g mint

# 启动文档预览
mint dev

文档将在 http://localhost:3000 上可用。

自定义端口

如果3000端口被占用，可以使用其他端口：

mint dev --port 3333

常见问题

依赖安装失败

检查Python版本是否为3.12+，确保网络连接正常。

API调用失败

确认环境变量配置正确，API密钥有效。

端口被占用

开发命令由 Makefile 管理。若需改端口，可直接运行：uv run uvicorn main:app --port 8001 --reload

下一步

Agent开发

学习如何为AI Gateway添加新的AI平台支持

API文档

查看完整的API接口文档

部署指南

了解如何部署AI Gateway到生产环境

架构设计

深入了解AI Gateway的技术架构

​环境准备

​安装uv

​克隆项目

​本地开发

​1. 安装依赖

​2. 配置环境变量

​3. 启动开发服务器

​使用 Makefile 进行本地调试

​开发工具

​代码格式化

​类型检查

​测试

​调试技巧

​日志配置

​调试模式

​开发新Agent

​文档开发

​本地预览文档

​自定义端口

​常见问题

​下一步

Agent开发

API文档

部署指南

架构设计

环境准备

安装uv

克隆项目

本地开发

1. 安装依赖

2. 配置环境变量

3. 启动开发服务器

使用 Makefile 进行本地调试

开发工具

代码格式化

类型检查

测试

调试技巧

日志配置

调试模式

开发新Agent

文档开发

本地预览文档

自定义端口

常见问题

下一步