10 KiB
知识库问答助手与思维导图助手 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。