定义和自定义文档（Defining and Customizing Documents）

定义和自定义文档（Defining and Customizing Documents）

定义文档（Defining Documents）

文档可以通过数据加载器自动创建，也可以手动构造。

默认情况下，我们所有的数据加载器（包括 LlamaHub 提供的那些）通过 load_data 函数返回 Document 对象。

from llama_index.core import SimpleDirectoryReader

documents = SimpleDirectoryReader("./data").load_data()

你也可以选择手动构造文档。LlamaIndex 暴露了 Document 结构体。

from llama_index.core import Document

text_list = [text1, text2, ...]  # 假设 text1, text2 等是你的文本数据
documents = [Document(text=t) for t in text_list]

为了加快原型设计和开发，你还可以使用一些默认文本快速创建文档：

document = Document.example()

自定义文档（Customizing Documents）

本节介绍各种自定义 Document 对象的方法。由于 Document 对象是 TextNode 对象的子类，所有这些设置和细节也适用于 TextNode 对象类。

元数据（Metadata）

文档还提供了包含有用元数据的机会。使用每个文档上的 metadata 字典，可以包含额外的信息，以帮助通知响应并跟踪查询响应的来源。这些信息可以是任何内容，例如文件名或类别。如果你与向量数据库集成，请记住一些向量数据库要求键必须是字符串，值必须是平面的（字符串、浮点数或整数）。

每个文档的 metadata 字典中设置的任何信息都会出现在从文档创建的每个源节点的元数据中。此外，这些信息包含在节点中，使索引能够在查询和响应中利用它。默认情况下，元数据会注入到文本中，用于嵌入和 LLM 模型调用。

有几种方法可以设置这个字典：

在文档构造函数中：

document = Document(
    text="text",
    metadata={"filename": "<doc_file_name>", "category": "<category>"},
)

在文档创建后：

document.metadata = {"filename": "<doc_file_name>"}

使用 SimpleDirectoryReader 和 file_metadata 钩子自动设置文件名。这将自动对每个文档运行钩子以设置元数据字段：

from llama_index.core import SimpleDirectoryReader

filename_fn = lambda filename: {"file_name": filename}

# 自动根据 filename_fn 设置每个文档的元数据
documents = SimpleDirectoryReader(
    "./data", file_metadata=filename_fn
).load_data()

自定义 ID（Customizing the id）

如文档管理部分所述，doc_id 用于在索引中高效刷新文档。使用 SimpleDirectoryReader 时，你可以自动将每个文档的 doc_id 设置为每个文档的完整路径：

from llama_index.core import SimpleDirectoryReader

documents = SimpleDirectoryReader("./data", filename_as_id=True).load_data()
print([x.doc_id for x in documents])

你也可以直接设置任何 Document 的 doc_id：

document.doc_id = "My new document id!"

注意：ID 也可以通过 node_id 或 id_ 属性在 Document 对象上设置，类似于 TextNode 对象。

高级 - 元数据自定义（Advanced - Metadata Customization）

上面提到的关键细节是，默认情况下，你设置的任何元数据都会包含在嵌入生成和 LLM 中。

自定义 LLM 元数据文本（Customizing LLM Metadata Text）

通常，一个文档可能有许多元数据键，但你可能不希望在响应合成期间所有这些键都对 LLM 可见。在上面的示例中，我们可能不希望 LLM 读取文档的 file_name。然而，file_name 可能包含有助于生成更好嵌入的信息。这样做的一个关键优势是，可以在不改变 LLM 最终读取内容的情况下，偏置嵌入以进行检索。

我们可以这样排除它：

document.excluded_llm_metadata_keys = ["file_name"]

然后，我们可以使用 get_content() 函数并指定 MetadataMode.LLM 来测试 LLM 实际读取的内容：

from llama_index.core.schema import MetadataMode

print(document.get_content(metadata_mode=MetadataMode.LLM))

自定义嵌入元数据文本（Customizing Embedding Metadata Text）

与自定义对 LLM 可见的元数据类似，我们也可以自定义对嵌入模型可见的元数据。在这种情况下，你可以特别排除对嵌入模型可见的元数据，以防你不希望特定文本偏置嵌入。

document.excluded_embed_metadata_keys = ["file_name"]

然后，我们可以使用 get_content() 函数并指定 MetadataMode.EMBED 来测试嵌入模型实际读取的内容：

from llama_index.core.schema import MetadataMode

print(document.get_content(metadata_mode=MetadataMode.EMBED))

自定义元数据格式（Customizing Metadata Format）

如你所知，元数据在发送到 LLM 或嵌入模型时会注入到每个文档/节点的实际文本中。默认情况下，元数据的格式由三个属性控制：

• Document.metadata_seperator -> 默认 = “\n”
  在连接所有键/值字段的元数据时，此字段控制每个键/值对之间的分隔符。

• Document.metadata_template -> 默认 = “{key}: {value}”
  此属性控制元数据中每个键/值对的格式。两个变量 key 和 value 是必需的。

• Document.text_template -> 默认 = “{metadata_str}\n\n{content}”
  一旦使用 metadata_seperator 和 metadata_template 将元数据转换为字符串，此模板控制该元数据与文档/节点文本内容结合时的外观。metadata 和 content 字符串键是必需的。

总结所有这些，让我们创建一个使用所有这些功能的简短示例：

from llama_index.core import Document
from llama_index.core.schema import MetadataMode

document = Document(
    text="This 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_template="Metadata: {metadata_str}\n-----\nContent: {content}",
)

print(
    "The LLM sees this: \n",
    document.get_content(metadata_mode=MetadataMode.LLM),
)
print(
    "The Embedding model sees this: \n",
    document.get_content(metadata_mode=MetadataMode.EMBED),
)

高级 - 自动元数据提取（Advanced - Automatic Metadata Extraction）

我们有一些初始示例使用 LLM 本身进行元数据提取。

通过这些详细的解释和示例，希望你能更好地理解和使用 LlamaIndex 中的 Document 和自定义功能。