MLflow entities 模块解析掌握 REST API 与 SDK 之间的数据实体层【免费下载链接】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.entities是 MLflow 面向 Python 开发者的实体层entity layer它将REST API返回的 JSON/Protobuf 数据统一投影为类型化的 Python 对象覆盖实验、Run、指标、参数、数据集、模型注册表、Tracing 与 Gateway 等全场景。本文以 mlflow.entities.rst 的 API 清单为主线结合源码逐类讲解这些实体的字段、语义与序列化机制帮助你在使用 MLflow 客户端编程、二次开发或阅读其源码时快速定位每一个数据对象并正确使用它们。一、entities 模块的定位REST API 返回对象的 Python 投影API 参考文档 mlflow.entities.rst 的核心是三个automodule指令它们分别把以下三个 Python 包的全部公开成员纳入文档生成范围mlflow.entities追踪与通用实体mlflow.entities.model_registry模型注册表实体排除了Prompt的自动文档生成因为Prompt已在更早的版本中被迁移与弃用mlflow.store.entities存储层辅助实体。模块自身在 mlflow/entities/init.py 的 docstring 中明确了其定位Themlflow.entitiesmodule defines entities returned by the MLflow REST API.也就是说无论你使用mlflow.tracking.MlflowClient、mlflow.fluent高层 API还是直接调用 REST 端点服务端返回的数据最终都会被反序列化为这里的实体对象。它们因此成为 SDK 与后端存储之间的事实数据契约。从实现上看所有实体都继承自 mlflow/entities/_mlflow_object.py 中的_MlflowObject并且大多数类都实现了成对的from_proto()/to_proto()方法用于和 Protobuf 消息定义于 mlflow/protos/service_pb2.py互相转换。这保证了「服务端存储 → REST 响应 → Python 对象 → 再序列化回 Protobuf」的完整闭环。__init__.py通过一份约 100 项的__all__列表统一导出所有实体且采用模块级__getattr__对EvaluationDataset做惰性加载以避免与mlflow.data形成循环导入——这也解释了为什么EvaluationDataset被刻意排除在__all__之外但依然可以通过from mlflow.entities import EvaluationDataset显式导入。二、追踪核心实体Experiment、Run 与 RunData1. Experiment一次实验的完整描述mlflow/entities/experiment.py 中的Experiment类承载了一个实验的全部元数据。其构造参数与属性对应如下属性类型说明experiment_idstr实验的唯一 IDnamestr实验名称模块内常量DEFAULT_EXPERIMENT_NAME Default对应默认实验名artifact_locationstr实验产物根目录的 URIlifecycle_stagestr生命周期阶段取值active或deletedtagsdict[str, str]实验标签构造时由ExperimentTag列表压平为字典creation_time/last_update_timeint \| None创建/更新时间毫秒级 Unix 时间戳可为Noneworkspacestr拥有该实验的工作空间名称trace_locationUnityCatalog \| None实验的 Trace 存储位置若配置effective_trace_archival_retentionstr \| None应用更广作用域覆盖后的生效 Trace 归档保留策略源码中有几个值得注意的细节tags在内部以{key: value}字典存储_add_tag()用于追加避免列表去重问题creation_time与last_update_time是 MLflow 1.29.0 才加入的字段from_proto()中通过proto.creation_time or None将旧版本实验的默认值 0 规范化为Nonetrace_location支持惰性解析如果构造时未显式传入会从标签如mlflow.experiment.databricks.trace.destination.path等由mlflow/utils/mlflow_tags.py定义的键中推断出UnityCatalog(catalog, schema, table_prefix)结构。2. Run一次运行的完整快照mlflow/entities/run.py 中的Run是访问频率最高的实体它由四个子对象聚合而成属性类型含义infoRunInfo运行元数据ID、状态、起止时间等dataRunData运行数据指标、参数、标签inputsRunInputs \| None运行输入数据集输入、模型输入outputsRunOutputs \| None运行输出模型输出等Run的构造器要求run_info不能为None否则抛出MlflowException。它同时提供to_proto()/from_proto()与to_dictionary()三种形态转换方便在网络传输与字典调试场景之间切换。3. RunInfo可搜索、可排序的运行元数据mlflow/entities/run_info.py 中的RunInfo定义了run_id、experiment_id、run_name、user_id、status、start_time、end_time、lifecycle_stage、artifact_uri等字段。时间字段均以「自 Unix 纪元起的毫秒数」表示from_proto()会把 proto2 中表示「无结束时间」的默认值 0 转换为None。该文件最有价值的设计是两个元类装饰器searchable_attribute标记可被search_runs等查询 API 过滤的属性run_id、run_name、user_id、status、start_time、end_time、artifact_uriorderable_attribute标记可排序属性且所有可搜索属性天然可排序。get_searchable_attributes()与get_orderable_attributes()两个类方法会动态收集这些装饰器标记的属性名供查询参数校验与文档生成使用。此外模块级函数check_run_is_active()会校验lifecycle_stage active否则抛出INVALID_PARAMETER_VALUE错误——这是很多写操作如记录指标、日志产物的前置条件。4. RunData指标、参数与标签的字典视图mlflow/entities/run_data.py 中的RunData内部维护_metric_objs原始列表同时提供metrics、params、tags三个dict[str, ...]属性。其metrics属性有一个容易忽略但重要的语义对每个指标键返回最新时间戳对应的值若同一最新时间戳下存在多个值则返回其中的最大值。这意味着RunData.metrics并非简单的「键→最新值」而是经过时间戳去重后的稳定视图与 UI 上展示的指标曲线语义保持一致。5. Metric / Param / RunTag三驾马车的字段契约mlflow/entities/metric.py 中的Metric核心字段为key、valuefloat、timestamp毫秒、step整数步数即 x 坐标扩展字段model_id、dataset_name、dataset_digest、run_id可选。构造函数带有一条硬性校验dataset_name与dataset_digest要么同时提供要么都不提供否则抛出MlflowException。同文件还定义了MetricWithRunId子类用于批量查询指标时携带 run 归属。Metric.from_dictionary()要求字典必须包含key、value、timestamp、step四个键。mlflow/entities/param.py 中的Param仅含key与value字符串。有一个贴心设计——如果进程内已加载pyspark.ml且传入的key是pyspark.ml.param.Param对象会自动提取其.name并字符串化 value方便 Spark 用户直接记录参数。mlflow/entities/run_tag.py 中的RunTag同样只有key/value两个字符串字段是所有标签类实体ExperimentTag、ModelVersionTag、RegisteredModelTag的通用范式。三、数据集与运行输入输出实体现代 MLflow 强调「数据血缘」追踪相关实体集中在Dataset、DatasetInput、InputTag、RunInputs、RunOutputs与Link等类中。mlflow/entities/run_inputs.py 中的RunInputs结构清晰dataset_inputsDatasetInput列表描述本次运行消费了哪些数据集model_inputsLoggedModelInput列表描述输入了哪些已记录的模型。to_dictionary()会将dataset_inputs递归转为字典便于调试与 JSON 序列化。配合DatasetRecord、DatasetRecordSource含DatasetRecordSourceType与Document等实体可以构建出「数据 → 模型 → 评估」的完整血缘链。此外Link实体用于表示实体间的关联引用EntityAssociationType则枚举了关联类型。四、模型注册表实体model_registry 子模块mlflow.entities.model_registry包见 mlflow/entities/model_registry/init.py专门承载模型注册表Model Registry相关实体实体作用RegisteredModel注册模型的元信息含名称、标签、描述、创建/更新时间、最新版本号等ModelVersion某个注册模型的特定版本含版本号、阶段Stage、来源 Run、状态等RegisteredModelAlias模型别名如champion、candidate用于语义化版本引用RegisteredModelTag/ModelVersionTag注册模型与模型版本的标签RegisteredModelSearch/ModelVersionSearch搜索 API 返回的精简摘要实体ModelVersionDeploymentJobState/RegisteredModelDeploymentJobState部署作业状态枚举Prompt/PromptVersion/PromptModelConfigPrompt 管理相关实体注意 API 文档生成时被exclude-members: Prompt排除因为该符号已在模块层通过from mlflow.entities.model_registry import Prompt导出这些实体与mlflow.models层的log_model、register_model以及MlflowClient的create_registered_model/create_model_version等方法配合使用构成模型生命周期的管理基础。五、store.entitiesPagedList 分页容器mlflow.store.entities包见 mlflow/store/entities/init.py目前只导出PagedList定义于 mlflow/store/entities/paged_list.py。PagedList继承自内置list唯一的增量是一个token字符串属性它由search_experiments、search_runs、search_registered_models、search_model_versions等分页查询 API 返回调用方可以将token传回原 API 的page_token参数以获取下一页数据token 为空或为None表示已无更多数据to_list()方法返回普通list便于在不需要翻页的场景下直接使用。from mlflow.tracking import MlflowClient client MlflowClient() page_token None while True: runs, page_token client.search_runs( experiment_ids[1], page_tokenpage_token, # 首次调用传入 None ) # runs 是 PagedList[Run]可直接迭代 for run in runs: print(run.info.run_id, run.info.status, run.data.metrics) if not page_token: break # 没有下一页六、Tracing 与新一代实体Span、Trace、Session 与 LoggedModel随着 MLflow 演进为「面向 Agent、LLM 与 ML 模型的 AI 工程平台」entities 层也加入了完整的可观测性实体可从 mlflow/entities/init.py 的导出列表确认Span 体系Span、LiveSpan、NoOpSpan、SpanType、SpanEvent、SpanLogLevel、SpanStatus、SpanStatusCode。SpanStatus与SpanStatusCode组合表达跨度状态SpanEvent记录跨度内发生的事件SpanLogLevel支持结构化日志级别Trace 体系Trace、TraceData、TraceInfo、TraceState、TraceLocation含TraceLocationType、MlflowExperimentLocation、InferenceTableLocation、UCSchemaLocation、UnityCatalog用于描述一条完整追踪链及其存储位置SessionSession实体承载对话/会话级上下文把多个 Trace 关联到同一交互会话LoggedModel 体系LoggedModel、LoggedModelInput、LoggedModelOutput、LoggedModelParameter、LoggedModelStatus、LoggedModelTag描述一次模型记录行为及其输入输出参数评估体系Assessment、AssessmentError、AssessmentSource含AssessmentSourceType、Expectation、Feedback、Issue含IssueSeverity、IssueStatus、IssueReference、ScorerVersion。这些实体与 mlflow/tracing 目录下的自动追踪实现以及mlflow.evaluate评估流程一一对应是排查 LLM 应用质量与成本问题时的数据基础。七、Gateway、MCP、Webhook 与工作空间实体平台化的能力同样体现在实体层Gateway 实体与 mlflow/gateway 服务对应GatewayEndpoint及其GatewayEndpointBinding、GatewayEndpointModelConfig、GatewayEndpointModelMapping、GatewayEndpointTag、GatewayModelDefinition、GatewayModelLinkageType、GatewayResourceType、RoutingStrategy、FallbackConfig、FallbackStrategy描述端点的模型路由与降级策略GatewayBudgetPolicy含BudgetAction、BudgetDuration、BudgetDurationUnit、BudgetTargetScope、BudgetUnit用于成本控制GatewayGuardrail含GuardrailAction、GuardrailStage用于安全护栏GatewaySecretInfo管理密钥信息MCP 实体MCPServer、MCPAccessEndpoint、MCPTool、MCPServerVersion含ConnectOptionSettings、MCPStatus、MCPRemoteTransportType支撑 Model Context Protocol 服务器接入Webhook 实体Webhook、WebhookEvent、WebhookStatus、WebhookTestResult用于事件通知工作空间实体Workspace、WorkspaceDeletionMode、TraceArchivalConfig管理多工作空间与 Trace 归档策略。需要说明的是以上实体的字段细节以各自源码文件为准例如 mlflow/entities/trace.py、mlflow/entities/span.py、mlflow/entities/gateway_endpoint.py 等本文仅从模块导出与命名角度勾勒其职责边界。八、配套枚举与辅助实体实体层还包含若干高频使用的枚举与常量类统一从mlflow.entities导出ViewType查询视图类型如ACTIVE_ONLY、DELETED_ONLY、ALL用于search_experiments/search_runsLifecycleStageactive/deleted生命周期常量RunInfo与Experiment均引用它RunStatusRUNNING、SCHEDULED、FINISHED、FAILED、KILLED等运行状态RunInfo.status的取值来源SourceType运行来源类型如NOTEBOOK、PROJECT、LOCAL、JOB等FileInfo产物文件/目录元信息路径、是否目录、文件大小由list_artifacts返回ExperimentTag实验标签实体结构与RunTag相同。九、实用建议如何阅读与使用 entities 层优先使用 Fluent API 与 MlflowClient日常开发中你通常不会直接构造这些实体而是从mlflow.log_*、client.search_runs()、client.get_run()等 API 的返回值中获得它们了解实体字段有助于正确解读返回对象。序列化形态三件套多数实体同时支持from_proto()、to_proto()与to_dictionary()部分还有from_dictionary()在调试、缓存或构建自定义存储层时可灵活选用。注意时间语义时间字段统一为毫秒级 Unix 时间戳RunInfo.end_time与Experiment.creation_time的None语义proto 默认值 0 →None在多版本兼容场景下需要留意。分页游标任何search_*返回的PagedList都携带token配合page_token参数即可完成全量遍历不要把它当普通 list 直接切片截断。以 API 文档与源码互证本模块的权威 API 说明由 mlflow.entities.rst 通过 Sphinx autodoc 自动生成字段细节以 mlflow/entities 与 mlflow/store/entities 下的源码为准继续深入可参考MlflowClient的完整用法mlflow/client.py与 REST API 文档docs/api_reference。结语mlflow.entities是连接 MLflow REST API 与 Python SDK 的枢纽层从最经典的Experiment/Run/Metric到模型注册表、数据集血缘、Tracing、Gateway 与 MCP 等新一代实体全部在此完成 Protobuf 与 Python 对象的双向转换。掌握这一层的数据结构与序列化契约你就能在客户端编程、日志解析、二次开发乃至贡献代码时准确理解 MLflow 内部的数据流。【免费下载链接】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 entities 模块解析：掌握 REST API 与 SDK 之间的数据实体层
MLflow entities 模块解析掌握 REST API 与 SDK 之间的数据实体层【免费下载链接】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.entities是 MLflow 面向 Python 开发者的实体层entity layer它将REST API返回的 JSON/Protobuf 数据统一投影为类型化的 Python 对象覆盖实验、Run、指标、参数、数据集、模型注册表、Tracing 与 Gateway 等全场景。本文以 mlflow.entities.rst 的 API 清单为主线结合源码逐类讲解这些实体的字段、语义与序列化机制帮助你在使用 MLflow 客户端编程、二次开发或阅读其源码时快速定位每一个数据对象并正确使用它们。一、entities 模块的定位REST API 返回对象的 Python 投影API 参考文档 mlflow.entities.rst 的核心是三个automodule指令它们分别把以下三个 Python 包的全部公开成员纳入文档生成范围mlflow.entities追踪与通用实体mlflow.entities.model_registry模型注册表实体排除了Prompt的自动文档生成因为Prompt已在更早的版本中被迁移与弃用mlflow.store.entities存储层辅助实体。模块自身在 mlflow/entities/init.py 的 docstring 中明确了其定位Themlflow.entitiesmodule defines entities returned by the MLflow REST API.也就是说无论你使用mlflow.tracking.MlflowClient、mlflow.fluent高层 API还是直接调用 REST 端点服务端返回的数据最终都会被反序列化为这里的实体对象。它们因此成为 SDK 与后端存储之间的事实数据契约。从实现上看所有实体都继承自 mlflow/entities/_mlflow_object.py 中的_MlflowObject并且大多数类都实现了成对的from_proto()/to_proto()方法用于和 Protobuf 消息定义于 mlflow/protos/service_pb2.py互相转换。这保证了「服务端存储 → REST 响应 → Python 对象 → 再序列化回 Protobuf」的完整闭环。__init__.py通过一份约 100 项的__all__列表统一导出所有实体且采用模块级__getattr__对EvaluationDataset做惰性加载以避免与mlflow.data形成循环导入——这也解释了为什么EvaluationDataset被刻意排除在__all__之外但依然可以通过from mlflow.entities import EvaluationDataset显式导入。二、追踪核心实体Experiment、Run 与 RunData1. Experiment一次实验的完整描述mlflow/entities/experiment.py 中的Experiment类承载了一个实验的全部元数据。其构造参数与属性对应如下属性类型说明experiment_idstr实验的唯一 IDnamestr实验名称模块内常量DEFAULT_EXPERIMENT_NAME Default对应默认实验名artifact_locationstr实验产物根目录的 URIlifecycle_stagestr生命周期阶段取值active或deletedtagsdict[str, str]实验标签构造时由ExperimentTag列表压平为字典creation_time/last_update_timeint \| None创建/更新时间毫秒级 Unix 时间戳可为Noneworkspacestr拥有该实验的工作空间名称trace_locationUnityCatalog \| None实验的 Trace 存储位置若配置effective_trace_archival_retentionstr \| None应用更广作用域覆盖后的生效 Trace 归档保留策略源码中有几个值得注意的细节tags在内部以{key: value}字典存储_add_tag()用于追加避免列表去重问题creation_time与last_update_time是 MLflow 1.29.0 才加入的字段from_proto()中通过proto.creation_time or None将旧版本实验的默认值 0 规范化为Nonetrace_location支持惰性解析如果构造时未显式传入会从标签如mlflow.experiment.databricks.trace.destination.path等由mlflow/utils/mlflow_tags.py定义的键中推断出UnityCatalog(catalog, schema, table_prefix)结构。2. Run一次运行的完整快照mlflow/entities/run.py 中的Run是访问频率最高的实体它由四个子对象聚合而成属性类型含义infoRunInfo运行元数据ID、状态、起止时间等dataRunData运行数据指标、参数、标签inputsRunInputs \| None运行输入数据集输入、模型输入outputsRunOutputs \| None运行输出模型输出等Run的构造器要求run_info不能为None否则抛出MlflowException。它同时提供to_proto()/from_proto()与to_dictionary()三种形态转换方便在网络传输与字典调试场景之间切换。3. RunInfo可搜索、可排序的运行元数据mlflow/entities/run_info.py 中的RunInfo定义了run_id、experiment_id、run_name、user_id、status、start_time、end_time、lifecycle_stage、artifact_uri等字段。时间字段均以「自 Unix 纪元起的毫秒数」表示from_proto()会把 proto2 中表示「无结束时间」的默认值 0 转换为None。该文件最有价值的设计是两个元类装饰器searchable_attribute标记可被search_runs等查询 API 过滤的属性run_id、run_name、user_id、status、start_time、end_time、artifact_uriorderable_attribute标记可排序属性且所有可搜索属性天然可排序。get_searchable_attributes()与get_orderable_attributes()两个类方法会动态收集这些装饰器标记的属性名供查询参数校验与文档生成使用。此外模块级函数check_run_is_active()会校验lifecycle_stage active否则抛出INVALID_PARAMETER_VALUE错误——这是很多写操作如记录指标、日志产物的前置条件。4. RunData指标、参数与标签的字典视图mlflow/entities/run_data.py 中的RunData内部维护_metric_objs原始列表同时提供metrics、params、tags三个dict[str, ...]属性。其metrics属性有一个容易忽略但重要的语义对每个指标键返回最新时间戳对应的值若同一最新时间戳下存在多个值则返回其中的最大值。这意味着RunData.metrics并非简单的「键→最新值」而是经过时间戳去重后的稳定视图与 UI 上展示的指标曲线语义保持一致。5. Metric / Param / RunTag三驾马车的字段契约mlflow/entities/metric.py 中的Metric核心字段为key、valuefloat、timestamp毫秒、step整数步数即 x 坐标扩展字段model_id、dataset_name、dataset_digest、run_id可选。构造函数带有一条硬性校验dataset_name与dataset_digest要么同时提供要么都不提供否则抛出MlflowException。同文件还定义了MetricWithRunId子类用于批量查询指标时携带 run 归属。Metric.from_dictionary()要求字典必须包含key、value、timestamp、step四个键。mlflow/entities/param.py 中的Param仅含key与value字符串。有一个贴心设计——如果进程内已加载pyspark.ml且传入的key是pyspark.ml.param.Param对象会自动提取其.name并字符串化 value方便 Spark 用户直接记录参数。mlflow/entities/run_tag.py 中的RunTag同样只有key/value两个字符串字段是所有标签类实体ExperimentTag、ModelVersionTag、RegisteredModelTag的通用范式。三、数据集与运行输入输出实体现代 MLflow 强调「数据血缘」追踪相关实体集中在Dataset、DatasetInput、InputTag、RunInputs、RunOutputs与Link等类中。mlflow/entities/run_inputs.py 中的RunInputs结构清晰dataset_inputsDatasetInput列表描述本次运行消费了哪些数据集model_inputsLoggedModelInput列表描述输入了哪些已记录的模型。to_dictionary()会将dataset_inputs递归转为字典便于调试与 JSON 序列化。配合DatasetRecord、DatasetRecordSource含DatasetRecordSourceType与Document等实体可以构建出「数据 → 模型 → 评估」的完整血缘链。此外Link实体用于表示实体间的关联引用EntityAssociationType则枚举了关联类型。四、模型注册表实体model_registry 子模块mlflow.entities.model_registry包见 mlflow/entities/model_registry/init.py专门承载模型注册表Model Registry相关实体实体作用RegisteredModel注册模型的元信息含名称、标签、描述、创建/更新时间、最新版本号等ModelVersion某个注册模型的特定版本含版本号、阶段Stage、来源 Run、状态等RegisteredModelAlias模型别名如champion、candidate用于语义化版本引用RegisteredModelTag/ModelVersionTag注册模型与模型版本的标签RegisteredModelSearch/ModelVersionSearch搜索 API 返回的精简摘要实体ModelVersionDeploymentJobState/RegisteredModelDeploymentJobState部署作业状态枚举Prompt/PromptVersion/PromptModelConfigPrompt 管理相关实体注意 API 文档生成时被exclude-members: Prompt排除因为该符号已在模块层通过from mlflow.entities.model_registry import Prompt导出这些实体与mlflow.models层的log_model、register_model以及MlflowClient的create_registered_model/create_model_version等方法配合使用构成模型生命周期的管理基础。五、store.entitiesPagedList 分页容器mlflow.store.entities包见 mlflow/store/entities/init.py目前只导出PagedList定义于 mlflow/store/entities/paged_list.py。PagedList继承自内置list唯一的增量是一个token字符串属性它由search_experiments、search_runs、search_registered_models、search_model_versions等分页查询 API 返回调用方可以将token传回原 API 的page_token参数以获取下一页数据token 为空或为None表示已无更多数据to_list()方法返回普通list便于在不需要翻页的场景下直接使用。from mlflow.tracking import MlflowClient client MlflowClient() page_token None while True: runs, page_token client.search_runs( experiment_ids[1], page_tokenpage_token, # 首次调用传入 None ) # runs 是 PagedList[Run]可直接迭代 for run in runs: print(run.info.run_id, run.info.status, run.data.metrics) if not page_token: break # 没有下一页六、Tracing 与新一代实体Span、Trace、Session 与 LoggedModel随着 MLflow 演进为「面向 Agent、LLM 与 ML 模型的 AI 工程平台」entities 层也加入了完整的可观测性实体可从 mlflow/entities/init.py 的导出列表确认Span 体系Span、LiveSpan、NoOpSpan、SpanType、SpanEvent、SpanLogLevel、SpanStatus、SpanStatusCode。SpanStatus与SpanStatusCode组合表达跨度状态SpanEvent记录跨度内发生的事件SpanLogLevel支持结构化日志级别Trace 体系Trace、TraceData、TraceInfo、TraceState、TraceLocation含TraceLocationType、MlflowExperimentLocation、InferenceTableLocation、UCSchemaLocation、UnityCatalog用于描述一条完整追踪链及其存储位置SessionSession实体承载对话/会话级上下文把多个 Trace 关联到同一交互会话LoggedModel 体系LoggedModel、LoggedModelInput、LoggedModelOutput、LoggedModelParameter、LoggedModelStatus、LoggedModelTag描述一次模型记录行为及其输入输出参数评估体系Assessment、AssessmentError、AssessmentSource含AssessmentSourceType、Expectation、Feedback、Issue含IssueSeverity、IssueStatus、IssueReference、ScorerVersion。这些实体与 mlflow/tracing 目录下的自动追踪实现以及mlflow.evaluate评估流程一一对应是排查 LLM 应用质量与成本问题时的数据基础。七、Gateway、MCP、Webhook 与工作空间实体平台化的能力同样体现在实体层Gateway 实体与 mlflow/gateway 服务对应GatewayEndpoint及其GatewayEndpointBinding、GatewayEndpointModelConfig、GatewayEndpointModelMapping、GatewayEndpointTag、GatewayModelDefinition、GatewayModelLinkageType、GatewayResourceType、RoutingStrategy、FallbackConfig、FallbackStrategy描述端点的模型路由与降级策略GatewayBudgetPolicy含BudgetAction、BudgetDuration、BudgetDurationUnit、BudgetTargetScope、BudgetUnit用于成本控制GatewayGuardrail含GuardrailAction、GuardrailStage用于安全护栏GatewaySecretInfo管理密钥信息MCP 实体MCPServer、MCPAccessEndpoint、MCPTool、MCPServerVersion含ConnectOptionSettings、MCPStatus、MCPRemoteTransportType支撑 Model Context Protocol 服务器接入Webhook 实体Webhook、WebhookEvent、WebhookStatus、WebhookTestResult用于事件通知工作空间实体Workspace、WorkspaceDeletionMode、TraceArchivalConfig管理多工作空间与 Trace 归档策略。需要说明的是以上实体的字段细节以各自源码文件为准例如 mlflow/entities/trace.py、mlflow/entities/span.py、mlflow/entities/gateway_endpoint.py 等本文仅从模块导出与命名角度勾勒其职责边界。八、配套枚举与辅助实体实体层还包含若干高频使用的枚举与常量类统一从mlflow.entities导出ViewType查询视图类型如ACTIVE_ONLY、DELETED_ONLY、ALL用于search_experiments/search_runsLifecycleStageactive/deleted生命周期常量RunInfo与Experiment均引用它RunStatusRUNNING、SCHEDULED、FINISHED、FAILED、KILLED等运行状态RunInfo.status的取值来源SourceType运行来源类型如NOTEBOOK、PROJECT、LOCAL、JOB等FileInfo产物文件/目录元信息路径、是否目录、文件大小由list_artifacts返回ExperimentTag实验标签实体结构与RunTag相同。九、实用建议如何阅读与使用 entities 层优先使用 Fluent API 与 MlflowClient日常开发中你通常不会直接构造这些实体而是从mlflow.log_*、client.search_runs()、client.get_run()等 API 的返回值中获得它们了解实体字段有助于正确解读返回对象。序列化形态三件套多数实体同时支持from_proto()、to_proto()与to_dictionary()部分还有from_dictionary()在调试、缓存或构建自定义存储层时可灵活选用。注意时间语义时间字段统一为毫秒级 Unix 时间戳RunInfo.end_time与Experiment.creation_time的None语义proto 默认值 0 →None在多版本兼容场景下需要留意。分页游标任何search_*返回的PagedList都携带token配合page_token参数即可完成全量遍历不要把它当普通 list 直接切片截断。以 API 文档与源码互证本模块的权威 API 说明由 mlflow.entities.rst 通过 Sphinx autodoc 自动生成字段细节以 mlflow/entities 与 mlflow/store/entities 下的源码为准继续深入可参考MlflowClient的完整用法mlflow/client.py与 REST API 文档docs/api_reference。结语mlflow.entities是连接 MLflow REST API 与 Python SDK 的枢纽层从最经典的Experiment/Run/Metric到模型注册表、数据集血缘、Tracing、Gateway 与 MCP 等新一代实体全部在此完成 Protobuf 与 Python 对象的双向转换。掌握这一层的数据结构与序列化契约你就能在客户端编程、日志解析、二次开发乃至贡献代码时准确理解 MLflow 内部的数据流。【免费下载链接】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），仅供参考
