bug: run_batched_evaluation mapper parameter’s MapperFunction protocol mismatch

问题场景

用户在调用 Langfuse Python SDK 中的 run_batched_evaluation 函数时，自定义的 mapper 参数（即 MapperFunction）无法按预期接收到完整数据，导致函数签名与传入对象类型不匹配。该问题出现在自托管（Self‑hosted）环境中，版本为 v3.150.0。

报错原文

bug: run_batched_evaluation mapper parameter's MapperFunction protocol mismatch
MapperFunction says it needs TraceWithFullDetails for trace level evaluations
but the _fetch_batch_with_retry function in BatchEvaluationRunner uses self.client.api.trace.list,
which returns TraceWithDetails.

原因分析

Langfuse 的 trace‑level 评估路径中，MapperFunction 的类型提示要求输入 TraceWithFullDetails（包含更丰富的信息），但内部 BatchEvaluationRunner._fetch_batch_with_retry 实际调用的是 trace.list 接口，该接口返回 TraceWithDetails 对象，缺少 TraceWithFullDetails 中的字段（如需要额外 client 调用才能获取的信息）。这是一个协议不匹配的 bug，导致用户在 mapper 函数中无法直接获取完整 trace 详情，必须手动拉取 client 补全。

环境排查

• 确认是否为 Langfuse Self‑hosted 或 Cloud（Issue 中为 Self‑hosted，Cloud 可能不受影响）
• 检查 langfuse Python SDK 版本是否为 v3.12 或更高
• 确认 run_batched_evaluation 是否为 trace‑level 评估，而非 observation‑level

解决步骤

1. 参考官方迁移文档：Upgrade trace-level evaluators to observation-level evaluators
2. 在自托管环境中，独立创建 observation‑level evaluator 并配置对应评分规则。
3. 将原本在 trace‑level mapper 中进行的逻辑迁移至 observation‑level evaluator 的评分函数中。
4. 在测试环境中验证新 evaluator 返回正确评分后，再停用旧的 trace‑level evaluator。
5. 如果仍要使用 trace‑level 路径，可暂时在 mapper 中主动通过 client 拉取 TraceWithFullDetails 作为临时 workaround（Issue 报告者已实现此办法，但非官方推荐长期方案）。

验证方法

运行迁移后的 observation‑level evaluator，确认其针对相同输入生成的评分与原有 trace‑level evaluator 一致或符合预期。同时监控 run_batched_evaluation 调用不再抛出类型错误。

参考来源

langfuse/langfuse #12347

AI 工具推荐

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

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

了解 GamsGo AI

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