AutoGPT 平台 Firecrawl Extract 块：用 AI 从网页中抽取结构化数据

Firecrawl Extract 是 AutoGPT Platform（autogpt_platform）中用于"网页结构化信息抽取"的搜索类积木块（Block）：只需给出一个或多个 URL、一句自然语言描述或一个 JSON Schema，它就能让 Firecrawl 的 AI 抽取引擎爬取页面并返回结构化数据。读完本文你将掌握该积木块的完整输入输出契约、源码级工作原理、通配符 URL 与 web search 的用法，以及它与 Crawl / Scrape / Map / Search 姊妹块的差异，可直接落地到商品信息采集、联系人抓取与数据管道等场景。

原始关联文档：docs/integrations/block-integrations/firecrawl/extract.md。在 AutoGPT Platform 中，这类文档是随积木块一起发布的手册（通过 <!-- MANUAL: ... --> 标记由仓库维护），正文与 积木块源码 一一对应。

这是什么：一个"绕过反爬 + AI 抽取"的块

Firecrawl 本身是一个网站抓取与数据抽取服务，主打"bypassing blockers"——即能够爬取网站并绕过常见的反爬拦截。AutoGPT 平台的 Firecrawl Extract 块将其 extract API 封装成平台积木块：你不需要自己写爬虫和解析 HTML，只要描述"想要什么数据"，AI 就能从目标页面中抽取并返回。

从源码看，块在平台注册信息如下（extract.py）：

• 类名：FirecrawlExtractBlock
• Block ID：d1774756-4d9e-40e6-bab1-47ec0ccd81b2
• 所属分类：BlockCategory.SEARCH（搜索类）
• 依赖：Python 官方 SDK firecrawl，通过 FirecrawlApp(api_key=...) 调用

工作原理：prompt 驱动还是 schema 驱动

Firecrawl 的 AI 抽取本质上是一个"先爬取、再用大模型按你的要求整理字段"的过程。块的运行逻辑集中在 run() 方法（extract.py L55-L83）：

app = FirecrawlApp(api_key=credentials.api_key.get_secret_value())
extract_result = app.extract(
    urls=input_data.urls,
    prompt=input_data.prompt,
    schema=input_data.output_schema,
    enable_web_search=input_data.enable_web_search,
)

两种抽取方式，按需二选一

方式	适用场景	说明
自然语言 prompt（prompt）	灵活抽取，不关心字段是否固定	直接描述要抽什么，如"提取每个产品的名称、价格与评分"
JSON Schema（output_schema）	需要严格、可落库的结构	用 Dict[str, Any] 传入 JSON Schema，输出即按该结构收敛

两者都非必填，但至少要提供其一，否则 AI 没有抽取目标。若同时给出，app.extract() 会同时把两者传给 Firecrawl 服务，由远端结合两者约束输出。

通配符 URL：一次抽多页

urls 字段支持通配符 /*。例如电商站点商品列表的多个详情页若符合同一路径模式，可以用一个模式覆盖多页，配合 AI 抽取即可批量产出同构数据。文档原话是 "Wildcards in URLs allow extracting data from multiple pages matching a pattern."

enable_web_search：能否跳出当前域

默认 False（源码 SchemaField 中的默认值），此时抽取只限定在给定 URL 域内；当置为 True 时，抽取过程中可以顺着链接跳到指定域名之外——适合"主页面信息不完整、需要从外链补全信息"的场景。

输入与输出：完整的契约表

原文档给出了块的 I/O 契约，逐项整理并补充默认值后如下。

Inputs（输入）

Input	描述	类型	必填	默认值（源码佐证）
urls	要爬取的 URL 列表，至少一个；支持通配符（/*）	List[str]	是	无
prompt	用于抽取的自然语言提示	str	否	None
output_schema	描述输出结构的 JSON Schema（需要更刚性结构时用）	Dict[str, Any]	否	None
enable_web_search	为 true 时抽取可跟随链接离开指定域	bool	否	False

补充：每个积木块在界面上都会附带一个 credentials（凭据） 输入，用于选择你在平台中已配置的 Firecrawl API Key（见下文"接入前置条件"）。它不属于业务输入，但却是运行所必需的，这一点在 Input 定义 L23 可见。

Outputs（输出）

Output	描述	类型
data	抽取/爬取的结果	Dict[str, Any]
error	抽取失败时的错误消息	str

实现细节：成功时块通过 yield "data", extract_result.data 产出结构化结果；失败时则抛出 BlockExecutionError（消息为 Extract failed: {e}），并附带块名与块 ID，方便在平台执行日志中定位（extract.py L67-L72）。

接入前置条件：Firecrawl API Key 与计费

块通过平台"凭据"体系拿 API Key，密钥经 get_secret_value() 解密后构造 FirecrawlApp。Provider 的定义位于 backend/blocks/firecrawl/_config.py：

• 环境变量 / 配置项：FIRECRAWL_API_KEY（"Firecrawl API Key"）
• Provider 名：firecrawl
• 基础成本：with_base_cost(1000, BlockCostType.COST_USD)，即按 1000 平台积分 = 1 美元的先验基准计价

计费细节很有意思——源码注释给出了一个精确换算关系（extract.py L74-L82）：

Firecrawl 的 extract 响应会返回 credits_used 字段；1 Firecrawl credit ≈ $0.001。平台按 1000 platform credits / USD 换算，所以 1 个 Firecrawl credit ≈ 1 个平台积分，与该块"单页抓取"的计费档次大致吻合。

运行成功后，块会把 provider_cost = credits_used * 0.001（USD）写入 NodeExecutionStats，供平台后续做计费对账（merge_stats(...)）。也就是说：真实费用不是拍脑袋，而是取自 Firecrawl 响应中的 credits_used，精度按 1 credit ≈ $0.001 折算。

在 Agent 或数据管道中怎么编排

典型使用场景（原文档示例）

1. 电商商品数据抽取（Product Data Extraction）：从电商站点抽取结构化商品信息（价格、规格、评论），喂给比价、选品或推荐系统。
2. 企业联系人抓取（Contact Scraping）：把公司官网上的商务联系信息（电话、邮箱、地址）批量抽成统一结构。
3. 数据管道输入（Data Pipeline Input）：把网页数据自动结构化后，作为分析与入库的输入源——这正好是积木块之于 AutoGPT 平台的意义：Web 内容由此变成下游 LLM、数据库或存储块可以直接消费的 JSON。

与同目录姊妹块如何分工

Firecrawl 在 AutoGPT 中不只一个块，它们同处 backend/blocks/firecrawl/，文档也集中在 docs/integrations/block-integrations/firecrawl/。选块时可参考这张对照表：

块	文档	擅长
Extract	extract.md	用 AI 按 prompt / JSON Schema 抽取多页结构化数据（本文主角）
Crawl	crawl.md	递归爬取整站/大批页面
Scrape	scrape.md	单页抓取，关注返回格式
Map	map.md	发现站点 URL 结构（sitemap）
Search	search.md	基于搜索而非给定 URL 的信息获取

简单经验法则：已经有明确 URL 且要"理解+整理"页面内容 → Extract；只要给定 URL 的原始/格式化内容 → Scrape；需要自动发现并遍历站点 → Map + Crawl；没有 URL 只有关键词 → Search。

从源码结构还能读出的注意事项

• 错误输出与异常：Output.error 在 schema 中默认值为空字符串（L41-L44），而 run() 在异常时直接抛 BlockExecutionError 而非 yield "error"。因此下游判断失败应依赖块的错误通道/执行状态，而非检查 data 是否为空。
• SDK 版本与格式体系：/firecrawl 目录内还有 _format_utils.py，负责把平台的 ScrapeFormat 枚举转换成 Firecrawl FormatOption（含 screenshot@fullPage 这类特殊值）——说明整个 Firecrawl 集成是围绕平台统一 SDK 封装层设计的，Extract 只是其中之一。
• 凭据管理：各 Firecrawl 块共用同一个 ProviderBuilder("firecrawl")，所以在平台里配一次 API Key 即可供五个块复用。

小结

Firecrawl Extract 把"爬虫 + 反爬绕过 + LLM 字段抽取"压缩成了一个搜索类积木块：urls 决定抓哪里，prompt / output_schema 决定抽什么、长什么样，enable_web_search 决定能不能跨域找补充信息。配合 AutoGPT Platform 的凭据与计费体系，它能把电商商品信息、企业联系人或任意网页内容变成可直接入库、直接喂给下游块的结构化数据，是搭建"网页 → 数据"管道的低成本起点。如果你需要了解整组 Firecrawl 块的能力边界，可以从 crawl.md、scrape.md、map.md、search.md 继续深入。