AI BI Helper开发实录01：文本向量与Milvus向量数据库集成

AI BI Helper 开发实录 01：文本向量与 Milvus 向量数据库集成

本篇内容将深入讲解 AI BI Helper 项目中文本向量与 Milvus 向量数据库的集成方案。整体架构划分为两大核心模块：第一部分聚焦文本向量技术，专用于文档语义检索与智能匹配；第二部分为 Graph 工作流编排，旨在实现智能数据分析与自动化决策。我们先攻克第一部分——文本向量，完整跑通文档上传、自定义标题分割、向量存储（从 Redis 迁移至 Milvus）的整套流程。

一. 基础环境搭建

1.1 新建项目 ivy-service-ai-bi-helper-bootstrap

在 ivy-services 中新增了 ivy-service-ai-bi-helper-bootstrap 项目。由于本次项目相对简洁，未单独构建 models 模块，所有代码统一存放，整体结构更加紧凑高效。

1.2 添加 pom 依赖

核心依赖涵盖：数据库持久化支持、Graph 工作流引擎、阿里百炼大模型服务。

[pom.xml 依赖配置内容]

1.3 新建 Spring Boot 启动类

[BIHelperApplication.ja va 启动类代码]

1.4 application.yml 配置

[application.yml 配置文件内容]

1.5 测试 Controller

[TestController.ja va 测试控制器代码]

1.6 运行测试

服务启动后，访问接口文档地址：http://127.0.0.1:8910/doc.html#/document/all/%E6%B5%8B%E8%AF%95Controller/test

1.7 小结

基础环境搭建整体顺畅，未遇到显著阻碍。可复用的组件均已封装完备，直接引入即可快速集成。这再次印证了我们的核心实践——将常用功能封装为自定义 starter 体系，新项目由此能够迅速上手、高效推进。

二. 文本向量 - Redis 版本

2.1 什么是文本向量

先厘清核心概念。引用豆包的解释：

文本向量：把自然语言（句子、段落、词语）转换成固定长度的浮点数数组，让计算机能理解文字语义。文字本身是字符串，机器无法直接计算相似度；转为向量后，就可以用数学方法衡量语义关系。

简而言之，就是将文字转化为数字数组，使计算机能够高效执行语义匹配与相似度计算。

2.2 向量模型选择

最初计划采用硅基流动的向量服务（已申请代金券），但始终无法正常使用，最终选定阿里百炼的文本向量模型：

模型名称：qwen3.7-text-embedding

2.3 配置 Embedding

在 application.yml 中添加向量模型配置：

[spring.ai.embedding 配置内容]

2.4 添加 Redis 向量存储依赖

[spring-ai-starter-vector-store-redis 依赖配置]

2.5 配置 Redis 向量存储

[spring.ai.vectorstore.redis 配置内容]

2.6 增加文档上传接口

[DocumentController.ja va 文档上传控制器代码]

2.7 DocumentServiceImpl 实现

2.7.1 添加 Tika 文档解析依赖

[spring-ai-tika-document-reader 依赖配置]

2.7.2 代码实现（基础版本）

[DocumentServiceImpl.ja va 基础版本代码]

2.7.3 测试

查看 Redis 中的向量数据：

2.7.4 问题发现

默认的文本拆分策略采用固定字符数切分，导致所有文档内容混杂在一起，语义连贯性遭到破坏。例如，同一标题下的内容被拆分到不同块中，后续检索时上下文信息变得不完整。

2.8 自定义标题分隔器 HeadingBasedSplitter

针对上述痛点，我们自定义了一个基于标题的文本分割器，按照文档中的数字标题（如 "1."、"1.1"、"2.3.1"）进行精准拆分，确保每个分块均为一个完整的语义章节。

[HeadingBasedSplitter.ja va 自定义标题分割器代码]

2.9 集成自定义分隔器

修改 DocumentServiceImpl，引入自定义分割器：

[DocumentServiceImpl.ja va 集成自定义分割器代码]

2.10 测试带分隔的效果

[测试结果截图]

三. 文本向量 - Milvus 数据库版本

Redis 作为向量数据库适用于小规模应用场景，生产环境建议选用专业级向量数据库。我们选择了 Milvus 3.0，这是一款开源的云原生向量数据库，性能卓越且社区活跃度极高。

3.1 移除 Redis 向量存储依赖

将 Redis 向量存储的引用注释掉（application.yml 中的配置可保留，不会产生干扰）：

[移除Redis依赖的注释代码]

3.2 安装 Milvus 3.0

参考官方文档：milvus.io/docs/zh/quickstart.md

3.2.1 下载 docker-compose.yml

[下载 docker-compose.yml 的命令]

3.2.2 docker-compose.yml 配置

[docker-compose.yml 配置内容]

3.2.3 启动 Milvus

[docker-compose up -d 命令]

3.2.4 权限问题处理

启动后遇到权限错误：

错误信息：[failed to mkdir 错误信息]

解决方案：Milvus 默认以 UID 1000 运行，需为数据目录配置正确的权限：

[chmod/chown 命令]

建议在当前目录执行：

[相对路径的chmod/chown 命令]

3.2.5 重启 Milvus

[重启命令]

访问 Milvus Web UI：http://192.168.55.130:9091/webui/

3.3 添加 Milvus 向量存储依赖

[spring-ai-starter-vector-store-milvus 依赖配置]

3.4 配置 Milvus

3.4.1 初始配置

[spring.ai.vectorstore.milvus 初始配置]

3.4.2 踩坑记录：Collection 名称格式错误

启动时报错：

[collection 名称格式错误信息]

问题分析：Milvus 的 collection 名称仅允许包含数字、字母和下划线，不可使用连字符 -。

解决方案：将 bi-helper 调整为 biHelper，并添加自动建表配置：

[修正后的配置内容]

3.5 测试 Milvus 向量存储

[测试结果截图]

已成功插入 8 条向量数据！

3.6 安装 Milvus 可视化工具 Attu

Milvus 3.0 默认未集成图形化管理界面，需单独安装 Attu：

[Attu 安装界面截图]

四. 数据库准备

为后续的 BI 分析与 Graph 工作流准备业务数据基础。

4.1 创建数据库

创建数据库 bi-helper：

4.2 创建数据库表

[SQL 建表语句]

4.3 创建数据

[SQL 数据插入语句]

五. 小结

本期内容主要聚焦于文本向量技术与 Milvus 向量数据库的集成实践，完成了以下关键工作：

已完成内容

1. 基础环境搭建：新建 ivy-service-ai-bi-helper-bootstrap 项目，完成数据库与大模型配置
2. 文本向量核心功能：
   • 集成阿里百炼 qwen3.7-text-embedding 向量模型
   • 实现文档上传接口，支持 PDF、Word 等多种格式
   • 自定义 HeadingBasedSplitter 标题分割器，按数字标题精准拆分文档
   • 支持 Redis 与 Milvus 两种向量存储方案
3. Milvus 3.0 部署：
   • Docker 部署 Milvus standalone 版本
   • 成功解决权限问题（UID 1000）
   • 安装 Attu 可视化工具
4. 数据库准备：创建商品、仓库、库存、销售、调拨等业务表，并插入测试数据

踩坑记录

下期预告

AI BI Helper 的第二部分——Graph 工作流编排，将实现基于 AI 的智能数据分析与调拨建议自动生成。