7.5 KiB

Raw Permalink Blame History

数学作业批改系统 - 部署指南

📋 项目概述

这是一个基于 LangGraph 的初中数学作业批改工作流系统，支持：

✅ 图片上传识别
✅ 自动批改
✅ 坐标定位
✅ 多学生多图片并行处理
✅ Word 文档答案解析
✅ 流式响应

🔧 前置条件

1. Docker 环境

# 安装 Docker
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y docker.io docker-compose

# CentOS/RHEL
sudo yum install -y docker docker-compose

# macOS
brew install docker docker-compose

# 启动 Docker
sudo systemctl start docker
sudo systemctl enable docker

2. API 密钥（重要！）

项目依赖 Coze API，需要以下密钥：

环境变量	说明	获取方式
`COZE_API_KEY`	Coze API 访问密钥	Coze 控制台
`LLM_API_KEY`	大语言模型 API 密钥	Coze 控制台
`COZE_WORKLOAD_IDENTITY_API_KEY`	工作负载身份认证密钥	Coze 控制台
`COZE_INTEGRATION_API_KEY`	集成 API 密钥	Coze 控制台
`COZE_WORKSPACE_ID`	工作空间 ID	Coze 控制台

获取密钥步骤：

注册/登录 Coze 平台
创建工作空间
在 API 密钥管理中获取相关密钥

3. 网络要求

✅ 可访问 api.coze.cn（中国区）
✅ 可访问阿里云 OSS（用于存储图片/答案文档）
✅ 防火墙允许出站 HTTPS 连接（443 端口）

4. 系统资源要求

资源	最低配置	推荐配置
CPU	2 核	4 核+
内存	4 GB	8 GB+
磁盘	10 GB	20 GB+
网络	1 Mbps	10 Mbps+

🚀 部署步骤

方式一：使用 Dockerfile（推荐）

1. 克隆/下载项目

# 方式一：使用 git clone
git clone <your-repo-url>
cd <project-directory>

# 方式二：下载压缩包并解压
unzip <project-name>.zip
cd <project-name>

2. 修改 API 密钥

编辑 assets/Dockerfile，替换第 47-51 行的环境变量：

ENV COZE_WORKLOAD_IDENTITY_API_KEY="Bearer YOUR_KEY_HERE" \
    LLM_API_KEY="Bearer YOUR_KEY_HERE" \
    COZE_API_KEY="Bearer YOUR_KEY_HERE" \
    COZE_INTEGRATION_API_KEY="Bearer YOUR_KEY_HERE" \
    COZE_WORKSPACE_ID=YOUR_WORKSPACE_ID

⚠️ 注意：请将 YOUR_KEY_HERE 和 YOUR_WORKSPACE_ID 替换为你的实际密钥。

3. 构建 Docker 镜像

docker build -f assets/Dockerfile -t math-correction:latest .

构建时间：约 5-10 分钟（首次构建较慢）

4. 运行容器

docker run -d \
  --name math-correction \
  -p 8000:8000 \
  -v /path/to/data:/app/data \
  math-correction:latest

参数说明：

-d：后台运行
--name：容器名称
-p 8000:8000：端口映射（主机:容器）
-v /path/to/data:/app/data：数据卷挂载（可选）

5. 验证运行

# 查看容器日志
docker logs -f math-correction

# 检查健康状态
curl http://localhost:8000/health

# 测试接口
curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{"student_homework": []}'

方式二：使用 Docker Compose（更方便）

1. 创建 `docker-compose.yml`

version: '3.8'

services:
  math-correction:
    build:
      context: .
      dockerfile: assets/Dockerfile
    container_name: math-correction
    ports:
      - "8000:8000"
    environment:
      # 替换为你的实际密钥
      - COZE_WORKLOAD_IDENTITY_API_KEY=Bearer YOUR_KEY_HERE
      - LLM_API_KEY=Bearer YOUR_KEY_HERE
      - COZE_API_KEY=Bearer YOUR_KEY_HERE
      - COZE_INTEGRATION_API_KEY=Bearer YOUR_KEY_HERE
      - COZE_WORKSPACE_ID=YOUR_WORKSPACE_ID
    volumes:
      - ./data:/app/data
    restart: unless-stopped

2. 启动服务

# 构建并启动
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

📝 API 接口说明

1. HTTP 模式（同步/异步）

# 端点
POST http://localhost:8000/run
POST http://localhost:8000/stream_run

# 请求头
Content-Type: application/json

# 请求体示例
{
  "student_homework": [
    {
      "student_id": 1,
      "student_name": "张三",
      "homework_images": [
        "https://example.com/homework1.jpg",
        "https://example.com/homework2.jpg"
      ]
    }
  ],
  "answer_doc_url": "https://example.com/answers.docx"
}

2. 流式响应模式

# 端点
POST http://localhost:8000/stream_run

# 响应格式（SSE）
data: {"event": "workflow_start", "data": {...}}
data: {"event": "ping", "data": {...}}
data: {"event": "workflow_end", "data": {...}}

🔍 常见问题排查

1. 构建失败

# 清理 Docker 缓存后重新构建
docker system prune -a
docker build --no-cache -f assets/Dockerfile -t math-correction:latest .

2. 容器启动失败

# 查看详细错误日志
docker logs math-correction

# 进入容器调试
docker exec -it math-correction bash

3. API 调用 401/403 错误

原因：API 密钥无效或过期

解决：

检查 Dockerfile 中的密钥是否正确
确认密钥是否有效且未过期
重新构建镜像（docker build ...）

4. 图片下载失败

原因：图片 URL 不可访问

解决：

检查图片 URL 是否有效
确认网络是否正常
检查防火墙设置

5. 内存不足

现象：容器频繁重启或 OOM

解决：

# 增加 Docker 内存限制
docker run -d \
  --name math-correction \
  --memory="8g" \
  -p 8000:8000 \
  math-correction:latest

📊 监控与日志

查看实时日志

# 容器日志
docker logs -f math-correction

# 查看最近 100 行
docker logs --tail 100 math-correction

# 查看错误日志
docker logs math-correction | grep ERROR

性能监控

# 查看容器资源使用
docker stats math-correction

# 查看容器详情
docker inspect math-correction

🛠️ 本地开发模式

如果不想使用 Docker，可以直接在本地运行：

# 安装 Python 3.12
python3.12 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 设置环境变量（创建 .env 文件）
export COZE_API_KEY="Bearer YOUR_KEY_HERE"
export LLM_API_KEY="Bearer YOUR_KEY_HERE"
export COZE_WORKSPACE_ID=YOUR_WORKSPACE_ID

# 运行
python src/main.py -m http -p 8000

📚 相关文档

⚠️ 注意事项

API 密钥安全：
- ❌ 不要将密钥提交到代码仓库
- ✅ 使用环境变量或密钥管理服务
图片存储：
- 推荐使用对象存储（如阿里云 OSS）
- 确保 URL 可公网访问
并发限制：
- 单图片超时：120 秒
- 建议并发数：10-50（根据服务器配置调整）
数据隔离：
- 不同学科的缓存目录独立
- 建议定期清理缓存

🆘 技术支持

如遇问题，请提供以下信息：

Docker 版本：docker --version
容器日志：docker logs math-correction
错误信息截图
系统配置：uname -a

📄 许可证

请遵循相关项目的许可证条款。

7.5 KiB Raw Permalink Blame History Unescape Escape