尧图网站建设 
LlamaIndex 节点Nodes完全指南定义、定制与关系管理【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本文基于 LlamaIndex 官方文档《Defining and Customizing Nodes》展开系统讲解 Nodes 作为 LlamaIndex 一等公民first-class citizen的核心概念如何通过NodeParser将源 Document 解析为 Node 块如何手动构造TextNode并建立节点间关系NodeRelationship以及如何自定义node_id。读完本文你将掌握 LlamaIndex 中文档切块 → 节点构建 → 关系建模 → 身份管理的完整链路并理解底层实现原理。什么是 NodeLlamaIndex 的数据基本单元在 LlamaIndex 中Node节点表示源 Document 的块chunk它可以是一段文本、一张图片或其他更丰富的内容形式。除了内容本身Node 还携带两类关键信息元数据metadata描述该块来源、属性等的扁平字典关系信息relationships记录该节点与其他节点、索引结构之间的关联。这一设计体现在核心类BaseNode上定义于 llama_index/core/schema.py。从源码可以看到BaseNode除id_唯一 ID与embedding向量外还内置了metadata、relationships以及两个用于控制元数据注入行为的字段字段默认值作用metadata{}扁平化的元数据字典会注入 LLM 上下文与 embedding 文本并可用于向量库过滤excluded_embed_metadata_keys[]生成 embedding 时从文本中排除的元数据键excluded_llm_metadata_keys[]提供给 LLM 时从文本中排除的元数据键relationships{}NodeRelationship到关联节点信息的映射metadata_templateDEFAULT_METADATA_TMPL元数据格式化模板占位符为{key}与{value}metadata_separator\n元数据转字符串时字段间的分隔符在 LlamaIndex 中定义 Node 有两条路径一是通过NodeParser把源 Document解析成 Nodes二是完全手动构造 Node 对象并自行设定全部属性。两条路径分别对应下面两节。方式一通过 NodeParser 将 Document 解析为 Nodes当你有成批的Document需要切分成索引友好的块时最直接的方式是使用NodeParser系列类。官方文档给出的最小示例是使用句子级切分器SentenceSplitterfrom llama_index.core.node_parser import SentenceSplitter parser SentenceSplitter() nodes parser.get_nodes_from_documents(documents)解析链路的底层实现get_nodes_from_documents定义于 node_parser/interface.py其执行流程为建立doc_id - Document映射表触发CBEventType.NODE_PARSING回调事件调用抽象方法_parse_nodes完成实际切分同步版或_aparse_nodes异步版调用_postprocess_parsed_nodes做后处理为每个 Node 定位其在父文档中的start_char_idx/end_char_idx、合并父文档元数据、并在同一源文档的相邻节点间建立PREVIOUS/NEXT关系interface.py#L84-L155。后处理阶段的两个开关对应NodeParser基类字段interface.py#L50-L66include_metadataTrue是否把父 Document 的元数据合并进 Nodeinclude_prev_next_relTrue是否自动为同源相邻节点建立前后关系id_func生成节点 ID 的函数默认使用default_id_func。NodeParser本身继承自TransformComponent因此它也实现了__call__/acall同步/异步调用协议可以无缝嵌入 LlamaIndex 的 Transform 流水线interface.py#L203-L207。SentenceSplitter 的切分策略与参数SentenceSplitter的核心目标是尽可能保持完整句子与段落避免在 chunk 末尾出现悬挂的半句话。它定义于 node_parser/text/sentence.py常用参数如下参数默认值说明chunk_size1024DEFAULT_CHUNK_SIZE单位为 token每个 chunk 的目标 token 大小chunk_overlap200SENTENCE_CHUNK_OVERLAP相邻 chunk 之间的 token 重叠量需小于chunk_size否则抛出ValueErrorseparator 按词切分的默认分隔符paragraph_separator\n\n\n段落分隔符优先按段落切分secondary_chunking_regex[^,.;。][,.;。]?\|[,.;。]兜底的句子切分正则tokenizer自动获取自定义 token 计算函数include_metadataTrue切分时是否考虑元数据长度include_prev_next_relTrue是否自动写入前后节点关系id_funcdefault_id_func节点 ID 生成函数元数据感知切分是SentenceSplitter的一个重要特性在split_text_metadata_aware中它会先用 tokenizer 统计元数据长度再用effective_chunk_size chunk_size - metadata_len作为实际切分大小sentence.py#L156-L174。如果元数据长度超过chunk_size会直接抛出ValueError提示增大 chunk_size 或缩减元数据。递归切分顺序_split方法sentence.py#L198-L245按paragraph_separator切段落按句子 tokenizer默认 nltk 句子切分器切句子按secondary_chunking_regex切子句按默认分隔符separator切词最后按字符兜底。若某一段切分后仍超出chunk_size会递归继续细分若出现单个不可再分的超大 token如小 chunk_size 下的多 token CJK 字符则保留为超尺寸 split由_merge抛出明确的 Single token exceeded chunk size 错误而不是死循环。方式二手动构造 Node 与设置关系当你不依赖解析器、希望完全掌控节点结构时可以直接构造TextNode并手工装配关系。官方文档示例from llama_index.core.schema import TextNode, NodeRelationship, RelatedNodeInfo node1 TextNode(texttext_chunk, id_node_id) node2 TextNode(texttext_chunk, id_node_id) # set relationships node1.relationships[NodeRelationship.NEXT] RelatedNodeInfo( node_idnode2.node_id ) node2.relationships[NodeRelationship.PREVIOUS] RelatedNodeInfo( node_idnode1.node_id ) nodes [node1, node2]注意这里id_是构造参数对应BaseNode.id_字段而在属性访问层面使用node_id属性。TextNode定义于 schema.py#L765-L849核心字段包括text节点文本内容mimetype内容 MIME 类型默认text/plainstart_char_idx/end_char_idx节点在源文档中的起止字符位置由解析器后处理自动填充text_template文本与元数据拼接模板。同时TextNode实现了get_content(metadata_mode)、set_content()、hash基于text metadata的 SHA-256等BaseNode抽象接口。RelatedNodeInfo关系载荷与附加元数据RelatedNodeInfo是关系信息的具体载荷schema.py#L249-L260包含node_id被关联节点的 IDnode_type被关联节点的对象类型ObjectTypemetadata附加元数据字典默认{}hash被关联节点的哈希。因此关系不仅可以表达谁连谁还能附带说明性元数据。文档示例即为在 PARENT 关系上携带额外信息node2.relationships[NodeRelationship.PARENT] RelatedNodeInfo( node_idnode1.node_id, metadata{key: val} )NodeRelationship五类标准关系NodeRelationship是定义于 schema.py#L207-L224 的枚举目前包含五类关系枚举值语义值类型SOURCE该节点源自的源文档节点单个RelatedNodeInfoPREVIOUS同一文档中的前一个节点单个RelatedNodeInfoNEXT同一文档中的后一个节点单个RelatedNodeInfoPARENT父节点如层级结构中的上层块单个RelatedNodeInfoCHILD子节点列表List[RelatedNodeInfo]BaseNode为这些关系提供了便捷属性schema.py#L390-L448source_node、prev_node、next_node、parent_node、child_nodes。它们会从relationships字典中提取对应条目并在类型不符时如 SOURCE 被赋成列表抛出明确的ValueError。测试用例 tests/schema/test_base_node.py 逐一验证了这些属性的取值与类型约束行为。此外as_related_node_info()schema.py#L494-L501可将任意节点转换为RelatedNodeInfo携带node_id、node_type、metadata、hash便于快速把已有节点挂到某个关系上——这也是解析器自动建立PREVIOUS/NEXT关系的底层手段。自定义 node_id节点身份管理每个 Node 都有一个node_id属性若未手动指定默认通过uuid.uuid4()自动生成见BaseNode.id_的default_factoryschema.py#L275-L277。这个 ID 用途广泛更新存储中的节点以node_id为键定位并覆盖持久化节点定义节点间关系通过IndexNode引用其他节点或对象时使用作为检索与去重标识与hash一起参与文档存储的判重与索引。node_id的读写由属性node_id提供schema.py#L382-L388它直接映射到内部字段id_。官方文档给出的读写方式print(node.node_id) node.node_id My new node_id!注意node_id是属性接口而构造时传入的关键字参数名为id_如TextNode(text..., id_node_id)两者指向同一存储字段切勿混淆。节点类型体系不止于文本BaseNode之下LlamaIndex 还提供了面向不同模态与用途的具体节点类型均位于 schema.pyTextNodeL765纯文本节点get_type()返回ObjectType.TEXT是最常用、最基础的节点类型ImageNodeL852图片节点支持imagebase64、image_path、image_url、image_mimetype并提供resolve_image()供 PIL 读取IndexNodeL948带index_id与obj的引用节点可指向其他索引、查询引擎、检索器甚至其他节点这与relationships的部分能力重叠get_type()返回ObjectType.INDEXNodeL638多模态节点基类通过text_resource/image_resource/audio_resource/video_resource四个MediaResource字段承载任意模态内容get_type()返回ObjectType.MULTIMODALNodeWithScoreL1035检索结果包装将BaseNode与相关性分数score绑定检索器返回的正是此类对象。ObjectType枚举schema.py#L227-L232定义了TEXT、IMAGE、INDEX、DOCUMENT、MULTIMODAL五种对象类型RelatedNodeInfo.node_type即使用该枚举标识被关联节点的类型。实践建议优先使用 NodeParser 处理真实文档SentenceSplitter会在切分时自动计算字符位置、合并父文档元数据并建立PREVIOUS/NEXT关系这些手工实现既繁琐又易错善用元数据排除键当元数据中存在不宜参与 embedding 或不应暴露给 LLM 的键如内部 ID时使用excluded_embed_metadata_keys与excluded_llm_metadata_keys精确控制注入范围手动构造适用于小规模与定制场景如演示、测试或对块粒度有严格要求的场景可完全控制text、id_、relationships与metadata在检索结果中使用NodeWithScore理解score与node的封装关系便于在检索后处理环节统一访问节点内容与相关性分数。通过上述两种定义路径、五类关系枚举与node_id管理机制你可以精确掌控 LlamaIndex 中文档切块、关系建模与身份标识的每一个细节为后续的索引构建、检索与更新打下坚实基础。【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LlamaIndex 节点（Nodes）完全指南：定义、定制与关系管理
LlamaIndex 节点Nodes完全指南定义、定制与关系管理【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本文基于 LlamaIndex 官方文档《Defining and Customizing Nodes》展开系统讲解 Nodes 作为 LlamaIndex 一等公民first-class citizen的核心概念如何通过NodeParser将源 Document 解析为 Node 块如何手动构造TextNode并建立节点间关系NodeRelationship以及如何自定义node_id。读完本文你将掌握 LlamaIndex 中文档切块 → 节点构建 → 关系建模 → 身份管理的完整链路并理解底层实现原理。什么是 NodeLlamaIndex 的数据基本单元在 LlamaIndex 中Node节点表示源 Document 的块chunk它可以是一段文本、一张图片或其他更丰富的内容形式。除了内容本身Node 还携带两类关键信息元数据metadata描述该块来源、属性等的扁平字典关系信息relationships记录该节点与其他节点、索引结构之间的关联。这一设计体现在核心类BaseNode上定义于 llama_index/core/schema.py。从源码可以看到BaseNode除id_唯一 ID与embedding向量外还内置了metadata、relationships以及两个用于控制元数据注入行为的字段字段默认值作用metadata{}扁平化的元数据字典会注入 LLM 上下文与 embedding 文本并可用于向量库过滤excluded_embed_metadata_keys[]生成 embedding 时从文本中排除的元数据键excluded_llm_metadata_keys[]提供给 LLM 时从文本中排除的元数据键relationships{}NodeRelationship到关联节点信息的映射metadata_templateDEFAULT_METADATA_TMPL元数据格式化模板占位符为{key}与{value}metadata_separator\n元数据转字符串时字段间的分隔符在 LlamaIndex 中定义 Node 有两条路径一是通过NodeParser把源 Document解析成 Nodes二是完全手动构造 Node 对象并自行设定全部属性。两条路径分别对应下面两节。方式一通过 NodeParser 将 Document 解析为 Nodes当你有成批的Document需要切分成索引友好的块时最直接的方式是使用NodeParser系列类。官方文档给出的最小示例是使用句子级切分器SentenceSplitterfrom llama_index.core.node_parser import SentenceSplitter parser SentenceSplitter() nodes parser.get_nodes_from_documents(documents)解析链路的底层实现get_nodes_from_documents定义于 node_parser/interface.py其执行流程为建立doc_id - Document映射表触发CBEventType.NODE_PARSING回调事件调用抽象方法_parse_nodes完成实际切分同步版或_aparse_nodes异步版调用_postprocess_parsed_nodes做后处理为每个 Node 定位其在父文档中的start_char_idx/end_char_idx、合并父文档元数据、并在同一源文档的相邻节点间建立PREVIOUS/NEXT关系interface.py#L84-L155。后处理阶段的两个开关对应NodeParser基类字段interface.py#L50-L66include_metadataTrue是否把父 Document 的元数据合并进 Nodeinclude_prev_next_relTrue是否自动为同源相邻节点建立前后关系id_func生成节点 ID 的函数默认使用default_id_func。NodeParser本身继承自TransformComponent因此它也实现了__call__/acall同步/异步调用协议可以无缝嵌入 LlamaIndex 的 Transform 流水线interface.py#L203-L207。SentenceSplitter 的切分策略与参数SentenceSplitter的核心目标是尽可能保持完整句子与段落避免在 chunk 末尾出现悬挂的半句话。它定义于 node_parser/text/sentence.py常用参数如下参数默认值说明chunk_size1024DEFAULT_CHUNK_SIZE单位为 token每个 chunk 的目标 token 大小chunk_overlap200SENTENCE_CHUNK_OVERLAP相邻 chunk 之间的 token 重叠量需小于chunk_size否则抛出ValueErrorseparator 按词切分的默认分隔符paragraph_separator\n\n\n段落分隔符优先按段落切分secondary_chunking_regex[^,.;。][,.;。]?\|[,.;。]兜底的句子切分正则tokenizer自动获取自定义 token 计算函数include_metadataTrue切分时是否考虑元数据长度include_prev_next_relTrue是否自动写入前后节点关系id_funcdefault_id_func节点 ID 生成函数元数据感知切分是SentenceSplitter的一个重要特性在split_text_metadata_aware中它会先用 tokenizer 统计元数据长度再用effective_chunk_size chunk_size - metadata_len作为实际切分大小sentence.py#L156-L174。如果元数据长度超过chunk_size会直接抛出ValueError提示增大 chunk_size 或缩减元数据。递归切分顺序_split方法sentence.py#L198-L245按paragraph_separator切段落按句子 tokenizer默认 nltk 句子切分器切句子按secondary_chunking_regex切子句按默认分隔符separator切词最后按字符兜底。若某一段切分后仍超出chunk_size会递归继续细分若出现单个不可再分的超大 token如小 chunk_size 下的多 token CJK 字符则保留为超尺寸 split由_merge抛出明确的 Single token exceeded chunk size 错误而不是死循环。方式二手动构造 Node 与设置关系当你不依赖解析器、希望完全掌控节点结构时可以直接构造TextNode并手工装配关系。官方文档示例from llama_index.core.schema import TextNode, NodeRelationship, RelatedNodeInfo node1 TextNode(texttext_chunk, id_node_id) node2 TextNode(texttext_chunk, id_node_id) # set relationships node1.relationships[NodeRelationship.NEXT] RelatedNodeInfo( node_idnode2.node_id ) node2.relationships[NodeRelationship.PREVIOUS] RelatedNodeInfo( node_idnode1.node_id ) nodes [node1, node2]注意这里id_是构造参数对应BaseNode.id_字段而在属性访问层面使用node_id属性。TextNode定义于 schema.py#L765-L849核心字段包括text节点文本内容mimetype内容 MIME 类型默认text/plainstart_char_idx/end_char_idx节点在源文档中的起止字符位置由解析器后处理自动填充text_template文本与元数据拼接模板。同时TextNode实现了get_content(metadata_mode)、set_content()、hash基于text metadata的 SHA-256等BaseNode抽象接口。RelatedNodeInfo关系载荷与附加元数据RelatedNodeInfo是关系信息的具体载荷schema.py#L249-L260包含node_id被关联节点的 IDnode_type被关联节点的对象类型ObjectTypemetadata附加元数据字典默认{}hash被关联节点的哈希。因此关系不仅可以表达谁连谁还能附带说明性元数据。文档示例即为在 PARENT 关系上携带额外信息node2.relationships[NodeRelationship.PARENT] RelatedNodeInfo( node_idnode1.node_id, metadata{key: val} )NodeRelationship五类标准关系NodeRelationship是定义于 schema.py#L207-L224 的枚举目前包含五类关系枚举值语义值类型SOURCE该节点源自的源文档节点单个RelatedNodeInfoPREVIOUS同一文档中的前一个节点单个RelatedNodeInfoNEXT同一文档中的后一个节点单个RelatedNodeInfoPARENT父节点如层级结构中的上层块单个RelatedNodeInfoCHILD子节点列表List[RelatedNodeInfo]BaseNode为这些关系提供了便捷属性schema.py#L390-L448source_node、prev_node、next_node、parent_node、child_nodes。它们会从relationships字典中提取对应条目并在类型不符时如 SOURCE 被赋成列表抛出明确的ValueError。测试用例 tests/schema/test_base_node.py 逐一验证了这些属性的取值与类型约束行为。此外as_related_node_info()schema.py#L494-L501可将任意节点转换为RelatedNodeInfo携带node_id、node_type、metadata、hash便于快速把已有节点挂到某个关系上——这也是解析器自动建立PREVIOUS/NEXT关系的底层手段。自定义 node_id节点身份管理每个 Node 都有一个node_id属性若未手动指定默认通过uuid.uuid4()自动生成见BaseNode.id_的default_factoryschema.py#L275-L277。这个 ID 用途广泛更新存储中的节点以node_id为键定位并覆盖持久化节点定义节点间关系通过IndexNode引用其他节点或对象时使用作为检索与去重标识与hash一起参与文档存储的判重与索引。node_id的读写由属性node_id提供schema.py#L382-L388它直接映射到内部字段id_。官方文档给出的读写方式print(node.node_id) node.node_id My new node_id!注意node_id是属性接口而构造时传入的关键字参数名为id_如TextNode(text..., id_node_id)两者指向同一存储字段切勿混淆。节点类型体系不止于文本BaseNode之下LlamaIndex 还提供了面向不同模态与用途的具体节点类型均位于 schema.pyTextNodeL765纯文本节点get_type()返回ObjectType.TEXT是最常用、最基础的节点类型ImageNodeL852图片节点支持imagebase64、image_path、image_url、image_mimetype并提供resolve_image()供 PIL 读取IndexNodeL948带index_id与obj的引用节点可指向其他索引、查询引擎、检索器甚至其他节点这与relationships的部分能力重叠get_type()返回ObjectType.INDEXNodeL638多模态节点基类通过text_resource/image_resource/audio_resource/video_resource四个MediaResource字段承载任意模态内容get_type()返回ObjectType.MULTIMODALNodeWithScoreL1035检索结果包装将BaseNode与相关性分数score绑定检索器返回的正是此类对象。ObjectType枚举schema.py#L227-L232定义了TEXT、IMAGE、INDEX、DOCUMENT、MULTIMODAL五种对象类型RelatedNodeInfo.node_type即使用该枚举标识被关联节点的类型。实践建议优先使用 NodeParser 处理真实文档SentenceSplitter会在切分时自动计算字符位置、合并父文档元数据并建立PREVIOUS/NEXT关系这些手工实现既繁琐又易错善用元数据排除键当元数据中存在不宜参与 embedding 或不应暴露给 LLM 的键如内部 ID时使用excluded_embed_metadata_keys与excluded_llm_metadata_keys精确控制注入范围手动构造适用于小规模与定制场景如演示、测试或对块粒度有严格要求的场景可完全控制text、id_、relationships与metadata在检索结果中使用NodeWithScore理解score与node的封装关系便于在检索后处理环节统一访问节点内容与相关性分数。通过上述两种定义路径、五类关系枚举与node_id管理机制你可以精确掌控 LlamaIndex 中文档切块、关系建模与身份标识的每一个细节为后续的索引构建、检索与更新打下坚实基础。【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考