摘要：本文介绍开源项目 VeapAI，它用一套平台打通了文档资料、知识库、向量化与 Milvus 大模型问答溯源等 8 个环节。文章围绕页级溯源能力、检索质量保障、向量化审计与幂等设计等工程细节展开，同时明确当前 V1 阶段的技术边界，并给出后端与前端的上手步骤，适合关注企业知识库问答与 Milvus 落地的开发者阅读。
# 开源项目 VeapAI 简介：一套平台打通 AI 知识库全链路
> 分类：资讯 / 开源推荐 | 目标平台：CSDN、知乎、掘金、OSCHINA（总览稿，全平台首发）
做企业知识库问答的人，大多经历过同一条弯路：文档上传了，切块切了，向量也写进去了，真到用户问“这段话出自哪份文件的哪一页”时，答不上来。问得再具体一点，比如“预算法中关于项目类别的定义，原文在第几页”，系统要么瞎编页码，要么给一段没有出处的文字。
VeapAI 是我在维护的一个开源项目，它把这条链路整段做进了平台里。项目地址：https://gitee.com/mindock/veap
## 它做了什么
一句话讲完：一套代码，跑通「文档资料 → 知识库 → 向量化（Milvus）→ 大模型问答溯源」8 个环节，全程界面配置。
后端是 Java 17 + Spring Boot 2.7 + Spring Cloud，前端 Vue 2.6 + Element-UI，向量库接 Milvus 2.4.x，MIT 协议，当前版本 3.6.5。
8 个环节按顺序是：
1. 配置 Milvus 实例（认证、TLS、健康检查）
2. 创建元数据标准，由标准声明式创建 / 更新 Collection
3. 创建知识主题
4. 上传附件资料并解析（统一 PDF 预览 + 页级片段）
5. AI 资料处理，初始化知识内容
6. 知识主题一键向量化
7. Milvus 调试搜索，初验证
8. 政策问答：知识搜索、溯源、文档在线定位预览
![知识全生命周期八步流程]
全链路分层架构（UI 配置层 → 业务模型层 → 向量作业层 → Milvus 引擎层 → 问答应用层）：
![全链路架构图]
第 8 步是这条链路的验收点。问答结果里的命中知识点，每个都能回到原文那一页、那一段。做到这一点的不是“把页码塞进提示词”的野路子，是数据库里一整套页级映射：`ai_doc_content` 记录页级片段，`ai_knowledge_entry_source` 把知识点精确挂到片段上，`locator_json` 是打开预览时定位的唯一依据。
## 为什么值得看源码
如果只是 8 个按钮，不值一篇资讯稿。这套代码在工程细节上有几处较真的地方：
– **检索质量决定生成上限**。检索参数不是散在问答代码里的魔法数字，检索模板固定 TopK、阈值、过滤表达式，每次调试检索写一条 `ai_vector_search_audit`，调参有据可查。
– **一张表一个唯一写入点**。`ai_vector_object_map` 只允许 `AiVectorIngestJobRunner` 写，旁路 CRUD 被禁止。业务对象和 Milvus 主键的映射一旦错账，删向量都删不干净。
– **job / run / item 三级审计**。一次向量化运行一条 run，每个对象一条 item，成功 / 跳过 / 失败逐条可查。跑挂了不靠猜。
– **ETag 幂等**。映射表用内容 hash + 嵌入模型 ID 决定要不要重算。文档没改就不重算向量，省的不止是钱，还有等待时间。
– **Milvus 操作禁止吞错**。每次运维操作写 `ai_milvus_op_log`，失败必须抛出来。吞错是这类系统的慢性病，这里在表设计层面就拦了。
– **没有向量就别硬聊**。问答候选匹配找不到启用作业时返回空列表、不兜底——宁可空结果，也不让模型瞎编出处。
这套东西我们团队自己踩坑踩出来的。早期版本向量写入失败就打印个日志继续跑，结果 Milvus 里少了一批数据，问答回表全是空。后来才定的“禁止吞错”这条规矩。
## 边界也得说清楚
V1 阶段有几个限制，别期待错了：
– 向量化对象类型冻结为 `knowledge_entry` 一种，代码里 `VectorObjectTypes` 常量只放了一个值；
– 向量作业的 source 只认知识主题（`source_config` 里的 `topicId`），不支持按标准全量扫；
– 文档解析引擎按文件类型选：扫描件走 PaddleOCR，电子文档走 office-pdf-text / pdf-text。
这些限制都写在代码和设计文档里，不是藏着掖着。
## 怎么上手
```bash
# 后端（单体模式）
cd veap-cloud
mvn -B -pl veap-package/veap-monolith -am -DskipTests package
# 前端
cd veap-ui
npm install
npm run dev # http://localhost:80
```
AI 能力相关表结构在 `veap-cloud/DB/veap.sql`，40 来张表，核心链路就 15 张。
接下来我会分 8 篇把这条链路逐步拆开：每一篇对应一个环节，讲表设计、讲源码走读、讲踩过的坑。想直接看代码的，去 Gitee 仓库翻，源码和设计文档都在里面。
仓库：https://gitee.com/mindock/veap
