跳到主要内容

工作区 (Workspaces)

工作空间为实验、注册模型、提示词（prompts）、AI 网关资源和工件（artifacts）等 MLflow 资源添加了一个可选的组织层和权限方案，让团队能够在不运行多个服务器的情况下共享同一部署。

核心功能​

资源范围限定：每个工作空间保留其自己的资源，例如实验、注册模型、提示词、AI 网关资源和工件。工作空间级别的权限控制谁可以查看或修改这些资源。除此之外，所有的 MLflow 客户端和 API 使用方式保持不变。

共享基础设施：多个团队可以使用单个 MLflow 服务器实例，在按工作空间对资源进行分组的同时，降低运营开销。

灵活集成：可插拔的工作空间存储架构可用于与现有的组织结构（如 Kubernetes 命名空间或身份提供商）集成。

向后兼容：工作空间功能是可选的，默认情况下处于禁用状态。现有部署在无需修改的情况下可继续工作。

何时使用工作空间​

当您有以下需求时，请使用工作空间：

  • 多个团队共享单个 MLflow 实例，同时保持实验、注册模型、提示词和 AI 网关资源的有序管理
  • 通过工作空间级别的权限来管理资源组，而无需管理单个实验或模型
  • 与平台级结构（例如 Kubernetes 命名空间）集成以保持资源分组
  • 在无需部署单独服务器的情况下，简化跨多个团队的 MLflow 管理

::::caution 非硬性隔离边界 工作空间在单个 MLflow 服务器内提供逻辑隔离和授权控制。如需严格的数据平面或合规性隔离，请运行独立的 MLflow 部署，而不是共享服务器。 :::

要求

工作空间需要 SQL 数据库后端存储。启用工作空间后，不支持基于文件的后端。

注意

如果您正在现有的启用 basic-auth 的实例上启用工作空间，请在您的 身份验证配置 中设置 grant_default_workspace_access = true 以实现向后兼容。否则，非管理员用户将无法访问 default 工作空间中的现有资源。

工作空间范围内的资源​

启用工作空间后，以下顶级资源属于工作空间范围：

  • 实验及其所有子资源（运行记录、追踪、指标、参数、标签、工件）
  • 注册模型及其模型版本
  • 提示词及其版本（提示词共享注册模型存储）
  • AI 网关资源，例如 API 密钥、模型定义和端点
  • 评估数据集

子资源会自动继承其父级的工作空间。例如，运行记录会继承实验的工作空间，模型版本会继承注册模型的工作空间。

工件隔离​

默认情况下，工件通过 URI 前缀在工作空间内进行隔离。当在工作空间中创建实验时，MLflow 会自动在以下路径下生成工件位置：

text
<default_artifact_root>/workspaces/<workspace-name>/<experiment-id>

可选地，工作空间可以覆盖其默认的工件根目录。当在工作空间上设置 default_artifact_root 时，新实验会使用该路径：

text
<workspace_default_artifact_root>/<experiment-id>

运行记录的工件根目录衍生自实验位置

text
.../<run-id>/artifacts

为了向后兼容，在启用工作空间之前就存在于预留的 default 工作空间中的资源，将保留其存储的工件位置（可能没有前缀）并保持可访问状态。

客户端指定的工件位置

启用工作空间后，客户端提供的 artifact_location 值将被拒绝，以防止绕过工作空间隔离。服务器会自动管理工件位置，以确保适当的隔离。

快速入门​

后端与启用

工作空间需要 SQL 后端（不支持文件后端）。请使用 MLFLOW_ENABLE_WORKSPACES=1 启用，并配置工作空间提供商（若未指定，则使用默认的 SQL 提供商）。

启动 MLflow 服务器时启用工作空间

bash
mlflow server \
  --backend-store-uri postgresql://user:pass@localhost/mlflow \
  --default-artifact-root s3://mlflow-artifacts \
  --enable-workspaces

通过 Python 客户端使用工作空间

python
import mlflow

# Set tracking URI (no workspace in URI)
mlflow.set_tracking_uri("https://mlflow.example.com")

# Set active workspace
mlflow.set_workspace("team-a")

# All subsequent operations are scoped to team-a
experiment_id = mlflow.create_experiment("my-experiment")

with mlflow.start_run(experiment_id=experiment_id):
    mlflow.log_param("alpha", 0.5)
    mlflow.log_metric("rmse", 0.8)

列出可用工作空间

python
workspaces = mlflow.list_workspaces()
for workspace in workspaces:
    print(f"{workspace.name}: {workspace.description}")

工作空间解析​

活动工作空间按以下顺序确定：

  1. 显式的 mlflow.set_workspace() 调用
  2. MLFLOW_WORKSPACE 环境变量
  3. 提供商的 get_default_workspace() 实现

如果未设置 mlflow.set_workspace() 也未设置 MLFLOW_WORKSPACE，MLflow 将回退到提供商的默认工作空间（通常为 default）。如果无法解析工作空间且提供商不支持默认工作空间，API 调用将返回错误。

身份验证与权限​

启用 MLflow 身份验证 后，工作空间支持工作空间范围的权限，这些权限补充了资源级别的访问控制：

  • 工作空间级别的权限为工作空间内的所有资源提供便捷的授权
  • 用户可以拥有工作空间级别权限、资源级别权限，或两者兼有
  • 拥有工作空间级别 READ 权限的用户可以访问该工作空间中的所有实验、注册模型、提示词和 AI 网关资源
  • 拥有工作空间级别 USE 权限的用户可以调用 AI 网关端点或引用网关模型定义和 API 密钥
  • 单个资源权限优先，并可进一步限制访问
  • 拥有 MANAGE 权限的用户可以将其工作空间内的访问权限委托给他人

详情请参阅 工作空间权限。

迁移与兼容性​

在现有部署上启用工作空间

  1. 现有资源会自动分配给 default 工作空间
  2. 工件位置保持不变
  3. 现有客户端通过使用 default 工作空间可继续工作
  4. 一旦资源存在于非默认工作空间中，除非删除了非默认工作空间中的所有资源，否则无法禁用工作空间功能。

default 工作空间是预留的，无法删除或重命名。它为现有部署提供了向后兼容性。

后续步骤​

API 参考​