内容参考于：图灵AI大模型全栈

llamaindex会把文档读取成Document类型

Document类型中存放了文档中的内容（text）、元数据（文件名、页码、创建时间、自定义内容等）元数据英文叫metadata、Document可以通过加载器自动创建，也可以我们自己创建

文档分割完之后的数据被称为Node，也就是节点，读取分割后的文档使用的是加载器（英文叫Reader）

Document

下图红框是LLamaIndex给我生成的Document对象

{
  "id_": "12f9b415-fe16-44ce-9408-c5534a9532bc",
  "embedding": null,
  "metadata": {
    "file_path": "data_file\\txt1.txt",
    "file_name": "txt1.txt",
    "file_type": "text/plain",
    "file_size": 14,
    "creation_date": "2026-07-07",
    "last_modified_date": "2026-07-07"
  },
  "excluded_embed_metadata_keys": [
    "file_name",
    "file_type",
    "file_size",
    "creation_date",
    "last_modified_date",
    "last_accessed_date"
  ],
  "excluded_llm_metadata_keys": [
    "file_name",
    "file_type",
    "file_size",
    "creation_date",
    "last_modified_date",
    "last_accessed_date"
  ],
  "relationships": {},
  "metadata_template": "{key}: {value}",
  "metadata_separator": "\n",
  "text_resource": {
    "embeddings": null,
    "text": "我是txt1.txt",
    "path": null,
    "url": null,
    "mimetype": null
  },
  "image_resource": null,
  "audio_resource": null,
  "video_resource": null,
  "text_template": "{metadata_str}\n\n{content}",
  "class_name": "Document",
  "text": "我是txt1.txt"
}

带注释

{
    // 【全局唯一主键】
    // 类型：字符串（UUID v4 格式）
    // 作用：Document 的全局唯一身份标识，索引构建、向量存储、节点关联、检索溯源全链路都通过该 ID 定位文档
    // 未手动指定时由框架自动生成；对外提供 doc_id / node_id 两个别名属性，本质都是读写该字段
    "id_": "12f9b415-fe16-44ce-9408-c5534a9532bc",

    // 【文本向量嵌入（顶层兼容字段）】
    // 类型：float数组 / null
    // 作用：存储文档文本对应的语义向量，是语义相似度检索的核心数据
    // 刚加载未向量化时为 null；调用 Embedding 模型后会被填充为浮点数向量
    // 0.10+ 多模态版本后，该字段为顶层兼容字段，数据会同步存储在 text_resource.embeddings 中
    "embedding": null,

    // 【元数据字典】
    // 类型：Dict[str, Any]，开放键值对结构
    // 作用：存储文档的附加结构化属性，支持检索过滤、文档溯源、增量更新、业务标识等扩展能力
    // 示例中为 SimpleDirectoryReader 自动注入的文件系统元数据，各子字段含义如下
    "metadata": {
        // 源文件在本地的相对/绝对路径，用于文档溯源、增量更新时定位源文件
        "file_path": "data_file\\txt1.txt",
        // 源文件的文件名，用于结果展示、人工识别文档来源
        "file_name": "txt1.txt",
        // 文件的 MIME 类型标识，加载器据此选择对应的解析逻辑
        "file_type": "text/plain",
        // 文件大小，单位：字节
        "file_size": 14,
        // 文件创建日期，格式 YYYY-MM-DD，可用于时间范围过滤检索
        "creation_date": "2026-07-07",
        // 文件最后修改日期，增量索引更新时通过该字段判断文件是否变更，避免重复解析
        "last_modified_date": "2026-07-07"
    },

    // 【Embedding 排除元数据键】
    // 类型：字符串数组
    // 作用：指定哪些元数据键不参与向量计算（对嵌入模型不可见）
    // 避免文件名、文件大小这类无语义的字段干扰文本向量的语义准确性
    // 被排除的元数据仍保留在 metadata 中，可用于检索过滤，只是不拼接入向量化文本
    "excluded_embed_metadata_keys": [
        "file_name",
        "file_type",
        "file_size",
        "creation_date",
        "last_modified_date",
        "last_accessed_date"
    ],

    // 【LLM 排除元数据键】
    // 类型：字符串数组
    // 作用：指定哪些元数据键不拼入传给大模型的上下文（对 LLM 不可见）
    // 避免文件系统类冗余信息占用 LLM 上下文窗口、干扰生成结果
    // 被排除的元数据仍可用于检索阶段过滤，仅在生成阶段隐藏
    "excluded_llm_metadata_keys": [
        "file_name",
        "file_type",
        "file_size",
        "creation_date",
        "last_modified_date",
        "last_accessed_date"
    ],

    // 【节点关联关系字典】
    // 类型：Dict[NodeRelationship枚举, RelatedNodeInfo]
    // 作用：存储当前文档与其他 Document/Node 的关联关系，如父子节点、前后文节点、源文档等
    // 完整 Document 刚加载时通常为空；文档分块后，子 Node 会通过该字段关联父 Document
    // 常见关系类型：SOURCE（源文档）、PARENT/CHILD（层级分块）、PREVIOUS/NEXT（同层前后文）
    "relationships": {},

    // 【单条元数据格式化模板】
    // 类型：字符串
    // 作用：定义元数据键值对的拼接格式，占位符 {key} 对应元数据键，{value} 对应元数据值
    // 示例中 "file_name: txt1.txt" 就是按该模板生成的
    "metadata_template": "{key}: {value}",

    // 【多条元数据分隔符】
    // 类型：字符串
    // 作用：多条元数据键值对拼接时的分隔符号，默认为换行符，让元数据逐行展示
    // 注：部分旧版本拼写为 metadata_seperator（拼写笔误），新版本已修正为 separator
    "metadata_separator": "\n",

    // 【文本模态资源对象（0.10+ 多模态重构核心）】
    // 类型：TextResource 对象
    // 作用：新版框架中，文本内容、对应向量的标准存储位置，统一封装文本类资源的所有信息
    // 顶层的 text、embedding 字段均为兼容旧接口的别名，最终数据同步到该对象中
    "text_resource": {
        // 文本对应的向量嵌入，与顶层 embedding 字段数据完全同步
        "embeddings": null,
        // 文档的核心文本内容，是 LLM 和 Embedding 模型处理的主体
        "text": "我是txt1.txt",
        // 文本本地路径，仅当文本来自外部文件且未加载到内存时填充；内存中文档为 null
        "path": null,
        // 文本远程 URL，仅当文本来自网络资源时填充；本地文档为 null
        "url": null,
        // 文本资源的 MIME 类型标识
        "mimetype": null
    },

    // 【图片模态资源对象】
    // 类型：ImageResource 对象 / null
    // 作用：存储图片模态的资源数据（图片内容、向量、路径等）
    // 纯文本文档该字段为 null；仅多模态文档/图片文档会填充
    "image_resource": null,

    // 【音频模态资源对象】
    // 类型：AudioResource 对象 / null
    // 作用：存储音频模态的资源数据；纯文本文档为 null
    "audio_resource": null,

    // 【视频模态资源对象】
    // 类型：VideoResource 对象 / null
    // 作用：存储视频模态的资源数据；纯文本文档为 null
    "video_resource": null,

    // 【整体内容格式化模板】
    // 类型：字符串
    // 作用：定义「元数据字符串 + 正文」的整体拼接格式
    // 占位符 {metadata_str} 对应拼接好的元数据文本，{content} 对应文档正文
    // 最终传给 LLM / Embedding 的文本就是按该模板组装的
    "text_template": "{metadata_str}\n\n{content}",

    // 【对象类型标识】
    // 类型：字符串
    // 作用：Pydantic 序列化/反序列化的类型标记，反序列化时自动还原为对应类实例
    // 常见取值：Document、TextNode、ImageNode 等，由框架自动填充，无需手动修改
    "class_name": "Document",

    // 【文档正文（顶层兼容字段）】
    // 类型：字符串
    // 作用：旧版框架的正文字段，0.10+ 版本中为向下兼容保留
    // 其值与 text_resource.text 完全同步，读写该字段本质是操作 text_resource.text
    "text": "我是txt1.txt"
}

手动创建Document

如下图手动创建Document

代码

# 从 LlamaIndex 核心模块导入 Document 文档实体类
# 类定位：LlamaIndex 知识库体系的基础文档单元，所有待入库做语义检索的文本内容，都必须先封装为 Document 实例
# 核心必填属性：text（字符串类型，文档正文内容，是后续文本切分、向量化、检索的核心载体）
# 核心可选属性：
#   - metadata：字典类型，存储文档附属元数据，字段完全支持自定义
#   - id_：字符串类型，文档唯一标识，不手动指定时框架会自动生成
# 数据流向：Document 会经过文本切分器拆分为多个 Node 节点，再生成向量存入索引，最终用于语义召回
from llama_index.core import Document

# 原始纯文本数据源，示例包含两段待入库的文本内容
# 实际业务场景中，通常来自文件批量读取、数据库查询、接口返回、爬虫结果等批量文本源
text_list = ["text1", "text2"]

# 通过列表推导式，批量将纯文本转换为带元数据的 Document 对象列表
# 遍历逻辑：依次取出 text_list 中的每一段文本赋值给变量 t，为每段文本生成一个独立的 Document 实例
# 构造参数说明：
#   text=t：必填参数，将当前遍历到的纯文本赋值给文档正文字段
#   metadata：可选参数，字典类型，文档附属元数据
#       核心特性：元数据会跟随文档切分后的每一个子节点（Node），检索返回的文本片段也会携带对应元数据
#       业务用途：支持检索时的条件过滤、结果溯源、业务分类、权限控制等场景，字段名与字段值无强制约束，可完全自定义
#       示例字段：
#           filename：标记文本来源的文件名称，用于检索结果溯源
#           category：业务分类字段，可用于检索时按类别过滤结果
#           xxxx：完全自定义的扩展字段，演示元数据可按需任意扩展
documents = [Document(text=t, metadata={"filename": "文件名称", "category": "类别","xxxx":"我是随便写的"}) for t in text_list]

# 以 repr 形式打印文档对象列表，用于开发调试
# repr() 内置函数作用：调用对象的 __repr__ 方法，返回对象的「官方结构化表示」，尽可能完整地展示对象的内部属性与结构
# 与直接 print(documents) 的核心区别：
#   - 直接 print 会调用 __str__ 方法，输出偏向人类阅读的简化格式，信息更精简
#   - repr 输出偏向开发调试的完整格式，能完整看到 Document 对象的 id、text、metadata 等全部核心属性的具体值
# 输出内容：列表中每个 Document 实例的完整属性信息，包括文档ID、正文内容、元数据字典、以及框架内置的其他默认属性
print(repr(documents) )

加载器读取文件

效果图：

下方的代码是使用的SimpleDirectoryReader加载的文档，它加载文档的方式并不好，仅仅是加载文档，需要通过file_extractor指定某类型文件的处理方式才可以加载的文档好一点

# 从 LlamaIndex 核心模块导入目录文档加载器
# 类全称：SimpleDirectoryReader
# 核心作用：批量扫描指定目录下的文件，自动根据文件后缀调用对应解析器，将文件内容转换为 Document 对象列表
# 原生支持格式：txt、md、pdf、docx、csv、html、json 等多种常见文档类型
# 典型场景：构建本地知识库时批量加载文件夹内的文档，是 LlamaIndex 最常用的批量文档加载工具
from llama_index.core import SimpleDirectoryReader


# 自定义 PDF 解析函数（占位实现）
# 作用：作为自定义文件提取器，替换框架默认的 PDF 解析逻辑，可接入更精准的解析工具（如 MinerU、PyMuPDF 等）
# 接口要求：接收文件路径作为入参，返回解析后的 Document 对象列表（List[Document]）
# 绑定方式：通过 file_extractor 参数和对应文件后缀关联，框架遇到该后缀的文件时会自动调用此函数解析
def parser():
    # 此处编写自定义 PDF 解析逻辑，例如调用第三方解析库提取文本、表格、版式信息
    pass


# 实例化目录加载器，配置扫描规则、过滤条件与解析行为
reader = SimpleDirectoryReader(
    # input_dir：核心参数，字符串类型，指定待扫描的目标文件夹根路径
    # 框架会以该目录为起点，按照后续配置的规则扫描内部文件
    input_dir="./data_file",
    # required_exts：可选参数，字符串列表类型，限定只加载指定后缀的文件
    # 作用：过滤无关文件，仅保留业务需要的文档类型；后缀名必须带点，大小写敏感
    # 不配置该项时，框架会加载所有原生支持格式的文件
    required_exts=[".pdf", ".docx", ".md", ".txt"],
    # recursive：可选参数，布尔类型，默认值 False
    # 作用：是否递归遍历所有层级的子文件夹；设为 True 时会扫描所有子目录下的匹配文件
    recursive=True,
    # exclude_hidden：可选参数，布尔类型，默认值 True
    # 作用：是否排除隐藏文件；开启后会跳过系统隐藏文件（如 Linux 下 . 开头的文件、Windows 隐藏属性文件）
    exclude_hidden=True,
    # exclude_empty：可选参数，布尔类型，默认值 True
    # 作用：是否排除大小为 0 的空文件，避免无效文档进入知识库
    exclude_empty=True,
    # filename_as_id：可选参数，布尔类型，默认值 False
    # 作用：是否使用文件名作为 Document 的 doc_id 唯一标识
    # 开启优势：文档溯源更直观，可直接通过 id 定位来源文件
    # 注意事项：不同子目录下存在同名文件时会出现 id 冲突，该场景不建议开启
    filename_as_id=True,
    # file_extractor：可选参数，字典类型，自定义文件后缀与解析器的映射关系
    # 键：文件后缀名（带点）；值：对应的解析器对象/解析函数
    # 作用：覆盖框架默认的解析逻辑，为指定类型文件使用自定义解析方案
    # 示例含义：所有 .pdf 后缀的文件，都调用自定义的 parser 函数进行解析
    file_extractor={".pdf": parser},
    # exclude：可选参数，字符串列表类型，指定需要排除的文件
    # 支持填写具体文件名，也支持通配符模式（如 "*.log" 排除所有日志文件）
    # 示例含义：扫描时跳过名为 111.txt 的文件
    exclude=['111.txt'],
    # num_files_limit：可选参数，整数类型，最大加载文件数量限制
    # 作用：防止目录内文件数量过多导致加载超时、内存溢出，超过限制数量后停止加载
    num_files_limit=1000,
)

# Python 脚本入口保护：仅当直接运行该脚本时执行加载逻辑，被其他文件导入时不执行
if __name__ == '__main__':
    # 执行文档加载，返回解析后的 Document 对象列表
    # 方法名：load_data
    # 入参说明：
    #   show_progress：布尔类型，默认 False；是否显示加载进度条，文件数量多时便于观察进度
    #   num_workers：整数类型，默认 1；并行加载的工作线程数量
    #       作用：多线程并行解析文件，提升批量加载速度；IO 密集型场景可适当调大，建议不超过 CPU 核心数
    # 返回值：List[Document]，每个成功解析的文件对应一个 Document 对象，自动携带文件属性元数据
    documents = reader.load_data(show_progress=True, num_workers=3)

    # 打印完整的 Document 对象列表，用于调试校验文档内容与元数据
    print(documents)
    # 打印加载成功的文档总数，快速确认加载结果是否符合预期
    print(f"成功加载 {len(documents)} 个 Document 对象")

SimpleDirectoryReader这个加载器它把文件全部读取完成后才会返回，如果我们想在读取的过程中做点什么需要用迭代器的方式

如下图迭代器的方式

# 从 LlamaIndex 核心模块导入目录文档加载器
# 类全称：SimpleDirectoryReader
# 核心作用：扫描指定目录下的文件，自动按后缀匹配对应解析器，将文件内容转换为 Document 对象
# 原生支持格式：txt、md、pdf、docx、csv、html、json 等常见文档类型
# 两种加载模式：一次性全量加载（load_data）、迭代器逐份加载（iter_data）
# 定位：LlamaIndex 最常用的本地批量文档加载入口
from llama_index.core import SimpleDirectoryReader


# 自定义 PDF 解析函数（占位实现）
# 接口规范：实际使用时必须接收「文件路径字符串」作为入参，返回 List[Document] 类型结果
# 作用：通过 file_extractor 绑定后，框架遇到 .pdf 文件会自动调用该函数，替换默认的 PDF 解析逻辑
# 扩展方向：可接入 MinerU、PyMuPDF、PaddleOCR 等更专业的解析工具，提升文本/表格/版式提取效果
def parser():
    # 这里编写自定义 PDF 解析逻辑，例如调用第三方库提取文本、结构化信息
    pass


# 实例化目录加载器，配置扫描规则、过滤条件与解析行为
reader = SimpleDirectoryReader(
    # input_dir：必填参数，指定待扫描的目标文件夹根路径
    # 框架以此目录为起点，按后续规则扫描内部文件
    input_dir="./data_file",
    # required_exts：可选参数，字符串列表，限定仅加载指定后缀的文件
    # 后缀必须带点号，大小写敏感；不配置则加载所有原生支持格式的文件
    required_exts=[".pdf", ".docx", ".md", ".txt"],
    # recursive：可选参数，布尔值，默认 False
    # True 表示递归遍历所有层级子文件夹；False 仅扫描当前一级目录
    recursive=True,
    # exclude_hidden：可选参数，布尔值，默认 True
    # True 表示自动排除系统隐藏文件，避免无关文件进入知识库
    exclude_hidden=True,
    # exclude_empty：可选参数，布尔值，默认 True
    # True 表示自动排除大小为 0 的空文件，过滤无效文档
    exclude_empty=True,
    # filename_as_id：可选参数，布尔值，默认 False
    # True 表示用文件名作为 Document 的 doc_id 唯一标识，便于溯源
    # 注意：多子目录存在同名文件时会触发 id 冲突，该场景不建议开启
    filename_as_id=True,
    # file_extractor：可选参数，字典类型，自定义文件后缀与解析器的映射
    # 键为文件后缀（带点），值为解析函数/解析器对象；会覆盖框架默认解析逻辑
    file_extractor={".pdf": parser},
    # exclude：可选参数，字符串列表，指定需要排除的文件
    # 支持具体文件名，也支持通配符模式（如 "*.log"）
    exclude=['111.txt'],
    # num_files_limit：可选参数，整数，最大加载文件数量上限
    # 超过限制后停止加载，避免文件量过大导致超时或内存溢出
    num_files_limit=1000,
)

# Python 脚本入口保护：仅直接运行脚本时执行加载逻辑，被导入时不执行
if __name__ == '__main__':
    # ========== 以下为 load_data 全量加载写法（已注释） ==========
    # load_data：一次性加载所有匹配文件，返回完整的 Document 对象列表
    # show_progress：是否显示加载进度条，文件量大时便于观察进度
    # num_workers：并行加载的线程数，多线程提升批量加载速度，IO 密集型场景可适当调大
    # 特点：加载完成后所有文档都在内存中，使用方便；文件量大时内存占用高
    # documents = reader.load_data(show_progress=True, num_workers=3)
    # print(documents)
    # print(f"成功加载 {len(documents)} 个 Document 对象")

    # ========== 当前启用：iter_data 迭代器逐份加载 ==========
    # 方法名：iter_data
    # 核心特性：返回生成器迭代器，逐个产出 Document 对象，边遍历边解析文件
    # 核心优势：不会一次性把所有文档加载进内存，内存峰值极低
    # 适用场景：文件数量极大、内存资源紧张、需要逐份处理后立即释放的场景
    # show_progress：是否显示加载进度条
    data = reader.iter_data(show_progress=True)
    
    # 遍历生成器，每轮循环拿到一个 Document 对象
    # 变量 i 类型：单个 Document 实例，包含文件正文与自动附加的文件元数据
    for i in data:
        print("*" * 100)
        # 打印单份文档对象，可查看正文、元数据、文档ID等信息
        print(i)

除了上方的SimpleDirectoryReader加载器，LLamaIndex还提供了其它的很多加载器

如下图红框，其它的数据加载可以在官网中找到

官网地址：https://developers.llamaindex.ai/python/framework-api-reference/readers/

在它里面就可以看到我们上方用的SimpleDirectoryReader加载器，如果不知道用什么加载器，就问ai，让ai告诉你

文档加载处理器

下载方式，llama_index.readers.file库有很多写好的处理文档的代码

pip install llama-index-readers-file

文档地址：https://developers.llamaindex.ai/python/framework-api-reference/readers/file/#llama_index.readers.file.PDFReader

如下图它提供了很多处理文档的代码

代码使用

# 从 LlamaIndex 官方文件读取器模块导入两款专用文档解析类
# 模块归属：llama-index-readers-file 官方扩展包，是专门的文件解析组件集
# 与 SimpleDirectoryReader 内置默认解析的区别：专用读取器解析更稳定、元数据更丰富、可配置性更强
# PDFReader：PDF 格式文档专用解析器
# DocxReader：Word 文档（.docx 格式）专用解析器
from llama_index.readers.file import PDFReader, DocxReader
# 导入目录批量加载器，负责扫描目标目录、匹配文件后缀、调度对应解析器批量加载文档
from llama_index.core import SimpleDirectoryReader


# 定义文件后缀与专用解析器的映射字典
# 作用：传入 SimpleDirectoryReader 的 file_extractor 参数，覆盖框架默认的解析逻辑
# 规则：键为文件后缀（必须带点号），值为对应解析器的实例对象
# 未在该字典中声明的后缀（如示例中的 .md、.txt），仍使用框架内置的默认解析器处理
file_extractor = {
    # PDFReader 实例：负责解析所有 .pdf 后缀文件
    # 默认行为：按 PDF 页面逐页拆分，每一页生成一个独立的 Document 对象
    # 自动附加元数据：page_label（页码）、file_name、file_path、file_size 等文件属性
    # 可选配置：实例化时传入 return_full_document=True，可让整份 PDF 生成单个 Document 对象
    ".pdf": PDFReader(),
    # DocxReader 实例：负责解析所有 .docx 后缀文件
    # 默认行为：解析整个文档的正文内容，整份文件生成一个 Document 对象
    # 自动附加元数据：file_name、file_path、file_size 等文件属性
    ".docx": DocxReader(),
}


# 链式调用：先实例化目录加载器并配置规则，再直接调用 load_data 执行全量加载
# 返回值：List[Document] 类型，所有解析成功的文档对象组成的列表
documents = SimpleDirectoryReader(
    # input_dir：必填参数，字符串类型，指定待扫描的目标文件夹根路径
    input_dir="./data",
    # required_exts：可选参数，字符串列表类型，限定仅加载指定后缀的文件
    # 后缀必须带点号，大小写敏感；不在列表中的文件类型会被直接过滤跳过
    required_exts=[".pdf", ".docx", ".md", ".txt"],
    # file_extractor：可选参数，字典类型，自定义后缀与解析器的映射关系
    # 传入后对应后缀的文件会使用指定的专用解析器，替代框架默认解析逻辑
    file_extractor=file_extractor,
    # recursive：可选参数，布尔类型，默认值 False
    # True 表示递归遍历所有层级的子文件夹；False 仅扫描当前一级目录
    recursive=True,
    # exclude_empty：可选参数，布尔类型，默认值 True
    # True 表示自动排除大小为 0 的空文件，避免无效文档进入知识库
    exclude_empty=True,
# load_data：执行文档加载的核心方法
# 执行流程：扫描目录文件 → 按后缀规则过滤 → 调度对应解析器解析文件 → 汇总返回所有 Document 对象
# 返回值：List[Document]，解析完成的全部文档对象
).load_data()


# 遍历所有加载完成的 Document 对象，逐个打印完整结构
for doc in documents:
    # repr() 内置函数：返回对象的结构化完整表示
    # 输出内容包含 Document 的 id_（文档ID）、text（正文内容）、metadata（元数据）等全部核心属性
    # 用途：开发调试时完整查看文档正文、元数据（如PDF页码、文件名、路径）等详细信息
    print(repr(doc))