Langfuse Seeder 测试数据生成系统完全指南架构、三类数据形态与扩展实践【免费下载链接】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/langfuseLangfuse Seeder System 是 Langfuse 仓库内置的一套测试数据生成系统用于在 ClickHouse 与 PostgreSQL 中批量生成接近真实的 trace、observation、score 与数据集实验数据服务于本地开发、调试、性能压测与演示场景。本文将以该系统的设计文档为核心结合源码逐层拆解其架构、三种数据形态、双层生成模式bulk / synthetic、配置项与扩展方法论帮助读者快速上手、按需定制属于自己的种子数据。系统定位与整体架构Seeder 系统解决的核心问题是开发 Langfuse 前端、评估器、数据集实验等功能时需要一个看起来像生产环境的数据集。手工造数据既慢又不真实而真实业务数据又无法直接进入开发库。Seeder 通过一组相互协作的 TypeScript 模块把生成什么样的数据与如何高效写入 ClickHouse彻底分离。其核心文件全部位于 packages/shared/scripts/seeder/utils/ 目录下文档中的架构树与实际文件一一对应seeder/utils/ ├── types.ts # 核心接口与类型SeederMode、SeederOptions、FileContent ├──>import { SeederOrchestrator } from ./seeder-orchestrator; const orchestrator new SeederOrchestrator(); // 完整播种数据集实验 评估数据 合成数据 支持会话 / 框架 trace / 媒体 trace await orchestrator.executeFullSeed(projectIds, { mode: bulk, // 生成策略见下文两种生成模式 numberOfDays: 30, // 时间戳向前回退的天数 numberOfRuns: 3, // 每个数据集执行的实验轮数 }); // 单独生成某一类数据 await orchestrator.createDatasetExperimentData(projectIds, { mode: bulk, numberOfDays: 30 }); await orchestrator.createEvaluationData(projectIds); await orchestrator.createSyntheticData(projectIds, { mode: bulk, numberOfDays: 30 });其中projectIds是目标项目的 ID 数组。注意executeFullSeedseeder-orchestrator.ts并非只做文档中提到的三类数据还会顺带生成三类补充数据完整流程为createDatasetExperimentData()—— 数据集实验数据createEvaluationData()—— 评估数据createSyntheticData()—— 大规模合成数据createSupportChatSessionTraces()—— 一条贴近真实的客服聊天会话 tracecreateFrameworkTraces()—— 从真实框架导出 JSON 加载的框架 traceLangGraph、OpenAI Agents、Pydantic AI 等createMediaTestTraces()—— 用于测试 trace 详情页媒体渲染图片 / PDF / 音频的专用 trace。每步执行完毕后logStatistics()会对traces、scores、observations三张表按project_id做计数统计并以 ASCII 条形图输出seeder-orchestrator.ts方便快速核对写入量。三种数据形态详解1. 数据集实验数据Dataset Experiment Data用途基于真实数据集生成实验 trace用于 A/B 测试与 prompt 对比、基于数据集的评估、prompt 测试环境environmentlangfuse-prompt-experiment结构每个数据集条目dataset item对应一条 tracetrace 下挂载一个GENERATION类型 observation并附带 trace 级与 run 级两类 scoreID 模式trace-dataset-{datasetName}-{itemIndex}-{projectId后8位}-{runNumber}见 seed-helpers.ts。实现层面data-generators.ts会对特定数据集做输入输出模板化例如demo-countries-dataset的条目会被翻译成What is the capital of France?/The capital of France is Paris.这样的自然语言对。每个 observation 的 token 用量输入 30–150、输出 10–80与成本约 $0.0001–0.01 区间均为随机变化成本经过 5 位小数舍入以保证精度data-generators.ts。数据集实验的分值与名称通过常量DATASET_SCORE_NAMES [score-1,score-2,score-3]与DATASET_RUN_SCORE_NAMES控制其中 run 级 score 会关联dataset_run_id形如demo-dataset-run-{runNumber}-{datasetName}-{projectId后8位}。2. 评估数据Evaluation Data用途面向评估器evaluator配置的测试数据用于评估器开发、分值校验与评估流程测试环境langfuse-evaluation结构每个评估器配置生成EVAL_TRACE_COUNT 100条 trace每条 trace 挂载 10 个 observations约 47%GENERATION、47%SPAN、其余EVENT并恰好为每条 trace 生成一条 scoreID 模式trace-eval-{evalTemplateId}-{projectId后8位}-{index}注意实现中实际包含评估模板 ID而非文档简写形式。评估 trace 的数据源头是 postgres-seed-constants.ts 中的SEED_EVALUATOR_CONFIGS仓库内置了一个名为toxicity-job的 ACTIVE 评估任务LLM_AS_JUDGE类型使用gpt-5.4-mini带temperature: 0.7等模型参数与变量映射以及一个typescript-code-eval-template的代码评估器模板。createEvaluationData()seeder-orchestrator.ts会遍历所有SEED_EVALUATOR_CONFIGS生成对应数据因此新增评估器配置即可自动扩充评估数据形态。3. 合成数据Synthetic Data用途大规模真实感 trace 数据用于压测、仪表盘演示与真实用量模拟环境default结构分层 trace内含多种 observation 类型与 scoreID 模式trace-synthetic-{index}-{projectId后8位}。合成数据同时覆盖新旧两代观测类型约 80% 为传统类型GENERATION/SPAN/EVENT其余 20% 从AGENT、TOOL、CHAIN、RETRIEVER、EVALUATOR、EMBEDDING、GUARDRAIL中随机抽取每种类型都有独立的名称池见 clickhouse-seed-constants.ts例如REALISTIC_TRACE_NAMES、REALISTIC_MODELS、REALISTIC_TOOL_NAMES。观测之间通过parent_observation_id串联成链形成父子层级。约 10% 的 trace 会走generateComprehensiveAIWorkflowTrace()data-generators.ts生成一条包含 AGENT → RETRIEVER → EMBEDDING → CHAIN → TOOL → GENERATION → EVALUATOR → GUARDRAIL 全链路的AI Agent 综合工作流 trace其中 GENERATION 观测还携带tool_definitions与tool_calls字段。Score 支持NUMERIC/CATEGORICAL/BOOLEAN三种类型并有约 10% 概率挂到 observation 上data-generators.ts。抽象架构三层职责分离系统通过三个核心类实现生成逻辑、写入逻辑、编排逻辑的完全解耦文档明确给出了各层的修改边界DataGenerator数据生成器负责生成上述三类数据的真实内容是修改 ClickHouse 数据形态时的首选入口。它是一个私有构造函数的单例getInstance()并通过setFileContent()接收编排器注入的真实载荷。关键方法generateDatasetTrace()—— 根据数据集条目创建实验 tracegenerateSyntheticTraces()—— 创建真实感合成 tracegenerateEvaluationTraces()—— 创建评估导向 trace。此外还包含generateSyntheticObservations()、generateSyntheticScores()、generateEvaluationObservations()、generateEvaluationScores()、generateDatasetObservation()、generateDatasetScore()、generateDatasetRunScore()等方法以及一组私有随机工具randomElement、randomBoolean、randomInt和元数据构造器buildNestedSeedMetadata()生成含customer.id、customer.plan、routing.queue、flags.beta等键的嵌套元数据模拟真实业务标签体系。ClickHouseQueryBuilder查询构建器构建并执行 ClickHouse 插入查询文档强调无需也不建议修改此文件。它内部实现了完整的字符串转义escapeString先处理反斜杠再转义单引号避免 JSON 夹具中的\破坏 SQL与嵌套元数据 Map 的 SQL 生成buildNestedMetadataMapSql。其 API 分两层executeXxxInsert()系列面向小规模、需要精确控制的定制数据直接复用packages/shared/src/server导出的createTracesCh/createObservationsCh/createScoresCh/createDatasetRunItemsChbuildBulkXxxInsert()系列面向超过 1000 条的大批量数据生成基于 ClickHousenumbers()表函数与xxHash32哈希列的纯 SQLINSERT ... SELECTclickhouse-builder.ts。SeederOrchestrator编排器对外暴露createDatasetExperimentData/createEvaluationData/createSyntheticData/executeFullSeed四个主方法职责包括加载真实输入输出文件内容、协调生成与插入、错误恢复任一插入失败即记录并抛出、提供日志与统计。执行批量 SQL 时通过clickhouseClient().command()并设置wait_end_of_query: 1保证查询同步完成seeder-orchestrator.ts。两种生成模式bulk 与 synthetic这是文档 Quick Start 之外必须补充的关键设计。在 types.ts 中SeederMode定义了两种策略export type SeederMode bulk | synthetic; // bulk: SQL 级生成速度快、体量大10 万条观测默认 // synthetic: 内存级生成速度较慢、结构更真实1 千条观测 export const getTotalObservationsForMode (mode: SeederMode): number { return mode bulk ? 100000 : 1000; }; export interface SeederOptions { mode: SeederMode; numberOfDays: number; numberOfRuns?: number; }createSyntheticData()的分支逻辑seeder-orchestrator.ts体现了两种模式的具体差异维度bulk默认synthetic实现方式纯 SQLnumbers() 哈希列内存中逐条构造记录对象观测总量100,000每项目1,000每项目每 trace 观测数1515每 trace 分数1010插入路径executeQuery(bulkQuery)executeTracesInsert / executeObservationsInsert / executeScoresInsert适用场景压测、列表页性能、大屏演示结构精细、便于人工核查的小数据集bulk 模式的 SQL 蕴含大量确定性技巧时间戳以 UTC 午夜为锚点anchorSeconds在 TS 侧计算不依赖 ClickHouse 服务器时区通过toDateTime(anchor - intDiv(number * spreadSeconds, count))让时间随行号均匀回退行间差异全部来自对行号加盐后的xxHash32(toUInt64(...))哈希列h1–h4从而保证同一天重复运行得到完全一致的数据配合 ReplacingMergeTree 的去重键可做到原地覆盖而非产生重复行这一点在 seeder 根目录 README.md 中被总结为ClickHouse determinism rules。此外 bulk 观测还通过h4 % 5将生成模型均匀分布到 5 个真实模型gpt-5.4-mini、claude-haiku-4-5等并支持传入真实 Postgres prompt 行让约 10% 的 generation 正确挂载 prompt 徽章伪造 ID 会破坏 PromptBadge 渲染因此未传入时 prompt 字段保持 NULL。配置选项详解文档给出的配置接口SeederConfig在现行源码中已演进为SeederOptions核心字段如下字段类型必填说明modebulk \| synthetic是生成策略直接决定观测总量100,000 或 1,000numberOfDaysnumber是时间戳向前回退的天数决定数据的时间跨度numberOfRunsnumber否每个数据集执行的实验轮数默认 1多轮用于模拟多次实验对比时间戳的生成逻辑为以当前 UTC 日零点为锚向前按numberOfDays * 86400秒均匀铺开。数据集实验数据中run 内每个条目还会叠加 1–10 秒的随机偏移制造真实的时间波动data-generators.ts。扩展系统六条修改路线文档用一组 Checklist 给出了系统的扩展方法论这里结合源码补充每条路线的具体落点新增数据类型Adding New Data Types在 types.ts 添加接口如DatasetItemInput、FileContent的模式在DataGenerator添加生成方法参照generateSyntheticTraces的模式创建记录时统一使用createTrace/createObservation/createTraceScore/createDatasetRunItem工厂函数在ClickHouseQueryBuilder添加查询构建方法小数据用executeXxxInsert大数据用buildBulkXxxInsert在SeederOrchestrator添加编排方法并视需要接入executeFullSeed流程更新本文件依赖关系文档。新增文件来源Adding New File Sources在SeederOrchestrator.loadFileContent()中追加文件路径seeder-orchestrator.ts 已有对三个载荷文件读取 → 截断 → 注入的完整模板注意大文件会被截断以控制测试数据体积在DataGenerator添加处理逻辑需要时扩展FileContent接口。修改数据分布Changing Data Distribution修改DataGenerator中的生成方法例如调整randomBoolean(0.3)的 user/session 关联概率、randomInt(20, 200)的 token 区间更新 clickhouse-seed-constants.ts 中的名称/模型池常量先用小数据集验证将mode设为synthetic或减少观测数。修改 ID 生成Changing ID Generation文档强调 ID 是跨库关联的合同修改前必须逐项核对检查所有按 ID 查询 ClickHouse 的位置检查PostgreSQL 外键引用如dataset_run_item_id、dataset_id检查数据集 run item 与评估 trace 的创建逻辑执行在 seed-helpers.ts 中一致性地更新generateDatasetRunItemId、generateDatasetItemId、generateDatasetRunTraceId、generateEvalTraceId、generateEvalObservationId、generateEvalScoreId等函数。值得注意的是现有 ID 全部基于名称 序号 项目 ID 后 8 位 run 号构造不含日期——这是刻意设计配合 UTC 日锚点时间戳使同日重复运行可以原地覆盖数据。修改环境名Changing Environment Names检查所有按 environment 过滤的 ClickHouse 查询检查PostgreSQL 中 dataset 与 prompt 的 environment 字段检查前端环境过滤逻辑执行同步更新两套系统中的常量。当前三个环境名分别为langfuse-prompt-experiment数据集实验、langfuse-evaluation评估与default合成数据。修改数据结构Changing Data Structure检查ClickHouse 表结构兼容性注意 clickhouse-builder.ts 中的注释bulk INSERT 依赖位置列序迁移新增列时必须保持 SELECT 列表与表结构同步检查PostgreSQL 表关系检查API 响应序列化执行先改两边 schema 再改生成逻辑。同时还要评估新类型是否需要对应的 PostgreSQL 表、是否引入新的外键关系、UI 是否需要处理新数据类型——必要时规划数据库迁移。文件依赖与数据常量必备载荷文件文件用途截断规则nested_json.json大体积嵌套 JSON模拟结构化工具输出products数组截取前 3 项markdown.txtMarkdown 内容模拟文档分析类输入不截断chat_ml_json.jsonChatML 格式示例模拟多轮对话messages数组截取前 4 条这三个文件在loadFileContent()中加载并截断seeder-orchestrator.ts加载失败时降级为内置占位内容并输出 warning。合成数据中约 30% 的输入会使用重型 Markdown、其余使用 ChatML JSON输出则约 30% 使用嵌套 JSON。常量文件postgres-seed-constants.ts数据集SEED_DATASETS含国家首都、IPA 音标、数学运算等 7 个数据集、文本与 ChatML promptSEED_TEXT_PROMPTS、SEED_CHAT_ML_PROMPTS、prompt 版本SEED_PROMPT_VERSIONS、评估器模板与任务配置SEED_EVALUATOR_TEMPLATES、SEED_EVALUATOR_CONFIGS、EVAL_TRACE_COUNT 100、默认 API Key 等clickhouse-seed-constants.tsClickHouse 侧的名称池与模型池REALISTIC_TRACE_NAMES、REALISTIC_MODELS、REALISTIC_AGENT_NAMES、REALISTIC_TOOL_NAMES、REALISTIC_CHAIN_NAMES、REALISTIC_RETRIEVER_NAMES、REALISTIC_EVALUATOR_NAMES、REALISTIC_EMBEDDING_NAMES、REALISTIC_GUARDRAIL_NAMES等。进阶新一代场景式 CLI如果目标是快速在本地堆出能暴露前端问题的数据可以直接使用新一代场景式 CLI见 packages/shared/scripts/seeder/README.mdpnpm run seed -- doctor # 诊断本地栈并给出修复命令 pnpm run seed -- list # 列出所有场景与参数--json 供机器读取 pnpm run seed -- trace-tree --observations 5000 --breadth 1000 --v4 pnpm run seed -- many-traces --count 100000 --days 14 pnpm run seed -- long-session --traces 300 --observations-per-trace 8该 CLI 提供trace-tree巨型分叉观测树、agent-timelineLangGraph 风格迭代 agent、deep-chain深链观测、many-tracesbulk SQL 大规模列表、outlier-traffic带异常峰值的流量模拟、support-agent手写客服 Copilot 完整 trace等十余种场景公共参数包括--project、--environment、--seed确定性种子、--id-prefix、--dry-run与--json运行末尾会输出可验证的 JSON 摘要与 UI 深链。其确定性与完整性保证时间锚定、xxHash32加盐、uniqExact读回校验等与本文介绍的utils/批量构建器一脉相承二者共享clickhouse-builder.ts中的 bulk 构建逻辑。结语Langfuse Seeder 系统的设计精髓在于生成与写入分离、定制与批量并存、确定性与真实感兼顾DataGenerator负责内容的真实感ClickHouseQueryBuilder负责写入的性能与正确性SeederOrchestrator负责编排与容错bulk模式用哈希驱动的 SQL 换取量级synthetic模式用内存构造换取精细结构。无论你是要为本地产物填充演示数据、为评估器准备测试集还是为压测构造十万级观测都可以依据文档中的六条扩展路线在明确的修改边界内快速定制属于你自己的种子数据。【免费下载链接】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），仅供参考