golden-dataset

黄金数据集

用于构建、管理和验证 AI/ML 评估黄金数据集的全面模式。每个类别的规则文件位于 rules/ 中，并按需加载。

快速参考

类别	规则	影响	适用场景
整理	2	高	内容收集、标注流水线
管理	2	高	版本控制、备份/恢复
验证	1	严重	回归测试
添加工作流	1	高	9 阶段整理、质量评分、偏差检测、从银级到金级

4 个类别共 6 条规则。内部阈值和经验教训：references/ork-delta.md。

整理

黄金数据集的内容收集、多 Agent 标注和多样性分析。

规则	文件	关键模式
收集	rules/curation-collection.md	内容类型分类、质量阈值、防止重复
标注	rules/curation-annotation.md	多 Agent 流水线、共识聚合、Langfuse 跟踪

难度阶梯、覆盖率下限和重复项阈值：references/ork-delta.md。

管理

黄金数据集的版本控制、存储和 CI/CD 自动化。

规则	文件	关键模式
版本控制	rules/management-versioning.md	JSON 备份格式、嵌入重新生成、灾难恢复
存储	rules/management-storage.md	备份策略、URL 契约、数据完整性检查

备份的 CI 自动化属于上游职责；参见下文的“上游覆盖范围”。

验证

黄金数据集的质量评分、漂移检测和回归测试。

规则	文件	关键模式
回归	rules/validation-regression.md	难度分布、提交前钩子、完整数据集验证

架构验证和重复项检测属于上游职责（参见下文的“上游覆盖范围”）；必须执行的内部阈值见 references/ork-delta.md。

添加工作流

用于向黄金数据集添加新文档的结构化工作流。

规则	文件	关键模式
添加文档	rules/curation-add-workflow.md	9 阶段整理、并行质量分析、偏差检测

快速入门示例

async def validate_before_add(document: dict, source_url_map: dict) -> dict:
    """Pre-addition validation for golden dataset entries."""
    errors = []

    # 1. URL contract check
    if "placeholder" in document.get("source_url", ""):
        errors.append("URL must be canonical, not a placeholder")

    # 2. Content quality
    if len(document.get("title", "")) < 10:
        errors.append("Title too short (min 10 chars)")

    # 3. Tag requirements
    if len(document.get("tags", [])) < 2:
        errors.append("At least 2 domain tags required")

    return {"valid": len(errors) == 0, "errors": errors}

关键决策

决策	建议
备份格式	JSON（可进行版本控制，便于移植）
嵌入存储	从备份中排除（恢复时重新生成）
质量阈值	纳入数据集的质量评分需 >= 0.70
置信度阈值	自动纳入需 >= 0.65
重复项阈值	相似度 >= 0.90 时阻止，>= 0.85 时警告
每条目最少标签数	2 个领域标签
每份文档最少测试查询数	3
难度平衡	简单 3、中等偏易 3、中等 5、困难 3（最低数量）
CI 频率	每周自动备份（UTC 周日凌晨 2 点）

常见错误

1. 使用占位 URL，而不是规范的源 URL
2. 恢复后跳过嵌入重新生成
3. 未验证文档与查询之间的引用完整性
4. 过度偏重文章（忽视教程和研究论文）
5. 测试查询中的难度分布不平衡
6. 备份/恢复操作后未运行验证
7. 在生产环境而非预发布环境测试恢复流程
8. 提交 SQL 转储而不是 JSON（不利于版本控制）

将数据集作为实验运行

整理数据集只完成了一半工作；另一半是针对它运行某项任务并评估结果。Langfuse 的两个 SDK 都提供了运行器，但它们的形式有所不同。

**Python（SDK 4.x）：**参见 monitoring-observability/references/experiments-api.md。

JS/TS（SDK 5.x）：@langfuse/client 可直接在获取的数据集上提供运行器。

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();
const dataset = await langfuse.dataset.get("my-evaluation-dataset");

const result = await dataset.runExperiment({
  name: "Retrieval quality",
  task: myTask,               // (params) => Promise<any>
  evaluators: [myEvaluator],  // per-item: (params) => Promise<Evaluation | Evaluation[]>
});

类型	评分	用途
Evaluator	单个条目	逐样本质量评估（忠实度、相关性）
RunEvaluator	整次运行	聚合断言——通过率、平均分、回归检查
Evaluation	—	{ name, value, comment?, metadata?, dataType?, configId? }

逐条目的 Evaluator 无法查看其他条目，因此任何比较性评估都应放在 RunEvaluator 中。createEvaluatorFromAutoevals 会封装一个 autoevals 评分器，无需手动编写；当运行结果相较于配置的基线出现回归时，会抛出 RegressionError——捕获它，即可在质量下降时让 CI 失败，而不只是发生异常时才失败。

完整的 JS 接口：monitoring-observability/references/langfuse-js-v5.md。

评估

参见 test-cases.json，其中包含涵盖所有类别的 9 个测试用例。

上游覆盖范围（不要重复说明）

主题	一手资料
数据集架构验证（JSON Schema、字段约束）	https://json-schema.org 和 https://zod.dev
通过嵌入向量、余弦相似度检测重复项	https://github.com/pgvector/pgvector
定时备份自动化（cron 工作流、提交机器人）	https://docs.github.com/actions/using-workflows/events-that-trigger-workflows#schedule
数据集运行、实验评分、标注队列	https://langfuse.com/docs/datasets
postgres 数据集的备份和恢复机制	https://www.postgresql.org/docs/current/backup.html

必须执行的 House 阈值：references/ork-delta.md。

相关技能

• ork:rag-retrieval - 使用黄金数据集进行检索评估
• ork:monitoring-observability - 用于整理工作流的 Langfuse 跟踪模式
• ork:testing-llm - 使用黄金数据集的评估测试框架
• ork:testing-unit - 单元测试模式和策略

能力详情

curation

**关键词：**黄金数据集、整理、内容收集、标注、质量标准

解决的问题：

• 对黄金数据集的文档内容类型进行分类
• 运行多 Agent 质量分析流水线
• 为新文档生成测试查询

management

**关键词：**黄金数据集、备份、恢复、版本控制、灾难恢复

解决的问题：

• 使用 JSON 备份和恢复黄金数据集
• 恢复后重新生成嵌入向量
• 使用 CI/CD 自动执行备份

validation

**关键词：**黄金数据集、验证、架构、重复项检测、质量指标

解决的问题：

• 根据文档架构验证条目
• 检测重复或近似重复的条目
• 分析数据集覆盖范围和分布缺口