pdf_converter_v2 启动说明

使用脚本启动（推荐）

使用 start_mineru_in_container.sh 和 start_api_in_container.sh 时，先起 MinerU，再起 pdf_converter_v2。

单卡

1. 启动 MinerU API（端口 5282）

在 Clerk2.5 项目根目录 执行：

# 若项目不在 /root/work/Clerk2.5，可先设置（脚本也会按路径自动识别）：
# export CLERK_ROOT=/你的/Clerk2.5/路径

# NPU：默认 npu；未装 CANN 可先 export MINERU_DEVICE_MODE=cpu
export MINERU_DEVICE_MODE=npu
export MINERU_PORT=5282

sh pdf_converter_v2/scripts/start_mineru_in_container.sh

或从 pdf_converter_v2 目录执行：sh scripts/start_mineru_in_container.sh

2. 启动 pdf_converter_v2 API（端口 4214）

在同一台机、Clerk2.5 项目根目录 执行：

export API_URL=http://127.0.0.1:5282
sh pdf_converter_v2/scripts/start_api_in_container.sh

或从 pdf_converter_v2 目录：sh scripts/start_api_in_container.sh

脚本会后台运行并写日志，输出类似：

MinerU：已后台启动 MinerU API，端口 5282，日志默认 $CLERK_ROOT/logs/mineru-api.log
pdf_converter_v2：已后台启动 pdf_converter_v2 API，端口 4214，日志默认 $CLERK_ROOT/logs/pdf-converter-v2-api.log

查看日志： tail -f $CLERK_ROOT/logs/mineru-api.log 或 tail -f $CLERK_ROOT/logs/pdf-converter-v2-api.log

多卡模型缓存： 脚本会设置 MODELSCOPE_CACHE=$CLERK_ROOT/.cache/modelscope，多个 MinerU 实例共用同一缓存，避免每卡重复下载。若需自定义缓存目录，可设置 export MODELSCOPE_CACHE=/你的路径 后再执行脚本。

一、单卡（一张 NPU/GPU，不用脚本时）

1. 先启动 MinerU API（提供 PDF→Markdown 转换）

在项目根目录（Clerk2.5）执行：

# NPU 环境：会尝试加载 CANN；若未装 CANN 可先 export MINERU_DEVICE_MODE=cpu
export MINERU_DEVICE_MODE=npu    # 或 npu:0
export MINERU_PORT=5282
sh pdf_converter_v2/scripts/start_mineru_in_container.sh

或使用虚拟环境直接起：

cd /path/to/Clerk2.5
export PYTHONPATH=/path/to/Clerk2.5
python3 -m uvicorn mineru.cli.fast_api:app --host 0.0.0.0 --port 5282

2. 再启动 pdf_converter_v2 API（对外提供 /convert 等接口）

cd /path/to/Clerk2.5
export PYTHONPATH=/path/to/Clerk2.5
export API_URL=http://127.0.0.1:5282
python3 pdf_converter_v2/api_server.py --host 0.0.0.0 --port 4214

或使用脚本后台启动：

sh pdf_converter_v2/scripts/start_api_in_container.sh

验证：

MinerU：curl http://127.0.0.1:5282/health 或访问 /docs
pdf_converter_v2：curl http://127.0.0.1:4214/docs

多卡（一键脚本，推荐）

使用 start_multi_card.sh 一次启动多张卡的 MinerU + 一个 pdf_converter_v2：

cd /path/to/Clerk2.5

# 启动 2 卡（默认）：MinerU 端口 5282、5283，再起 pdf_converter_v2 并设 API_URL / PADDLE_OCR_DEVICES
bash pdf_converter_v2/scripts/start_multi_card.sh

# 启动 3 卡
bash pdf_converter_v2/scripts/start_multi_card.sh 3

# 或通过环境变量
export MINERU_NUM_CARDS=2
bash pdf_converter_v2/scripts/start_multi_card.sh

脚本会依次：起 N 个 MinerU（npu:0→5282, npu:1→5283, …）、等待端口就绪、设 API_URL 与 PADDLE_OCR_DEVICES、再起 pdf_converter_v2。
可选环境变量：MINERU_NUM_CARDS（卡数）、MINERU_BASE_PORT（起始端口，默认 5282）、MINERU_WAIT_READY（等待端口秒数，默认 120）。

多卡（手动分终端起）

1. 每个卡起一个 MinerU（不同端口）

终端 1：

cd /path/to/Clerk2.5
export MINERU_DEVICE_MODE=npu:0
export MINERU_PORT=5282
sh pdf_converter_v2/scripts/start_mineru_in_container.sh

终端 2：

cd /path/to/Clerk2.5
export MINERU_DEVICE_MODE=npu:1
export MINERU_PORT=5283
sh pdf_converter_v2/scripts/start_mineru_in_container.sh

（脚本会按端口自动使用不同日志和 PID 文件：mineru-api-5282.log / mineru-api-5283.log。）

2. 起 pdf_converter_v2，指向多 MinerU

cd /path/to/Clerk2.5
export API_URL=http://127.0.0.1:5282,http://127.0.0.1:5283
# 若 Paddle 也多卡：export PADDLE_OCR_DEVICES=npu:0,npu:1
sh pdf_converter_v2/scripts/start_api_in_container.sh

二、多卡（单任务用满所有卡，不用脚本时）

需要：多个 MinerU API 实例（每卡一个进程、不同端口），pdf_converter_v2 用 API_URL 逗号分隔；Paddle 多卡用 PADDLE_OCR_DEVICES。

1. 启动多个 MinerU API（每卡一个）

示例：2 张卡，端口 5282、5283。

终端 1（卡 0）：

cd /path/to/Clerk2.5
export PYTHONPATH=/path/to/Clerk2.5
export MINERU_DEVICE_MODE=npu:0
export MINERU_PORT=5282
# NPU 需先加载 CANN：source /usr/local/Ascend/ascend-toolkit/set_env.sh
sh pdf_converter_v2/scripts/start_mineru_in_container.sh

终端 2（卡 1）：

cd /path/to/Clerk2.5
export PYTHONPATH=/path/to/Clerk2.5
export MINERU_DEVICE_MODE=npu:1
export MINERU_PORT=5283
sh pdf_converter_v2/scripts/start_mineru_in_container.sh

（更多卡同理：npu:2 + MINERU_PORT=5284 等。）

2. 启动 pdf_converter_v2（多 MinerU 地址 + 可选 Paddle 多卡）

cd /path/to/Clerk2.5
export PYTHONPATH=/path/to/Clerk2.5
# 多 MinerU：逗号分隔，单次 PDF 会按页拆分并行发往各实例
export API_URL=http://127.0.0.1:5282,http://127.0.0.1:5283
# 若用 Paddle 多卡（备用/工况解析）：单次 PDF 会按页拆分并行用各卡
export PADDLE_OCR_DEVICES=npu:0,npu:1
python3 pdf_converter_v2/api_server.py --host 0.0.0.0 --port 4214

验证： 发一个多页 PDF 到 /convert，看日志应出现「拆成 N 段并行」之类输出。

三、用 systemd 管理（生产环境）

1. 安装并改配置

sudo cp service/pdf-converter-v2.service /etc/systemd/system/
# 按本机路径修改
sudo sed -i 's|/mnt/win_d/Clerk2.5|/你的/Clerk2.5/路径|g' /etc/systemd/system/pdf-converter-v2.service
# 若用虚拟环境，改 ExecStart 为：/path/to/Clerk2.5/.venv_paddleocr/bin/python3 /path/to/Clerk2.5/pdf_converter_v2/api_server.py ...

多卡时 在 service 里加环境变量（或建 override）：

Environment="API_URL=http://127.0.0.1:5282,http://127.0.0.1:5283"
Environment="PADDLE_OCR_DEVICES=npu:0,npu:1"

2. 启停、开机自启、看日志

sudo systemctl daemon-reload
sudo systemctl start pdf-converter-v2
sudo systemctl enable pdf-converter-v2   # 开机自启
sudo systemctl status pdf-converter-v2
sudo journalctl -u pdf-converter-v2 -f   # 看日志

注意： MinerU API 需单独起（多个卡就起多个实例，见第二节），systemd 只管理 pdf_converter_v2 服务。

四、常见问题

sklearn / paddlex：`cannot allocate memory in static TLS block`

报错类似：

ImportError: .../scikit_learn.libs/libgomp-d22c30c5.so.1.0.0: cannot allocate memory in static TLS block

原因是 Paddle/sklearn 等库加载顺序导致 libgomp 的 static TLS 空间不足。用脚本启动 MinerU 时，start_mineru_in_container.sh 会自动设置 LD_PRELOAD 预加载 libgomp，一般可避免此问题。

若未用脚本（例如直接 python3 -m uvicorn ... 或 systemd），需在启动前设置：

# 任选其一存在即可（路径按你本机 scikit-learn 安装位置调整）
export LD_PRELOAD=/usr/local/lib/python3.10/dist-packages/scikit_learn.libs/libgomp-d22c30c5.so.1.0.0
# 或系统 libgomp
export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libgomp.so.1
python3 -m uvicorn mineru.cli.fast_api:app --host 0.0.0.0 --port 5282

systemd 服务可在 Environment= 里加上上述 LD_PRELOAD。

五、环境变量速查

作用	变量	示例
MinerU 单地址	`API_URL`	`http://127.0.0.1:5282`
MinerU 多卡	`API_URL`（逗号分隔）	`http://127.0.0.1:5282,http://127.0.0.1:5283`
Paddle 单卡	`PADDLE_OCR_DEVICE`	`npu:0`
Paddle 多卡	`PADDLE_OCR_DEVICES`	`npu:0,npu:1`
MinerU 设备	`MINERU_DEVICE_MODE`	`npu` / `npu:0` / `npu:1`
本服务端口	命令行 `--port` 或脚本	默认 4214
MinerU 端口	`MINERU_PORT`	默认 5282

更多见 README.md 中「环境变量配置」与「多 NPU 配置」小节。

README_STARTUP.md 8.4 KB Historie Surový