大多数评估LLM应用程序的团队都面临着一团糟的局面。人类注释散落在一个电子表格中。LLM作为裁判的评分则藏在某个脚本输出中。用户反馈被丢弃在无人问津的仪表板上。而程序化检查则在CI中运行，但无人将它们与其他信号关联起来。

Langfuse 的评估系统有一个设计决策，它能够解决这个问题：每项质量判断都转化为一个评分。人类注释、LLM裁判输出、正则表达式检查、用户给出的差评——它们都会产生相同的数据对象。相同的结构、相同的分析、相同的仪表板。

这听起来很简单，但它改变了下游的一切。

评分实际上是什么

Langfuse 中的每项评分都有四个属性：名称（如“正确性”）、值、数据类型和可选的注释。

数据类型包括数值（0.9）、分类（“正确”/“部分正确”）、布尔值（通过/未通过）和文本（自由格式的笔记）。数值用于连续判断。分类用于离散标签。布尔值用于二元检查。文本用于后续正式化的定性反馈。

评分可以附加到跟踪、观察、会话或数据集运行中。最常见的用法是附加到跟踪——一个完整的端到端交互会被打分。

重要的是：评分可以在任何时候添加。与标签不同，标签描述了事物是什么并且在跟踪后是不可变的，评分衡量事物的好坏，并且可以在几个小时、几天或几周后添加。你可以对上周的生产流量运行新的LLM作为裁判评估器，从而在旧的跟踪上获得新的评分。

五种创建评分的方法

LLM作为裁判——一个LLM根据评分标准评估输出。你定义标准，从跟踪中映射变量（输入、输出、元数据通过JSONPath），裁判产生结构化的评分并附带理由。GPT-4o、Claude Sonnet、Gemini Pro——任何具有结构化输出支持的LLM都适用。研究表明，其与人类评估者的共识度在80-90%之间，与人类之间的互评者共识度相当。

代码评估器——在Langfuse内部运行的确定性Python或TypeScript。不涉及LLM。精确匹配、正则表达式、JSON验证、模式检查、业务规则。运行时是沙盒化的：仅标准库，无网络，2秒超时。听起来很限制——但它足以处理生产中真正重要的检查。

通过UI创建评分——人类通过跟踪并分配评分。需要先设置评分配置。也可从实验比较视图中进行注释以标注实验结果。

评分队列——结构化的审查工作流。创建一个评分配置的队列，分配跟踪，审阅者使用键盘快捷键工作。设计用于领域专家构建地面真实数据集。

通过API/SDK创建评分——程序化摄取。你的应用程序代码、CI流水线或自定义评估服务计算一个评分并发送到Langfuse。这是用户反馈（点赞/点踩）、护栏结果和自定义评估流水线的路径。

观察级别转变

这里就是Langfuse与大多数评估平台的不同之处：它们从跟踪级别转向观察级别评估。

一个跟踪是一个完整的端到端交互。一个观察是在该跟踪中的单个操作——一次LLM调用、一次检索、一次工具调用。这种区别很重要。

假设你的代理执行：检索文档 → 生成答案 → 调用工具 → 格式化响应。在跟踪级别评估中，你对整个过程打分。而在观察级别评估中，你可以仅在检索步骤上运行相关性评估器，在LLM生成上运行毒性检查，在工具调用上运行格式验证器。同样的跟踪，不同的评估器在不同的操作上。

这也意味着执行速度显著加快。观察级别的评估异步并行处理。你可以针对特定观察类型（仅面向客户的LLM调用，不包括内部调用）进行过滤，并将观察过滤器与跟踪过滤器堆叠。想要评估“所有标记为‘客户支持’的对话中的LLM生成，针对高级用户”？这是一个过滤组合，而不是自定义管道。

跟踪级别的评估器已被弃用。迁移截止日期与Langfuse v4相关联。

实验：离线路径

实验是你在部署前测试的方法。创建一个数据集（一组输入+可选的预期输出），编写一个任务函数（你的应用程序逻辑），然后将任务运行在每个项目上。然后对结果评分。

数据集部分值得强调：

  • 版本控制——每次添加、更新、删除或存档都会创建一个新的版本。你可以在特定时间戳下获取数据集，并针对历史数据集状态运行实验。这意味着即使项目发生变化，实验仍然可重复。
  • 模式强制执行——输入和预期输出的可选JSON模式验证。无效项会被详细错误拒绝。
  • 媒体支持——数据集项中的图像、音频、视频。Python SDK >= 4.10.0 和 JS/TS SDK >= 5.6.0。
  • 生产数据管道——从生产中选择不良跟踪，将它们添加到数据集中，由专家添加预期输出，然后针对它们运行实验。

通过SDK运行实验给你完全的控制权：自定义任务函数、项目级评估器、运行级评估器（聚合指标）、可配置的并发性和自动跟踪。结果对象有一个.format()方法，可以打印出干净的摘要。

result = langfuse.run_experiment(
    name="客户支持测试",
    data=test_data,
    task=my_agent,
    evaluators=[accuracy_eval, tone_eval],
    run_evaluators=[avg_accuracy],
    max_concurrency=10,
)
print(result.format())

你也可以通过UI运行提示实验——从提示管理中选择一个提示版本，选择一个数据集和模型，无需编写代码即可进行比较。适合快速迭代。

评分分析：零配置验证

一旦你有了评分，评分分析立即生效。无需配置。

选择一个评分：获取分布图表、时间趋势和统计（计数、均值、标准差）。选择两个相同类型的评分：获取相关性指标、混淆矩阵和一致性统计。

两个评分比较是其中最有用的部分。在相同的跟踪上运行GPT-4o和Gemini作为裁判，比较它们的评分。皮尔逊相关系数为0.984？你的评估是可靠的。人类注释与你的LLM裁判之间的科恩κ值为0.85？这些AI评估足够可靠，可以自动化。

匹配与所有数据视图揭示了覆盖率缺口。如果你有1,143个单独的评分，但只有567个匹配对，一半的跟踪只有一个评估方法。这是一个需要增加更多评估器的信号。

限制：最多两个评分（多向时为成对），相同数据类型，文本评分除外，评分超过100,000时自动采样。

CI/CD集成

Langfuse 提供了一个 GitHub 动作 (langfuse/experiment-action)，它在你的流水线中运行实验，并基于评分阈值进行门控。

流程：编写一个实验脚本，其中包含一个 experiment(context) 函数，定义评估器，当评分违反你的阈值时抛出 RegressionError。该动作会在PR评论中发布通过/失败状态、评分、指向Langfuse比较视图的链接以及项目输出的表格。

def experiment(context: RunnerContext):
    result = context.run_experiment(
        name="PR门控",
        task=my_task,
        evaluators=[exact_match],
        run_evaluators=[avg_accuracy],
    )
    accuracy = next(
        e.value for e in result.run_evaluations if e.name == "avg_accuracy"
    )
    if accuracy < 0.95:
        raise RegressionError(
            result=result, metric="avg_accuracy",
            value=accuracy, threshold=0.95,
        )
    return result

它也适用于 Pytest 和 Vitest，如果你更喜欢标准测试框架。

最后总结

Langfuse 的评估架构押注于一个理念：将所有质量信号统一为单一评分原语，并在观察级别粒度上操作，比为每种方法专门设计的评估工具更有价值。评分分析、CI/CD门控和数据集版本控制都源自这一基础。

如果你评估LLM应用程序时，信号分散在电子表格、脚本和仪表板中——评分作为通用原语的方法值得一看。不是因为它新颖，而是因为它迫使你将评估视为首要的工程问题，而不是事后考虑。