10 KiB

Raw Blame History

项目部署指南

本文档帮助你将初中物理作业批改工作流导出到自己的服务器上运行。

📋 目录

前置要求
快速部署
详细配置
启动方式
常见问题

前置要求

1. 系统要求

操作系统: Linux / macOS / Windows (推荐 Linux)
Python版本: Python 3.10 或以上
内存: 建议 4GB 以上
磁盘空间: 建议 10GB 以上

2. 必需的第三方服务

本项目依赖以下第三方服务，必须提前准备好：

大语言模型 API

推荐: 火山引擎豆包大模型（本项目使用 doubao-seed-2-0-pro-260215）
替代方案:
- OpenAI API
- 其他兼容 OpenAI 格式的 API（如 DeepSeek、Kimi）
获取方式:
- 火山引擎: https://console.volcengine.com/ark
- OpenAI: https://platform.openai.com/

注意：

✅ 不需要配置对象存储（S3/TOS/OSS 等）
✅ 图片直接使用原始URL，不上传存储
✅ Word文档使用 requests 直接下载，不涉及对象存储

快速部署

步骤 1: 导出项目代码

方式一：从 Coze 平台下载

# 在 Coze Coding 平台点击"导出项目"按钮
# 下载后解压到服务器

方式二：使用 Git 克隆（如果有仓库地址）

git clone <your-repo-url>
cd <project-directory>

步骤 2: 安装依赖

# 创建虚拟环境（推荐）
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# 或 venv\Scripts\activate  # Windows

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

步骤 3: 配置环境变量

创建 .env 文件（或在服务器环境变量中配置）：

# 必需环境变量（只需配置大模型API）
export LLM_API_KEY="your-api-key-here"
export LLM_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
export LLM_MODEL_NAME="doubao-seed-2-0-pro-260215"

# 可选：日志级别
export LOG_LEVEL="INFO"

# 注意：不需要配置对象存储（S3/TOS等）

步骤 4: 启动服务

# 方式1: 使用启动脚本（推荐）
bash scripts/http_run.sh -p 8000

# 方式2: 直接运行
python src/main.py -m http -p 8000

服务启动后，访问：

健康检查: http://localhost:8000/health
API 文档: http://localhost:8000/docs（FastAPI 自动生成）

详细配置

1. 大语言模型配置

方式一：使用火山引擎豆包大模型（推荐）

# 环境变量
export LLM_API_KEY="your-ark-api-key"
export LLM_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
export LLM_MODEL_NAME="doubao-seed-2-0-pro-260215"

获取方式：

访问火山引擎控制台: https://console.volcengine.com/ark
创建推理接入点
获取 API Key

方式二：使用 OpenAI API

需要修改代码中的模型配置文件（config/*.json），将 model 字段改为 OpenAI 模型：

{
  "config": {
    "model": "gpt-4o",
    "temperature": 0.0
  }
}

环境变量：

export LLM_API_KEY="your-openai-api-key"
export LLM_BASE_URL="https://api.openai.com/v1"
export LLM_MODEL_NAME="gpt-4o"

2. 对象存储配置（已移除）

重要更新（2026-03-27）：

❌ 不需要配置对象存储
✅ 图片直接使用原始URL，不上传
✅ Word文档直接下载，不存储

架构优化原因：

AI模型足够强大，可以直接访问原始图片URL
使用相对坐标系统（0-1000），自动适配任意尺寸
减少存储成本和上传时间，处理速度更快

3. 修改代码适配自己的环境

修改 LLM 调用逻辑

项目使用了 coze-coding-dev-sdk，需要修改为直接调用 OpenAI API：

修改文件: src/graphs/nodes/doc_extract_node.py、src/graphs/nodes/recognize_and_correct_node.py

原代码（使用 coze-coding-dev-sdk）：

from coze_coding_dev_sdk import LLM

llm = LLM()
response = llm.invoke(messages)

修改为（直接使用 OpenAI SDK）：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("LLM_API_KEY"),
    base_url=os.getenv("LLM_BASE_URL")
)

response = client.chat.completions.create(
    model=os.getenv("LLM_MODEL_NAME"),
    messages=messages
)

修改对象存储逻辑（不需要）

已移除：2026-03-27 优化后，不再使用对象存储

图片直接使用原始URL
Word文档使用 requests 下载
无需修改任何存储相关代码

4. 缓存配置（可选）

项目使用文件缓存来存储解析结果，默认缓存目录为 /tmp/cache。

如需修改缓存目录：

export CACHE_DIR="/your/custom/cache/dir"

启动方式

1. HTTP 服务模式（推荐生产环境）

# 使用启动脚本
bash scripts/http_run.sh -p 8000

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

特点：

提供 REST API 接口
支持流式响应（SSE）
支持超时控制
支持任务取消

API 接口：

POST /run - 同步运行工作流
POST /stream_run - 流式运行工作流（SSE）
POST /cancel/{run_id} - 取消运行
GET /health - 健康检查
GET /graph_parameter - 查看工作流参数

2. 命令行模式（本地测试）

# 运行整个工作流
python src/main.py -m flow -i '{"student_homework": [...], "answer_doc_url": "..."}'

# 运行单个节点
python src/main.py -m node -n doc_extract -i '{"answer_doc_url": "..."}'

3. Docker 部署（推荐）

创建 Dockerfile：

FROM python:3.10-slim

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# 复制依赖文件
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制项目文件
COPY . .

# 暴露端口
EXPOSE 8000

# 启动命令
CMD ["python", "src/main.py", "-m", "http", "-p", "8000"]

构建和运行：

# 构建镜像
docker build -t homework-correction:v1 .

# 运行容器
docker run -d \
  --name homework-correction \
  -p 8000:8000 \
  -e LLM_API_KEY="your-api-key" \
  -e LLM_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" \
  -e LLM_MODEL_NAME="doubao-seed-2-0-pro-260215" \
  homework-correction:v1

4. 使用 Docker Compose

创建 docker-compose.yml：

version: '3.8'

services:
  homework-correction:
    build: .
    ports:
      - "8000:8000"
    environment:
      - LLM_API_KEY=${LLM_API_KEY}
      - LLM_BASE_URL=${LLM_BASE_URL}
      - LLM_MODEL_NAME=${LLM_MODEL_NAME}
    restart: unless-stopped
    volumes:
      - ./cache:/tmp/cache  # 持久化缓存

运行：

docker-compose up -d

常见问题

Q1: 如何验证环境变量是否正确配置？

# 检查环境变量
echo $LLM_API_KEY
echo $LLM_BASE_URL
echo $S3_ACCESS_KEY

# 或在代码中打印
python -c "import os; print(os.getenv('LLM_API_KEY'))"

Q2: 启动时报错 "ModuleNotFoundError: No module named 'xxx'"

解决方案：

# 确保在虚拟环境中
source venv/bin/activate

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

Q3: LLM 调用失败，报错 "API key not found"

原因: 环境变量未正确设置