2026 年 Google NLP API 实操：1,000 字符向上取整与定价页没明说的 tier 跳价

让我第一次真正去读 Cloud Natural Language 定价页的是一张账单，对应的是给一个 fintech 客户的客服归档跑的知识库 ingest 管线。计划很简单：把过去三年的所有 closed 工单拉下来，对每个客户的第一条消息跑 analyzeSentiment，把分数存到工单上做趋势分析。一共 140 万条工单，平均长度 350 字符左右，因为开场消息一般都不长。我按 "140 万乘以 $0.0010 / 1,000 字符" 粗算预算约 $400。

实际账单是 $1,316。

如果你是从 "google nlp api" 这类检索词过来的，Cloud Natural Language API 大概率已经在你的候选清单里了，要么你还没真花钱，要么花了发现数字比预期大。这篇要讲的就是定价模型里文档其实讲了、但很少有人在被收费之前真正吃透的几件事：1,000 字符向上取整、按特性独立的免费额度不对称、tier 跳价让不同量级的工作负载经济性差出一个数量级。

"一个 unit" 到底怎么算

定价页说标准特性按 "每 1,000 个 Unicode 字符" 计费。它没用粗体强调的是：每次请求向上取整到下一个 1,000。例子藏在 unit-of-charge 这一节：

"如果你发三个 Sentiment Analysis 请求，分别是 800、1,500 和 600 字符，账单是 4 个 units：第一个请求 1 unit，第二个请求 2 units，第三个请求 1 unit。"

三次请求总共 2,900 字符，按 4,000 字符的量计费。损失 38%。我的工单管线里平均一条工单 350 字符，每条都按完整 1,000 字符的 unit 收，所以单条真实成本是 $0.0010，不是按线性数学算出的 $0.00035，140 万条乘起来就是那张账单。

规则推到所有特性上：

moderateText 用 100 字符的 unit，单次请求的取整损失绝对值小，但触发的频率高。60 字符的评论审核请求向上取整到 100 字符（损失 40%），同样 60 字符的 sentiment 请求向上取整到 1,000 字符（损失 94%）。实际 UGC 流量下，moderation 的成本曲线更贴近理论价格，sentiment 的曲线和理论价差远很多。

免费额度按特性分，而且不对称

定价页把免费额度按特性列成一张表，数字第一眼看着不大，直到你意识到它们不是池化的：

同一份文档既跑 sentiment 又跑 classification 的团队，是分别拿 5,000 sentiment 免费 units 和 30,000 classification 免费 units，不是 35,000 的二选一。一般先撞墙的是 sentiment，因为它最常用、配额最小。classifyText 的 30,000 units 头部空间足够覆盖一个平均文档不超过 1,000 字符的小型内容打标流量；sentiment 的 5,000 calls（按每 call 1 unit 算）在任何真实生产流量下第三天就用完。

这种不对称对第二个决定有影响：要不要用 annotateText 把多个特性 bundle 起来。如果你在 sentiment 上还没超免费额度但 classification 已经超了，一个同时返回两者的 annotateText 请求，sentiment 部分仍然走免费额度，classification 部分按付费费率计费。bundle 不会让你浪费免费额度，但 bundle 也不会让你省钱。

5K 和 30K 处的 tier 跳价

按 tier 分段的定价，在定价页上看着挺合理，只有当你的量过了某一档才会咬人。Cloud Natural Language 每个特性有三档，跳价幅度都不小。

四个标准特性（sentiment、entities、entity-sentiment、syntax）：

classifyText：

moderateText：

最显眼的是 classifyText 从 30K-250K 档（$0.0020）到 5M+ 档（$0.0001）的 20 倍压缩。某团队每月跑 10 万次 classify 当月花 $200，另一个跑 6M 次的团队按 60 倍的量却只花 $600 出头。如果你的 roadmap 里 classify 会迅速上量，单位经济性会随规模站在你这边；如果不会，你就一直按顶档付费率。

另一个实际后果是 当前规模下的边际费率才是 capacity planning 的依据，不是平均值。账单最让人吃惊的团队，往往是按当前量级估了一遍单位成本之后，假设 10 倍量时这个平均费率还成立。

annotateText 是省事，不是省钱

annotateText 一次请求返回多个特性。需要同时拿 sentiment、entities、syntax 的代码路径，可以把三次往返合成一次。延迟（一条 TCP/HTTP/TLS 链路而不是三条）和代码复杂度（一个错误路径而不是三个）这两块确实省下来了。

但成本这块没有。定价页原话：

"一个同时返回 syntactic analysis 和 classification 的 annotateText 请求，和分别调用 syntax 与 content classification 一次的成本相同。"

bundle 不会改变各个 unit 落在哪个 tier，也不会改变每个特性走哪个免费额度。决策规则纯粹是运维的：真的需要 bundled 多个特性、且延迟降低有意义就 bundle；只用一个特性、又想着 "顺便把其他几个也要了" 就不要 bundle。

十五行跑通 analyzeSentiment

用 Python 客户端拿单文档分数的最小 payload：

from google.cloud import language_v2

client = language_v2.LanguageServiceClient()

document = language_v2.Document(
    content="集成过程没什么坑，文档比我想象中清晰。",
    type_=language_v2.Document.Type.PLAIN_TEXT,
    language_code="zh",
)

response = client.analyze_sentiment(
    request={
        "document": document,
        "encoding_type": language_v2.EncodingType.UTF8,
    },
)

print(f"score={response.document_sentiment.score:.2f}")
print(f"magnitude={response.document_sentiment.magnitude:.2f}")
for sentence in response.sentences:
    print(f"  {sentence.sentiment.score:+.2f} | {sentence.text.content}")

这段里三个第一次集成容易踩的点：

1. v2 端点和 v1 并行存在。 Python 包名 google-cloud-language 同时覆盖两版，但客户端类 LanguageServiceClient 在 language_v2 下。v1 还能用；v2 有更新的 classifyText 长文模型和文档语言自动检测。新代码选 v2。

2. encoding_type 必须显式指定，offset 才准确。 不写的话，sentence 和 entity 的 offset 返回的是未指定单位，下游 UI 高亮在多字节文本上会差几个字符。UTF8 是安全的默认值。

3. 认证是隐式的。 客户端自动取 Application Default Credentials。本地跑 gcloud auth application-default login；CI/CD 把 GOOGLE_APPLICATION_CREDENTIALS 指向 service account JSON 路径。客户端不会提示要 API key，因为标准端点根本不接受 API key。

Gemini 什么时候真比 NLP 便宜

Gemini 当了两年 "干嘛不直接用 LLM" 的明显平替，2026 年的答案比早期玩家说的更微妙。对 NLP 覆盖的结构化任务来说，把输出 token 算进去之后，纯成本很少站在 Gemini 这边。

Gemini Flash 大约 $0.075 / 百万 input token、$0.30 / 百万 output token（请在 Gemini 定价页验证当前费率，这些数一直在动）。一个 token 大约是 4 个英文字符。所以 1,000 字符的 input 在 Flash 上约 $0.000019，而 analyzeSentiment 在 5K-1M 档收 $0.0010。纯 input 在那个量级上 Gemini 便宜 52 倍。

但 analyzeSentiment 返回一个大约 60 字节的 score-magnitude 结构体。要让 Gemini 输出同样的结构，你得让它返回 JSON，output 就被撑大了。一个合理的 sentiment JSON 包，把 key、score、magnitude、句级拆解和模型总忍不住加的解释性散文都算上，差不多 100~200 个 output token。按每次请求 150 output token 算，Flash output 成本约 $0.000045 / 次。Gemini 每次总成本来到 $0.000064，5K-1M 档 NLP 每次 $0.0010，依然 Gemini 便宜。

所以纯成本在 sub-1M 量级 sentiment 任务上 Gemini 确实赢。继续选 NLP 的理由：

• 输出 schema 确定。 Gemini 在长尾输入上偶尔会把结构幻觉掉。NLP 每次返回同样的 shape。
• 不用做 prompt 工程。 Gemini 改一次 prompt 就是一次回归风险。NLP 的输入就是文本。
• 延迟可预测。 NLP 的 p99 稳定。Gemini 的延迟随输出长度和当前负载浮动。
• 成本可预测。 NLP 成本只跟输入字符数有关。Gemini 成本看模型决定输出多长，可能会悄悄漂移。
• 合规姿态。 几家企业的合规体系已经把 NLP 批准为结构化数据处理器，但没把 Gemini 批准为同等工作负载的生成式服务。

Gemini 真正赢的场景不是 NLP 也覆盖的场景。是 NLP 根本没端点的那些：开放式文档摘要、超出 classifyText 700+ 类目的自定义分类、单次调用里多步抽取（先提实体、再分类、再总结关系）。

配额、重试和 600 req/min 到底是什么意思

默认项目配额是 600 请求/分钟、800,000/天，单请求 1,000,000 字节上限。这些数字是整个项目、所有 NLP 特性合并算的，不是按特性单独计的。600 RPM 是 token-bucket，所以哪怕一分钟平均没超，短时间内峰值超过 600 / 分钟也会触发 429。

生产设计上两个实际影响：

• 在应用层批量，不是把 payload 塞大。 1MB 单请求上限不会让你省钱，因为账单还是按字符算。1,000 条独立的 400 字符请求和 1 条 400,000 字符的批量请求（假设你正好有这种数据），unit 数一样。批量的理由是让流量形态贴在 600 RPM 上限下面，不是省钱。

• 上线前申请配额上调，不是等 429 来了再申请。 Cloud Quotas console 处理 NLP 配额上调一般几小时到一天，要超过 10 倍的会更久。如果你的上线流量预估稳态超过约 500 RPM，提前一周提工单。

800K/天上限这边的算术是：按 600 RPM 恒定流量算每天 864,000 次请求，所以日配额比分钟配额还紧一点。白天峰值、晚上空闲的工作负载一般撞不上；真正 24/7 稳态的会撞。

上线 100 万 / 天之前的清单

把 Cloud Natural Language 集成从原型推到生产量级前的具体清单：

1. 测一下真实的字符分布。 从实际数据里抽 1,000 条代表性输入，算请求的平均字符长度。乘 1.5 得到保守的 billed-units 估算（多数工作负载会比线性估算多出 30~50%）。

2. 先选对 tier。 如果你的预估量落在 1M-5M 档，按 sentiment $0.000500/unit 算单位经济性，不是 $0.0010。如果落在 1M 以下，按 5K-1M 档算。

3. 按特性组合决定 bundle 还是分开调。 延迟敏感的路径吃 annotateText 的好处。成本敏感的批处理 bundle 不会省，分别调每个特性的专用端点是最便宜的。

4. 在 Cloud Billing 设 50% 和 90% 预算告警。 字符向上取整的惊喜在第一个完整账单周期里最猛。

5. 预估稳态 RPM > 400 就提配额。 给峰值留头部空间。

6. 复用一个 LanguageServiceClient 实例。 客户端管理 gRPC 连接池，每次请求重建会增加延迟、消耗临时端口。

如果你已经过了原型阶段，想看一下相关文本类 API 的清单，API 目录的文本类目页 列出了下手前值得对比的替代品、互补服务和相邻服务。