1. 项目概述这不是一次技术炫技而是一场对知识服务底层逻辑的重新校准“我为什么花21个月用纯Java重写一个MaxKB”——这句话刚在技术社区里冒头就引来一片错愕。有人第一反应是MaxKB不是现成的开源RAG知识库系统吗界面清爽、支持多模型接入、自带Web UI连向量切分和标签检索都封装好了为什么还要从零造轮子更别说用Java——那个被戏称为“企业级胶水语言”、在AI工程领域常被Python光环掩盖的“老派选手”。但如果你真点开过MaxKB的源码就会发现它底层依赖大量Python生态组件LangChain、LlamaIndex、FastAPI部署时要配Conda环境、装CUDA驱动、调PyTorch版本一个pip install失败就能卡住整个团队两天它的向量切分逻辑硬编码在chunking.py里想按中文语义切分标题段落代码块得改三处、测五轮、再祈祷Embedding模型不崩它的标签检索走的是Elasticsearch模糊匹配查“Spring Boot事务传播机制”结果返回一堆带“事务”但讲MySQL锁的文档——精准度差一档用户信任就掉一半。这正是我启动这个项目的起点RAG不是把文档扔进向量库就完事的流水线而是知识可解释性、可追溯性、可治理性的系统工程。21个月不是工期拖延是把每个模块都拉到显微镜下重审向量切分不能只看token数得懂中文标点层级、Markdown结构、代码缩进语义元数据管理不能只存个文件名得建轻量级本体Ontology关联技术栈、业务域、更新时效检索过程不能黑箱打分得让工程师能一眼看出“为什么这篇排第一”——是关键词密度高还是向量相似度突增抑或标签权重叠加Java在这里不是怀旧而是选择Spring Boot的自动装配能精准控制Bean生命周期MyBatis-Plus的动态SQL让元数据查询像写业务逻辑一样自然JVM的G1垃圾回收器在长文本解析场景下比CPython的GIL更稳更重要的是整个系统能打包成单个JARjava -jar maxkb.jar --spring.profiles.activeprod运维同学敲完回车就能喝咖啡不用再问“Python环境装对了吗”你不需要是Java专家也能看懂这个项目的价值——它解决的从来不是“能不能跑”而是“敢不敢交到客户生产环境里跑”。如果你正被RAG项目的交付周期拖垮被向量检索的不可控结果反复质疑或者正纠结于Dify和MaxKB哪个更适合企业内训系统那接下来拆解的每一个决策点都是我在21个月里用真实故障单换来的答案。2. 核心设计思路为什么放弃Python生态选择Java重构RAG全链路2.1 放弃Python不是否定其能力而是拒绝为“便利性”支付长期治理成本很多人看到“重写MaxKB”第一反应是“Python做RAG不是天经地义吗”确实LangChain的链式调用、LlamaIndex的索引抽象、Milvus的向量检索让Python在RAG原型开发上快得惊人。但快≠稳更≠可交付。我带着原版MaxKB做过三次POC第一次给金融客户演示因PyTorch CUDA版本冲突导致GPU推理卡死第二次给制造业客户部署因Conda环境隔离不彻底新装的scikit-learn覆盖了旧版pandas报表服务直接报错第三次最致命——客户要求审计所有知识召回路径我们翻遍Python日志发现Embedding调用链里混着三个不同版本的sentence-transformers根本无法定位哪次向量生成用了哪个模型。这些不是边缘case而是Python生态在企业级交付中的常态。Java的选择本质是选“确定性”。Spring Boot的ConditionalOnClass能精确控制组件加载时机避免Python里import xxx引发的隐式依赖爆炸Maven的dependencyManagement强制统一所有模块的Guava版本杜绝了Python中pip list | grep guava后发现七个不同小版本的荒诞更重要的是Java的强类型系统在编译期就拦住了80%的运行时错误——比如向量切分模块要求输入必须是Document对象含sourceId、metadata、content字段Python里传个dict可能到检索阶段才报KeyError而Java的Document.builder().sourceId(xxx).content(yyy).build()缺字段直接编译失败。这21个月里我们累计提交了137次PR其中42次是修复Python版里“能跑但不对”的逻辑漏洞比如原版用正则\n\n切分段落结果把YAML配置文件里的双换行也当段落切了导致嵌套结构全乱。提示不要迷信“AI项目必须用Python”的教条。当你的核心诉求是“知识服务的可审计性、可回滚性、可监控性”时Java的工程化底座反而成了加速器。2.2 RAG全链路重构的四大支柱切分、嵌入、检索、生成全部Java化落地重写不是简单翻译语法而是用Java思维重构RAG的DNA。我们把原版MaxKB的Python脚本式流程拆解为四个可独立演进、可灰度发布的服务模块切分引擎Chunking Engine放弃LangChain的RecursiveCharacterTextSplitter自研SemanticChunker。它不按字符数硬切而是先用OpenNLP做中文分词识别出“Spring Boot”、“Transactional”、“PROPAGATION_REQUIRED”等技术实体再结合Markdown AST解析器提取标题层级H1/H2/H3、代码块语言标识java、表格行列结构最终生成带语义标签的Chunk。例如一段Spring Boot事务说明会被切为[TAG:FRAMEWORK_SPRINGBOOT] [TAG:CONCEPT_TRANSACTION] [CONTENT:... Transactional注解的传播行为...]。这种切分让后续检索能精准命中“框架概念”组合而不是泛泛匹配“事务”二字。嵌入服务Embedding Service不直接调用HuggingFace API而是封装成EmbeddingClient接口支持HuggingFace、Ollama、本地ONNX Runtime三种后端。关键创新在于嵌入缓存策略对相同sourceIdcontentHash的Chunk复用已计算的向量避免重复调用大模型。我们用Caffeine构建本地LRU缓存命中率稳定在92%以上使10万文档知识库的首次向量化时间从17小时压缩到4.3小时。检索中枢Retrieval Hub抛弃Elasticsearch的全文模糊匹配采用混合检索架构主路走PGVector的余弦相似度SELECT * FROM chunks ORDER BY embedding %s LIMIT 10辅路用PostgreSQL的全文检索to_tsvector(chinese, content) to_tsquery(chinese, 事务传播)最后用加权融合算法公式score 0.7 * vector_score 0.3 * fulltext_score排序。这样既保留向量的语义泛化能力又确保关键词的精确召回。生成网关Generation Gateway不把LLM调用写死在Controller里而是抽象为LLMProviderSPIService Provider Interface。当前实现支持OpenAI、Azure OpenAI、本地Ollama未来接入千问、GLM只需新增一个实现类。最关键的是生成过程可观测每个请求生成traceId记录输入Prompt模板、实际渲染后的Prompt、LLM返回的完整Response、Token消耗、耗时全部写入Elasticsearch供审计。客户问“为什么答案里没提REQUIRES_NEW”我们能直接查trace发现是Prompt模板里漏写了“请列举所有传播行为”。这四大支柱不是孤立存在而是通过Spring Cloud Stream用Kafka解耦。切分完成发CHUNK_CREATED事件嵌入服务消费后发EMBEDDING_COMPLETED检索服务监听这两个事件构建索引——整个流程像流水线一样清晰可控出了问题能准确定位到哪个环节。2.3 技术选型背后的硬核权衡为什么是Spring Boot 3.x MyBatis-Plus PGVector选型不是堆砌流行词而是每一步都算过ROI投资回报率。我们对比过Spring Boot 2.7/3.0/3.2/4.0最终锁定3.2.x原因很实在它是首个全面拥抱GraalVM Native Image的Spring Boot大版本能把整个RAG服务编译成Linux原生二进制启动时间从2.3秒压到0.17秒内存占用从512MB降到186MB。这对边缘设备部署如工厂内网的离线知识终端是决定性优势。MyBatis-Plus替代JPA不是因为讨厌ORM而是JPA的Query写复杂检索SQL太反直觉。比如实现“查所有带Java标签且更新时间在30天内的Chunk”JPA要写Query(SELECT c FROM Chunk c WHERE c.tags LIKE %:tag% AND c.updatedAt :date)而MyBatis-Plus的QueryWrapper一行搞定queryWrapper.like(tags, java).gt(updated_at, LocalDateTime.now().minusDays(30))。更关键的是MyBatis-Plus的LambdaQueryWrapper能用方法引用避免字符串硬编码queryWrapper.eq(Chunk::getSourceId, doc-123)重构时改字段名IDE自动提示Python里filter(source_iddoc-123)只能靠grep。PGVector选型更是血泪教训。试过Milvus、Weaviate、Qdrant最终回归PostgreSQL原因有三第一客户现有数据库就是PostgreSQL不用额外运维一套向量数据库第二PGVector的-操作符性能足够100万Chunk在i7-11800H上P95响应时间80ms第三也是最重要的——数据一致性。当用户编辑一篇文档我们要原子性地更新documents表、删除旧chunks、插入新chunks、同步更新向量索引。在Milvus里这得写事务补偿逻辑在PostgreSQL里一个BEGIN; DELETE ...; INSERT ...; COMMIT;全搞定。我们线上环境跑过压力测试每秒200次文档更新PGVector零丢向量、零索引错乱。注意别被“向量数据库”名词绑架。对大多数企业知识库场景PGVector不是妥协而是更优解——它把向量能力无缝融入现有数据治理体系省下的运维人力够招两个专职LLM工程师。3. 核心模块深度解析从向量切分到标签检索的实操细节3.1 向量切分中文语义优先的Chunking Engine实现原版MaxKB的切分逻辑简单粗暴按500字符切遇到换行就断。这在英文文档里勉强可用但面对中文技术文档立刻露馅。比如一段Spring Boot配置说明“spring.jpa.hibernate.ddl-autoupdate该配置在开发环境启用会自动根据Entity更新表结构但生产环境严禁使用。”——按字符切很可能把“开发环境启用”和“生产环境严禁”切到两个Chunk里导致检索“生产环境配置”时漏掉关键禁令。我们的SemanticChunker分三步破局第一步结构感知预处理用jsoup解析HTML用commonmark解析Markdown构建AST抽象语法树。对以下节点特殊标记Heading节点记录层级H1100, H280, H360作为Chunk权重基础分CodeBlock节点提取语言标识java/python/sql打上[CODE:JAVA]标签Table节点将每行转为独立Chunk附加[TABLE_ROW]标签第二步中文语义切分不用正则而用HanLP的Segment分词器重点识别技术实体// 示例识别Spring Boot相关术语 ListTerm terms HanLP.segment(Spring Boot的Transactional注解); // 输出[Spring/nx, Boot/nx, 的/ude1, Transactional/jj, 注解/n]然后基于术语密度动态调整切分点当连续5个词中出现2个以上技术术语nx/nx/jj/n则在此处设为强切分点若遇到中文句号、问号、感叹号且前10字无技术术语则设为弱切分点。第三步Chunk组装与元数据注入每个Chunk包含content: 实际文本去HTML标签保留Markdown格式sourceId: 原始文档IDchunkId:sourceId - sequenceNumbermetadata: JSON字符串含{headingLevel:2,codeLanguage:java,tableRow:false,termDensity:0.35}实测效果对《Spring Boot官方文档》PDF转文本后的12万字内容切分出8432个Chunk人工抽检准确率98.7%。关键提升在于——检索“Transactional传播行为”时返回的Chunk100%包含完整代码示例和对应文字说明而非零散的半句话。实操心得切分不是越细越好。我们做过AB测试500字符切分召回率82%1000字符切分召回率89%但生成质量下降12%LLM上下文太长导致注意力分散。最终选定750字符为黄金阈值兼顾精度与生成稳定性。3.2 标签检索从关键词匹配到本体驱动的多维过滤原版MaxKB的标签检索本质是字符串匹配用户输“java spring”系统查tags LIKE %java% AND tags LIKE %spring%。这导致两个问题一是同义词无法覆盖“Java”和“JAVA”算不同标签二是关系缺失“Spring Boot”和“Spring MVC”应有关联但数据库里只是两个独立字符串。我们的解决方案是轻量级本体Ontology 动态标签图谱本体层Ontology Layer用JSON-LD定义技术领域本体{ context: {skos: http://www.w3.org/2004/02/skos/core#}, id: tech:spring-boot, type: skos:Concept, skos:prefLabel: Spring Boot, skos:broader: [tech:spring-framework], skos:narrower: [tech:spring-boot-starter-web] }这个本体不追求OWL级别的复杂推理只做三件事定义标准标签名prefLabel、声明上下位关系broader/narrower、标注同义词altLabel。所有用户上传文档时标签字段必须通过本体校验API标准化springboot自动转为Spring Boot。标签图谱层Tag Graph Layer用Neo4j存储标签关系节点是Tag边是RELATED_TO权重0.1~1.0。关系来源有三本体定义的broader/narrower权重0.8用户搜索日志当用户搜“Spring Boot”后紧接着搜“Actuator”记一次关联权重0.3文档共现分析同一文档中同时出现“Spring Boot”和“Docker”记一次弱关联权重0.1检索时用户输入“spring boot 监控”系统先本体标准化为[Spring Boot, Monitoring]再查图谱找关联标签[Actuator, Prometheus, Micrometer]最后执行混合查询-- 主查询向量相似度 SELECT * FROM chunks WHERE embedding (SELECT embedding FROM embeddings WHERE tag Spring Boot) AND tags ARRAY[Spring Boot, Monitoring] -- 辅助查询关联标签扩展 UNION SELECT * FROM chunks WHERE tags ARRAY[Actuator, Prometheus] ORDER BY score DESC LIMIT 10;上线三个月后标签检索的“首次命中率”用户第一次搜索就得到满意答案从54%提升到89%。最典型的案例客户搜“k8s部署java应用”系统自动关联“Helm Chart”、“ConfigMap”、“StatefulSet”返回的文档不仅讲部署步骤还包含YAML模板和故障排查清单。3.3 元数据治理用MyBatis-Plus动态SQL实现灵活的知识溯源RAG最大的信任危机不是答错而是答得“太对却无法验证”。用户问“Spring Boot 3.x默认事务隔离级别是什么”系统返回“READ_COMMITTED”但用户会追问“这个结论来自哪篇文档第几章谁写的什么时候更新的”我们的元数据治理方案叫四维溯源Four-Dimensional Traceability维度1文档源Source Dimensiondocuments表存原始信息source_typeweb/url、file/pdf、api/swagger、source_url如果是网页、file_hash如果是PDF、author从PDF元数据或Git提交者提取维度2处理链Processing Dimensionprocessing_logs表记录每次处理chunk_id、stepparse/chunk/embed、tool_versionHanLP 2.1.0、timestamp维度3知识图谱Knowledge Dimensionknowledge_facts表存结构化事实fact_id、subjectSpring Boot、predicatehasDefaultIsolationLevel、objectREAD_COMMITTED、evidence_chunk_id支撑该事实的Chunk ID维度4用户反馈Feedback Dimensionuser_feedback表存人工校验chunk_id、is_accuratetrue/false、feedback_time、reviewer_idMyBatis-Plus的动态SQL让这四维查询变得极其优雅。比如用户点击“查看来源”前端传chunkIddoc-123-005后端代码public ListSourceTrace getSourceTrace(String chunkId) { QueryWrapperProcessingLog logWrapper new QueryWrapper(); logWrapper.eq(chunk_id, chunkId).orderByDesc(timestamp); QueryWrapperDocument docWrapper new QueryWrapper(); docWrapper.eq(id, // 子查询从processing_logs找到document_id new LambdaQueryWrapperProcessingLog() .eq(ProcessingLog::getChunkId, chunkId) .select(ProcessingLog::getDocumentId) ); return sourceTraceMapper.selectJoin(docWrapper, logWrapper); }生成的SQL自动关联documents、processing_logs、knowledge_facts三张表返回结构化溯源数据。运维同学用Kibana看日志时能直接点击chunk_id跳转到溯源详情页——知识服务的可信度就藏在这些可点击的细节里。注意元数据不是越多越好。我们砍掉了原版MaxKB里所有“看起来有用”的字段如word_count、reading_level只保留能直接回答“谁、在哪、何时、为何”的四维字段。上线后DB查询平均耗时降低37%因为索引更聚焦。4. 实操全流程从零部署到生产环境的完整步骤与参数详解4.1 环境准备JDK 17 PostgreSQL 15 PGVector 0.5.0的最小可行配置别被“21个月”吓住核心服务的最小可行部署MVP只要30分钟。我们用Docker Compose定义生产就绪环境关键参数都经过压测验证# docker-compose.yml version: 3.8 services: postgres: image: postgres:15-alpine environment: POSTGRES_DB: maxkb POSTGRES_USER: maxkb POSTGRES_PASSWORD: maxkb123 volumes: - ./data/postgres:/var/lib/postgresql/data # 关键配置为PGVector优化 command: postgres -c shared_preload_librariesvector -c max_connections200 -c work_mem16MB ports: - 5432:5432 app: image: registry.example.com/maxkb:1.0.0 environment: SPRING_PROFILES_ACTIVE: prod SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/maxkb SPRING_DATASOURCE_USERNAME: maxkb SPRING_DATASOURCE_PASSWORD: maxkb123 # JVM关键参数G1GC针对RAG场景调优 JAVA_OPTS: - -Xms1g -Xmx2g -XX:UseG1GC -XX:MaxGCPauseMillis200 -XX:UseStringDeduplication depends_on: - postgres ports: - 8080:8080PostgreSQL调优要点shared_preload_librariesvector必须开启否则PGVector扩展无法加载max_connections200是底线RAG服务需连接池HikariCP 向量检索 后台任务100连接不够用work_mem16MB提升ORDER BY向量相似度的排序效率实测比默认4MB快2.3倍JVM参数深意-Xms1g -Xmx2g避免堆内存动态伸缩带来的GC抖动RAG服务内存占用稳定在1.4~1.8g-XX:MaxGCPauseMillis200设定G1停顿目标确保95%的GC停顿200ms不影响实时检索-XX:UseStringDeduplication减少Chunk内容字符串的重复内存占用10万文档节省约120MB部署命令极简# 1. 启动数据库 docker-compose up -d postgres # 2. 初始化PGVector扩展首次运行 docker exec -it maxkb-postgres psql -U maxkb -d maxkb -c CREATE EXTENSION vector; # 3. 启动应用 docker-compose up -d app # 4. 访问 http://localhost:8080 即可开始导入知识库实操心得别在开发机上用Docker Desktop跑PostgreSQLMac/Windows的文件系统虚拟化会让PGVector性能暴跌40%。我们用WSL2Windows或原生Linux VM性能差距立现。4.2 知识库构建从PDF解析到向量入库的端到端流水线知识库构建不是“上传文件→点按钮→完成”而是需要精细控制的流水线。我们提供CLI工具maxkb-cli支持三种模式模式1单文件快速导入适合POC# 解析PDF切分嵌入入库一步到位 maxkb-cli import --file manual.pdf \ --chunk-size 750 \ --embedding-model bge-m3 \ --batch-size 32参数详解--chunk-size 750中文语义切分的黄金长度已在3.1节验证--embedding-model bge-m3选择BAAI的bge-m3模型它支持多语言、多粒度dense/sparse/hybrid中文检索准确率比text2vec-base-chinese高11.2%--batch-size 32GPU批处理大小RTX 3090实测32最佳太大OOM太小吞吐低模式2目录批量导入适合企业知识库# 扫描docs/目录自动识别PDF/MD/TXT按文件名分组如spring-boot-guide.md → 标签Spring Boot maxkb-cli import-dir --path ./docs \ --tag-strategy filename \ --recursive true--tag-strategy支持filenamespring-boot-guide.md→[Spring Boot, Guide]header读取MD文件首行# Spring Boot 指南→[Spring Boot]none不自动打标签全靠人工模式3API流式导入适合CI/CD集成# 从Git仓库拉取最新文档触发构建 curl -X POST http://localhost:8080/api/v1/knowledge/build \ -H Content-Type: application/json \ -d { gitUrl: https://github.com/company/docs.git, branch: main, filePath: docs/spring-boot/, embeddingModel: bge-m3 }这个API会返回buildId前端可轮询/api/v1/knowledge/build/{id}/status获取进度精确到“已处理127/8432个Chunk”。整个流水线的关键监控点切分阶段记录avg_chunk_length目标750±50、chunk_count_per_docPDF平均切出12.3个Chunk嵌入阶段记录embedding_latency_p95目标1200ms、cache_hit_rate目标90%入库阶段记录pgvector_index_build_time10万Chunk索引构建8分钟上线后客户知识库从“每周手动更新”变成“Git Push自动触发”知识保鲜度提升300%。4.3 生产调优JVM GC日志分析与PGVector索引优化实战生产环境不出问题是靠日志里每一行GC记录和每个索引的填充因子撑起来的。分享两个真实案例案例1G1GC停顿飙升至1.2秒的根因分析某天凌晨报警/api/v1/retrieveP95延迟从80ms跳到1200ms。查JVM GC日志2023-10-15T02:17:23.4560000: [GC pause (G1 Evacuation Pause) (young), 1.2345678 secs] [Eden: 128.0M(128.0M)-0.0B(128.0M) Survivors: 0.0B-16.0M Heap: 1.2G(2.0G)-1.1G(2.0G)]1.2秒停顿远超-XX:MaxGCPauseMillis200设定继续查日志发现规律每小时整点触发一次Full GC。追查发现是ScheduledExecutorService每小时清理一次内存缓存但清理逻辑写了cache.clear()清空所有导致Eden区瞬间涌入大量Chunk对象。解决方案改用cache.invalidateAll()异步清理并加Scheduled(fixedDelay 3600000, initialDelay 60000)错峰。案例2PGVector索引失效的隐形杀手知识库运行两周后检索速度变慢。EXPLAIN ANALYZE显示Seq Scan on chunks (cost0.00..12345.67 rows8432 width1234) Filter: ((embedding [0.1,0.2,...]::vector) 0.8)居然走了全表扫描查pg_indexes发现idx_chunks_embedding索引存在但pg_stat_all_indexes显示idx_chunks_embedding的idx_scan为0。根因PGVector的-操作符需要vector扩展的vector_l2_ops操作符族而建索引时误用了默认btree。修复命令-- 删除错误索引 DROP INDEX idx_chunks_embedding; -- 重建正确索引 CREATE INDEX idx_chunks_embedding ON chunks USING ivfflat (embedding vector_l2_ops) WITH (lists 100); -- lists sqrt(row_count) ≈ sqrt(8432)≈92 → 取100重建后EXPLAIN变为Index Scan using idx_chunks_embedding on chunks (cost0.00..12.34 rows10 width1234) Index Cond: ((embedding [0.1,0.2,...]::vector) 0.8)P95延迟从1200ms回到78ms。独家技巧在application-prod.yml里加健康检查端点management: endpoint: health: show-details: always endpoints: web: exposure: include: health,metrics,prometheus,loggers访问/actuator/health能看到pgvector-index-status: UP、embedding-cache-hit-rate: 92.3%等关键指标比写Shell脚本查数据库直观十倍。5. 常见问题与避坑指南21个月踩过的37个坑总结成速查表5.1 向量切分与嵌入常见问题问题现象根本原因解决方案验证方式检索结果包含无关代码片段切分引擎未识别代码块边界把// TODO: fix bug这样的注释单独切为Chunk在SemanticChunker中增加CodeBlockBoundaryDetector用正则(?s)//.*?(\n$)相同文档多次导入向量重复sourceId生成逻辑未考虑文件修改时间PDF元数据ModDate变更但sourceId不变sourceId改为SHA256(file_content file_mod_time)确保内容或时间任一变化即生成新ID导入同一PDF两次修改时间不同chunks表中sourceId不同embedding表无重复向量中文检索准确率低于英文Embedding模型用text2vec-base-chinese但该模型在技术术语上表现弱切换为BAAI的bge-m3它在MTEB中文榜单上比text2vec高14.7%在自建测试集1000个中英文技术问题上中文准确率从73.2%→87.9%英文从85.1%→88.3%5.2 检索与生成稳定性问题问题现象根本原因解决方案验证方式高并发下检索返回空结果PGVector的ivfflat索引在并发写入时lists参数未适配导致近似搜索失效将lists从固定值改为动态计算lists CEIL(SQRT(count(*) FROM chunks))并在INSERT后触发ANALYZE chunks用JMeter模拟200并发空结果率从12.4%→0%LLM生成答案突然变短Prompt模板中{context}占位符被截断因MAX_CONTEXT_LENGTH4096但Chunk向量拼接后超长实现ContextTruncator按Chunk权重Heading等级×Term密度降序排列优先保留高权重Chunk直到总token3500对100个长文档测试生成答案长度标准差从±287字降至±42字用户反馈“答案不一致”同一问题在不同时间点调用因Embedding服务后端切换HuggingFace→Ollama向量空间不一致强制所有Embedding服务实现VectorSpaceConsistency接口提供getVectorSpaceId()方法如huggingface-bge-m3-v1.0检索时校验空间ID一致部署双后端/actuator/health显示embedding-space-consistent: true5.3 运维与升级避坑清单升级Spring Boot 3.2.x时springdoc-openapi不兼容新版Spring Doc要求Operation注解必须有summary而原版API文档缺失。解决方案全局搜索Operation批量添加summary XXX接口或降级springdoc-openapi-starter-webmvc-api到2.3.0。PGVector 0.5.0升级后-操作符报错function vector_l2_distance does not exist这是扩展版本不匹配。执行SELECT * FROM pg_extension;确认vector版本若为0.4.0则需ALTER EXTENSION vector UPDATE TO 0.5.0;而非卸载重装。Docker容器内存溢出OOM Killed不是JVM内存不足而是容器内存限制太低。docker stats显示maxkb-app的MEM USAGE / LIMIT为1.95GiB / 2GiB但jstat -gc显示JVM堆仅用1.4G。根因JVM未配置-XX:UseContainerSupport无法感知Docker内存限制。解决方案