UnisKB/deploy_artifacts/DEPLOY_CN.md

10 KiB
Raw Blame History

知识库问答助手与思维导图助手 Docker 部署说明

本文档用于在测试环境或生产环境部署已打包好的知识库问答助手、思维导图助手及统一网关。

1. 下载安装包

将开发机 /home/tlw/unis/deploy_artifacts 下的部署产物下载或拷贝到目标服务器,例如:

mkdir -p /data1/zywlw/tar
cd /data1/zywlw/tar

目标目录中建议包含以下文件:

docker-compose.unis.yml
start-all.sh
load-images.sh
download-models.sh
SHA256SUMS.txt
README_DEPLOY.md
DEPLOY_CN.md
unis-kb-latest.tar
unis-gateway-latest.tar
unis-mindmap-api-latest.tar
unis-mindmap-api-corex-latest.tar
unis-mindmap-api-cuda-latest.tar
unis-mindmap-web-latest.tar
mineru-models-modelscope.tar.gz

其中:

  • unis-kb-latest.tar:知识库问答助手镜像。
  • unis-gateway-latest.tar:统一入口网关镜像,对外提供 8989 端口。
  • unis-mindmap-api-latest.tar:思维导图助手 MinerU/API 默认镜像,通常对应天数/CoreX 版本。
  • unis-mindmap-api-corex-latest.tar:思维导图助手 MinerU/API 天数/CoreX GPU 版本。
  • unis-mindmap-api-cuda-latest.tar:思维导图助手 MinerU/API NVIDIA CUDA GPU 版本。
  • unis-mindmap-web-latest.tar:思维导图助手 Web 镜像,对外提供 9898 端口。
  • mineru-models-modelscope.tar.gz:思维导图助手模型包,可独立更新。

2. 检查资源完整性

进入部署目录后,先校验文件完整性:

cd /data1/zywlw/tar
sha256sum -c SHA256SUMS.txt

所有文件显示 成功 或 OK 后再继续部署。

如果提示某个文件校验失败,需要重新拷贝对应文件,不建议继续使用。

部署前还建议检查 Docker 存储空间:

df -h
docker system df

unis-mindmap-api-*-latest.tar 和 unis-kb-latest.tar 较大,镜像加载时还会产生临时写入。建议 Docker 数据盘至少预留 15G - 20G 可用空间。如果同时加载天数/CoreX 和 NVIDIA/CUDA 两个 API 镜像,需要预留更多空间。

如果加载镜像时出现 no space left on device,需要先清理旧镜像、旧容器或扩容 Docker 数据目录:

docker container prune -f
docker image prune -af
docker builder prune -af
docker system prune -af

清理前请确认没有仍需保留的业务容器或镜像。

3. 解压模型文件

思维导图助手的模型文件不打进 API 镜像,需要单独放到宿主机目录,并通过 MINERU_MODEL_DIR 挂载进容器。

推荐模型目录:

/data1/zywlw/mineru-models

首次部署或模型包有更新时执行:

mkdir -p /data1/zywlw/mineru-models
tar -xzf mineru-models-modelscope.tar.gz -C /data1/zywlw

解压后目录结构通常为:

/data1/zywlw/mineru-models/pipeline
/data1/zywlw/mineru-models/vlm

如果目标目录已有旧模型,可以覆盖更新:

tar -xzf mineru-models-modelscope.tar.gz -C /data1/zywlw --overwrite

模型包只在模型有变化时需要更新。普通代码镜像升级时,可以复用已有模型目录。

可检查关键模型文件是否存在:

find /data1/zywlw/mineru-models -name 'yolo_v8_ft.pt'
find /data1/zywlw/mineru-models -name 'doclayout_yolo_docstructbench_imgsz1280_2501.pt'
find /data1/zywlw/mineru-models -name 'model.safetensors'

4. 加载镜像

按目标服务器 GPU 类型选择加载方式。

天数/CoreX GPU 服务器执行:

cd /data1/zywlw/tar
chmod +x *.sh
GPU_FLAVOR=corex ./load-images.sh

NVIDIA CUDA GPU 服务器执行:

cd /data1/zywlw/tar
chmod +x *.sh
GPU_FLAVOR=cuda ./load-images.sh

GPU_FLAVOR 说明:

  • corex:加载天数/CoreX 版本 unis-mindmap-api-corex-latest.tar。
  • cuda:加载 NVIDIA CUDA 版本 unis-mindmap-api-cuda-latest.tar。

脚本会将选中的 API 镜像标记为 unis-mindmap-api:latest,因此后续 ./start-all.sh 不需要再区分 GPU 类型。

脚本会依次加载:

unis-kb:latest
unis-gateway:latest
unis-mindmap-web:latest
unis-mindmap-api:latest

加载完成后可以检查镜像:

docker images | grep -E 'unis-kb|unis-gateway|unis-mindmap'

如果服务器需要 sudo 才能执行 Docker 命令,可以使用:

sudo GPU_FLAVOR=corex ./load-images.sh
# 或
sudo GPU_FLAVOR=cuda ./load-images.sh

5. 启动服务

推荐启动命令如下:

cd /data1/zywlw/tar

MINDMAP_LLM_BASE_URL=http://10.100.53.199:9527/v1 \
MINDMAP_LLM_API_KEY=xxx \
MINDMAP_LLM_MODEL=gemma-4-26B \
MINERU_MODEL_DIR=/data1/zywlw/mineru-models \
KB_DATA_DIR=/data1/zywlw/maxkb \
MINDMAP_PUBLIC_URL=/mindmap/ \
MINERU_DOCKER_RUNTIME=nvidia \
MINERU_CUDA_VISIBLE_DEVICES=1 \
MINERU_GPU_MEMORY_UTILIZATION=0.75 \
./start-all.sh

启动后会创建并运行以下容器:

airag           知识库问答助手
mineru-api      思维导图解析 API
mindmap-web     思维导图 Web 页面
unis-gateway    统一访问网关

访问地址:

知识库后台:http://服务器IP:8989/admin/
知识库聊天:http://服务器IP:8989/chat/
思维导图,经网关访问:http://服务器IP:8989/mindmap/
思维导图,直接端口访问:http://服务器IP:9898/

6. 重要启动参数说明

MINDMAP_LLM_BASE_URL

智能整理、智能总结使用的大模型服务地址。

需要填写 OpenAI 兼容接口的 base URL,不要带 /chat/completions。

示例:

MINDMAP_LLM_BASE_URL=http://10.100.53.199:9527/v1

如果实际接口是:

http://10.100.53.199:9527/v1/chat/completions

则参数应配置为:

http://10.100.53.199:9527/v1

如果不配置该参数,思维导图助手的文件转换仍可使用,但智能整理/智能总结会提示未配置模型服务。

MINDMAP_LLM_API_KEY

大模型服务的 API Key。

如果本地模型服务不校验 Key,可以填任意非空值,例如:

MINDMAP_LLM_API_KEY=EMPTY

如果服务有鉴权要求,需要填写真实 Key。

MINDMAP_LLM_MODEL

智能整理、智能总结调用的模型名称,需要与大模型服务端提供的模型名一致。

示例:

MINDMAP_LLM_MODEL=gemma-4-26B

MINERU_MODEL_DIR

宿主机上的思维导图模型目录,会挂载到 mineru-api 容器内的 /models。

示例:

MINERU_MODEL_DIR=/data1/zywlw/mineru-models

该目录中应包含:

pipeline/
vlm/

建议放在数据盘,避免系统盘空间不足。

KB_DATA_DIR

知识库问答助手的数据持久化目录,会挂载到容器内 /opt/maxkb。

示例:

KB_DATA_DIR=/data1/zywlw/maxkb

该目录会保存知识库运行数据、数据库数据、上传文件等持久化内容。升级镜像时不要删除该目录。

MINDMAP_PUBLIC_URL

知识库问答助手中打开思维导图助手时使用的访问地址。

通过统一网关访问时使用:

MINDMAP_PUBLIC_URL=/mindmap/

此时访问链路为:

http://服务器IP:8989/mindmap/

如果希望知识库菜单直接打开思维导图独立端口,也可以配置为完整地址:

MINDMAP_PUBLIC_URL=http://服务器IP:9898/

MINERU_CUDA_VISIBLE_DEVICES

指定 mineru-api 容器使用哪张 GPU。

示例:

MINERU_CUDA_VISIBLE_DEVICES=1

表示使用宿主机上的 GPU 1。

如果 GPU 0 已被其它大模型服务占用,建议配置为 1 或其它空闲 GPU。

天数 GPU 服务器可使用:

ixsmi

查看显存占用。

NVIDIA GPU 服务器可使用:

nvidia-smi

查看显存占用。

MINERU_DOCKER_RUNTIME

指定 mineru-api 容器使用的 Docker runtime。

天数/CoreX 环境通常不需要设置该参数,默认使用 runc。

NVIDIA 环境如果 docker info 中可以看到 nvidia runtime,需要设置:

MINERU_DOCKER_RUNTIME=nvidia

如果不设置,宿主机 nvidia-smi 即使正常,容器内也可能看不到 libcuda.so.1,从而报:

CUDA not available
Device string must not be empty

MINERU_GPU_MEMORY_UTILIZATION

控制 VLLM/MinerU 使用 GPU 显存的比例,默认值为 0.5。

示例:

MINERU_GPU_MEMORY_UTILIZATION=0.4

当同一张 GPU 上还有其它服务,或启动时出现显存不足,可以调低该值。

如果是 8G 左右的 NVIDIA 显卡,建议从 0.75 开始尝试。该值太低时,VLLM 可能没有足够 KV cache 空间,并报:

No available memory for the cache blocks

MINDMAP_LLM_TIMEOUT

智能整理、智能总结请求大模型服务的超时时间,单位秒,默认 180。

文档较大或模型响应较慢时可以调大:

MINDMAP_LLM_TIMEOUT=300

7. 常用运维命令

查看容器状态:

docker ps

查看知识库助手日志:

docker logs -f airag

查看思维导图 API 日志:

docker logs -f mineru-api

查看网关日志:

docker logs -f unis-gateway

停止服务:

docker compose -f docker-compose.unis.yml down

重新启动:

./start-all.sh

升级镜像后强制重建容器:

docker compose -f docker-compose.unis.yml up -d --force-recreate

8. 常见问题

首页加载报 ERR_INCOMPLETE_CHUNKED_ENCODING

一般优先检查是否加载了最新镜像,或者浏览器缓存了旧的前端入口文件。

检查首页实际引用的 JS:

curl -s http://服务器IP:8989/admin/ | grep -o 'assets/admin-[^"]*\.js'
docker exec airag grep -o 'assets/admin-[^"]*\.js' /opt/maxkb-app/apps/static/admin/index.html

如果浏览器仍请求旧文件,尝试无痕窗口或清理浏览器缓存。

加载镜像时报 no space left on device

说明 Docker 数据目录空间不足。先检查:

df -h
docker system df

再按需清理旧镜像和构建缓存:

docker container prune -f
docker image prune -af
docker builder prune -af
docker system prune -af

思维导图提示缺少模型文件

检查模型目录挂载是否正确:

docker exec mineru-api ls -lah /models
docker exec mineru-api find /models -name 'yolo_v8_ft.pt'

如果找不到关键模型文件,需要重新解压或更新 mineru-models-modelscope.tar.gz。

智能整理提示未配置模型服务

检查启动时是否设置:

MINDMAP_LLM_BASE_URL
MINDMAP_LLM_API_KEY
MINDMAP_LLM_MODEL

其中 MINDMAP_LLM_BASE_URL 应为 /v1 级别地址,不要带 /chat/completions。