Docker部署AI知识库的完整步骤教程

文章导读
把 AI 知识库跑在 Docker 里,实际是把四个东西拼起来:向量库、负责切片与检索的后端服务、负责向量化的嵌入模型,以及前面的 Web 界面或网关。能不能一次启动成功,通常取决于三件事有没有先想清楚:文档放在哪、向量化放在本地还是走外部接口、机器内存和磁盘够不够。下面按“先确认—再动手—再验证—最后划边界”的顺序给出一套可以直接替换参数的通用做法,具体端口、健康检查路径和镜像名需要结合你选的组
📋 目录
  1. Ⅰ 先确认当前场景和目标
  2. Ⅱ 按这个顺序处理
  3. Ⅲ 改完后怎么验证
  4. Ⅳ 容易忽略的边界
A A

把 AI 知识库跑在 Docker 里,实际是把四个东西拼起来:向量库、负责切片与检索的后端服务、负责向量化的嵌入模型,以及前面的 Web 界面或网关。能不能一次启动成功,通常取决于三件事有没有先想清楚:文档放在哪、向量化放在本地还是走外部接口、机器内存和磁盘够不够。下面按“先确认—再动手—再验证—最后划边界”的顺序给出一套可以直接替换参数的通用做法,具体端口、健康检查路径和镜像名需要结合你选的组件确认。

Docker 部署 AI 知识库的适用前提是:文档可以集中放进一个挂载目录,嵌入模型要么能在本机跑、要么接受调用外部接口,机器内存能同时容纳向量库与模型进程。操作上建议先只起向量库和后端两个容器,跑通“上传一份文档→提问能命中”再补前端和网关。验证看三处:容器状态、健康检查返回、一次带引用的问答结果。边界在于向量维度必须与向量库 collection 一致、数据卷必须持久化、端口不要直接暴露到公网,镜像 tag 不建议长期用 latest。

先确认当前场景和目标

不是所有知识库都适合用同一套 Docker 组合。先确认下面几项,判断条件对不上就先改方案,而不是先写 compose 文件:

  • 文档规模与格式:几十份 PDF 和几十万条工单是两种部署,前者单机容器足够,后者需要评估向量库的分片与磁盘占用。
  • 数据能否出网:如果文档涉密,嵌入模型必须本地部署,这会直接决定是否需要 GPU 或至少更大的内存。
  • 使用者数量:只有自己用,可以不装鉴权;多人使用就必须在网关层加登录和限流,否则后端接口等于对外开放。
  • 更新频率:文档经常变,就要确认后端是否支持增量索引;只能全量重建的话,需要预留重建期间的可用性方案。
  • 磁盘与备份:向量库、原始文档、模型权重通常要占掉可观空间,宿主机剩余空间和备份路径要提前规划。

如果以上任一项暂时无法确定,建议先用最小组合跑通流程:一个向量库容器 + 一个后端容器,嵌入模型先用外部接口,确认整条链路可用后再替换为本地模型。

按这个顺序处理

第一步,规划目录结构。把所有需要持久化的内容集中到项目目录下,不要留在容器内:

Docker部署AI知识库的完整步骤教程
kb/
├── docker-compose.yml
├── .env
└── data/
    ├── vector/     # 向量库数据
    └── docs/       # 原始文档,供后端读取与重建索引

第二步,写配置。下面是一份通用骨架,镜像名、端口和数据路径都要替换成你所选组件实际使用的值,不要原样复制:

services:
  vector-db:
    image: <向量库镜像>:<固定版本tag>
    restart: unless-stopped
    volumes:
      - ./data/vector:/var/lib/data
    ports:
      - "127.0.0.1:6333:6333"

  kb-api:
    image: <知识库后端镜像>:<固定版本tag>
    restart: unless-stopped
    env_file: .env
    depends_on:
      - vector-db
    volumes:
      - ./data/docs:/app/docs
    ports:
      - "127.0.0.1:8080:8080"

端口前面绑定 127.0.0.1 是有意为之:只有本机能访问,需要外部访问时再通过反向代理转发并加鉴权,避免容器直接暴露在公网。

第三步,填环境变量。把密钥和模型参数写在 .env 里,不要写进镜像或 compose 明文:

VECTOR_DB_URL=http://vector-db:6333
EMBEDDING_PROVIDER=local
EMBEDDING_MODEL=<模型名>
EMBEDDING_DIM=<向量维度,需与向量库collection一致>
CHUNK_SIZE=800
CHUNK_OVERLAP=100
ADMIN_TOKEN=<自行生成的长随机串>

第四步,先起依赖再起服务。向量库要先就绪,后端启动时通常会连接并检查 collection:

Docker部署AI知识库的完整步骤教程
docker compose pull
docker compose up -d vector-db
docker compose logs -f vector-db   # 等到出现监听端口或就绪日志
# 另开终端
docker compose up -d kb-api

第五步,导入文档。把文件放进 ./data/docs,再通过后端的导入接口或自带命令行触发索引。这一步的具体命令取决于你选的后端,判断标准只有一个:日志里能看到切片数量与写入成功的记录,且没有维度不匹配的报错。

改完后怎么验证

验证不要只看容器是不是 Up,建议按下面顺序逐项确认:

  1. 看容器状态与日志:docker compose ps 确认没有反复重启,docker compose logs --tail=100 kb-api 中不应出现连接超时或向量维度错误。
  2. 打健康检查接口:curl -s http://127.0.0.1:8080/health,返回内容以你所选后端的实际定义为准;没有健康接口时,用一次列表或统计请求代替。
  3. 做一次可判断对错的问答:先放一份只有你知道答案的文档,例如一份内部操作说明,然后提问一个只能从该文档得到答案的问题,观察返回内容是否带原文片段引用。
  4. 验证持久化:docker compose down 后重新 up -d,再次提问同一个问题,命中结果应当仍然存在,以此确认数据确实落在挂载卷上而不是容器内部。
  5. 验证增量:往 data/docs 加一份新文档并重新索引,再问一个只在新文档里出现的问题,确认能被检索到。

预期信号是:问答结果里能指出引用来源文件;如果回答通顺但引用为空,通常说明检索没有命中,问题在切片或嵌入环节,而不在生成模型。

容易忽略的边界

  • 镜像版本:生产用途不建议长期使用 latest,向量库与后端的大版本升级可能改变接口或索引格式,建议固定 tag 并记录在案。
  • 向量维度一致性:换嵌入模型时必须同步重建 collection,维度不一致会让写入静默失败或检索结果异常;这是最常见的一类“看起来跑起来了但答不出”的情况。
  • 资源与并发:本地嵌入模型对内存和显存要求较高,容器不设资源限制时可能拖垮宿主机,建议在 compose 中加限制并结合机器实际负载调整。
  • 权限与暴露面:管理接口、导入接口都应加鉴权;反向代理层建议同时限制上传大小和请求频率,避免被当作免费接口使用。
  • 不适用条件:如果文档需要严格的按人授权(每人只能查自己可见的文档),通用开源组合通常需要自行在检索层做过滤,不能只靠容器隔离实现。
  • 回退建议:升级前备份 data/vector 和 compose 文件,出现索引不兼容时先回退镜像 tag 与数据卷快照,再排查维度或接口变化。