bug: Dataset run-level cost aggregation shows $0.00 despite individual items tracking costs correctly

快速结论：该报错发生在 Langfuse 数据集运行（dataset run）的总成本聚合时，尽管单个数据集项目（item）和追踪（trace）级别均能正确记录成本，但运行级别始终显示 $0.00。优先排查每个观测（observation）或追踪的 costDetails 中是否缺少 total 字段。

问题场景

用户通过 Langfuse Python SDK 调用 dataset.run_experiment() 时，借助 OpenTelemetry 检测（例如通过 openinference-instrumentation-agno）追踪 LLM 调用成本。所有成本在单个数据集项目（Item）和追踪层面均可正确显示，但在 Langfuse 界面的数据集运行（Run）选项卡中，“Total Cost (avg)” 和 “Total Cost (sum)” 均显示为 $0.00。

报错原文

Total Cost (avg): $0.00
Total Cost (sum): $0.00

原因分析

这是 Langfuse 数据库一个已知行为限制。成本追踪在追踪和观测级别存储时结构完整，但数据集运行级的聚合逻辑要求每个观测或追踪的 costDetails 中包含规范的 total 键。如果成本仅存在于 input、output 等其他键下，或 total 键缺失或命名不正确，则后端聚合和 UI 显示会输出零值。即使底层数据正确，UI 也会显示 $0.00。这是一个系统级问题，与具体的 Langfuse 或 SDK 版本无严格绑定关系，但迁移或数据表关联异常（如字符集问题）可能加剧此现象。

环境排查

Langfuse 实例类型：自托管（Docker）/ 云版本。本次涉及自托管版本 3.129.0。
Python 版本：3.11.9
Langfuse Python SDK：版本 3.9.1
OpenTelemetry 组件：openinference-instrumentation-agno、opentelemetry-exporter-otlp-proto-http
LLM 框架：Agno（通过 OpenTelemetry 检测）
确认数据库迁移：自托管版本升级后，检查所有数据库迁移是否成功执行，排除字符集或链接问题。

解决步骤

验证成本数据结构：检查通过 OpenTelemetry 采集的追踪是否包含 costDetails.total 字段。该字段必须在每个相关观测或追踪中明确设置，示例如下（伪代码）：
```
// 期望的结构（在观察中）
costDetails = {
   "input": ...,
   "output": ...,
   "total": ...   // 必须存在
}
```
如果 total 缺失或命名不规范，则需调整检测逻辑或直接注入计算后的成本。
自定义成本注入：若使用的框架（如 Agno）未自动填充 costDetails.total，可考虑在任务函数中手动添加总成本估值，或使用 Langfuse 的标准 SDK 记录（非仅 OTLP）。
检查是否存在已知关联问题：如果近期升级了 Langfuse 版本，请确保数据库迁移已完全应用，且数据集表无字符集不一致或外键关联问题（参考 #9647）。
测试直接 SDK 写入：作为临时验证手段，可尝试使用 Langfuse Python SDK 直接创建观测（不依赖 OTLP）并明确设置 costDetails.total，确认聚合功能是否正常工作。若解决，则可推断问题限于 OTLP 管道向 costDetails 写入的方式。

验证方法

完成修改并重新执行数据集实验后，进入 Langfuse UI 的数据集详情页面，点击“Runs”选项卡。确认“Total Cost (avg)”和“Total Cost (sum)”现在显示非零且正确的聚合值。同时可检查单个追踪上的成本详情，与运行级别的总和分析是否一致。

参考来源

langfuse/langfuse #10322

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

bug: Dataset run-level cost aggregation shows $0.00 despite individual items tracking costs correctly