自适应学习系统 - 完整部署指南

自适应学习系统部署指南摘要
本文详细介绍了自适应学习系统的完整部署流程，系统架构包含PDF处理模块、PostgreSQL数据库、FastAPI后端和Dify工作流。部署步骤包括：1) 安装Python依赖和PostgreSQL；2) 配置数据库连接；3) 处理PDF并初始化数据；4) 启动FastAPI服务；5) 配置Dify工作流集成；6) 可选的生产环境部署方案。文章还提供了常见问题解决方案，如使用LLM增强PDF解析质量、生成更智能的测试题以及API性能监控方法。系统支持Docker容器化部署，并提供了详细的Nginx反向代理配置示例。

整体架构

[PDF文件]
    ↓
[process_pdf.py] - 处理PDF，生成X/Y/Z，构建路径
    ↓
[PostgreSQL数据库] - 存储所有数据
    ↑
[main.py - FastAPI] - 提供REST API
    ↑
[Dify Workflow] - 用户交互逻辑
    ↓
[用户]

---

第一步：环境准备

1.1 安装Python依赖

pip install fastapi uvicorn sqlalchemy psycopg2-binary pymupdf pydantic

1.2 安装PostgreSQL

Ubuntu/Debian:

sudo apt update
sudo apt install postgresql postgresql-contrib

MacOS:

brew install postgresql
brew services start postgresql

Windows:
下载安装包：https://www.postgresql.org/download/windows/

1.3 创建数据库

# 进入PostgreSQL命令行
sudo -u postgres psql

# 创建数据库
CREATE DATABASE adaptive_learning;

# 创建用户
CREATE USER your_user WITH PASSWORD 'your_password';

# 授权
GRANT ALL PRIVILEGES ON DATABASE adaptive_learning TO your_user;

# 退出
\q

---

第二步：配置代码

2.1 修改数据库连接

编辑 main.py 第15行：

DATABASE_URL = "postgresql://your_user:your_password@localhost/adaptive_learning"

替换为你的实际用户名和密码。

2.2 文件结构

project/
├── main.py              # FastAPI后端
├── process_pdf.py       # PDF处理脚本
├── requirements.txt     # Python依赖
└── data/
    └── course.pdf       # 你的课程PDF

---

第三步：处理PDF并初始化数据

3.1 运行处理脚本

python process_pdf.py

这会：

1. 解析PDF，提取X slides
2. 生成Y slides（压缩版）
3. 生成Z slides（练习版）
4. 构建A/B/C三条路径
5. 保存到数据库

3.2 验证数据

sudo -u postgres psql adaptive_learning

# 查看课程
SELECT * FROM courses;

# 查看slides数量
SELECT slide_type, COUNT(*) FROM slides GROUP BY slide_type;

# 查看路径
SELECT * FROM learning_paths;

---

第四步：启动FastAPI服务

4.1 启动服务

uvicorn main:app --reload --host 0.0.0.0 --port 8000

4.2 测试API

访问：http://localhost:8000/docs

你会看到自动生成的API文档（Swagger UI）

4.3 手动测试

# 测试健康检查
curl http://localhost:8000/health

# 开始课程
curl -X POST http://localhost:8000/api/courses/start \
  -H "Content-Type: application/json" \
  -d '{"course_id": 1, "user_id": "test_user"}'

# 会返回：
# {"session_id": "xxx", "first_slide_id": "X1"}

---

第五步：配置Dify Workflow

5.1 修改Dify代码节点中的API地址

在所有代码节点中，将：

api_url = "http://your-api-domain.com/..."

改为：

api_url = "http://localhost:8000/..."  # 开发环境
# 或
api_url = "http://your-server-ip:8000/..."  # 生产环境

5.2 测试Dify调用

在Dify的"初始化会话"代码节点中，点击"运行"测试，确保能成功调用API。

---

第六步：生产环境部署（可选）

6.1 使用Gunicorn部署

pip install gunicorn

gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000

6.2 使用Nginx反向代理

# /etc/nginx/sites-available/adaptive-learning
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

6.3 使用Docker部署

创建 Dockerfile:

FROM python:3.10

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

创建 docker-compose.yml:

version: '3.8'

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: adaptive_learning
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  api:
    build: .
    ports:
      - "8000:8000"
    depends_on:
      - postgres
    environment:
      DATABASE_URL: postgresql://user:password@postgres/adaptive_learning

volumes:
  postgres_data:

启动：

docker-compose up -d

---

常见问题

Q1: PDF解析不准确怎么办？

解决方案：使用LLM增强解析

在 process_pdf.py 中，调用Claude API来智能分割：

import anthropic

def llm_split_pdf(pdf_text):
    client = anthropic.Anthropic(api_key="your-api-key")
    
    message = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=4000,
        messages=[{
            "role": "user",
            "content": f"将以下PDF文本分割成独立的学习单元，返回JSON格式：\n{pdf_text}"
        }]
    )
    
    return message.content

Q2: 如何生成更好的测试题？

解决方案：集成LLM

修改 generate_quiz_for_slide 函数，调用Claude API：

def generate_quiz_for_slide(slide_content, slide_id):
    client = anthropic.Anthropic(api_key="your-api-key")
    
    prompt = f"""
基于以下内容生成3道单选题：
{json.dumps(slide_content, ensure_ascii=False)}

要求：严格JSON格式，无markdown
"""
    
    message = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=2000,
        messages=[{"role": "user", "content": prompt}]
    )
    
    return json.loads(message.content[0].text)

Q3: 如何监控API性能？

添加日志和监控：

import logging
from datetime import datetime

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@app.middleware("http")
async def log_requests(request, call_next):
    start_time = datetime.now()
    response = await call_next(request)
    duration = (datetime.now() - start_time).total_seconds()
    
    logger.info(f"{request.method} {request.url.path} - {duration:.2f}s")
    
    return response

Q4: 数据库迁移怎么处理？

使用Alembic：

pip install alembic

# 初始化
alembic init alembic

# 创建迁移
alembic revision --autogenerate -m "Add new column"

# 执行迁移
alembic upgrade head

---

测试检查清单

部署完成后，依次测试：

• PostgreSQL数据库可以连接
• 运行 process_pdf.py 成功处理PDF
• 数据库中有courses、slides、paths数据
• FastAPI服务启动成功
• 访问 http://localhost:8000/docs 看到API文档
• 手动测试 /api/courses/start 接口
• 手动测试 /api/slides/{slide_id} 接口
• 手动测试 /api/quiz/submit 接口
• Dify代码节点能成功调用API
• Dify workflow完整运行一次

---

下一步优化

1. 性能优化

   • 添加Redis缓存
   • 数据库查询优化（添加索引）
   • 使用异步数据库操作

2. 功能增强

   • 添加用户认证（JWT）
   • 支持多门课程管理
   • 添加学习进度可视化

3. 监控和日志

   • 集成Sentry错误追踪
   • 使用Prometheus监控
   • ELK日志收集

4. 扩展性

   • 支持更多PDF格式
   • 支持视频、音频内容
   • 多语言支持

---

需要帮助？请检查：

1. FastAPI日志：终端输出
2. PostgreSQL日志：/var/log/postgresql/
3. Dify测试面板：右侧详情窗口