EnterpriseKB

EnterpriseKB 是一个可本地运行的企业知识库 RAG 演示项目。它使用 Spring Boot、LangChain4j、PostgreSQL/pgvector、DeepSeek 和本地中文向量模型，实现文档摄取、带引用的流式问答、工具调用 Agent 与离线评估。

本仓库用于学习、评估和本地演示，不是可直接暴露到互联网的生产系统。生产差距见安全与部署边界和 SECURITY.md。

功能

能力	实现
文档摄取	Apache Tika 解析 PDF、Word、PPT、Markdown、TXT；异步切片并写入 pgvector
向量检索	本地 bge-small-zh-v1.5 生成 512 维向量；按 kb_id 过滤；HNSW 余弦索引
可核验回答	SSE 流式输出；答案使用 [n] 标注来源并返回文件名、片段和相似度
会话记忆	按会话保存窗口上下文
工具调用 Agent	在知识库检索、假期余额、IT 工单查询和创建之间自主路由，返回 toolTrace
访问控制	Spring Security、JWT、知识库属主校验和向量 metadata 隔离
离线评估	Recall@K、MRR、引用精确率/召回率、工具路由/参数准确率、回答正确性、groundedness
本地部署	Docker Compose 启动应用和 PostgreSQL 16 + pgvector

架构

Browser (chat UI / SSE)
        |
       JWT
        v
Spring Boot
  |-- auth        Spring Security + JWT
  |-- kb          knowledge-base and document CRUD
  |-- ingestion   Tika -> chunking -> local embeddings -> pgvector
  |-- retrieval   kb_id-scoped search -> prompt context -> citations
  |-- chat         streaming orchestration and conversation memory
  |-- agent        function-calling loop and HR/IT tools
  `-- eval         EvalCase -> Observation -> Score -> Report
        |
        +---- PostgreSQL 16 + pgvector
        `---- DeepSeek-compatible chat API

技术栈：Java 21、Spring Boot 3.3、LangChain4j 1.16、PostgreSQL 16、pgvector、Flyway、Apache Tika、Spring Security、Testcontainers 和 Docker Compose。

数据与信任边界

运行本项目意味着接受以下数据流：

• 文本向量由进程内的 bge-small-zh-v1.5 生成，不调用远端 embedding API。
• 普通问答会把用户问题和检索到的文档片段发送给配置的 DeepSeek-compatible endpoint；Agent 还会发送用户问题、检索片段和工具执行结果，包括假期余额、工单号与工单状态。
• 离线评估还会把生成答案、预期事实和实际引用上下文发送给 judge 模型。
• 上传原文件保存在本地 data/uploads 或 Compose volume；业务数据和向量保存在 PostgreSQL volume。
• 本项目不提供恶意文件扫描。不要上传来源不明的文件。

samples/ 中的制度、人员、工单、地址和 example.com 域名均为合成演示数据，不对应真实企业或个人。除非组织已经审查模型供应商、保留策略、网络路径和数据处理协议，否则不要使用真实机密或个人数据。

快速开始

前置条件：Docker（含 Compose v2）。

cp .env.example .env

# 编辑 .env：
# 1. 填入自己的 DEEPSEEK_API_KEY
# 2. 生成 JWT_SECRET，并把输出写入 .env
openssl rand -base64 48

docker compose up --build

打开 http://localhost:8080。Compose 会拒绝空的 DeepSeek key 或 JWT secret；PostgreSQL 的宿主机端口只绑定到 127.0.0.1:5432。

可选配置：

环境变量	用途	默认值
DEEPSEEK_API_KEY	对话、Agent 和 eval judge	必填
JWT_SECRET	JWT HMAC 密钥，至少 32 个 UTF-8 字节	必填
DEEPSEEK_BASE_URL	OpenAI-compatible API 地址	https://api.deepseek.com
DEEPSEEK_CHAT_MODEL	对话模型	deepseek-chat
STORAGE_DIR	上传文件目录	直接运行时为 ./data/uploads；Compose 使用 /app/data/uploads

演示流程

1. 注册演示账号。
2. 新建知识库“员工自助”。
3. 上传 samples/ 下的 员工手册.md、IT指南.md 和 常见问题FAQ.md。
4. 等待文档状态变为 READY。
5. 尝试以下问题：
   • 入职满一年有几天年假?
   • VPN 连不上怎么办?
   • 公司食堂几点开门?
6. 切换到 Agent 模式，尝试：
   • 我还剩几天年假?
   • 我的打印机坏了，帮我创建工单

工具调用 Agent

POST /api/agent/ask 接收 {kbId, question}，返回 {answer, citations, toolTrace}。

工具	用途
search_kb	检索制度和 FAQ
get_leave_balance	查询当前登录用户的假期余额
lookup_ticket_status	查询当前登录用户的 IT 工单
create_it_ticket	为当前登录用户创建 IT 工单

用户身份只来自 JWT，不是模型参数。Agent 最多执行 5 轮工具调用。

离线评估

评估管线按 EvalCase -> Observation -> Score -> Report 分层：

• 确定性指标：Source Recall@K、MRR、引用 precision/recall、工具 routing/argument accuracy。
• LLM-as-judge：answer correctness 只对照预期事实；groundedness 只对照 Agent 实际使用的完整引用上下文。
• 原始检索、回答、引用和 toolTrace 先写入 observations.jsonl，再执行 judge。
• 单题应用或 judge 失败会保留产物并使进程非零退出；低质量分数本身不会触发质量门禁。

docker compose up -d db
set -a && source .env && set +a
./mvnw spring-boot:run -Dspring-boot.run.profiles=eval

数据集位于 eval/datasets/enterprise-v1/cases.json。每次运行在被 Git 忽略的 eval/results/<run-id>/ 下生成：

• observations.jsonl
• scores.jsonl
• summary.json
• report.md

已验证基线

以下是 2026-08-17 的一次真实本地运行快照，不是长期 SLA 或发布门禁。模型、数据集或参数变化后应重新运行。

条件	值
模型	deepseek-chat
数据集	enterprise-v1，15 题（11 RAG、4 TOOL）
检索参数	top-k 4，min-score 0.5
切片参数	size 1500，overlap 200
完成情况	15/15；observation errors 0；evaluator errors 0

指标	均值	评估数
Source Recall@K	1.0000	11
MRR	0.7273	11
Citation precision	0.3333	11
Citation recall	1.0000	11
Tool routing accuracy	1.0000	15
Tool argument accuracy	1.0000	2
Answer correctness	1.0000	11
Groundedness	0.9773	11

本地开发与测试

# 启动数据库并把 .env 导入当前 shell
docker compose up -d db
set -a && source .env && set +a

./mvnw spring-boot:run

# Testcontainers 会启动隔离的 pgvector；模型使用确定性测试桩
./mvnw test

测试不需要真实 API key。CI 配置位于 .github/workflows/ci.yml。

API

应用启动后可访问 http://localhost:8080/swagger-ui.html。

方法	路径	说明
POST	/api/auth/register	注册
POST	/api/auth/login	登录并返回 JWT
POST / GET	/api/kb	新建或列出知识库
POST / GET	/api/kb/{id}/documents	上传或列出文档
POST	/api/chat/stream	SSE 流式问答
POST	/api/agent/ask	工具调用 Agent

安全与部署边界

Docker Compose 和默认配置只面向本地演示。当前版本包含公开注册和 Swagger，且没有 TLS、速率限制、恶意文件扫描、生产密钥管理、审计日志、备份策略或多实例协调。数据库使用本地演示凭据。

任何互联网或真实企业数据部署都需要先完成独立威胁建模和安全加固。漏洞报告与详细边界见 SECURITY.md。

许可证

项目自有代码采用 MIT License。

本项目通过 LangChain4j 使用 BAAI 的 bge-small-zh-v1.5 模型；其官方模型卡标记为 MIT License。其他依赖遵循各自许可证。