企业级生成式 AI 应用 Web 服务框架：基于 FastAPI、CrewAI、OceanBase 与云原生可观测性。
- Web: FastAPI + Uvicorn
- AI 编排: CrewAI（智能体/任务/流程 YAML + Python）
- 持久化: SQLAlchemy 2.0 异步（OceanBase/MySQL 兼容）、Alembic 迁移、本地文件客户端
- 安全: X-API-Key 鉴权、SlowAPI 限流
- 可观测: structlog 结构化日志、Prometheus 指标、Request ID 贯穿
- Python 3.11+
- 可选：Redis、MySQL/OceanBase（生产）
# 克隆
git clone https://github.com/kid0317/fastapi_base.git && cd fastapi_base
# 虚拟环境与依赖
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
# 配置（复制后填入阿里云/百度 API Key 等，见下方「配置说明」）
cp .env.example .env
# 编辑 .env，至少填写 APP_LLM_API_KEY、APP_BAIDU_API_KEY；
# 也可直接使用环境变量 QWEN_API_KEY、BAIDU_API_KEY（未填 APP_ 时会自动 fallback）
# 启动（任选其一，在项目根目录）
# 方式 A：虚拟环境激活后
uvicorn app.main:app --reload --app-dir src
# 方式 B：直接用 venv 的 Python（推荐，避免子进程用错解释器）
.venv/bin/python -m uvicorn app.main:app --reload --app-dir src
# 方式 C：以模块运行（需设置 PYTHONPATH）
PYTHONPATH=src python -m app-
命令行（项目根目录，先激活
.venv或使用.venv/bin/python）：PYTHONPATH=src python -m app
断点调试时可在
src/app/__main__.py里把reload=True改为False，避免 reload 子进程导致断点不命中。 -
Cursor / VS Code：已配置
.vscode/launch.json，在「运行和调试」里选择：- FastAPI (调试，无 reload)：适合打断点调试，单进程。
- FastAPI (开发，reload)：改代码自动重载。
- Python: 以模块运行 app：以
python -m app方式启动，便于在__main__.py里设断点。
- 健康检查:
GET /health/live、GET /health/ready - API 文档:
GET /docs（开发环境） - 指标:
GET /metrics - 示例接口:
GET /api/v1/demo/ping（需请求头X-API-Key，开发环境可不配置 APP_API_KEYS） - Demo 深度调研:
POST /api/v1/demo/deep-research，请求体须为 JSON：必填topic（非空字符串，1–500 字），可选extra_instructions（字符串或 null）。需请求头Content-Type: application/json、X-API-Key。返回 422 时查看响应detail定位校验错误。需配置阿里云 LLM + 百度搜索 API Key。
src/app/
├── main.py # 入口、中间件、异常处理
├── api/v1/ # 版本化 API、dependencies
├── core/ # config、security
├── crews/ # agents、tasks、flows、tools、llm（CrewAI）
├── db/ # clients、models、migrations、repositories
├── schemas/ # Pydantic Request/Response/Domain
├── services/ # 领域服务
└── observability/ # 日志、指标
tests/ # unit、integration
deploy/ # docker、k8s、grafana
复制 .env.example 为 .env 后，至少需填入以下与阿里云、百度相关的环境变量（其余可选）：
| 变量 | 说明 | 必填 | 获取方式 |
|---|---|---|---|
| APP_LLM_API_KEY（或 QWEN_API_KEY） | 阿里云 DashScope API Key | 是 | 阿里云百炼 / 灵积控制台 创建 API-KEY |
| APP_LLM_PROVIDER | 固定填 aliyun |
否 | 默认 aliyun |
| APP_LLM_MODEL | 模型名，如 qwen-plus、qwen-turbo |
否 | 默认 qwen-plus |
| APP_LLM_REGION | 地域：cn / intl / finance |
否 | 默认 cn |
| APP_LLM_TIMEOUT | 请求超时秒数 | 否 | 默认 600 |
| 变量 | 说明 | 必填 | 获取方式 |
|---|---|---|---|
| APP_BAIDU_API_KEY（或 BAIDU_API_KEY） | 百度千帆 AppBuilder API Key | 使用百度搜索工具时必填 | 百度智能云千帆控制台 创建应用获取 API Key |
| APP_BAIDU_SEARCH_TIMEOUT | 搜索请求超时秒数 | 否 | 默认 30 |
完整项见 .env.example。
# 从项目根目录执行，PYTHONPATH 已由 pyproject.toml 配置
pytest tests/ -v深度调研集成测试（需配置 LLM + 百度 API Key，否则会跳过）：
# 方式一：使用 .env 中的 APP_LLM_API_KEY、APP_BAIDU_API_KEY
pytest tests/integration/test_deep_research.py -v
# 方式二：临时使用 QWEN_API_KEY、BAIDU_API_KEY 跑一次
export QWEN_API_KEY=sk-xxx
export BAIDU_API_KEY=bce-v3/xxx
pytest tests/integration/test_deep_research.py -v- Docker:
deploy/docker/Dockerfile，多阶段构建、非 root 用户 - K8s:
deploy/k8s/deployment.yaml，liveness/readiness 使用/health/live、/health/ready - 敏感配置使用 Secret，非敏感使用 ConfigMap，参见
deploy/k8s/configmap.example.yaml
见 doc/Python AI 应用框架设计文档.md。
MIT