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"
    }
  }

逐个字段解释

content
原始文本块（chunk分片后的原文），就是PDF切出来的正文内容。

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

metadata
元数据，key‑value。这里source记录来源文件名。

可以存：文件名、页码、文档ID、创建时间、分类。
向量库检索的时候，可以做过滤查询 ：例如只查source="安全预警预测管理制度.pdf"的片段。

id
文档唯一ID，UUID字符串。
存入向量数据库时作为这条向量记录的主键。

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

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

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

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

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

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。

embedding

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

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

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

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

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

关键业务理解

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

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

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

和LangChain4j TextSegment简单对比

SpringAI：Document，字段：content、metadata、embedding、formattedContent
LangChain4j：TextSegment，字段：text、metadata、embedding

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