ScrapeGraphAI 中文教程：用一句中文描述抓取任意网页数据

一、它到底是什么，能帮你做什么

入门

传统爬虫要你先读懂网页的 HTML 结构，再一条条写规则去"抠"数据。网页一改版，规则全废。ScrapeGraphAI 换了个思路：你只要用一句大白话说明想要什么，它自己去读页面、把数据整理成结构化结果。

打个比方，传统爬虫像是你拿着清单去仓库一件件搬货；ScrapeGraphAI 像是你告诉管家"把这家公司的简介、创始人和社交账号整理给我"，剩下的它自己搞定。

它背后调用大语言模型（LLM，可以理解为能读懂文字并做判断的 AI）来理解页面内容，所以对网页结构变化没那么敏感。支持抓取网站，也支持本地文件（XML、HTML、JSON、Markdown 等）。

ScrapeGraphAI 项目概览

它有两种用法：自己部署的 Python 库（免费、跑在你自己的机器上），以及官方托管的云服务（通过 SDK 调用，省去自己配模型）。本文讲的是自己部署的 Python 库。

二、开始前你需要准备什么

入门

这一步别跳过，缺一样后面都会报错。

Python 3.10 或更高版本：库本身是 Python 写的，版本太低装不上。
一个能用的 LLM：可以选云端模型（OpenAI、Groq、Gemini 等，需要对应 API Key），也可以选本地模型（用 Ollama 跑，不花钱但要先装好 Ollama）。
网络能访问目标网站：抓取本质是程序替你去打开网页，网络不通自然拿不到数据。

如果你完全没接触过命令行，建议先装一个虚拟环境（把项目依赖单独隔离，避免和系统里其他 Python 程序打架），README 里也特别提醒了这一点。

三、安装：两条命令搞定

入门

安装分两步。第一条装库本身，第二条装浏览器内核——因为很多网页内容是靠浏览器动态渲染出来的，不装它抓不到。

pip install scrapegraphai

## 抓取网页内容必需的浏览器内核
playwright install

如果你用的是本地模型（Ollama），还需要额外装一个配套命令：

pip install "scrapegraphai[ollama]"

装完后可以简单验证一下：在命令行输入 python 进入交互环境，执行 from scrapegraphai.graphs import SmartScraperGraph，不报错就说明装好了。

四、跑通第一个抓取任务

入门

最常用的抓取管道叫 SmartScraperGraph（智能抓取图），作用是从单个页面按你的描述提取信息。把下面这段存成 demo.py 再运行：

from scrapegraphai.graphs import SmartScraperGraph
import json

## 配置抓取管道
graph_config = {
    "llm": {
        "model": "ollama/llama3.2",   # 换成你的模型
        "model_tokens": 8192,
        "format": "json",
    },
    "verbose": True,     # 打印执行过程，方便排查
    "headless": False,   # 是否显示浏览器窗口
}

smart_scraper_graph = SmartScraperGraph(
    prompt="提取网页有用信息，包括公司简介、创始人和社交媒体链接",
    source="https://scrapegraphai.com/",
    config=graph_config
)

result = smart_scraper_graph.run()
print(json.dumps(result, indent=4))

三个关键参数分别是：prompt（你想要什么，用自然语言写）、source（抓哪个页面）、config（用哪个模型、怎么跑）。运行后终端会打印出 JSON 格式的结果。

ScrapeGraphAI 的 API 使用示意

五、配置项逐个讲清楚

进阶 · 推荐细读

配置写错是最常见的报错来源，下面几个字段值得单独说明。

model：模型名称。云端写成 openai/gpt-4o 这类格式，本地写成 ollama/llama3.2。
model_tokens：模型一次能处理的最大文字量。页面很长时要调大，否则内容会被截断。
format：设为 json 让模型直接输出结构化结果，方便后续处理。
verbose：设为 True 会打印每一步执行细节，调试阶段建议开着。
headless：False 会弹出浏览器窗口，能亲眼看到抓取过程；正式跑批时设 True 更省资源。

用云端模型时，API Key 一般通过环境变量传入，不要把密钥直接写在代码里提交到公开仓库。

页面特别长、或者要抓很多页时，注意 model_tokens 和调用成本会同步上升，建议先用小范围页面测试效果再放大。

六、常见问题排查

进阶 · 推荐细读

新手最容易卡在这几处，对照检查一般能解决。

抓回来是空内容：多数是没执行 playwright install，或者页面是动态渲染的，试试把 headless 设为 False 观察。
模型连不上：本地模型确认 Ollama 已经在运行；云端模型确认 API Key 正确、账户有余额。
结果被截断：调大 model_tokens，或缩小抓取范围。
装库报错：先确认 Python 版本 ≥ 3.10，并尽量在虚拟环境里安装。
想抓本地文件：source 直接填本地文件路径即可，支持 XML、HTML、JSON、Markdown。

七、进阶方向与运维建议

深入 · 老手可选

跑通单页之后，可以往这几个方向扩展。

批量抓取：把多个 URL 放进循环，配合脚本定时执行，形成自己的数据采集流程。
接代理：高频抓取容易被目标网站限制，可通过代理服务分散请求（项目 README 中有合作代理商的说明）。
换更强模型：页面结构越复杂，越需要理解能力强的模型，效果和成本需要自己权衡。
数据备份：抓取结果建议落盘保存为 JSON 文件，别只打印在终端里，否则程序一关就没了。

如果不想自己配模型、管服务器，官方也提供了托管版云服务，通过 Python 或 JS/TS 的 SDK 调用即可，适合只想拿数据、不想折腾环境的场景。两种方式按自己的需求选就行。

项目信息

项目	值
仓库	ScrapeGraphAI/Scrapegraph-ai
语言	Python
Star	31,397
Fork	3,171
主页	https://scrapegraphai.com

参考链接

延伸阅读

想继续探索？这些同领域的教程可能也适合你：

S.A.O