企业官网建设流程全解析

1. 项目概述：为什么用 PostgreSQL 做向量检索，而不是换数据库？

“SpringAI Retrieval Augmented Generation (RAG) With PgVector Part 1”——这个标题里藏着三个关键信号：Spring 生态、RAG 架构落地、PgVector 实战。它不是讲大模型原理，也不是教你怎么调 API，而是直击企业级 AI 应用最卡脖子的一环：如何让大模型“记得住你自己的数据”，且记得准、查得快、改得稳。我带团队做过 7 个生产级 RAG 项目，从金融知识库到医疗文档助手，踩过所有坑：向量库选型摇摆、嵌入一致性断裂、检索结果漂移、Spring 事务与向量写入不同步……最后发现，不换数据库，反而赢在起点。

很多人一提 RAG 就默认上 Milvus、Qdrant 或 Chroma，但现实是：你手里的客户合同、产品手册、工单记录、内部 Wiki，90% 都躺在 PostgreSQL 里。硬拆出来另建一套向量库，等于把数据库当“只读缓存”用，带来三重代价：数据双写一致性难保障（比如业务更新了 PDF 元数据，向量库没同步）、权限体系割裂（DBA 管 PG，AI 工程师管 Qdrant，审计时两头扯皮）、运维成本翻倍（多一套服务、多一套监控、多一套备份策略）。而 PgVector 是 PostgreSQL 的原生扩展，它不新增服务，不改变数据流，向量就是一种新数据类型，和VARCHAR、JSONB平起平坐。你在 Spring 中执行INSERT INTO docs (title, content, embedding) VALUES (?, ?, ?)，那个embedding字段就是vector(1536)类型——和插一条普通记录毫无区别。这种“零感知集成”，才是企业敢把 RAG 推进核心业务的底气。

标题里强调 “Part 1”，说明这不是炫技 Demo，而是分阶段落地的工程实践。Part 1 的核心目标非常务实：在 Spring Boot 3.2+ 环境下，用 JPA + PgVector 实现端到端的向量写入、相似性检索、结果注入 LLM 提示词的闭环，且全程可调试、可监控、可回滚。它不追求吞吐量破万 QPS，但要求每一步操作都有迹可循：嵌入向量怎么生成的？检索时用了什么距离函数？Top-K 结果为什么是这三条？这些在生产环境里不是“优化项”，而是“必选项”。我见过太多团队 Part 1 没走稳，直接跳 Part 2 做混合检索或重排序，结果上线后用户反馈“回答牛头不对马嘴”，一查日志发现：嵌入模型用的是text-embedding-ada-002，但向量表字段定义却是vector(768)，维度错位导致余弦相似度计算完全失效——这种低级错误，恰恰暴露了对底层数据契约的漠视。

关键词 “SpringAI” 也值得深挖。它不是 Spring 官方的 AI 框架，而是 Spring 生态中首个专为 AI 场景设计的抽象层，2024 年初刚升为 GA 版本。它的价值不在替代 LangChain，而在把 AI 能力“Spring 化”：向量存储是VectorStore接口，大模型是ChatModel接口，提示词模板是PromptTemplate，全部遵循 Spring 的依赖注入、事务管理、配置绑定机制。这意味着，你可以在@Service里直接@Autowired private VectorStore pgVectorStore;，然后像调用 DAO 一样调用pgVectorStore.similaritySearch(query)，背后自动完成连接池管理、异常翻译、指标埋点。这种设计，让 Java 老兵不用学新范式，就能把 RAG 编排进现有微服务架构。所以，这个标题的本质，是在回答一个现实问题：当你的技术栈是 Spring + PostgreSQL 时，如何用最小改造成本，把 RAG 变成一个可维护、可测试、可交付的模块，而不是一个游离在系统之外的“AI 黑盒”？

2. 核心设计思路：为什么放弃 LangChain 集成，坚持手写 JPA Repository？

很多开发者看到 “RAG + PgVector”，第一反应是找现成的 LangChain 集成包，比如langchain4j-pgvector或spring-ai-pgvector-store。我试过，也推荐团队在 PoC 阶段用，但进入 Part 1 工程落地时，果断砍掉所有第三方 LangChain 绑定，回归纯 JPA + 原生 SQL。这不是守旧，而是基于三个硬性约束的理性选择。

第一，调试可见性。LangChain 的PgVectorStore封装了太多黑盒逻辑：它自动创建表、自动处理索引、自动拼接ORDER BY embedding <=> ? LIMIT ?。当你发现检索结果不准时，想查“它到底用了哪个距离函数？是否加了WHERE过滤条件？查询计划有没有走索引？”，LangChain 日志只给你一行Executing similarity search...，而真正的 SQL 被藏在AbstractVectorStore的doSimilaritySearch方法里，需要断点跟进去十层调用栈。而手写 JPA Repository，你的@Query注解就是最终 SQL：“SELECT * FROM documents WHERE status = 'ACTIVE' AND embedding <=> :query < :threshold ORDER BY embedding <=> :query LIMIT :topK”。你可以把它复制到 psql 里直接执行，用EXPLAIN ANALYZE看执行计划，确认IVFFlat索引是否生效，distance计算是否被下推——这是生产环境故障排查的黄金路径。

第二，事务一致性。RAG 流程常需“先写文档元数据，再写向量，再触发异步嵌入更新”。LangChain 的add方法默认开启新事务，而你的业务 Service 可能已在一个@Transactional里。如果嵌入失败，LangChain 的add回滚了，但业务数据已提交，造成元数据与向量不一致。手写 JPA 则完全可控：你在一个@Transactional方法里，先documentRepository.save(doc)，再embeddingRepository.save(embedding)，两个操作共享同一数据库连接和事务上下文。哪怕嵌入生成失败，整个事务回滚，数据零残留。我们有个保险案例：某次批量导入 5000 份保单条款，因 OpenAI API 限流导致 37 条嵌入失败，手写方案自动回滚全部，而 LangChain 方案留下 4963 条“有元数据无向量”的脏数据，人工清理耗时两天。

第三，版本演进成本。PgVector 本身迭代极快，2024 年已支持HNSW索引、bit向量压缩、sparse vector等新特性。LangChain 的适配往往滞后 2-3 个版本。比如 PgVector 0.5.0 新增CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops)，但langchain4j-pgvector1.0.0 还只认ivfflat。手写方案只需改一行 DDL 和@Query，而 LangChain 方案要么等官方更新，要么 fork 代码自己改——这对 Java 团队是不可接受的技术债。我们 Part 1 的application.yml里明确禁用所有spring.ai.*自动配置，只保留spring.datasource.*和spring.jpa.*，确保控制权牢牢握在自己手里。

提示：这不是反对 LangChain，而是分阶段策略。Part 1 的目标是“建立数据契约”，必须亲手摸清每一行 SQL、每一个向量维度、每一个索引参数。等这套流程跑稳，Part 2 再引入 LangChain 做高级编排（如多路召回、LLM 路由），此时你已具备判断其行为是否符合预期的能力。

3. 核心细节解析：PgVector 表结构设计与向量维度锁定

表结构设计是 RAG 稳定性的地基，绝不能照搬教程里的id, content, embedding三字段。我在 Part 1 中强制采用6 字段最小完备模型，每个字段都对应一个真实痛点：

CREATE TABLE documents ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), title VARCHAR(512) NOT NULL, content TEXT NOT NULL, embedding VECTOR(1536) NOT NULL, -- 关键！维度必须显式声明 metadata JSONB NOT NULL DEFAULT '{}', created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() );

embedding VECTOR(1536)是核心中的核心。1536不是随便写的，它来自所选嵌入模型的输出维度。我们 Part 1 固定使用text-embedding-3-small（OpenAI），其输出固定为 1536 维。维度错位是 RAG 最隐蔽的性能杀手。假设你误设为VECTOR(768)，PostgreSQL 不会报错，但计算embedding <=> query时，会截断或填充向量，导致余弦相似度值失真。实测中，维度错位 10%，检索 Top-1 准确率从 82% 直降为 41%。更糟的是，这种错误无法通过单元测试发现——因为save()和search()都能成功执行，只是结果不可靠。因此，Part 1 的硬性规定是：嵌入模型、Java 实体类@Column(columnDefinition = "vector(1536)")、数据库 DDL、SpringAIEmbeddingClient配置，四者维度值必须完全一致，且写死在代码注释里。我们在DocumentEntity.java顶部加了这样一段注释：

/** * Embedding dimension: 1536 (from text-embedding-3-small) * MUST match: * - Database column: ALTER TABLE documents ALTER COLUMN embedding TYPE vector(1536) * - SpringAI config: spring.ai.openai.embedding.dimensions=1536 * - JPA mapping: @Column(columnDefinition = "vector(1536)") * Violation causes silent semantic drift in retrieval. */

metadata JSONB NOT NULL DEFAULT '{}'字段解决的是“过滤难”问题。纯向量检索无法做业务过滤，比如“只检索 2024 年发布的有效合同”。若用WHERE加业务条件，再对结果做向量排序，会极大降低性能（全表扫描后再排序）。正确做法是把业务维度塞进metadata，并为其创建 GIN 索引：CREATE INDEX idx_documents_metadata_gin ON documents USING GIN (metadata). 这样，查询可写成：WHERE metadata @> '{"year": "2024", "status": "valid"}' AND embedding <=> ? < ? ORDER BY ...，PostgreSQL 会先用 GIN 索引快速筛选出几百条候选，再对这几百条做向量计算，速度提升 10 倍以上。我们曾用此法将某金融问答场景的 P95 延迟从 1200ms 降至 110ms。

created_at TIMESTAMP WITH TIME ZONE看似普通，实则为后续“时间衰减权重”埋下伏笔。RAG 检索结果常需按时间新鲜度加权，比如新发布的政策解读应比三年前的文档权重更高。手写 SQL 可轻松实现：ORDER BY (embedding <=> ?) * EXP(-0.001 * EXTRACT(EPOCH FROM NOW() - created_at)/3600) LIMIT ?。而 LangChain 的similaritySearch接口不支持自定义排序表达式，只能返回原始分数，加权逻辑被迫移到应用层，增加网络传输和内存开销。

注意：title和content分离是经验之谈。很多教程把全文塞进content，但实际中title是高频检索字段（用户常问“XX 功能怎么用？”），单独建GIN索引CREATE INDEX idx_documents_title_gin ON documents USING GIN (to_tsvector('chinese', title))，可支持中文全文检索，与向量检索形成互补。Part 1 不强制要求，但预留了字段和索引空间。

4. 实操过程详解：从零搭建 Spring Boot + PgVector RAG 环境

4.1 环境准备与依赖锁定

Part 1 的环境必须“极度克制”，避免任何可能引入不确定性的依赖。我们锁定以下组合，经 3 个项目验证稳定：

• JDK: 17.0.10（LTS，避免 JDK 21 的 preview 特性）
• Spring Boot: 3.2.7（Spring AI 1.0.0-M5 的唯一兼容版本，GA 版本发布前的最稳选择）
• PostgreSQL: 15.5（PgVector 0.5.1 的最佳匹配，16.x 对某些向量函数支持尚不完善）
• PgVector 扩展: 0.5.1（必须手动安装，非 Maven 依赖）

第一步，安装 PgVector 扩展。切勿用CREATE EXTENSION IF NOT EXISTS vector—— 这是旧版语法，且不指定版本易引发兼容问题。正确流程是：

1. 下载 PgVector 0.5.1 的二进制包（ https://github.com/pgvector/pgvector/releases/tag/v0.5.1 ），解压到 PostgreSQL 的lib目录；
2. 将vector.control和vector--0.5.1.sql复制到share/extension/目录；
3. 重启 PostgreSQL 服务；
4. 在目标数据库中执行：

   CREATE EXTENSION vector VERSION '0.5.1';

验证是否成功：SELECT * FROM pg_extension WHERE extname = 'vector';应返回一行，extversion为0.5.1。

Maven 依赖精简到 5 个核心：

<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency> <dependency> <groupId>org.postgresql</groupId> <artifactId>postgresql</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>io.github.jan-holst</groupId> <artifactId>pgvector-spring-boot-starter</artifactId> <version>0.5.1</version> <!-- 非官方，但专为 Spring Boot 3.2 优化 --> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai-spring-boot-starter</artifactId> <version>1.0.0-M5</version> </dependency> </dependencies>

关键点：pgvector-spring-boot-starter是社区维护的轻量启动器，它只做两件事——自动注册VectorTemplateBean 和提供VectorTypeHibernate 类型映射，绝不封装VectorStore接口，完美契合 Part 1 的手写策略。而spring-ai-openai-spring-boot-starter仅用于获取EmbeddingClient，不启用其VectorStoreAutoConfiguration。

4.2 数据库初始化与索引优化

建表后，索引是性能分水岭。PgVector 支持IVFFlat和HNSW两种索引，Part 1 选择IVFFlat，原因很实在：它支持INSERT时实时更新，而 HNSW 在数据量增长时需重建索引，不适合频繁写入场景。我们的业务文档日均增量 200+，HNSW 重建一次要 15 分钟，不可接受。

创建IVFFlat索引的命令必须带lists参数，其值决定索引质量与查询速度的平衡点。公式为：lists ≈ sqrt(n)，其中n是预计总向量数。例如，预估文档 10 万条，则lists = 316。我们 Part 1 的初始值设为100（适应小规模测试），并在application.yml中配置：

spring: datasource: url: jdbc:postgresql://localhost:5432/ragdb?currentSchema=public jpa: hibernate: ddl-auto: validate # 严禁 use create-drop！ properties: hibernate: dialect: org.hibernate.dialect.PostgreSQLDialect type_contributors: io.github.janholst.pgvector.hibernate.PgVectorTypeContributor

ddl-auto: validate是铁律。create或update会破坏VECTOR类型的元数据，导致ALTER COLUMN失效。所有 DDL 必须通过 Flyway 管理。我们在src/main/resources/db/migration/V1__init.sql中写死：

CREATE TABLE documents ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), title VARCHAR(512) NOT NULL, content TEXT NOT NULL, embedding VECTOR(1536) NOT NULL, metadata JSONB NOT NULL DEFAULT '{}', created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() ); CREATE INDEX idx_documents_embedding_ivfflat ON documents USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

实操心得：lists参数调优必须实测。我们用pgbench模拟 1 万条向量数据，测试不同lists值下的 P95 查询延迟：

lists	P95 延迟 (ms)	索引大小 (MB)
50	42	12
100	28	24
200	21	48
500	18	120
最终选择100，因延迟下降边际效益递减，而索引体积翻倍会增加主从同步压力。

4.3 向量写入与检索的核心代码实现

DocumentRepository是 Part 1 的心脏，它必须同时满足：可测试、可监控、可追溯。我们不继承JpaRepository，而是手写@Repository：

@Repository public class DocumentRepository { private final JdbcTemplate jdbcTemplate; private final EmbeddingClient embeddingClient; public DocumentRepository(JdbcTemplate jdbcTemplate, EmbeddingClient embeddingClient) { this.jdbcTemplate = jdbcTemplate; this.embeddingClient = embeddingClient; } // 写入：先生成嵌入，再插入 @Transactional public UUID saveDocument(String title, String content, Map<String, Object> metadata) { // 1. 生成嵌入（同步调用，确保事务内完成） List<Double> embedding = embeddingClient.embed(content).getEmbedding(); // 2. 插入数据库（使用 PostgreSQL 原生 vector 数组语法） String sql = """ INSERT INTO documents (title, content, embedding, metadata) VALUES (?, ?, ?::vector, ?::jsonb) RETURNING id """; return jdbcTemplate.queryForObject(sql, new Object[]{title, content, embedding.toArray(new Double[0]), new ObjectMapper().writeValueAsString(metadata)}, new ColumnRowMapper<>(UUID.class, "id")); } // 检索：支持业务过滤 + 向量排序 public List<DocumentResult> search(String query, int topK, Map<String, Object> filters) { // 1. 生成查询向量 List<Double> queryEmbedding = embeddingClient.embed(query).getEmbedding(); // 2. 构建动态 WHERE 条件 String whereClause = buildWhereClause(filters); String sql = String.format(""" SELECT id, title, content, 1 - (embedding <=> ?::vector) AS score FROM documents %s ORDER BY embedding <=> ?::vector LIMIT ? """, whereClause); return jdbcTemplate.query(sql, new Object[]{ queryEmbedding.toArray(new Double[0]), queryEmbedding.toArray(new Double[0]), topK }, (rs, rowNum) -> new DocumentResult( rs.getObject("id", UUID.class), rs.getString("title"), rs.getString("content"), rs.getDouble("score") )); } private String buildWhereClause(Map<String, Object> filters) { if (filters == null || filters.isEmpty()) return ""; StringBuilder sb = new StringBuilder(" WHERE "); List<String> conditions = new ArrayList<>(); for (Map.Entry<String, Object> entry : filters.entrySet()) { conditions.add(String.format("metadata @> ?::jsonb", entry.getKey())); } sb.append(String.join(" AND ", conditions)); return sb.toString(); } }

关键细节：

• embedding <=> ?::vector中的::vector强制类型转换，避免隐式转换错误；
• 1 - (embedding <=> ?)将距离转为相似度（0~1），便于后续 LLM 提示词注入；
• RETURNING id确保写入后立即拿到 ID，无需二次查询；
• buildWhereClause支持任意metadata键值对过滤，且参数化防止 SQL 注入。

4.4 RAG 流程闭环：从检索到 LLM 提示词组装

Part 1 的终点不是“查出几条文档”，而是“生成一条准确回答”。我们设计了一个极简但完备的RagService：

@Service public class RagService { private final DocumentRepository documentRepository; private final ChatClient chatClient; public RagService(DocumentRepository documentRepository, ChatClient chatClient) { this.documentRepository = documentRepository; this.chatClient = chatClient; } public String answerQuestion(String question) { // Step 1: 检索相关文档 List<DocumentResult> results = documentRepository.search( question, 3, Map.of("source", "manuals", "language", "zh") ); // Step 2: 组装提示词（严格遵循 RAG 最佳实践） String context = results.stream() .map(r -> String.format("【%s】%s", r.getTitle(), r.getContent())) .collect(Collectors.joining("\n\n")); String prompt = String.format(""" 你是一个专业的产品助手，请基于以下【参考资料】回答用户问题。 【参考资料】 %s 【用户问题】 %s 【回答要求】 - 仅使用参考资料中的信息，禁止编造。 - 若参考资料未提及，回答“根据现有资料无法确定”。 - 用中文回答，简洁明了。 """, context, question); // Step 3: 调用 LLM return chatClient.call(prompt).getResult().getOutput().getContent(); } }

这个流程看似简单，却锁定了三个关键契约：

• 检索与生成分离：search()和call()是两个独立方法，可分别打点监控；
• 提示词可审计：prompt字符串完整记录在日志中，故障时可复现；
• 答案可验证：【参考资料】块清晰标注来源，用户质疑时可快速定位原文。

我们在线上环境给answerQuestion方法加了 Micrometer 指标：

• rag.search.latency：检索耗时（含嵌入生成）；
• rag.llm.latency：LLM 调用耗时；
• rag.retrieval.hit_rate：检索结果中真正被 LLM 引用的片段占比（通过正则匹配【.*?】提取）。

实测数据显示，当hit_rate < 60%时，大概率是嵌入模型与业务语义不匹配，需调整text-embedding-3-small的dimensions或换模型；当search.latency > 200ms时，优先检查IVFFlat索引的lists参数和WHERE过滤条件是否合理。

5. 常见问题与排查技巧实录

5.1 问题速查表：从现象反推根因

5.2 独家避坑技巧：那些文档里不会写的细节

技巧一：向量写入的“批处理陷阱”
PgVector 的INSERT单条性能极好，但批量INSERT时，若向量数组过大（如 1536 个double），JDBC 驱动会因PreparedStatement参数过多而报错。解决方案不是拆小批次，而是用COPY协议。我们在DocumentRepository中添加batchSave方法：

public void batchSave(List<DocumentBatchItem> items) { // 1. 先生成所有嵌入（并行，但注意 OpenAI 限流） List<EmbeddingResponse> embeddings = embeddingClient.embed( items.stream().map(DocumentBatchItem::getContent).toList() ); // 2. 构建 COPY 数据流 String copySql = "COPY documents (title, content, embedding, metadata) FROM STDIN WITH (FORMAT BINARY)"; CopyManager copyManager = ((PGConnection) jdbcTemplate.getDataSource() .getConnection()).getCopyAPI(); // 3. 执行 COPY（比 1000 条 INSERT 快 8 倍） copyManager.copyIn(copySql, new DocumentCopyIn(items, embeddings)); }

DocumentCopyIn实现CopyIn接口，将List<Double>直接序列化为 PostgreSQL 的vector二进制格式。这是 PgVector 官方文档未强调，但生产环境必备的优化。

技巧二：IVFFlat索引的“冷启动校准”
IVFFlat索引在首次CREATE后，必须执行SET LOCAL ivfflat.probes = X才能生效。probes值决定搜索时探测的聚类中心数，probes ≈ sqrt(lists)。若不设置，probes默认为 1，检索精度暴跌。我们在search()方法开头强制设置：

jdbcTemplate.execute("SET LOCAL ivfflat.probes = 10");

这个SET LOCAL只对当前事务生效，不影响其他连接，安全可靠。

技巧三：嵌入模型的“温度控制”
text-embedding-3-small的dimensions参数不仅影响向量长度，还影响语义密度。我们实测发现：dimensions=1536（默认）时，对长文本摘要能力强；dimensions=512时，对短关键词匹配更准。Part 1 的application.yml中明确配置：

spring: ai: openai: embedding: dimensions: 1536 # 重要！禁用 base64 编码，避免 JSON 解析错误 encoding_format: float

encoding_format: float是关键，若用base64，EmbeddingResponse.getEmbedding()返回的是编码字符串，需额外解码，极易出错。

6. 性能压测与线上稳定性验证

Part 1 的交付标准不是“能跑”，而是“能扛”。我们用k6对answerQuestion接口进行阶梯式压测，目标：100 并发下，P95 延迟 ≤ 800ms，错误率 0%。

压测脚本核心逻辑：

import http from 'k6/http'; import { check, sleep } from 'k6'; export const options = { stages: [ { duration: '30s', target: 20 }, // ramp up { duration: '2m', target: 100 }, // peak { duration: '30s', target: 0 }, // ramp down ], }; export default function () { const question = "如何申请退款？"; const res = http.post('http://localhost:8080/api/rag/answer', JSON.stringify({ question }), { headers: { 'Content-Type': 'application/json' } } ); check(res, { 'is status 200': (r) => r.status === 200, 'p95 latency < 800ms': (r) => r.timings.p95 < 800, }); sleep(1); // 模拟用户思考时间 }

压测结果（100 并发，持续 2 分钟）：

瓶颈分析显示：rag.search.latency的 189ms 中，120ms 花在EmbeddingClient.embed()的 HTTP 调用上，这是外部依赖，本地无可优化。而向量检索的 69ms，已优于IVFFlat理论极限（lists=100时，理论 P95 ≤ 75ms）。这证明我们的索引、SQL、JDBC 配置已调至最优。

线上稳定性验证则聚焦“故障恢复”。我们模拟三种故障：

• PgVector 扩展意外卸载：DROP EXTENSION vector;，观察应用日志是否清晰报错ERROR: type "vector" does not exist，而非NullPointerException；
• 向量表被 truncate：TRUNCATE documents;，验证search()返回空列表，而非抛异常；
• OpenAI API 限流：手动在EmbeddingClient上加Thread.sleep(5000)，确认@Transactional正确回滚，无脏数据。

三次故障均按预期行为响应，日志清晰可读，监控指标（Micrometer）实时报警，验证了 Part 1 设计的鲁棒性。

7. 我的实际体会：为什么 Part 1 要“慢下来”

带团队做完这个 Part 1，最大的感触是：RAG 不是拼谁集成得快，而是拼谁理解得深。很多团队 Part 1 用 LangChain 一周搞定，但上线三个月后，因嵌入模型升级、PgVector 版本迭代、业务过滤逻辑变更，不得不推倒重来。而我们花三周手写 JPA，换来的是：一张清晰的documents表结构图、一份可执行的EXPLAIN ANALYZE检查清单、一个能精确到毫秒的rag.search.latency指标、以及团队每个人都能看懂的@QuerySQL。

这种“慢”，是把不确定性转化为确定性。当search()方法返回异常结果时，我不需要打开 LangChain 源码，只需复制 SQL 到 psql，加EXPLAIN，看执行计划里有没有Index Scan using idx_documents_embedding_ivfflat。当用户说“这个回答不对”，我能立刻查日志，找到那条完整的prompt字符串，确认是检索错了，还是 LLM 理解错了，抑或是提示词模板有歧义。

Part 1 的终点，不是功能上线，而是**建立一套可传承