PROJECT 01

一心 yixn · 企业级 RAG 知识库

把散落在 PDF / Word / TXT 里的非结构化知识，变成员工可以直接提问、并且每条结论都能点回原文的知识资产。

角色: 独立开发
周期: 2025.12 — 2026.03
项目重点: 检索链路 · 异步流水线 · 工程落地

这个项目解决什么问题

企业积累了大量文档，但传统文件管理方式让知识变成孤岛：员工找不到、 看不懂、不敢信。

一心用 RAG（检索增强生成）把这条链路打通：

上传文档 → 自动解析 → 语义切片 → 向量化入库 → 自然语言提问 → 在权限范围内检索 → 基于原文作答并标注来源。

系统支撑多租户（组织标签层级隔离）与角色权限，保证不同部门只能看到自己该看的内容。

核心能力

混合检索

Elasticsearch 一次查询内完成「2048 维向量语义召回 + BM25 关键词精排」，兼顾召回率与准确率，而不是二选一。

Agentic RAG

由模型自主决定是否调用知识库检索、内容总结等工具进行多轮推理；回答标注来源编号，可点击溯源到原文与页码。

大文件分片上传与断点续传

5MB 分片、单文件 4 路并发；分片存 MinIO，Redis Bitmap 记录分片状态、MySQL 兜底；中断后仅补传缺失分片，避免整体重传。

异步文档流水线

上传不阻塞：Kafka 事务投递 → 解析（PDF / Office / Tika）→ 语义切片 → 向量化 → 入库；消费失败按固定退避重试后进入死信主题，并持久化向量化状态与失败原因。

流式对话链路

WebSocket 长连接逐字输出；支持主动中断，并同步取消上游模型请求 —— 只停前端推送是不够的，不取消上游模型还在按 token 计费。

多租户与权限

角色鉴权 + 组织标签层级继承 + 文档公开属性，权限条件直接下推到检索查询层，而不是查到之后再过滤。

成本治理

Token 配额两阶段记账（预占 → 结算 / 回滚）、流式用量精确计量、多模型供应商运行时热切换。

我做了什么

1. 从零部署与工程化

独立完成 MySQL / Redis / MinIO / Kafka / Elasticsearch 五服务的 Docker 编排与调优，定位并修复了 23 处部署配置问题，并补齐一键启停、崩溃自愈脚本与部署手册。

2. 前端品牌与界面重构

重做登录页（左右分栏品牌布局）与对话页空态（欢迎屏 + 可点击推荐问题卡），统一全站品牌与主题视觉。

3. 缺陷定位与修复

排查并修复多个线上问题，例如 Nginx 未识别 .mjs 的 MIME 导致 PDF 预览失败、 MinIO 预签名 URL 因替换 host 破坏 SigV4 签名导致 403、Kafka 消费端未开启事务读隔离等。

三个值得说的坑

MinIO 预签名 URL 与 SigV4
把签名 URL 里的内网 host 替换成公网 host，会破坏 X-Amz-SignedHeaders=host 的签名，直接 403。最终让 MINIO_ENDPOINT 与 MINIO_PUBLIC_URL 保持一致才解决。

一个 .mjs 文件导致白屏
Nginx 1.18 的 mime.types 不含 mjs，PDF 预览用的 worker 被当成 application/octet-stream 返回，浏览器拒绝执行。

事务消息「只做了一半」
生产端开启了事务与幂等，消费端却没配 isolation.level=read_committed —— 这类「看起来配了、其实没闭环」的问题最难发现。

技术栈

Java 17Spring Boot 3.4Spring Security + JWT Spring Data JPAMySQL 8Redis 7 MinIOKafkaElasticsearch 8.10 IK 分词Apache TikaWebSocket DeepSeek API阿里云百炼 text-embedding-v4 Vue 3TypeScriptVitePinia