MLRun实战指南：从训练到部署的MLOps工程化全流程

1. 为什么需要MLRun：MLOps的痛点与破局思路

1.1 MLOps到底难在哪

先聊点实话。深度学习、机器学习项目，很多团队最后不是死在模型精度上，而是死在“把模型弄上线”这件事上。我在多个团队里见过同一种剧本：算法工程师在本地笔记本上把准确率调到了95%，模型文件保存在自己的output/目录里，训练代码依赖一堆临时的路径和魔法参数。到了工程那边，环境不一样、依赖版本对不上、特征处理逻辑散落在不同的脚本里、模型文件不知道哪个版本对应哪次训练，好不容易上线了，发现线上数据和训练数据分布完全不同，模型表现垮掉，然后两边互相扯皮。

这不是单点工具能解决的问题。模型的生命周期横跨数据准备、特征工程、实验跟踪、超参调优、模型评估、容器化部署、线上监控，每一步之间都有“接缝”。MLRun就是要填掉这些接缝的一个平台。它的定位非常清晰：把整个ML/LLM开发流程当成一套工程系统来管理，用代码描述每个步骤、自动追踪每次运行、标准化打包和部署，最后把“模型上线”从一次人工交接变成一条可重复的自动化流水线。

1.2 MLRun的设计思路

MLRun的核心设计理念，简单说就是“MLOps as Code”——把机器学习工作流的所有部分都代码化、可版本化、可复现化。你写完一个训练函数，MLRun负责把它变成一个可以在Kubernetes或本地运行的作业；你定义好数据集或模型工件，MLRun负责记录元数据、版本、指标；你想做超参数搜索，MLRun帮你把多组参数调度到不同的运行时去并行跑；模型训练好了，MLRun又能以Serverless的方式把它发布成一个在线服务。

这个思路和现在的Infrastructure as Code是同一个逻辑。不同之处在于，MLOps as Code除了管“跑什么脚本”，还管“脚本吃了什么数据”“产出了什么模型”“指标长什么样”“要不要自动重新调度”。它把整个ML流程当作一个持续运转的闭环，而不是一次次手工触发的科研实验。

1.3 选中MLRun而没选其他工具的原因

市面上MLOps工具很多，有的偏实验跟踪（比如实验管理类平台），有的偏流水线编排（比如工作流引擎类平台），有的偏模型部署（比如模型服务框架）。MLRun最吸引我的地方，是它把这些能力整合进了一套统一的框架里，不用我拼搭五六个工具来回倒数据。尤其是模型工件跟踪这一块，MLRun天然知道模型文件、数据集、指标、代码之间的关系，不用像某些工具一样手动维护一张“谁是谁的训练产物”的映射表。

选型时另一个判断依据是它对异构环境的容忍度。MLRun的函数可以跑在本地Docker、Kubernetes、远程集群上，同一个函数只要你切换runtime配置就能换执行环境，不用改写业务代码。这种可移植性在混合环境下的价值非常大——我在本地调试，在集群上大规模训练，用同一套代码，少了一堆环境同步的噩梦。

2. 核心概念入门：先弄懂这几个词再说实操

2.1 Project：一切容器

MLRun里所有的实验、函数、工件、调度，都归属于某个Project。你可以把Project想成“一个ML业务线的隔离空间”，里面有自己的数据集列表、模型列表、函数列表、定时任务。多个人协作时，每个Project可以绑定多个成员，有权限控制，底层的artifact存储位置和计算资源配额也都是按Project隔离的。

我第一次用的时候就吃过没建Project直接乱跑的亏：所有函数和日志堆在默认项目里，时间一长根本分不清哪个是哪次实验的。后来老老实实每个业务场景建独立Project，终于治好了混乱。管理上我用一个yaml文件描述Project元数据，也推荐大家这样做，方便迁移和备份。

2.2 Function：把代码变成可执行单元

在MLRun中，Function是核心抽象。一段训练代码、一个数据处理脚本、一个推理服务，都可以封装成Function。Function的定义包括：代码入口（是.py文件还是notebook、是源代码还是预置镜像）、运行时类型（local、docker、kubernetes等）、计算资源（CPU/GPU/内存）、镜像、环境变量、挂载卷等。

通常我会先写一个普通Python函数，再用@mlrun.handler这种装饰器或者通过SDK直接注册。MLRun拿到函数定义后，会把它包装成标准化的任务执行单元，你只需要调用project.run_function()，给它传参数，它负责调度和执行。

这个“函数化”设计的妙处在于，它让你在写算法的时候完全不用分心考虑“这个代码将来怎么在集群里跑”，只专注业务逻辑。真正要做分布式时，在运行时配置里加gpus: 1这种条件，剩下的交给平台。

2.3 Runtime：决定代码跑在哪

有朋友问过我，MLRun和直接写Dockerfile有什么本质区别。区别就在这个Runtime抽象层。我可以在开发阶段把Runtime配成local，直接在本机跑，遇到问题随便打断点调试；跑通了以后把Runtime切到kubernetes，加个replicas: 8，同一个函数就变成分布式并行任务了。整个过程没有换代码框架，也没改业务逻辑。

Runtime配置里最重要的几项是kind、image、resources和env。image字段指基础镜像，MLRun默认会准备一系列兼容不同框架的镜像，比如带有scikit-learn、xgboost、pytorch、tensorflow等不同组合的版本。资源限制必须写清楚，不写有时调度器默认给得很小，批量跑任务时会莫名其妙OOM。

2.4 Artifacts：每一次运行的“痕迹”

MLRun里Artifact是指一个函数运行时产生的文件、数据集、模型、图表等产出物。区别于普通文件系统，Artifact会自动被登记在MLRun的元数据服务中，记录它的来源函数、运行参数、指标、标签、时间戳和血缘关系。后续你可以按名称一键加载某个历史版本的数据集或模型，而不用自己搞一堆带时间戳的词目录。

我最喜欢的用法是在前一次运行的模型工件上接着微调。直接在函数参数里写inputs={'model': 'mlrun://{project}/models/my_model:latest'}，MLRun自动解析到最新版本，我把版本号改成具体哈希就能复现历史实验。团队其他人拉取同一个Project后，这些地址也是共享的，协作成本大幅降低。

2.5 Schedule和Pipeline：自动化与编排

光能手动跑函数还不够，真正的MLOps至少要能自动重跑。MLRun的project.schedule_function()可以直接给函数挂定时任务，比如每周日凌晨自动对已部署的模型做离线评测，把指标更新到文档。流水线方面，MLRun支持两种语言：自己的一套轻量级SDK（Python），以及兼容Kubeflow Pipeline格式的定义方式。你可以把多个函数链接成一个有向无环图，上游产出做下游输入，异常时还能配置重试和通知。

3. 环境搭建：从零跑通第一个MLRun项目

3.1 安装与启动

先从安装说起。最简单的起步路径是在本地装Docker Desktop或直接用Linux环境，然后通过pip安装客户端：

pip install mlrun mlrun ui

这个命令会启动本地开发环境，默认包括：一个API服务和一个可视化UI。浏览器打开后能直接操作Project、函数、运行记录、工件和定时任务。不用先折腾Kubernetes，也能体验到核心功能。整个搭建流程大约十来分钟，这也是我推荐新手先在本机跑一遍的原因，快速建立对系统的整体感知。

如果你的团队已经有Kubernetes基础，那就可以直接部署到集群上。用官方Helm Chart更省心，只需要准备好存储类、镜像仓库访问权限和负载均衡入口。

3.2 初始化Project与存储配置

本地环境起来后，我习惯先用SDK创建Project，指定artifact路径：

import mlrun project = mlrun.get_or_create_project( name="demo-train", user_project=False, context="./", )

这里有个细节：如果指定context为当前目录，MLRun会把该目录下未忽略的文件快照进项目，作为代码版本管理。所以建议在项目根目录加一个.mlrunignore文件，把data/、output/、__pycache__之类的临时内容排除掉，不然每次运行都上传一遍数据文件，既慢又占空间。

3.3 编写并运行第一个函数

接下来写一个模拟的预处理函数，感受一下流程。先定义数据获取：

import mlrun def gen_data(context, rows=1000): import pandas as pd import numpy as np df = pd.DataFrame({ "x": np.random.randn(rows), "y": np.random.randn(rows) * 0.5 + 0.3, "label": np.random.randint(0, 2, size=rows), }) context.log_dataset("toy_data", df, format="parquet")

然后注册函数并调用：

project.set_function("prep.py", name="prep", kind="job", image="mlrun/mlrun") run = project.run_function("prep", params={"rows": 5000}, local=True)

这里local=True表示直接在本地Python进程里跑，不要打包镜像。作为第一次验证非常方便。运行结束后，打开UI看一眼Artifacts，会发现toy_data已经被登记为数据集工件，包含行数、列名、数据格式等元数据。

4. 实操训练与调优：一套能落地的训练流水线

4.1 参数化训练函数

有了数据，下一步是训练。写训练函数时要充分参数化，因为之后做超参搜索时要反复传不同的参数组合，写死了就白搭。下面是scikit-learn逻辑回归示例：

import mlrun from mlrun.execution import MLClientCtx def train_logreg(ctx: MLClientCtx, dataset_key: str = "toy_data", C: float = 1.0, solver: str = "lbfgs", test_size: float = 0.2): import pandas as pd from sklearn.linear_model import LogisticRegression from sklearn.model_selection import train_test_split df = ctx.datasets[dataset_key].as_df() X = df[["x", "y"]].values y = df["label"].values X_train, X_test, y_train, y_test = train_test_split( X, y, test_size=test_size, random_state=42 ) model = LogisticRegression(C=C, solver=solver, max_iter=2000) model.fit(X_train, y_train) acc = model.score(X_test, y_test) ctx.log_result("accuracy", acc) ctx.log_model("logreg_model", body=model, sample_input=X_test[:5], metrics={"accuracy": acc})

这里ctx.log_model会把模型对象序列化并存储为MLRun模型工件，同时自动附带测试样本和metrics。之后部署服务的时候，就从这个工件直接加载模型，不用在部署阶段再重复训练逻辑。

4.2 并行跑超参调优

MLRun天然支持超参搜索。先用mlrun.run的方式指定一组参数字典：

from mlrun import RunTemplate from mlrun.runtimes import HyperParamStrategies train_func = project.get_function("train") project.run_function( "train", params={"C": [0.01, 0.1, 1, 10, 100], "solver": ["lbfgs", "liblinear"]}, selector="min", # 这里演示选accuracy最大，可改为max )

MLRun会把参数做笛卡尔积，并在配置的Runtime上并行调度。我在Kubernetes环境里实测过，20组参数开8个并行副本，约莫几分钟就跑完了。运行结束后，在UI里能看到不同参数组合的指标对比图，非常直观。

有些读者可能不习惯用原生SDK，MLRun也支持更简单的参数化运行方式：直接在Python里把参数以param_list传入，控制粒度更细。

4.3 指标记录和工件版本管理

追踪实验指标时，不要只在控制台打印，要主动记录到MLRun的元数据里。上面的示例里ctx.log_result就是干这个的。它把指标登记成可搜索的结构化结果。我实测在几十轮实验后，按指标排序筛选最优模型就是一个API调用，完全不需要看日志记录文件。

工件的版本管理也是这里的重要部分。log_model每次运行都会生成新版本，默认latest标签指向最新；生产部署时可以通过指定具体哈希或标签锁定版本。我强烈建议在生产环境固定模型版本hash，不要用latest，否则别人一更新，线上服务就被悄悄替换了。

5. 模型部署：把训练产物变成可用服务

5.1 部署方式与Serverless架构

模型训练完只是开始，还得能上线。MLRun部署模型最常用的是mlrun.serving，它基于轻量级Serverless函数实现，把log_model存下来的工件暴露成一个REST API。部署时需要指定模型名称、模型路径、运行时镜像以及期望的副本数。

部署之后，平台会为你创建一个可伸缩的推理服务，自动处理请求负载均衡。在Kubernetes环境里，它可以基于请求量自动扩缩容，空闲时缩到零，省资源。

5.2 自定义推理类

模型工件自动生成的服务能够满足多数标准场景，但业务上常常还有预处理、后处理、缓存、AB测试之类的定制逻辑。MLRun允许你写一个自定义ModelServer子类，overrideload和predict方法：

import mlrun class MyModel(mlrun.serving.V2ModelServer): def load(self): import pickle model_path = self.get_model_path() with open(model_path, "rb") as f: self.model = pickle.load(f) def predict(self, body: dict): import numpy as np features = np.array(body["inputs"], dtype=float).reshape(1, -1) proba = self.model.predict_proba(features)[0] return {"probabilities": proba.tolist(), "label": int(proba.argmax())}

定义好后，注册为函数并指向模型工件即可。这个自定义推理类最大的价值是把“预处理、特征转换、模型推理、后处理”整个封装到服务内，线上代码和训练代码共享同一个逻辑，切断了一个经典的系统性风险来源——训练/线上代码漂移。

5.3 在线测试与版本切换

部署完成后，SDK会返回一个URL，用curl或requests就能直接调用：

curl -X POST http://localhost:8080/v2/models/logreg_model/infer \ -H "Content-Type: application/json" \ -d '{"inputs": [0.1, -0.2]}'

想切换模型版本，只要重新部署时换掉model路径参数即可。MLRun支持多版本共存，我做灰度发布时，会把新版本部署成同一服务的另一个路由，用一小部分流量进入，对比正确率和延迟后再全量切过去，几行代码就完成了。

6. LLMOps实践：大语言模型场景下的特殊玩法

6.1 LLM给MLOps带来了什么新挑战

大语言模型和传统ML有不少差异。LLM不再是那个“一个模型”就结束的流程，它通常牵扯到提示词管理、外部知识库检索、向量数据库、生成结果评估、成本和延迟权衡等新问题。很多团队用LangChain等框架来编排这些组件，却发现编排好以后，怎么管理提示词版本、怎么追踪每一次LLM调用的价格和延迟、怎么做回归评测，依然是空白。MLRun的工件跟踪和流水线能力正好填补这块。

我在实践中的一个内部项目（我们就叫它“某对话系统”吧）里，把一次LLM调用封装成Function，输入是用户问题和检索到的上下文片段，输出是生成的回复以及调用元数据。每次运行，MLRun记录的工件里包含了提示词版本、模型名、token用量、首字延迟等字段。不同提示词版本的对比不再依靠“我记得好像改过”，而是直接看指标表。

6.2 搭建一条RAG类型的流水线

RAG（检索增强生成）是很常见的LLM应用架构。我建议把RAG的每一步都拆解成MLRun的独立Function，比如：

1. 文档切分与向量化入库
2. 查询时的检索函数
3. 增强生成函数

每个环节各自有输入输出，生产和测试环境复用同一套函数定义。比如检索函数：

def retrieve(context, query: str, top_k: int = 3): # 省略向量检索细节 results = search_similar(query, top_k=top_k) context.log_dataset("contexts", results) return {"contexts": results}

然后是生成函数，把检索结果拼接进提示词，调用大模型API。两个函数串成流水线后，每次改提示词或换向量库，都触发一次端到端运行，产出的回答直接落到工件里方便评估。

6.3 评测与可观测性

LLM评测不能只看传统指标，还要关注回答准确性、幻觉程度、相关性、敏感词等。我通常在流水线尾部挂一个评估函数，接收生成结果，计算多个维度得分，并记录到artifact中。这样每次更新都能在UI里对比效果，而不是靠肉眼扫几页对话记录。除此之外，token的开销也值得追踪——LLM成本不再是固定资源费用，而是和输入输出长度强相关的变量。把每次调用的token数和价格记成结构化指标，对做成本控制特别有用。

MLRun在LLM场景的另一个优点是它天然支持容器镜像的隔离，你可以把不同的LLM依赖（例如不同版本的tokenizer、推理库）封装成不同镜像，在同一个项目中并行使用而互不干扰。这个特性对团队协作尤其重要，避免“我升级了库版本影响你的调用”这类事情。

7. 常见问题与排查：把踩过的坑一次说清楚

7.1 典型报错与解决思路

我在使用MLRun过程中积累了几类高概率出现的坑，整理成表：

7.2 避坑心得与操作习惯

有几个习惯我踩了多次坑才养成的。第一，永远在函数入口处打印或记录输入参数的校验，因为编排系统传参时容易漏掉数据类型；第二，将镜像依赖固定到精确版本，用基础镜像时一定要顶住“latest”的诱惑，否则环境漂移会让你排查到怀疑人生；第三，定期备份项目定义文件，MLRun里Project的yaml配置文件是带了完整元数据的，丢了就得从头重建，非常痛苦。

另外，我建议团队在CI阶段就跑一次“流水线空跑”（用极小的数据集），确认从代码提交到模型工件生成全链路是通的，再去做会跑很久的正式任务。这样可以把配置或代码问题暴露在几分钟内，而不是让几十个GPU小时白白浪费在不兼容的代码上。

最后分享一点我的实际操作体会

这套平台用下来，最大的感受是系统性的稳定感。以前做ML项目，最怕的就是“这次跑出来结果不一样”和“模型怎么上线”这种玄学问题。把流程拆进MLRun后，代码、参数、数据、环境、模型、指标全部被登记成可回溯的工件，试验多个版本也能很轻松地判断哪个更好、哪里出了问题。它不是帮你加速训练本身，而是帮你在训练之外省下大量的隐性成本。

如果你刚接触MLOps，建议不要一上来就上Kubernetes。先在本地模式把要点跑通，体会函数、工件、运行记录、部署之间的关系。之后再迁移到集群，过程中你会非常有把握。整套平台的东西不算少，但核心逻辑只要抓住了“一切皆函数、一切皆工件”这八个字，后面再看文档就顺了。