Evoliant 的 AI 服务模块提供智能化的教育功能，包括学情分析、知识图谱构建和课程评价等核心功能。主要业务逻辑已迁移到 Supabase 边缘函数，后端主要提供 Worker 管理功能。

系统架构

Evoliant 的 AI 服务基于 FastAPI 构建，采用现代化的微服务架构，主要包含以下组件：

核心组件

• Web API 服务：FastAPI 框架提供高性能的 RESTful API 接口
• 异步任务处理：基于 Worker 系统的分布式任务处理
• PDF 智能解析：集成 MinerU 和 PyMuPDF 的文档处理引擎
• AI 评分服务：基于 OpenAI/通义等模型的智能评分和评价系统
• 实时状态跟踪：任务进度的实时监控和反馈

项目结构

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 虚拟环境目录

功能模块

核心服务

• PDF 智能解析 - 基于 MinerU 和 PyMuPDF 的文档内容提取和分析
• AI 自动评分 - 基于通义模型的智能评分系统
• 报告处理 - 端到端的报告上传、解析、评估流程
• 知识图谱构建 - 智能化的知识关系构建和标准化

API 端点

• 用户管理 (app/api/users) - 用户注册、登录、权限管理
• Worker 管理 (app/api/workers) - 异步任务状态查询和管理
• 系统接口 - 健康检查、API 信息、根路径

异步任务系统

• 任务队列管理 - 基于 Worker 系统的任务调度
• 工作器池 - 可扩展的并发任务处理能力
• 状态持久化 - 任务执行状态的数据库存储和恢复
• 错误处理 - 完善的异常处理和重试机制

技术栈

Web 框架

• FastAPI 0.112+：高性能的 Python Web 框架，支持异步处理
• Uvicorn：ASGI 服务器，提供生产级性能
• Pydantic 2.7+：数据验证和序列化框架

数据库和存储

• Supabase：PostgreSQL 数据库和实时功能
• 异步数据库驱动：asyncpg 和 psycopg2

PDF 处理

• MinerU：AI 驱动的 PDF 内容理解（主要工具）
• PyMuPDF：高性能 PDF 解析和渲染（备选方案）
• OpenCV：图像处理和识别
• Pillow：图像格式转换和处理

机器学习和 AI

• 通义千问：阿里云大语言模型

异步和并发

• asyncio：Python 异步编程支持
• aiofiles：异步文件操作
• httpx：异步 HTTP 客户端

开发和监控

• Loguru：结构化日志系统
• Pytest：测试框架
• Black & isort：代码格式化和排序
• MyPy：静态类型检查

系统特性

高性能

• 异步 I/O 处理，支持高并发请求
• Worker 任务系统，可横向扩展
• 内存优化的 PDF 处理流程

可扩展性

• 模块化的服务架构，易于功能扩展
• 插件式的工作器系统，支持自定义任务类型
• 配置驱动的服务参数调整

可靠性

• 完善的错误处理和日志记录
• 任务状态持久化，支持故障恢复
• 健康检查和监控端点
• AI 服务容错机制，自动回退到模拟模式

安全性

• 输入数据验证和清理
• 文件上传安全检查
• 环境变量配置管理

核心服务详解

AI 评分服务

• 评分维度：目录、正文、引文分别评分
• 评分算法：基础分数 × 目录等级系数 = 最终得分
• 等级评定：优秀(90-100)、良好(80-89)、中等(70-79)、及格(60-69)、不及格(0-59)
• 容错机制：AI 请求失败时自动回退到模拟评分模式

PDF 处理服务

• 核心工具：集成 MinerU 进行高质量 PDF 解析
• 支持格式：PDF 文件（最大 50MB）
• 功能特性：
  • 文本提取和布局检测
  • 公式和表格识别
  • 图像提取
  • 元数据提取（页数、作者、创建时间等）
• 回退机制：MinerU 不可用时使用 PyMuPDF 作为备选方案

报告处理服务

• 端到端处理：从文件上传到内容解析的完整流程
• 文件管理：自动生成 UUID、计算哈希值、文件归档
• 内容提取：目录、正文、摘要、关键词、引文等结构化信息
• 状态跟踪：实时监控处理进度（下载 → 转换 → 分析 → 评分 → 保存）

开发指南

本地开发环境

进入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

任务监控

• 实时任务状态查询
• Worker 性能监控
• 错误日志和堆栈追踪
• 系统资源使用情况

开发注意事项

1. AI 服务配置：确保正确配置 API 密钥或使用模拟模式
2. MinerU 依赖：如需完整 PDF 处理功能，确保 MinerU 服务可用
3. 环境变量：配置必要的环境变量（数据库连接、API 密钥等）
4. Worker 配置：通过环境变量调整 Worker 数量和类型
5. 日志监控：使用内置日志系统监控应用运行状态

请参考 README 文档 了解 AI 服务的详细技术规范和开发指导。

版权所有

版权归属：Evoliant

许可证：MIT