# 知识库问答助手与思维导图助手 Docker 部署说明 本文档用于在测试环境或生产环境部署已打包好的知识库问答助手、思维导图助手及统一网关。 ## 1. 下载安装包 将开发机 `/home/tlw/unis/deploy_artifacts` 下的部署产物下载或拷贝到目标服务器,例如: ```bash mkdir -p /data1/zywlw/tar cd /data1/zywlw/tar ``` 目标目录中建议包含以下文件: ```text 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. 检查资源完整性 进入部署目录后,先校验文件完整性: ```bash cd /data1/zywlw/tar sha256sum -c SHA256SUMS.txt ``` 所有文件显示 `成功` 或 `OK` 后再继续部署。 如果提示某个文件校验失败,需要重新拷贝对应文件,不建议继续使用。 部署前还建议检查 Docker 存储空间: ```bash 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 数据目录: ```bash docker container prune -f docker image prune -af docker builder prune -af docker system prune -af ``` 清理前请确认没有仍需保留的业务容器或镜像。 ## 3. 解压模型文件 思维导图助手的模型文件不打进 API 镜像,需要单独放到宿主机目录,并通过 `MINERU_MODEL_DIR` 挂载进容器。 推荐模型目录: ```bash /data1/zywlw/mineru-models ``` 首次部署或模型包有更新时执行: ```bash mkdir -p /data1/zywlw/mineru-models tar -xzf mineru-models-modelscope.tar.gz -C /data1/zywlw ``` 解压后目录结构通常为: ```text /data1/zywlw/mineru-models/pipeline /data1/zywlw/mineru-models/vlm ``` 如果目标目录已有旧模型,可以覆盖更新: ```bash tar -xzf mineru-models-modelscope.tar.gz -C /data1/zywlw --overwrite ``` 模型包只在模型有变化时需要更新。普通代码镜像升级时,可以复用已有模型目录。 可检查关键模型文件是否存在: ```bash 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 服务器执行: ```bash cd /data1/zywlw/tar chmod +x *.sh GPU_FLAVOR=corex ./load-images.sh ``` NVIDIA CUDA GPU 服务器执行: ```bash 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 类型。 脚本会依次加载: ```text unis-kb:latest unis-gateway:latest unis-mindmap-web:latest unis-mindmap-api:latest ``` 加载完成后可以检查镜像: ```bash docker images | grep -E 'unis-kb|unis-gateway|unis-mindmap' ``` 如果服务器需要 `sudo` 才能执行 Docker 命令,可以使用: ```bash sudo GPU_FLAVOR=corex ./load-images.sh # 或 sudo GPU_FLAVOR=cuda ./load-images.sh ``` ## 5. 启动服务 推荐启动命令如下: ```bash 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 ``` 启动后会创建并运行以下容器: ```text airag 知识库问答助手 mineru-api 思维导图解析 API mindmap-web 思维导图 Web 页面 unis-gateway 统一访问网关 ``` 访问地址: ```text 知识库后台: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`。 示例: ```bash MINDMAP_LLM_BASE_URL=http://10.100.53.199:9527/v1 ``` 如果实际接口是: ```text http://10.100.53.199:9527/v1/chat/completions ``` 则参数应配置为: ```text http://10.100.53.199:9527/v1 ``` 如果不配置该参数,思维导图助手的文件转换仍可使用,但智能整理/智能总结会提示未配置模型服务。 ### MINDMAP_LLM_API_KEY 大模型服务的 API Key。 如果本地模型服务不校验 Key,可以填任意非空值,例如: ```bash MINDMAP_LLM_API_KEY=EMPTY ``` 如果服务有鉴权要求,需要填写真实 Key。 ### MINDMAP_LLM_MODEL 智能整理、智能总结调用的模型名称,需要与大模型服务端提供的模型名一致。 示例: ```bash MINDMAP_LLM_MODEL=gemma-4-26B ``` ### MINERU_MODEL_DIR 宿主机上的思维导图模型目录,会挂载到 `mineru-api` 容器内的 `/models`。 示例: ```bash MINERU_MODEL_DIR=/data1/zywlw/mineru-models ``` 该目录中应包含: ```text pipeline/ vlm/ ``` 建议放在数据盘,避免系统盘空间不足。 ### KB_DATA_DIR 知识库问答助手的数据持久化目录,会挂载到容器内 `/opt/maxkb`。 示例: ```bash KB_DATA_DIR=/data1/zywlw/maxkb ``` 该目录会保存知识库运行数据、数据库数据、上传文件等持久化内容。升级镜像时不要删除该目录。 ### MINDMAP_PUBLIC_URL 知识库问答助手中打开思维导图助手时使用的访问地址。 通过统一网关访问时使用: ```bash MINDMAP_PUBLIC_URL=/mindmap/ ``` 此时访问链路为: ```text http://服务器IP:8989/mindmap/ ``` 如果希望知识库菜单直接打开思维导图独立端口,也可以配置为完整地址: ```bash MINDMAP_PUBLIC_URL=http://服务器IP:9898/ ``` ### MINERU_CUDA_VISIBLE_DEVICES 指定 `mineru-api` 容器使用哪张 GPU。 示例: ```bash MINERU_CUDA_VISIBLE_DEVICES=1 ``` 表示使用宿主机上的 GPU 1。 如果 GPU 0 已被其它大模型服务占用,建议配置为 `1` 或其它空闲 GPU。 天数 GPU 服务器可使用: ```bash ixsmi ``` 查看显存占用。 NVIDIA GPU 服务器可使用: ```bash nvidia-smi ``` 查看显存占用。 ### MINERU_DOCKER_RUNTIME 指定 `mineru-api` 容器使用的 Docker runtime。 天数/CoreX 环境通常不需要设置该参数,默认使用 `runc`。 NVIDIA 环境如果 `docker info` 中可以看到 `nvidia` runtime,需要设置: ```bash MINERU_DOCKER_RUNTIME=nvidia ``` 如果不设置,宿主机 `nvidia-smi` 即使正常,容器内也可能看不到 `libcuda.so.1`,从而报: ```text CUDA not available Device string must not be empty ``` ### MINERU_GPU_MEMORY_UTILIZATION 控制 VLLM/MinerU 使用 GPU 显存的比例,默认值为 `0.5`。 示例: ```bash MINERU_GPU_MEMORY_UTILIZATION=0.4 ``` 当同一张 GPU 上还有其它服务,或启动时出现显存不足,可以调低该值。 如果是 8G 左右的 NVIDIA 显卡,建议从 `0.75` 开始尝试。该值太低时,VLLM 可能没有足够 KV cache 空间,并报: ```text No available memory for the cache blocks ``` ### MINDMAP_LLM_TIMEOUT 智能整理、智能总结请求大模型服务的超时时间,单位秒,默认 `180`。 文档较大或模型响应较慢时可以调大: ```bash MINDMAP_LLM_TIMEOUT=300 ``` ## 7. 常用运维命令 查看容器状态: ```bash docker ps ``` 查看知识库助手日志: ```bash docker logs -f airag ``` 查看思维导图 API 日志: ```bash docker logs -f mineru-api ``` 查看网关日志: ```bash docker logs -f unis-gateway ``` 停止服务: ```bash docker compose -f docker-compose.unis.yml down ``` 重新启动: ```bash ./start-all.sh ``` 升级镜像后强制重建容器: ```bash docker compose -f docker-compose.unis.yml up -d --force-recreate ``` ## 8. 常见问题 ### 首页加载报 `ERR_INCOMPLETE_CHUNKED_ENCODING` 一般优先检查是否加载了最新镜像,或者浏览器缓存了旧的前端入口文件。 检查首页实际引用的 JS: ```bash 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 数据目录空间不足。先检查: ```bash df -h docker system df ``` 再按需清理旧镜像和构建缓存: ```bash docker container prune -f docker image prune -af docker builder prune -af docker system prune -af ``` ### 思维导图提示缺少模型文件 检查模型目录挂载是否正确: ```bash docker exec mineru-api ls -lah /models docker exec mineru-api find /models -name 'yolo_v8_ft.pt' ``` 如果找不到关键模型文件,需要重新解压或更新 `mineru-models-modelscope.tar.gz`。 ### 智能整理提示未配置模型服务 检查启动时是否设置: ```bash MINDMAP_LLM_BASE_URL MINDMAP_LLM_API_KEY MINDMAP_LLM_MODEL ``` 其中 `MINDMAP_LLM_BASE_URL` 应为 `/v1` 级别地址,不要带 `/chat/completions`。