Linux系统部署KAG知识增强生成框架完整指南

一、KAG框架简介

KAG（Knowledge Augmented Generation） 是蚂蚁集团推出的基于OpenSPG引擎和大型语言模型（LLM）的专业领域知识服务框架，专为构建垂直领域知识库的逻辑推理问答解决方案而设计。

与传统RAG（检索增强生成）技术相比，KAG具有三大核心优势：

• 逻辑推理能力：支持多条件组合推理、时序推理和矛盾检测
• 知识准确性：通过概念语义推理实现自动消歧和术语对齐
• 多模态知识管理：支持文本/表格/图谱等多种格式知识的双向索引

KAG已在金融风控、医疗诊断、法律合同审查等专业领域得到验证，在电子政务问答场景中准确率可达91.6%，显著优于传统RAG方案。

二、系统部署要求

2.1 硬件要求

• CPU：≥ 8核（推荐16核及以上）
• 内存：≥ 32GB（推荐64GB，最低16GB可运行基础功能）
• 磁盘：≥ 100GB SSD（用于存储Docker镜像和知识库数据）
• 网络：稳定的互联网连接（需拉取Docker镜像和代码）

2.2 软件要求

• 操作系统：
  • Ubuntu 20.04 LTS 或更高版本
  • CentOS 7 或更高版本
• 必要软件：
  • Docker 20.10.x 或更高版本
  • Docker Compose 1.29.x 或更高版本
  • Git（用于克隆代码仓库）

三、部署前准备工作

3.1 安装Docker和Docker Compose

Ubuntu系统安装步骤：

# 更新系统包索引并升级已安装包
sudo apt update && sudo apt upgrade -y

# 安装Docker依赖包
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 Engine
sudo apt update && sudo apt install -y docker-ce docker-ce-cli containerd.io

# 安装Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

CentOS系统安装步骤：

# 安装Docker依赖包
sudo yum install -y yum-utils device-mapper-persistent-data lvm2

# 添加Docker官方仓库
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 安装Docker Engine
sudo yum install -y docker-ce docker-ce-cli containerd.io

# 安装Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

3.2 配置Docker服务

# 启动Docker服务并设置开机自启
sudo systemctl start docker
sudo systemctl enable docker

# 将当前用户添加到docker组（避免每次使用sudo）
sudo usermod -aG docker $USER

# 验证Docker安装是否成功
docker --version
docker-compose --version

注意：添加用户到docker组后，需要注销并重新登录才能使权限生效

3.3 配置Docker镜像加速器（国内用户）

# 创建或修改daemon.json文件
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": ["https://your-mirror-url.mirror.aliyuncs.com"]
}
EOF

# 重启Docker服务使配置生效
sudo systemctl daemon-reload
sudo systemctl restart docker

提示：国内用户可使用阿里云、网易云等提供的Docker镜像加速器，需注册并获取专属加速地址

四．部署KAG框架

4.1 创建工作目录并获取配置文件

# 创建工作目录
mkdir -p ~/kag-deploy && cd ~/kag-deploy

# 下载官方Docker Compose配置文件
curl -sSL https://raw.githubusercontent.com/OpenSPG/openspg/refs/heads/master/dev/release/docker-compose-west.yml -o docker-compose.yml

4.2 启动KAG服务

# 后台启动所有服务组件
docker compose -f docker-compose.yml up -d

# 查看服务启动状态
docker compose ps

4.3 验证服务启动情况

# 查看容器日志（主要服务）
docker compose logs -f server

# 检查8887端口是否已监听
netstat -tuln | grep 8887

服务启动成功标志：日志中出现"Started Application in XX seconds"，且8887端口处于LISTEN状态

五、访问与验证KAG服务

5.1 登录KAG Web界面

1. 打开浏览器，访问地址：http://服务器IP:8887
2. 使用默认账号登录：
   • 用户名：openspg
   • 密码：openspg@kag

安全提示：首次登录后，请立即修改默认密码！点击右上角用户头像→"个人设置"→"修改密码"

5.2 基本功能验证

创建测试知识库：

1. 登录后点击"新建知识库"
2. 填写知识库名称（如"test-kb"）和描述
3. 高级配置保持默认，点击"创建"

上传示例文档：

1. 进入创建的知识库
2. 点击"文档上传"，选择本地PDF或TXT文件
3. 等待文档处理完成（较大文件可能需要几分钟）

测试问答功能：

1. 在知识库页面的搜索框中输入问题
2. 观察系统返回的答案是否准确引用了文档内容
3. 测试多跳问题，验证KAG的逻辑推理能力

六、常见问题解决

6.1 Docker镜像拉取缓慢或失败

• 解决方案：配置国内镜像加速器（见3.3节）
• 备选方案：手动拉取镜像

# 单独拉取各个组件镜像
docker pull spg-registry.cn-hangzhou.cr.aliyuncs.com/spg/openspg-server:latest
docker pull spg-registry.cn-hangzhou.cr.aliyuncs.com/spg/openspg-mysql:latest
docker pull spg-registry.cn-hangzhou.cr.aliyuncs.com/spg/openspg-neo4j:latest
docker pull spg-registry.cn-hangzhou.cr.aliyuncs.com/spg/openspg-minio:latest

6.2 端口冲突问题

# 查看端口占用情况
sudo lsof -i :8887

# 修改docker-compose.yml中的端口映射
vi docker-compose.yml
# 将"8887:8887"修改为"自定义端口:8887"，如"8080:8887"

# 重启服务使修改生效
docker compose -f docker-compose.yml up -d --force-recreate

6.3 服务启动后无法访问

• 防火墙配置：

# Ubuntu系统
sudo ufw allow 8887/tcp

# CentOS系统
sudo firewall-cmd --add-port=8887/tcp --permanent
sudo firewall-cmd --reload

• SELinux配置（CentOS）：

# 临时关闭SELinux
sudo setenforce 0

# 永久关闭SELinux（需重启）
sudo sed -i 's/SELINUX=enforcing/SELINUX=permissive/g' /etc/selinux/config

6.4 内存不足导致服务崩溃

• 增加系统内存（推荐至少32GB）
• 调整Docker资源限制：

# 在docker-compose.yml中添加资源限制
services:
  server:
    deploy:
      resources:
        limits:
          cpus: '8'
          memory: 24G

七、结语

通过本文档，您已成功在Linux系统上部署了KAG知识增强生成框架。KAG作为新一代知识服务框架，凭借其强大的逻辑推理能力和知识管理功能，为专业领域知识库建设提供了高效解决方案。

后续学习建议：

1. 深入学习KAG的知识建模方法，设计符合业务需求的Schema
2. 探索KAG与企业现有系统的集成方案
3. 关注官方GitHub仓库获取最新更新：https://github.com/OpenSPG/KAG

官方资源：

• KAG项目主页：https://spg.openkg.cn/
• 技术文档：https://spg.openkg.cn/docs
• 社区论坛：https://discuss.openkg.cn/c/kag

希望本指南对您的KAG部署之旅有所帮助！如有任何问题，欢迎在官方社区提问交流。