LangChain4j+pgvector+Redis构建AI文档问答系统-平芜编程栈

CloudVault：LangChain4j + RAG + PostgreSQL/pgvector + Redis 打造仿百度网盘的 AI 文档问答系统

这次来看一个工程味道很足的项目：CloudVault。它不是一个纯粹的 RAG demo，也不是一个只有上传下载功能的网盘，而是一个把“文件管理”和“AI 文档问答”串起来的完整后端系统。技术栈集中在 Java 生态：LangChain4j 负责 RAG 问答编排，PostgreSQL + pgvector 存向量并做相似度检索，Redis 做缓存、分布式锁和实时通知的辅助通道，WebSocket 负责把任务状态推给前端界面。

核心流程很直接：用户上传文档后，系统会自动解析并切片，调用 Embedding 模型生成向量，写入 pgvector；用户提问时，先把问题向量化，在 pgvector 里检索相关片段，再拼装成 Prompt，交给 LLM 生成答案。整个过程围绕文件生命周期展开，所以很适合做企业内部知识库、团队文档检索、个人网盘 AI 搜索这类场景。

本文会从系统架构开始，逐步拆解数据库设计、LangChain4j 的 RAG 接入、Redis 实时通知、Docker Compose 快速启动、接口 API 调用示例、批量任务思路和常见问题排查。目标读者是已经熟悉 Spring Boot 基础、想落一套“网盘 + 向量检索 + 文档问答”组合方案的 Java 后端开发者。阅读完，你能得到一份可以直接照着搭的架构和代码骨架。

1. 核心能力速览

CloudVault 本身是一个后端服务，核心能力集中在文件管理与 AI 问答的结合。

项目类型	Java / Spring Boot 后端服务，仿百度网盘功能 + RAG 文档问答
核心功能	文件上传下载、文档解析切片、向量化索引、RAG 文档问答、实时通知、缓存
技术栈	LangChain4j、Spring Boot、PostgreSQL、pgvector、Redis、WebSocket
向量检索	pgvector 存储文本向量，支持 HNSW 或 IVFFlat 索引
AI 问答	基于文档内容的 RAG 问答，问题上下文来自文件中检索到的相关片段
实时通知	Redis + WebSocket 推送上传完成、索引完成、问答完成等状态
是否支持 API	支持，可提供文件服务、索引任务、问答接口等 HTTP 接口
是否支持批量任务	适合做批量导入、批量建索引、批量问答结果导出
推荐部署环境	JDK 17 + Maven 3.8+ + Docker（PostgreSQL、Redis）
GPU 要求	CloudVault 本体不需要 GPU；GPU 取决于你接入的 LLM / Embedding 服务
适合场景	企业知识库、技术资料管理、团队文档问答、个人网盘 AI 搜索

从材料看，这个项目的关键卖点不是“网盘本身多复杂”，而是把文件管理、向量检索、AI 问答和实时通知组合成了一条可工程化的链路。如果你只是想要一个网盘，那没必要上 pgvector 和 LangChain4j；如果你希望“上传一堆文档后，能直接问里面的内容”，这套组合就是比较典型的落地方案。

2. 系统架构与模块划分

CloudVault 的架构可以按职责拆成下面几个模块，每个模块彼此独立，通过 Spring 容器和消息通道串联。

2.1 文件管理模块

负责文件上传、下载、删除、分享链接生成和目录管理。文件物理存储可以放在本地磁盘或对象存储，数据库只保存文件元数据。上传成功后，会触发异步索引任务，这是网盘场景里最基础的链路。

2.2 文档解析与索引模块

这是 RAG 的入口。文件上传后，根据扩展名选择解析器：文本文件直接读取，Markdown 文件保留结构，PDF / Word 类文件先用解析库抽取文本。解析完成后，按固定大小或语义边界做切片，再调用 Embedding 模型把每个切片转成向量，写入 PostgreSQL 的 pgvector 表。

2.3 RAG 问答模块

用户提交问题时，系统先向量化问题，再在 pgvector 中检索最相关的 N 个文本片段，把片段内容拼进 Prompt，调用 ChatLanguageModel 生成答案。为了让答案可追溯，返回结果中应该带上命中的文件 ID 和片段原文。

2.4 缓存与协同模块

Redis 在其中承担三类职责：缓存热点文件元数据和问答结果；用 SETNX 实现索引任务的分布式锁，避免同一个文件被并发重复索引；还可以借助 Redis 的 Pub/Sub 做轻量级事件通知。

2.5 实时通知模块

基于 WebSocket 协议，服务端把文件上传完成、索引完成、问答任务完成、文件分享等事件推送到前端。配合 Redis，可以做到多实例部署时的事件广播，避免只有单个 WebSocket 节点能收到消息。

这套架构把 RAG 和传统业务系统放在一起考虑，值得借鉴的点在于：文件上传不是终点，而是索引任务的起点；用户问答不是简单的 LLM 调用，而是先做检索再生成；通知不是只靠轮询，而是由服务端主动推送。

3. 适用场景与使用边界

3.1 适合谁用

团队内部文档管理：把散落的 Markdown、Word、PDF 集中到一个系统里，支持按内容提问。
企业知识库问答：用 RAG 的方式让员工直接问“报销流程是什么”“某个项目的服务器地址在哪”，答案都来自内部文档。
个人资料库：上传自己的技术笔记后，用自然语言检索过去写过的内容。
Java 技术栈团队：想研究 LangChain4j 如何与 Spring Boot 集成，并落在真实业务里。

3.2 不适合什么场景

对文件管理要求极高、需要在线预览 Office、秒传、断点续传、版本回滚的完整网盘产品，需要额外扩展能力。
需要高并发在线编辑协作的场景，这不是 CloudVault 的定位。
对 AI 回答准确性要求极其严格，且不允许出现幻觉的场景，不能只靠 RAG 裸输出，必须先加人工审核或答案引用校验。

3.3 合规与安全边界

涉及网盘和 RAG 问答，必须把授权和隐私放在第一位。用户上传的文档可能包含版权材料、个人隐私、公司机密，因此系统需要有清晰的权限隔离：谁能看到哪个目录，谁能检索哪个文件，答案中拼接的片段是否越权，都要在检索层做过滤。RAG 使用的文档只能来自用户有权限访问的文件。AI 生成的答案可能存在幻觉，不应直接作为医疗、法律、财务等高风险领域的最终结论。如果后续接入人脸、声音、视频等模态能力，还要额外确认素材授权和数据脱敏。

4. 环境准备与前置条件

4.1 基础软件

组件	建议版本	用途
JDK	17 及以上	运行 Spring Boot 服务
Maven	3.8 及以上	构建项目、拉取依赖
PostgreSQL	14 及以上，建议 16	业务数据与向量数据存储
pgvector	与 PostgreSQL 版本匹配的最新版	扩展向量类型与索引
Redis	6.x 或 7.x	缓存、分布式锁、事件通道
Docker / Docker Compose	可选但推荐	快速启动 PostgreSQL 和 Redis

4.2 模型服务准备

CloudVault 本身不训练模型，它像一个调度器，依赖外部的 LLM 和 Embedding 服务。你可以选择：

OpenAI 兼容接口：很多云厂商和本地推理服务都提供v1/chat/completions形态接口。
本地 Ollama：在开发机上跑一个小模型做测试，但此时需要关注本机内存和 GPU。
企业内网模型服务：通过自定义 Base URL 接入，避免数据出内网。

如果你在本地用 Ollama 或 llama.cpp 跑 7B 级模型，显存占用一般在 6GB 到 12GB 不等，具体要看量化方式和上下文长度。如果只是 CloudVault 本身的编译启动，不需要 GPU。

4.3 快速检查清单

java -version mvn -version docker --version

确保 Docker 能正常拉镜像，本地 5432 和 6379 端口没有被占用。如果你已经装了本地 PostgreSQL，要确认是否安装了 pgvector 插件；如果没有，直接使用 Docker 镜像会更快。

5. 数据库设计与 pgvector 接入

5.1 创建数据库并启用向量扩展

进入 PostgreSQL 后，先建库再启用插件。

CREATE DATABASE cloudvault; \c cloudvault CREATE EXTENSION IF NOT EXISTS vector;

如果提示 extension 不存在，说明 pgvector 没有安装成功。Docker 场景下推荐直接使用带 pgvector 的镜像，省去手动编译。

5.2 基础表设计

文件表保存网盘文件的基本信息：

CREATE TABLE files ( id BIGSERIAL PRIMARY KEY, file_id VARCHAR(64) UNIQUE NOT NULL, file_name VARCHAR(255) NOT NULL, file_path TEXT NOT NULL, file_size BIGINT DEFAULT 0, owner_id BIGINT NOT NULL, status VARCHAR(32) DEFAULT 'UPLOADED', created_at TIMESTAMP DEFAULT now(), updated_at TIMESTAMP DEFAULT now() );

文档切片表用来保存每一个被索引的文本块：

CREATE TABLE file_documents ( id BIGSERIAL PRIMARY KEY, file_id VARCHAR(64) NOT NULL, chunk_index INT NOT NULL, chunk_text TEXT NOT NULL, embedding vector(1024), -- 维度按 Embedding 模型实际输出调整 created_at TIMESTAMP DEFAULT now() ); CREATE INDEX idx_file_docs_file_id ON file_documents(file_id);

这里的vector(1024)只是一种示例。实际维度必须与 Embedding 模型输出对齐，比如某些模型的维度是 768，某些是 1024，甚至更高。维度不一致会在 INSERT 时直接报错。

5.3 向量索引

当切片数据量大的时候，必须建向量索引，否则相似度检索会全表扫描，速度不可接受。pgvector 提供 HNSW 和 IVFFlat 两种索引，HNSW 查询精度和速度比较均衡，适合大多数场景。

CREATE INDEX ON file_documents USING hnsw (embedding vector_cosine_ops);

在 LangChain4j 的 SQL 日志里，你会看到它实际执行的是通过 cosine 距离取 Top N 的查询。索引建立了，单次检索可以在毫秒级返回，但数据量很小的时候不一定体现得出来。

5.4 LangChain4j 的 pgvector 配置

在 Spring Boot 的配置文件中，数据源和向量存储指向同一个数据库。

spring: datasource: url: jdbc:postgresql://localhost:5432/cloudvault username: cloudvault password: change-me redis: host: localhost port: 6379

关键点在于：不要让 LangChain4j 的 pgvector 集成自己去建第二个连接池。直接复用 Spring 的DataSource，保证事务一致性和连接资源可控。

6. LangChain4j + RAG 文档问答实现

6.1 引入依赖

在pom.xml中加入 LangChain4j 核心、OpenAI 兼容模型模块和 pgvector 模块。具体版本号请按项目实际环境锁定。

<dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j</artifactId> <version>${langchain4j.version}</version> </dependency> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-open-ai</artifactId> <version>${langchain4j.version}</version> </dependency> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-pgvector</artifactId> <version>${langchain4j.version}</version> </dependency>

6.2 模型配置

用 OpenAI 兼容协议接入内容生成模型和 Embedding 模型。base-url指向你们内部的 LLM 网关或 Ollama 服务地址。

langchain4j: open-ai: chat-model: base-url: http://your-llm-server/v1 api-key: demo-key model-name: your-chat-model-name temperature: 0.2 embedding-model: base-url: http://your-llm-server/v1 api-key: demo-key model-name: your-embedding-model-name

这里没有任何本地显存压力，所有计算都发生在模型服务侧。CloudVault 这边只负责文本切分、调用接口和保存返回结果。

6.3 文档切片与向量化

文档上传后，按文件类型解析文本。文本很长时，直接用固定 chunk 大小切分，通常 500 到 1000 个字符比较稳妥，同时保留一个 overlap，避免切断语义。

public List<TextSegment> splitText(String text) { Document document = Document.from(text); DocumentSplitter splitter = DocumentSplitters.recursive(600, 80); return splitter.split(document); }

recursive(600, 80)的意思是每个片段约 600 字符，重叠 80 字符，保证上下文连贯。拿到TextSegment列表后，调用 EmbeddingModel 生成向量，再写入 pgvector。

List<TextSegment> segments = splitText(rawText); List<Embedding> embeddings = embeddingModel.embedAll(segments) .content() .stream() .map(Result::content) .toList(); embeddingStore.addAll(embeddings, segments);

注意不同版本 LangChain4j 的 API 命名可能有差异，比如embedAll返回值可能是Response<List<Embedding>>，写法要跟随你锁定的版本。

6.4 RAG 问答核心流程

问答服务是核心流程：先向量化问题，再检索最相关的片段，拼装 Prompt，最后交给 ChatLanguageModel 生成。

@Service public class RagService { private final ChatLanguageModel chatModel; private final EmbeddingModel embeddingModel; private final EmbeddingStore<TextSegment> embeddingStore; public RagService(ChatLanguageModel chatModel, EmbeddingModel embeddingModel, EmbeddingStore<TextSegment> embeddingStore) { this.chatModel = chatModel; this.embeddingModel = embeddingModel; this.embeddingStore = embeddingStore; } public String answer(String userQuestion) { Embedding questionEmbedding = embeddingModel.embed(userQuestion).content(); List<EmbeddingMatch<TextSegment>> matches = embeddingStore.findRelevant(questionEmbedding, 5); String context = matches.stream() .map(match -> match.embedded().text()) .collect(Collectors.joining("\n---\n")); String prompt = """ 请根据下面的文档片段回答用户问题。 如果片段中没有足够信息，请直接说明“当前文档中未找到相关内容”。 文档片段： %s 用户问题： %s """.formatted(context, userQuestion); return chatModel.generate(prompt); } }

检索到的片段数量不宜太多。Top 3 到 Top 5 通常足够，太多会稀释 Prompt 中的有效信息，同时增加 token 消耗。

6.5 更完整的 RAG 链路

如果你用的 LangChain4j 版本支持ContentRetriever和RetrievalAugmentor，可以把检索器进一步封装，让 LangChain4j 在每次 Chat 时自动完成“检索 -> 组装 -> 生成”。

ContentRetriever retriever = EmbeddingStoreContentRetriever.builder() .embeddingStore(embeddingStore) .embeddingModel(embeddingModel) .maxResults(5) .minScore(0.6) .build(); RetrievalAugmentor augmentor = DefaultRetrievalAugmentor.builder() .contentRetriever(retriever) .build(); ChatLanguageModel ragModel = OpenAiChatModel.builder() .baseUrl("http://your-llm-server/v1") .apiKey("demo-key") .modelName("your-chat-model-name") .build() .toBuilder() // 具体绑定方式以实际版本 API 为准 .build();

这种写法更贴近 LangChain4j 官方推荐的“自动 RAG”形态，但 API 变化较快，实践时以官方文档或你锁定的版本源代码为准。

7. Redis 缓存与分布式锁

Redis 在整个系统中的角色非常多，这里说三个最典型的用法。

7.1 热点缓存

文件列表、问答结果这类读取频率高但更新不频繁的数据，适合放在 Redis 里。

@Service public class FileCacheService { private final StringRedisTemplate redisTemplate; public FileCacheService(StringRedisTemplate redisTemplate) { this.redisTemplate = redisTemplate; } public void cacheFileMeta(String fileId, String metaJson) { redisTemplate.opsForValue().set("FILE_META:" + fileId, metaJson, Duration.ofMinutes(30)); } public String getFileMeta(String fileId) { return redisTemplate.opsForValue().get("FILE_META:" + fileId); } }

缓存过期时间要根据业务定。文件元数据短时间内变化不大，30 分钟比较合适。问答结果如果希望减少重复调用 LLM，也可以按相同问题做短时间缓存，但要注意用户问题千变万化，缓存命中率可能不高。

7.2 索引任务分布式锁

同一个文件可能被用户重复点击“重新索引”，如果服务多实例部署，并发处理同一个文件会浪费资源。这里用 Redis 的SETNX做一个简单锁。

public boolean tryAcquireIndexLock(String fileId) { return Boolean.TRUE.equals(redisTemplate.opsForValue() .setIfAbsent("INDEX_LOCK:" + fileId, "LOCKED", Duration.ofMinutes(10))); }

锁的过期时间要大于任务最大执行时间，否则任务还没跑完锁就释放了。更稳妥的做法是任务结束后主动删锁，并配合 Lua 脚本比较 value 再删除，避免误删其他实例加的锁。

7.3 Redis Pub/Sub 与多实例通知

WebSocket 连接绑定在某一个实例上。当用户在实例 A 上传文件，索引任务却在实例 B 执行完毕时，需要把完成事件广播到所有实例，让持有 WebSocket 会话的实例推送给前端。Redis Pub/Sub 天然适合这种轻量级广播。

redisTemplate.convertAndSend("cloudvault:notification", payloadJson);

消费端监听该频道，再通过SimpMessagingTemplate推给对应的 WebSocket 会话。

8. 实时通知机制：WebSocket + Redis

实时通知用于解决“任务做完后怎么告诉用户”的问题。典型场景包括：文件上传完成、索引建立完成、问答任务完成、文件分享成功。

8.1 配置 WebSocket

@Configuration @EnableWebSocketMessageBroker public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { @Override public void configureMessageBroker(MessageBrokerRegistry registry) { registry.enableSimpleBroker("/topic"); registry.setApplicationDestinationPrefixes("/app"); } @Override public void registerStompEndpoints(StompEndpointRegistry registry) { registry.addEndpoint("/ws") .setAllowedOriginPatterns("*") .withSockJS(); } }

简单模式下，/topic前缀的消息会直接广播给订阅了对应地址的客户端。生产环境如果想做多节点广播，可以把enableSimpleBroker换成一个完整的消息代理，并用 Redis Pub/Sub 做事件桥接。

8.2 推送任务状态

索引任务完成后，推送一条 JSON 消息给对应用户。

@Service public class NotificationService { private final SimpMessagingTemplate messagingTemplate; private final StringRedisTemplate redisTemplate; public NotificationService(SimpMessagingTemplate messagingTemplate, StringRedisTemplate redisTemplate) { this.messagingTemplate = messagingTemplate; this.redisTemplate = redisTemplate; } public void notifyIndexFinished(Long userId, String fileId, String status) { String payload = """ { "type": "INDEX_FINISHED", "fileId": "%s", "status": "%s", "time": "%s" } """.formatted(fileId, status, LocalDateTime.now()); messagingTemplate.convertAndSend("/topic/user/" + userId, payload); redisTemplate.convertAndSend("cloudvault:notification", payload); } }

前端订阅地址为/topic/user/{userId}，需要在 WebSocket 建立连接时带上鉴权信息，避免越权订阅其他人频道。

8.3 前端订阅示例

const socket = new SockJS('/ws'); const stompClient = Stomp.over(socket); stompClient.connect({}, function () { stompClient.subscribe('/topic/user/1001', function (message) { const data = JSON.parse(message.body); if (data.type === 'INDEX_FINISHED') { console.log('索引完成', data.fileId, data.status); } }); });

9. 快速启动与验证流程

9.1 使用 Docker Compose 启动依赖

这里提供一个开发环境用的 Compose 配置。pgvector/pgvector:pg16镜像自带 PostgreSQL 16 和 pgvector 插件，适合本地快速拉起数据库。

services: postgres: image: pgvector/pgvector:pg16 container_name: cloudvault-pg environment: POSTGRES_USER: cloudvault POSTGRES_PASSWORD: change-me POSTGRES_DB: cloudvault ports: - "5432:5432" volumes: - pgdata:/var/lib/postgresql/data redis: image: redis:7 container_name: cloudvault-redis ports: - "6379:6379" volumes: pgdata:

启动依赖：

docker compose up -d

检查容器状态：

docker ps docker logs cloudvault-pg

9.2 启动 Spring Boot 服务

mvn clean package -DskipTests java -jar target/cloudvault.jar

Java 服务默认监听 8080 端口。如果端口冲突，可以加--server.port=8081。启动日志里如果看到数据库连接成功、Redis 连接成功、模型服务连接测试通过，说明前置准备做完。

9.3 第一条验证链路

上传一个 Markdown 文件。
观察日志中是否出现分片、Embedding 生成、pgvector INSERT 记录。
检查file_documents表中的向量数据条数。
提交一个与文档内容相关的问题。
看接口返回的答案是否引用了文档片段。
打开 WebSocket 页面，确认前端收到索引完成和问答完成通知。

这一步能走到第 4 步，说明 RAG 链路已经通；走到第 6 步，说明实时通知模块也正常。

10. 接口 API 与批量任务

10.1 主要接口

接口	方法	作用
/api/files/upload	POST	上传文件并触发异步索引
/api/files/{fileId}	GET	获取文件元数据
/api/files/{fileId}/content	GET	获取文件解析后的文本
/api/files/{fileId}/index	POST	手动触发索引任务
/api/ask	POST	基于已索引文档进行 RAG 问答
/api/notifications	WS	WebSocket 实时通知通道

10.2 上传文件

curl -X POST http://localhost:8080/api/files/upload \ -H "Authorization: Bearer <token>" \ -F "file=@./README.md"

预期返回数据中包含fileId。服务端收到文件后，会先保存文件，再异步执行文本解析与向量化。

10.3 发起问答

curl -X POST http://localhost:8080/api/ask \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <token>" \ -d '{ "question": "这个项目的核心功能是什么？", "fileIds": ["FILE_001", "FILE_002"] }'

fileIds用于限定检索范围，让用户只在自己有权限的文件里检索。这个设计比“全库检索”更安全，也更符合网盘产品的权限模型。

10.4 批量任务

批量任务是 RAG 平台真正要关心的能力。常见批量场景有：

批量导入历史文档并建索引。
定期对新增文件执行索引任务。
对一批预置问题跑问答回归，验证知识库效果。

实现上可以用一张任务表和异步线程池。任务表记录文件 ID、状态、错误信息、开始和结束时间。

CREATE TABLE index_tasks ( id BIGSERIAL PRIMARY KEY, task_type VARCHAR(32) NOT NULL, file_id VARCHAR(64) NOT NULL, status VARCHAR(32) DEFAULT 'PENDING', error_msg TEXT, created_at TIMESTAMP DEFAULT now(), updated_at TIMESTAMP DEFAULT now() );

任务提交后，扫描器不断拉起PENDING状态的任务。执行成功改成SUCCESS，失败改成FAILED并写入尝试次数。每次重试要有最大次数限制，同时把错误信息记录清楚，方便运维定位。

@Scheduled(fixedDelay = 5000) public void scanTasks() { List<IndexTask> pendingTasks = taskMapper.findByStatus("PENDING"); for (IndexTask task : pendingTasks) { taskExecutor.execute(() -> executeIndexTask(task)); } }

这里只是给出通用任务扫描逻辑。实际项目中，推荐在批量任务里加上每一条任务的日志输出、耗时统计和失败重试队列，避免任务堆在一个线程池里互相影响。

11. 资源占用与性能观察

11.1 CloudVault 本体

CloudVault 是一个 Java 服务，资源占用取决于连接数、任务并发和文档大小。正常开发环境，给它 2 到 4 GB 内存比较稳妥。CPU 消耗主要在文本解析、Embedding 转换和 JSON 序列化，实测时你可以用top或jstat观察。

11.2 模型服务侧

真正的算力开销在接入的 LLM / Embedding 服务上。如果使用云端 API，本机只消耗网络 IO；如果本地部署 7B 级模型，显存通常需要 6GB 以上，量化模型会降低一些要求，但要关注并发请求时的峰值显存。具体数字必须按你的模型和推理框架实测，不建议凭感觉定资源规格。

11.3 数据库与 Redis 观察

启动后重点观察 PostgreSQL 连接池和 Redis 内存。

docker stats

看cloudvault-pg和cloudvault-redis的 CPU 和内存。向量索引建立后，跑几条问答，观察file_documents表的查询耗时。如果检索明显变慢，优先检查是否建了 HNSW 索引，以及查询是否命中了索引。

11.4 性能优化方向

向量检索：限制每次问答只检索 Top 5 或 Top 10。
缓存：对高频访问的文件元数据、热点问答结果做 Redis 缓存。
异步化：文档解析、向量化、索引更新全部放到任务队列，避免阻塞上传接口。
连接池：MySQL 和 Redis 连接池都要设置合理上限，避免线程堆积。
分批写入：批量 embedding 后一次性写入 pgvector，不要一条一条 INSERT。

12. 常见问题与排查方法

问题现象	可能原因	排查方式	解决方案
CREATE EXTENSION vector 报错	PostgreSQL 没有安装 pgvector	登录数据库查看已安装扩展	换用 pgvector/pgvector 镜像或编译安装
向量字段类型不存在	建表时 extension 未生效	执行`\dx`查看扩展列表	先`CREATE EXTENSION`再建表
LangChain4j 连接模型超时	Base URL 或模型服务不可达	用 curl 测试`/v1/chat/completions`	修正 URL、检查鉴权或网络策略
Embedding 维度与 vector 字段不一致	模型输出维度与建表维度不同	打印向量长度	修改表字段维度或换模型
Redis 连接拒绝	Redis 未启动或配置错误	`redis-cli ping`	启动 Redis，检查地址和密码
WebSocket 页面连不上	前端地址或鉴权错误	看浏览器 Network 面板	检查`/ws`路径和 Stomp 订阅地址
文件上传后索引没生效	异步任务失败或队列未消费	查看`index_tasks`表和日志	修复解析异常或任务执行器配置
问答回答完全不相关	检索的片段不相关或 prompt 太弱	打印检索到的片段内容	调整切片大小、增加 topK、加 minScore 过滤
高并发时索引重复执行	没有分布式锁或锁已过期	查看 Redis 中锁 key 状态	加 SETNX 锁并设置合理过期时间
端口冲突	本机已有服务占用 8080 或 5432	`lsof -i :8080`	换端口或停掉旧进程

13. 最佳实践与合规提醒

13.1 工程实践

第一次跑通时，先用小文件、小模型，验证明白链路，再上大文档和数据量。
保存一份最小可运行配置，模型地址、数据库地址、Redis 地址都放在环境变量或配置中心，不硬编码。
文件、向量、缓存、日志分目录管理。pgvector 表数据量大了以后，要单独做备份策略。
批量任务必须加日志和失败重试，避免任务静默失败。
接口服务要限制访问范围，不要把带操作权限的接口暴露到公网。

13.2 RAG 与网盘的合规边界

用户上传的文档要有权限隔离。问答检索时，必须根据当前用户过滤可见文件，否则会造成数据越权访问。
如果文档包含个人敏感信息，需要先做脱敏或禁止入库检索。
AI 生成的答案存在幻觉风险，上线前建议给答案加“引用片段”，方便用户人工核对。
涉及版权材料、商业机密、人脸声音等素材时，必须确认上传者拥有合法授权，并设置明确的访问审计。
如果系统部署在个人服务器上，要避免把内部文档索引结果通过公网接口随意暴露。

14. 总结与下一步

CloudVault 这类项目最值得尝试的点，是把“文件管理”和“RAG 问答”放进了同一个 Java 后端体系里。上传文档不是终点，而是生成可检索知识的第一步；用户提问也不是直接调大模型，而是先从 PostgreSQL + pgvector 中检索出相关片段，再交给 LLM 生成。

最先应该验证的功能是这条核心链路：上传文档 -> 解析切片 -> Embedding -> pgvector 存储 -> 提问 -> 检索相关片段 -> 生成答案。最容易踩的坑是 pgvector 插件未启用、向量维度不匹配、模型服务地址不可达。只要这条链路通了，剩下的缓存、实时通知、批量任务都是在给它做工程化加固。

后续可以继续扩展的方向有很多：接入本地 Ollama 模型实现内网离线问答；在检索层增加用户权限过滤；用消费队列替换定时扫描批量任务；前端做一个简单的文档列表和 WebSocket 通知页面；再加一个问答日志审计，记录每次提问命中了哪些文档、最终答案是什么。整套架构从这开始，可以一路生长成一个可商用的企业内部知识库系统。