9002563e75
Some checks failed
Android CI / build (push) Has been cancelled
- pc-server/README.md 重写：从零开始的全流程部署说明 - 包含 conda 环境创建、MinerU/OCRmyPDF/Tesseract/Ghostscript 安装步骤 - main.py 配置项说明：哪些需要改、哪些自动检测 - 模型下载指令、国内网络镜像方案 - 常见故障排查表 - 根 README 简化部署章节，指向详细文档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
224 lines
6.2 KiB
Markdown
224 lines
6.2 KiB
Markdown
# 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 环境
|
||
|
||
```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 <tag> # 切换到一个兼容的版本
|
||
> ```
|
||
|
||
### 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
|
||
```
|
||
|
||
输出：
|
||
```
|
||
🚀 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
|
||
```
|