JSON 模式 | Firecrawl

选择合适的工具。 当你只有一个 URL，并且想从该页面提取字段时，JSON 模式 (本页) 就是合适的选择。

对于任何超出单个 URL 的场景——例如多个 URL、URL 模式或代理发现——请参见代理。
完整对比：如何选择数据提取器。

v2 API 变更： v2 已完全支持 JSON schema 提取，但 API 格式有所调整。在 v2 中，schema 直接嵌入到 format 对象中，写法为 formats: [{type: "json", schema: {...}}]。v1 的 jsonOptions 参数在 v2 中已被移除。

对于 schema 验证失败及其他提取错误，请参见 Errors——提取相关问题通常会表现为 400 或 422 响应。

使用 Firecrawl 抓取并提取结构化数据

Firecrawl 借助 AI 通过 3 个步骤从网页获取结构化数据：

设置 Schema (可选) ： 定义一个 JSON Schema (采用 OpenAI 的格式) 来明确所需数据；如果不需要严格的 Schema，也可仅提供一个 prompt，并附上网页 URL。
发起请求： 使用 JSON 模式将你的 URL 和 Schema 发送到我们的 /scrape 端点。查看方法： Scrape Endpoint Documentation
获取数据： 返回与你的 Schema 匹配的干净、结构化数据，可直接使用。

这使你能快速、轻松地按所需 formats 获取网页数据。

提取结构化数据

通过 /scrape 的 JSON 模式

用于从抓取的页面中提取结构化数据。

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)

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);

# 无需 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"
          ]
        }
      } ]
    }'

输出：

JSON

{
    "success": true,
    "data": {
      "json": {
        "company_mission": "AI 赋能的网页抓取与数据抽取",
        "supports_sso": true,
        "is_open_source": true,
        "is_in_yc": true
      },
      "metadata": {
        "title": "Firecrawl",
        "description": "AI 赋能的网页抓取与数据抽取",
        "robots": "follow, index",
        "ogTitle": "Firecrawl",
        "ogDescription": "AI 赋能的网页抓取与数据抽取",
        "ogUrl": "https://firecrawl.dev/",
        "ogImage": "https://firecrawl.dev/og.png",
        "ogLocaleAlternate": [],
        "ogSiteName": "Firecrawl",
        "sourceURL": "https://firecrawl.dev/"
      },
    }
}

无需 schema 的结构化数据

你也可以只向端点传入一个 prompt，在没有 schema 的情况下进行提取。LLM 会自行确定数据结构。

from firecrawl import Firecrawl

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

result = app.scrape(
    'https://firecrawl.dev',
    formats=[{
      "type": "json",
      "prompt": "Extract the company mission from the page."
    }],
    only_main_content=False,
    timeout=120000
)

print(result)

import { Firecrawl } from "firecrawl";

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

const result = await app.scrape("https://firecrawl.dev", {
  formats: [{
    type: "json",
    prompt: "Extract the company mission from the page."
  }]
});

console.log(result);

# 无需 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",
        "prompt": "Extract the company mission from the page."
      }]
    }'

输出：

JSON

{
    "success": true,
    "data": {
      "json": {
        "company_mission": "AI 驱动的网页抓取与数据抽取",
      },
      "metadata": {
        "title": "Firecrawl",
        "description": "AI 驱动的网页抓取与数据抽取",
        "robots": "follow, index",
        "ogTitle": "Firecrawl",
        "ogDescription": "AI 驱动的网页抓取与数据抽取",
        "ogUrl": "https://firecrawl.dev/",
        "ogImage": "https://firecrawl.dev/og.png",
        "ogLocaleAlternate": [],
        "ogSiteName": "Firecrawl",
        "sourceURL": "https://firecrawl.dev/"
      },
    }
}

真实案例：提取公司信息

下面是一个从网站提取结构化公司信息的完整示例：

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()
    }]
)

print(result)

import { Firecrawl } from "firecrawl";
import { z } from "zod";

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

const companyInfoSchema = 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: companyInfoSchema
  }]
});

console.log(result);

# 无需 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"
          ]
        }
      }]
    }'

输出：

Output

{
  "success": true,
  "data": {
    "json": {
      "company_mission": "将网站转换为 LLM 可用数据",
      "supports_sso": true,
      "is_open_source": true,
      "is_in_yc": true
    }
  }
}

JSON 格式选项

在 v2 中使用 JSON 模式时，需要在 formats 中直接包含一个内嵌 schema 的对象： formats: [{ type: 'json', schema: { ... }, prompt: '...' }] 参数：

schema: 描述所需结构化输出的 JSON Schema (基于 schema 的提取为必填) 。
prompt: 可选提示，用于引导提取 (也用于无 schema 的提取) 。
checkPromptInjection: 已废弃。请改用顶层的 checkPromptInjection 抓取选项 (请参见 prompt 注入检测)。在此处设置的值仍然有效。

重要说明： 与 v1 不同，v2 中没有单独的 jsonOptions 参数。schema 必须直接包含在 formats 数组中的格式对象内。

prompt 注入检测

网页可能包含精心构造的隐藏文本，用于劫持 LLM，例如指示模型忽略你的 schema 并返回由攻击者控制的数据。如果你抓取的是不受信任或用户提交的 URL，可以设置顶层抓取选项 checkPromptInjection，在任何基于 LLM 的格式 (如 json、summary 或 question) 运行前检查页面内容。该选项适用于除 rawBase64 之外的所有格式，包括普通的 markdown 抓取：

{
  "url": "https://example.com",
  "formats": [
    {
      "type": "json",
      "schema": { "type": "object", "properties": { "title": { "type": "string" } } }
    }
  ],
  "checkPromptInjection": true
}

工作原理：

专用分类器会在每次抓取时检查一次页面内容，且在任何基于 LLM 的格式运行之前执行，因此会为请求增加分类器的延迟。
如果检测到 prompt 注入尝试，请求会失败并返回 HTTP 403 和错误代码 SCRAPE_PROMPT_INJECTION_DETECTED。不会返回任何输出。
如果检查无法扫描全部内容 (例如分类器调用失败，或页面内容超过 2,000,000 个字符) ，抓取会继续进行，响应中会包含 warning，且该检查不计费。
该检查运行时，会额外计费 +4 额度。如果检查运行后抓取失败 (包括检测到注入且请求被封禁时) ，则会计费 5 额度，而不是失败抓取通常的 0 额度，因为分类器调用仍已运行。

该选项同样适用于批量抓取，以及爬取、搜索和 monitors 的 scrapeOptions。在 json 格式 object 上设置 checkPromptInjection 仍然有效，但已废弃。在 v1 中，该选项为 jsonOptions.checkPromptInjection。SDKs 中以 checkPromptInjection (JS) 和 check_prompt_injection (Python) 的形式提供。

JSON 提取中不支持 HTML 属性。 JSON 提取是基于页面的 Markdown 转换结果工作的，该转换只保留可见文本内容。HTML 属性 (例如 data-id、元素上的自定义属性) 会在转换过程中被去除，大语言模型无法看到这些属性。如果你需要提取 HTML 属性值，请使用 rawHtml 格式并在客户端解析属性，或者使用 executeJavascript 动作为在提取前将属性值注入到可见文本中。

保持提取一致性的技巧

如果你在使用 JSON 提取时遇到结果不一致或不完整的情况，可以参考以下做法：

让 prompt 简短且聚焦。 带有大量规则的长 prompt 会增加结果的不确定性。将具体约束 (如允许值) 移入 schema 本身。
使用简洁的属性名。 避免在属性名中嵌入说明或枚举列表。用类似 "installation_type" 这样的简短键名，并把允许值放在 enum 数组中。
为受限字段添加 enum 数组。 当某个字段只有固定取值时，将它们列在 enum 中，并确保与页面上显示的文本完全匹配。
在字段描述中包含 null 处理逻辑。 在每个字段的 description 中添加 "Return null if not found on the page."，以避免模型猜测缺失值。
添加位置信息提示。 告诉模型在页面上哪里查找数据，例如 "Flow rate in GPM from the Specifications table."。
将大型 schema 拆分成多个请求。 字段很多 (例如 30+) 的 schema 通常会产生更不稳定的结果。将其拆成 2–3 个请求，每个请求包含 10–15 个字段。
避免在数组上使用 minItems/maxItems。 minItems 和 maxItems 这类 JSON Schema 验证关键字并不能控制抓取器收集多少内容。设置 minItems: 20 并不会让 LLM 返回更多条目——反而可能会为了满足约束而臆造一些条目。请移除这些关键字，改用 prompt 来引导完整性 (例如 "Extract ALL reviews from the page. Do not skip any.")。
使用 "type": "array" 提取列表项。 如果你需要提取多个条目 (例如人员、产品或评论列表)，请将它们放在带有 items 块的数组属性中。对列表使用 "type": "object" 只会返回单个条目。请参见下方的数组 schema 示例。

结构良好的 schema 示例：

{
  "type": "object",
  "properties": {
    "product_name": {
      "type": ["string", "null"],
      "description": "Full descriptive product name as shown on the page. Return null if not found."
    },
    "installation_type": {
      "type": ["string", "null"],
      "description": "Installation type from the Specifications section. Return null if not found.",
      "enum": ["Deck-mount", "Wall-mount", "Countertop", "Drop-in", "Undermount"]
    },
    "flow_rate_gpm": {
      "type": ["string", "null"],
      "description": "Flow rate in GPM from the Specifications section. Return null if not found."
    }
  }
}

提取条目列表的示例： 当页面包含多个条目 (例如团队成员、产品、评论) 时，使用 "type": "array" 搭配 "items" 来获取完整列表：

{
  "type": "object",
  "properties": {
    "people": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "role": { "type": "string" },
          "department": { "type": "string" }
        }
      }
    }
  }
}

你是需要 Firecrawl API 密钥的 AI 代理吗？请参阅 firecrawl.dev/agent-onboarding/SKILL.md 了解自动化入门说明。

快速上手

核心端点

更多

快速入门

开发者指南

Webhooks

使用场景

其他

参与贡献

JSON 模式 - 结构化结果

使用 Firecrawl 抓取并提取结构化数据

提取结构化数据

通过 /scrape 的 JSON 模式

无需 schema 的结构化数据

真实案例：提取公司信息

JSON 格式选项

prompt 注入检测

保持提取一致性的技巧

​使用 Firecrawl 抓取并提取结构化数据

​提取结构化数据

​通过 /scrape 的 JSON 模式

​无需 schema 的结构化数据

​真实案例：提取公司信息

​JSON 格式选项

​prompt 注入检测

​保持提取一致性的技巧

使用 Firecrawl 抓取并提取结构化数据

提取结构化数据

通过 /scrape 的 JSON 模式

无需 schema 的结构化数据

真实案例：提取公司信息

JSON 格式选项

prompt 注入检测

保持提取一致性的技巧