文章目录1. Document 对象1.1 构造函数1.2 属性1.3 方法1.4 ImageDocument2. 基础操作2.1 自动生成2.2 手动构建2.3 自定义文档 ID3. 文档元数据3.1 元数据是什么3.2 三种设置元数据的方式3.3 控制 LLM 可见性3.4 控制 Embedding 可见性3.5 自定义元数据拼接格式3.6 LLM 自动提取元数据3.7 提取元数据3.8 日期时间元数据4. 参考案例1. Document 对象Document文档与Node节点对象是LlamaIndex的核心抽象。Document是任意数据源的通用容器例如PDF文件、API返回结果、数据库查询得到的数据。文档既可以手动构造也可以通过数据加载器自动生成。默认情况下Document存储文本以及一些附加属性部分核心属性如下metadata字典类型可附加到文本上的注解信息。relationships字典类型保存与其他Document/Node的关联关系。Document是LlamaIndex体系里通用文档数据模型核心设计目标是多框架兼容 历史字段兼容ImageDocument继承自Document封装图片资源能力适配多模态场景。1.1 构造函数为了兼容老版本入参在传给父类Node之前做字段转换与警告def__init__(self,**data:Any)-None:外部业务可以继续使用老字段doc_id/extra_info/text内部统一走新模型id_/metadata/text_resource实现无痛版本迭代。1.2 属性只读属性text向后兼容属性内部调用get_content()本质读取text_resource的文本内容doc_id兼容老接口读写代理到id_配套setter支持赋值get_type()类属性方法固定返回ObjectType.DOCUMENT用于类型识别内置基础字段继承自Nodeid_文档唯一标识metadata文档元数据text_resource文本资源包装对象MediaResourceembedding向量excluded_embed_metadata_keys、excluded_llm_metadata_keys元数据过滤配置1.3 方法序列化相关custom_model_dumpPydantic wrap序列化钩子序列化时主动补充text字段保证老客户端解析兼容即使底层存储使用text_resource对外输出依然存在text。多框架格式互转核心能力方法作用to_langchain_format / from_langchain_format和LangChain Document互相转换to_haystack_format / from_haystack_format和Haystack Document互相转换to_embedchain_format / from_embedchain_format和EmbedChain文档结构互转to_semantic_kernel_format / from_semantic_kernel_format和Semantic Kernel MemoryRecord互转to_cloud_document / from_cloud_document对接LlamaCloud旧版SDK文档模型已废弃其他工具方法to_vectorflow无原生文档模型落地方式是写入临时文件调用客户端embedexample()类方法返回标准Document样例用于测试/示例class_name()返回类名Document框架内部反射识别使用__str__格式化打印截断超长文本方便日志输出展示Doc ID 摘要文本1.4 ImageDocument继承普通文档能力新增图片资源封装是LlamaIndex多模态文档载体。注存储图片属于Beta测试功能官方正在持续优化多模态能力。2. 基础操作Document继承自TextNode本节所有配置同样适用于TextNode。2.1 自动生成Document可以通过数据加载器自动生成也可以手动构造。所有内置数据加载器包含LlamaHub提供的加载器都会通过load_data函数返回Document对象。fromllama_index.coreimportSimpleDirectoryReader documentsSimpleDirectoryReader(./data).load_data()2.2 手动构建也可以手动构建Document对象fromllama_index.coreimportDocument text_list[text1,text2,...]documents[Document(textt)fortintext_list]快速原型开发时可以使用示例工厂方法快速生成文档documentDocument.example()2.3 自定义文档 IDdoc_id是Document的唯一标识等价于id_用于索引中文档的高效刷新更新。使用SimpleDirectoryReader可以直接把文件完整路径设置为文档IDfromllama_index.coreimportSimpleDirectoryReader documentsSimpleDirectoryReader(./data,filename_as_idTrue).load_data()print([x.doc_idforxindocuments])也可以直接手动修改文档IDdocument.doc_idMy new document id!提示和TextNode一样也可以通过node_id/id_属性读写ID。3. 文档元数据3.1 元数据是什么Document支持携带业务元数据。通过metadata字典可以附加额外信息用于辅助回答、溯源引用来源元数据可以是文件名、分类标签等任意内容。对接向量数据库注意部分向量库要求key为字符串value只能是字符串、浮点数、整数等扁平类型不支持嵌套字典。Document的元数据会自动继承到拆分后的子Node中索引在查询与生成回答时可以读取这些元数据。默认行为元数据会拼接到原始文本一同送入 Embedding 模型与大模型。3.2 三种设置元数据的方式1. 构造对象时传入documentDocument(texttext,metadata{filename:doc_file_name,category:category},)2. 对象创建完成后赋值document.metadata{filename:doc_file_name}3.SimpleDirectoryReader使用file_metadata钩子自动生成元数据fromllama_index.coreimportSimpleDirectoryReader filename_fnlambdafilename:{file_name:filename}# 根据回调函数自动为每个文档设置元数据documentsSimpleDirectoryReader(./data,file_metadatafilename_fn).load_data()SimpleDirectoryReader自动生成元数据示例{file_name:test.docx,file_path:E:\\TD\\study\\LlamaIndexProject\\loader\\data\\test.docx,file_type:application/vnd.openxmlformats‑officedocument.wordprocessingml.document,file_size:37167,creation_date:2026‑08‑25,last_modified_date:2026‑08‑25}3.3 控制 LLM 可见性前面提到默认情况下元数据会参与Embedding生成同时传给LLM。文档可能携带很多元数据但部分字段不希望大模型看到。例如不想让LLM读取文件名但是希望文件名参与向量生成实现检索侧的偏向同时不影响大模型的输入上下文。排除字段示例document.excluded_llm_metadata_keys[file_name]使用get_content()指定MetadataMode.LLM查看大模型实际读到的完整文本fromllama_index.core.schemaimportMetadataModeprint(document.get_content(metadata_modeMetadataMode.LLM))输出示例file_path:E:\TD\study\LlamaIndexProject\loader\data\test.docx file_type:application/vnd.openxmlformats-officedocument.wordprocessingml.document file_size:37167creation_date:2026-08-25last_modified_date:2026-08-25RAG技术测试文档3.4 控制 Embedding 可见性同理可以指定某些元数据不参与向量生成避免干扰Embedding结果。document.excluded_embed_metadata_keys[file_name]使用MetadataMode.EMBED查看向量模型实际读取的文本fromllama_index.core.schemaimportMetadataModeprint(document.get_content(metadata_modeMetadataMode.EMBED))3.5 自定义元数据拼接格式LlamaIndex在把文档交给Embedding、LLM前会将metadata字典拼接成字符串和正文合并由3个模板属性共同控制最终输出文本。格式由三个属性控制metadata_seperator元数据键‑值对之间的分隔符示例改为::多条元数据就用::隔开。metadata_template单条元数据格式化模板示例{key}{value}输出变成categoryfinance。text_template把拼接好的元数据字符串metadata_str和原文content组装成最终文本。代码示例fromllama_index.coreimportDocumentfromllama_index.core.schemaimportMetadataMode documentDocument(textThis is a super-customized document,metadata{file_name:super_secret_document.txt,category:finance,author:LlamaIndex,},excluded_llm_metadata_keys[file_name],metadata_seperator::,metadata_template{key}{value},text_templateMetadata: {metadata_str}\n-----\nContent: {content},)print(大模型看到的内容: \n,document.get_content(metadata_modeMetadataMode.LLM),)print(Embedding模型看到的内容: \n,document.get_content(metadata_modeMetadataMode.EMBED),)输出示例大模型看到的内容:Metadata:categoryfinance::authorLlamaIndex-----Content:Thisisasuper-customized document Embedding模型看到的内容:Metadata:file_namesuper_secret_document.txt::categoryfinance::authorLlamaIndex-----Content:Thisisasuper-customized document3.6 LLM 自动提取元数据使用Metadata Extractor模块可以借助大模型自动生成元数据。内置提取器SummaryExtractor自动为节点生成摘要QuestionsAnsweredExtractor提取该节点能够回答的若干问题TitleExtractor基于节点上下文生成标题EntityExtractor提取文本中出现的实体人名、地名、事物等提取器可以和节点解析器串联接入数据摄入流水线fromllama_index.core.extractorsimport(TitleExtractor,QuestionsAnsweredExtractor,)fromllama_index.core.node_parserimportTokenTextSplitter text_splitterTokenTextSplitter(separator ,chunk_size512,chunk_overlap128)title_extractorTitleExtractor(nodes5)qa_extractorQuestionsAnsweredExtractor(questions3)# 假设 documents 已经加载完成执行流水线fromllama_index.core.ingestionimportIngestionPipeline pipelineIngestionPipeline(transformations[text_splitter,title_extractor,qa_extractor])nodespipeline.run(documentsdocuments,in_placeTrue,show_progressTrue,)也可以在构建索引时直接传入转换列表fromllama_index.coreimportVectorStoreIndex indexVectorStoreIndex.from_documents(documents,transformations[text_splitter,title_extractor,qa_extractor])3.7 提取元数据SimpleDirectoryReader会自动为每个Document对象挂载元数字典。默认包含以下字段file_path文件完整路径含文件名字符串file_name文件名含后缀字符串file_type通过mimetypes.guess_type()推测得到的 MIME 类型字符串file_size文件大小单位字节整数creation_date、last_modified_date、last_accessed_date文件创建、修改、访问时间统一转换为UTC时区字符串。可以自定义元数据生成逻辑编写函数接收文件路径字符串返回字典通过file_metadata参数传入读取器defget_meta(file_path):return{foo:bar,file_path:file_path}readerSimpleDirectoryReader(input_dirpath/to/directory,file_metadataget_meta)docsreader.load_data()print(docs[0].metadata[foo])# 输出 bar3.8 日期时间元数据默认元数据函数输出日期格式为%Y‑%m‑%d。为保证跨平台一致性时间戳统一转为UTC时区。如果看到日期和实际日期差一天大概率是UTC零点时区偏移导致。4. 参考案例SEC文档元数据提取LLM调研文档提取实体提取‑气候案例Marvin元数据提取DemoPydantic结构化元数据提取