mlflow-onboarding
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMLflow Onboarding
MLflow入门引导
MLflow supports two broad use cases that require different onboarding paths:
- GenAI applications and agents: LLM-powered apps, chatbots, RAG pipelines, tool-calling agents. Key MLflow features include tracing for observability, evaluation with LLM judges, and prompt management, among others.
- Traditional ML / deep learning models: scikit-learn, PyTorch, TensorFlow, XGBoost, etc. Key MLflow features include experiment tracking (parameters, metrics, artifacts), model logging, and model deployment, among others.
Determining which use case applies is the first and most important step. The onboarding path, quickstart tutorials, and integration steps differ significantly between the two.
MLflow支持两大类用例,对应不同的入门路径:
- GenAI应用与代理:基于LLM的应用、聊天机器人、RAG流水线、工具调用代理等。MLflow的核心功能包括用于可观测性的tracing(追踪)、基于LLM评估器的evaluation(评估)以及prompt管理等。
- 传统机器学习/深度学习模型:scikit-learn、PyTorch、TensorFlow、XGBoost等框架模型。MLflow的核心功能包括实验跟踪(参数、指标、产物)、模型日志记录以及模型部署等。
确定用户的用例是第一步也是最重要的步骤。两类用例的入门路径、快速入门教程和集成步骤存在显著差异。
Step 1: Determine the Use Case
步骤1:确定用例
Before recommending tutorials or integration steps, determine which use case the user is working on. Use the signals below, checking them in order. If the signals are ambiguous or absent, you MUST ask the user directly.
在推荐教程或集成步骤之前,先确定用户的用例。按照以下信号依次检查。如果信号模糊或缺失,必须直接询问用户。
Signal 1: Check the Codebase
信号1:检查代码库
Search the user's project for imports and usage patterns that indicate the use case:
GenAI indicators (any of these suggest GenAI):
- Imports from LLM client libraries: ,
openai,anthropic,google.generativeai,langchain,langchain_openai,langgraph,llamaindex,litellm,autogen,crewaidspy - Imports from MLflow GenAI modules: ,
mlflow.genai,mlflow.tracing,mlflow.openaimlflow.langchain - Usage of chat completions, embeddings, or agent frameworks
- Prompt templates or prompt engineering code
Traditional ML indicators (any of these suggest ML):
- Imports from ML frameworks: ,
sklearn,torch,tensorflow,keras,xgboost,lightgbm,catboost,statsmodelsscipy - Imports from MLflow ML modules: ,
mlflow.sklearn,mlflow.pytorchmlflow.tensorflow - Model training loops, calls, hyperparameter tuning code
.fit() - Dataset loading with tabular/image/time-series data
bash
undefined搜索用户项目中的导入语句和使用模式,判断用例类型:
GenAI识别特征(满足任意一项即表明为GenAI用例):
- 导入LLM客户端库:、
openai、anthropic、google.generativeai、langchain、langchain_openai、langgraph、llamaindex、litellm、autogen、crewaidspy - 导入MLflow GenAI模块:、
mlflow.genai、mlflow.tracing、mlflow.openaimlflow.langchain - 使用聊天补全、嵌入或代理框架
- 存在提示词模板或提示词工程代码
传统机器学习识别特征(满足任意一项即表明为传统ML用例):
- 导入机器学习框架:、
sklearn、torch、tensorflow、keras、xgboost、lightgbm、catboost、statsmodelsscipy - 导入MLflow ML模块:、
mlflow.sklearn、mlflow.pytorchmlflow.tensorflow - 模型训练循环、调用、超参数调优代码
.fit() - 使用表格/图像/时间序列数据加载数据集
bash
undefinedSearch for GenAI indicators
Search for GenAI indicators
grep -rl --include='*.py' -E '(import openai|import anthropic|from langchain|from langgraph|import litellm|from mlflow.genai|from mlflow.tracing|mlflow.openai|mlflow.langchain|ChatCompletion|chat.completions)' .
grep -rl --include='*.py' -E '(import openai|import anthropic|from langchain|from langgraph|import litellm|from mlflow.genai|from mlflow.tracing|mlflow.openai|mlflow.langchain|ChatCompletion|chat.completions)' .
Search for ML indicators
Search for ML indicators
grep -rl --include='*.py' -E '(from sklearn|import torch|import tensorflow|import keras|import xgboost|import lightgbm|mlflow.sklearn|mlflow.pytorch|mlflow.tensorflow|.fit()' .
undefinedgrep -rl --include='*.py' -E '(from sklearn|import torch|import tensorflow|import keras|import xgboost|import lightgbm|mlflow.sklearn|mlflow.pytorch|mlflow.tensorflow|.fit()' .
undefinedSignal 2: Check the Experiment Type Tag
信号2:检查实验类型标签
If the codebase or project directory is the MLflow repository itself, skip to Signal 3 — the MLflow repo contains code for all use cases and does not indicate the user's intent.
If the experiment ID is known, check its tag. This tag is set by MLflow to indicate the experiment type:
mlflow.experimentKindbash
mlflow experiments get --experiment-id <EXPERIMENT_ID> --output json > /tmp/exp_detail.json
jq -r '.tags["mlflow.experimentKind"] // "not set"' /tmp/exp_detail.json- → GenAI use case
genai_development - → Traditional ML use case
custom_model_development - Not set → Proceed to Signal 3
If the experiment ID is not known, skip to Signal 3.
如果代码库或项目目录是MLflow官方仓库本身,直接跳至信号3——MLflow仓库包含所有用例的代码,无法体现用户的实际需求。
如果已知实验ID,检查其标签。该标签由MLflow设置,用于标识实验类型:
mlflow.experimentKindbash
mlflow experiments get --experiment-id <EXPERIMENT_ID> --output json > /tmp/exp_detail.json
jq -r '.tags["mlflow.experimentKind"] // "not set"' /tmp/exp_detail.json- → GenAI用例
genai_development - → 传统ML用例
custom_model_development - 未设置 → 继续执行信号3
如果未知实验ID,直接跳至信号3。
Signal 3: Ask the User
信号3:询问用户
If the codebase and experiment signals are inconclusive, ask directly:
Are you building a GenAI application (e.g., an LLM-powered chatbot, RAG pipeline, or tool-calling agent) or a traditional ML/deep learning model (e.g., training a classifier, regression model, or neural network)?
Do not guess. The onboarding paths are different enough that starting down the wrong one wastes the user's time.
如果代码库和实验信号均无法确定用例,直接询问用户:
您正在开发GenAI应用(例如基于LLM的聊天机器人、RAG流水线或工具调用代理)还是传统机器学习/深度学习模型(例如训练分类器、回归模型或神经网络)?
请勿猜测。两类用例的入门路径差异极大,错误的引导会浪费用户时间。
Step 2: Recommend Quickstart Tutorials
步骤2:推荐快速入门教程
Once the use case is determined, recommend the appropriate quickstart tutorials from the MLflow documentation. Present them to the user and ask if they'd like to follow along or jump directly to integrating MLflow into their project.
确定用例后,从MLflow文档中推荐合适的快速入门教程。将教程呈现给用户,并询问他们是否希望跟随教程学习,或直接跳至MLflow集成步骤。
GenAI Path
GenAI路径
The MLflow GenAI documentation is at: https://mlflow.org/docs/latest/genai/getting-started/
Choose the most relevant tutorials based on the user's context and what they've told you. Available tutorials include:
- Tracing Quickstart (https://mlflow.org/docs/latest/genai/tracing/quickstart/) — Enabling automatic tracing for LLM calls. Covers starting an MLflow server, creating an experiment, enabling autologging, and viewing traces in the UI.
- Python + OpenAI variant: https://mlflow.org/docs/latest/genai/tracing/quickstart/python-openai/
- TypeScript + OpenAI variant: https://mlflow.org/docs/latest/genai/tracing/quickstart/typescript-openai
- OpenTelemetry (language-agnostic) variant: also linked from the quickstart page
- Evaluation Quickstart (https://mlflow.org/docs/latest/genai/eval-monitor/quickstart/) — Evaluating GenAI application quality using LLM judges (scorers). Covers defining datasets, prediction functions, and built-in + custom scorers.
- Version Tracking Quickstart (https://mlflow.org/docs/latest/genai/version-tracking/quickstart/) — Prompt management, application versioning, and connecting tracing to versioned prompts.
If none of these match the user's needs, look up the MLflow GenAI documentation for more relevant guides.
MLflow GenAI文档地址:https://mlflow.org/docs/latest/genai/getting-started/
根据用户的上下文和需求选择最相关的教程,可用教程包括:
- 追踪快速入门(https://mlflow.org/docs/latest/genai/tracing/quickstart/)——为LLM调用启用自动追踪。内容包括启动MLflow服务器、创建实验、启用自动日志记录,以及在UI中查看追踪数据。
- Python + OpenAI版本:https://mlflow.org/docs/latest/genai/tracing/quickstart/python-openai/
- TypeScript + OpenAI版本:https://mlflow.org/docs/latest/genai/tracing/quickstart/typescript-openai
- OpenTelemetry(跨语言)版本:可从快速入门页面跳转
- 评估快速入门(https://mlflow.org/docs/latest/genai/eval-monitor/quickstart/)——使用LLM评估器(评分器)评估GenAI应用的质量。内容包括定义数据集、预测函数,以及内置和自定义评分器的使用。
- 版本跟踪快速入门(https://mlflow.org/docs/latest/genai/version-tracking/quickstart/)——提示词管理、应用版本控制,以及将追踪数据与版本化提示词关联。
如果以上教程均不符合用户需求,可查阅MLflow GenAI文档获取更多相关指南。
Traditional ML Path
传统ML路径
The MLflow ML documentation is at: https://mlflow.org/docs/latest/ml/getting-started/
Choose the most relevant tutorials based on the user's context and what they've told you. Available tutorials include:
- Tracking Quickstart (https://mlflow.org/docs/latest/ml/tracking/quickstart/) — Experiment tracking with scikit-learn: autologging, manual parameter/metric/model logging, and exploring results in the MLflow UI.
- Deep Learning Tutorial (https://mlflow.org/docs/latest/ml/getting-started/deep-learning/) — Training a PyTorch model with MLflow logging: parameters, metrics, checkpoints, and system metrics (GPU utilization, memory).
- Hyperparameter Tuning Tutorial (https://mlflow.org/docs/latest/ml/getting-started/hyperparameter-tuning/) — Running hyperparameter searches with Optuna + MLflow, comparing results, and selecting the best model.
If none of these match the user's needs, look up the MLflow ML documentation for more relevant guides.
MLflow ML文档地址:https://mlflow.org/docs/latest/ml/getting-started/
根据用户的上下文和需求选择最相关的教程,可用教程包括:
- 跟踪快速入门(https://mlflow.org/docs/latest/ml/tracking/quickstart/)——使用scikit-learn进行实验跟踪:自动日志记录、手动参数/指标/模型日志记录,以及在MLflow UI中探索结果。
- 深度学习教程(https://mlflow.org/docs/latest/ml/getting-started/deep-learning/)——结合MLflow日志记录训练PyTorch模型:参数、指标、检查点和系统指标(GPU利用率、内存)。
- 超参数调优教程(https://mlflow.org/docs/latest/ml/getting-started/hyperparameter-tuning/)——使用Optuna + MLflow运行超参数搜索、比较结果并选择最佳模型。
如果以上教程均不符合用户需求,可查阅MLflow ML文档获取更多相关指南。
Step 3: Integrate MLflow into the User's Project
步骤3:将MLflow集成到用户项目中
After the user has reviewed the quickstart tutorials (or opted to skip them), offer to help integrate MLflow directly into their codebase. Always ask for the user's consent before making changes to their code.
用户查看快速入门教程后(或选择跳过教程),可提供直接将MLflow集成到其代码库的帮助。在修改用户代码前,必须先获得用户的同意。
GenAI Integration
GenAI集成
The core integration for GenAI apps is tracing — capturing LLM calls, tool invocations, and agent steps automatically.
If asked to create an example project: Do not assume the user has LLM API keys (e.g., OpenAI, Anthropic). Instead, create traces with mock data using and to demonstrate tracing without requiring external API access. For example:
@mlflow.tracemlflow.start_span()python
import mlflow
mlflow.set_experiment("example-genai-app")
@mlflow.trace
def mock_chat(query: str) -> str:
with mlflow.start_span(name="retrieve_context") as span:
context = "Mock retrieved context for: " + query
span.set_inputs({"query": query})
span.set_outputs({"context": context})
with mlflow.start_span(name="generate_response") as span:
response = "Mock response based on: " + context
span.set_inputs({"context": context, "query": query})
span.set_outputs({"response": response})
return response
mock_chat("What is MLflow?")What to set up (for an existing project):
-
Autologging — If the user's code uses a supported framework, a single line automatically traces all calls to their LLM provider. See https://mlflow.org/docs/latest/genai/tracing/ for the full list of supported providers. If the provider is supported:python
import mlflow # Pick the one that matches the user's LLM provider: mlflow.openai.autolog() # OpenAI SDK mlflow.anthropic.autolog() # Anthropic SDK mlflow.langchain.autolog() # LangChain / LangGraph mlflow.litellm.autolog() # LiteLLMAdd this call once at application startup (e.g., top of,main.py, or the entry point module). It must execute before any LLM calls are made.app.pyIf the provider is not supported by autologging, skip to step 3 (Custom tracing) and useto manually instrument the relevant functions.@mlflow.trace -
Experiment configuration — Set the experiment so traces are organized:python
mlflow.set_experiment("my-genai-app")Or via environment variable:export MLFLOW_EXPERIMENT_NAME="my-genai-app" -
Custom tracing (optional) — For functions that aren't automatically traced (custom tools, business logic), use thedecorator:
@mlflow.tracepython@mlflow.trace def my_custom_tool(query: str) -> str: # ... tool logic ... return result
Where to add it: Find the application's entry point or initialization module and add the autologging call there. Search for the main LLM client instantiation (e.g., , ) to find the right location.
openai.OpenAI()ChatOpenAI()GenAI应用的核心集成是tracing(追踪)——自动捕获LLM调用、工具调用和代理步骤。
如果用户要求创建示例项目:请勿假设用户拥有LLM API密钥(如OpenAI、Anthropic)。应使用和生成模拟数据的追踪记录,无需外部API即可演示追踪功能。示例如下:
@mlflow.tracemlflow.start_span()python
import mlflow
mlflow.set_experiment("example-genai-app")
@mlflow.trace
def mock_chat(query: str) -> str:
with mlflow.start_span(name="retrieve_context") as span:
context = "Mock retrieved context for: " + query
span.set_inputs({"query": query})
span.set_outputs({"context": context})
with mlflow.start_span(name="generate_response") as span:
response = "Mock response based on: " + context
span.set_inputs({"context": context, "query": query})
span.set_outputs({"response": response})
return response
mock_chat("What is MLflow?")现有项目的集成配置:
-
自动日志记录——如果用户的代码使用受支持的框架,仅需一行代码即可自动追踪所有LLM提供商的调用。受支持的提供商完整列表请查看https://mlflow.org/docs/latest/genai/tracing/。如果提供商受支持:python
import mlflow # 选择与用户LLM提供商匹配的代码: mlflow.openai.autolog() # OpenAI SDK mlflow.anthropic.autolog() # Anthropic SDK mlflow.langchain.autolog() # LangChain / LangGraph mlflow.litellm.autolog() # LiteLLM将此调用添加到应用启动时执行的位置(例如、main.py的顶部或入口模块),且必须在所有LLM调用之前执行。app.py如果提供商不支持自动日志记录,跳至步骤3(自定义追踪),使用装饰器手动埋点相关函数。@mlflow.trace -
实验配置——设置实验以组织追踪记录:python
mlflow.set_experiment("my-genai-app")或通过环境变量设置:export MLFLOW_EXPERIMENT_NAME="my-genai-app" -
自定义追踪(可选)——对于未被自动追踪的函数(自定义工具、业务逻辑),使用装饰器:
@mlflow.tracepython@mlflow.trace def my_custom_tool(query: str) -> str: # ... 工具逻辑 ... return result
代码添加位置:找到应用的入口点或初始化模块,添加自动日志记录调用。可通过搜索主要LLM客户端实例化代码(如、)确定合适的位置。
openai.OpenAI()ChatOpenAI()Traditional ML Integration
传统ML集成
The core integration for ML is experiment tracking — capturing parameters, metrics, and models from training runs.
What to set up:
-
Autologging — If the user's code uses a supported framework, a single line automatically logs parameters, metrics, and models during training. See https://mlflow.org/docs/latest/ml/ for the full list of supported frameworks. If the framework is supported:python
import mlflow # Pick the one that matches the user's ML framework: mlflow.sklearn.autolog() # scikit-learn mlflow.pytorch.autolog() # PyTorch / PyTorch Lightning mlflow.tensorflow.autolog() # TensorFlow / Keras mlflow.xgboost.autolog() # XGBoost mlflow.lightgbm.autolog() # LightGBMAdd this call once before training starts. It automatically capturescalls, logged metrics, and model artifacts.model.fit()If the framework is not supported by autologging, skip to step 3 (Manual logging) and use,mlflow.log_param(), andmlflow.log_metric()to log data explicitly.mlflow.log_artifact() -
Experiment configuration — Set the experiment so runs are organized:python
mlflow.set_experiment("my-ml-experiment")Or via environment variable:export MLFLOW_EXPERIMENT_NAME="my-ml-experiment" -
Manual logging (optional) — For metrics or parameters not captured by autologging:python
with mlflow.start_run(): mlflow.log_param("custom_param", value) mlflow.log_metric("custom_metric", value)
Where to add it: Find the training script or module where (or equivalent) is called. Add the autologging call before the training loop begins.
model.fit()传统机器学习的核心集成是实验跟踪——捕获训练过程中的参数、指标和模型。
集成配置内容:
-
自动日志记录——如果用户的代码使用受支持的框架,仅需一行代码即可自动记录训练过程中的参数、指标和模型。受支持的框架完整列表请查看https://mlflow.org/docs/latest/ml/。如果框架受支持:python
import mlflow # 选择与用户ML框架匹配的代码: mlflow.sklearn.autolog() # scikit-learn mlflow.pytorch.autolog() # PyTorch / PyTorch Lightning mlflow.tensorflow.autolog() # TensorFlow / Keras mlflow.xgboost.autolog() # XGBoost mlflow.lightgbm.autolog() # LightGBM将此调用添加到训练开始前执行的位置。它会自动捕获调用、记录的指标和模型产物。model.fit()如果框架不支持自动日志记录,跳至步骤3(手动日志记录),使用、mlflow.log_param()和mlflow.log_metric()显式记录数据。mlflow.log_artifact() -
实验配置——设置实验以组织训练运行记录:python
mlflow.set_experiment("my-ml-experiment")或通过环境变量设置:export MLFLOW_EXPERIMENT_NAME="my-ml-experiment" -
手动日志记录(可选)——对于未被自动捕获的指标或参数:python
with mlflow.start_run(): mlflow.log_param("custom_param", value) mlflow.log_metric("custom_metric", value)
代码添加位置:找到执行(或等效代码)的训练脚本或模块,在训练循环开始前添加自动日志记录调用。
model.fit()Verification
验证
After integration, verify that MLflow is capturing data correctly:
完成集成后,验证MLflow是否正确捕获数据:
GenAI Verification
GenAI验证
- Run the application and trigger at least one LLM call
- Check for traces:
bash
mlflow traces search \ --experiment-id <EXPERIMENT_ID> \ --max-results 5 \ --extract-fields 'info.trace_id,info.state,info.request_time' \ --output json > /tmp/verify_traces.json jq '.traces | length' /tmp/verify_traces.json - If traces appear, open the MLflow UI to inspect them visually
- 运行应用并触发至少一次LLM调用
- 检查追踪记录:
bash
mlflow traces search \ --experiment-id <EXPERIMENT_ID> \ --max-results 5 \ --extract-fields 'info.trace_id,info.state,info.request_time' \ --output json > /tmp/verify_traces.json jq '.traces | length' /tmp/verify_traces.json - 如果存在追踪记录,打开MLflow UI可视化查看
ML Verification
ML验证
- Run the training script
- Check for runs:
bash
mlflow runs search \ --experiment-id <EXPERIMENT_ID> \ --max-results 5 \ --output json > /tmp/verify_runs.json jq '.runs | length' /tmp/verify_runs.json - If runs appear, open the MLflow UI to inspect logged parameters, metrics, and artifacts
- 运行训练脚本
- 检查训练运行记录:
bash
mlflow runs search \ --experiment-id <EXPERIMENT_ID> \ --max-results 5 \ --output json > /tmp/verify_runs.json jq '.runs | length' /tmp/verify_runs.json - 如果存在训练运行记录,打开MLflow UI查看记录的参数、指标和产物