5. 核心模块：Tracking API、Model Registry、Artifact、Flavor 与 GenAI 组件

一句话理解：MLflow 的核心实现可以分成三层——面向用户的 Fluent/Client API、负责元数据的 Tracking/Registry Service、负责文件存储的 Artifact Repository，再加上 Model Flavor 把各种框架模型统一封装；MLflow 3.x 又新增了 mlflow.tracing / mlflow.genai / mlflow.gateway 三个面向 GenAI 的模块。

5.1 模块分层

┌──────────────────────────────────────────────────────────────────────┐
│              用户层：Fluent API / MlflowClient / @mlflow.trace        │
│         mlflow.log_param() / start_run() / autolog()                 │
└───────────────────────────────┬──────────────────────────────────────┘
                                │
                                ▼
┌──────────────────────────────────────────────────────────────────────┐
│         服务层：Tracking / Model Registry / Tracing / Gateway         │
│   mlflow.tracking._tracking_service / _model_registry                │
│   mlflow.store.tracking / mlflow.store.model_registry                │
│   mlflow.tracing（OTel 摄取、span 处理）                              │
│   mlflow.gateway（LLM 路由、预算、Guardrails）                        │
└───────────────────────────────┬──────────────────────────────────────┘
                                │
            ┌───────────────────┴───────────────────┐
            │                                       │
            ▼                                       ▼
┌───────────────────────────┐           ┌───────────────────────────┐
│   Backend Store (SQL)     │           │   Artifact Repository     │
│  SQLite / PostgreSQL /    │           │  Local / S3 / GCS / Azure │
│  MySQL / SQL Server       │           │                           │
│  + traces/prompts/scorers │           │  + trace 多模态附件        │
└───────────────────────────┘           └───────────────────────────┘

5.2 Fluent API

mlflow/tracking/fluent.py 提供高阶 API，是大多数用户直接接触的一层。

关键函数

函数	作用
`mlflow.set_tracking_uri(uri)`	设置 Tracking Server 地址
`mlflow.set_experiment(name)`	设置当前 experiment
`mlflow.start_run()`	开始一个 Run
`mlflow.log_param(key, value)`	记录单个参数
`mlflow.log_params(dict)`	批量记录参数
`mlflow.log_metric(key, value, step)`	记录指标（可重复）
`mlflow.log_artifact(path)`	上传文件 artifact
`mlflow.log_artifacts(dir)`	上传目录 artifact
`mlflow.set_tag(key, value)`	设置 tag
`mlflow.end_run()`	结束当前 Run

自动上下文

python

with mlflow.start_run() as run:
    mlflow.log_param("lr", 0.01)
    # Run 在 with 块结束时自动关闭

5.3 MlflowClient

mlflow/tracking/client.py 提供更底层、更完整的控制能力。

python

from mlflow import MlflowClient

client = MlflowClient()
client.create_experiment("my-exp")
runs = client.search_runs(experiment_ids=["1"], filter_string="metrics.auc > 0.9")

常用能力：

搜索 Run（带过滤、排序）。
管理 Registered Model / Model Version。
设置 alias、stage、tag。
下载 artifact。

5.4 Tracking Service

内部实现位于 mlflow/tracking/_tracking_service/ 和 mlflow/store/tracking/。

职责：

把 Fluent/Client 请求转换成对 backend store 的操作。
处理 metric 的历史版本（每次 log_metric 新增一行，支持时间序列）。
处理 artifact URI 解析和重定向。

Backend Store 抽象

mlflow/store/tracking/abstract_store.py 定义接口，具体实现：

file_store.py：本地文件系统。
sqlalchemy_store.py：SQL 数据库。
rest_store.py：通过 REST API 访问远程 Tracking Server。

5.5 Model Registry Service

内部实现位于 mlflow/tracking/_model_registry/ 和 mlflow/store/model_registry/。

职责：

管理 Registered Model 的 CRUD。
管理 Model Version 的创建、查询、阶段转换。
管理 alias、tag、description。

注意：Model Registry 需要 SQL backend，本地文件模式不支持。

5.6 Artifact Repository

mlflow/artifacts/ 和 mlflow/store/artifact/ 实现多种 artifact 存储后端。

支持的 Repository：

Repository	类路径
LocalArtifactRepository	`mlflow/store/artifact/local_artifact_repo.py`
S3ArtifactRepository	`mlflow/artifacts/s3_artifact_repo.py`
GCSArtifactRepository	`mlflow/artifacts/gcs_artifact_repo.py`
AzureArtifactRepository	`mlflow/artifacts/azure_blob_artifact_repo.py`
HdfsArtifactRepository	`mlflow/artifacts/hdfs_artifact_repo.py`

Artifact Repository 只负责文件的上传、下载、列出，不解析文件内容。

5.7 Model Flavor

每种机器学习框架有一个 Flavor 模块，例如：

mlflow/sklearn/__init__.py
mlflow/xgboost/__init__.py
mlflow/pytorch/__init__.py
mlflow/tensorflow/__init__.py
mlflow/pyfunc/__init__.py

Flavor 职责

save_model：把框架模型保存到本地目录。
log_model：调用 save_model + 上传 artifact + 记录元数据。
load_model：从 MLflow model URI 加载模型并返回框架原生对象。
定义 MLmodel 文件中的 flavor 段。

一个 MLmodel 文件示例

yaml

artifact_path: model
flavors:
  python_function:
    env:
      conda: conda.yaml
      virtualenv: python_env.yaml
    loader_module: mlflow.sklearn
    model_path: model.pkl
    predict_fn: predict
    python_version: 3.10.12
  sklearn:
    code: null
    pickled_model: model.pkl
    serialization_format: cloudpickle
    sklearn_version: 1.5.0
mlflow_version: 3.2.1
model_size_bytes: 1234
model_id: m-9f2c1a7b3d804e56
signature:
  inputs: '[{"type": "tensor", "tensor-spec": {"dtype": "float64", "shape": [-1, 4]}}]'
  outputs: '[{"type": "tensor", "tensor-spec": {"dtype": "int64", "shape": [-1]}}]'
utc_time_created: '2026-07-04 10:00:00.000000'

5.8 PyFunc：通用部署接口

所有 flavor 都必须能转成 pyfunc 用于部署。mlflow.pyfunc.PyFuncModel 提供统一接口：

python

model = mlflow.pyfunc.load_model("models:/fraud-detector@champion")
predictions = model.predict(input_df)

底层会调用对应 flavor 的 load_model 和 predict。

5.9 MLflow Server

mlflow/server/fastapi_app.py 实现 FastAPI 应用，暴露 REST API。

主要路由组：

/api/2.0/mlflow/runs/*：Run CRUD。
/api/2.0/mlflow/experiments/*：Experiment CRUD。
/api/2.0/mlflow/model-versions/*：Model Version。
/api/2.0/mlflow/registered-models/*：Registered Model。
/api/2.0/mlflow/artifacts/*：Artifact 获取/列出（3.15+ 支持 presigned URL 直传）。
/api/2.0/mlflow/traces/*：Trace 写入与查询（3.x）。
/api/2.0/mlflow/genai/*：Prompt Registry、Evaluation、Gateway 相关接口（3.x）。
/api/2.0/mlflow/permissions/*：RBAC 权限管理（3.13+）。

UI 是 server/js/ 下的前端，调用这些 REST API。

5.10 GenAI 模块（3.x）

mlflow.tracing

基于 OpenTelemetry 实现：Span 处理器把 span 批量写入 MLflow 后端，同时可导出到任意 OTel collector。
提供 @mlflow.trace 装饰器、mlflow.start_span 上下文管理器，以及各框架的 autolog() 开关（mlflow.langchain.autolog()、mlflow.llama_index.autolog()、mlflow.openai.autolog() 等）。
独立的 mlflow-tracing 包只含追踪能力，供不想引入整个 MLflow 的应用使用。

mlflow.genai

Prompt Registry：register_prompt() / load_prompt()，模板带版本与别名。
Evaluation：mlflow.genai.evaluate() 批量运行评估集并调用 scorer（LLM-as-a-Judge 或启发式）打分；评估结果与 trace 双向关联。
Scorer 管理：内置 relevance / groundedness / correctness / safety 等，支持自定义与多模态 judge（3.15+）。

mlflow.gateway

AI Gateway：把多家 LLM provider 抽象成统一端点，提供路由、按时间窗口（日/周/月）的预算、告警与超支阻断（3.11.1+）、输入输出 Guardrails（3.12+）。
MCP Registry（3.15+）：集中注册 MCP Server 配置（版本、别名、标签），供 Agent 工具发现。

5.11 模块交互示例

一次 mlflow.sklearn.log_model() 的调用链：

mlflow.sklearn.log_model()
        │
        ▼
mlflow.models.model.log()
        │
        ▼
flavor.save_model() → 本地临时目录
        │
        ▼
mlflow.tracking.artifact_utils.get_artifact_repository()
        │
        ▼
ArtifactRepository.log_artifacts() → S3
        │
        ▼
生成 MLmodel 文件并上传
        │
        ▼
记录 artifact URI 到 backend store

本章小结

Fluent API：用户最常用的 mlflow.* 函数。
MlflowClient：更完整的底层控制。
Tracking Service：处理 Run、params、metrics、tags 与 LoggedModel（3.x）。
Model Registry Service：管理模型版本、阶段、别名。
Artifact Repository：负责文件上传/下载的抽象。
Model Flavor：把不同框架模型统一封装成 MLflow Model。
PyFunc：统一预测接口，支撑服务部署。
MLflow Server：FastAPI + REST API + UI（3.x 新增 traces/genai/permissions 路由组）。
GenAI 模块：mlflow.tracing（OTel 追踪）、mlflow.genai（Prompt Registry + 评估）、mlflow.gateway（LLM 网关 + MCP Registry）。

参考来源

5. 核心模块：Tracking API、Model Registry、Artifact、Flavor 与 GenAI 组件 ​

5.1 模块分层 ​

5.2 Fluent API ​

关键函数 ​

自动上下文 ​

5.3 MlflowClient ​

5.4 Tracking Service ​

Backend Store 抽象 ​

5.5 Model Registry Service ​

5.6 Artifact Repository ​

5.7 Model Flavor ​

Flavor 职责 ​

一个 MLmodel 文件示例 ​

5.8 PyFunc：通用部署接口 ​

5.9 MLflow Server ​

5.10 GenAI 模块（3.x） ​

mlflow.tracing ​

mlflow.genai ​

mlflow.gateway ​

5.11 模块交互示例 ​

本章小结 ​

5. 核心模块：Tracking API、Model Registry、Artifact、Flavor 与 GenAI 组件

5.1 模块分层

5.2 Fluent API

关键函数

自动上下文

5.3 MlflowClient

5.4 Tracking Service

Backend Store 抽象

5.5 Model Registry Service

5.6 Artifact Repository

5.7 Model Flavor

Flavor 职责

一个 MLmodel 文件示例

5.8 PyFunc：通用部署接口

5.9 MLflow Server

5.10 GenAI 模块（3.x）

mlflow.tracing

mlflow.genai

mlflow.gateway

5.11 模块交互示例

本章小结