# 选择数据提取工具 (/zh/developer-guides/usage-guides/choosing-the-data-extractor)

<!-- agent-signals: reading_time_min: 7 · est_tokens: 3766 · updated: 2026-07-30 -->
Related: [全栈模板](/zh/developer-guides/examples.md), [OpenAI](/zh/developer-guides/llm-sdks-and-frameworks/openai.md)

Firecrawl 提供三种从网页提取结构化数据的方式。它们分别适用于不同的使用场景，在自动化程度和可控性上各不相同。

<div id="quick-comparison">
  ## 快速对比 [#快速对比]
</div>

| 功能              | `/agent`            | `/extract`                   | `/scrape` (JSON 模式)                |
| --------------- | ------------------- | ---------------------------- | ---------------------------------- |
| **状态**          | 已启用                 | 请改用 `/agent`                 | 已启用                                |
| **是否需要 URL**    | 否 (可选)              | 是 (支持通配符)                    | 是 (单一 URL)                         |
| **范围**          | 全网范围发现              | 多页面/多域名                      | 单页面                                |
| **URL 发现**      | 自动进行全网搜索            | 从给定 URL 进行爬取                 | 无                                  |
| **处理方式**        | 异步                  | 异步                           | 同步                                 |
| **是否需要 Schema** | 否 (prompt 或 schema) | 否 (prompt 或 schema)          | 否 (prompt 或 schema)                |
| **计费**          | 动态计费 (每天 5 次免费运行)   | 基于 token (1 额度 = 15 个 token) | 5 额度/页 (1 额度基础费用 + JSON 模式额外 4 额度) |
| **最适合**         | 调研、发现、复杂信息收集        | 多页面抽取 (在已知 URL 的情况下)         | 已知单页面抽取                            |

<div id="1-agent-endpoint">
  ## 1. `/agent` 端点 [#1-agent-端点]
</div>

`/agent` 端点是 Firecrawl 最先进的功能，是 `/extract` 的后继者。它使用 AI 代理自主在全网进行搜索、导航和数据采集。

<div id="key-characteristics">
  ### 关键特性 [#关键特性]
</div>

* **URL 可选**：只需通过 `prompt` 描述你的需求；URL 完全可选
* **自主导航**：代理会自动搜索并深入浏览站点来找到你的数据
* **深度网页搜索**：自主在多个域名和页面间发现所需信息
* **并行处理**：同时处理多个数据源以提升返回速度
* **可用模型**：`spark-1-mini` (默认，成本低 60%) 和 `spark-1-pro` (精度更高)

<div id="example">
  ### 示例 [#示例]
</div>

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="curl+node+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Node">
        Node
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="cURL">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      from firecrawl import Firecrawl
      from pydantic import BaseModel, Field
      from typing import List, Optional

      app = Firecrawl(api_key="fc-YOUR_API_KEY")

      class Founder(BaseModel):
          name: str = Field(description="Full name of the founder")
          role: Optional[str] = Field(None, description="Role or position")
          background: Optional[str] = Field(None, description="专业背景")

      class FoundersSchema(BaseModel):
          founders: List[Founder] = Field(description="List of founders")

      result = app.agent(
          prompt="Find the founders of Firecrawl",
          schema=FoundersSchema,
          model="spark-1-mini",
          max_credits=100
      )

      print(result.data)
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Node">
      ```js  
      import { Firecrawl } from 'firecrawl';
      import { z } from 'zod';

      const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

      const result = await firecrawl.agent({
        prompt: "Find the founders of Firecrawl",
        schema: z.object({
          founders: z.array(z.object({
            name: z.string().describe("Full name of the founder"),
            role: z.string().describe("Role or position").optional(),
            background: z.string().describe("Professional background").optional()
          })).describe("List of founders")
        }),
        model: "spark-1-mini",
        maxCredits: 100
      });

      console.log(result.data);
      ```
    </CodeBlockTab>

    <CodeBlockTab value="cURL">
      ```bash  
      curl -X POST "https://api.firecrawl.dev/v2/agent" \
        -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "prompt": "Find the founders of Firecrawl",
          "model": "spark-1-mini",
          "maxCredits": 100,
          "schema": {
            "type": "object",
            "properties": {
              "founders": {
                "type": "array",
                "description": "List of founders",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string", "description": "Full name" },
                    "role": { "type": "string", "description": "Role or position" },
                    "background": { "type": "string", "description": "专业背景" }
                  },
                  "required": ["name"]
                }
              }
            },
            "required": ["founders"]
          }
        }'
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<div id="best-use-case-autonomous-research-discovery">
  ### 最佳用例：自主研究与探索 [#最佳用例自主研究与探索]
</div>

**场景**：你需要查找关于获得 A 轮融资的 AI 初创公司的信息，包括其创始人及融资金额。

**为什么用 `/agent`**：你不知道从哪些网站可以获取这些信息。`agent` 会自主在网上搜索，访问相关来源 (Crunchbase、新闻网站、公司页面) ，并为你整理结构化数据。

更多详情请参见 [Agent 文档](/zh/features/agent)。

***

<div id="2-extract-endpoint">
  ## 2. `/extract` 端点 [#2-extract-端点]
</div>

<Note>
  **请改用 `/agent`**：我们建议迁移到 [`/agent`](/zh/features/agent)——它更快、更可靠、无需提供 URL，并且能覆盖所有 `/extract` 的用例并支持更多场景。
</Note>

`/extract` 端点使用基于 LLM 的提取能力，从指定的 URL 或整个域名中收集结构化数据。

<div id="key-characteristics">
  ### 关键特性 [#关键特性-1]
</div>

* **通常需要提供 URL**：至少提供一个 URL (支持通配符，如 `example.com/*`)
* **域级爬取**：可以爬取并解析在某个域名下发现的所有 URL
* **网页搜索增强**：可选参数 `enableWebSearch`，用于跟踪指定域名之外的链接
* **可选 Schema**：同时支持严格的 JSON schema 或自然语言提示词
* **异步处理**：返回用于状态查询的任务 ID

<div id="the-url-limitation">
  ### URL 限制 [#url-限制]
</div>

`/extract` 的核心问题在于，你通常需要提前知道 URL：

1. **发现缺口**：对于类似“找出 YC W24 公司”这样的任务，你并不知道哪些 URL 包含所需数据。你需要在调用 `/extract` 之前先单独执行一次搜索。
2. **笨拙的网页搜索**：虽然有 `enableWebSearch`，但它只能从你提供的 URL 开始——对于以发现为主的任务来说，这个流程非常别扭。
3. **`/agent` 被创建的原因**：`/extract` 很擅长从已知位置抽取数据，但在“先发现数据在哪里”这方面就没那么有效。

<div id="example">
  ### 示例 [#示例-1]
</div>

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="curl+node+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Node">
        Node
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="cURL">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      from firecrawl import Firecrawl

      firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

      schema = {
          "type": "object",
          "properties": {"description": {"type": "string"}},
          "required": ["description"],
      }

      res = firecrawl.extract(
          urls=["https://docs.firecrawl.dev"],
          prompt="提取该页面的描述",
          schema=schema,
      )

      print(res.data["description"])
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Node">
      ```js  
      import { Firecrawl } from 'firecrawl';

      const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

      const schema = {
        type: 'object',
        properties: {
          title: { type: 'string' }
        },
        required: ['title']
      };

      const res = await firecrawl.extract({
        urls: ['https://docs.firecrawl.dev'],
        prompt: 'Extract the page title',
        schema,
        scrapeOptions: { formats: [{ type: 'json', prompt: 'Extract', schema }] }
      });

      console.log(res.status || res.success, res.data);
      ```
    </CodeBlockTab>

    <CodeBlockTab value="cURL">
      ```bash  
      curl -s -X POST "https://api.firecrawl.dev/v2/extract" \
        -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "urls": ["https://docs.firecrawl.dev"],
          "prompt": "提取页面标题",
          "schema": {
            "type": "object",
            "properties": {"title": {"type": "string"}},
            "required": ["title"]
          },
          "scrapeOptions": {
            "formats": [{"type": "json", "prompt": "提取", "schema": {"type": "object"}}]
          }
        }'
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<div id="best-use-case-targeted-multi-page-extraction">
  ### 最佳使用场景：有针对性的多页面提取 [#最佳使用场景有针对性的多页面提取]
</div>

**场景**：你有竞争对手的文档 URL，想从 `docs.competitor.com/*` 中提取出他们所有的 API 端点。

**为什么这里使用 `/extract` 很合适**：你已经知道确切的域名。但即便如此，如今在提供 URL 的前提下，`/agent` 通常会得到更好的效果。

更多详情，请参阅 [Extract 文档](/zh/features/extract)。

***

<div id="3-scrape-endpoint-with-json-mode">
  ## 3. 使用 JSON 模式的 `/scrape` 端点 [#3-使用-json-模式的-scrape-端点]
</div>

使用 JSON 模式的 `/scrape` 端点是可控性最高的方案——它使用 LLM 将页面内容解析为你指定的 schema，从单个已知 URL 中提取结构化数据。

<div id="key-characteristics">
  ### 关键特性 [#关键特性-2]
</div>

* **仅支持单个 URL**：用于一次仅从一个特定页面提取数据
* **必须提供精确 URL**：必须明确包含数据的精确 URL
* **Schema 可选**：可以使用 JSON schema，或仅提供 prompt (由 LLM 决定结构)
* **同步**：立即返回数据 (无需轮询任务状态)
* **额外 formats**：可以在一次请求中同时获取 JSON 抽取结果以及 markdown、HTML、截图等

<div id="example">
  ### 示例 [#示例-2]
</div>

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="curl+node+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Node">
        Node
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="cURL">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      from firecrawl import Firecrawl
      from pydantic import BaseModel

      app = Firecrawl(
        # 无需 API 密钥即可开始使用 — 添加一个以获得更高的限流额度：
        # api_key="fc-YOUR-API-KEY",
      )

      class CompanyInfo(BaseModel):
          company_mission: str
          supports_sso: bool
          is_open_source: bool
          is_in_yc: bool

      result = app.scrape(
          'https://firecrawl.dev',
          formats=[{
            "type": "json",
            "schema": CompanyInfo.model_json_schema()
          }],
          only_main_content=False,
          timeout=120000
      )

      print(result)
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Node">
      ```js  
      import { Firecrawl } from "firecrawl";
      import { z } from "zod";

      const app = new Firecrawl({
        // 无需 API 密钥即可开始使用——添加一个以获得更高的限流额度：
        // apiKey: "fc-YOUR_API_KEY",
      });

      // Define schema to extract contents into
      const schema = z.object({
        company_mission: z.string(),
        supports_sso: z.boolean(),
        is_open_source: z.boolean(),
        is_in_yc: z.boolean()
      });

      const result = await app.scrape("https://firecrawl.dev", {
        formats: [{
          type: "json",
          schema: schema
        }],
      });

      console.log(result);
      ```
    </CodeBlockTab>

    <CodeBlockTab value="cURL">
      ```bash  
      # 无需 API 密钥即可开始使用 — 添加 -H "Authorization: Bearer YOUR_API_KEY" 以获得更高的限流额度：
      curl -X POST https://api.firecrawl.dev/v2/scrape \
          -H 'Content-Type: application/json' \
          -d '{
            "url": "https://firecrawl.dev",
            "formats": [ {
              "type": "json",
              "schema": {
                "type": "object",
                "properties": {
                  "company_mission": {
                            "type": "string"
                  },
                  "supports_sso": {
                            "type": "boolean"
                  },
                  "is_open_source": {
                            "type": "boolean"
                  },
                  "is_in_yc": {
                            "type": "boolean"
                  }
                },
                "required": [
                  "company_mission",
                  "supports_sso",
                  "is_open_source",
                  "is_in_yc"
                ]
              }
            } ]
          }'
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<div id="best-use-case-single-page-precision-extraction">
  ### 最佳适用场景：单页精确抽取 [#最佳适用场景单页精确抽取]
</div>

**场景**：你在构建一个价格监控工具，需要从已知 URL 的特定产品页面中抽取价格、库存状态和产品详情。

**为什么使用 `/scrape` 搭配 JSON 模式**：你确切知道哪个页面包含所需数据，需要对单页进行精确抽取，并且希望同步返回结果，而不想处理任务管理的开销。

更多详情请参阅 [JSON 模式文档](/zh/features/llm-extract)。

***

<div id="decision-guide">
  ## 决策指南 [#决策指南]
</div>

**您是否知道包含数据的确切 URL?**

* **否** → 使用 `/agent`(自主网页发现)
* **是**
  * **单个页面?** → 使用 `/scrape` 配合 JSON 模式
  * **多个页面?** → 使用 `/agent` 配合 URL (或使用 `/scrape` 配合批量处理)

<div id="recommendations-by-scenario">
  ### 按场景推荐 [#按场景推荐]
</div>

| 场景                         | 推荐使用的 Endpoint      |
| -------------------------- | ------------------- |
| 「查找所有 AI 初创公司及其融资情况」       | `/agent`            |
| 「从这个特定的产品页面中提取数据」          | `/scrape` (JSON 模式) |
| 「获取 competitor.com 上的所有博文」 | `/agent` 配合 URL     |
| 「监控多个已知 URL 的价格变化」         | `/scrape` 配合批量处理    |
| 「调研某一特定行业的公司」              | `/agent`            |
| 「从 50 个已知公司页面中提取联系信息」      | `/scrape` 配合批量处理    |

***

<div id="pricing">
  ## 价格 [#价格]
</div>

| 端点                  | 费用                                | 备注                 |
| ------------------- | --------------------------------- | ------------------ |
| `/scrape` (JSON 模式) | 5 额度/页 (1 基础 + 4 个 JSON 模式)       | 固定且可预测             |
| `/extract`          | 按 Token 计费 (1 credit = 15 tokens) | 随内容变化              |
| `/agent`            | 动态计费                              | 每天可免费运行 5 次；视复杂度而定 |

<div id="example-find-the-founders-of-firecrawl">
  ### 示例：“查找 Firecrawl 的创始人” [#示例查找-firecrawl-的创始人]
</div>

| Endpoint   | 工作方式                              | 消耗积分            |
| ---------- | --------------------------------- | --------------- |
| `/scrape`  | 你先手动找到 URL，然后抓取 1 个页面             | 约 1 个积分         |
| `/extract` | 你提供一个或多个 URL，即可抽取结构化数据            | 可变 (按 token 计费) |
| `/agent`   | 只需发送提示词 (prompt) ——agent 会自动发现并抽取 | 约 100–500 个积分   |

**取舍**：`/scrape` 成本最低，但需要你事先知道 URL。`/agent` 成本更高，但会自动完成网址发现。

有关详细定价，请参见 [Firecrawl Pricing](https://firecrawl.dev/pricing)。

***

<div id="migration-extract-agent">
  ## 迁移：`/extract` → `/agent` [#迁移extract--agent]
</div>

如果你当前正在使用 `/extract` 接口，迁移过程非常简单：

**迁移前 (使用 `/extract`) ：**

```python
result = app.extract(
    urls=["https://example.com/*"],
    prompt="提取产品信息",
    schema=schema
)
```

**之后 (使用 Agent) ：**

```python
result = app.agent(
    urls=["https://example.com"],  # 可选 - 可完全省略
    prompt="Extract product information from example.com",
    schema=schema,
    model="spark-1-mini"  # 或使用 "spark-1-pro" 获得更高准确度
)
```

关键优势在于：使用 `/agent` 时，你甚至可以省略 URL，只需描述你的需求。

***

<div id="key-takeaways">
  ## 关键要点 [#关键要点]
</div>

1. **已经知道精确 URL？** 使用 `/scrape` 搭配 JSON 模式——这是最便宜 (5 额度/页面) 、最快 (同步) 、且最可预测的选项。

2. **需要自动化调研？** 使用 `/agent`——它会自动完成信息发现，每天有 5 次免费运行，之后根据复杂度动态计费。

3. **将 `/extract` 迁移** 到用于新项目的 `/agent`——`/agent` 是功能更强的继任方案。

4. **成本与便利性的权衡**：当你已经知道 URL 时，`/scrape` 性价比最高；`/agent` 成本更高，但免去了手动发现 URL 的工作。

***

<div id="further-reading">
  ## 延伸阅读 [#延伸阅读]
</div>

* [Agent 文档](/zh/features/agent)
* [Agent 模型](/zh/features/models)
* [JSON 模式文档](/zh/features/llm-extract)
* [Extract 文档](/zh/features/extract)
* [批量抓取](/zh/features/batch-scrape)