为什么我们对每一次 LLM 调用都做缓存——dossier 背后的成本账

引发这次改造的审计

操作员反馈只有两句话：「请求返回的 overview 要落库，避免每次请求，造成浪费。 其他的所有文案如果是有调用 LLM 进行转换的，都要落盘」。 我们于是在 repo 里 grep call_llm + generateText。八个 LLM 驱动的功能。六个已经 缓存了。两个没有。

已缓存（不动）

• kol_overview——DBKolOverviewSummary，30 天
• kol_background——DBKolBackgroundResearch，30 天
• kol_deep_overview——DBKolDeepOverview，7 天
• kol_activity——DBKolActivitySummary，24 小时
• translate——直接写 bio_zh / display_name_zh / category_zh 到 author 列；每个 author 每个字段只跑一次
• 4 张 insight 卡——通过 insight_* 服务写入 DBSearchInsight

新增缓存

• kol_outreach——新表 kol_outreach_drafts（migration 013），30 天， locale 关卡
• kol_audience_insights——新表 kol_audience_insights（migration 013），30 天， locale 关卡 + snapshot hash 关卡

每个功能三种调用形态

每个被缓存的 LLM 功能都暴露同样的三个入口，调用层（HTTP 路由、MCP 工具、调度器）按需挑：

1. read_cached(...)——绝不调 LLM。miss 返回 None。用于仅读缓存的场景，比如 watchlist 的品牌匹配度星级。
2. get_or_generate(...)——cache-first。miss 或 过期时才调 LLM。
3. regenerate(...)——一定调。对应 UI 的 Refresh 按钮 + ?refresh=true query。

把 locale 当成一等缓存 key 维度

2026 年 5 月给 dossier 加 zh-CN 时暴露出一个微妙的缓存 bug： zh-CN 用户来请求时被一行英文旧缓存命中了，要点 Refresh 才会 重生成。所以我们把 locale 写进缓存行的 JSON payload，_read_cached 现在把 locale 不匹配视作 miss。

向下兼容：上线前的旧行没有 locale 字段，默认按 "en" 处理。英文用户的旧缓存继续服务英文 请求——只有新增语言需要一次新鲜生成。

Snapshot hash 关卡（仅 audience insights）

audience insights 是异类：输入是操作员可以重新跑的抽样粉丝 快照。我们写入时把 snapshot dict 做 SHA-256；读取时如果调用方 给的 snapshot hash 跟缓存行不一致，自动失效——不需要手动 Refresh。

扣费在路由层，不在服务层

服务层不知道 credits 这回事。路由层先调 charge()（workspace 池 → 个人兜底），成功之后 才进 regenerate 路径。AI Gateway 在 debit 之后返回 503 时， 路由当即把 workspace 那一半退掉。

为什么拆开：缓存行只该在「操作员被计费 AND LLM 返回有效 内容」的双成立后才存在。两阶段提交在重试下会死锁；先扣后退 的模式更简单，也匹配 /api/scrape 已有的做法。

每个 workspace 实际的 LLM 花费

数量级估算，按每周打开 50 张 KOL dossier 的 workspace 计：

• 改造前：50 次 dossier 打开 × 页面上 2 张 LLM 驱动的卡 = 约 100 次 LLM 调用 / 周
• 改造后：第一周 50 次首生成，之后每周约 5-10 次刷新
• 稳态下降 5-10 倍；第一周一样高，因为啥都没缓存

Deep Analysis（5 credits、按钮显式选择）这一档不变—— 那一档本身就是要有意识地点的。