Langfuse Evaluators v2 数据模型深度解析从 eval_templates 到 Evaluator / Rule / Rule Assignment 的架构演进【免费下载链接】langfuse Open source AI engineering platform: LLM evals, observability, metrics, prompt management, playground, datasets. Integrates with OpenTelemetry, LangChain, OpenAI SDK, LiteLLM, and more. YC W23项目地址: https://gitcode.com/GitHub_Trending/la/langfuse本指南以 web/src/features/evals/v2/CLAUDE.md 为骨架深入剖析 Langfuse 新一代评测系统Evaluators v2的数据模型设计、迁移路径与工程实践。读者将掌握新旧两代数据模型的差异、Evaluator/Rule/Rule Assignment三者间的 n:m 关联结构、评测执行元数据的兼容策略以及该模块的测试规范与源码组织方式。为什么需要 Evaluators v2Langfuse 的评测Evals能力早期依赖一套模板 作业配置的模型。在旧设计中一个可复用的评测器定义与它的运行规则被拆散在不同表中导致评测器这一核心业务实体缺乏一等公民地位eval_templates负责存放评测器的定义提示词、模型、输出 schema、源码等job_configurations负责存放变量映射variable mapping以及该评测器要跑在哪些事件上which events it runs against。这种拆分带来的问题是模板与运行配置是一对多、却又通过外部引用强耦合的关系当需要把一个评测器同时挂到多条运行规则上、并为每条规则定制变量映射时关系表达不够自然也难以在 UI 中形成清晰的评测器详情视图。Evaluators v2 用三个实体重构了这一领域模型参见 packages/shared/prisma/schema.prismaEvaluator评测器评测能力的定义本体Rule规则旧job_configuration的继承者负责描述在什么条件下跑、按什么采样率跑Rule Assignment规则关联处理 Evaluator 与 Rule 之间 n:m 关系的关联表。新数据模型详解Evaluator评测器定义本体Evaluator模型schema.prisma落库为evaluators表字段包括字段说明name评测器名称type评测类型取值见EvalTemplateType枚举LLM_AS_JUDGELLM 作为裁判或CODE代码评测description可选描述createdByUserId创建者删除用户时置空onDelete: SetNullblockedAt/blockReason/blockMessage阻断状态当 LLM 连接鉴权失败、账单耗尽、端点不可达、默认评测模型缺失或模型配置无效时评测器会被标记为BLOCKED评测器的定义内容本身是可版本化的存放在evaluator_versions表EvaluatorVersionschema.prisma中。每个版本通过unique([evaluatorId, version(sort: Desc)])约束实现单调递增的版本号并保存prompt/promptMessages/varsLLM-as-Judge 的提示词体系provider/model/modelParams模型配置outputDefinition输出评分定义variableMapping变量映射JSONsourceCode/sourceCodeLanguage代码评测的源码sourceCode为VarChar(262144)语言枚举PYTHON/TYPESCRIPT。在服务端评测器定义通过 discriminated union 进行强校验web/src/features/evals/v2/server/evaluators/evaluatorTypes.tsLLM_AS_JUDGE分支要求promptMessages、modelConfig、outputDefinition并会从提示词中自动抽取变量extractVariables写入varsCODE分支则要求sourceCode与sourceCodeLanguage且不允许携带variableMappingz.never().optional()因为代码评测的变量映射语义与 LLM 评测不同。Rule旧 job_configuration 的继承者EvaluationRuleschema.prisma落库为evaluation_rules表保留了JobConfiguration的核心运行时语义字段说明name规则名称statusJobConfigState枚举ACTIVE/INACTIVEtargetObject目标对象类型v2 中通过过滤器表达规则的targetObject字段已被标记为 deprecatedfilterJSON 形式的条件过滤器决定哪些事件会被评估samplingDecimal 采样率取值范围 0..1控制作业实际执行的比例delay执行延迟毫秒timeScope时间范围默认[NEW]从类型层看ruleTypes.tsRuleMetadataSchema将sampling约束为z.number().min(0).max(1)filter为singleFilter数组CreateRuleSchema中targetObject的默认值为EVENT并明确注释modern rules are event rules and experiment scope is expressed through filters现代规则即事件规则实验experiment范围通过过滤器表达。Rule Assignmentn:m 关联表EvaluationRuleEvaluatorAssignmentschema.prisma落库为evaluation_rule_evaluator_assignments表是 v2 数据模型相对旧版最关键的结构性变化同时持有evaluationRuleId与evaluatorId两个外键均级联删除unique([evaluationRuleId, evaluatorId])保证同一规则下每个评测器只出现一次每个关联可以携带独立的variableMappingJSON这意味着同一个评测器挂在多条规则上时每条规则都能有各自的变量映射额外的evaluatorId索引用于支撑按评测器反查其关联的所有规则。这套设计把旧模型中模板定义 作业配置的一对多耦合升级为评测器 ⇄ 规则的干净多对多关系也正是文档中association table handling the n:m relationship所指的内容。新旧数据模型对照维度v1旧版v2新版评测器定义EvalTemplateeval_templatesEvaluatorEvaluatorVersionevaluators / evaluator_versions运行配置JobConfigurationjob_configurationsEvaluationRuleevaluation_rules关联方式JobConfiguration 通过evalTemplateId外键指向模板EvaluationRuleEvaluatorAssignment关联表n:m变量映射存放在 JobConfiguration.variableMapping存放在 Assignment.variableMapping可逐规则定制版本管理EvalTemplate 以unique([projectId, name, version])约束版本EvaluatorVersion 以unique([evaluatorId, version])约束版本执行元数据仅记录job_configuration_id记录evaluator_idevaluation_rule_id assignment id需要说明的是旧表并未被删除EvalTemplate、JobConfiguration、JobExecution仍保留在 schema.prisma 中用于支撑存量数据与兼容旧执行链路。评测执行的元数据job_configuration_id 与 evaluator_id 的兼容原文档特别强调了一个向后兼容细节过去捕获的评测执行 trace 只记录了job_configuration_id只有新的运行才会记录evaluator_id和evaluation_rule_id。在源码中这一元数据约定被集中定义在 packages/shared/src/features/evals/evalExecutionMetadata.ts完整键集合包括EVALUATOR_ID: evaluator_id, EVALUATOR_VERSION_ID: evaluator_version_id, EVALUATOR_TEST: evaluator_test, EVALUATION_RULE_ID: evaluation_rule_id, EVALUATION_RULE_ASSIGNMENT_ID: evaluation_rule_assignment_id, JOB_EXECUTION_ID: job_execution_id, JOB_CONFIGURATION_ID: job_configuration_id, TARGET_TRACE_ID: target_trace_id, TARGET_OBSERVATION_ID: target_observation_id, TARGET_DATASET_ITEM_ID: target_dataset_item_id,其中evaluator_test标记该次执行是否为测试运行evaluator_version_id精确到版本evaluation_rule_assignment_id精确到关联记录——这些字段共同支撑这次评分是由哪个评测器、哪个版本、哪条规则、哪个关联产生的完整追溯链。为了让新旧执行记录在查询层面统一可检索事件表为两者都暴露了过滤列Evaluator IDe.evaluator_id与Rule IDe.evaluation_rule_id见 packages/shared/src/eventsTable.ts。而查询层packages/shared/src/features/query/dataModel.ts使用coalesce(nullIf(evaluator_id, ), evaluation_rule_id)将新字段回退到旧字段当某条记录缺少新的evaluator_id即旧运行时自动用evaluation_rule_id兜底从而让新旧执行在同一个过滤器下都能被命中。评测器版本管理与创建/更新流程v2 将评测器定义与评测器元信息分层Evaluator表保存name/type/description等元数据与阻断状态而EvaluatorVersion表保存每一版定义内容。创建与更新的入参 schema 定义在 evaluatorTypes.tsCreateEvaluatorSchemaprojectId 可选evaluatorId用于从已存在评测器创建新版本definitionUpdateEvaluatorSchemaprojectIdevaluatorIddefinition同时支持部分更新PatchEvaluatorInput。版本分页使用 base64url 编码的游标evaluatorTypes.ts游标 JSON 形如{ v: 1, version: 42 }解码失败会抛出InvalidRequestErrorEvaluatorVersionsSchema默认limit 50。定义内容在持久化时会区分数据库 NULL 与 JSON nullPrisma.DbNullvsPrisma.InputJsonValue参见 evaluatorRepository.ts 的versionData函数。前端对应的版本体验组件包括 EvaluatorVersionHistorySheet版本历史抽屉与 EvaluatorVersionConflictDialog版本冲突提示评测器创建/编辑走 EvaluatorSetupEditor 的三步向导DefinitionStep定义→NameStep命名→VariableMappingStep变量映射每一步都有独立的 Container 组件负责状态管理。Rule 的生命周期与激活语义规则模块的 tRPC 路由web/src/features/evals/v2/server/rules/ruleRouter.ts覆盖了规则的完整生命周期list/get/filterOptions/reusableFilters规则的查询与筛选create/update/delete/deleteMany增删改setEnabled/setManyEnabled启用/停用JobConfigState.ACTIVE/INACTIVEattach/detach为规则挂载/卸载评测器写入关联表createOrAttachFromEvaluatorFilters从一个评测器的过滤器一键派生规则recentExecutions/costByRuleIds最近执行与成本估算suggestName根据过滤器与采样率自动生成规则名。规则激活是 v2 的一个设计亮点。SetRuleEnabledSchemaruleTypes.ts允许在确认激活时一并调整采样率注释说明了原因激活对话框可以在确认时微调采样二者落在同一个事务与同一条审计日志中。与之配套的前端是 ActivationConfirmationDialog 及其成本估算视图 ActivationCostEstimateView激活前的成本预估由服务端 activationCostService.ts 计算其入参 schemaevaluatorTypes.ts包含过滤器、采样率、是否扣除已知测试运行成本knownTestRunCostUsd并对时间范围做了约束起始不能早于 6 个月前结束不能晚于今天。规则的过滤器还支持复用reusableFilters过程返回可复用的过滤器预设ruleFilterMatching.ts 提供filterStateKey/filtersMatch通过稳定序列化数组排序 stableJsonStringify实现两个过滤器状态的等价比较以及fallbackRuleName将过滤器渲染为可读的默认规则名空过滤器时返回 All observations多条件用·连接并截断到 200 字符。n:m 关联在前端与批量操作中的体现关联表的存在直接影响了 UI 与批量操作的设计按规则视角RuleSetup 向导依次引导用户完成RuleNameStep命名→RuleFilterStep过滤器→RuleEvaluatorsStep选择评测器并逐一配置变量映射并通过 RuleEvaluatorCostEstimate 展示成本估算按评测器视角EvaluatorRuleRelationships 展示某个评测器被哪些规则引用对应服务端listRulesForEvaluator过程批量删除限制仓库中的batchEligibleEvaluatorWhereevaluatorRepository.ts明确规定带有TRACE/DATASET目标对象规则的评测器不能参与观察级批量删除因为trace/dataset 关联携带规则特定的映射仅凭评测器 ID 无法在观察批量中解析。这种一个评测器可挂多条规则、每条规则可挂多个评测器的能力正是 n:m 关联表相比旧版外键设计的价值所在。API 层权限、审计与测试运行权限与审计服务端路由全部基于 tRPC 的protectedProjectProcedure构建evaluatorRouter.ts每个过程先调用throwIfNoProjectAccess校验 RBAC scope评测器使用evaluator:read等 scope规则使用evaluationRule:read等 scope。审计日志方面评测器写操作沿用旧的evalTemplate资源类型evaluatorRouter.ts而规则写操作使用JOB_CONFIGURATION_AUDIT_LOG_RESOURCE_TYPEruleRouter.ts可以看到审计资源类型上同样保留了新旧迁移的痕迹。测试运行test过程evaluatorRouter.ts接受observationId/traceId/startTime与一份完整的评测器定义针对真实样本执行一次评测无需先落库正式版本。前端对应 EvaluatorTestPanel 与 TestSection支持选取样本观察SampleObservationSelectorBase、过滤样本ObservationFilterBuilder、重跑TestRerunButton与查看结果 traceTestResultTraceActions。测试执行的元数据中EVALUATOR_TEST标记会区分测试运行与正式运行。列表与筛选评测器列表支持按name/creator/model进行字符串过滤按status/type进行选项过滤并支持分页与排序name/type/createdAt/updatedAtschema 校验在 evaluatorTypes.ts规则列表则支持name/creator/enabled/upgradeRequired过滤见 ruleTypes.ts。评测器画廊listGallery采用基于createdAt id的游标分页便于在 EvaluatorGalleryView 中无限滚动浏览模板。测试规范避免无意义的 tautological 测试原文档在 Testing 一节给出了两条明确约束这也是 v2 模块工程规范的核心不要编写同义反复tautological的 React 客户端测试即测试逻辑只是在重复实现本身例如断言点击按钮后 state 变成了按钮 onClick 里写死的值这类不验证真实行为的用例不要测试像素定位避免对布局坐标、样式位移这类与业务行为无关的断言只有当组件测试能约束有意义的行为时才添加测试的价值在于守护真实业务规则而非凑覆盖率。从 v2 目录中已有的测试文件可以看到这一规范的落地形态行为导向的测试如 EvaluatorSavedDialog.clienttest.tsx校验保存对话框的交互行为、RuleNameStep.clienttest.tsx、EvaluatorVersionHistorySheet.clienttest.tsx纯函数逻辑则有配套的单元测试如 prepareModernRuleVariableMapping.clienttest.ts、buildSampleQueryFilters.clienttest.ts、managedTemplatesCatalog.clienttest.ts。服务端侧则通过 servertest 覆盖事务与成本计算等关键路径例如 activationCostService.servertest.ts。小结Evaluators v2 是 Langfuse 评测体系的一次数据模型重构用Evaluator含版本化定义、Rule运行条件与采样和Rule Assignmentn:m 关联逐关联变量映射替换旧的EvalTemplateJobConfiguration组合同时通过执行元数据双写evaluator_id/evaluation_rule_id与兼容旧记录的job_configuration_id和查询层coalesce兜底保证了新旧执行记录的统一可观测。如果你需要深入某一部分建议从 web/src/features/evals/v2/server/evaluators/evaluatorTypes.ts 与 web/src/features/evals/v2/server/rules/ruleTypes.ts 两份 schema 定义入手再对照 packages/shared/prisma/schema.prisma 的物理表结构与 packages/shared/src/features/evals/evalExecutionMetadata.ts 的元数据约定即可完整还原这套模型的实现全貌。【免费下载链接】langfuse Open source AI engineering platform: LLM evals, observability, metrics, prompt management, playground, datasets. Integrates with OpenTelemetry, LangChain, OpenAI SDK, LiteLLM, and more. YC W23项目地址: https://gitcode.com/GitHub_Trending/la/langfuse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Langfuse Evaluators v2 数据模型深度解析：从 eval_templates 到 Evaluator / Rule / Rule Assignment 的架构演进
Langfuse Evaluators v2 数据模型深度解析从 eval_templates 到 Evaluator / Rule / Rule Assignment 的架构演进【免费下载链接】langfuse Open source AI engineering platform: LLM evals, observability, metrics, prompt management, playground, datasets. Integrates with OpenTelemetry, LangChain, OpenAI SDK, LiteLLM, and more. YC W23项目地址: https://gitcode.com/GitHub_Trending/la/langfuse本指南以 web/src/features/evals/v2/CLAUDE.md 为骨架深入剖析 Langfuse 新一代评测系统Evaluators v2的数据模型设计、迁移路径与工程实践。读者将掌握新旧两代数据模型的差异、Evaluator/Rule/Rule Assignment三者间的 n:m 关联结构、评测执行元数据的兼容策略以及该模块的测试规范与源码组织方式。为什么需要 Evaluators v2Langfuse 的评测Evals能力早期依赖一套模板 作业配置的模型。在旧设计中一个可复用的评测器定义与它的运行规则被拆散在不同表中导致评测器这一核心业务实体缺乏一等公民地位eval_templates负责存放评测器的定义提示词、模型、输出 schema、源码等job_configurations负责存放变量映射variable mapping以及该评测器要跑在哪些事件上which events it runs against。这种拆分带来的问题是模板与运行配置是一对多、却又通过外部引用强耦合的关系当需要把一个评测器同时挂到多条运行规则上、并为每条规则定制变量映射时关系表达不够自然也难以在 UI 中形成清晰的评测器详情视图。Evaluators v2 用三个实体重构了这一领域模型参见 packages/shared/prisma/schema.prismaEvaluator评测器评测能力的定义本体Rule规则旧job_configuration的继承者负责描述在什么条件下跑、按什么采样率跑Rule Assignment规则关联处理 Evaluator 与 Rule 之间 n:m 关系的关联表。新数据模型详解Evaluator评测器定义本体Evaluator模型schema.prisma落库为evaluators表字段包括字段说明name评测器名称type评测类型取值见EvalTemplateType枚举LLM_AS_JUDGELLM 作为裁判或CODE代码评测description可选描述createdByUserId创建者删除用户时置空onDelete: SetNullblockedAt/blockReason/blockMessage阻断状态当 LLM 连接鉴权失败、账单耗尽、端点不可达、默认评测模型缺失或模型配置无效时评测器会被标记为BLOCKED评测器的定义内容本身是可版本化的存放在evaluator_versions表EvaluatorVersionschema.prisma中。每个版本通过unique([evaluatorId, version(sort: Desc)])约束实现单调递增的版本号并保存prompt/promptMessages/varsLLM-as-Judge 的提示词体系provider/model/modelParams模型配置outputDefinition输出评分定义variableMapping变量映射JSONsourceCode/sourceCodeLanguage代码评测的源码sourceCode为VarChar(262144)语言枚举PYTHON/TYPESCRIPT。在服务端评测器定义通过 discriminated union 进行强校验web/src/features/evals/v2/server/evaluators/evaluatorTypes.tsLLM_AS_JUDGE分支要求promptMessages、modelConfig、outputDefinition并会从提示词中自动抽取变量extractVariables写入varsCODE分支则要求sourceCode与sourceCodeLanguage且不允许携带variableMappingz.never().optional()因为代码评测的变量映射语义与 LLM 评测不同。Rule旧 job_configuration 的继承者EvaluationRuleschema.prisma落库为evaluation_rules表保留了JobConfiguration的核心运行时语义字段说明name规则名称statusJobConfigState枚举ACTIVE/INACTIVEtargetObject目标对象类型v2 中通过过滤器表达规则的targetObject字段已被标记为 deprecatedfilterJSON 形式的条件过滤器决定哪些事件会被评估samplingDecimal 采样率取值范围 0..1控制作业实际执行的比例delay执行延迟毫秒timeScope时间范围默认[NEW]从类型层看ruleTypes.tsRuleMetadataSchema将sampling约束为z.number().min(0).max(1)filter为singleFilter数组CreateRuleSchema中targetObject的默认值为EVENT并明确注释modern rules are event rules and experiment scope is expressed through filters现代规则即事件规则实验experiment范围通过过滤器表达。Rule Assignmentn:m 关联表EvaluationRuleEvaluatorAssignmentschema.prisma落库为evaluation_rule_evaluator_assignments表是 v2 数据模型相对旧版最关键的结构性变化同时持有evaluationRuleId与evaluatorId两个外键均级联删除unique([evaluationRuleId, evaluatorId])保证同一规则下每个评测器只出现一次每个关联可以携带独立的variableMappingJSON这意味着同一个评测器挂在多条规则上时每条规则都能有各自的变量映射额外的evaluatorId索引用于支撑按评测器反查其关联的所有规则。这套设计把旧模型中模板定义 作业配置的一对多耦合升级为评测器 ⇄ 规则的干净多对多关系也正是文档中association table handling the n:m relationship所指的内容。新旧数据模型对照维度v1旧版v2新版评测器定义EvalTemplateeval_templatesEvaluatorEvaluatorVersionevaluators / evaluator_versions运行配置JobConfigurationjob_configurationsEvaluationRuleevaluation_rules关联方式JobConfiguration 通过evalTemplateId外键指向模板EvaluationRuleEvaluatorAssignment关联表n:m变量映射存放在 JobConfiguration.variableMapping存放在 Assignment.variableMapping可逐规则定制版本管理EvalTemplate 以unique([projectId, name, version])约束版本EvaluatorVersion 以unique([evaluatorId, version])约束版本执行元数据仅记录job_configuration_id记录evaluator_idevaluation_rule_id assignment id需要说明的是旧表并未被删除EvalTemplate、JobConfiguration、JobExecution仍保留在 schema.prisma 中用于支撑存量数据与兼容旧执行链路。评测执行的元数据job_configuration_id 与 evaluator_id 的兼容原文档特别强调了一个向后兼容细节过去捕获的评测执行 trace 只记录了job_configuration_id只有新的运行才会记录evaluator_id和evaluation_rule_id。在源码中这一元数据约定被集中定义在 packages/shared/src/features/evals/evalExecutionMetadata.ts完整键集合包括EVALUATOR_ID: evaluator_id, EVALUATOR_VERSION_ID: evaluator_version_id, EVALUATOR_TEST: evaluator_test, EVALUATION_RULE_ID: evaluation_rule_id, EVALUATION_RULE_ASSIGNMENT_ID: evaluation_rule_assignment_id, JOB_EXECUTION_ID: job_execution_id, JOB_CONFIGURATION_ID: job_configuration_id, TARGET_TRACE_ID: target_trace_id, TARGET_OBSERVATION_ID: target_observation_id, TARGET_DATASET_ITEM_ID: target_dataset_item_id,其中evaluator_test标记该次执行是否为测试运行evaluator_version_id精确到版本evaluation_rule_assignment_id精确到关联记录——这些字段共同支撑这次评分是由哪个评测器、哪个版本、哪条规则、哪个关联产生的完整追溯链。为了让新旧执行记录在查询层面统一可检索事件表为两者都暴露了过滤列Evaluator IDe.evaluator_id与Rule IDe.evaluation_rule_id见 packages/shared/src/eventsTable.ts。而查询层packages/shared/src/features/query/dataModel.ts使用coalesce(nullIf(evaluator_id, ), evaluation_rule_id)将新字段回退到旧字段当某条记录缺少新的evaluator_id即旧运行时自动用evaluation_rule_id兜底从而让新旧执行在同一个过滤器下都能被命中。评测器版本管理与创建/更新流程v2 将评测器定义与评测器元信息分层Evaluator表保存name/type/description等元数据与阻断状态而EvaluatorVersion表保存每一版定义内容。创建与更新的入参 schema 定义在 evaluatorTypes.tsCreateEvaluatorSchemaprojectId 可选evaluatorId用于从已存在评测器创建新版本definitionUpdateEvaluatorSchemaprojectIdevaluatorIddefinition同时支持部分更新PatchEvaluatorInput。版本分页使用 base64url 编码的游标evaluatorTypes.ts游标 JSON 形如{ v: 1, version: 42 }解码失败会抛出InvalidRequestErrorEvaluatorVersionsSchema默认limit 50。定义内容在持久化时会区分数据库 NULL 与 JSON nullPrisma.DbNullvsPrisma.InputJsonValue参见 evaluatorRepository.ts 的versionData函数。前端对应的版本体验组件包括 EvaluatorVersionHistorySheet版本历史抽屉与 EvaluatorVersionConflictDialog版本冲突提示评测器创建/编辑走 EvaluatorSetupEditor 的三步向导DefinitionStep定义→NameStep命名→VariableMappingStep变量映射每一步都有独立的 Container 组件负责状态管理。Rule 的生命周期与激活语义规则模块的 tRPC 路由web/src/features/evals/v2/server/rules/ruleRouter.ts覆盖了规则的完整生命周期list/get/filterOptions/reusableFilters规则的查询与筛选create/update/delete/deleteMany增删改setEnabled/setManyEnabled启用/停用JobConfigState.ACTIVE/INACTIVEattach/detach为规则挂载/卸载评测器写入关联表createOrAttachFromEvaluatorFilters从一个评测器的过滤器一键派生规则recentExecutions/costByRuleIds最近执行与成本估算suggestName根据过滤器与采样率自动生成规则名。规则激活是 v2 的一个设计亮点。SetRuleEnabledSchemaruleTypes.ts允许在确认激活时一并调整采样率注释说明了原因激活对话框可以在确认时微调采样二者落在同一个事务与同一条审计日志中。与之配套的前端是 ActivationConfirmationDialog 及其成本估算视图 ActivationCostEstimateView激活前的成本预估由服务端 activationCostService.ts 计算其入参 schemaevaluatorTypes.ts包含过滤器、采样率、是否扣除已知测试运行成本knownTestRunCostUsd并对时间范围做了约束起始不能早于 6 个月前结束不能晚于今天。规则的过滤器还支持复用reusableFilters过程返回可复用的过滤器预设ruleFilterMatching.ts 提供filterStateKey/filtersMatch通过稳定序列化数组排序 stableJsonStringify实现两个过滤器状态的等价比较以及fallbackRuleName将过滤器渲染为可读的默认规则名空过滤器时返回 All observations多条件用·连接并截断到 200 字符。n:m 关联在前端与批量操作中的体现关联表的存在直接影响了 UI 与批量操作的设计按规则视角RuleSetup 向导依次引导用户完成RuleNameStep命名→RuleFilterStep过滤器→RuleEvaluatorsStep选择评测器并逐一配置变量映射并通过 RuleEvaluatorCostEstimate 展示成本估算按评测器视角EvaluatorRuleRelationships 展示某个评测器被哪些规则引用对应服务端listRulesForEvaluator过程批量删除限制仓库中的batchEligibleEvaluatorWhereevaluatorRepository.ts明确规定带有TRACE/DATASET目标对象规则的评测器不能参与观察级批量删除因为trace/dataset 关联携带规则特定的映射仅凭评测器 ID 无法在观察批量中解析。这种一个评测器可挂多条规则、每条规则可挂多个评测器的能力正是 n:m 关联表相比旧版外键设计的价值所在。API 层权限、审计与测试运行权限与审计服务端路由全部基于 tRPC 的protectedProjectProcedure构建evaluatorRouter.ts每个过程先调用throwIfNoProjectAccess校验 RBAC scope评测器使用evaluator:read等 scope规则使用evaluationRule:read等 scope。审计日志方面评测器写操作沿用旧的evalTemplate资源类型evaluatorRouter.ts而规则写操作使用JOB_CONFIGURATION_AUDIT_LOG_RESOURCE_TYPEruleRouter.ts可以看到审计资源类型上同样保留了新旧迁移的痕迹。测试运行test过程evaluatorRouter.ts接受observationId/traceId/startTime与一份完整的评测器定义针对真实样本执行一次评测无需先落库正式版本。前端对应 EvaluatorTestPanel 与 TestSection支持选取样本观察SampleObservationSelectorBase、过滤样本ObservationFilterBuilder、重跑TestRerunButton与查看结果 traceTestResultTraceActions。测试执行的元数据中EVALUATOR_TEST标记会区分测试运行与正式运行。列表与筛选评测器列表支持按name/creator/model进行字符串过滤按status/type进行选项过滤并支持分页与排序name/type/createdAt/updatedAtschema 校验在 evaluatorTypes.ts规则列表则支持name/creator/enabled/upgradeRequired过滤见 ruleTypes.ts。评测器画廊listGallery采用基于createdAt id的游标分页便于在 EvaluatorGalleryView 中无限滚动浏览模板。测试规范避免无意义的 tautological 测试原文档在 Testing 一节给出了两条明确约束这也是 v2 模块工程规范的核心不要编写同义反复tautological的 React 客户端测试即测试逻辑只是在重复实现本身例如断言点击按钮后 state 变成了按钮 onClick 里写死的值这类不验证真实行为的用例不要测试像素定位避免对布局坐标、样式位移这类与业务行为无关的断言只有当组件测试能约束有意义的行为时才添加测试的价值在于守护真实业务规则而非凑覆盖率。从 v2 目录中已有的测试文件可以看到这一规范的落地形态行为导向的测试如 EvaluatorSavedDialog.clienttest.tsx校验保存对话框的交互行为、RuleNameStep.clienttest.tsx、EvaluatorVersionHistorySheet.clienttest.tsx纯函数逻辑则有配套的单元测试如 prepareModernRuleVariableMapping.clienttest.ts、buildSampleQueryFilters.clienttest.ts、managedTemplatesCatalog.clienttest.ts。服务端侧则通过 servertest 覆盖事务与成本计算等关键路径例如 activationCostService.servertest.ts。小结Evaluators v2 是 Langfuse 评测体系的一次数据模型重构用Evaluator含版本化定义、Rule运行条件与采样和Rule Assignmentn:m 关联逐关联变量映射替换旧的EvalTemplateJobConfiguration组合同时通过执行元数据双写evaluator_id/evaluation_rule_id与兼容旧记录的job_configuration_id和查询层coalesce兜底保证了新旧执行记录的统一可观测。如果你需要深入某一部分建议从 web/src/features/evals/v2/server/evaluators/evaluatorTypes.ts 与 web/src/features/evals/v2/server/rules/ruleTypes.ts 两份 schema 定义入手再对照 packages/shared/prisma/schema.prisma 的物理表结构与 packages/shared/src/features/evals/evalExecutionMetadata.ts 的元数据约定即可完整还原这套模型的实现全貌。【免费下载链接】langfuse Open source AI engineering platform: LLM evals, observability, metrics, prompt management, playground, datasets. Integrates with OpenTelemetry, LangChain, OpenAI SDK, LiteLLM, and more. YC W23项目地址: https://gitcode.com/GitHub_Trending/la/langfuse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考