Fairscan_cyy/pc-server/README.md

FSBC PC Server — 部署指南

本文档写给在全新机器上部署此项目的人，从零开始搭建 PC 端处理服务。

---

1. 硬件要求

项目	最低	推荐
GPU	无（纯 CPU）	NVIDIA 8GB VRAM+
内存	8 GB	16 GB
磁盘	20 GB	50 GB（模型缓存 ~5GB）
系统	Windows / Linux / macOS	—

无 GPU 也可运行，但 MinerU 处理速度会显著下降（10~30 秒/页）。

---

2. 环境搭建（完整步骤）

2.1 安装 Miniconda

从 https://docs.conda.io/en/latest/miniconda.html 下载安装。安装后打开 Anaconda Prompt（Windows）或终端。

2.2 创建 conda 环境

conda create -n MinerU python=3.10 -y
conda activate MinerU

2.3 安装 PyTorch（CUDA 版）

# CUDA 12.4
pip install torch==2.6.0 torchvision==0.21.0 --index-url https://download.pytorch.org/whl/cu124

# 如果无 NVIDIA GPU，装 CPU 版：
# pip install torch==2.6.0 --index-url https://download.pytorch.org/whl/cpu

2.4 安装 MinerU

git clone https://github.com/opendatalab/MinerU.git
cd MinerU
# 注意：最新版需要 Python >= 3.11，但我们的环境是 3.10
# 使用兼容版本（例如 v3.0.9 tag 或对应 commit）
pip install -e .
cd ..

如果 pip install -e . 因 Python 版本不兼容失败，找一个兼容 3.10 的 tag：

git tag | tail -20   # 查看可用版本
git checkout <tag>   # 切换到一个兼容的版本

2.5 安装 OCRmyPDF

git clone https://github.com/ocrmypdf/OCRmyPDF.git ocRmypdf
cd ocRmypdf
# 最新版需要 Python >= 3.11，用 v15.4.4（支持 Python 3.10）
git checkout v15.4.4
pip install -e .
cd ..

2.6 安装 Tesseract + Ghostscript

conda install -c conda-forge tesseract ghostscript -y

2.7 下载 Tesseract 语言包

# 中文简体
curl -L -o "$CONDA_PREFIX/Library/share/tessdata/chi_sim.traineddata" \
  "https://github.com/tesseract-ocr/tessdata/raw/main/chi_sim.traineddata"

# 英语
curl -L -o "$CONDA_PREFIX/Library/share/tessdata/eng.traineddata" \
  "https://github.com/tesseract-ocr/tessdata/raw/main/eng.traineddata"

# 可选：日语、韩语
# curl -L -o "$CONDA_PREFIX/Library/share/tessdata/jpn.traineddata" \
#   "https://github.com/tesseract-ocr/tessdata/raw/main/jpn.traineddata"
# curl -L -o "$CONDA_PREFIX/Library/share/tessdata/kor.traineddata" \
#   "https://github.com/tesseract-ocr/tessdata/raw/main/kor.traineddata"

验证：

tesseract --list-langs
# 应输出：chi_sim, eng

2.8 安装 FSBC PC Server 依赖

cd pc-server
pip install -r requirements.txt

2.9 下载 MinerU 模型

python -c "
from huggingface_hub import snapshot_download
# Pipeline 模型（~2.5 GB）
snapshot_download('opendatalab/PDF-Extract-Kit-1.0')
# VLM 模型（~2 GB，可选，仅 VLM 后端需要）
# snapshot_download('opendatalab/MinerU2.5-2509-1.2B')
"

国内网络无法访问 huggingface.co？设置镜像：

export HF_ENDPOINT=https://hf-mirror.com

模型下载完成后，main.py 会自动设置 HF_HUB_OFFLINE=1 使用本地缓存。

---

3. 配置 main.py

3.1 不需要改的部分

以下配置由 main.py 自动检测，通常不需要手动修改：

# HF_HUB_OFFLINE=1 — 自动设置，强制使用本地模型缓存
# TESSDATA_PREFIX — 自动从 CONDA_PREFIX 推导路径

3.2 可能需要改的部分

配置项	位置	默认值	说明
服务端口	main.py 底部 port = 2026	2026	如果端口被占用，改这里
上传目录	UPLOAD_DIR	./uploads	上传的 PDF 存放位置
任务目录	TASKS_DIR	./tasks	处理产物存放位置
MinerU 后端	backend	"pipeline"	pipeline/vlm/hybrid
Markdown 解析方式	parse_method	"auto"	auto/txt/ocr
OCR 语言	lang 映射	ch→chi_sim	在 process_with_mineru 中修改映射

3.3 如果你不用 conda

如果你直接在系统 Python 中安装而非 conda 环境，需要手动设置：

# 在 main.py 顶部添加：
os.environ["TESSDATA_PREFIX"] = "C:/path/to/your/tessdata"
os.environ["HF_HUB_OFFLINE"] = "1"   # 如果模型已下载

---

4. 启动服务

conda activate MinerU
cd pc-server
python main.py

输出：

🚀 FSBC Server starting on http://0.0.0.0:2026
   Stream:   http://localhost:2026
   Dashboard: http://localhost:2026/dashboard
   Health:   http://localhost:2026/health

4.1 验证

# 健康检查
curl http://localhost:2026/health
# → {"status":"ok","name":"FSBC-PC","features":["stream","upload","tasks"]}

# 浏览器打开管理面板
# http://localhost:2026/dashboard

# 浏览器打开图传预览
# http://localhost:2026

---

5. 故障排查

问题	原因	解决
ModuleNotFoundError: mineru	MinerU 未安装	执行步骤 2.4
ModuleNotFoundError: ocrmypdf	OCRmyPDF 未安装	执行步骤 2.5
Could not find program 'tesseract'	Tesseract 未安装	执行步骤 2.6
Could not find program 'gs'	Ghostscript 未安装	执行步骤 2.6
MinerU SSL 错误连不上 huggingface.co	国内网络限制	设置 HF_ENDPOINT 镜像后重新下载模型
TESSDATA_PREFIX 路径不对	未用 conda 或路径不同	手动设置 os.environ["TESSDATA_PREFIX"]
WebSocket 404 / uvicorn 警告	缺少 websockets 包	pip install websockets
'Pdf' object has no attribute 'check'	pikepdf 版本过新	pip install "pikepdf>=8.7.1,<9"
OCR 结果不理想	语言包不对	确认 tesseract --list-langs 包含目标语言

---

6. 目录结构

pc-server/
├── main.py              # 主服务入口
├── requirements.txt     # Python 依赖
├── README.md            # 本文件
├── uploads/             # 上传的原始 PDF（自动创建）
└── tasks/               # 处理任务输出（自动创建）
    └── {taskId}/
        ├── {name}.md              # Markdown 产物
        ├── {name}_result.zip      # .md + images 打包
        └── {name}_ocr.pdf         # OCR 双层 PDF