企业官网建设流程全解析

• 网页爬虫
• 人工智能
• AI 应用

本篇技术指南围绕 ScrapeGraphAI 仓库中的图类型说明文档展开，系统梳理该库提供的全部图（Graph）类型——包括单页爬取的 SmartScraperGraph、多页搜索的 SearchGraph、语音输出的 SpeechGraph、脚本生成的 ScriptCreatorGraph，以及基于 GPT-4o 的 OmniScraperGraph / OmniSearchGraph——并结合 graphs/ 目录下的源码实现，深入讲解每种图的节点流水线、配置参数与schema用法。读完本文，你将能够根据"单页提取、全网搜索、图文理解、语音播报、脚本生成"等不同任务场景，正确选择并配置对应的图类型，跑通可复用的抓取流水线。

一、什么是 Graph：按任务封装的节点流水线

根据 docs/source/scrapers/graphs.rst 的定义，Graph 是"为解决特定任务而设计的抓取流水线（scraping pipelines）"，由一系列可独立配置的节点（Node）组成，每个节点负责任务的一个环节——抓取数据（FetchNode）、解析内容（ParseNode）、生成答案（GenerateAnswerNode）等。不同的图，本质上是不同节点及其连接关系（边）的组合。

从源码结构看，所有图都继承自 scrapegraphai/graphs/abstract_graph.py 中的AbstractGraph抽象基类，它负责：

• 通过_create_llm()从config["llm"]创建大语言模型实例（abstract_graph.py#L118）；
• 通过set_common_params()将headless、verbose、loader_kwargs、cache_path、timeout（默认 480 秒）等公共参数统一下发给图中所有节点（abstract_graph.py#L88-L97）；
• 通过run()执行self.graph.execute(inputs)，最终从final_state中取出answer。

子类只需实现_create_graph()方法，声明节点的输入输出与连接关系，即可定义一条完整的抓取流水线。types.rst 中所有图都遵循"定义graph_config→ 实例化图类 →run()→print(result)"的统一四步范式，下面逐一展开。

所有图共用一个图配置（graph_config字典）来设置 LLM 模型及其他参数，相关细节可参考 LLM 配置说明 与 图配置说明。此外，所有图的构造器都接受可选的schema参数（PydanticBaseModel子类），用于约束输出结构；若不提供或设为None，输出 schema 将由 LLM 自行生成。

二、SmartScraperGraph：单页 LLM 抓取的基石

SmartScraperGraph是最核心、最常用的图类型：输入一条用户定义的 prompt 和一个 URL（或本地文件路径），由 LLM 从该单一来源中提取所需信息，并以 JSON 格式返回。它也是 SearchGraph、SpeechGraph、OmniScraperGraph 等众多图的基础构建块。

from scrapegraphai.graphs import SmartScraperGraph graph_config = { "llm": {...}, } smart_scraper_graph = SmartScraperGraph( prompt="List me all the projects with their descriptions", source="https://perinim.github.io/projects", config=graph_config, schema=schema ) result = smart_scraper_graph.run() print(result)

从源码 smart_scraper_graph.py#L72-L292 可以看到，其默认流水线为：

FetchNode(抓取HTML) → ParseNode(解析/分块) → GenerateAnswerNode(LLM生成答案)

• FetchNode接收url | local_dir，根据source以http开头还是本地路径自动选择输入键（smart_scraper_graph.py#L67）；
• ParseNode按model_token指定的分块大小切分文档，供 LLM 处理超长页面；
• GenerateAnswerNode结合user_prompt、解析后的文档块与可选schema，生成最终 JSON 答案。

2.1 三种开关：html_mode / reasoning / reattempt

源码中的graph_variation_config字典（smart_scraper_graph.py#L185-L268）展示了该图可配置的三种行为开关，它们决定了节点的增删：

例如默认配置（html_mode=False, reasoning=False, reattempt=False）对应fetch → parse → generate_answer三条边；而三者全开时流水线变为fetch → parse → reasoning → generate_answer → conditional → regen，实现"推理 + 失败重试"的闭环。

2.2 SmartScraperMultiGraph：多源版本

SmartScraperMultiGraph与 SmartScraperGraph 行为类似，区别在于source接收一个 URL 列表，可同时抓取多个来源。其流水线（smart_scraper_multi_graph.py#L72-L98）为：

GraphIteratorNode(对每个URL运行SmartScraperGraph) → MergeAnswersNode(合并结果)

from scrapegraphai.graphs import SmartScraperMultiGraph graph_config = { "llm": {...}, } smart_scraper_multi_graph = SmartScraperMultiGraph( prompt="List me all the projects with their descriptions", source=["https://perinim.github.io/projects", "https://perinim.github.io/cv/"], config=graph_config, schema=schema ) result = smart_scraper_multi_graph.run() print(result)

从文档来看，ScriptCreatorMultiGraph与SmartScraperMultiGraph采用相同的多源设计思路：通过GraphIteratorNode遍历每个来源运行子图，再经MergeAnswersNode汇总答案，因此当你需要同时对多个页面应用同一 prompt 时，应选用 Multi 系列。

三、SearchGraph：只给 prompt，自动全网搜索

SearchGraph是构建在 SmartScraperGraph 之上的多页爬虫：它只需要一条用户 prompt，便会自动构造搜索查询、从搜索引擎抓取前 n 条结果、对每个结果运行一次 SmartScraperGraph，最后合并所有页面的答案并以 JSON 返回。

from scrapegraphai.graphs import SearchGraph graph_config = { "llm": {...}, "embeddings": {...}, } # Create the SearchGraph instance search_graph = SearchGraph( prompt="List me all the traditional recipes from Chioggia", config=graph_config, schema=schema ) # Run the graph result = search_graph.run() print(result)

注意与 SmartScraperGraph 不同，SearchGraph不需要传source，因为它自己搜索。其流水线（search_graph.py#L64-L101）为：

SearchInternetNode(生成搜索词并抓取前n条URL) → GraphIteratorNode(对每条URL运行SmartScraperGraph) → MergeAnswersNode(合并答案)

两个值得关注的实现细节：

• max_results控制搜索引擎抓取的结果条数，默认值为 3（search_graph.py#L48），可通过graph_config["max_results"]调整；
• run()执行后会把本次考虑过的 URL 存入self.considered_urls，并可通过search_graph.get_considered_urls()获取（search_graph.py#L120-L127），便于审计"答案来自哪些网页"。

此外，搜索流程还支持search_engine与serper_api_key配置（search_graph.py#L72-L73），可切换搜索引擎或使用 Serper 服务。

四、SpeechGraph：抓取 + 文本转语音

SpeechGraph基于 SmartScraperGraph 的流水线，在生成文字答案之后追加一步文本转语音（TTS）：输入 prompt 与 URL（或本地文件），输出 JSON 格式的文字答案，同时把答案合成为音频文件保存到本地。

from scrapegraphai.graphs import SpeechGraph graph_config = { "llm": {...}, "tts_model": {...}, } # ************************************************ # Create the SpeechGraph instance and run it # ************************************************ speech_graph = SpeechGraph( prompt="Make a detailed audio summary of the projects.", source="https://perinim.github.io/projects/", config=graph_config, schema=schema ) result = speech_graph.run() print(result)

其流水线（speech_graph.py#L68-L101）为：

FetchNode → ParseNode → GenerateAnswerNode → TextToSpeechNode

关键实现细节：

• tts_model配置键用于指定语音合成模型，源码中通过OpenAITextToSpeech(self.config["tts_model"])构造 TTS 实例（speech_graph.py#L89）；
• output_path指定音频文件保存路径，默认值为output.mp3；run()内部调用save_audio_from_bytes()写入音频文件（speech_graph.py#L114-L118）；
• 若 TTS 未能生成音频，run()会抛出ValueError，方便你排查配置问题。

五、ScriptCreatorGraph：让 LLM 生成抓取脚本

ScriptCreatorGraph的目标不是直接给出提取结果，而是生成一段可复用的 Python 抓取脚本：输入 prompt 与 URL（或本地文件），输出使用指定库（如 BeautifulSoup）编写的爬虫代码。

from scrapegraphai.graphs import ScriptCreatorGraph graph_config = { "llm": {...}, "library": "beautifulsoup4" } script_creator_graph = ScriptCreatorGraph( prompt="Create a Python script to scrape the projects.", source="https://perinim.github.io/projects/", config=graph_config, schema=schema ) result = script_creator_graph.run() print(result)

两个配置要点：

• library：必需配置项（源码中直接以config["library"]读取，见 script_creator_graph.py#L53），指定生成脚本所用的抓取库，例如beautifulsoup4；
• 流水线（script_creator_graph.py#L67-L112）为FetchNode → ParseNode → GenerateScraperNode，其中FetchNode会以script_creator=True模式抓取页面原始 HTML，ParseNode关闭parse_html（保留原始 HTML 供脚本生成参考），GenerateScraperNode再结合 prompt、页面源码与目标库生成完整脚本。

ScriptCreatorMultiGraph与单源版本行为类似，但可同时处理多个来源：同样通过GraphIteratorNode遍历各来源、生成多个脚本后由MergeGeneratedScriptsNode合并，适合需要一次性为多个页面产出抓取脚本的场景。

六、Omni 系列：GPT-4o 时代的图文一体化爬取

随着 GPT-4o 引入，仓库新增了两个多模态图类型，它们不仅能抓取文本，还能爬取页面中的图片并生成文字描述。

6.1 OmniScraperGraph

OmniScraperGraph类似 SmartScraperGraph，但在流水线中新增了图片理解环节，可基于 prompt 提取项目标题、描述以及对应的图片链接与图片描述：

from scrapegraphai.graphs import OmniScraperGraph graph_config = { "llm": {...}, } omni_scraper_graph = OmniScraperGraph( prompt="List me all the projects with their titles and image links and descriptions.", source="https://perinim.github.io/projects", config=graph_config, schema=schema ) result = omni_scraper_graph.run() print(result)

其流水线（omni_scraper_graph.py#L70-L122）为：

FetchNode → ParseNode(输出parsed_doc + link_urls + img_urls) → ImageToTextNode(对图片生成描述) → GenerateAnswerOmniNode(融合文本与图片描述生成答案)

源码要点：

• ParseNode开启parse_urls=True，额外产出页面中的链接与图片 URL（omni_scraper_graph.py#L79-L87）；
• max_images控制最多分析多少张图片，默认值为 5（omni_scraper_graph.py#L56）；
• ImageToTextNode使用OpenAIImageToText模型实例对图片做视觉理解（omni_scraper_graph.py#L89-L96），因此该图通常搭配 GPT-4o 等支持视觉的模型使用。

6.2 OmniSearchGraph

OmniSearchGraph是 SearchGraph 的多模态版本：只需 prompt，即可搜索、抓取搜索结果中的图文内容并输出 JSON。其执行流程为：生成搜索查询 → 抓取搜索引擎前 n 条结果 → 对每条结果运行一次 OmniScraperGraph（同步完成图片理解）→ 合并所有答案。

from scrapegraphai.graphs import OmniSearchGraph graph_config = { "llm": {...}, } # Create the OmniSearchGraph instance omni_search_graph = OmniSearchGraph( prompt="List me all Chioggia's famous dishes and describe their pictures.", config=graph_config, schema=schema ) # Run the graph result = omni_search_graph.run() print(result)

从源码 omni_search_graph.py#L63-L96 可以看到，其结构与 SearchGraph 完全对应，唯一的区别是GraphIteratorNode内部运行的是OmniScraperGraph而非SmartScraperGraph。仓库提供的真实示例 examples/omni_scraper_graph/omni_search_openai.py 给出了完整可运行配置：

graph_config = { "llm": { "api_key": openai_key, "model": "openai/gpt-4o", }, "max_results": 2, "max_images": 1, "verbose": True, }

示例还展示了通过omni_search_graph.get_execution_info()配合prettify_exec_info输出执行信息，便于调试流水线各环节耗时。

七、schema 参数：约束输出的结构化结果

types.rst 反复强调：所有图构造函数都接受可选的schema参数。它接收一个PydanticBaseModel子类，用于定义输出的 JSON 结构；若未提供或为None，schema 将由 LLM 自行推断。

仓库示例 examples/smart_scraper_graph/openai/smart_scraper_schema_openai.py 展示了标准用法：

from pydantic import BaseModel, Field class Project(BaseModel): title: str = Field(description="The title of the project") description: str = Field(description="The description of the project") class Projects(BaseModel): projects: List[Project] graph_config = { "llm": { "api_key": openai_key, "model": "openai/gpt-4o-mini", }, "verbose": True, "headless": False, } smart_scraper_graph = SmartScraperGraph( prompt="List me all the projects with their description", source="https://perinim.github.io/projects/", schema=Projects, config=graph_config, )

schema最终会传递到GenerateAnswerNode/GenerateAnswerOmniNode/MergeAnswersNode等节点的node_config（如 smart_scraper_graph.py#L135-L136），促使 LLM 严格按预定义结构返回结果，避免自由格式输出带来的解析成本。这在实际项目中非常有用：例如将返回结果直接序列化为业务对象的字段，或对接下游数据库入库。

八、图配置参数速查表

所有图共用一套graph_config字典，其中llm为必需键（部分图还需embeddings、tts_model、library）。除 LLM 相关键外，docs/source/scrapers/graph_config.rst 汇总了以下常用参数：

8.1 Burr 集成：可视化抓取流水线

burr_kwargs用于启用Burr——一个开源的状态机应用管理库——提供的本地 Web 可视化界面，可直观看到抓取流水线节点与数据流。启用步骤：

pip install scrapegraphai[burr]

然后运行图形界面：

burr

在graph_config中配置burr_kwargs即可记录图执行过程：

graph_config = { "llm": {...}, "burr_kwargs": { "project_name": "test-scraper", "app_instance_id": "some_id", } }

从源码看（abstract_graph.py#L99-L105），只要检测到burr_kwargs，图会开启use_burr=True；若未显式指定app_instance_id，会自动生成一个 UUID，方便多次运行的日志区分。

8.2 代理轮换：loader_kwargs 实战

通过loader_kwargs["proxy"]可配置代理。仓库免费代理服务基于free-proxy库，可按条件筛选匿名、安全（HTTPS）、指定国家（如意大利）的代理：

graph_config = { "llm": {...}, "loader_kwargs": { "proxy": { "server": "broker", "criteria": { "anonymous": True, "secure": True, "countryset": {"IT"}, "timeout": 10.0, "max_shape": 3 }, }, }, }

若已有自建代理服务器，也可直接指定服务器地址与认证信息：

graph_config = { "llm": {...}, "loader_kwargs": { "proxy": { "server": "http://your_proxy_server:port", "username": "your_username", "password": "your_password", }, }, }

代理相关的底层实现可进一步参考 scrapegraphai/utils/proxy_rotation.py 与测试 tests/utils/test_proxy_rotation.py。

九、选型速查：我应该用哪个 Graph？

十、总结

types.rst 所描述的八种图类型覆盖了 AI 抓取领域最常见的任务形态：SmartScraperGraph是单页提取的基石，SearchGraph把"搜索 + 抓取"流水线化，SpeechGraph打通了"提取 → 语音合成"链路，ScriptCreatorGraph让 LLM 直接产出可复用代码，而 Omni 系列则借助 GPT-4o 的多模态能力把图片理解纳入抓取结果。理解每种图的节点流水线（源码可在 scrapegraphai/graphs/ 目录下逐一查看）与graph_config公共参数，是正确选型、排障与二次定制的基础。进一步阅读可参考 LLM 配置（本地 Ollama 模型、OpenAI/Gemini/Groq/Azure/HuggingFace/Anthropic 等 API 模型）、图配置 以及 examples/ 目录下各图对应的完整示例脚本。

• 网页爬虫
• 人工智能
• AI 应用