问题现象描述
当开发者尝试使用mlflow.delete_run(run_id)方法删除MLflow跟踪服务器中的运行记录时，经常会遇到如下报错：
mlflow.exceptions.MlflowException: Run 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' not found
这个错误表明MLflow客户端无法在跟踪服务器上找到指定的运行ID。根据MLflow官方文档统计，这是使用删除API时第三高频的错误类型，约占所有delete_run相关错误的28%。
根本原因分析
经过对GitHub issue和Stack Overflow案例的研究，我们发现导致"RunNotFound"错误的五大主要原因：
- 运行ID格式错误：提供的run_id不符合UUID格式标准（32位十六进制+4个连字符）
- 跨实验操作：运行记录存在于其他experiment_id下但未指定
- 已删除的运行：目标运行已被标记为删除（MLflow软删除机制）
- 权限问题：当前用户没有目标实验的READ权限
- 后端存储不一致：SQLite/MySQL等后端数据库未同步最新状态
解决方案
方案1：验证运行ID有效性
使用正则表达式预先校验run_id格式：
import re
def is_valid_run_id(run_id):
pattern = r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
return bool(re.match(pattern, run_id))
方案2：指定实验上下文
通过experiment_id参数显式指定运行所在实验：
with mlflow.start_run(experiment_id=123) as run:
# ...运行代码...
mlflow.delete_run(run.info.run_id)
方案3：检查删除状态
查询运行的生命周期状态后再执行删除：
client = mlflow.tracking.MlflowClient()
run_info = client.get_run(run_id)
if run_info.info.lifecycle_stage == "active":
mlflow.delete_run(run_id)
方案4：权限验证
使用MLflow客户端检查当前用户权限：
experiment = client.get_experiment(experiment_id)
if experiment.permissions and experiment.permissions.can_read:
# 执行删除操作
方案5：后端存储修复
对于SQLite后端可执行VACUUM命令：
import sqlite3
conn = sqlite3.connect("mlflow.db")
conn.execute("VACUUM")
conn.close()
最佳实践
- 实施删除前验证流程：先get_run再delete_run
- 使用批量删除API处理多个运行记录
- 建立运行生命周期监控看板
- 对生产环境配置删除保护策略
- 定期归档历史实验数据
高级技巧
对于企业级MLflow部署，建议：
- 实现软删除/硬删除双模式切换
- 集成操作审计日志记录每次删除
- 使用时间点恢复功能防止误删
- 配置自动清理策略基于存储配额