分割器概述
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 内容拆分为可管理的块，同时保留重要元素（如表格、列表和其他 HTML 组件）的语义结构。这确保了此类元素不会跨块拆分，从而导致上下文相关性（如表头、列表标题等）的丢失。
该分割器的核心设计是创建上下文相关的块。使用 HTMLHeaderTextSplitter 进行常规递归拆分可能会导致表格、列表和其他结构化元素在中间被拆分，从而丢失重要上下文并创建不良块。
HTMLSemanticPreservingSplitter 对于拆分包含结构化元素（如表格和列表）的 HTML 内容至关重要，尤其是在需要完整保留这些元素时。此外，它能够为特定 HTML 标签定义自定义处理程序，使其成为处理复杂 HTML 文档的多功能工具。
重要提示：max_chunk_size 不是块的绝对最大大小，最大大小的计算发生在保留内容不属于块时，以确保它不会被拆分。当我们将保留的数据添加回块时，块大小有可能超过 max_chunk_size。这对于确保我们维护原始文档的结构至关重要。
注意：
- 我们定义了一个自定义处理程序来重新格式化代码块的内容
- 我们为特定 HTML 元素定义了一个拒绝列表，以在预处理中分解它们及其内容
- 我们故意设置了一个小的块大小来演示元素的非拆分
保留表格和列表
在此示例中，我们将演示HTMLSemanticPreservingSplitter 如何保留 HTML 文档中的表格和大列表。块大小将设置为 50 个字符，以说明分割器如何确保这些元素不会被拆分，即使它们超过了定义的最大块大小。
解释
在此示例中，HTMLSemanticPreservingSplitter 确保整个表格和无序列表（<ul>）保留在它们各自的块中。即使块大小设置为 50 个字符，分割器也会识别这些元素不应被拆分并保持它们完整。
这在处理数据表或列表时尤为重要，因为拆分内容可能导致上下文丢失或混淆。生成的 Document 对象保留了这些元素的完整结构，确保信息的上下文相关性得以保持。
使用自定义处理程序
HTMLSemanticPreservingSplitter 允许您为特定 HTML 元素定义自定义处理程序。某些平台具有自定义 HTML 标签，这些标签不是 BeautifulSoup 原生解析的，当这种情况发生时，您可以利用自定义处理程序轻松添加格式化逻辑。
这对于需要特殊处理的元素（如 <iframe> 标签或特定的 ‘data-’ 元素）特别有用。在此示例中，我们将为 iframe 标签创建一个自定义处理程序，将其转换为类似 Markdown 的链接。
解释
在此示例中，我们为iframe 标签定义了一个自定义处理程序，将其转换为类似 Markdown 的链接。当分割器处理 HTML 内容时，它使用此自定义处理程序来转换 iframe 标签，同时保留其他元素（如表格和列表）。生成的 Document 对象显示了 iframe 如何根据您提供的自定义逻辑进行处理。
重要提示：当保留链接等项目时，应注意不要在分隔符中包含 .，或将分隔符留空。RecursiveCharacterTextSplitter 会在句点处拆分，这将把链接切成两半。确保您提供一个包含 . 的分隔符列表。
使用自定义处理程序通过 LLM 分析图像
使用自定义处理程序，我们还可以覆盖任何元素的默认处理。一个很好的例子是在分块流程中直接插入文档中图像的语义分析。 由于我们的函数在发现标签时被调用，我们可以覆盖<img> 标签并关闭 preserve_images 以插入我们希望嵌入到块中的任何内容。
解释：
通过我们编写的自定义处理程序从 HTML 中的<img> 元素提取特定字段，我们可以使用代理进一步处理数据，并将结果直接插入到我们的块中。重要的是确保 preserve_images 设置为 False，否则将发生 <img> 字段的默认处理。
通过 MCP 将这些文档连接到 Claude、VSCode 等 以获取实时答案。