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.txtFastAPI 开发服务器启动
在backend-ai目录下运行以下命令
uvicorn main:app --reloadAPI 概览
应用在 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 /infoAPI 信息GET /根路径信息
核心服务功能
AI 评分服务 (ai_service.py)
- 功能: 基于 OpenAI/通义等模型的智能评分
- 评分维度: 目录、正文、引文分别评分
- 评分算法: 基础分数 × 目录等级系数 = 最终得分
- 等级评定: 优秀(90-100)、良好(80-89)、中等(70-79)、及格(60-69)、不及格(0-59)
- 容错机制: AI 请求失败时自动回退到模拟评分模式
PDF 处理服务 (pdf_service.py)
- 核心工具: 集成 MinerU 进行高质量 PDF 解析
- 支持格式: PDF 文件(最大 50MB)
- 功能特性:
- 文本提取和布局检测
- 公式和表格识别
- 图像提取
- 元数据提取(页数、作者、创建时间等)
- 回退机制: MinerU 不可用时使用 PyMuPDF 作为备选方案
报告处理服务 (report_service.py)
- 端到端处理: 从文件上传到内容解析的完整流程
- 文件管理: 自动生成 UUID、计算哈希值、文件归档
- 内容提取: 目录、正文、摘要、关键词、引文等结构化信息
- 状态跟踪: 实时监控处理进度(下载 → 转换 → 分析 → 评分 → 保存)
评估系统 (evaluation.py)
- 评分模型: 支持自定义评估标准和权重配置
- 评分细分: 每个部分可设置多个评估标准,支持权重计算
- 评语系统: 自动生成评语、优点和改进建议
- 等级映射: 分数自动映射到评估等级
异步 Worker 系统
基础架构
- 基类:
app/worker/base_worker.py- 任务路由、错误处理、死信队列、优雅启停、DB 连接池管理
具体实现
- ExampleWorker: 示例任务处理器,支持"example"和"test"类型任务
- BatchPDFWorker: 批量 PDF 处理,支持从 Supabase Storage 下载和转换
- AIScoringWorker: AI 评分任务处理
- KnowledgeGraphFullBuildWorker: 知识图谱构建
管理器
- worker_manager.py:
- 环境变量驱动 Worker 数量和类型配置
- 应用启动时自动启动,关闭时优雅停止
- 集成在 main.py 的 lifespan 中
数据模型
用户模型 (user.py)
- 用户基本信息、认证状态、权限管理
评估模型 (evaluation.py)
- EvaluationResult: 完整评估结果
- SectionScore: 各部分评分
- ScoreBreakdown: 评分细分
- EvaluationLevel: 评估等级枚举
报告模型 (report.py)
- PDFInfo: PDF 内容信息(目录、正文、摘要、引文等)
- ReportMetadata: 报告元数据(UUID、文件名、状态等)
- ReportScore: 评分详情
- ProcessingStage: 处理阶段枚举
工具与配置
日志系统 (logger.py)
- 模块化日志实例管理
- 支持控制台和文件输出
- 可配置日志级别和轮转策略
配置管理 (config.py)
- 统一配置管理(API 密钥、数据库连接、AI 模型等)
- 环境变量支持
- 开发和生产环境配置分离
MinerU 集成 (mineru_utils.py)
- MinerU 可用性检测
- PDF 转换接口封装
- 页面图像提取功能
评估状态管理 (evaluation_status.py)
- 评估流程状态跟踪
- 状态转换逻辑
- 进度监控
Supabase 集成
数据库连接 (supabase_config.py)
- 异步数据库连接池管理
- Supabase 客户端配置
- 环境变量配置支持
边缘函数架构
- 主要业务逻辑已迁移到 Supabase 边缘函数
- 后端主要提供 Worker 管理和任务调度
- 支持实时状态同步和任务队列管理
开发注意事项
- AI 服务配置: 确保正确配置 API 密钥或使用模拟模式
- MinerU 依赖: 如需完整 PDF 处理功能,确保 MinerU 服务可用
- 环境变量: 配置必要的环境变量(数据库连接、API 密钥等)
- Worker 配置: 通过环境变量调整 Worker 数量和类型
- 日志监控: 使用内置日志系统监控应用运行状态
部署说明
- 生产环境: 建议使用 Gunicorn 或 Uvicorn 作为 WSGI 服务器
- 容器化: 支持 Docker 部署,包含所有必要的 Python 依赖
- 监控: 集成健康检查和状态监控端点
- 扩展性: Worker 系统支持水平扩展,可根据负载调整 Worker 数量
版权所有
版权归属:Evoliant
许可证:MIT