HTML 转 Markdown

简而言之:HTML 转 Markdown 会去除表现层标记,同时保留文档结构。它通常可将页面大小缩减 90% 以上,因此已成为向语言模型输入网页内容的标准格式。

HTML 转 Markdown会将网页改写为轻量级文本格式,保留标题、列表、链接和强调内容,同时舍弃样式、脚本及布局容器。这种做法多年来一直用于简化文档处理。随着语言模型让 Token 数量成为一项直接成本,它也由此成为基础设施。

为什么转换对 LLM 很重要:

  1. Token 经济性:标记会消耗不承载任何含义的 Token。类名、内联样式和嵌套容器在提示词中完全是额外开销。
  2. 上下文限制:以 HTML 格式呈现时超出模型上下文窗口的页面,转换为 Markdown 后通常可以轻松容纳。
  3. 信号清晰度:当内容未被属性和嵌套结构掩埋时,模型能更可靠地关注内容。
  4. 保留结构:与纯文本提取不同,Markdown 会保留标题层级和列表分组,而这些结构具有实际含义。

缩减幅度非常可观。一个通常包含 180 KB HTML 的文章页面,转换后大约只有 8 至 12 KB 的 Markdown。大规模应用时,这一差异将决定检索管道的成本是否可承受。

可顺利映射的内容:

HTML 元素 Markdown 输出
1 至 6 级标题 一至六个井号
段落 以空行分隔的文本
加重和粗体 双星号
强调和斜体 单星号
无序列表 以连字符开头的行
有序列表 带编号的行
锚点 方括号中的文本及圆括号中的 URL
图像 感叹号、替代文本和 URL
行内代码 单反引号
预格式化块 三反引号围栏
块引用 大于号前缀

转换效果不佳的内容:

复杂表格。Markdown 表格无法表示合并单元格、嵌套表格或多行表头。转换工具要么将结构扁平化并丢失关联关系,要么输出原始标记,违背转换的初衷。

表单和交互式元素。输入框、选择框和按钮在 Markdown 中没有对应形式,通常会被丢弃。如果页面的价值在于表单,转换就会破坏这些内容。

承载含义的布局。多列对比和并排面板会变成顺序排列的文本,使其易于理解的视觉关系也会随之消失。

自定义组件。选项卡、手风琴式组件和模态框会被扁平化成无法区分的内容,往往还会显示原渲染页面中隐藏的文本。

实际转换:

import httpx
from markdownify import markdownify
from readability import Document

def page_to_markdown(url):
    html = httpx.get(url, timeout=20).text

    # Isolate main content before converting
    article = Document(html).summary()

    return markdownify(
        article,
        heading_style="ATX",
        strip=["script", "style", "nav", "footer", "form"]
    )

内容隔离步骤是区分可用结果和低质量结果的关键。转换整个页面会生成包含完整导航菜单、Cookie 横幅和页脚站点地图的 Markdown。先通过样板内容去除提取主要内容,可以生成体积更小且更实用的输出。

转换顺序:

操作顺序对输出质量的影响,比选择哪种转换库更大。

  1. 按需渲染:如果内容由客户端生成,请应用 JavaScript 渲染,因为转换空壳页面只会得到空文档。
  2. 去除样板内容:移除导航、页脚、广告和相关内容面板。
  3. 解析 URL:将相对链接转换为绝对链接,否则输出中的所有链接一旦脱离原页面上下文都会失效。
  4. 转换:将清理后的片段转换为 Markdown。
  5. 后处理:合并重复的空行并清除残留内容。

Markdown 与检索管道:

Markdown 已成为检索增强生成中的默认中间格式,除了体积更小之外,还有一个实际原因。它的标题结构为文档分块提供了自然边界,因此可以在章节边界处拆分文档,而不是按任意字符数进行切分。与标题对齐的分块能够保留连贯的含义,从而显著提高检索质量。

Bright Data 的爬虫 API和搜索与提取可直接返回 Markdown,并且已经去除样板内容并解析链接,从而完全省去管道中的转换和清理阶段。

准备好开始了吗?