PhysicsCorrection/DEPLOYMENT.md

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

## 📋 项目概述

这是一个基于 LangGraph 的初中数学作业批改工作流系统，支持：
- ✅ 图片上传识别
- ✅ 自动批改
- ✅ 坐标定位
- ✅ 多学生多图片并行处理
- ✅ Word 文档答案解析
- ✅ 流式响应

---

## 🔧 前置条件

### 1. **Docker 环境**

```bash
# 安装 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 控制台](https://www.coze.cn/) |
| `LLM_API_KEY` | 大语言模型 API 密钥 | [Coze 控制台](https://www.coze.cn/) |
| `COZE_WORKLOAD_IDENTITY_API_KEY` | 工作负载身份认证密钥 | [Coze 控制台](https://www.coze.cn/) |
| `COZE_INTEGRATION_API_KEY` | 集成 API 密钥 | [Coze 控制台](https://www.coze.cn/) |
| `COZE_WORKSPACE_ID` | 工作空间 ID | [Coze 控制台](https://www.coze.cn/) |

**获取密钥步骤**：
1. 注册/登录 [Coze 平台](https://www.coze.cn/)
2. 创建工作空间
3. 在 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. 克隆/下载项目

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

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

#### 2. 修改 API 密钥

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

```dockerfile
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 镜像

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

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

#### 4. 运行容器

```bash
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. 验证运行

```bash
# 查看容器日志
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`

```yaml
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. 启动服务

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

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

---

## 📝 API 接口说明

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

```bash
# 端点
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. **流式响应模式**

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

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

---

## 🔍 常见问题排查

### 1. **构建失败**

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

### 2. **容器启动失败**

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

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

### 3. **API 调用 401/403 错误**

**原因**：API 密钥无效或过期

**解决**：
1. 检查 `Dockerfile` 中的密钥是否正确
2. 确认密钥是否有效且未过期
3. 重新构建镜像（`docker build ...`）

### 4. **图片下载失败**

**原因**：图片 URL 不可访问

**解决**：
1. 检查图片 URL 是否有效
2. 确认网络是否正常
3. 检查防火墙设置

### 5. **内存不足**

**现象**：容器频繁重启或 OOM

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

---

## 📊 监控与日志

### 查看实时日志

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

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

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

### 性能监控

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

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

---

## 🛠️ 本地开发模式

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

```bash
# 安装 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
```

---

## 📚 相关文档

- [LangGraph 官方文档](https://langchain-ai.github.io/langgraph/)
- [Coze API 文档](https://www.coze.cn/docs/developer_guides)
- [项目结构说明](./AGENTS.md)

---

## ⚠️ 注意事项

1. **API 密钥安全**：
   - ❌ 不要将密钥提交到代码仓库
   - ✅ 使用环境变量或密钥管理服务

2. **图片存储**：
   - 推荐使用对象存储（如阿里云 OSS）
   - 确保 URL 可公网访问

3. **并发限制**：
   - 单图片超时：120 秒
   - 建议并发数：10-50（根据服务器配置调整）

4. **数据隔离**：
   - 不同学科的缓存目录独立
   - 建议定期清理缓存

---

## 🆘 技术支持

如遇问题，请提供以下信息：
1. Docker 版本：`docker --version`
2. 容器日志：`docker logs math-correction`
3. 错误信息截图
4. 系统配置：`uname -a`

---

## 📄 许可证

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