分割器概述
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 文档到另一个 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 内容分割成可管理的块，同时保留重要元素（如表格、列表和其他 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> 字段的默认处理。
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.