MarkItDown 网络爬虫：将页面转换为适合大型语言模型的 Markdown

TL;DR:

• MarkItDown将抓取的HTML页面转换为Markdown，保留了语言模型易于读取的标题、链接和列表。
• 抓取会在内存中获取HTML，因此指南使用convert_stream与BytesIO以及显式的.html扩展名，而不是文件路径。
• MarkItDown没有清除块内容的获取层，因此Scrapeless获取页面，MarkItDown进行转换。
• 在示例页面中，11,021个字符的HTML变成了2,973个字符的Markdown，并以一个真正的标题开头。
• MarkItDown将整个文档转换为结构化的Markdown；当你只想要去掉模板的主要文章时，请选择trafilatura。
• 通过Scrapeless免费计划开始并转换你的第一页。

语言模型比原始HTML更好地读取Markdown。Markdown保持了模型需要的结构，标题、列表和链接，而没有填满HTML页面的标签噪音、脚本块和内联样式。MarkItDown，微软的文档到Markdown转换器，执行这种转换，并通过一个接口处理HTML、PDF、Office文档等。它不执行获取页面的功能，这一环节是抓取工作流程必须提供的一半。

本指南将两者结合起来。Scrapeless Universal Scraping API获取页面，MarkItDown将返回的HTML转换为Markdown。以下每个数字都来自对公共页面的真实运行。

MarkItDown的功能

MarkItDown接受一个文档并返回Markdown。其存在的理由是LLM输入：它生成的文本以令牌高效的形式保持结构，遵循其发出的Markdown的广泛实施的CommonMark规范。MarkItDown仓库列出了它接受的输入格式，包括HTML、PDF、Word、PowerPoint和图像。

MarkItDown不是一个抓取工具。它没有浏览器，也没有办法绕过访问挑战，因此它转换你提供的任何字节。从一个实时的，有时受到保护的页面获取这些字节是一个单独的工作。

安装

MarkItDown是一个简单的pip安装。

pip install markitdown

在终端中设置你的Scrapeless密钥。在运行时使用真实密钥，并将占位符保留在源代码外。

export SCRAPELESS_API_KEY="sk_your_key_here"

将抓取的HTML转换为Markdown

抓取返回一个HTML字符串，而不是文件，因此正确的入口点是convert_stream。将HTML包装在BytesIO中，并传递file_extension=".html"，以便MarkItDown将其解析为HTML。转换后的Markdown在结果的text_content中。

import io
import json
import os
import urllib.request

from markitdown import MarkItDown

API_URL = "https://api.scrapeless.com/api/v2/unlocker/request"
TARGET = "https://quotes.toscrape.com/"


def fetch_html(url: str) -> str:
    payload = json.dumps(
        {"actor": "unlocker.webunlocker", "input": {"url": url, "js_render": False, "headless": False}}
    ).encode()
    request = urllib.request.Request(
        API_URL,
        data=payload,
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"], "Content-Type": "application/json"},
        method="POST",
    )
    with urllib.request.urlopen(request, timeout=90) as response:
        return json.loads(response.read())["data"]


html = fetch_html(TARGET)
result = MarkItDown().convert_stream(io.BytesIO(html.encode("utf-8")), file_extension=".html")
markdown = result.text_content

print(f"原始HTML字符数: {len(html)}")
print(f"Markdown字符数: {len(markdown)}")
print(f"是否以标题开头: {markdown.lstrip().startswith('#')}")
print("--- Markdown的前几行 ---")
for line in [line for line in markdown.splitlines() if line.strip()][:4]:
    print(line)

运行报告大小并打印Markdown的顶部。

原始HTML字符数: 11021
Markdown字符数: 2973
是否以标题开头: True
--- Markdown的前几行 ---
# [Quotes to Scrape](/)
[Login](/login)
“The world as we have created it is a process of our thinking. It cannot be changed without changing our thinking.”
by Albert Einstein

输出以一个真正的Markdown标题和一个链接开头，页面的第一个引用紧随其后。模型可以使用的结构在转换中保留，11,021个字符的HTML减少到2,973个字符的Markdown。

为什么为LLM选择Markdown

Markdown 是大多数语言模型训练的读取格式，因此标题变为章节，链接保持可读，列表保持为列表，所有这些都比原始 HTML 使用更少的标记。直接传递原始 HTML 则会消耗标记来处理标签和内联样式，模型必须忽略这些内容，从而埋没了帮助模型组织内容的结构。此时先转换为 Markdown 是一个便宜的步骤，在每个下游调用中都能获得回报。

MarkItDown 的局限

MarkItDown 可以转换；但它不支持跨块检索，这就是为什么本指南将其与检索工具配对的原因。将受保护页面的 HTML 交给 MarkItDown，它会忠实地将挑战页面转换为 Markdown。Scrapeless 返回真实渲染的 HTML，MarkItDown 对此进行转换。当目标用 JavaScript 构建内容时，在请求中将 js_render 设置为 True，以便 HTML 已包含内容；当标记是服务器渲染时，将其保持为 False，正如这里所示。

MarkItDown 和 trafilatura 解决不同的问题。MarkItDown 将整个文档转换为结构化的 Markdown，保持页面的形状。Trafilatura 则提取主要文章并忽略模板内容。当您希望页面作为 Markdown 时，请使用 MarkItDown；当您只希望获得文章主体时，请使用 trafilatura。

在跨站点运行此操作之前，请阅读其 robots.txt 和条款。机器人排除协议 规定了网站请求自动化客户端避免的路径，遵守此协议可以保持转换管道的可持续性。有关更广泛的模式，本指南提供有关 AI 内容管道 的说明，其中显示了此类转换步骤的适用位置。

准备好转换您自己的页面了吗？ 创建一个免费 Scrapeless 账户，并更改目标 URL。

结论

将 Markdown 传递给模型而不是 HTML 是一个小改变，但却能带来真实的收益，它需要两个工具：Scrapeless 用于检索页面，MarkItDown 用于转换。一次 convert_stream 调用将 11,021 个字符的 HTML 转换为 2,973 个字符的结构化 Markdown，随时准备进行嵌入步骤或提示。从上面的脚本开始，指向您自己的 URL，并将 Markdown 传递给您的模型。

从 Scrapeless 免费计划开始 以检索您自己的页面，并在您评估定期工作时查看 Scrapeless 定价。

常见问题

问：MarkItDown 自己能抓取网页吗？

不能。MarkItDown 仅转换您提供的文档，并没有浏览器或解锁功能，因此在受保护的页面上，它将转换一个挑战页面而不是内容。将其与返回渲染 HTML 的检索工具（例如 Scrapeless）配对，然后转换该 HTML。

问：我该如何在不保存文件的情况下将抓取的 HTML 传递给 MarkItDown？

使用 convert_stream，将 HTML 包裹在 io.BytesIO 中，并设置 file_extension=".html"，这样 MarkItDown 将内存中的字节解析为 HTML。这可以避免将抓取的页面写入磁盘再读取，Markdown 将在结果的 text_content 中。

问：MarkItDown 能转换哪些格式？

MarkItDown 接受 HTML、PDF、Word、PowerPoint、Excel、图像以及其他几种格式，并通过相同的接口将每种格式转换为 Markdown。对于网页抓取，相关输入是 HTML，但如果您的管道也收集这些内容，同样的转换器可以处理抓取的 PDF 或电子表格。

问：我应该使用 MarkItDown 还是 trafilatura？

当您希望将整个文档转换为结构化 Markdown 时使用 MarkItDown，当您只希望获取去除导航和页脚的主要文章时使用 trafilatura。它们解决不同的问题：一个是格式转换器，另一个是主要内容提取器。

问：为什么在调用模型之前要转换为 Markdown？

Markdown 保持标题、列表和链接的紧凑形式，语言模型能够很好地读取，而原始 HTML 则在标签和样式上消耗标记，模型必须忽略这些内容。首先进行转换可以降低标记成本，并为模型提供更清晰的结构。