Document、Node与离线索引

Document代表输入文档及元数据，Node是切分后的检索单位。Index管理索引结构，Retriever返回候选节点与分数，Response Synthesizer使用模型整合证据，Query Engine连接两者。Chat Engine还要管理对话，不能把它当“自动长期记忆”。

先创建隔离环境，不修改网站项目依赖。下面安装命令需要网络；Python代码没有付费模型调用。

python3.12 -m venv .venv
.venv/bin/pip install llama-index-core==0.14.6

将以下内容保存为lab.py，运行.venv/bin/python lab.py。

from llama_index.core import Document, VectorStoreIndex
from llama_index.core.embeddings import MockEmbedding
from llama_index.core.node_parser import SentenceSplitter

docs = [Document(text='Team A allows two remote days.', id_='policy-a', metadata={'tenant':'A'})]
splitter = SentenceSplitter(chunk_size=64, chunk_overlap=8)
nodes = splitter.get_nodes_from_documents(docs)
assert len(nodes) == 1
assert nodes[0].ref_doc_id == 'policy-a'
index = VectorStoreIndex(nodes, embed_model=MockEmbedding(embed_dim=8))
hits = index.as_retriever(similarity_top_k=1).retrieve('remote policy')
assert len(hits) == 1
assert hits[0].node.metadata['tenant'] == 'A'
print(hits[0].node.text)

MockEmbedding提供确定的假向量，证明数据经过切分与检索接口，不能证明查询理解了“remote”。只有一个候选也无法证明排序正确。改成真实embedding时需固定模型revision、维度和输入模板，并加入至少一个难负例与人工相关标注。

元数据可能默认参与embedding文本和模型上下文；敏感字段应按目的排除，不能把ACL密钥藏在metadata以为不会发送。ref_doc_id将子节点关联到文档，支持删除与追溯；自己生成稳定ID时应包含租户和版本，不依赖随机节点ID维持业务身份。

连接器负责获取数据，解析器负责结构，摄取管道负责变换与缓存。缓存键要覆盖输入和变换配置；解析器升级后旧节点不应误命中。父子节点、句子窗口与自动合并都能扩展上下文，但扩展后要重新检查权限与预算。

练习

在第二份Document上设不同id和tenant，验证每个切分节点能追溯到正确父文档。不要用MockEmbedding得出的名次证明语义相关性。

完成后查看本章答案。

下一章：持久化、重载与文档生命周期。