3.7 · Web Scraping 与 URL 入库（Web Scraping and URL Ingestion）

Web Scraping 与 URL 入库（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/3.7-web-scraping-and-url-ingestion

翻译时间：2026-05-27T08:45:08.344Z

翻译模型：deepseek-chat

原文字符数：7902

项目：Cognee (cognee)

---

网页抓取与 URL 入库

Cognee 的网页抓取模块提供了强大的基础设施，用于将网页内容入库到知识图谱中。它既支持通过 DefaultUrlCrawler（使用 BeautifulSoup 或 Playwright）进行高性能本地爬取，也支持通过 Tavily API 进行托管式提取。该系统设计上兼顾了 robots.txt 合规性、速率限制以及定时重复抓取任务。

数据流与工具选择

获取网页内容的主要入口点是 fetch_page_content，它会根据环境配置自动选择合适的工具。如果设置了 TAVILY_API_KEY，系统默认使用 Tavily；否则，会使用内部的 DefaultUrlCrawler cognee/tasks/web_scraper/utils.py:46-54。

网页抓取架构

下图展示了入库任务与底层抓取引擎之间的关系。

graph TD
    subgraph "公共 API"
        CO_ADD["cognee.add(url)"]
        CRON_TASK["cron_web_scraper_task"]
    end

    subgraph "编排层"
        WEB_TASK["web_scraper_task"]
        FETCH_PC["fetch_page_content"]
    end

    subgraph "抓取引擎"
        TAVILY["fetch_with_tavily"]
        DEF_CRAWLER["DefaultUrlCrawler"]
    end

    subgraph "外部资源"
        TAV_API["Tavily API"]
        WEB_PAGE["目标网站"]
    end

    CO_ADD --> FETCH_PC
    CRON_TASK --> WEB_TASK
    WEB_TASK --> FETCH_PC
    FETCH_PC -->|设置了 TAVILY_API_KEY| TAVILY
    FETCH_PC -->|默认| DEF_CRAWLER
    TAVILY --> TAV_API
    DEF_CRAWLER --> WEB_PAGE

来源：cognee/tasks/web_scraper/utils.py:17-87，cognee/tasks/web_scraper/web_scraper_task.py:44-115

DefaultUrlCrawler 与 robots.txt 合规性

DefaultUrlCrawler 是一个高度可配置的异步爬虫，基于 httpx 构建，并可选择使用 playwright cognee/tasks/web_scraper/default_url_crawler.py:45-86。它通过严格执行 robots.txt 规范和域名级速率限制，优先保证合规抓取。

• Robots.txt 缓存：使用 Protego 库解析 robots.txt 文件，并缓存解析结果（默认 TTL 为 3600 秒），以减少开销 cognee/tasks/web_scraper/default_url_crawler.py:31-42。
• 速率限制：爬虫会跟踪 _last_request_time_per_domain，并在向同一域名发起新请求前，强制遵守 crawl_delay（来自 robots.txt 或默认设置）cognee/tasks/web_scraper/default_url_crawler.py:136-159。
• JS 渲染：通过 use_playwright 支持 JavaScript 密集型网站 cognee/tasks/web_scraper/config.py:23-24。

来源：cognee/tasks/web_scraper/default_url_crawler.py:161-200，cognee/tasks/web_scraper/config.py:13-27

Tavily 集成

当需要托管式抓取时，Cognee 通过 fetch_with_tavily 与 Tavily API 集成。这支持"高级"提取深度，并通过 Tavily 的基础设施处理代理管理和内容清理 cognee/tasks/web_scraper/utils.py:89-142。

来源：cognee/tasks/web_scraper/config.py:6-27，cognee/tasks/web_scraper/utils.py:89-142

图模型与持久化

网页数据不仅以文本形式存储，还会被建模为图中的结构化实体。web_scraper_task 会将抓取的 URL 转换为 WebPage 和 WebSite 节点，并通过关系进行关联。

• WebPage：包含内容、哈希值以及所使用的特定提取规则 cognee/tasks/web_scraper/models.py:6-19。
• WebSite：代表域名，存储 robots.txt 数据和累计页面计数 cognee/tasks/web_scraper/models.py:22-33。
• ScrapingJob：跟踪重复任务的执行状态和调度计划 cognee/tasks/web_scraper/models.py:36-47。

自然语言到代码实体的映射：抓取对象

下图将概念上的网页实体映射到其实现类和图关系。

graph LR
    subgraph "自然语言概念"
        URL["网页 URL"]
        DOMAIN["网站域名"]
        SCHED["重复调度"]
    end

    subgraph "代码实体空间（models.py）"
        WP["WebPage（DataPoint）"]
        WS["WebSite（DataPoint）"]
        SJ["ScrapingJob（DataPoint）"]
    end

    URL -.-> WP
    DOMAIN -.-> WS
    SCHED -.-> SJ

    WP -- "is_part_of" --> WS
    SJ -- "is_scraping" --> WS

来源：cognee/tasks/web_scraper/models.py:1-47，cognee/tasks/web_scraper/web_scraper_task.py:133-134

定时抓取

Cognee 使用 APScheduler 管理重复抓取任务。cron_web_scraper_task 函数接受一个类似 cron 的 schedule 字符串（例如，"0 0 * * *" 表示每天午夜执行）cognee/tasks/web_scraper/web_scraper_task.py:44-53。

• 立即执行：如果未提供调度计划，任务会立即执行 cognee/tasks/web_scraper/web_scraper_task.py:107-115。
• 持久化：抓取任务会存储在图形数据库中，使系统能够跟踪 last_run 和 next_run 时间 cognee/tasks/web_scraper/web_scraper_task.py:178-187。
• 任务管理：任务通过从 job_name 生成的 UUID 进行标识，确保可以更新或替换 cognee/tasks/web_scraper/web_scraper_task.py:189-190。

来源：cognee/tasks/web_scraper/web_scraper_task.py:78-103，cognee/tasks/web_scraper/web_scraper_task.py:161-187

配置参数

抓取行为通过 DefaultCrawlerConfig 和 TavilyConfig 进行控制。

# BeautifulSoup 爬虫的示例配置
soup_config = DefaultCrawlerConfig(
    concurrency=5,
    crawl_delay=0.5,
    timeout=15.0,
    max_retries=2,
    extraction_rules={
        "quotes": {"selector": ".quote span.text", "all": True}
    }
)

来源：cognee/tasks/web_scraper/config.py:13-27，cognee/tests/tasks/web_scraping/web_scraping_test.py:17-25

来源：cognee/tasks/web_scraper/config.py:13-27