Documentation Index
Fetch the complete documentation index at: https://ai-gateway.juniortree.com/llms.txt
Use this file to discover all available pages before exploring further.
前置要求:
- 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
使用 Makefile 进行本地调试
如果你更偏好通过 Makefile 管理开发与调试流程，项目内置了常用的一站式命令：
安装与环境同步
# 安装生产/开发/测试/文档依赖（按需选择其一）
make install
make install-dev
make install-test
make install-docs
# 同步锁定依赖到虚拟环境
make sync-deps
认证系统初始化（可选）
# 初始化 .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() # 在代码中添加断点
{
"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
自定义端口
如果3000端口被占用，可以使用其他端口：
常见问题
检查Python版本是否为3.12+，确保网络连接正常。
确认环境变量配置正确，API密钥有效。
开发命令由 Makefile 管理。若需改端口，可直接运行：uv run uvicorn main:app --port 8001 --reload
下一步
Agent开发
学习如何为AI Gateway添加新的AI平台支持
部署指南
了解如何部署AI Gateway到生产环境
