作业14：Langfuse 跟学 · 字段规范 · Top10 Token · 告警草稿（动手 + Cursor）

作业目标：安装（或使用现成）Langfuse 并逛遍 Trace / Generation / 成本相关视图；落实统一字段规范；用 Cursor 写出从导出 JSON/CSV 汇总「昨日 Top10 烧 Token 应用」的脚本；起草 3 条告警规则（先 Markdown）。

验收标准：

1. UI 截图或文字记录：能指出 Trace、Generation、Token/成本入口

2. 能默写/对照本作业 8 个规范字段

3. 脚本对样本或真实导出跑出 Top10 CSV/MD

4. 3 条告警规则草稿完整（条件/级别/动作）

环境：本环境已有 Langfuse http://192.168.110.207:3000（详见部署教程）；无环境者可按官方 docker 自建。

HTML：docs/html_cursor/作业14_Langfuse字段规范与Token成本_cursor.html

脚本：scripts_cursor/作业14_Langfuse字段规范与Token成本/

结果：data/homework14/

告警草稿：docs/md_cursor/作业14_告警规则草稿_Token错误延迟_cursor.md

目录

1. 做完长什么样
2. 学习路线
3. Part A · 安装与逛 UI
4. Part B · 字段规范
5. Part C · Cursor 任务：昨日 Top10
6. Part D · 三条告警规则草稿
7. 完整程序与样本
8. 验收清单

做完长什么样

学习路线

A  打开 Langfuse → 认门（Trace / Generation / 成本或用量）
B  背熟字段规范，对照一条真实 Trace 填表
C  导出 JSON/CSV（或用样本）→ 跑 Top10 脚本
D  用 Cursor 自己写一版汇总脚本（可对照仓库实现）
E  写/读 3 条告警规则草稿

Part A · 安装与逛 UI

A1. 本环境（已安装则跳过安装）

• 地址：http://192.168.110.207:3000
• 部署说明：Langfuse_部署教程_cursor
• 与 Dify 联调：Langfuse_连接Dify专题_cursor、作业3

健康检查：

curl -sS http://192.168.110.207:3000/api/public/health

A2. 若从零安装（自备机器）

按官方 Docker Compose 自托管即可（注意与 Dify 端口错开；本环境用 :3000）。装好后创建 Project、拿 PK/SK。

A3. 逛一遍（必做，写下你看到的路径）

在 UI 中依次打开并用自己的话记一行：

Langfuse 大版本 UI 文案可能不同：找不到「成本」时，到 Project → Metrics / Dashboard / Usage 近义入口即可，作业认「能量化 Token」的页面。

A4. 造一条数据（可选）

对已开 Tracing 的 Dify Agent 问一句，然后在 Traces 里找到它（作业3 已验收过工具 Span 更佳）。

Part B · 字段规范

B1. 强制字段（上报与导出都应对齐）

B2. 建议扩展

B3. 对照练习

打开任意一条 Trace，按下表抄写（交作业可贴此表）：

trace_id:
session_id:
model:
prompt_tokens:
completion_tokens:
tool_name:
latency_ms:
error_type:
app_name:

Part C · Cursor 任务：昨日 Top10

C1. 准备数据

方式 1 · 练习样本（推荐先跑通）：

python scripts_cursor/作业14_Langfuse字段规范与Token成本/hw14_01_生成练习样本.py
python scripts_cursor/作业14_Langfuse字段规范与Token成本/hw14_02_昨日Top10烧Token.py \
  --input data/homework14/sample_export.json

方式 2 · 真实导出：

1. Langfuse UI 导出 Traces（JSON/CSV，按你版本菜单操作）
2. 保存到 data/homework14/export_yesterday.json
3. 执行：

python scripts_cursor/作业14_Langfuse字段规范与Token成本/hw14_02_昨日Top10烧Token.py \
  --input data/homework14/export_yesterday.json \
  --date 2026-08-26

无时间戳的练习数据可加：--include-missing-ts。

C2. Cursor 提示词（可复制，自己生成一版）

用 Python3 标准库写脚本：
- 读取 Langfuse 导出的 JSON 或 CSV
- 字段兼容：trace_id/traceId, session_id/sessionId, model,
  prompt_tokens/promptTokens, completion_tokens/completionTokens,
  tool_name, latency_ms, error_type, app_name（或 metadata.app_name / tags 里 app:xxx）
- 筛选「昨天」记录（可传 --date YYYY-MM-DD）
- 按 app_name 汇总 total_tokens，输出 Top10
- 打印表格，并写 CSV + Markdown 到 data/homework14/

C3. 期望输出

终端类似：

=== 昨日 Top10 烧 Token 的应用 ===
rank app_name                    total_tokens   traces  errors
1    客服助手                           ....      ..      .
...
[OK] data/homework14/top10_tokens_YYYYMMDD.csv

Part D · 三条告警规则草稿

完整表格见：作业14_告警规则草稿_Token错误延迟_cursor.md

摘要：

1. 日 Token 突增：某应用当日 Token ≥ 昨日 3 倍且 ≥ 5 万 → P2 成本告警
2. 错误率升高：5 分钟 error_type 非空占比 ≥ 5%（样本≥20）→ P1/P2
3. 延迟恶化：15 分钟 latency_ms P95 ≥ 15s → P2（≥60s → P1）

先写在 Markdown；有监控后再迁到 Alertmanager / 值班机器人。

完整程序与样本

验收清单

• [ ] 能说明 Trace / Generation / 成本（或 Usage）在 UI 的入口
• [ ] 8 个规范字段能对照一条真实或样本 Trace 填完
• [ ] hw14_02 对 sample_export.json 跑通并生成 Top10 文件
• [ ] （加分）用 Cursor 自写脚本，结果与仓库版 Top10 应用名大体一致
• [ ] 3 条告警规则含：条件、窗口、级别、动作

与其它作业关系