MLflow 2.19.0 log_image路径字符异常问题求助

问题 #

在Red Hat Enterprise Linux Server release 7.9（Maipo）环境使用Mlflow==2.19.0时，其他功能正常，但log_image方法使用key参数时，生成的图像路径出现字符异常：

• 错误路径：/data/gcprcmsbx/work/hive/gcprcmsbx_work/citilabs/sherlock/mlflow/artifacts/ip70574/1/3403fe396bf64129980fb6e7f26b5875/artifacts/images/sample_image%step%0%timestamp%1745516773738�f3cea2-6baa-4b8a-9107-68f0ab83b572.png
• 正确路径：hdfs:/data/gcprcmsbx/work/hive/gcprcmsbx_work/citilabs/sherlock/mlflow/artifacts/ip70574/1/3403fe396bf64129980fb6e7f26b5875/artifacts/images/sample_image%step%0%timestamp%1745516773738%daf3cea2-6baa-4b8a-9107-68f0ab83b572.png

已尝试以下环境变量配置，均无效：

os.environ["ESCAPE_PERCENT"] = "1"
os.environ["LANG"] = "en_US.UTF-8"
os.environ["LC_ALL"] = "en_US.UTF-8"
os.environ["PYTHONUTF8"] = "1"
os.environ["PYTHONIOENCODING"] = "UTF-8"
os.environ["NO_PROXY"] = "*"

约束条件：必须使用key≠None（需对比不同运行的图像），无sudo权限。

复现代码：

import io
import matplotlib.pyplot as plt
from PIL import Image
import mlflow

x = range(10)
y = [i**2 for i in x]

plt.plot(x, y, marker='o')
plt.title('Basic Line Plot')
plt.xlabel('X-axis')
plt.ylabel('Y-axis')

fig = plt.gcf()

def fig2img(fig):
    """Converts a Matplotlib figure to a PIL Image."""
    buf = io.BytesIO()
    fig.savefig(buf, format='png', bbox_inches='tight')
    buf.seek(0)
    img = Image.open(buf)
    return img

pil_image = fig2img(fig=fig)

mlflow.log_image(image=pil_image,                 
                 key='sample_image',
                 step=None,
                 timestamp=None)

解决方案 #

1. 手动构造路径并保留对比标识 #

MLflow自动生成路径时，会将%d误解析为格式占位符而非字面量，导致字符异常。可以手动生成符合规则的文件名，用artifact_file参数指定路径，同时通过run标签保留key信息以实现对比：

import time
import uuid
import mlflow

# 手动构造符合要求的文件名
custom_filename = f"images/sample_image%step%0%timestamp%{int(time.time()*1000)}%{uuid.uuid4()}.png"
# 存入标签用于后续对比
mlflow.set_tag("image_key", "sample_image")
# 用artifact_file参数替代key参数完成日志
mlflow.log_image(image=pil_image, artifact_file=custom_filename)

2. 猴子补丁修复MLflow内部逻辑 #

在脚本开头对MlflowClient的log_image方法打补丁，绕过原有的错误路径生成逻辑：

import time
import uuid
import mlflow
from mlflow.tracking.client import MlflowClient

original_log_image = MlflowClient.log_image

def patched_log_image(self, run_id, image, artifact_file=None, key=None, step=None, timestamp=None, synchronous=False):
    if key is not None:
        # 手动生成正确路径，避免格式字符串解析错误
        step = step if step is not None else 0
        timestamp = timestamp if timestamp is not None else int(time.time() * 1000)
        artifact_file = f"images/{key}%step%{step}%timestamp%{timestamp}%{uuid.uuid4()}.png"
        # 清空key等参数，让MLflow走artifact_file逻辑
        key = step = timestamp = None
    return original_log_image(self, run_id, image, artifact_file, key, step, timestamp, synchronous)

MlflowClient.log_image = patched_log_image

# 之后正常调用log_image即可
mlflow.log_image(image=pil_image, key='sample_image')

3. 升级MLflow版本 #

该问题大概率是MLflow 2.19.0的版本bug，后续版本可能已修复。无需sudo权限，用--user参数升级到最新稳定版：

pip install --upgrade mlflow --user

内容的提问来源于stack exchange，提问作者Ivan