跳至内容

定义与自定义文档#

定义文档#

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

默认情况下，我们所有的数据加载器（包括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, ...]
documents = [Document(text=t) for t in text_list]

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

document = Document.example()

自定义文档#

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

元数据#

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

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

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

  1. 在文档构造函数中：
document = Document(
    text="text",
    metadata={"filename": "<doc_file_name>", "category": "<category>"},
)
  1. 文档创建后：
document.metadata = {"filename": "<doc_file_name>"}
  1. 使用SimpleDirectoryReader和file_metadata钩子自动设置文件名。这将自动在每个文档上运行钩子来设置metadata字段：
from llama_index.core import SimpleDirectoryReader

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

# automatically sets the metadata of each document according to filename_fn
documents = SimpleDirectoryReader(
    "./data", file_metadata=filename_fn
).load_data()

自定义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也可以通过Document对象上的node_id或id_属性设置，类似于TextNode对象。

高级 - 元数据自定义#

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

自定义LLM元数据文本#

通常，一个文档可能包含许多元数据键，但在响应合成过程中，您可能不希望所有元数据都对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))

自定义嵌入元数据文本#

类似于定制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))

自定义元数据格式#

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

  1. Document.metadata_seperator -> 默认值 = "\n"

在拼接元数据的所有键/值字段时，此字段控制每个键/值对之间的分隔符。

  1. Document.metadata_template -> 默认值 = "{key}: {value}"

该属性控制元数据中每个键/值对的格式化方式。必须包含两个变量：字符串键key和value。

  1. 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),
)

高级功能 - 自动元数据提取#

我们提供了初步示例，展示如何使用LLM自身执行元数据提取。

优云智算