如何一次性分析1000条用户评论:xai-cookbook用Grok Batch API提炼产品改进主题
如何一次性分析1000条用户评论:xai-cookbook用Grok Batch API提炼产品改进主题
xai-cookbook 是 xAI 官方维护的 Grok API 实战示例集,其中的 reviews-to-themes 示例专门演示如何用 Grok Batch API 批量分析上千条用户评论:自动提炼出用户抱怨什么、期待什么、喜欢什么,并给出每个主题的出现次数、趋势走向和原始引文——从 1000 条评论到一份产品改进清单,只需一条命令、约 23 美分。
这个示例能帮你解决什么问题 📊
产品经理最头疼的场景:应用上线后积累了上千条 App Store 评论、工单和反馈,想找出"用户到底在骂什么",靠人工逐条看根本不现实。
examples/reviews-to-themes/ 示例把这件事变成了一条流水线:
| 你投入 | 你得到 |
|---|---|
| 一个 CSV 文件(评论文本 + 日期 + 评分) | 按提及量排序的主题榜单 |
| 一条启动命令 | 每个主题的趋势(上升/下降/平稳)与平均评分 |
| 约 0.23 美元 | 可追溯到具体行号的原始引文 |
示例自带一份 sample-reviews.csv:993 条虚构的记账 App 评论,横跨 12 周,其中埋了"银行同步越来越频繁地坏掉""涨价""新规划器受欢迎但伴随崩溃""登录问题已修复"等主题,方便你验证分析结果是否靠谱。
为什么是 Batch API,而不是一条一条地请求 🚀
把 1000 条评论逐条发给模型,会撞上两个硬伤:限流(大批请求触发 429 错误,只能排队等待)和进程中断(终端一关,进度全丢)。
Grok Batch API 一次性解决:
- 不计入速率限制:批量请求在 xAI 服务端排队执行,你的本地进程随时可以关掉;
- 价格折扣:批量模式按折扣价计费;
- 可恢复:Batch 创建后 ID 立即存入
run.json,哪怕进程崩溃、页面关闭,重新运行同一命令就能"接着上次继续",用client.batches.cancel()还能随时取消。
源码里这个提交动作只有几行:把请求写成 JSONL 文件 → client.files.upload() 上传 → client.batches.create({ input_file_id }) 启动,见 themes.ts#L270-L284。
💡 小细节:默认使用支持批量的
grok-4.3做打标。最强的grok-4.7不支持批量(会报 "Model grok-4.7 is not supported for batch processing"),选中它时应用自动切换为 live 模式,8 个请求并发发出。
三步 Map-Reduce:1000 条评论如何变成主题榜单
核心逻辑在 themes.ts 的 analyze() 中,是一个经典的分治思路:
① 采样发现:150 条评论找出候选主题
grok-4.7 从整个时间段里均匀抽取 150 条评论(保证"最近才出现的新问题"也能被采样到),流式输出候选主题清单。每个主题带 ID、名称和"什么话才算数"的判定标准,最多 15 个。
② 批量打标:每 25 条一个请求,40 个请求一次提交
每 25 条评论打包成一个打标请求,JSON Schema 里每条评论占一个必填属性(漏不掉任何一条),主题 ID 用 enum 约束(不会出现瞎编的主题)。993 条评论 ≈ 40 个请求,全部写进一个 JSONL 文件提交批量任务。
轮询结果时每 3 秒检查一次,哪条完成读哪条,而不是傻等整批结束,见 themes.ts#L287-L321。
🎓 省 token 技巧:Schema 本身也占输入 token。源码让 40 条引用的定义通过
$defs共享一份,把每个请求的输入 token 从约 3900 砍到 1600。
③ 合并命名:reduce 出最终榜单
所有评论打标完成后,把"每个候选主题的计数 + 代表性引文"交给 grok-4.7,合并实为同一问题的候选项,起一个自然的名字(如 "Checkout fails on Android")。最后按周统计每个主题的评论数,对比前后各 4 周得出趋势。
| 步骤 | 模型 | 请求数 | 作用 |
|---|---|---|---|
| 发现候选主题 | grok-4.7 | 1(流式) | 从 150 条采样里找出主题 |
| 全量打标 | grok-4.3 | 约 40 个(批量) | 给每条评论贴主题标签 |
| 合并命名 | grok-4.7 | 1(流式) | 输出最终主题榜单 |
最快上手:安装与运行 🛠️
前提:Node.js 22.13+,并在仓库根目录的 .env 中配置 XAI_API_KEY。如果还没有仓库,先克隆:
git clone https://gitcode.com/gh_mirrors/xa/xai-cookbook
然后进入示例目录安装并启动:
cd examples/reviews-to-themes/typescript
npm install
npm run web
打开 http://localhost:3000 ,点击 Run on the sample 即可对内置样本跑一遍。页面顶部是三步进度条:候选主题逐个浮出、已打标评论数滚动增长,完成后主题按提及量排序展示,点击任一主题可查看其逐周分布和背后每一条评论。
更喜欢终端?直接:
npm start -- reviews.csv
加 --model 换打标模型,加 --live 改为实时请求,加 --new 重跑。
如何准备你自己的评论 CSV 📝
把自己的数据整理成 CSV 即可,列名宽容度很高:
| 用途 | 可识别的列名 | 说明 |
|---|---|---|
| 评论文本(必填) | text / review / body / comment / content / message / feedback |
至少要有这一列 |
| 日期(可选) | date / created_at / created / submitted_at / timestamp |
有日期才会输出趋势 |
| 评分(可选) | rating / stars / score |
有评分才会输出主题平均分 |
Web 端通过 /api/uploads 上传你的 CSV 后开始运行,页面关闭也不会杀掉服务端批量任务——下次打开页面它会主动询问是否接着上次的 Batch 继续,见 server.ts。
输出结果与成本 💰
每次运行在 output/<文件名>/ 下保存三样东西:
themes.md:人类可读的主题报告,含占比、趋势、引文与行号;themes.json:机器可读的完整结果,可直接喂给下游工具;reviews.csv:每条原始评论 + 它被贴上的主题,方便抽查验证。
真实跑一次样本(993 条评论):耗时 1~3 分钟,成本约 0.23 美元,绝大部分花在全量打标环节。Batch 结果里的费用以 cost_in_usd_ticks 报告(100 亿 ticks = 1 美元),页面上会直接显示本次运行花了多少钱。
如何迁移到你自己的产品 🚀
这个示例的每一步都可以直接照搬,建议按此顺序落地:
- 先用小样本试:抽 150 条跑"发现候选主题",确认主题粒度合适(一个评论涉及两个问题就计两个主题);
- 再全量打标:把批量任务跑起来,关掉终端也不影响;
- 按趋势排优先级:趋势上升的主题(比如"银行同步坏得越来越频繁")优先修,平稳的排后;
- 用引文做验收:每个主题都带着可回溯到行号的原文,汇报给团队时最有说服力。
写在最后
xai-cookbook 里的 reviews-to-themes 示例,把"上千条评论 → 产品改进主题"这件脏活累活压缩成了一条可恢复、可取消、成本透明的 Batch 流水线。想要动手,从 npm run web 开始,五分钟内就能看到你数据的主题榜单。仓库里还有 meeting-to-action-items、x-sentiment-tracker 等更多同类实战示例,值得顺藤摸瓜看一遍。

