企业官网建设流程全解析

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

本篇技术指南以 examples/omni_scraper_graph/README.md 为核心，系统讲解 Scrapegraph-ai 中通用抓取管线 OmniScraperGraph 及其扩展形态 OmniSearchGraph 的完整用法。你将掌握 JSON、XML、HTML、CSV 等多格式数据的统一抽取、网页中图片的自动转文本、自动格式识别与统一 JSON 输出，并学会如何通过一套配置驱动"网页/本地文件抓取"与"互联网搜索 + 多结果聚合"两类实际场景。

一、Omni 系列要解决什么问题

传统爬虫通常针对单一数据格式编写专用解析器：JSON 用json.loads、XML 用 XPath、HTML 用选择器，一旦目标站点改版或换格式，代码就要重写。Scrapegraph-ai 的 Omni 系列管线把"格式差异"交给 LLM 消化，让抓取逻辑与数据格式解耦。

从 scrapegraphai/graphs/omni_scraper_graph.py 的类文档可以看到其定位：

"OmniScraper is a scraping pipeline that automates the process of extracting information from web pages using a natural language model to interpret and answer prompts."

即：用自然语言模型理解页面内容并回答用户提问，从而实现对多种数据格式的通用抽取。官方 README 归纳的四个核心能力为：

• 多格式数据抽取（JSON、XML、HTML、CSV）
• 自动格式识别
• 统一数据输出
• 内容转换（文本与图片描述融合）

二、环境准备与依赖安装

原文档 Setup 部分给出了三步准备流程，展开如下：

2.1 安装依赖

Omni 管线依赖 Scrapegraph-ai 及其底层 LLM 集成组件，项目根目录提供了 requirements.txt 与 requirements-dev.txt。推荐使用项目使用的包管理器：

pip install -r requirements.txt

若要从源码运行示例，需要 Python 环境中包含scrapegraphai包，并确保python-dotenv可用（示例代码通过dotenv加载.env）。

2.2 配置密钥文件

仓库的示例目录并没有附带.env.example，但结合 examples/omni_scraper_graph/omni_search_openai.py 的加载逻辑可知，运行前需要在.env中配置 API 密钥：

# 复制示例模板（如有）或直接创建 cp .env.example .env

2.3 设置 API Key

.env中最核心的变量是：

OPENAI_APIKEY=sk-xxxx

注意示例代码读取的是OPENAI_APIKEY（而非OPENAI_API_KEY），然后通过os.getenv("OPENAI_APIKEY")注入图配置。原文档末尾列出的OPENAI_API_KEY变量名与示例脚本存在差异，从源码实测角度（omni_search_openai.py）应以OPENAI_APIKEY为准；若要沿用OPENAI_API_KEY，需同步修改os.getenv的参数名。

三、快速上手：最小可运行示例

原文档 Usage 给出的最小示例为：

from scrapegraphai.graphs import OmniScraperGraph graph = OmniScraperGraph() data = graph.scrape("https://example.com/data")

需要特别指出两点（以源码为准）：

1. 构造函数没有默认参数。omni_scraper_graph.py 中__init__强制要求prompt、source、config三个位置参数，OmniScraperGraph()空构造会直接报错。
2. 该类没有scrape方法，对外入口是run()；run()在 abstract_graph.py 的子类实现中执行self.graph.execute(inputs)，并从最终状态读取"answer"键。

因此真正可运行的最小写法为：

from scrapegraphai.graphs import OmniScraperGraph omni_scraper_graph = OmniScraperGraph( prompt="List me all the attractions in Chioggia and describe their pictures.", source="https://en.wikipedia.org/wiki/Chioggia", config={"llm": {"model": "openai/gpt-4o"}}, ) result = omni_scraper_graph.run() print(result)

其中prompt是自然语言提问，source可以是网页 URL 或本地目录/文件路径，config是图配置字典（至少包含llm）。

四、GraphConfig 配置详解

Omni 图的核心配置项与对应源码取值如下：

关于模型命名的细节

abstract_graph.py 会解析llm.model：若包含/，则按厂商/模型拆分（如openai/gpt-4o→ provider=openai）；若不含/，则会在内置 models_tokens 表中反查厂商。找不到厂商时会抛ValueError，因此建议始终显式携带厂商前缀。

max_images 的底层行为

max_images同时在图的image_to_text_node生效（omni_scraper_graph.py）。在 image_to_text_node.py 中，当max_images < 1时直接返回空图片描述列表，用于快速关闭图片处理分支。

五、完整示例：OmniSearchGraph 实战

仓库附带的 omni_search_openai.py 演示的是 Omni 系列的搜索形态。它与 OmniScraperGraph 的差异在于：只需一个prompt，无需指定source，管线会先联网搜索再对每个结果执行抓取。

import json import os from dotenv import load_dotenv from scrapegraphai.graphs import OmniSearchGraph from scrapegraphai.utils import prettify_exec_info load_dotenv() openai_key = os.getenv("OPENAI_APIKEY") graph_config = { "llm": { "api_key": openai_key, "model": "openai/gpt-4o", }, "max_results": 2, "max_images": 1, "verbose": True, } omni_search_graph = OmniSearchGraph( prompt="List me all Chioggia's famous dishes and describe their pictures.", config=graph_config, ) result = omni_search_graph.run() print(json.dumps(result, indent=2)) graph_exec_info = omni_search_graph.get_execution_info() print(prettify_exec_info(graph_exec_info))

运行方式：

python examples/omni_scraper_graph/omni_search_openai.py

执行信息查看

示例后半部分展示了两个调试 API：

• get_execution_info()：返回self.execution_info（abstract_graph.py），即graph.execute()产生的执行追踪信息；
• prettify_exec_info：将执行信息格式化为易读文本。

六、OmniScraperGraph 内部节点与工作流

原 README 只给了使用摘要，这里从源码补充完整的管线构成。OmniScraperGraph 在 omni_scraper_graph.py 中构建了一条 4 节点链：

Fetch → Parse → ImageToText → GenerateAnswerOmni

节点分工如下：

输入源自适应

omni_scraper_graph.py 会根据source是否以http开头决定input_key：

self.input_key = "url" if source.startswith("http") else "local_dir"

即：传 URL 走网页抓取，传本地路径走本地目录加载，FetchNode的输入表达式url | local_dir正是为此设计的。

图片转文本的容错处理

image_to_text_node.py 对每张图片执行HumanMessage多模态请求，若请求失败（格式不兼容或模型异常）会回退为字符串"Error: incompatible image format or model failure."，不会中断整条管线。图片模型默认使用 OpenAIImageToText，它是ChatOpenAI的封装，固定max_tokens=256，并请求描述"provided image"。

答案生成的分块策略

GenerateAnswerOmniNode 依据文档块数选择生成策略：

• 单块：直接使用TEMPLATE_NO_CHUNKS_OMNI提示词（generate_answer_node_omni_prompts.py），同时注入页面文本与图片描述；
• 多块：对每个 chunk 用TEMPLATE_CHUNKS_OMNI并行生成中间答案（RunnableParallel），再用TEMPLATE_MERGE_OMNI合并去重，最终统一为 JSON 输出。

三套提示词均要求：找不到答案时输出"NA"，并强制输出合法 JSON。schema存在时，OpenAI/Mistral 走with_structured_output，其他模型走 Pydantic 输出解析器。

七、OmniSearchGraph：搜索 → 抓取 → 聚合

从 omni_search_graph.py 可以看出，OmniSearchGraph 由 3 个节点组成：

SearchInternet → GraphIterator(OmniScraperGraph × N) → MergeAnswers

配置的隔离性设计

omni_search_graph.py 在构造时对config和schema做了深拷贝（safe_deepcopy/deepcopy），避免子图实例间共享可变配置。这一设计被 tests/test_omni_search_graph.py 的两个测试直接验证：修改外部 config 或 schema 不影响内部副本。测试还确认了图结构为 3 节点 2 边、graph_name == "OmniSearchGraph"，以及无答案时run()返回默认字符串"No answer found."。

八、结构化输出：用 schema 约束结果

原 README 提到"统一数据输出"，其实现方式是可选传入 Pydantic schema：

from pydantic import BaseModel class Attraction(BaseModel): name: str description: str omni_scraper_graph = OmniScraperGraph( prompt="List all attractions and describe them.", source="https://en.wikipedia.org/wiki/Chioggia", config={"llm": {"model": "openai/gpt-4o"}}, schema=Attraction, )

传schema后，generate_answer_omni_node.py 会：

• 对ChatOpenAI/ChatMistralAI使用with_structured_output(schema)；
• 其他模型使用get_pydantic_output_parser(schema)生成格式指令。

未传 schema 时则退回JsonOutputParser，输出仍是 JSON 但结构不受约束。

九、从文档/测试佐证到的边界与限制

基于仓库实际内容，使用 Omni 系列需注意：

1. 多格式支持依赖 LLM 理解而非内建解析器：README 宣称支持 JSON、XML、HTML、CSV，源码中实际由ParseNode的 HTML→文本转换（parse_node.py）与 LLM 提示词（TEMPLATE_*_OMNI）共同承担，因此对格式的识别能力受模型能力影响；
2. 图片处理默认开启：max_images默认 5，若不希望触发多模态请求，需显式设max_images: 0；
3. 无答案有兜底：run()在最终状态缺失answer时返回"No answer found."（omni_scraper_graph.py）；
4. 密钥变量名：示例使用OPENAI_APIKEY（omni_search_openai.py），与 README 中的OPENAI_API_KEY不一致，运行时请以实际读取的变量名为准；
5. 浏览器与登录态：headless、storage_state、loader_kwargs会通过 abstract_graph.py 的set_common_params广播到所有节点，用于需要登录或特殊渲染的站点。

十、总结：Omni 管线的定位与适用场景

• OmniScraperGraph：面向"给定 URL/本地文件 + 用户问题"的单源多格式抽取，输出统一 JSON；
• OmniSearchGraph：面向"仅有用户问题"的多源搜索场景，内部复用 N 个 OmniScraperGraph 子图，再合并答案，本质上是搜索图与 Omni 抓取图的组合（omni_search_graph.py）；
• 两者共享同一套llm配置格式、max_images图片处理逻辑与 JSON 输出约定，可参照 scrapegraphai/graphs/init.py 的导出清单按需导入。

若需进一步扩展，可在当前仓库中找到全部相关源码：管线定义在 scrapegraphai/graphs/omni_scraper_graph.py 与 scrapegraphai/graphs/omni_search_graph.py，提示词模板在 scrapegraphai/prompts/generate_answer_node_omni_prompts.py，测试用例在 tests/test_omni_search_graph.py，运行入口在 examples/omni_scraper_graph/omni_search_openai.py。

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