claude-seo 集成 Google Cloud Natural Language API 实战指南：用实体、情感与分类信号驱动 E-E-A-T 内容优化-开发者社区

claude-seo 集成 Google Cloud Natural Language API 实战指南：用实体、情感与分类信号驱动 E-E-A-T 内容优化

【免费下载链接】claude-seoUniversal SEO skill for Claude Code. 25 sub-skills + 18 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, backlinks, local SEO, maps intelligence, semantic clustering, e-commerce SEO, international SEO, Google APIs, and PDF/Excel reporting. Optional DataForSEO, Firecrawl, and Banana extensions.项目地址: https://gitcode.com/gh_mirrors/cl/claude-seo

本篇技术指南聚焦 claude-seo 开源仓库中 NLP API 参考文档所讲解的 Google Cloud Natural Language API 集成方案，覆盖实体提取（Entity Analysis）、文档情感分析（Sentiment）、内容分类（Classification）与文本审核（Moderation）四大能力，以及它们如何服务于 E-E-A-T（Experience、Expertise、Authoritativeness、Trustworthiness）评分中的实体覆盖度、内容语气与主题相关性验证。读完本文，你将掌握该 API 的端点路由、配额计价模型、在 claude-seo 中的一键调用方式（/seo google nlp与/seo google entities），以及底层nlp_analyze.py的实现细节与可用性边界。

一、为什么 SEO 工作流需要 Google 自己的 NLP 分析

claude-seo 是一个面向 Claude Code 的通用 SEO 技能仓库，包含 25 个子技能与 18 个子 Agent。在其 seo-google 技能中，NLP 分析被定位为"用 Google 自己的分类体系与实体识别能力增强 E-E-A-T 评分"的引擎：相比第三方爬虫式的内容分析，直接调用 Google 的实体库与知识图谱（Knowledge Graph）元数据，可以得到与搜索引擎自身视角一致的实体覆盖度、内容情感走向与主题归类结果。

对照仓库中的 E-E-A-T 评估框架可以看到，Expertise（专业度）维度的核心信号之一就是"技术准确性、深度与受众匹配"，而 Google NLP 返回的 700+ 分类体系与实体 salience 分数，恰好提供了可量化、可复验的客观证据，供审计流程引用。因此，本模块与 seo-content、seo-audit 等技能形成了"先量化分析、后内容优化"的闭环。

二、双端点架构：v1 实体提取与 v2 全文标注

根据 NLP API 参考文档，claude-seo 的 NLP 集成采用两个不同的 REST 端点：

用途	端点	说明
实体提取	`POST https://language.googleapis.com/v1/documents:analyzeEntities`	返回实体、salience 分数与知识图谱元数据
情感 / 分类 / 审核	`POST https://language.googleapis.com/v2/documents:annotateText`	v2 多特性标注接口，一次请求完成多个分析

鉴权方式：API key 必须放在X-Goog-Api-Key请求头中传递，而不是拼在 URL 查询参数里。这一点在源码中有直接体现——google_auth.py 中的google_api_key_headers()函数统一返回{"X-Goog-Api-Key": api_key}规范请求头，nlp_analyze.py的所有requests.post调用都通过该函数携带凭证。

从源码结构看，之所以实体走 v1、其余特性走 v2，是因为 v1 的analyzeEntities能够稳定返回 Knowledge Graph 的mid（实体 ID）与 Wikipedia 元数据，对实体优化与品牌验证价值更高；而情感、分类、审核在 v2 的annotateText中一次请求即可完成。这一路由策略在 tests/test_nlp_analyze.py 中有专门的测试用例验证：test_entity_extraction_uses_v1_and_other_features_use_v2断言实体请求打到 v1 端点、其余特性请求打到 v2 端点，且 v2 请求体中的features不含extractEntities。

三、四大核心特性与 SEO 用途映射

原文档给出四个可用的分析特性，这里结合 nlp_analyze.py 的 FEATURES 常量表一并说明其内部映射关系：

特性	API 行为	SEO 用途	内部映射键
`extractEntities`	提取人物、机构、地点、事件并给出 salience 分数	主题覆盖深度评估、实体优化	`entities`/`categories`
`extractDocumentSentiment`	文档级 + 句子级情感得分与强度	内容语气评估、品牌情感监测	`sentiment`
`classifyText`	将内容映射到 700+ Google 分类	主题相关性验证、内容定位校准	`classify`
`moderateText`	内容安全 / 审核类目判定	内容质量红旗标记、合规自查	`moderate`

需要特别注意的是源码中的别名设计：categories与classify都映射到classifyText（见 nlp_analyze.py），因此命令行中写--features classify或--features categories效果等价。默认特性集为entities,sentiment,classify，即默认调用会覆盖实体、情感、分类三个维度。

四、实体类型与实体字段详解

原文档列出的实体类型全集为：

PERSON（人物）、LOCATION（地点）、ORGANIZATION（机构）、EVENT（事件）、WORK_OF_ART（艺术作品）、CONSUMER_GOOD（消费品）、OTHER（其他）、PHONE_NUMBER（电话号码）、ADDRESS（地址）、DATE（日期）、NUMBER（数字）、PRICE（价格）。

每个返回的实体包含以下字段：

字段	含义	SEO 解读
`name`	实体文本	可直接对照页面关键主题词
`type`	实体类型（上表枚举）	判断页面是否覆盖"人物 / 机构 / 地点"等权威信号
`salience`	重要性分数（0~1，越高越相关）	实体覆盖深度：核心实体 salience 是否突出
`sentiment`	该实体维度下的情感（score + magnitude）	品牌 / 竞品实体情感正负
`metadata`	Wikipedia URL、MID（Knowledge Graph ID）	品牌实体是否被知识图谱收录、可关联权威来源
`mentions`	实体在文本中的出现次数	重复提及度、实体密度

源码在归一化这些字段时做了一次质量排序：nlp_analyze.py 在收集完实体后按salience降序排列，保证输出中"最重要的实体排在前面"，便于审计 Agent 直接取前 N 条做 E-E-A-T 实体覆盖评估；同时 salience 被四舍五入保留 4 位小数，mention_count取 mentions 列表长度（见 nlp_analyze.py）。

五、情感评分体系：Score 与 Magnitude 的组合解读

原文档对情感评分的核心规则如下：

Score：-1.0（负面）到 +1.0（正面），代表情感极性；
Magnitude：0 到正无穷，代表情感强度，值越大情绪越强烈；
中性内容：score 接近 0、magnitude 低——内容平铺直叙，几乎没有情感表达；
混合内容：score 接近 0、magnitude 高——同一文档中同时存在大量正面与负面表述，是"有争议 / 双面评价"的典型信号。

仓库实现在此基础上进一步加工出可直接消费的结论：nlp_analyze.py 会将 score 以 ±0.25 为阈值划分为positive/negative/neutral三档语气（tone），magnitude 以 0.5 与 2 为界划分为 low / moderate / high 三档情感强度，并拼装出人可读的interpretation描述串；当 API 返回句子级情感时，还会计算sentence_count、most_positive与most_negative，给出文档内部情感波动范围。这比单一文档级 score 更利于内容审计：例如一篇"评分接近 0 但句子级跨度大"的文章，可能意味着论据摇摆、语气不一致。

六、配额与定价模型

原文档给出的计费表（1 unit = 1,000 字符，免费额度按月重置）：

特性	免费额度（每月）	付费（每 1K 字符）
Entity Analysis（实体分析）	5,000 units	$0.001
Sentiment Analysis（情感分析）	5,000 units	$0.001
Content Classification（内容分类）	30,000 units	$0.002
Text Moderation（文本审核）	50,000 units	$0.0005

这意味着：每月约可免费分析 500 万字级的实体 / 情感请求（5,000 × 1,000 字符）。配额相关的异常处理在源码中同样完整——nlp_analyze.py 对 HTTP 403 返回"需在 GCP 控制台启用 API 且项目必须开启结算"的指引，对 429 返回"免费额度为每月 5,000 units"的明确提示，错误信息中还会通过redact_google_api_key()清洗掉可能泄露的 API key。

七、启用 API 与凭证配置（前置条件）

原文档给出的启用步骤为：

打开 Google Cloud 控制台的 API 库页面（APIs & Services > Library）；
搜索 "Cloud Natural Language API"；
点击 Enable 启用；
项目必须开启结算（Billing）——即使使用免费额度，未绑定结算账户的项目也无法调用该 API。

凭证共用说明：NLP 分析与 PSI / CrUX 共用同一个 API key，属于 seo-google 技能中的Tier 0（仅 API Key）能力，即不需要服务账号、不需要 OAuth，配置好api_key即可使用。

完整配置方式见 auth-setup.md：在 GCP 控制台创建 API key 后，写入配置文件~/.config/claude-seo/google-api.json：

{ "service_account_path": "~/.config/claude-seo/service_account.json", "api_key": "<GOOGLE_API_KEY>", "default_property": "sc-domain:example.com", "ga4_property_id": "properties/123456789" }

NLP 只需要其中的api_key字段。也支持环境变量回退：GOOGLE_API_KEY会被 google_auth.py 的 load_config() 作为兜底读取。配置完成后运行python3 scripts/google_auth.py --check校验凭证是否可用。

八、在 claude-seo 中调用：两个开箱即用的命令

seo-google/SKILL.md 为 NLP 分析提供了两个 Agent 命令：

命令	行为	底层脚本
`/seo google nlp <url-or-text>`	完整分析：实体 + 情感 + 内容分类	`python3 scripts/nlp_analyze.py --url <url> --json`或`--text "..."`
`/seo google entities <url-or-text>`	仅实体提取（更快、更省配额）	`python3 scripts/nlp_analyze.py --url <url> --features entities --json`

直接使用脚本时的完整参数（见 nlp_analyze.py main()）：

# 分析一段文本（默认特性：entities,sentiment,classify） python3 scripts/nlp_analyze.py --text "你的正文内容" --json # 分析一个 URL（先抓取页面并抽取正文文本，再做 NLP 分析） python3 scripts/nlp_analyze.py --url https://example.com --json # 自定义特性组合，按需控制配额消耗 python3 scripts/nlp_analyze.py --url https://example.com --features entities --json python3 scripts/nlp_analyze.py --text "..." --features entities,sentiment,classify,moderate --json # 覆盖 API key（不推荐，正常走配置文件） python3 scripts/nlp_analyze.py --text "..." --api-key <KEY> --json

CLI 默认输出为易读的纯文本摘要（=== NLP Analysis ===头、语气标签、Top 15 实体、分类置信度、审核标记），加--json则输出结构化 JSON 供后续报告生成与审计脚本消费。

九、源码实现纵深：URL 分析链与安全边界

analyze_url()的完整调用链（nlp_analyze.py）体现了本仓库一贯的 SSRF 防护与降级策略：

URL 校验：调用validate_url()（底层为 url_safety.py 的实现），只接受指向公网主机的 http/https 地址，拒绝内网 / 回环地址，从源头阻断 SSRF 攻击面；
安全抓取：通过safe_requests_get()抓取页面，携带Mozilla/5.0 (compatible; ClaudeSEO/1.7 NLP Analyzer)的 User-Agent；若命中 SSRF 保护则直接返回错误；
正文抽取：优先使用 BeautifulSoup 移除script、style、nav、footer、header等噪音标签后抽取纯文本；若未安装 bs4 则降级为正则抽取；
长度校验：抽取文本少于 50 字符即判定"不足以做有意义的 NLP 分析"并中止，避免浪费配额；
文本截断：送入 API 的文本被截断到 100,000 字符（nlp_analyze.py），这是 API 单次请求的输入上限。

此外，test_nlp_analyze.py 中的test_entities_only_skips_v2_annotate_text_call验证了"仅实体模式"下只会发出 v1 端点一次请求、完全跳过 v2 调用，这正是/seo google entities命令"更快、更省配额"的底层原因——配额敏感的批量场景下，优先用实体模式做覆盖度粗筛，需要情感 / 分类时再升级到完整模式。

十、与 E-E-A-T 框架的落地衔接

回到本模块的定位——"NLP 分析增强 E-E-A-T 评分"。结合 eeat-framework.md 的评分维度，可将 NLP 输出映射为可执行的审计结论：

E-E-A-T 维度	NLP 信号	审计动作
Expertise（专业度）	实体类型分布 + 分类置信度	核心领域实体是否出现、分类是否精准落在目标主题（而非宽泛大类）
Authoritativeness（权威性）	`metadata`中的 MID / Wikipedia	品牌或核心人物实体是否被知识图谱收录，能否关联权威来源
Trustworthiness（可信度）	情感 score/magnitude + moderation	语气是否稳健一致、是否存在被 moderation 标记的内容风险
内容覆盖深度	salience 排序 + mention_count	页面是否围绕高 salience 核心实体展开，而非实体散乱

一句话实践建议：对每篇重要页面运行/seo google nlp，重点检查"分类置信度是否 ≥ 0.7、Top 实体 salience 是否高度集中、情感 magnitude 是否与内容目标一致"，即可把原本主观的 E-E-A-T 评估变成可复验的量化审计项。

十一、已知边界与排错提示

免费额度：实体 / 情感各 5,000 units/月，分类 30,000 units/月，审核 50,000 units/月；超出后需按量付费，超限会收到 429 错误提示（nlp_analyze.py）；
必须开启结算：即使使用免费额度，GCP 项目未绑定结算账户时调用会返回 403，源码错误信息已明确提示这一前提；
输入限制：单请求文本上限 100,000 字符，超长页面会被截断；正文抽取过短（<50 字符）会被主动拒绝；
凭证层级：NLP 属于 Tier 0，仅需 API key，无需服务账号与 OAuth，是最低门槛的 Google 数据能力之一（详见 SKILL.md 的 Credential Tiers 表）。