Spring‑AI Document 对象 JSON 字段详解

json 复制代码
{
 "内容格式化器": {
 "排除嵌入元数据键": [], // 生成向量时,哪些metadata不要拼进文本
 "排除推理元数据键": [], // 给大模型推理时,哪些metadata不要拼进文本
 "元数据分隔符": "\r\n", // 多个元数据之间换行分隔
 "元数据模板": "{key}: {value}", // 元数据行格式 key: value
 "文本模板": "{metadata_string}\n\n{content}" // 整体拼接模板
 }
}

Spring‑AI Document 对象JSON字段详解

这是Spring AI的org.springframework.ai.document.Document,存入向量库之前的文档对象。

注意:embedding: []是空数组,代表这个文档还没有生成向量,还没调用EmbeddingModel做向量化。

json 复制代码
  {
    "content": "安全预警预测管理制度 Q/DHG05.20(87)---2019A1 1 目的 为提升公司安全管理水平,规范各类职业健康安全等信息的管理流程,做好 对事故的防控,对在生产经营、作业场所出现的安全生产、设备设施管理、职业 健康、交通安全、环境保护、劳动纪律、安全操作、安全培训、隐患排查、应急 预案管理等问题,做到早发现、早处理、早排除,确保企业安全管理责任落实到 位,消除事故隐患,特制订本制度。 2 适应范围 荻港海螺公司生产经营、作业场所出现的安全生产、设备设施管理、职业健 康、交通安全、环境保护、劳动纪律、安全操作、安全培训、隐患排查、应急预 案管理等方面的隐患信息管理适用本规定。 3 引用文件 《企业安全生产标准化基本规范》 《冶金等工贸行业企业安全生产预警系统技术标准(试行)》 4 职责 4.1 设备保全处、安全环保处负责监督、指导各单位预测预警系统的使用与 维护。 4.2 公司各单位领导、工段长、专兼职安全员负责对系统中教育培训、应急 救援、事故管理、隐患登记、隐患整改等内容的填写。 5 工作内容 5.1 各级单位日常进行的安全教育培训,培训结束后次日下午下班之前将培 训概要录入教",
    "contentFormatter": {
      "excludedEmbedMetadataKeys": [],
      "excludedInferenceMetadataKeys": [],
      "metadataSeparator": "\r\n",
      "metadataTemplate": "{key}: {value}",
      "textTemplate": "{metadata_string}\n\n{content}"
    },
    "embedding": [],
    "formattedContent": "source: 安全预警预测管理制度.pdf\n\n安全预警预测管理制度 Q/DHG05.20(87)---2019A1 1 目的 为提升公司安全管理水平,规范各类职业健康安全等信息的管理流程,做好 对事故的防控,对在生产经营、作业场所出现的安全生产、设备设施管理、职业 健康、交通安全、环境保护、劳动纪律、安全操作、安全培训、隐患排查、应急 预案管理等问题,做到早发现、早处理、早排除,确保企业安全管理责任落实到 位,消除事故隐患,特制订本制度。 2 适应范围 荻港海螺公司生产经营、作业场所出现的安全生产、设备设施管理、职业健 康、交通安全、环境保护、劳动纪律、安全操作、安全培训、隐患排查、应急预 案管理等方面的隐患信息管理适用本规定。 3 引用文件 《企业安全生产标准化基本规范》 《冶金等工贸行业企业安全生产预警系统技术标准(试行)》 4 职责 4.1 设备保全处、安全环保处负责监督、指导各单位预测预警系统的使用与 维护。 4.2 公司各单位领导、工段长、专兼职安全员负责对系统中教育培训、应急 救援、事故管理、隐患登记、隐患整改等内容的填写。 5 工作内容 5.1 各级单位日常进行的安全教育培训,培训结束后次日下午下班之前将培 训概要录入教",
    "id": "9273ea23-0e3a-4245-98ea-0411ffb80361",
    "media": [],
    "metadata": {
      "source": "安全预警预测管理制度.pdf"
    }
  }

逐个字段解释

  1. content
    原始文本块(chunk分片后的原文),就是PDF切出来的正文内容。

只存纯业务文本,不带元数据。

  1. metadata
    元数据,key‑value。这里source记录来源文件名。
  • 可以存:文件名、页码、文档ID、创建时间、分类。
  • 向量库检索的时候,可以做过滤查询 :例如只查source="安全预警预测管理制度.pdf"的片段。
  1. id
    文档唯一ID,UUID字符串。
    存入向量数据库时作为这条向量记录的主键。

如果不手动指定,SpringAI会自动生成随机UUID。

  1. formattedContent
    给大模型LLM用的拼接好的完整文本 。
    看模板:{metadata_string}\n\n{content}
    实际效果:把metadata拼在最前面,再换行放正文。

    source: 安全预警预测管理制度.pdf

    安全预警预测管理制度......

RAG召回文档之后,把formattedContent丢给大模型,而不是原始content。

  1. contentFormatter
    格式化器配置,控制formattedContent怎么拼接出来。
json 复制代码
"contentFormatter": {
  "excludedEmbedMetadataKeys": [],      // 生成向量时,哪些metadata不要拼进文本
  "excludedInferenceMetadataKeys": [],  // 给大模型推理时,哪些metadata不要拼进文本
  "metadataSeparator": "\r\n",          // 多个元数据之间换行分隔
  "metadataTemplate": "{key}: {value}", // 元数据行格式 key: value
  "textTemplate": "{metadata_string}\n\n{content}" // 整体拼接模板
}
  • excludedEmbedMetadataKeys:比如填["source"],生成向量的时候就不会把source拼进文本去算embedding。
  • excludedInferenceMetadataKeys:传给大模型的时候忽略某些元数据。

⚠️重点坑:

很多人踩坑:metadata会拼进文本参与向量计算。如果你不想文件名参与向量计算,就把source放到excludedEmbedMetadataKeys。

  1. embedding

    向量浮点数数组,float[]。

    []空数组 = 尚未向量化 ,还没调用EmbeddingModel。

    调用embeddingModel.embed(document)之后,这里会填满几百个浮点数,存入向量库。

  2. media

    图片/多媒体资源,RAG纯文本场景永远是空数组。

    用于多模态,存图片Media对象。


关键业务理解

  1. content 原始分片文本;formattedContent 是拼接元数据后的最终给LLM的文本。
  2. 向量是拿什么文本算出来的?
    看contentFormatter配置:默认会把metadata+content一起拼接,再去生成向量。

很多人踩坑:source文件名会参与向量计算,干扰相似度检索。不想这样,配置excludedEmbedMetadataKeys: ["source"]。

  1. embedding:[] 代表还没执行向量化,此时直接丢进VectorStore,会由VectorStore内部自动调用EmbeddingModel补全向量。
  2. metadata不参与向量计算,但是存入向量库,可以做元数据过滤检索。

和LangChain4j TextSegment简单对比

  • SpringAI:Document,字段:content、metadata、embedding、formattedContent
  • LangChain4j:TextSegment,字段:text、metadata、embedding

SpringAI多了一套contentFormatter/formattedContent格式化机制,LangChain4j没有这个概念。

相关推荐
VIP_CQCRE7 小时前
GPT Image 2.6 商品图换背景后悬浮?接触阴影、透明区域与反射验收
图像处理·人工智能·ai·电商
泯泷8 小时前
别再傻傻地喂文件了,大厂都在偷偷给AI建这种“专属图书馆”
人工智能
oak隔壁找我8 小时前
一款运行在 DSH(DeepSeek Harness)中的类 Postman HTTP 接口调试插件
人工智能·程序员
高洁018 小时前
数字孪生与计算机视觉:让机器看懂现场
人工智能·python·机器学习·transformer·迁移学习
Csvn9 小时前
如果明天供应商涨价 3 倍?三层解耦,换模型只改一行配置(C05)
人工智能·aigc·agent
在所不辞兄10 小时前
为什么数字孪生驱动的产线标定需要在线更新机制,而不能一次标定后长期沿用?
人工智能·神经网络·其他·算法·机器学习
锋行天下10 小时前
langgraph 全栈项目(三)
前端·人工智能·后端
黄啊码11 小时前
【黄啊码】最近面了十几个想转 FDE 的程序员,一个都没招
人工智能
锋行天下11 小时前
langgraph 全栈项目(二)
前端·人工智能·后端
大模型真好玩11 小时前
用 Seedance 2.5 Flash 实现1分钟AI短剧,满足孩子的超级英雄对战梦
人工智能·aigc·deepseek