docs(deploy): §5c MinerU CPU 裸部署 + §5d embedding 裸部署固化(176 实测)
- MinerU: 175 minerupy312 conda env 整体 tar 搬运到 176 /srv/plantai/mineru-cpu(8.1G), 模型缓存 /srv/plantai/mineru-models(3.6G);四个陷阱: tar --numeric-owner(非 --numeric-ids)、 shebang 重写、modelscope 绝对路径软链断链、stdin-EOF 关闭监视器(< /dev/null) - 冒烟: 22 页英文 PDF 67s 出 74KB markdown, 与 175 GPU 基线 md5 逐字节一致 - prod.env 五项 env 已加(176, 待 methodology 代码修复后随 install 包重发布生效) - embedding: Ollama 裸服务离线布局/bge-m3 位置/vstore env/CPU 性能实测(短句 4.1s, 780 字 1.0s) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Claude Fable 5
+115
-1
@@ -19,7 +19,7 @@
|
||||
| 打包产物目录 | `tooling/build/<VERSION>/install/`（VERSION 默认读 `tooling/tooling.env`，当前 2.0.0） |
|
||||
| 已就绪辅助脚本 | `deploy/ollama_restart.sh`（本地嵌入模型拉起）、`vstore/vstore_restart.sh`（路径自推导重启）已入包 |
|
||||
| nginx 代理模板 | `deploy/nginx/plantai.conf`（SSE 长连接 + 大文件上传适配，随安装包发布到 `install/nginx/`） |
|
||||
| 176 已部署 | **2026-09-09 按本标准完成 176 部署**（隧道B 接入，`/srv/plantai` 布局：install + qa-db + data + docgen；nginx 80 唯一入口；无 GPU、无 docker、无生信） |
|
||||
| 176 已部署 | **2026-09-09 按本标准完成 176 部署**（隧道B 接入，`/srv/plantai` 布局：install + qa-db + data + docgen；nginx 80 唯一入口；无 GPU、无 docker、无生信）；**2026-09-10 增补 MinerU CPU 裸部署（§5c）与 embedding 裸部署固化（§5d）** |
|
||||
| QA 数据库裸进程 | **systemd 裸进程为最终部署标准**（无 docker）：qdrant v1.18.3 + neo4j 5.15.0-community，全部 127.0.0.1；**端口 27433/27434 + 19888/19885**；数据在 `<部署根>/qa-db/`；安装脚本 `install/qa-db/install_qdrant.sh`、`install_neo4j.sh`（均免编译：官方静态二进制/tarball，支持本地 bin/ 离线分发）；175 上 docker 容器（27333/19788）为其他项目共享服务、不动 |
|
||||
|
||||
## 1. 编译阶段（构建机）
|
||||
@@ -208,6 +208,120 @@ nginx 模板关键适配（勿删勿改，详见 `deploy/nginx/plantai.conf` 注
|
||||
- **大文件上传**（上传无大小限制；生信基因组数百 MB）：`client_max_body_size 0` + `proxy_request_buffering off` + `proxy_send_timeout 600s`。
|
||||
- 静态资源由 BFF 自身托管（ui/dist），nginx 只做反代，不自管静态目录。
|
||||
|
||||
### 5c. MinerU CPU 裸部署（目标机，无 GPU/无 docker/无 conda）
|
||||
|
||||
> MinerU 以**裸服务**形态部署：构建机 conda env 目录整体搬运（env 内 bin/python 自包含，部署后不依赖 conda 二进制），
|
||||
> 目标机仅需一个实体目录 + 一份模型缓存 + 一个 mineru.json 配置。2026-09-10 已在 176 全量验证（见下方冒烟）。
|
||||
|
||||
**形态与位置约定**：
|
||||
- 环境目录：`/srv/plantai/mineru-cpu/`（175 `minerupy312` conda env 搬运，8.1G，含 torch 2.11.0+cu128 与 mineru 3.1.13）；`MINERU_CMD=/srv/plantai/mineru-cpu/bin/mineru`。
|
||||
- 模型缓存：`/srv/plantai/mineru-models/`（175 `~/.cache/modelscope` 同步，3.6G；PDF-Extract-Kit-1.0 与 MinerU2.5-Pro-2604-1.2B 两仓库）。
|
||||
- 模型本地化配置：`~/mineru.json`（或 `MINERU_TOOLS_CONFIG_JSON` 指向任意路径），`models-dir` 把 pipeline/vlm 两个 repo 映射到实体路径——mineru 3.1.13 的 `MINERU_MODEL_SOURCE=local` 依赖此映射，缺失时报 `'NoneType' object has no attribute 'get'`。
|
||||
|
||||
**搬运步骤（175 构建机 → 176 目标机，P2P 内网直连）**：
|
||||
|
||||
```bash
|
||||
# 1) 打包（注意 GNU tar 1.35 用 --numeric-owner 而非 --numeric-ids）
|
||||
tar --numeric-owner -C /home/xzq/miniconda3/envs -cf /home/xzq/minerupy312-env.tar minerupy312
|
||||
|
||||
# 2) 传输（rsync 模板见 §5.1 内网直连；模型缓存与 env 包可并行传）
|
||||
rsync -a --numeric-ids -e 'ssh -i ~/.ssh/id_ed25519_p2p -p 26518 -o BatchMode=yes' \
|
||||
/home/xzq/minerupy312-env.tar xzq@192.168.0.176:/srv/plantai/minerupy312-env.tar
|
||||
rsync -a --numeric-ids -e 'ssh -i ~/.ssh/id_ed25519_p2p -p 26518 -o BatchMode=yes' \
|
||||
/home/xzq/.cache/modelscope/ xzq@192.168.0.176:/srv/plantai/mineru-models/
|
||||
|
||||
# 3) 解包（目标机；--strip-components=1 去掉 env 顶层目录名）
|
||||
mkdir -p /srv/plantai/mineru-cpu
|
||||
tar -xf /srv/plantai/minerupy312-env.tar -C /srv/plantai/mineru-cpu --strip-components=1
|
||||
|
||||
# 4) 重写 shebang（env 内 bin/* 的 shebang 是构建机绝对路径，不改则 bin/mineru 直接调用失败）
|
||||
sed -i 's|#!/home/xzq/miniconda3/envs/minerupy312/bin/python|#!/srv/plantai/mineru-cpu/bin/python|' /srv/plantai/mineru-cpu/bin/*
|
||||
```
|
||||
|
||||
**modelscope 缓存软链陷阱（必做）**：modelscope 缓存顶层是真名→转义名的**绝对路径软链**
|
||||
（如 `PDF-Extract-Kit-1.0 -> /home/xzq/.cache/modelscope/hub/models/OpenDataLab/PDF-Extract-Kit-1___0`）。
|
||||
rsync 原样保留后软链指向 175 旧路径，在目标机是断链。目标机上需删除软链、把转义名实体目录复制回真名：
|
||||
|
||||
```bash
|
||||
cd /srv/plantai/mineru-models/hub/models/OpenDataLab
|
||||
rm PDF-Extract-Kit-1.0 MinerU2.5-Pro-2604-1.2B
|
||||
cp -a PDF-Extract-Kit-1___0 PDF-Extract-Kit-1.0
|
||||
cp -a MinerU2___5-Pro-2604-1___2B MinerU2.5-Pro-2604-1.2B
|
||||
```
|
||||
|
||||
**目标机 mineru.json**（运行用户家目录；或放部署根并用 `MINERU_TOOLS_CONFIG_JSON` 显式指向）：
|
||||
|
||||
```json
|
||||
{"models-dir": {
|
||||
"pipeline": "/srv/plantai/mineru-models/hub/models/OpenDataLab/PDF-Extract-Kit-1.0",
|
||||
"vlm": "/srv/plantai/mineru-models/hub/models/OpenDataLab/MinerU2.5-Pro-2604-1.2B"}}
|
||||
```
|
||||
|
||||
**prod.env 增量键（methodology/legacy-rag 的 env/prod.env，只加键值不改其他）**：
|
||||
|
||||
```bash
|
||||
MINERU_CMD=/srv/plantai/mineru-cpu/bin/mineru
|
||||
MINERU_DEVICE_MODE=cpu
|
||||
MINERU_MODEL_SOURCE=local
|
||||
MINERU_TOOLS_CONFIG_JSON=/home/xzq/mineru.json
|
||||
METHODOLOGY_MINERU_GPU_PREFLIGHT=0
|
||||
METHODOLOGY_MINERU_RUNTIME_MODE=single
|
||||
V15_MINERU_BACKEND=pipeline
|
||||
```
|
||||
|
||||
> **生效时序**：当前 methodology 代码已支持 `MINERU_CMD`/`METHODOLOGY_MINERU_GPU_PREFLIGHT`/`METHODOLOGY_MINERU_RUNTIME_MODE`/`V15_MINERU_BACKEND`，
|
||||
> 但还不显式传 `MINERU_DEVICE_MODE` 与 `MINERU_MODEL_SOURCE`/`MINERU_TOOLS_CONFIG_JSON`（修复中会加）。因此今天先以冒烟脚本 env 方式验证；
|
||||
> prod.env 的键先加上，待代码修复后随 install 包重发布时生效。175 GPU 机不设这些 env，行为不变（get_device() 自动探测 cuda）。
|
||||
|
||||
**CPU 冒烟（关键验收，176 实测通过）**：
|
||||
|
||||
```bash
|
||||
env MINERU_DEVICE_MODE=cpu MINERU_MODEL_SOURCE=local \
|
||||
MINERU_TOOLS_CONFIG_JSON=/home/xzq/mineru.json \
|
||||
MODELSCOPE_CACHE=/srv/plantai/mineru-models CUDA_VISIBLE_DEVICES= \
|
||||
/srv/plantai/mineru-cpu/bin/mineru -p <测试PDF> -o /tmp/mineru-smoke -b pipeline -l ch < /dev/null
|
||||
# 断言：输出目录出现 *.md 且内容非空
|
||||
find /tmp/mineru-smoke -name '*.md' -exec head -5 {} \;
|
||||
```
|
||||
|
||||
- **stdin-EOF 陷阱**：mineru 3.1.13 CLI 内置本地 API 子进程带 `MINERU_API_SHUTDOWN_ON_STDIN_EOF=1` 关闭监视器；
|
||||
后台冒烟若不显式 `< /dev/null`（或经 nohup/setsid 使 stdin 立即 EOF），服务会在任务中途主动 shutdown，报「Async task failed」且错误为空。
|
||||
methodology 以 subprocess 调 MINERU_CMD 时同样要保证 stdin 非管道 EOF（修复代码会显式传 `MINERU_DEVICE_MODE` 并规避此问题）。
|
||||
- 实测数据（176，AMD EPYC 7542 128 核 / 251G 内存）：22 页英文 PDF 全程 67s（模型初始化约 4s）；
|
||||
输出 markdown 74KB 与 175 GPU 机基线**逐字节一致（md5 相同）**。CPU 比 GPU 慢数倍属预期（layout/OCR 全走 CPU 推理）。
|
||||
- `mineru --version` 输出 `mineru, version 3.1.13`；torch 2.11.0+cu128 在无 GPU 机 import 正常（CPU 路径），无需重装 CPU torch。
|
||||
- **备用路径（整目录搬运冒烟失败时才走）**：目标机 `python3 -m venv /opt/mineru-cpu-venv` 裸装（CPU torch + mineru 3.1.13），
|
||||
模型缓存与 mineru.json 同上。本次整目录搬运一次通过，未启用。
|
||||
|
||||
### 5d. 本地向量库 embedding 模型部署（Ollama 裸服务，离线）
|
||||
|
||||
> 176 上 embedding 已裸部署（实体进程，非 docker）：Ollama 官方二进制 + bge-m3:567m，vstore 已指向它。本节为文档固化。
|
||||
|
||||
**离线布局（Ollama 三件套）**：
|
||||
- `/opt/ollama/bin/ollama`（实体二进制，38M）
|
||||
- `/usr/local/bin/ollama -> /opt/ollama/bin/ollama`（symlink，进 PATH）
|
||||
- `/opt/ollama/lib/ollama/`（llama-server + libggml-cpu-*.so runner + cuda_v12/cuda_v13；缺失时报 `llama-server binary not found`）
|
||||
|
||||
**bge-m3 模型位置**：`~/.ollama/models/`（manifests + blobs，1.1G；bge-m3:567m = 1 个 manifest + 对应 blob）。
|
||||
|
||||
**vstore env 指向**（vstore/.env，与 §5.1 一致）：
|
||||
|
||||
```bash
|
||||
VSTORE_EMBED_URL=http://127.0.0.1:11434
|
||||
VSTORE_EMBED_MODEL=bge-m3:567m
|
||||
```
|
||||
|
||||
**服务进程**：`/usr/local/bin/ollama serve` 常驻实体进程（pgrep -af ollama）；拉起脚本 `install/ollama_restart.sh`。
|
||||
|
||||
**离线安装法**（目标机连不上 ollama.com/registry.ollama.ai 时唯一路径）：
|
||||
1. 源机把 `/opt/ollama/` 整目录与 `/usr/local/bin/ollama` symlink 打包（tar --numeric-owner）；
|
||||
2. 模型目录 `~/.ollama/models/` 一并 tar（注意属主：目标机同 UID 用户解包，否则 chown）；
|
||||
3. 目标机解包到相同路径，`ollama serve` 启动后 `ollama list` 应见 bge-m3:567m（否则 manifests 与 blobs 不匹配）。
|
||||
|
||||
**性能事实（176 无 GPU，CPU 推理）**：
|
||||
- 短句（12 字）单次嵌入 4.1s；780 字长文本 1.0s（2026-09-10 实测，模型常驻后）；
|
||||
- 单篇文档全量嵌入（多 chunk 累计）约 52s 属历史实测值——功能正常，纯性能差距，无 GPU 机器属预期。
|
||||
|
||||
## 6. 部署后完整质检（agent 逐条执行并记录结果，全过才算部署成功）
|
||||
|
||||
```bash
|
||||
|
||||
Reference in New Issue
Block a user