Veridex 是面向企业私有化部署的 RAG(Retrieval-Augmented Generation,检索增强生成)平台。它以「知识库 → 检索 → 带引用回答」为主线,覆盖从文档入库、索引发布、授权问答,到质量评测与运营反馈闭环的完整链路。
应用已提供 backend/web 双容器镜像、Compose 完整应用栈、原生 Helm chart 与受限网络离线交付。
- Phase 1:可执行基础 — 已完成
- Phase 2:知识入库垂直切片 — 已完成
- Phase 3:带权限的 RAG 查询 — 已完成
- Phase 4:质量评测与运营闭环 — 已完成
- Phase 5-b:可观测性与受控 Trace Body — 已完成
- Phase 5:企业试点准备 — 持续进行中
详细阶段目标见交付路线图。
- 本地用户、Session 登录和
PLATFORM_ADMIN/KNOWLEDGE_ADMIN/EMPLOYEE角色 - 知识库创建及 VIEW / MANAGE 授权模型
- PDF、DOCX、TXT、Markdown 文档上传(单文件最大 50 MB)
- MinIO 原始文件和解析结果存储
- PostgreSQL Transactional Outbox + RabbitMQ 异步入库
- Apache Tika 文档解析及结构优先分块
- OpenSearch 全文和向量字段写入
- 不可变 IndexRelease,以及发布、设为当前、离线和删除流程
- 解析文本、Chunk 和文档版本预览
- 重复消息幂等、失败版本隔离及离线立即排除
- 授权知识范围(多知识库交集)上的混合检索(BM25 + 向量 + RRF 融合)
- 有限多轮会话、SSE 流式回答、
[n]引用校验与原文预览 - 依据不足时明确拒答(含
ACCESS_RESTRICTED统一文案) - 版本化评测集(
DatasetVersion不可变快照 + 冻结用例,支持 ANSWER / REFUSE 期望行为) - 不可变 RAG 配置版本(chunking / retrieval / generation / prompt / model 五维草稿 + 发布冻结快照)
- 同步评测运行与自动指标(Recall@K、MRR、NDCG、citation hit、refusal match、latency)
- 两个评测运行的逐指标对比与回归门禁(相对退化 10% 阈值)
- 点赞/点踩反馈落库与坏例转评测集闭环
- 默认
DeterministicEmbeddingModel为 128 维确定性哈希(无语义);可通过VERIDEX_EMBEDDING_PROVIDER=ollama切换 Ollamaqwen3-embedding:0.6b(真实语义,1024 维;同时需设置VERIDEX_EMBEDDING_DIMENSIONS=1024)。 - 默认对话模型由
VERIDEX_CHAT_PROVIDER=deepseek决定(模型deepseek-v4-flash,也可切换ollama);deterministic为测试占位实现。配置 Profile 的chatModel/embeddingModel字段目前仅作标识记录,未接入运行时模型路由(当前单一模型装配)。 - 评测为「仅自动指标」的同步运行;judge-model 自动评判与人工评审尚未实现。
- 回归门禁阈值为硬编码默认值(相对退化 10%),尚未配置化。
- 配置版本(Profile)已同时驱动评测运行与在线问答的检索/生成参数、prompt 模板、会话历史轮数,以及入库时的分块参数;
chatModel/embeddingModel仍仅作标识记录(不做模型路由)。改chunking后,仅对之后新入库的文档生效,存量文档需重新入库才会按新参数重切。 - PDF / DOCX 的结构识别较基础;没有 Markdown 标题时主要按文本长度分块。
- 失败消息进入 DLQ;自动重试、退避以及 Outbox 定时恢复仍待增强。
| 区域 | 技术 |
|---|---|
| 后端 | Java 21、Spring Boot 4、Spring Modulith、Spring Data JPA、Spring Security、Spring AI 2 |
| 前端 | React 19、TypeScript、Vite、Vitest |
| 业务数据库 | PostgreSQL 17 |
| 消息队列 | RabbitMQ 4 |
| 对象存储 | MinIO |
| 检索索引 | OpenSearch 3.2 |
| 会话存储 | PostgreSQL(Spring Session JDBC,迁移 V15) |
| 文档解析 | Apache Tika 3 |
| 集成测试 | JUnit、Testcontainers |
.
├── backend/ Spring Boot 模块化单体
├── web/ React + Vite 管理控制台
├── deploy/compose/ 本地基础设施 Compose 配置
├── docs/ 架构、路线图和专题文档
├── scripts/verify.sh 项目一键质量门禁
├── pom.xml Maven 父项目
└── mvnw Maven Wrapper
- Compose 完整应用栈:
deploy/compose/compose.yml(基础设施 + backend + web),冒烟验收deploy/compose/smoke.sh。 - 原生 Helm chart:
deploy/helm/veridex(双端口 Service、existing Secret、Ingress/PDB/HPA/NetworkPolicy/ServiceMonitor)。 - 部署门禁:
scripts/verify-deployment.sh(镜像、Compose 栈、Helm lint/template 矩阵、kind 集群验收、离线交付包)。 - 受限网络离线交付:
deploy/offline/生成离线包,安装步骤见deploy/offline/veridex-offline/INSTALL.txt。
⚠️ 无论哪种部署方式,都要先把 Chat 与 Embedding 模型配成真实 provider,不要用默认deterministic(详见 配置说明)。
⚠️ 必须先配好模型,否则问答检索跑不出真实结果。 默认的deterministicembedding 是 128 维无语义哈希,向量检索基本没用;deepseek对话模型必须提供VERIDEX_DEEPSEEK_API_KEY。启动前请按 配置说明 把VERIDEX_CHAT_PROVIDER与VERIDEX_EMBEDDING_PROVIDER都配成真实模型,不要用默认值。
启动基础设施、后端和前端三个部分:
# 1. 启动基础设施(PostgreSQL / RabbitMQ / MinIO / OpenSearch)
docker compose -f deploy/compose/compose.yml up -d
# 2. 启动后端(已配好 chat/embedding 模型后)
./mvnw -pl backend spring-boot:run
# 3. 启动前端(另开终端)
npm --prefix web ci
npm --prefix web run dev访问 http://localhost:5173,使用 admin / veridex 登录。完整的环境要求、分步说明、服务地址与默认账号、停止清理见快速启动指南。
| 主题 | 文档 |
|---|---|
| 快速启动与环境 | docs/getting-started.md |
| 配置与模型 provider | docs/configuration.md |
| 架构、部署拓扑与可观测性 | docs/architecture.md |
| 知识入库管道 | docs/knowledge-ingestion-pipeline.md |
| RAG 配置参数语义 | docs/rag-configuration-parameters.md |
| 容量与恢复报告 | docs/capacity-report-2026-08.md |
Copyright 2026 Xinghua Zhou。本项目以 Apache License 2.0 开源(见 LICENSE、NOTICE)。
选它的理由:与所依赖的 Spring Boot / Spring AI / Spring Modulith 全栈一致(均 Apache 2.0),并附带显式专利授权。所依赖的第三方组件(后端 Spring 生态为 Apache 2.0、PostgreSQL JDBC 为 BSD 2-Clause,前端 React / React Router 等为 MIT)均为宽松许可,各自保留其原始许可,本项目不对其再许可;完整清单见 NOTICE。
欢迎贡献!请先阅读贡献指南与行为准则。安全漏洞请按 SECURITY.md 所述方式私下报告,不要通过公开 issue 披露。变更历史见 CHANGELOG.md。