model-registry

模型注册表：用 MLflow Registry 和 OCI 制品管理版本与别名。

补充说明

模型注册表解决三件事：版本可追溯、部署引用稳定、回滚有据。MLflow Model Registry 提供版本、别名和 lineage；OCI 制品适合存放权重和推理镜像。

基础实验跟踪见 mlflow；本页聚焦注册、别名发布和部署引用。

安装与启动

pip install -U mlflow
mlflow server --host 0.0.0.0 --port 5000 \
  --backend-store-uri "postgresql://$PG_USER:$PG_PASS@$PG_HOST:5432/mlflow" \
  --artifacts-destination "s3://$ARTIFACT_BUCKET"

生产必须用外部数据库和对象存储；SQLite 加本地目录只能单机试用。

常用示例

训练后记录模型并注册：

python - <<'PY'
import mlflow, mlflow.sklearn
mlflow.set_tracking_uri("http://mlflow.internal:5000")
with mlflow.start_run() as run:
    mlflow.sklearn.log_model(model, name="model",
                             registered_model_name="qwen-lora")
    print("run_id:", run.info.run_id)
PY

MLflow 3 用 name=，2.x 用 artifact_path=；客户端大版本要和服务端匹配。

用 REST API 创建版本和别名：

curl -s -X POST "$MLFLOW_URI/api/2.0/mlflow/model-versions/create" \
  -H 'Content-Type: application/json' \
  -d "{\"name\":\"qwen-lora\",\"source\":\"runs:/$RUN_ID/model\"}"

curl -s -X POST "$MLFLOW_URI/api/2.0/mlflow/registered-models/set-alias" \
  -H 'Content-Type: application/json' \
  -d '{"name":"qwen-lora","alias":"champion","version":"3"}'

curl -s "$MLFLOW_URI/api/2.0/mlflow/registered-models/alias?name=qwen-lora&alias=champion"

部署端只引用别名，不写死版本：

python - <<'PY'
import mlflow.pyfunc
mlflow.set_tracking_uri("http://mlflow.internal:5000")
model = mlflow.pyfunc.load_model("models:/qwen-lora@champion")
print(model.predict(df))
PY

用 OCI 仓库存放权重并保留不可变引用：

oras login registry.example.com
oras push registry.example.com/models/qwen-lora:v3 \
  ./model:/model:application/octet-stream
oras manifest fetch registry.example.com/models/qwen-lora:v3

易错点与排错

• Stage（Staging/Production）已被弃用，新流程用 alias；继续依赖 stage 会在升级后失效。
• source 必须是服务端能解析的 URI；runs:/ 依赖 artifact 根配置，跨集群迁移时改用绝对路径。
• alias 是可变的，同一 alias 被并发更新时后写覆盖；发布系统要加锁并记录解析到的版本。
• 删除仍被 alias 或线上引用的版本会导致加载失败；先切别名、归档旧版本，再清理。
• 模型没记录 signature，部署时输入 schema 不匹配只能到运行期才发现；log_model 时传入 signature。
• 多副本 MLflow 必须共享同一个后端数据库和 artifact store，否则各副本看到的版本不一致。
• 服务端进程没有对象存储权限时，注册能成功但加载 404；用服务端身份单独验证读权限。
• OCI tag 可被覆盖，生产部署固定 digest；tag 只用于人读。

读完自测

合上页面，先回答，再展开对照。

1. 为什么部署要用 alias 而不是固定版本号？
2. runs:/ 来源在什么情况下会失效？
3. 删除模型版本前要检查什么？

相关条目

• mlflow
• dvc
• ray-serve
• triton-inference-server
• llama-factory