Ingested cost_details without a pricing-table model match never populate effective cost – counted in aggregates but rendered as $0.00 in tab

快速结论：当你在 Langfuse v4 项目中通过 OTel / Python SDK 直接写入 cost_details（或 usage_details），但该 observation 的 model 没有匹配到 pricing-table 定义时，成本只落在 provided_cost_details，不会被提升为 effective cost_details，结果在 Observations 表 / Trace 视图中渲染为 $0.00，而 Metrics API、Public API 却已计算该成本。优先排查 observation 的 model 是否命中 pricing-table。

适用环境：Langfuse Cloud（us.cloud.langfuse.com）v4 项目 · Python SDK 4.14.2 · OTel ingestion。其他自托管版本、SDK 版本未在 Issue 中确认。

最快修复方案：升级到修复版本（维护者在 langfuse/langfuse#15717 中说明已修复该问题）。在无法升级前，可优先尝试为对应 observation 设置一个能匹配 pricing-table 的 model，作为临时绕行方案。

注意事项：为 observation 设置 model 只是绕过“promotion 被 model match 门控”的临时手段，并非官方修复；它会改变该 observation 的模型归属展示。Issue 中另提到 Python SDK 对非 generation 类型仍会静默丢弃 usage_details / cost_details 参数（LangfuseTool.update 接受但未设置 OTel 属性），该 SDK 侧问题是否随 #15717 一并修复，Issue 中未明确确认。

问题场景

在 Langfuse v4 项目中使用 Python SDK 4.14.2，通过 OTel ingestion 直接为 observation 写入 cost_details（例如把计量型非 LLM 调用——网页抓取、搜索服务商——的单次成本挂到 tool 类型的 observation 上，使 trace cost = LLM 花费 + 工具花费）。写入后，同一个 observation 在不同界面/接口上的成本呈现不一致：API 和 Metrics 已计入该成本，但 UI 的 Observations 表 / Trace 视图显示 $0.00。

报错原文

Ingested cost_details without a pricing-table model match never populate effective cost - counted in aggregates but rendered as $0.00 in tab

对应 Issue 中给出的 TRPC 响应片段（UI 自身网络请求）如下：

"providedUsageDetails": {"total": 3},
"providedCostDetails": {"total": 0.03},
"usageDetails": {},
"costDetails": {},
"totalCost": 0

原因分析

最可能的原因是：ingestion 阶段只有在 observation 的 model 能匹配到 pricing-table 定义时，才会基于 usage 计算并写入 effective cost_details / usage_details 列。对于没有 model match 的 observation，直接写入的 cost_details 只保留在 provided_cost_details 中，never promoted 为 effective 成本。

这与文档描述相冲突：token-and-cost-tracking 文档称直接 ingest 的 cost_details 会被 “used verbatim and are not affected”。同时不同读取路径行为不一致——Public API（GET /api/public/observations、GET /api/public/traces/{id}）与 Metrics API 会返回/统计该成本，而 UI 的表格读取（TRPC generations.all）未 coalesce provided_cost_details，因此渲染为 $0.00。

Issue 作者用对照实验确认这不是 observation 类型限制：同样的 span 只要 model 命中自定义 pricing-table 定义（model.name + usage_details），effective costDetails 就会计算并在各处正常渲染，说明 promotion 是被 model match 门控的。

环境排查

确认 Langfuse 部署形态与版本：Issue 为 Langfuse Cloud（us.cloud.langfuse.com）v4 项目。
确认 Python SDK 版本：Issue 为 4.14.2。
确认是否使用 OTel ingestion 写入数据。
检查触发问题的 observation 是否设置了 model，以及该 model 是否匹配项目中已定义的 pricing-table 条目。
核对写入的字段：是直接传了 cost_details / usage_details，还是仅依赖自动计算。

解决步骤

先按 Issue 的复现方式确认现象：创建 observation 并直接写入 usage_details 与 cost_details，model 保持不匹配 pricing-table，观察 UI 表格是否显示 $0.00，同时对比 Public API 与 Metrics API 是否返回/计入该成本。
确认该 observation 是否命中 pricing-table：若未命中，则符合 Issue 描述的触发条件。
升级到包含修复的版本（对应 langfuse/langfuse#15717）。
若暂时无法升级，可优先尝试为相关 observation 设置能匹配 pricing-table 的 model（对照实验中该方式可让 effective cost 正常计算并到处渲染）。
若你使用非 generation 类型（如 tool）写入 usage_details / cost_details，注意 SDK 可能静默丢弃这些 kwargs，需单独确认 SDK 侧是否已修复。

验证方法

对同一 observation 交叉比对：Observations 表 / Trace 视图中是否不再显示 $0.00，TRPC 响应中 costDetails / totalCost 是否已填充；同时核对 Public API 的 costDetails、calculatedTotalCost 与 Metrics API 的 sum(totalCost) 是否与表格显示一致。若各界面数值统一，则问题已解决。