分割器概述
HTMLHeaderTextSplitter
当您希望根据文档标题保留文档的层次结构时非常有用。
<h1>、<h2>、<h3> 等）分割 HTML 文本，并为与给定块相关的每个标题添加元数据。
功能：
- 在 HTML 元素级别分割文本。
- 保留文档结构中编码的上下文丰富信息。
- 可逐元素返回块，也可合并具有相同元数据的元素。
HTMLSectionSplitter
当您希望将 HTML 文档分割为更大的节（如
<section>、<div> 或自定义节）时非常有用。- 使用 XSLT 变换来检测和分割节。
- 内部对大型节使用
RecursiveCharacterTextSplitter。 - 考虑字体大小来确定节。
HTMLSemanticPreservingSplitter
当您需要确保结构化元素不跨块分割、保留上下文相关性时最为理想。
- 保留表格、列表和其他指定的 HTML 元素。
- 允许为特定 HTML 标签自定义处理器。
- 确保文档的语义含义得以维护。
- 内置规范化与停用词移除
选择合适的分割器
- 使用
HTMLHeaderTextSplitter的场景：需要根据标题层次分割 HTML 文档，并维护关于标题的元数据。 - 使用
HTMLSectionSplitter的场景：需要将文档分割为更大、更通用的节，可能基于自定义标签或字体大小。 - 使用
HTMLSemanticPreservingSplitter的场景：需要在保留表格和列表等语义元素的同时分割文档，确保它们不被分割且上下文得以维护。
| 功能 | HTMLHeaderTextSplitter | HTMLSectionSplitter | HTMLSemanticPreservingSplitter |
|---|---|---|---|
| 基于标题分割 | 是 | 是 | 是 |
| 保留语义元素（表格、列表） | 否 | 否 | 是 |
| 为标题添加元数据 | 是 | 是 | 是 |
| HTML 标签自定义处理器 | 否 | 否 | 是 |
| 保留媒体（图片、视频） | 否 | 否 | 是 |
| 考虑字体大小 | 否 | 是 | 否 |
| 使用 XSLT 变换 | 否 | 是 | 否 |
HTML 文档示例
我们使用以下 HTML 文档作为示例：使用 HTMLHeaderTextSplitter
HTMLHeaderTextSplitter 是一个”结构感知”文本分割器，它在 HTML 元素级别分割文本，并为与任何给定块”相关”的每个标题添加元数据。它可以逐元素返回块，也可以合并具有相同元数据的元素，目标是 (a) 语义上（或多或少）将相关文本分组，(b) 保留文档结构中编码的上下文丰富信息。它可以作为分块管道的一部分与其他文本分割器配合使用。 它类似于 Markdown 文件的 MarkdownHeaderTextSplitter。 要指定分割的标题，请在实例化HTMLHeaderTextSplitter 时指定 headers_to_split_on，如下所示。
HTMLHeaderTextSplitter 时指定 return_each_element=True：
Document 返回：
如何从 URL 或 HTML 文件中分割：
要直接从 URL 读取，请将 URL 字符串传入split_text_from_url 方法。
同样，本地 HTML 文件可以传入 split_text_from_file 方法。
如何限制块大小：
HTMLHeaderTextSplitter（基于 HTML 标题分割）可以与另一个基于字符长度限制分割的分割器（如 RecursiveCharacterTextSplitter）组合使用。
这可以使用第二个分割器的 .split_documents 方法实现：
局限性
HTML 文档之间可能存在相当大的结构差异，尽管HTMLHeaderTextSplitter 会尝试将所有”相关”标题附加到给定块，但有时可能会遗漏某些标题。例如，该算法假设信息层次结构中标题始终位于相关文本”上方”的节点，即先前的兄弟节点、祖先节点及其组合。在以下新闻文章中（截至本文撰写时），文档的结构使得顶级标题文本虽然标记为”h1”，但位于与我们期望其”上方”的文本元素不同的子树中—因此我们可以观察到”h1”元素及其关联文本不会出现在块元数据中（但在适用情况下，我们确实会看到”h2”及其关联文本）：
使用 HTMLSectionSplitter
与 HTMLHeaderTextSplitter 概念相似，HTMLSectionSplitter 是一个”结构感知”文本分割器，它在元素级别分割文本，并为与任何给定块”相关”的每个标题添加元数据。它允许您按节分割 HTML。
它可以逐元素返回块，也可以合并具有相同元数据的元素，目标是 (a) 语义上（或多或少）将相关文本分组，(b) 保留文档结构中编码的上下文丰富信息。
使用 xslt_path 提供转换 HTML 的绝对路径，以便根据提供的标签检测节。默认使用 data_connection/document_transformers 目录中的 converting_to_header.xslt 文件。这用于将 HTML 转换为更易于检测节的格式/布局。例如，根据字体大小的 span 可以转换为标题标签以被检测为节。
如何分割 HTML 字符串：
如何限制块大小：
HTMLSectionSplitter 可以作为分块管道的一部分与其他文本分割器配合使用。当节的大小超过块大小时，内部使用 RecursiveCharacterTextSplitter。它还会考虑文本的字体大小，根据确定的字体大小阈值来判断是否构成一个节。
使用 HTMLSemanticPreservingSplitter
HTMLSemanticPreservingSplitter 旨在将 HTML 内容分割为可管理的块，同时保留表格、列表等重要元素的语义结构。这确保了这些元素不会跨块分割，从而避免丢失表头、列表头等上下文相关性。
该分割器的核心设计目标是创建具有上下文相关性的块。使用 HTMLHeaderTextSplitter 进行通用递归分割可能导致表格、列表和其他结构化元素在中间被分割，丢失重要上下文并产生质量差的块。
HTMLSemanticPreservingSplitter 对于分割包含表格和列表等结构化元素的 HTML 内容至关重要，尤其是在必须完整保留这些元素时。此外，它为特定 HTML 标签定义自定义处理器的能力使其成为处理复杂 HTML 文档的多功能工具。
重要提示：max_chunk_size 不是块的绝对最大大小。最大大小的计算发生在保留内容不属于块的时候，以确保其不被分割。当我们将保留的数据添加回块中时，块大小可能超过 max_chunk_size。这对于确保维护原始文档结构至关重要。
注意事项：
- 我们定义了一个自定义处理器来重新格式化代码块的内容
- 我们为特定 HTML 元素定义了拒绝列表，以在预处理时分解它们及其内容
- 我们特意设置了较小的块大小来演示元素不被分割的效果
保留表格和列表
在此示例中，我们将演示HTMLSemanticPreservingSplitter 如何在 HTML 文档中保留表格和大型列表。块大小将设置为 50 个字符，以说明分割器如何确保这些元素不被分割，即使它们超过了定义的最大块大小。
说明
在此示例中，HTMLSemanticPreservingSplitter 确保整个表格和无序列表（<ul>）在各自的块中得以保留。即使块大小设置为 50 个字符，分割器也能识别这些元素不应被分割并保持其完整性。
在处理数据表或列表时，这一点尤为重要，因为分割内容可能导致上下文丢失或产生混乱。生成的 Document 对象保留了这些元素的完整结构，确保信息的上下文相关性得以维护。
使用自定义处理器
HTMLSemanticPreservingSplitter 允许您为特定 HTML 元素定义自定义处理器。某些平台具有 BeautifulSoup 无法原生解析的自定义 HTML 标签，在这种情况下，您可以利用自定义处理器轻松添加格式化逻辑。
这对于需要特殊处理的元素（如 <iframe> 标签或特定的 data- 元素）特别有用。在此示例中，我们将为 iframe 标签创建一个将其转换为类似 Markdown 链接的自定义处理器。
说明
在此示例中，我们为iframe 标签定义了一个将其转换为类似 Markdown 链接的自定义处理器。当分割器处理 HTML 内容时，它使用此自定义处理器转换 iframe 标签，同时保留表格和列表等其他元素。生成的 Document 对象展示了 iframe 如何按照您提供的自定义逻辑进行处理。
重要提示：保留链接等内容时，请注意不要在分隔符中包含 .，也不要将分隔符留空。RecursiveCharacterTextSplitter 会在句号处分割，这将切断链接。请确保提供包含 . （后面有空格）的分隔符列表。
使用自定义处理器通过 LLM 分析图像
通过自定义处理器，我们还可以覆盖任何元素的默认处理逻辑。一个很好的例子是直接在分块流程中插入文档中图像的语义分析。 由于我们的函数在发现标签时被调用，我们可以覆盖<img> 标签并关闭 preserve_images，以插入我们希望嵌入块中的任何内容。
说明：
通过编写自定义处理器从 HTML 中的<img> 元素提取特定字段，我们可以使用智能体进一步处理数据，并将结果直接插入块中。重要的是确保 preserve_images 设置为 False，否则将使用 <img> 字段的默认处理逻辑。
连接这些文档 到 Claude、VSCode 等，通过 MCP 获取实时答案。