mlflow-onboarding

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MLflow 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
    ,
    crewai
    ,
    dspy
  • Imports from MLflow GenAI modules:
    mlflow.genai
    ,
    mlflow.tracing
    ,
    mlflow.openai
    ,
    mlflow.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
    ,
    statsmodels
    ,
    scipy
  • Imports from MLflow ML modules:
    mlflow.sklearn
    ,
    mlflow.pytorch
    ,
    mlflow.tensorflow
  • Model training loops,
    .fit()
    calls, hyperparameter tuning code
  • Dataset loading with tabular/image/time-series data
bash
undefined
搜索用户项目中的导入语句和使用模式,判断用例类型:
GenAI识别特征(满足任意一项即表明为GenAI用例):
  • 导入LLM客户端库:
    openai
    anthropic
    google.generativeai
    langchain
    langchain_openai
    langgraph
    llamaindex
    litellm
    autogen
    crewai
    dspy
  • 导入MLflow GenAI模块:
    mlflow.genai
    mlflow.tracing
    mlflow.openai
    mlflow.langchain
  • 使用聊天补全、嵌入或代理框架
  • 存在提示词模板或提示词工程代码
传统机器学习识别特征(满足任意一项即表明为传统ML用例):
  • 导入机器学习框架:
    sklearn
    torch
    tensorflow
    keras
    xgboost
    lightgbm
    catboost
    statsmodels
    scipy
  • 导入MLflow ML模块:
    mlflow.sklearn
    mlflow.pytorch
    mlflow.tensorflow
  • 模型训练循环、
    .fit()
    调用、超参数调优代码
  • 使用表格/图像/时间序列数据加载数据集
bash
undefined

Search 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()' .
undefined
grep -rl --include='*.py' -E '(from sklearn|import torch|import tensorflow|import keras|import xgboost|import lightgbm|mlflow.sklearn|mlflow.pytorch|mlflow.tensorflow|.fit()' .
undefined

Signal 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
mlflow.experimentKind
tag. This tag is set by MLflow to indicate the experiment type:
bash
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_development
    → GenAI use case
  • custom_model_development
    → Traditional ML use case
  • Not set → Proceed to Signal 3
If the experiment ID is not known, skip to Signal 3.
如果代码库或项目目录是MLflow官方仓库本身,直接跳至信号3——MLflow仓库包含所有用例的代码,无法体现用户的实际需求。
如果已知实验ID,检查其
mlflow.experimentKind
标签。该标签由MLflow设置,用于标识实验类型:
bash
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_development
    → GenAI用例
  • custom_model_development
    → 传统ML用例
  • 未设置 → 继续执行信号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:
If none of these match the user's needs, look up the MLflow GenAI documentation for more relevant guides.

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:
If none of these match the user's needs, look up the MLflow ML documentation for more relevant guides.
根据用户的上下文和需求选择最相关的教程,可用教程包括:
如果以上教程均不符合用户需求,可查阅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
@mlflow.trace
and
mlflow.start_span()
to demonstrate tracing without requiring external API access. For example:
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):
  1. 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()      # LiteLLM
    Add this call once at application startup (e.g., top of
    main.py
    ,
    app.py
    , or the entry point module). It must execute before any LLM calls are made.
    If the provider is not supported by autologging, skip to step 3 (Custom tracing) and use
    @mlflow.trace
    to manually instrument the relevant functions.
  2. 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"
  3. Custom tracing (optional) — For functions that aren't automatically traced (custom tools, business logic), use the
    @mlflow.trace
    decorator:
    python
    @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.,
openai.OpenAI()
,
ChatOpenAI()
) to find the right location.
GenAI应用的核心集成是tracing(追踪)——自动捕获LLM调用、工具调用和代理步骤。
如果用户要求创建示例项目:请勿假设用户拥有LLM API密钥(如OpenAI、Anthropic)。应使用
@mlflow.trace
mlflow.start_span()
生成模拟数据的追踪记录,无需外部API即可演示追踪功能。示例如下:
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?")
现有项目的集成配置
  1. 自动日志记录——如果用户的代码使用受支持的框架,仅需一行代码即可自动追踪所有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
    app.py
    的顶部或入口模块),且必须在所有LLM调用之前执行。
    如果提供商不支持自动日志记录,跳至步骤3(自定义追踪),使用
    @mlflow.trace
    装饰器手动埋点相关函数。
  2. 实验配置——设置实验以组织追踪记录:
    python
    mlflow.set_experiment("my-genai-app")
    或通过环境变量设置:
    export MLFLOW_EXPERIMENT_NAME="my-genai-app"
  3. 自定义追踪(可选)——对于未被自动追踪的函数(自定义工具、业务逻辑),使用
    @mlflow.trace
    装饰器:
    python
    @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:
  1. 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()     # LightGBM
    Add this call once before training starts. It automatically captures
    model.fit()
    calls, logged metrics, and model artifacts.
    If the framework is not supported by autologging, skip to step 3 (Manual logging) and use
    mlflow.log_param()
    ,
    mlflow.log_metric()
    , and
    mlflow.log_artifact()
    to log data explicitly.
  2. 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"
  3. 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
model.fit()
(or equivalent) is called. Add the autologging call before the training loop begins.
传统机器学习的核心集成是实验跟踪——捕获训练过程中的参数、指标和模型。
集成配置内容
  1. 自动日志记录——如果用户的代码使用受支持的框架,仅需一行代码即可自动记录训练过程中的参数、指标和模型。受支持的框架完整列表请查看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()
    显式记录数据。
  2. 实验配置——设置实验以组织训练运行记录:
    python
    mlflow.set_experiment("my-ml-experiment")
    或通过环境变量设置:
    export MLFLOW_EXPERIMENT_NAME="my-ml-experiment"
  3. 手动日志记录(可选)——对于未被自动捕获的指标或参数:
    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验证

  1. Run the application and trigger at least one LLM call
  2. 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
  3. If traces appear, open the MLflow UI to inspect them visually
  1. 运行应用并触发至少一次LLM调用
  2. 检查追踪记录:
    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
  3. 如果存在追踪记录,打开MLflow UI可视化查看

ML Verification

ML验证

  1. Run the training script
  2. 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
  3. If runs appear, open the MLflow UI to inspect logged parameters, metrics, and artifacts
  1. 运行训练脚本
  2. 检查训练运行记录:
    bash
    mlflow runs search \
      --experiment-id <EXPERIMENT_ID> \
      --max-results 5 \
      --output json > /tmp/verify_runs.json
    jq '.runs | length' /tmp/verify_runs.json
  3. 如果存在训练运行记录,打开MLflow UI查看记录的参数、指标和产物