企业级本地知识库部署教程：MaxKB + vLLM + BGE-M3 完全指南

hk5222

318人浏览 · 2026-05-20 22:08:21

hk5222 · 2026-05-20 22:08:21 发布

🚀 企业级本地知识库部署教程：MaxKB + vLLM + BGE-M3 完全指南

适合新手小白，全程命令可复制粘贴，基于 Ubuntu 22.04 + Docker，成功在本地搭建起具有文档向量化、大模型问答能力的知识库系统。

📋 目录

准备工作
安装 Docker 并优化存储
部署基础服务（PostgreSQL、Elasticsearch、Milvus）
部署 MaxKB 主程序
接入本地 vLLM 大模型（Qwen3）
部署向量化模型 BGE-M3（手动下载+Flask服务）
在 MaxKB 中创建知识库并上传文档
日常维护与清理

1. 准备工作

1.1 硬件要求

最低配置：4核CPU、16GB内存、50GB可用硬盘（建议SSD）
推荐配置：8核以上、32GB内存、NVIDIA GPU（用于大模型推理）
本文基于：Intel Xeon 10核、32GB内存、V100 32GB显卡

1.2 软件环境

操作系统：Ubuntu 22.04 LTS（其他Linux发行版类似）
已安装 Docker（版本 20.10+）
已安装 NVIDIA 驱动和 CUDA（如果使用 GPU）

1.3 目录规划

我们统一将数据存放在大容量硬盘挂载点 /mnt/ai_models（请根据你的实际情况修改路径）。

# 创建知识库专用目录（如果不存在）
mkdir -p /mnt/ai_models/knowledge/data
mkdir -p /mnt/ai_models/models

提示：如果没有额外硬盘，可以将所有路径中的 /mnt/ai_models 替换为 /home/你的用户名/data。

2. 安装 Docker 并优化存储

2.1 安装 Docker（如已安装可跳过）

# 更新软件源
sudo apt update
# 安装依赖
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
# 添加 Docker 官方 GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
# 添加 Docker 仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# 安装 Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io
# 将当前用户加入 docker 组（避免每次 sudo）
sudo usermod -aG docker $USER
# 重新登录或执行 newgrp docker
newgrp docker

2.2 迁移 Docker 数据目录到大容量磁盘（重要！）

防止系统盘被撑爆。

# 停止 Docker 服务
sudo systemctl stop docker
# 创建新目录
sudo mkdir -p /mnt/ai_models/docker
# 同步原有数据（如果 Docker 刚安装，可跳过）
sudo rsync -avxP /var/lib/docker/ /mnt/ai_models/docker/
# 修改 Docker 配置文件
sudo tee /etc/docker/daemon.json <<EOF
{
  "data-root": "/mnt/ai_models/docker",
  "registry-mirrors": [
    "https://docker.xuanyuan.me",
    "https://docker.1ms.run"
  ]
}
EOF
# 重启 Docker
sudo systemctl start docker
# 验证
docker info | grep "Docker Root Dir"
# 应输出 /mnt/ai_models/docker

2.3 安装 Docker Compose V2

新版 Docker 已内置 docker compose 命令（注意中间没有横线）。验证：

docker compose version

如果提示找不到，可安装独立版本：

sudo apt install -y docker-compose-plugin

3. 部署基础服务

我们需要三个基础服务：PostgreSQL（元数据）、Elasticsearch（关键词检索）、Milvus（向量数据库）。

3.1 部署 PostgreSQL

# 创建数据目录
mkdir -p /mnt/ai_models/knowledge/data/postgresql
# 运行容器
docker run -d \
  --name postgres \
  --restart unless-stopped \
  -p 5432:5432 \
  -e POSTGRES_DB=maxkb \
  -e POSTGRES_USER=maxkb \
  -e POSTGRES_PASSWORD=maxkb_secure_password \
  -v /mnt/ai_models/knowledge/data/postgresql:/var/lib/postgresql/data \
  postgres:15-alpine
# 等待5秒后测试
sleep 5
docker exec -it postgres psql -U maxkb -c "SELECT 1"
# 若输出包含 ?column? 和 1，则成功

3.2 部署 Elasticsearch

mkdir -p /mnt/ai_models/knowledge/data/elasticsearch
docker run -d \
  --name elasticsearch \
  --restart unless-stopped \
  -p 9200:9200 \
  -p 9300:9300 \
  -e "discovery.type=single-node" \
  -e "ES_JAVA_OPTS=-Xms4g -Xmx4g" \
  -e "xpack.security.enabled=false" \
  -v /mnt/ai_models/knowledge/data/elasticsearch:/usr/share/elasticsearch/data \
  docker.elastic.co/elasticsearch/elasticsearch:8.11.0
sleep 30
curl http://localhost:9200
# 应返回 JSON 信息

3.3 部署 Milvus（向量数据库）

Milvus 需要用 docker-compose 启动多个容器。首先下载配置文件。

cd /mnt/ai_models/knowledge
# 使用国内镜像加速下载（ghfast.top）
curl -L -o docker-compose-milvus.yml \
  "https://ghfast.top/https://github.com/milvus-io/milvus/releases/download/v2.3.3/milvus-standalone-docker-compose.yml"
# 修改数据存储路径
sed -i 's|/var/lib/milvus|/mnt/ai_models/knowledge/data/milvus|g' docker-compose-milvus.yml
# 启动
docker compose -f docker-compose-milvus.yml up -d
# 查看容器状态
docker ps | grep milvus
# 应看到 milvus-standalone、milvus-etcd、milvus-minio 三个容器运行中

4. 部署 MaxKB 主程序

MaxKB 是一个开源的 LLM 应用平台，提供知识库管理、RAG 对话等功能。

4.1 获取宿主机 IP（用于容器间通信）

# 获取 docker0 网桥 IP（通常是 172.17.0.1）
HOST_IP=$(ip addr show docker0 | grep "inet " | awk '{print $2}' | cut -d/ -f1)
echo $HOST_IP
# 如果为空，使用 host.docker.internal（Docker 20.10+ 支持）

4.2 启动 MaxKB 容器

# 创建数据目录
mkdir -p /mnt/ai_models/knowledge/data/maxkb

docker run -d \
  --name maxkb \
  --restart unless-stopped \
  -p 8080:8080 \
  -v /mnt/ai_models/knowledge/data/maxkb:/var/lib/postgresql/data \
  -e MAXKB_POSTGRES_HOST=${HOST_IP:-host.docker.internal} \
  -e MAXKB_POSTGRES_PORT=5432 \
  -e MAXKB_POSTGRES_DB=maxkb \
  -e MAXKB_POSTGRES_USER=maxkb \
  -e MAXKB_POSTGRES_PASSWORD=maxkb_secure_password \
  -e MAXKB_ELASTICSEARCH_HOST=http://${HOST_IP:-host.docker.internal}:9200 \
  -e MAXKB_MILVUS_HOST=${HOST_IP:-host.docker.internal} \
  -e MAXKB_MILVUS_PORT=19530 \
  1panel/maxkb:latest

4.3 初始化数据库

# 进入容器执行迁移
docker exec -it maxkb python manage.py migrate

4.4 访问 MaxKB Web 界面

打开浏览器，输入 http://你的服务器IP:8080。

首次访问需要注册管理员账号：

用户名：自定义（如 admin）
密码：自定义（务必记住）
邮箱：任意

注意：如果页面提示需要输入 License，说明你下载的是企业版。请改用社区版镜像：1panel/maxkb:latest 为社区版，无需 license。

5. 接入本地 vLLM 大模型（Qwen3）

假设你已经有一个运行中的 vLLM 服务，地址为 http://192.168.101.12:8000，模型名称为 Qwen3.6-35B-A3B-AWQ。

在 MaxKB 中添加该模型：

登录 MaxKB，点击左侧菜单 「系统设置」→「模型管理」。
点击右上角 「添加模型」。
填写以下信息：

字段	值
模型类型	大语言模型
供应商	vLLM
模型名称	`Qwen3.6-35B-A3B-AWQ`
API 域名	`http://192.168.101.12:8000/v1`
API Key	任意字符（如 `local`）

点击 「保存」，然后点击 「校验」 测试连接。如果成功，大模型即可在应用中使用。

6. 部署向量化模型 BGE-M3（手动下载+Flask服务）

向量模型用于将文档切片转化为向量，供检索使用。我们选择 BGE-M3（中文效果最佳），但 Ollama 版本不稳定，因此采用手动下载 + Flask 服务的方式。

6.1 手动下载 BGE-M3 模型

# 安装 modelscope SDK
pip3 install modelscope -U

# 下载模型到数据盘（约 2.27GB，需耐心等待）
modelscope download --model BAAI/bge-m3 --local_dir /mnt/ai_models/models/bge-m3

# 验证模型文件
ls -lh /mnt/ai_models/models/bge-m3/
# 应看到 pytorch_model.bin 等文件

6.2 创建 Flask 服务脚本

在服务器上创建一个 Python 脚本，提供与 OpenAI 兼容的 /v1/embeddings 接口。

mkdir -p /home/psw/maxkb_project
cat > /home/psw/maxkb_project/app_flask.py << 'EOF'
from flask import Flask, request, jsonify
from FlagEmbedding import FlagModel
import logging

app = Flask(__name__)
logging.basicConfig(level=logging.INFO)

# 加载本地模型
model = FlagModel('/mnt/ai_models/models/bge-m3',
                  query_instruction_for_retrieval="",
                  use_fp16=False)

@app.route('/v1/embeddings', methods=['POST'])
def embeddings():
    data = request.get_json()
    texts = data.get('input', [])
    if isinstance(texts, str):
        texts = [texts]
    embeddings = model.encode(texts)
    emb_list = [e.tolist() for e in embeddings]
    return jsonify({
        "object": "list",
        "data": [{"object": "embedding", "index": i, "embedding": emb} for i, emb in enumerate(emb_list)],
        "model": "bge-m3"
    })

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8081)
EOF

6.3 构建 Docker 镜像

cd /home/psw/maxkb_project

# 创建 Dockerfile
cat > Dockerfile << 'EOF'
FROM python:3.10-slim
RUN pip install flask flagembedding -i https://pypi.tuna.tsinghua.edu.cn/simple
COPY app_flask.py /app.py
CMD ["python", "/app.py"]
EOF

# 构建镜像
docker build -t bge-m3-cpu:fixed .

6.4 运行向量服务容器

docker run -d \
  --name bge-m3-service \
  --restart unless-stopped \
  -p 8082:8081 \
  -v /mnt/ai_models/models/bge-m3:/mnt/ai_models/models/bge-m3 \
  bge-m3-cpu:fixed

6.5 测试向量服务

curl -X POST http://localhost:8082/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"input": ["测试文本"]}'

如果返回一长串向量数值（如 {"object":"list","data":[...]}），则服务正常。

6.6 在 MaxKB 中添加向量模型

回到 MaxKB 后台，「系统设置」→「模型管理」→「添加模型」。
填写：

字段	值
模型类型	向量模型
供应商	OpenAI（因为我们的接口兼容 OpenAI）
模型名称	`bge-m3`
API 域名	`http://172.17.0.1:8082/v1`
API Key	任意（如 `local`）

保存并点击「校验」，显示成功即可。

7. 在 MaxKB 中创建知识库并上传文档

7.1 创建知识库

登录 MaxKB，点击左侧 「知识库」。
点击 「创建知识库」。
名称：例如 我的维修手册。
向量模型：选择刚刚添加的 bge-m3。
点击 「确定」。

7.2 上传文档

进入知识库详情页，点击 「上传文档」。
支持格式：PDF、Word、Excel、TXT、Markdown、PPT 等。
可以拖拽整个文件夹，或选择多个文件。
点击 「开始导入」。

系统会自动对文档进行切片、向量化处理。可以在右上角 「任务中心」 查看进度。当文档状态变为「已完成」或「成功」，即表示向量化完成。

7.3 创建对话应用并测试

点击左侧 「应用」 → 「创建应用」。
选择 「聊天助手」，填写名称如 知识库助手。
关联知识库：选择你刚刚创建的知识库。
AI 模型：选择第5步添加的 Qwen3 模型。
点击 「保存」。
在应用对话界面输入问题，例如“请总结维修手册中关于离心泵的维护周期”。如果回答基于文档内容，恭喜你，本地知识库已成功运行！

8. 日常维护与清理

8.1 查看所有容器状态

docker ps -a

8.2 重启某个服务（例如 MaxKB）

docker restart maxkb

8.3 清理无用的 Docker 镜像和容器

# 删除所有停止的容器
docker container prune -f
# 删除未被使用的镜像
docker image prune -a -f

8.4 备份重要数据

建议定期备份 /mnt/ai_models/knowledge 目录：

tar -czf /mnt/ai_models/backup_$(date +%Y%m%d).tar.gz /mnt/ai_models/knowledge

8.5 升级 MaxKB

docker pull 1panel/maxkb:latest
docker stop maxkb && docker rm maxkb
# 重新运行启动命令（环境变量相同）

如果服务器重启，绝大多数服务都会自动恢复，因为你已经为所有 Docker 容器设置了 --restart unless-stopped 参数。但为了确保万无一失，你需要做以下检查和可能的少量手动操作。

9.0 服务器重启后自动恢复

Docker 守护进程本身需要开机自启。执行以下命令确认：

sudo systemctl is-enabled docker

如果输出 enabled，说明 Docker 会在系统启动时自动运行，进而自动启动所有设置了 --restart unless-stopped 的容器。如果不是 enabled，请执行：

sudo systemctl enable docker

📋 重启后需要检查的核心服务

1. 查看所有容器状态

docker ps -a

你应该看到以下容器状态为 Up（正在运行）：

容器名	说明
`postgres`	元数据库
`elasticsearch`	检索引擎
`milvus-standalone`	向量数据库主节点
`milvus-etcd`	Milvus 协调服务
`milvus-minio`	Milvus 对象存储
`maxkb`	MaxKB 主程序
`bge-m3-service`	向量化服务
`vllm-qwen`	大模型推理服务（如果之前是容器）

如果某个容器状态为 Exited，可以手动启动：

docker start <容器名>

例如：

docker start postgres
docker start elasticsearch
docker start milvus-standalone
docker start maxkb
docker start bge-m3-service
docker start vllm-qwen

注意：milvus-etcd 和 milvus-minio 通常随 milvus-standalone 一起自动启动，无需单独操作。

🔧 手动启动命令汇总（一键脚本）

创建一个启动脚本，方便日后使用：

cat > ~/start_knowledge_services.sh << 'EOF'
#!/bin/bash
echo "正在启动知识库相关服务..."
docker start postgres 2>/dev/null
docker start elasticsearch 2>/dev/null
docker start milvus-standalone 2>/dev/null
docker start maxkb 2>/dev/null
docker start bge-m3-service 2>/dev/null
docker start vllm-qwen 2>/dev/null
echo "启动完成，查看状态："
docker ps --format "table {{.Names}}\t{{.Status}}"
EOF

chmod +x ~/start_knowledge_services.sh

以后只需执行：

~/start_knowledge_services.sh

📌 特殊情况：vLLM 不是 Docker 容器

如果你的 vLLM 是通过直接运行命令行启动的（而非容器），则重启后需要重新执行启动命令。例如：

# 进入你的 vLLM 环境（如 conda 环境）
conda activate vllm_env
# 重新运行 vLLM 服务
vllm serve /path/to/model --served-model-name Qwen3.6-35B-A3B-AWQ --port 8000

建议将这条命令放入 systemd 服务或 rc.local 实现自动启动。

🧪 验证所有服务是否正常工作

测试 MaxKB 访问：浏览器打开 http://你的服务器IP:8080，应能打开登录页。

测试向量化服务：

curl http://localhost:8082/v1/embeddings -H "Content-Type: application/json" -d '{"input": ["测试"]}'

应返回向量数组。

测试大模型服务：
```
curl http://192.168.101.12:8000/v1/models
```
应返回模型列表。
在 MaxKB 中发送一条测试消息，确认能正常回复。

🎉 结束语

至此，你已经成功搭建了一套完整的本地知识库系统，包括：

文档管理和向量检索（BGE-M3）
大模型问答（Qwen3 via vLLM）
Web 界面管理和对话

这套系统完全运行在你自己的服务器上，数据不外泄，且无需付费。你可以继续上传成百上千份文档，让 AI 成为你的私人知识专家。

如果遇到任何问题，欢迎在评论区留言，我会尽力协助。

附录：常见问题

Q1: 容器启动失败，提示端口被占用？
A: 检查端口是否已被其它程序占用：sudo lsof -i :端口号，更换映射端口或停止占用进程。

Q2: MaxKB 校验 vLLM 模型失败？
A: 确认 vLLM 服务正在运行，且 API 域名填写正确（注意末尾的 /v1）。可以先用 curl 测试：curl http://192.168.101.12:8000/v1/models。

Q3: 向量模型服务返回 404？
A: 检查 Flask 服务是否启动：docker logs bge-m3-service。确认 API 域名为 http://172.17.0.1:8082/v1（不是 8082 裸端口）。

Q4: 如何彻底删除所有容器并重来？
A: docker stop $(docker ps -aq) 停止所有，docker system prune -a --volumes 彻底清理（危险！会删除所有数据）。@TOC

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

Gemini Omni Flash 完整指南：Google AI 视频生成器深度解析

AtomGit开源社区

基于神经网络的带输出三相逆变器模型预测控制LC滤波器附Matlab代码

在三相逆变器系统中，输出滤波器对于提高电能质量起着关键作用。LC 滤波器因其结构简单、成本低等优点被广泛应用。然而，传统的 LC 滤波器设计方法往往基于固定的系统参数和工况，在实际运行中，系统参数的变化以及负载的不确定性会影响滤波器的性能。模型预测控制（MPC）作为一种先进的控制策略，能够考虑系统的未来动态行为，实现对逆变器的有效控制。将神经网络与模型预测控制相结合，应用于带输出 LC 滤波器的三

AtomGit开源社区

基于神经网络的带输出三相逆变器模型预测控制LC滤波器附Matlab代码

AtomGit开源社区

所有评论(0)

查看更多评论

hk5222

@hk5222

已为社区贡献2条内容

企业级本地知识库部署教程：MaxKB + vLLM + BGE-M3 完全指南

hk5222

🚀 企业级本地知识库部署教程：MaxKB + vLLM + BGE-M3 完全指南

📋 目录

1. 准备工作

1.1 硬件要求

1.2 软件环境

1.3 目录规划

2. 安装 Docker 并优化存储

2.1 安装 Docker（如已安装可跳过）

2.2 迁移 Docker 数据目录到大容量磁盘（重要！）

2.3 安装 Docker Compose V2

3. 部署基础服务

3.1 部署 PostgreSQL

3.2 部署 Elasticsearch

3.3 部署 Milvus（向量数据库）

4. 部署 MaxKB 主程序

4.1 获取宿主机 IP（用于容器间通信）

4.2 启动 MaxKB 容器

4.3 初始化数据库

4.4 访问 MaxKB Web 界面

5. 接入本地 vLLM 大模型（Qwen3）

6. 部署向量化模型 BGE-M3（手动下载+Flask服务）

6.1 手动下载 BGE-M3 模型

6.2 创建 Flask 服务脚本

6.3 构建 Docker 镜像

6.4 运行向量服务容器

6.5 测试向量服务

6.6 在 MaxKB 中添加向量模型

7. 在 MaxKB 中创建知识库并上传文档

7.1 创建知识库

7.2 上传文档

7.3 创建对话应用并测试

8. 日常维护与清理

8.1 查看所有容器状态

8.2 重启某个服务（例如 MaxKB）

8.3 清理无用的 Docker 镜像和容器

8.4 备份重要数据

8.5 升级 MaxKB

9.0 服务器重启后自动恢复

📋 重启后需要检查的核心服务

1. 查看所有容器状态

🔧 手动启动命令汇总（一键脚本）

📌 特殊情况：vLLM 不是 Docker 容器

🧪 验证所有服务是否正常工作

🎉 结束语

所有评论(0)

温馨提示：您尚未绑定手机号

hk5222