MLflow Demo Data Framework 完全指南一键生成 GenAI 演示数据的架构、生成器与扩展实践【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflowMLflow 的 Demo Data Framework演示数据框架是 mlflow/demo 目录下的一个独立子模块用于为 MLflow 的 GenAI 功能Traces 追踪、Prompt 管理、LLM 评估、Issue 检测、Review Queue 人工标注等自动生成一套逼真的演示数据。本文基于仓库中的 demo/README.md 及其源码实现系统讲解该框架的三大用户入口、生成器架构、命名与版本管理约定、HTTP API 端点并给出从零新增一个自定义生成器的完整实战步骤帮助读者既能一键体验MLflow GenAI 能力也能深入理解乃至扩展这套数据生成机制。什么是 MLflow Demo Data FrameworkDemo Data Framework 是一套可插拔的演示数据生成框架它通过一个注册表 若干生成器Generator的结构把生成哪类演示数据抽象为一个个独立的BaseDemoGenerator子类。每个生成器负责一类 GenAI 功能的数据例如 prompts、traces、evaluation、judges、issues、review_queues 等统一挂载到名为MLflow Demo常量DEMO_EXPERIMENT_NAME MLflow Demo见 mlflow/demo/base.py的演示实验名下。框架的目标用户是想要快速体验 MLflow GenAI 界面的开发者运行一条命令或点击一个按钮服务器里就会出现一套包含历史版本、真实链路的 trace、评估结果、质量问题的演示数据无需自己编写任何业务代码。从源码结构看该框架的核心组件可以归纳为四层层次模块职责抽象层mlflow/demo/base.py定义DemoFeature枚举、DemoResult结果对象、抽象基类BaseDemoGenerator注册层mlflow/demo/registry.pyDemoRegistry注册表维护功能名 → 生成器类的映射调度层mlflow/demo/init.pygenerate_all_demos()统一编排所有生成器执行数据/实现层mlflow/demo/data.py mlflow/demo/generators演示数据的静态定义与各生成器的具体实现三个用户入口从 CLI 到 UI 按钮原文档明确列出了框架的三个用户入口下面结合源码逐一展开。入口一CLI 命令mlflow demomlflow demo是注册在mlflow根命令下的子命令见 mlflow/cli/init.py 中的cli.add_command(demo)完整实现在 mlflow/cli/demo.py。它的作用是启动一个临时服务器并预填充演示数据mlflow demo # 启动全新 demo 服务器自动找空闲端口 mlflow demo --no-browser # 启动但不自动打开浏览器 mlflow demo --port 5001 # 指定端口 mlflow demo --tracking-uri http://localhost:5000 # 向已运行的服务器填充演示数据该命令支持四个可选参数见 mlflow/cli/demo.py参数类型默认值说明--portint自动分配空闲端口仅当启动新服务器时生效若端口被占用会直接报错并提示换端口--tracking-uristr交互式询问指定已存在的 MLflow 服务器地址向其填充演示数据--no-browserboolflagFalse不自动打开浏览器--refreshboolflagFalse先删除已有演示数据再重新生成强制刷新源码揭示了两个有趣的行为细节交互式引导不带--tracking-uri运行时命令会先询问是否已有正在运行的 MLflow 服务器如果回答是再要求输入服务器 URL默认http://localhost:5000见 mlflow/cli/demo.py。持久化环境启动新服务器时会在当前目录创建./mlflow-demo/目录内含 SQLite 数据库mlflow.db和文件型 artifacts 目录并设置MLFLOW_TRACKING_URI指向该数据库见 mlflow/cli/demo.py。数据在多次重启间持久保留需要重新生成时用--refresh。入口二首页 Launch Demo 按钮MLflow Web UI 首页提供 Launch Demo 按钮用于向已存在的服务器追加演示数据。它背后调用的是服务端 HTTP API见下文API 端点一节由 mlflow/server/handlers.py 中的_generate_demo处理器实现先检查演示数据是否已存在幂等判断不存在才执行生成。入口三设置页 Clear Demo Data设置页的 Clear Demo Data 按钮调用_delete_demo处理器见 mlflow/server/handlers.py 起执行的是硬删除hard delete——彻底清除演示实验及全部关联数据等价于mlflow gc的效果而不是简单的软删除。架构总览模块结构与被刻意强调的顺序原文档给出的模块结构如下对应真实仓库 mlflow/demo 目录mlflow/demo/ ├── base.py # BaseDemoGenerator, DemoFeature 枚举, DemoResult ├── registry.py # DemoRegistry 生成器注册表 ├── data.py # 全部演示数据静态定义prompts/traces/issues 等 └── generators/ ├── __init__.py # 注册所有生成器顺序很关键 ├── prompts.py # Prompt 版本与别名 ├── traces.py # 各类模式的示例 traces ├── custom_view.py # 保存的自定义视图span 输入输出卡片 准确率表单 ├── saved_views.py # 保存的 Traces 表格视图 ├── evaluation.py # 评估 runs 与数据集 ├── judges.py # 注册的 LLM judges ├── issues.py # 关联失败 traces 的检测问题 └── review_queues.py # 审核队列、标签 schema 与队列条目注原文档的目录树中未列出data.py但它是框架中实际的数据字典文件集中定义了全部演示 prompts、traces、issues 数据下文会专门展开。生成器顺序为什么重要原文档明确指出一些生成器依赖其他生成器例如 traces 依赖 promptscustom view 和 evaluation 依赖 traces。在 mlflow/demo/generators/init.py 的注册代码注释中依赖关系被描述得非常清楚demo_registry.register(PromptsDemoGenerator) # prompts 必须先于 traces用于关联 demo_registry.register(TracesDemoGenerator) # traces 必须先于 evaluation被引用 demo_registry.register(CustomViewDemoGenerator) # custom view / saved views 依赖实验存在 demo_registry.register(SavedViewsDemoGenerator) demo_registry.register(EvaluationDemoGenerator) # 引用 traces 与 prompts demo_registry.register(JudgesDemoGenerator) # 独立可最后注册 demo_registry.register(IssuesDemoGenerator) # 引用 traces 上的失败评估 demo_registry.register(ReviewQueuesDemoGenerator) # 需要把 traces 挂到队列上调度函数generate_all_demos()见 mlflow/demo/init.py按注册顺序依次取出生成器逐个检查是否已生成含版本校验跳过已存在的对需要生成的执行generate()并记录版本号。它还接受可选的features参数用于只生成指定功能的数据子集。核心抽象DemoFeature、DemoResult 与 BaseDemoGenerator原文档的Adding a New Generator一节给出了一段示例代码理解这段代码的关键在于三个核心抽象全部定义在 mlflow/demo/base.py 中。DemoFeature功能的枚举标识DemoFeature是字符串枚举见 mlflow/demo/base.py当前包含 8 个值TRACES、EVALUATION、PROMPTS、JUDGES、ISSUES、REVIEW_QUEUES、CUSTOM_VIEW、SAVED_VIEWS。每个生成器通过name类属性声明自己对应哪个功能。DemoResult生成结果DemoResult是一个 dataclass见 mlflow/demo/base.py包含三个字段字段类型含义featureDemoFeature本次生成的演示功能entity_idslist[str]创建的实体 ID 列表如 trace ID、数据集名navigation_urlstr前端跳转路径用于生成后引导用户查看演示数据BaseDemoGenerator生成器的抽象基类抽象基类BaseDemoGenerator见 mlflow/demo/base.py规定了子类必须实现的协议class MyFeatureDemoGenerator(BaseDemoGenerator): name DemoFeature.MY_FEATURE # 必填声明功能未定义会抛 ValueError version 1 # 可选默认 1 def generate(self) - DemoResult: # 用 MLflow API 创建演示数据返回带 navigation_url 的 DemoResult ... def _data_exists(self) - bool: # 返回演示数据是否已存在不关心版本 ... def delete_demo(self) - None: # 清理演示数据可选基类默认是空操作 no-op ...基类还内置了两个重要的免费功能is_generated()见 mlflow/demo/base.py只有当数据存在且存储的版本号与当前生成器version一致时才返回True若版本不匹配会自动调用delete_demo()并返回False从而触发重新生成。版本持久化_get_stored_version()/store_version()通过实验 tagmlflow.demo.version.feature读写版本号见 mlflow/demo/base.py这正是Versioning一节提到的版本机制的实现细节。DemoRegistry生成器注册表DemoRegistry见 mlflow/demo/registry.py维护{DemoFeature: 生成器类}映射提供register()、get()、list_generators()等接口并拒绝重复注册同名生成器。模块级单例demo_registry被generate_all_demos()和 HTTP 处理器共享使用。八大生成器每类演示数据做什么结合源码逐一说明当前注册的 8 个生成器及其产出生成器类与版本号可在各文件中确认。1. PromptsDemoGenerator —— Prompt 版本历史与别名version 1基于 mlflow/demo/data.py 中定义的 3 个 Promptcustomer-support、document-summarizer、code-reviewer每个都有 3~4 个版本展示从简单模板到生产级 chat 格式的演进过程并为特定版本设置别名baseline、production等见 mlflow/demo/generators/prompts.py。生成后导航到#/prompts。2. TracesDemoGenerator —— 覆盖多种模式的示例 Tracesversion 3这是最复杂的生成器mlflow/demo/generators/traces.py为每个场景生成v1baseline和 v2改进后两套 traces模拟agent 优化前后的对比。共覆盖 5 种类型RAGembed_query → retrieve_docs → LLM三段式链路标注SpanType.EMBEDDING / RETRIEVER / LLMAgentReAct 风格LLM 调用与 TOOL 调用交替出现带 OpenAI 风格 function call 的 tool schemaPrompt关联 Prompt 模板展示渲染后的完整 prompt由PromptTemplateValues.render()完成变量插值Session多轮会话3 个 session共 7 轮对话带session_id/session_user/turn_indexMultimodal图像输入、图像生成DALL-E 风格、音频转录、TTS 四类多模态 span输入输出使用 OpenAI message 格式实现细节颇具巧思trace 的时间戳按确定性算法分布在过去 7 天内见 mlflow/demo/generators/traces.py使仪表盘的时间轴看起来真实有趋势token 数按约 4 字符 ≈ 1 token估算成本按三个模型gpt-5.2 / claude-sonnet-4-5 / gemini-3-pro各自的每百万 token 单价计算保证成本分布图有层次见 mlflow/demo/generators/traces.py。每套 21 条 trace共 42 条。3. CustomViewDemoGenerator —— 自定义视图version 1创建名为 Span review 的自定义视图用 A2UI 模板把每个 span 的输入/输出渲染成卡片并附带一个 5 档的 Accuracy 评分表单Super accurate 到 Not accurate见 mlflow/demo/generators/custom_view.py。其本质是写入实验 tag前缀MLFLOW_CUSTOM_VIEW_TAG_PREFIX。4. SavedViewsDemoGenerator —— 保存的 Traces 表格视图version 1向演示实验播种一个名为 MLflow conversations 的 V4 Traces 已保存视图视图中内置搜索词 MLflow、每页 50 条、指定列集合start_time、session、input、output、duration、state、tokens等状态状态经 zlib 压缩后 base64 编码写入实验 tag见 mlflow/demo/generators/saved_views.py。5. EvaluationDemoGenerator —— 评估运行与数据集version 2在演示实验下创建 3 个数据集trace 级、baseline 会话级、改进会话级并跑出 3 个评估 runtrace-level-evaluation、baseline-session-evaluation、improved-session-evaluation见 mlflow/demo/generators/evaluation.py。其核心是 4 个确定性伪评分器relevance / correctness / groundedness / safety输出越长越详细通过率越高从而模拟改进后的响应自然得分更高的真实场景见 mlflow/demo/generators/evaluation.py。同时还会给每条 trace 打上基于EXPECTED_ANSWERS映射的 ground-truth expectationAssessmentSource为 HUMAN 类型。6. JudgesDemoGenerator —— 注册的 LLM Judgesversion 1用make_judge()注册 4 个与评估评分器同名的 judgemlflow-demo.judges.relevance/.correctness/.groundedness/.safety每个 judge 都带自然语言指令见 mlflow/demo/generators/judges.py。刻意与 evaluation 的评分器同名让Judges UI 与评估结果讲同一个故事。7. IssuesDemoGenerator —— 关联失败 traces 的检测问题version 4从评估结果中找出实际失败feedback 值为 no的 v1 traces按评估类型聚合生成 issueLow Relevance Responses、Incorrect Information、Ungrounded Claims、Potential Safety Concerns每个 issue 带严重级别MEDIUM/HIGH、根因分类如 prompt_engineering、model_hallucination与描述并链接最多 5 条失败 trace见 mlflow/demo/generators/issues.py。issue 定义与根因解释来自 mlflow/demo/data.py 中的ASSESSMENT_TO_ISSUE与ROOT_CAUSE_EXPLANATIONS。8. ReviewQueuesDemoGenerator —— 审核队列与标签 Schemaversion 1创建名为 Demo Response Review 的自定义队列定义 3 个标签 schemaresponse_quality的 Excellent/Good/Fair/Poor 四档评分、is_helpful的 Pass/Fail、correct_answer的文本期望答案并为alice、bob及默认查看者各建一个个人用户队列附上带混合审核进度的 traces见 mlflow/demo/generators/review_queues.py。演示数据命名约定原文档的命名约定表格与 mlflow/demo/base.py 中的常量一一对应实体类型约定示例ExperimentDEMO_EXPERIMENT_NAME常量MLflow DemoPrompts{DEMO_PROMPT_PREFIX}.name前缀常量值为mlflow-demomlflow-demo.prompts.customer-supportJudges{DEMO_PROMPT_PREFIX}.judges.*mlflow-demo.judges.relevanceMetadatamlflow.demo.*mlflow.demo.version.traces、mlflow.demo.trace_type、mlflow.demo.start_time_ms等从源码看元数据约定还更细版本 tag 具体格式是mlflow.demo.version.feature见 mlflow/demo/base.pytrace 元数据还包括mlflow.demo.versionv1/v2、mlflow.demo.trace_typerag/agent/prompt/session、mlflow.demo.session.turn等见 mlflow/demo/generators/traces.py。保持统一前缀是各生成器幂等检查name LIKE mlflow-demo.%能够工作的前提。版本管理旧数据自动失效与重建原文档的 Versioning 一节所述机制其实现就是上文BaseDemoGenerator.is_generated()的逻辑mlflow/demo/base.py每个生成器都有version属性。当版本变化时旧的演示数据会被自动删除并重新生成。当修改导致旧数据与当前 UI 不兼容时应提升版本号。整个流程是启动/触发生成时 →is_generated()检查数据是否存在 → 读取实验 tag 中的存储版本 → 若与当前version不符则调用delete_demo()清空 → 返回 False 触发重新生成 → 生成成功后store_version()写回新版本号。实际仓库中各生成器版本从 1 到 4 不等traces 为 3、evaluation 为 2、issues 为 4正是该机制运作的例证。HTTP API 端点幂等生成与硬删除原文档的 API 端点表对应的服务端实现位于 mlflow/server/handlers.pyEndpointMethod说明实现要点/ajax-api/3.0/mlflow/demo/generatePOST生成演示数据幂等_generate_demo全部数据已存在时直接返回status: exists否则加锁执行generate_all_demos()/ajax-api/3.0/mlflow/demo/deletePOST硬删除全部演示数据_delete_demo彻底删除演示实验及关联数据_generate_demo支持可选的 JSON body如{features: [traces, prompts]}只生成指定功能响应中会返回experiment_id、features_generated列表和navigation_url见 mlflow/server/handlers.py。源码还特别用了一个线程锁_demo_generate_lock来串行化并发请求——因为生成过程会临时修改进程级的环境变量MLFLOW_WORKSPACE并发执行可能产生竞态见 mlflow/server/handlers.py。两个端点均已通过 tests/demo/test_api_routes.py 覆盖测试。扩展实践新增一个自定义生成器原文档给出的三步流程结合源码补充细节后如下。第 1 步在 DemoFeature 枚举中新增功能在 mlflow/demo/base.py 的DemoFeature中加入新值例如MY_FEATURE my_feature。第 2 步创建继承 BaseDemoGenerator 的生成器类class MyFeatureDemoGenerator(BaseDemoGenerator): name DemoFeature.MY_FEATURE version 1 def generate(self) - DemoResult: # 用 MLflow API 创建演示数据 # 返回 DemoResult其中 navigation_url 指向前端展示页 return DemoResult( featureself.name, entity_ids[...], navigation_url#/experiments/xxx, ) def _data_exists(self) - bool: # 返回 True 表示演示数据已存在版本校验由基类负责 return False def delete_demo(self) - None: # 清理演示数据可选基类默认空操作 pass编写时需要注意的源码级要点name类属性必须定义否则构造函数会抛ValueError见 mlflow/demo/base.py生成数据前建议先调用_restore_experiment_if_deleted()恢复被软删除的演示实验参考 mlflow/demo/generators/prompts.py如果生成器依赖其他生成器的产出可以在generate()里先实例化依赖生成器并调用is_generated()/generate()参考 mlflow/demo/generators/evaluation.py。第 3 步在 generators/init.py 中注册注意依赖顺序from mlflow.demo.generators.my_feature import MyFeatureDemoGenerator ... demo_registry.register(MyFeatureDemoGenerator) # 放在其依赖的生成器之后注册顺序即执行顺序若新生成器依赖 traces就必须注册在TracesDemoGenerator之后同时注册表会拒绝同名重复注册见 mlflow/demo/registry.py。注册完成后新生成器会自动被mlflow demoCLI、generate_all_demos()以及/mlflow/demo/generateAPI 统一调度无需改动其他代码。测试如何验证演示数据框架原文档给出的测试命令为uv run pytest tests/demo/ -vmlflow/demo 模块配套了完善的测试套件位于 tests/demo 目录覆盖了框架的各个层面测试文件覆盖范围test_base.py/test_registry.py抽象基类与注册表的单元行为test_generate.py/test_demo_integration.pygenerate_all_demos()调度与端到端生成test_api_routes.pygenerate/delete 两个 HTTP 端点的行为test_cli.pymlflow demo命令的参数处理与执行路径test_traces_generator.py等按生成器划分的文件各生成器产出的数据正确性总结MLflow Demo Data Framework 通过注册表 生成器 版本化幂等的简洁架构把复杂的 GenAI 演示数据prompts、traces、评估、judges、issues、审核队列、自定义视图标准化为可插拔的模块。开发者可以零成本通过mlflow demo命令或 UI 按钮获得一套完整的演示环境也可以遵循三步注册法快速扩展新的数据生成器复用到generate_all_demos()的统一调度之中。若想继续深入建议从 mlflow/demo/base.py 的抽象协议读起再对照 mlflow/demo/generators/traces.py 理解最复杂的 trace 生成细节最后用 tests/demo 中的测试用例验证自己的理解。【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MLflow Demo Data Framework 完全指南：一键生成 GenAI 演示数据的架构、生成器与扩展实践
MLflow Demo Data Framework 完全指南一键生成 GenAI 演示数据的架构、生成器与扩展实践【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflowMLflow 的 Demo Data Framework演示数据框架是 mlflow/demo 目录下的一个独立子模块用于为 MLflow 的 GenAI 功能Traces 追踪、Prompt 管理、LLM 评估、Issue 检测、Review Queue 人工标注等自动生成一套逼真的演示数据。本文基于仓库中的 demo/README.md 及其源码实现系统讲解该框架的三大用户入口、生成器架构、命名与版本管理约定、HTTP API 端点并给出从零新增一个自定义生成器的完整实战步骤帮助读者既能一键体验MLflow GenAI 能力也能深入理解乃至扩展这套数据生成机制。什么是 MLflow Demo Data FrameworkDemo Data Framework 是一套可插拔的演示数据生成框架它通过一个注册表 若干生成器Generator的结构把生成哪类演示数据抽象为一个个独立的BaseDemoGenerator子类。每个生成器负责一类 GenAI 功能的数据例如 prompts、traces、evaluation、judges、issues、review_queues 等统一挂载到名为MLflow Demo常量DEMO_EXPERIMENT_NAME MLflow Demo见 mlflow/demo/base.py的演示实验名下。框架的目标用户是想要快速体验 MLflow GenAI 界面的开发者运行一条命令或点击一个按钮服务器里就会出现一套包含历史版本、真实链路的 trace、评估结果、质量问题的演示数据无需自己编写任何业务代码。从源码结构看该框架的核心组件可以归纳为四层层次模块职责抽象层mlflow/demo/base.py定义DemoFeature枚举、DemoResult结果对象、抽象基类BaseDemoGenerator注册层mlflow/demo/registry.pyDemoRegistry注册表维护功能名 → 生成器类的映射调度层mlflow/demo/init.pygenerate_all_demos()统一编排所有生成器执行数据/实现层mlflow/demo/data.py mlflow/demo/generators演示数据的静态定义与各生成器的具体实现三个用户入口从 CLI 到 UI 按钮原文档明确列出了框架的三个用户入口下面结合源码逐一展开。入口一CLI 命令mlflow demomlflow demo是注册在mlflow根命令下的子命令见 mlflow/cli/init.py 中的cli.add_command(demo)完整实现在 mlflow/cli/demo.py。它的作用是启动一个临时服务器并预填充演示数据mlflow demo # 启动全新 demo 服务器自动找空闲端口 mlflow demo --no-browser # 启动但不自动打开浏览器 mlflow demo --port 5001 # 指定端口 mlflow demo --tracking-uri http://localhost:5000 # 向已运行的服务器填充演示数据该命令支持四个可选参数见 mlflow/cli/demo.py参数类型默认值说明--portint自动分配空闲端口仅当启动新服务器时生效若端口被占用会直接报错并提示换端口--tracking-uristr交互式询问指定已存在的 MLflow 服务器地址向其填充演示数据--no-browserboolflagFalse不自动打开浏览器--refreshboolflagFalse先删除已有演示数据再重新生成强制刷新源码揭示了两个有趣的行为细节交互式引导不带--tracking-uri运行时命令会先询问是否已有正在运行的 MLflow 服务器如果回答是再要求输入服务器 URL默认http://localhost:5000见 mlflow/cli/demo.py。持久化环境启动新服务器时会在当前目录创建./mlflow-demo/目录内含 SQLite 数据库mlflow.db和文件型 artifacts 目录并设置MLFLOW_TRACKING_URI指向该数据库见 mlflow/cli/demo.py。数据在多次重启间持久保留需要重新生成时用--refresh。入口二首页 Launch Demo 按钮MLflow Web UI 首页提供 Launch Demo 按钮用于向已存在的服务器追加演示数据。它背后调用的是服务端 HTTP API见下文API 端点一节由 mlflow/server/handlers.py 中的_generate_demo处理器实现先检查演示数据是否已存在幂等判断不存在才执行生成。入口三设置页 Clear Demo Data设置页的 Clear Demo Data 按钮调用_delete_demo处理器见 mlflow/server/handlers.py 起执行的是硬删除hard delete——彻底清除演示实验及全部关联数据等价于mlflow gc的效果而不是简单的软删除。架构总览模块结构与被刻意强调的顺序原文档给出的模块结构如下对应真实仓库 mlflow/demo 目录mlflow/demo/ ├── base.py # BaseDemoGenerator, DemoFeature 枚举, DemoResult ├── registry.py # DemoRegistry 生成器注册表 ├── data.py # 全部演示数据静态定义prompts/traces/issues 等 └── generators/ ├── __init__.py # 注册所有生成器顺序很关键 ├── prompts.py # Prompt 版本与别名 ├── traces.py # 各类模式的示例 traces ├── custom_view.py # 保存的自定义视图span 输入输出卡片 准确率表单 ├── saved_views.py # 保存的 Traces 表格视图 ├── evaluation.py # 评估 runs 与数据集 ├── judges.py # 注册的 LLM judges ├── issues.py # 关联失败 traces 的检测问题 └── review_queues.py # 审核队列、标签 schema 与队列条目注原文档的目录树中未列出data.py但它是框架中实际的数据字典文件集中定义了全部演示 prompts、traces、issues 数据下文会专门展开。生成器顺序为什么重要原文档明确指出一些生成器依赖其他生成器例如 traces 依赖 promptscustom view 和 evaluation 依赖 traces。在 mlflow/demo/generators/init.py 的注册代码注释中依赖关系被描述得非常清楚demo_registry.register(PromptsDemoGenerator) # prompts 必须先于 traces用于关联 demo_registry.register(TracesDemoGenerator) # traces 必须先于 evaluation被引用 demo_registry.register(CustomViewDemoGenerator) # custom view / saved views 依赖实验存在 demo_registry.register(SavedViewsDemoGenerator) demo_registry.register(EvaluationDemoGenerator) # 引用 traces 与 prompts demo_registry.register(JudgesDemoGenerator) # 独立可最后注册 demo_registry.register(IssuesDemoGenerator) # 引用 traces 上的失败评估 demo_registry.register(ReviewQueuesDemoGenerator) # 需要把 traces 挂到队列上调度函数generate_all_demos()见 mlflow/demo/init.py按注册顺序依次取出生成器逐个检查是否已生成含版本校验跳过已存在的对需要生成的执行generate()并记录版本号。它还接受可选的features参数用于只生成指定功能的数据子集。核心抽象DemoFeature、DemoResult 与 BaseDemoGenerator原文档的Adding a New Generator一节给出了一段示例代码理解这段代码的关键在于三个核心抽象全部定义在 mlflow/demo/base.py 中。DemoFeature功能的枚举标识DemoFeature是字符串枚举见 mlflow/demo/base.py当前包含 8 个值TRACES、EVALUATION、PROMPTS、JUDGES、ISSUES、REVIEW_QUEUES、CUSTOM_VIEW、SAVED_VIEWS。每个生成器通过name类属性声明自己对应哪个功能。DemoResult生成结果DemoResult是一个 dataclass见 mlflow/demo/base.py包含三个字段字段类型含义featureDemoFeature本次生成的演示功能entity_idslist[str]创建的实体 ID 列表如 trace ID、数据集名navigation_urlstr前端跳转路径用于生成后引导用户查看演示数据BaseDemoGenerator生成器的抽象基类抽象基类BaseDemoGenerator见 mlflow/demo/base.py规定了子类必须实现的协议class MyFeatureDemoGenerator(BaseDemoGenerator): name DemoFeature.MY_FEATURE # 必填声明功能未定义会抛 ValueError version 1 # 可选默认 1 def generate(self) - DemoResult: # 用 MLflow API 创建演示数据返回带 navigation_url 的 DemoResult ... def _data_exists(self) - bool: # 返回演示数据是否已存在不关心版本 ... def delete_demo(self) - None: # 清理演示数据可选基类默认是空操作 no-op ...基类还内置了两个重要的免费功能is_generated()见 mlflow/demo/base.py只有当数据存在且存储的版本号与当前生成器version一致时才返回True若版本不匹配会自动调用delete_demo()并返回False从而触发重新生成。版本持久化_get_stored_version()/store_version()通过实验 tagmlflow.demo.version.feature读写版本号见 mlflow/demo/base.py这正是Versioning一节提到的版本机制的实现细节。DemoRegistry生成器注册表DemoRegistry见 mlflow/demo/registry.py维护{DemoFeature: 生成器类}映射提供register()、get()、list_generators()等接口并拒绝重复注册同名生成器。模块级单例demo_registry被generate_all_demos()和 HTTP 处理器共享使用。八大生成器每类演示数据做什么结合源码逐一说明当前注册的 8 个生成器及其产出生成器类与版本号可在各文件中确认。1. PromptsDemoGenerator —— Prompt 版本历史与别名version 1基于 mlflow/demo/data.py 中定义的 3 个 Promptcustomer-support、document-summarizer、code-reviewer每个都有 3~4 个版本展示从简单模板到生产级 chat 格式的演进过程并为特定版本设置别名baseline、production等见 mlflow/demo/generators/prompts.py。生成后导航到#/prompts。2. TracesDemoGenerator —— 覆盖多种模式的示例 Tracesversion 3这是最复杂的生成器mlflow/demo/generators/traces.py为每个场景生成v1baseline和 v2改进后两套 traces模拟agent 优化前后的对比。共覆盖 5 种类型RAGembed_query → retrieve_docs → LLM三段式链路标注SpanType.EMBEDDING / RETRIEVER / LLMAgentReAct 风格LLM 调用与 TOOL 调用交替出现带 OpenAI 风格 function call 的 tool schemaPrompt关联 Prompt 模板展示渲染后的完整 prompt由PromptTemplateValues.render()完成变量插值Session多轮会话3 个 session共 7 轮对话带session_id/session_user/turn_indexMultimodal图像输入、图像生成DALL-E 风格、音频转录、TTS 四类多模态 span输入输出使用 OpenAI message 格式实现细节颇具巧思trace 的时间戳按确定性算法分布在过去 7 天内见 mlflow/demo/generators/traces.py使仪表盘的时间轴看起来真实有趋势token 数按约 4 字符 ≈ 1 token估算成本按三个模型gpt-5.2 / claude-sonnet-4-5 / gemini-3-pro各自的每百万 token 单价计算保证成本分布图有层次见 mlflow/demo/generators/traces.py。每套 21 条 trace共 42 条。3. CustomViewDemoGenerator —— 自定义视图version 1创建名为 Span review 的自定义视图用 A2UI 模板把每个 span 的输入/输出渲染成卡片并附带一个 5 档的 Accuracy 评分表单Super accurate 到 Not accurate见 mlflow/demo/generators/custom_view.py。其本质是写入实验 tag前缀MLFLOW_CUSTOM_VIEW_TAG_PREFIX。4. SavedViewsDemoGenerator —— 保存的 Traces 表格视图version 1向演示实验播种一个名为 MLflow conversations 的 V4 Traces 已保存视图视图中内置搜索词 MLflow、每页 50 条、指定列集合start_time、session、input、output、duration、state、tokens等状态状态经 zlib 压缩后 base64 编码写入实验 tag见 mlflow/demo/generators/saved_views.py。5. EvaluationDemoGenerator —— 评估运行与数据集version 2在演示实验下创建 3 个数据集trace 级、baseline 会话级、改进会话级并跑出 3 个评估 runtrace-level-evaluation、baseline-session-evaluation、improved-session-evaluation见 mlflow/demo/generators/evaluation.py。其核心是 4 个确定性伪评分器relevance / correctness / groundedness / safety输出越长越详细通过率越高从而模拟改进后的响应自然得分更高的真实场景见 mlflow/demo/generators/evaluation.py。同时还会给每条 trace 打上基于EXPECTED_ANSWERS映射的 ground-truth expectationAssessmentSource为 HUMAN 类型。6. JudgesDemoGenerator —— 注册的 LLM Judgesversion 1用make_judge()注册 4 个与评估评分器同名的 judgemlflow-demo.judges.relevance/.correctness/.groundedness/.safety每个 judge 都带自然语言指令见 mlflow/demo/generators/judges.py。刻意与 evaluation 的评分器同名让Judges UI 与评估结果讲同一个故事。7. IssuesDemoGenerator —— 关联失败 traces 的检测问题version 4从评估结果中找出实际失败feedback 值为 no的 v1 traces按评估类型聚合生成 issueLow Relevance Responses、Incorrect Information、Ungrounded Claims、Potential Safety Concerns每个 issue 带严重级别MEDIUM/HIGH、根因分类如 prompt_engineering、model_hallucination与描述并链接最多 5 条失败 trace见 mlflow/demo/generators/issues.py。issue 定义与根因解释来自 mlflow/demo/data.py 中的ASSESSMENT_TO_ISSUE与ROOT_CAUSE_EXPLANATIONS。8. ReviewQueuesDemoGenerator —— 审核队列与标签 Schemaversion 1创建名为 Demo Response Review 的自定义队列定义 3 个标签 schemaresponse_quality的 Excellent/Good/Fair/Poor 四档评分、is_helpful的 Pass/Fail、correct_answer的文本期望答案并为alice、bob及默认查看者各建一个个人用户队列附上带混合审核进度的 traces见 mlflow/demo/generators/review_queues.py。演示数据命名约定原文档的命名约定表格与 mlflow/demo/base.py 中的常量一一对应实体类型约定示例ExperimentDEMO_EXPERIMENT_NAME常量MLflow DemoPrompts{DEMO_PROMPT_PREFIX}.name前缀常量值为mlflow-demomlflow-demo.prompts.customer-supportJudges{DEMO_PROMPT_PREFIX}.judges.*mlflow-demo.judges.relevanceMetadatamlflow.demo.*mlflow.demo.version.traces、mlflow.demo.trace_type、mlflow.demo.start_time_ms等从源码看元数据约定还更细版本 tag 具体格式是mlflow.demo.version.feature见 mlflow/demo/base.pytrace 元数据还包括mlflow.demo.versionv1/v2、mlflow.demo.trace_typerag/agent/prompt/session、mlflow.demo.session.turn等见 mlflow/demo/generators/traces.py。保持统一前缀是各生成器幂等检查name LIKE mlflow-demo.%能够工作的前提。版本管理旧数据自动失效与重建原文档的 Versioning 一节所述机制其实现就是上文BaseDemoGenerator.is_generated()的逻辑mlflow/demo/base.py每个生成器都有version属性。当版本变化时旧的演示数据会被自动删除并重新生成。当修改导致旧数据与当前 UI 不兼容时应提升版本号。整个流程是启动/触发生成时 →is_generated()检查数据是否存在 → 读取实验 tag 中的存储版本 → 若与当前version不符则调用delete_demo()清空 → 返回 False 触发重新生成 → 生成成功后store_version()写回新版本号。实际仓库中各生成器版本从 1 到 4 不等traces 为 3、evaluation 为 2、issues 为 4正是该机制运作的例证。HTTP API 端点幂等生成与硬删除原文档的 API 端点表对应的服务端实现位于 mlflow/server/handlers.pyEndpointMethod说明实现要点/ajax-api/3.0/mlflow/demo/generatePOST生成演示数据幂等_generate_demo全部数据已存在时直接返回status: exists否则加锁执行generate_all_demos()/ajax-api/3.0/mlflow/demo/deletePOST硬删除全部演示数据_delete_demo彻底删除演示实验及关联数据_generate_demo支持可选的 JSON body如{features: [traces, prompts]}只生成指定功能响应中会返回experiment_id、features_generated列表和navigation_url见 mlflow/server/handlers.py。源码还特别用了一个线程锁_demo_generate_lock来串行化并发请求——因为生成过程会临时修改进程级的环境变量MLFLOW_WORKSPACE并发执行可能产生竞态见 mlflow/server/handlers.py。两个端点均已通过 tests/demo/test_api_routes.py 覆盖测试。扩展实践新增一个自定义生成器原文档给出的三步流程结合源码补充细节后如下。第 1 步在 DemoFeature 枚举中新增功能在 mlflow/demo/base.py 的DemoFeature中加入新值例如MY_FEATURE my_feature。第 2 步创建继承 BaseDemoGenerator 的生成器类class MyFeatureDemoGenerator(BaseDemoGenerator): name DemoFeature.MY_FEATURE version 1 def generate(self) - DemoResult: # 用 MLflow API 创建演示数据 # 返回 DemoResult其中 navigation_url 指向前端展示页 return DemoResult( featureself.name, entity_ids[...], navigation_url#/experiments/xxx, ) def _data_exists(self) - bool: # 返回 True 表示演示数据已存在版本校验由基类负责 return False def delete_demo(self) - None: # 清理演示数据可选基类默认空操作 pass编写时需要注意的源码级要点name类属性必须定义否则构造函数会抛ValueError见 mlflow/demo/base.py生成数据前建议先调用_restore_experiment_if_deleted()恢复被软删除的演示实验参考 mlflow/demo/generators/prompts.py如果生成器依赖其他生成器的产出可以在generate()里先实例化依赖生成器并调用is_generated()/generate()参考 mlflow/demo/generators/evaluation.py。第 3 步在 generators/init.py 中注册注意依赖顺序from mlflow.demo.generators.my_feature import MyFeatureDemoGenerator ... demo_registry.register(MyFeatureDemoGenerator) # 放在其依赖的生成器之后注册顺序即执行顺序若新生成器依赖 traces就必须注册在TracesDemoGenerator之后同时注册表会拒绝同名重复注册见 mlflow/demo/registry.py。注册完成后新生成器会自动被mlflow demoCLI、generate_all_demos()以及/mlflow/demo/generateAPI 统一调度无需改动其他代码。测试如何验证演示数据框架原文档给出的测试命令为uv run pytest tests/demo/ -vmlflow/demo 模块配套了完善的测试套件位于 tests/demo 目录覆盖了框架的各个层面测试文件覆盖范围test_base.py/test_registry.py抽象基类与注册表的单元行为test_generate.py/test_demo_integration.pygenerate_all_demos()调度与端到端生成test_api_routes.pygenerate/delete 两个 HTTP 端点的行为test_cli.pymlflow demo命令的参数处理与执行路径test_traces_generator.py等按生成器划分的文件各生成器产出的数据正确性总结MLflow Demo Data Framework 通过注册表 生成器 版本化幂等的简洁架构把复杂的 GenAI 演示数据prompts、traces、评估、judges、issues、审核队列、自定义视图标准化为可插拔的模块。开发者可以零成本通过mlflow demo命令或 UI 按钮获得一套完整的演示环境也可以遵循三步注册法快速扩展新的数据生成器复用到generate_all_demos()的统一调度之中。若想继续深入建议从 mlflow/demo/base.py 的抽象协议读起再对照 mlflow/demo/generators/traces.py 理解最复杂的 trace 生成细节最后用 tests/demo 中的测试用例验证自己的理解。【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考