Spring AI知识库搭建实战教程

从 Langchain4j 迁移至 Spring AI 搭建知识库？这项改造虽然看似折腾，但从长远来看，能够显著降低后续升级与维护成本。本文是一份完整的实战攻略，将手把手教你完成从数据表设计、向量数据库部署到模型集成的全过程。内容较长，适合具备一定开发基础的同学阅读。

先说明一下环境配置：基于 Ruoyi-Vue-Plus 框架，版本 5.3.1，Spring Boot 3.4.4，JDK 17，Spring AI 1.0.0。本地需要提前安装好 Ollama，并拉取 nomic-embed-text 模型。

步骤一：知识库表结构设计

新增 5 张核心表：ai_knowledge（知识库）、ai_knowledge_document（文档）、ai_knowledge_segment（文档切片）、ai_model（模型）、ai_api_key（API 密钥）。具体建表 SQL 此处不再一一罗列，直接参照字段定义创建即可。

步骤二：开发环境搭建

本次演示选用 Milvus 向量数据库，需要事先准备好 Docker 环境。Docker Desktop 的安装流程此处省略，默认你已经完成。首先检查 Docker Compose 是否可用：

docker-compose --version

确认无误后，新建 docker-compose.yml 文件，内容如下：

version: '3.5'
services:
  etcd:
    container_name: milvus-etcd
    image: quay.io/coreos/etcd:v3.5.18
    environment:
      - ETCD_AUTO_COMPACTION_MODE=revision
      - ETCD_AUTO_COMPACTION_RETENTION=1000
      - ETCD_QUOTA_BACKEND_BYTES=4294967296
      - ETCD_SNAPSHOT_COUNT=50000
    volumes:
      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/etcd:/etcd
    command: etcd -advertise-client-urls=http://etcd:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd
    healthcheck:
      test: ["CMD", "etcdctl", "endpoint", "health"]
      interval: 30s
      timeout: 20s
      retries: 3
  minio:
    container_name: milvus-minio
    image: minio/minio:RELEASE.2025-04-22T22-12-26Z
    environment:
      MINIO_ACCESS_KEY: minioadmin
      MINIO_SECRET_KEY: minioadmin
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/minio:/minio_data
    command: minio server /minio_data --console-address ":9001"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3
  standalone:
    container_name: milvus-standalone
    image: milvusdb/milvus:v2.5.13
    command: ["milvus", "run", "standalone"]
    security_opt:
      - seccomp:unconfined
    environment:
      ETCD_ENDPOINTS: etcd:2379
      MINIO_ADDRESS: minio:9000
    volumes:
      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/milvus:/var/lib/milvus
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9091/healthz"]
      interval: 30s
      start_period: 90s
      timeout: 20s
      retries: 3
    ports:
      - "19530:19530"
      - "9091:9091"
    depends_on:
      - "etcd"
      - "minio"
  attu:
    container_name: attu
    image: zilliz/attu:v2.5.7
    environment:
      MILVUS_URL: milvus-standalone:19530
    ports:
      - "19500:3000"
    depends_on:
      - "standalone"
networks:
  default:
    name: milvus

在配置文件所在目录下执行以下命令启动所有服务：

docker-compose up -d

随后验证镜像是否成功拉取以及容器是否正常运行：

docker images
docker ps

如果 docker ps 返回结果为空，可先查看所有容器（包括已停止的）：

docker ps -a

然后按以下顺序依次重启：

docker restart etcd容器id
docker restart minio容器id
docker restart milvus容器id
docker restart attu容器id

这里简要说明各组件的用途：

• Minio：负责对象存储，用于保存 Milvus 的日志与索引文件。浏览器打开 localhost:9000 即可访问控制台，默认账号和密码均为 minioadmin。
• Attu：Milvus 的可视化管理工具。浏览器访问 localhost:19500，若提示认证，用户名输入 root，密码输入 milvus 即可直接登录。

步骤三：引入项目依赖

在父模块的 pom.xml 中添加以下版本声明及依赖项：

    3.0.0
    1.0.0
    2.16.1




    org.apache.tika
    tika-core
    ${tika.version}
    
        
            commons-io
            commons-io
        
    



    org.springframework.ai
    spring-ai-tika-document-reader
    ${spring-ai.version}



    commons-io
    commons-io
    ${commons-io.version}

步骤四：配置 application.yml

spring:
  application:
    name: RuoYi-Vue-Plus
  ai:
    vectorstore:
      milvus:
        initialize-schema: true
        database-name: default
        collection-name: test
        client:
          host: milvus服务ip地址
          port: 19530
          username: root
          password: milvus

然后需要在 Milvus 的 default 数据库中创建一个名为 test 的集合，该集合应包含以下 4 个字段：

• doc_id：文档 ID，对应表 ai_knowledge_segment 中的 vector_id，用于后续验证与检索。
• embedding：向量字段，由 nomic-embed-text 模型生成，维度固定为 768（若使用 1024 或其他维度的模型将导致错误）。
• content：文本内容，通过 Tika 解析文档后获得。
• metadata：元数据，存储业务相关信息（如知识库 ID、文档 ID 等）。注意 Spring AI 的 Document 对象本身已包含 metadata 属性，字段设计需保持一致。

步骤五：代码自动生成

借助框架自带的代码生成器，可以快速生成以下三部分的后端代码：

1. 知识库模块（ai_knowledge）
2. 模型模块（ai_model）
3. 密钥模块（ai_api_key）

步骤六：核心逻辑讲解

系统的核心接口是上传文档列表，入口位于 AiKnowledgeDocumentController：

@PostMapping("/createKnowledgeDocumentList")
public R> createKnowledgeDocumentList(@RequestBody AiKnowledgeDocumentListBo bo) {
    return R.ok(aiKnowledgeDocumentService.createKnowledgeDocumentList(bo));
}

对应的 Service 实现包含以下主要逻辑：

@Override
@Transactional(rollbackFor = Exception.class)
public List createKnowledgeDocumentList(AiKnowledgeDocumentListBo bo) {
    // 校验知识库是否存在
    aiKnowledgeService.validateKnowledgeExists(bo.getKnowledgeId());
    if (ObjectUtil.isEmpty(bo.getList())) {
        throw new ServiceException("至少上传一个文件");
    }
    // 批量读取文档内容
    List aiKnowledgeDocuments = prepareDocuments(bo);
    baseMapper.insertBatch(aiKnowledgeDocuments);
    // 执行文档切片并向量化存储
    processDocumentSegment(aiKnowledgeDocuments);
    return extractDocumentIds(aiKnowledgeDocuments);
}

其中，获取向量存储对象的实现如下：

@Override
public VectorStore getOrCreateVectorStore(Long embedModelId, Map> metadataFields) {
    // 获取模型信息
    AiModelVo aiModelVo = validateModel(embedModelId);
    AiApiKeyVo aiApiKeyVo = aiApiKeyService.validateApiKey(aiModelVo.getKeyId());
    AiPlatformEnum aiPlatformEnum = AiPlatformEnum.validatePlatform(aiApiKeyVo.getPlatform());

    // 创建或获取嵌入模型
    EmbeddingModel embeddingModel = modelFactoryService.getOrCreateEmbeddingModel(
        aiPlatformEnum, aiApiKeyVo.getApiKey(), aiApiKeyVo.getUrl(), aiModelVo.getModel()
    );

    return modelFactoryService.getOrCreateVectorStore(MilvusVectorStore.class, embeddingModel, metadataFields);
}

这里明确指定使用 MilvusVectorStore 进行向量存储。如果你阅读过之前的文档，会发现只需将 MilvusVectorStore.class 替换为 SimpleVectorStore.class，即可快速切换为本地内存存储模式。这种设计具有良好的扩展性，后续接入其他向量数据库（如 Pinecone、Weaviate）也极为方便。

步骤七：数据录入操作顺序

为了保证数据完整性，请严格按照以下顺序操作：

1. 新增 API 密钥 → 系统自动验证
2. 新增 AI 模型 → 系统自动验证
3. 新增知识库 → 系统自动验证
4. 上传文档 → 框架提供内置验证
5. 查询文档 → 框架提供内置功能
6. 查看文档列表 → 框架提供内置功能
7. 删除文档 → 框架提供内置验证

步骤八：接口测试与结果验证

完成数据录入后，需重点验证以下三个环节：

• 文档表：确认 ai_knowledge_document 表中已正确插入文档记录。
• 切片表：确认 ai_knowledge_segment 表中已生成对应的文档切片。
• 向量库：通过 Attu 可视化界面查看 test 集合中是否存在对应的向量数据。

至此，基于 Spring AI 的知识库示例（Demo 版）已完整实现。回顾整个流程，核心环节包括：数据库表设计、Milvus 向量数据库部署、Tika 文档解析、文本切片以及向量化存储。未来如果需要对接其他 AI 模型或向量存储方案，只需在工厂类中扩展相应实现即可，整个代码结构清晰、易于维护。

你是一名 AI 行业编辑，请围绕下面这条热点输出一份资讯解读：
热点：Spring AI知识库搭建实战教程要求：
1. 先用一句话解释这条热点在讲什么
2. 再总结它为什么重要
3. 说明会影响哪些 AI 产品或内容方向
4. 最后给出 3 个适合资讯站使用的标题