AI 服务文档

约 1597 字大约 5 分钟

2025-08-11

本模块基于 FastAPI 构建，提供报告（PDF）解析、AI 评分、批处理转换与异步 Worker 能力，并与 Supabase/Postgres 集成。主要业务逻辑已迁移到 Supabase 边缘函数，后端主要提供 Worker 管理功能。

架构概览

Web API: FastAPI 应用入口在 main.py，主要提供 Worker 管理功能
服务层: 领域服务在 app/service/*（如 report_service.py, pdf_service.py, ai_service.py, module_eval.py, relationship_builder_service.py, knowledge_standardization_service.py）
异步 Worker: 任务基类与实现位于 app/worker/*，管理器在 worker_manager.py，随应用生命周期自动启动/停止
工具与配置: 日志、配置、MinerU 工具、Supabase/DB 连接在 app/utils/*
数据模型: Pydantic schemas 在 app/schemas/*（用户、评估、报告等）

项目结构

backend-ai/
├── main.py                 # FastAPI 应用入口 - Worker管理服务
├── requirements.txt        # Python 依赖包列表
├── app/                   # 应用程序代码
│   ├── __init__.py        # 包初始化文件
│   ├── api/               # API 路由和端点
│   │   ├── user.py        # 用户管理接口
│   │   └── worker.py      # Worker管理接口
│   ├── models/            # 数据模型定义
│   │   └── user.py        # 用户数据模型
│   ├── schemas/           # Pydantic 数据验证和序列化
│   │   ├── user.py        # 用户相关模型
│   │   ├── evaluation.py  # 评估相关模型
│   │   └── report.py      # 报告相关模型
│   ├── service/           # 业务逻辑服务层
│   │   ├── ai_service.py  # AI 智能评分服务
│   │   ├── pdf_service.py # PDF 处理服务（集成MinerU）
│   │   ├── report_service.py # 报告处理服务
│   │   ├── module_eval.py # 模块评估服务
│   │   ├── relationship_builder_service.py # 关系构建服务
│   │   ├── report_service.py # 报告服务
│   │   └── knowledge_standardization_service.py # 知识标准化服务
│   ├── utils/             # 工具函数和配置
│   │   ├── config.py      # 应用配置管理
│   │   ├── logger.py      # 日志系统
│   │   ├── mineru_utils.py # MinerU工具集成
│   │   ├── evaluation_status.py # 评估状态管理
│   │   └── supabase_config.py # Supabase 配置
│   └── worker/            # 异步任务处理
│       ├── base_worker.py # 基础工作器类
│       ├── task_workers.py # 具体任务工作器
│       ├── worker_manager.py # 工作器管理器
│       └── KnowledgeGraphFullBuildWorker.py # 知识图谱构建Worker
└── venv/                  # Python 虚拟环境目录

运行前置

FastAPI 环境

进入backend-ai目录，首先运行以下命令创建虚拟环境

python -m venv venv

激活虚拟环境

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

安装需要的依赖

pip install -r requirements.txt

FastAPI 开发服务器启动

在backend-ai目录下运行以下命令

uvicorn main:app --reload

API 概览

应用在 main.py 中注册路由，并通过 lifespan 自动启动/停止 Worker 管理器。

全局前缀：/api/v1
用户管理（app/api/user.py）
- GET /api/v1/api/users/{user_id} 获取单个用户
- POST /api/v1/api/users 创建用户
- PUT /api/v1/api/users/{user_id} 更新用户
- DELETE /api/v1/api/users/{user_id} 删除用户
- GET /api/v1/api/users?limit&offset 列表
Worker 管理（app/api/worker.py）
- GET /api/v1/workers/status 查询 Worker 状态
系统接口
- GET /health 健康检查
- GET /info API 信息
- GET / 根路径信息