09 · 写入向量数据 add 学完能做什么正确构造 Document、设计 metadata、批量写入并控制 id避免重复灌库与更新错乱。⏱️ 预计耗时40 分钟含动手 依赖前置第 07、08 章 难度一句话vectorStore.add(ListDocument)把文本自动转向量后写库写好 metadata 和稳定的 id是后续过滤检索和幂等更新的前提。1. Document向量库里的一条记录一个Document 文本内容 元数据 自动生成的 id 与向量DocumentdocnewDocument(本店退货政策签收起 7 天内商品完好可无理由退货。,// contentMap.of(// metadatasource,退货政策,category,售后,updatedAt,2026-01-01));vectorStore.add(List.of(doc));content会被 embedding 成向量也是回答时喂给模型的原文。metadata不参与相似度计算但用于过滤第 11 章和溯源第 21 章。2. metadata 怎么设计很重要metadata 决定了你以后能怎么「筛选」检索范围。常见维度Map.of(source,产品手册v3.pdf,// 来源文件溯源用category,售后,// 业务分类过滤用tenantId,1001,// 多租户隔离过滤用page,12,// 页码溯源定位lang,zh// 语言) 经验灌库时想清楚以后要按什么筛就在 metadata 里放什么。事后补 metadata 要重灌成本高。3. 批量写入性能关键灌库一定要批量别一条条 addListDocumentdocsnewArrayList();for(Articlea:articles){docs.add(newDocument(a.getContent(),Map.of(source,a.getTitle(),category,a.getCategory())));}vectorStore.add(docs);// 一次批量内部批量 embedding 批量入库大批量上万条还需分批提交、控制并发与 token 速率见第 15 章 ETL 与第 32 章大规模导入。4. 控制 id实现幂等与更新不指定 id 时Spring AI 会自动生成 UUID——每次灌库都会新增导致重复数据。要「同一条资料可更新、不重复」就自己指定稳定 id// 用业务主键当 id重复灌库时可先删后加实现「更新」StringstableIdarticle-article.getId();DocumentdocnewDocument(stableId,article.getContent(),metadata);vectorStore.delete(List.of(stableId));// 先删旧的幂等vectorStore.add(List.of(doc));// 再写新的 规律id 稳定 可更新可去重id 随机 每次灌都新增。生产灌库务必用稳定 id。5. 删除// 按 id 删vectorStore.delete(List.of(article-1001,article-1002));// 按 metadata 条件删如清空某租户/某来源语法见第 11 章 FiltervectorStore.delete(newFilterExpressionBuilder().eq(source,产品手册v2.pdf).build());6. 一个可复用的灌库服务ServiceclassDocIngestService{privatefinalVectorStorevectorStore;DocIngestService(VectorStorevectorStore){this.vectorStorevectorStore;}/** 幂等灌入同 id 先删后加 */voidupsert(Stringid,Stringcontent,MapString,Objectmetadata){vectorStore.delete(List.of(id));vectorStore.add(List.of(newDocument(id,content,metadata)));}voidbatchInsert(ListDocumentdocs){// 分批避免单次请求过大 / 超 token 速率intbatch100;for(inti0;idocs.size();ibatch){vectorStore.add(docs.subList(i,Math.min(ibatch,docs.size())));}}}7. 常见坑现象原因 / 处理数据越灌越多、重复用了随机 id改用稳定 id 先删后加想按分类筛却筛不了灌库时没写对应 metadata单次 add 很慢/超时没分批或单条文本过长先分块更新资料后检索还是旧内容只 add 没 delete旧向量还在8. 一句话总结写入 add(ListDocument)content 转向量、metadata 供过滤与溯源用稳定 id 先删后加实现幂等更新批量分批提交保证性能。➡️ 下一章10-相似检索similaritySearch.md学会用 TopK、相似度阈值把最相关的资料查出来。