AutoGPT 中的 DataForSEO Related Keywords Block：语义关键词发现与 SEO 指标提取实战指南

导读

本文基于 related_keywords.md 文档，深入讲解 AutoGPT Platform 中基于 DataForSEO Labs Google 相关关键词 API 构建的两个 Block：Data For Seo Related Keywords（获取语义相关关键词及其搜索指标）与 Related Keyword Extractor（将复合关键词对象拆解为独立字段）。读者将掌握这两个 Block 的完整输入输出契约、depth 深度参数的扩展规律、RelatedKeyword 对象结构，以及它们背后的 API 调用、认证与成本核算实现。

---

1. 概览：DataForSEO 集成在 AutoGPT Platform 中的定位

DataForSEO 是一类专注于 SEO 与 SERP（搜索引擎结果页）数据的第三方服务。在 AutoGPT Platform 的可视化 Agent/Graph 编辑器中，DataForSEO 相关能力被封装为若干可拖拽节点 Block。它们位于仓库的 blocks/dataforseo 目录，共包含 4 个文件：

文件	职责
related_keywords.py	相关关键词发现 + 字段提取两个 Block（本文核心）
keyword_suggestions.py	关键词建议 Block（姊妹功能，见 keyword_suggestions.md）
_api.py	共享的异步 HTTP API 客户端 DataForSeoClient
_config.py	供应商注册、凭证定义与成本配置

在 Block 分类体系上，Data For Seo Related Keywords 被归类为 SEARCH（"searches or extracts information from the internet"）与 DATA（"interacts with structured data"）两个类别（见 blocks/_base.py 中 BlockCategory 枚举），而 Related Keyword Extractor 仅属于 DATA 类，因为它的作用纯粹是对结构化对象做字段拆分。

---

2. Data For Seo Related Keywords：获取语义相关关键词

2.1 它是什么

该 Block 调用 DataForSEO Labs 的 Google 相关关键词接口，基于一个种子关键词（seed keyword）查找与其语义相关的一组关键词。与精确匹配或拼写变体不同，它返回的是共享相似搜索意图或主题相关性的关键词集合，例如在仓库内置测试中，种子词 content marketing 会命中 content strategy 这类相关词（源码见 related_keywords.py）。

2.2 工作原理与数据流

从源码 run() 方法（related_keywords.py）可以还原出完整的执行链路：

1. 使用当前节点的凭证构造 DataForSeoClient；
2. 调用 _fetch_related_keywords() 转发至 client.related_keywords()（该方法封装了对 DataForSEO 的 HTTP 请求，见下一节）；
3. 将 API 返回结果中每个 item 的 keyword_data 映射为 RelatedKeyword 结构化对象，逐个 yield "related_keyword"，同时累积成列表；
4. 依次输出 related_keywords（完整列表）、total_count（数量）、seed_keyword（回显查询词）；
5. 任意异常被捕获后输出 error 字段。

其中 depth 参数控制检索广度：深度越高，返回的相关关键词数量近似指数增长。文档给出的对应关系为：

depth	返回关键词数量（约）
0	1 个
1	~8 个
2	~72 个
3	~584 个
4	~4680 个

除关键词本身外，结果还附带搜索量、竞争度等指标，并可（按需）返回 SERP 与点击流（clickstream）信息。注意 depth 与下文 limit 需要配合理解：depth 决定候选池的大小，limit 决定实际返回的上限。

2.3 输入参数（含默认值）

原文档输入表如下，本文结合 Block 的 Input Schema 定义 补充了源码中实际生效的默认值与约束范围：

输入	说明	类型	必填	源码默认值 / 约束
keyword	用于查找相关关键词的种子关键词	str	是	无默认
location_code	目标市场地区代码（如 2840 代表美国）	int	否	默认 2840（USA）
language_code	语言代码（如 'en' 英语）	str	否	默认 'en'
include_seed_keyword	结果中是否包含种子词本身	bool	否	默认 True
include_serp_info	是否包含 SERP 信息	bool	否	默认 False
include_clickstream_data	是否包含点击流指标	bool	否	默认 False
limit	最大返回结果数	int	否	默认 100，范围 1~3000（ge=1, le=3000）
depth	关键词搜索深度	int	否	默认 1，范围 0~4（ge=0, le=4），数量增长见 2.2 表格

需要说明：原文档输入表中 location_code、language_code 等未标注默认值，但在实际实现中它们均带默认值。因此在构建工作流时可只填 keyword 一项即可运行（仅需补充凭证）。

另有一个不在文档输入表中、但对运行必需的隐式输入：credentials。它由 _config.py 中的 dataforseo.credentials_field 生成，以用户名/密码形式接入，映射到环境变量 DATAFORSEO_USERNAME 与 DATAFORSEO_PASSWORD。

2.4 输出参数

输出	说明	类型
error	操作失败时的错误信息	str
related_keywords	携带指标的相关关键词列表	List[RelatedKeyword]
related_keyword	单个相关关键词对象（流式逐个输出）	RelatedKeyword
total_count	实际返回的相关关键词总数	int
seed_keyword	查询所使用的种子关键词（回显）	str

其中 RelatedKeyword 是贯穿本模块的核心数据对象（schema 定义见 related_keywords.py），其字段如下：

字段	说明	类型
keyword	相关关键词文本	str
search_volume	月搜索量	Optional[int]
competition	竞争度（0~1）	Optional[float]
cpc	单次点击成本（美元）	Optional[float]
keyword_difficulty	关键词难度分	Optional[int]
serp_info	该关键词的 SERP 数据	Optional[Dict[str, Any]]
clickstream_data	点击流指标	Optional[Dict[str, Any]]

需要重点理解 serp_info 与 clickstream_data 的取值规则：源码在映射结果时（related_keywords.py）会检查输入开关 include_serp_info / include_clickstream_data，只有对应开关为 True 时才会从 API 响应中提取并填充这两个字段，否则一律置为 None。因此要拿到这两类增强数据，必须在调用方明确开启开关。

2.5 典型应用场景

原文档归纳了三类核心用法：

• 主题聚类（Topic Clustering）：将语义相关关键词归组，围绕一个主题构建完整的内容集群；
• 语义 SEO（Semantic SEO）：发现 LSI（潜在语义索引）关键词，提升内容与查询意图的匹配度、增强内容相关性；
• 关键词扩展（Keyword Expansion）：把投放/写作目标从精确匹配扩展到更广的相关搜索流量。

这三者本质都依赖于"相关关键词 = 同一搜索意图下的词群"这一核心能力。

---

3. 底层实现：DataForSeoClient 的 API 调用链

Block 本身不含任何 HTTP 逻辑，实际网络请求全部收敛到 _api.py 中的 DataForSeoClient，这既便于复用（keyword_suggestions 与 related_keywords 两个 Block 共享同一客户端），也便于测试替身（mock）。

3.1 认证：Basic Auth

DataForSEO 使用 用户名:密码 的 Basic 认证。客户端从 UserPasswordCredentials 中取出秘密值，做 ASCII 编码与 Base64 后放入 Authorization 头（_api.py）：

credentials_str = f"{username}:{password}"
encoded = base64.b64encode(credentials_str.encode("ascii")).decode("ascii")
return {
    "Authorization": f"Basic {encoded}",
    "Content-Type": "application/json",
}

3.2 请求与响应处理

related_keywords() 方法（_api.py）的实现要点：

• 请求端点：向 DataForSEO API 的 /v3/dataforseo_labs/google/related_keywords/live 端点发起 POST，请求体为包含单任务的 JSON 数组；
• 载荷构建：payload 仅组装非 None 参数，避免向服务端发送冗余空值字段；
• 双层错误处理：第一层检查 HTTP 状态码（非 200 时抛出带 status_message 的异常）；第二层检查任务级 status_code，DataForSEO 约定 20000 为任务成功码，否则抛出 DataForSEO task error 异常；
• 成本回填：任务成功时从响应 task.cost 中读取本次调用的美元成本并暂存到 client.last_cost_usd。

3.3 成本与积分结算

Block 的 run() 在拿到结果后，会将 last_cost_usd 通过 merge_stats(NodeExecutionStats(provider_cost=..., provider_cost_type="cost_usd")) 汇入节点执行统计，供平台的 COST_USD 计费解析器在结算时按真实供应商花费抵扣。

对应的计价规则在 _config.py 中定义为：with_base_cost(1000, BlockCostType.COST_USD)——即 1 美元成本折算为 1000 平台积分；DataForSEO 标准档大致按每个返回关键词 ~$0.001 计费，因此约合每个关键词 1 积分。这意味着该 Block 的实际消耗不是固定值，而是与调用成功与否、返回数据量挂钩的可变成本，需要在设计高频 Agent 时加以考量。

---

4. Related Keyword Extractor：复合对象字段拆分

4.1 它是什么

Related Keyword Extractor 接收 Data For Seo Related Keywords（或任何上游）产生的 RelatedKeyword 对象，将其从单一复合对象中分离为多个独立的输出端口，便于工作流后续节点直接消费单一字段。

4.2 输入与输出

该 Block 的输入极简（完整定义见 related_keywords.py）：

输入	说明	类型	必填
related_keyword	需要拆分的相关关键词对象	RelatedKeyword	是

输出覆盖该对象的所有字段，外加统一的错误通道：

输出	说明	类型
error	操作失败时的错误信息	str
keyword	相关关键词文本	str
search_volume	月搜索量	int
competition	竞争度（0~1）	float
cpc	单次点击成本（美元）	float
keyword_difficulty	关键词难度分	int
serp_info	该关键词的 SERP 数据	Dict[str, Any]
clickstream_data	点击流指标	Dict[str, Any]

从实现看，它的 run() 只是把对象各属性逐一 yield 出来（related_keywords.py），不做任何计算或网络调用，是一个纯数据整形节点。这也解释了它为何归属 DATA 类目——它的定位是图工作流中的数据管道组件。

4.3 典型应用场景

• 关键词优先级排序（Keyword Prioritization）：抽出指标字段，在后续逻辑 Block 中按机会评分（如结合搜索量与低竞争度）对候选词排序；
• 内容优化决策（Content Optimization）：直接读取 keyword_difficulty 与 search_volume，判断内容选题的性价比；
• 竞争分析（Competitive Analysis）：使用 competition 与 cpc 评估关键词投放可行性，服务于 SEO 与 PPC 双重策略。

---

5. 在图中组合使用：建议链路与验证机制

5.1 推荐的串联方式

结合两个 Block 的设计意图，一个典型的"种子词 → 相关词 → 指标筛选"链路可以这样搭建：

1. 输入：以常量或上游输出提供种子关键词（如 content marketing）；
2. Data For Seo Related Keywords：配置 location_code=2840、language_code=en、适度 depth（如 2）+ limit 上限，按需开启 include_serp_info / include_clickstream_data；
3. Related Keyword Extractor：把每一个流出的 related_keyword 对象拆成字段；
4. 下游处理：接入文本/逻辑类 Block 按 search_volume ≥ X 或 keyword_difficulty ≤ Y 过滤，或接表格/数据库类 Block 沉淀关键词清单。

5.2 内置测试与 Mock 验证

两个 Block 都携带完整的自测夹具（定义于 Block 构造参数中），可作为理解预期行为的规范样例：

• Data For Seo Related Keywords 的 test_input 使用 keyword="content marketing"、limit=1，其 test_output 断言 related_keyword.keyword == "content strategy"、related_keywords 长度为 1、total_count == 1、seed_keyword 回显正确；test_mock 则模拟了 API 返回（包含 search_volume: 8000、competition: 0.4、cpc: 3.0、keyword_difficulty: 45 的样例载荷），通过拦截 _fetch_related_keywords 实现离线验证（related_keywords.py）；
• Related Keyword Extractor 的测试则直接构造一个 RelatedKeyword 样例，断言 7 个输出字段与对象字段逐一对齐、且 serp_info / clickstream_data 在未请求时输出 None（related_keywords.py）。

把测试数据中 mock 的 JSON 结构与 2.4 节的 RelatedKeyword 字段对照，就能直观看到"DataForSEO 返回的 keyword_info / keyword_properties 原始字段 → 结构化对象字段"的映射关系：keyword_info.search_volume → search_volume、keyword_info.competition → competition、keyword_info.cpc → cpc、keyword_properties.keyword_difficulty → keyword_difficulty。

---

6. 使用前置条件与注意事项

1. 凭证：必须先在平台配置 DataForSEO 账号的用户名/密码（服务端对应读取环境变量 DATAFORSEO_USERNAME / DATAFORSEO_PASSWORD，见 _config.py），并确保账号对 DataForSEO Labs 产品有可用配额；
2. 地区与语言：location_code、language_code 需要与目标市场匹配，不同地区的搜索量、竞争度、CPC 数据差异很大；2840 与 'en' 仅代表美国英语市场；
3. depth 与 limit 的量级意识：depth=4 理论候选近 4680 词，即便用 limit 截断，API 侧的计算量也可能高于低深度调用，应结合实际预算（见 3.3 的成本模型）选择参数，避免高频 Agent 产生意外花费；
4. 增强数据的代价：include_serp_info、include_clickstream_data 会显著增加单任务返回体量与（通常伴随的）接口费用，默认关闭即为控制成本的保守选项；
5. 错误通道：凭证错误、配额耗尽、参数非法都会体现为 error 输出，工作流设计中应预留错误分支，而不是默认输出端口始终有值。

7. 参考文件

• 本文依据的集成文档：related_keywords.md
• 姊妹功能（关键词建议）文档：keyword_suggestions.md
• Block 实现：related_keywords.py
• API 客户端：_api.py
• 凭证与成本配置：_config.py
• Block 分类枚举定义：blocks/_base.py