Skip to main content
前置要求:
  • 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
1

安装与环境同步

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

# 同步锁定依赖到虚拟环境
make sync-deps
需要已安装 uv，且已在项目根目录执行命令。
2

认证系统初始化（可选）

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

# 创建管理员用户（需先完成 setup-auth）
make create-admin
未设置 JWT_SECRET_KEY 时，系统会自动生成安全密钥。若需固定密钥，可在 .env 中设置。
3

启动与构建

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

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

# 构建项目发行物
make build
4

测试与质量

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

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

API 与文档

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

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

调试认证与 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密钥有效。
开发命令由 Makefile 管理。若需改端口，可直接运行：uv run uvicorn main:app --port 8001 --reload

​
下一步

Agent开发

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

API文档

查看完整的API接口文档

部署指南

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

架构设计

深入了解AI Gateway的技术架构