scrapfly-extraction

Scrapfly Extraction

使用 Scrapfly Extraction API，通过 LLM 提示词、预训练 AI 模型或自定义提取模板，从 HTML、Markdown 或文本中提取结构化数据。

适用场景

• 从网页内容中提取结构化数据
• 使用自然语言提示词从文档中提取特定信息
• 使用自动 AI 模型提取产品、文章、评论或房地产数据
• 使用自定义模板将 HTML/Markdown 解析为结构化格式
• 针对文档内容提问并获取 AI 驱动的回答

设置

pip install scrapfly-sdk

必须通过环境变量 SCRAPFLY_API_KEY 提供 API 密钥，或直接传递给客户端。

API 参考

端点： POST https://api.scrapfly.io/extraction

ScrapflyClient

from scrapfly import ScrapflyClient, ExtractionConfig
import os

client = ScrapflyClient(key=os.environ["SCRAPFLY_API_KEY"])

ExtractionConfig 参数

参数	类型	默认值	描述
body	str	必填	要从中提取数据的文档内容
content_type	str	必填	输入格式："text/html"、"text/markdown"、"text/plain"、"text/xml"
url	str	None	用于解析 HTML 中相对链接的基础 URL
charset	str	None	文档编码（若省略则自动检测）
extraction_prompt	str	None	用于 LLM 提取的自然语言指令
extraction_model	str	None	预训练模型："product"、"article"、"review_list"、"real_estate_listing"
extraction_template	str	None	自定义模板名称或内联模板定义
timeout	int	None	处理超时时间，单位为秒（60-155）
webhook_name	str	None	用于异步处理的 Webhook 名称

必须且只能提供以下其中一项： extraction_prompt、extraction_model 或 extraction_template。

三种提取方式

1. LLM 提示词提取

使用自然语言描述要提取的数据。AI 会解析内容并返回结构化结果。

2. 自动 AI 模型

针对常见数据类型的预训练模型。返回带有质量评分的标准化架构。

• "article" - 新闻/博客文章（标题、作者、日期、内容等）
• "event" - 活动（名称、日期、地点、描述等）
• "food_recipe" - 食谱（食材、步骤、份量等）
• "hotel" - 单家酒店/房产（名称、设施、评分等）
• "hotel_listing" - 酒店搜索/列表结果
• "job_listing" - 职位搜索/列表结果
• "job_posting" - 单个职位（职位名称、公司、薪资、描述等）
• "organization" - 公司/组织（名称、联系方式、描述等）
• "product" - 电商产品（名称、价格、描述、图片等）
• "product_listing" - 产品搜索/分类列表
• "real_estate_property" - 单处房产（价格、地址、特征等）
• "real_estate_property_listing" - 房产搜索/列表结果
• "review_list" - 评论列表（评论者、评分、文本、日期等）
• "search_engine_results" - SERP 数据（结果、摘要等）
• "social_media_post" - 社交媒体帖子（作者、内容、互动数据等）
• "software" - 软件/应用（名称、描述、定价等）
• "stock" - 股票/市场数据
• "vehicle_ad" - 单辆车的挂牌信息
• "vehicle_ad_listing" - 车辆搜索/列表结果

3. 自定义模板

用于在相似页面间保持解析一致性的结构化提取规则。可以内联定义（JSON 对象），也可以存储在 Scrapfly 上并通过 slug 引用。

已保存的模板（按 slug 引用）

如果你已在 Scrapfly 控制面板中保存模板（Extraction API → Templates），请将其 slug 作为普通字符串传入。平台会解析为当前已发布的版本并应用：

result = client.extract(ExtractionConfig(
    body=html_content,
    content_type="text/html",
    url="https://example.com/product/1",
    extraction_template="product-card",
))

已保存的模板支持：

• 完整的版本历史记录，并设有单独的发布指针（可原子性地发布新版本；也可随时回滚）。
• 可选的 URL 范围（match_domain / match_path），在控制面板中配置。请求不匹配的 URL 时会返回 ERR::EXTRACTION::TEMPLATE_URL_MISMATCH。
• 读取时缓存，TTL 为 60 秒：新发布的版本会在一分钟内生效，无需重新部署客户端。

slug 格式为小写字母、数字或连字符，长度为 3 到 128 个字符。

内联模板

传入 Python 字典即可执行一次提取，无需保存。适用于一次性脚本，以及每次调用都不同的模板。

extraction_template = {
    "source": "html",
    "selectors": [    
        {
            "name": "title",
            "query": "h3.product-title::text",
            "type": "css",
            "formatters": [
                {
                    "name": "uppercase"
                }
            ],
        },
        {
            "name": "description",
            "query": "p.product-description::text",
            "type": "css"
        },
        {
            "extractor": {
                "name": "price"
            },
            "name": "price",
            "query": ".product-price::text",
            "type": "css"
        },
        {
            "name": "variants",
          	"query": "div.variants",
            "type": "css",
            "nested": [
                {
                    "name": "name",
                    "query": "//a[@data-variant-id]/@data-variant-id",
                    "type": "xpath",
                    "multiple": True,
                },
                {
                    "name": "link",
                    "query": "//a[@data-variant-id]/@href",
                    "type": "xpath",
                    "multiple": True,
                },
            ]
        },
        {
            "name": "reviews",
            "query": "div.review>p::text",
            "type": "css",
            "multiple": True,            
        }
    ]
}

示例

从 HTML 中提取 LLM 提示词

from scrapfly import ScrapflyClient, ExtractionConfig
import os

client = ScrapflyClient(key=os.environ["SCRAPFLY_API_KEY"])

html_content = "<html><body><h1>iPhone 15</h1><span class='price'>$999</span><p>Latest Apple smartphone</p></body></html>"

result = client.extract(ExtractionConfig(
    body=html_content,
    content_type="text/html",
    extraction_prompt="Extract the product name, price, and description as JSON",
))

# result
result.extraction_result['data']
# or
print(result.data)

# result content_type
result.extraction_result['content_type']
# or
print(result.content_type)

从 Markdown 中提取 LLM 提示词

markdown_content = """
# Best Restaurants in NYC

1. **Le Bernardin** - French, $$$, 4.8 stars
2. **Peter Luger** - Steakhouse, $$$, 4.5 stars
3. **Di Fara Pizza** - Italian, $, 4.7 stars
"""

result = client.extract(ExtractionConfig(
    body=markdown_content,
    content_type="text/markdown",
    extraction_prompt="Extract each restaurant as a JSON array with name, cuisine, price_range, and rating fields",
))
print(result.data)

Auto AI 模型：提取产品信息

from scrapfly import ScrapflyClient, ExtractionConfig, ScrapeConfig
# First scrape the page, then extract
scrape_result = client.scrape(ScrapeConfig(url="https://web-scraping.dev/product/1"))

result = client.extract(ExtractionConfig(
    body=scrape_result.content,
    content_type="text/html",
    url="https://web-scraping.dev/product/1",
    extraction_model="product",
))

print(result.data)
# Returns: {"name": "...", "price": "...", "currency": "...", "description": "...", ...}

针对内容提问

result = client.extract(ExtractionConfig(
    body=html_content,
    content_type="text/html",
    extraction_prompt="What is the most expensive item on this page and how much does it cost?",
))
print(result.data)

在一个工作流中完成抓取和提取

from scrapfly import ScrapflyClient, ScrapeConfig, ExtractionConfig
import os

client = ScrapflyClient(key=os.environ["SCRAPFLY_API_KEY"])

# Step 1: Scrape the page
scrape_result = client.scrape(ScrapeConfig(
    url="https://web-scraping.dev/product/1",
    format="markdown",
))

# Step 2: Extract structured data from the content
extraction_result = client.extract(ExtractionConfig(
    body=scrape_result.content,
    content_type="text/markdown",
    extraction_prompt="Extract all products as a JSON array with fields: name, price, availability",
))

print(extraction_result.data)

使用 Scrape API 进行内联提取

你也可以直接在抓取请求中提取数据：

result = client.scrape(ScrapeConfig(
    url="https://web-scraping.dev/product/1",
    extraction_prompt="Extract the product name, price, and description as JSON",
))
# Extraction result is included in the scrape response
print(result.scrape_result["extracted_data"])

自定义提取模板（内联）

# First, scrape the web page to retrieve its HTML
api_response = client.scrape(scrape_config=ScrapeConfig(
    url='https://web-scraping.dev/product/1',
    render_js=True
))

html = api_response.content

# extraction template for HTML parsing instructions. It accepts the following:
# selectors: CSS, XPath, JMESPath, Regex, Nested (nesting multiple selector types)
# extractors: extracts commonly accessed data types: price, image, links, emails
# formatters: transforms the extracted data for common methods: lowercase, uppercase, datatime, etc.
# refer to the docs for more details: https://scrapfly.io/docs/extraction-api/rules-and-template#rules
extraction_template = {
    "source": "html",
    "selectors": [    
        {
            "name": "title",
            "query": "h3.product-title::text",
            "type": "css",
            "formatters": [
                {
                    "name": "uppercase"
                }
            ],
        },
        {
            "name": "description",
            "query": "p.product-description::text",
            "type": "css"
        },
        {
            "extractor": {
                "name": "price"
            },
            "name": "price",
            "query": ".product-price::text",
            "type": "css"
        },
        {
            "name": "variants",
          	"query": "div.variants",
            "type": "css",
            "nested": [
                {
                    "name": "name",
                    "query": "//a[@data-variant-id]/@data-variant-id",
                    "type": "xpath",
                    "multiple": True,
                },
                {
                    "name": "link",
                    "query": "//a[@data-variant-id]/@href",
                    "type": "xpath",
                    "multiple": True,
                },
            ]
        },
        {
            "name": "reviews",
            "query": "div.review>p::text",
            "type": "css",
            "multiple": True,            
        }
    ]
}

extraction_api_response = client.extract(
    extraction_config=ExtractionConfig(
        body=html, # pass the HTML content
        content_type='text/html', # content data type
        charset='utf-8', # passed content charset, use `auto` if you aren't sure
        extraction_ephemeral_template=extraction_template # declared template defintion or template name saved on the dashboard
    )
)

# extracted data
print(extraction_api_response.data)

# extracted data content_type
print(extraction_api_response.content_type)

错误处理

from scrapfly.errors import ScrapflyError

try:
    result = client.extract(ExtractionConfig(
        body="<html><body><h1>iPhone 15</h1><span class='price'>$999</span><p>Latest Apple smartphone</p></body></html",
        content_type="text/html",
        extraction_prompt="Extract the product price",
    ))
    print(result.data)
except ScrapflyError as e:
    print(f"Extraction failed: {e.message}")

重要说明

• 每个请求只能提供一种提取方法：extraction_prompt、extraction_model 或 extraction_template
• 对于 LLM 提示词，请明确指定所需的输出格式（例如“以 JSON 格式输出”）
• url 参数有助于解析 HTML 中的相对链接，但不是必需的
• 对于较大的文档，可先在抓取步骤中使用 format="markdown" 或 format="text"，以减少 token 用量
• Auto AI 模型会在提取的数据旁返回质量指标
• 也可以在抓取期间进行内联提取，只需将 extraction_prompt 或 extraction_model 添加到 ScrapeConfig 中