diff --git a/README.md b/README.md index 0130072..bb25e84 100644 --- a/README.md +++ b/README.md @@ -64,18 +64,9 @@ ## PC 服务器部署 -### 环境要求 +**详细部署指南**:[pc-server/README.md](pc-server/README.md) -| 组件 | 说明 | -|------|------| -| Conda 环境 | `MinerU`(Python 3.10, PyTorch 2.6, CUDA 12.4) | -| MinerU | v3.0.9(markdown 处理) | -| OCRmyPDF | v15.4.4(ocrpdf 处理) | -| Tesseract | 5.5.2 + chi_sim / eng 语言包 | -| Ghostscript | 10.07.1 | -| GPU | NVIDIA RTX 4060 8GB(推荐) | - -### 启动 +### 快速启动(环境已配好) ```bash conda activate MinerU @@ -85,6 +76,17 @@ python main.py 服务启动在 `http://0.0.0.0:2026`。 +### 环境一览 + +| 组件 | 版本 | 用途 | +|------|------|------| +| Python | 3.10 | conda 环境 `MinerU` | +| PyTorch | 2.6 + CUDA 12.4 | GPU 推理 | +| MinerU | git clone + pip install -e | markdown 处理 | +| OCRmyPDF | v15.4.4 | 可搜索双层 PDF | +| Tesseract | 5.5.2 + chi_sim/eng | OCR 引擎 | +| Ghostscript | 10.07.1 | PDF 后处理 | + ### API 端点 | 端点 | 方法 | 功能 | diff --git a/pc-server/README.md b/pc-server/README.md index f095aa7..2be0ec8 100644 --- a/pc-server/README.md +++ b/pc-server/README.md @@ -1,15 +1,223 @@ -# PC Server for FairScan real-time camera streaming -# -# This is a minimal test server that: -# - Receives WebSocket frames from the Android app -# - Displays them in a browser -# - Provides GET /health for connection testing +# FSBC PC Server — 部署指南 -## Quick Start +本文档写给**在全新机器上部署此项目的人**,从零开始搭建 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 环境 ```bash +conda create -n MinerU python=3.10 -y +conda activate MinerU +``` + +### 2.3 安装 PyTorch(CUDA 版) + +```bash +# 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 + +```bash +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: +> ```bash +> git tag | tail -20 # 查看可用版本 +> git checkout # 切换到一个兼容的版本 +> ``` + +### 2.5 安装 OCRmyPDF + +```bash +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 + +```bash +conda install -c conda-forge tesseract ghostscript -y +``` + +### 2.7 下载 Tesseract 语言包 + +```bash +# 中文简体 +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" +``` + +验证: +```bash +tesseract --list-langs +# 应输出:chi_sim, eng +``` + +### 2.8 安装 FSBC PC Server 依赖 + +```bash +cd pc-server pip install -r requirements.txt +``` + +### 2.9 下载 MinerU 模型 + +```bash +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?设置镜像: +> ```bash +> export HF_ENDPOINT=https://hf-mirror.com +> ``` +> 模型下载完成后,`main.py` 会自动设置 `HF_HUB_OFFLINE=1` 使用本地缓存。 + +--- + +## 3. 配置 main.py + +### 3.1 不需要改的部分 + +以下配置由 `main.py` **自动检测**,通常不需要手动修改: + +```python +# 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 环境,需要手动设置: + +```python +# 在 main.py 顶部添加: +os.environ["TESSDATA_PREFIX"] = "C:/path/to/your/tessdata" +os.environ["HF_HUB_OFFLINE"] = "1" # 如果模型已下载 +``` + +--- + +## 4. 启动服务 + +```bash +conda activate MinerU +cd pc-server python main.py ``` -Open http://localhost:2026 in a browser to see the stream. +输出: +``` +🚀 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 验证 + +```bash +# 健康检查 +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 +```