mlflow-onboarding

MLflow 入门

选择与用户项目匹配的入门路径：

• GenAI 应用和 Agent — 为聊天机器人、RAG 流水线和工具调用 Agent 提供追踪、评估和提示词管理。
• 传统 ML / 深度学习 — 为 scikit-learn、PyTorch、TensorFlow、XGBoost 和其他训练框架提供实验跟踪、模型记录和部署。

复用现有配置

复用可正常工作的跟踪 URI 和实验，包括 Databricks 工具提供的配置。仅解决缺失的配置，或处理用户要求的后端变更；不要替换已提供的配置文件、凭据或实验。

步骤 1：确定使用场景

按以下顺序检查这些信号。如果使用场景仍不明确，请询问用户。

信号 1：检查代码库

搜索用户的项目，查找能表明使用场景的导入和用法模式：

GenAI 指标：

• 导入 LLM 客户端库：openai、anthropic、google.generativeai、google.genai、langchain、langchain_openai、langgraph、llamaindex、litellm、autogen、crewai、dspy
• 导入 MLflow GenAI 模块：mlflow.genai、mlflow.tracing、mlflow.openai、mlflow.langchain
• 使用聊天补全、嵌入或 Agent 框架
• 提示词模板或提示词工程代码

传统 ML 指标：

• 导入 ML 框架：sklearn、torch、tensorflow、keras、xgboost、lightgbm、catboost、statsmodels、scipy
• 导入 MLflow ML 模块：mlflow.sklearn、mlflow.pytorch、mlflow.tensorflow
• 模型训练循环、.fit() 调用、超参数调优代码
• 加载表格、图像或时间序列数据集

# 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)' .

# 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\()' .

信号 2：检查实验类型标签

如果代码库或项目目录本身就是 MLflow 仓库，请跳到信号 3 — MLflow 仓库包含适用于所有使用场景的代码，因此无法表明用户的意图。

如果已知实验 ID，请检查其 mlflow.experimentKind 标签：

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。

信号 3：询问用户

如果代码库和实验信号都无法明确判断，请直接询问：

您正在构建 GenAI 应用（例如，由 LLM 驱动的聊天机器人、RAG 流水线或工具调用 Agent），还是传统 ML / 深度学习模型（例如，训练分类器、回归模型或神经网络）？

不要猜测使用场景。

步骤 2：推荐快速入门教程

推荐与项目匹配的快速入门教程。询问用户是想要逐步讲解，还是直接集成。

GenAI 路径

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 文档，寻找更相关的指南。

传统 ML 路径

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 文档，寻找更合适的指南。

第 3 步：集成 MLflow

完成教程后，或用户跳过教程时，可提供直接集成方案。更改用户代码前务必征得用户同意。

GenAI 集成

GenAI 应用的核心集成方式是跟踪，即自动捕获 LLM 调用、工具调用和 Agent 步骤。

**如果用户要求创建示例项目：**不要假设用户拥有 LLM API 密钥（例如 OpenAI、Anthropic）。应使用 @mlflow.trace 和 mlflow.start_span() 通过模拟数据创建跟踪，以演示跟踪功能，而无需访问外部 API。例如：

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/。如果该提供商受支持：

   import mlflow
   
   # Pick the one that matches the user's LLM provider:
   mlflow.openai.autolog()       # OpenAI SDK
   mlflow.anthropic.autolog()    # Anthropic SDK
   mlflow.gemini.autolog()       # Google Gemini (google-genai SDK)
   mlflow.langchain.autolog()    # LangChain / LangGraph
   mlflow.litellm.autolog()      # LiteLLM
   

   在应用启动时添加一次此调用（例如，放在 main.py、app.py 或入口模块的顶部）。它必须在发出任何 LLM 调用之前执行。

   如果该提供商不支持自动记录，请跳到步骤 3（自定义跟踪），并使用 @mlflow.trace 手动检测相关函数。

2. 实验配置——设置实验，以便整理跟踪记录：

   mlflow.set_experiment("my-genai-app")
   

   或通过环境变量设置：export MLFLOW_EXPERIMENT_NAME="my-genai-app"

3. 自定义跟踪（可选）——对于不会被自动跟踪的函数（自定义工具、业务逻辑），请使用 @mlflow.trace 装饰器：

   @mlflow.trace
   def my_custom_tool(query: str) -> str:
       # ... tool logic ...
       return result
   

**添加位置：**找到应用的入口或初始化模块，并在那里添加自动记录调用。搜索主要 LLM 客户端的实例化代码（例如 openai.OpenAI()、ChatOpenAI()），以找到合适的位置。

4. 提示词注册表（可选）——MLflow 可以对提示词进行版本管理、存储和加载，让应用代码通过 URI 加载提示词，而不是将模板硬编码。

   import mlflow
   
   # Register a prompt version
   prompt_version = mlflow.genai.register_prompt(
       name="my_prompt",
       template="Answer the user's question: {{question}}",
   )
   print(prompt_version.uri)  # prompts:/my_prompt/1
   
   # Load it back in application code
   prompt = mlflow.genai.load_prompt("prompts:/my_prompt/1")
   

   **在 Databricks（Unity Catalog）上：**提示词存储在 UC catalog.schema 下，因此 name 是三段式的 catalog.schema.my_prompt，并且工作区必须启用 Prompt Registry 预览（账户管理员 -> 预览 -> "Prompt Registry"）。成功后，register_prompt 会记录工作区 UI 链接，并自动将活动实验的 Prompts 选项卡关联到 catalog.schema。如果注册后该选项卡为空，则表示活动实验未自动关联（较旧版本的 mlflow 不会自动设置此标签）。请手动设置：

   mlflow.set_experiment_tag(
       "mlflow.promptRegistryLocation",
       "catalog.schema",  # two-part: catalog.schema (no prompt name)
   )
   

传统 ML 集成

ML 的核心集成是实验跟踪——从训练运行中捕获参数、指标和模型。

需要设置的内容：

1. 自动记录——如果用户的代码使用受支持的框架，只需一行代码，就能在训练过程中自动记录参数、指标和模型。受支持框架的完整列表请参阅 https://mlflow.org/docs/latest/ml/。如果框架受支持：

   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
   

   在训练开始前调用一次。它会自动捕获 model.fit() 调用、记录的指标和模型制品。

   如果框架不支持自动记录，请跳到第 3 步（手动记录），使用 mlflow.log_param()、mlflow.log_metric() 和 mlflow.log_artifact() 显式记录数据。

2. 实验配置——设置实验，以便组织运行：

   mlflow.set_experiment("my-ml-experiment")
   

   或通过环境变量设置：export MLFLOW_EXPERIMENT_NAME="my-ml-experiment"

3. 手动记录（可选）——用于记录自动记录未捕获的指标或参数：

   with mlflow.start_run():
       mlflow.log_param("custom_param", value)
       mlflow.log_metric("custom_metric", value)
   

**添加位置：**找到调用 model.fit()（或等效方法）的训练脚本或模块。在训练循环开始前添加自动记录调用。

验证

GenAI 验证

按照 mlflow-trace-instrumentation 中的验证工作流操作。运行一次经过插桩的应用，然后为回读设置 60 秒的实际时间期限：获取捕获的跟踪 ID，或使用从运行开始时间起的 trace.timestamp_ms 边界和 max_results=1 进行搜索。期限到时后立即取消验证命令，即使 MLflow 调用仍在等待或内部重试。只有在原定期限内完成了具体且快速的修复后，才最多重试一次。确认跟踪和预期的跨度后即可停止；无需额外进行目视检查。

如果因缺少 API 密钥、身份验证、权限或 SQL 仓库缓慢／不可用而无法执行或回读，请提供已验证的步骤、未经验证的结果、观察到的错误，以及用户需要采取的具体操作。不要反复运行应用，也不要尝试 SQL、原始 REST 或其他身份验证方式来完成验证。

ML 验证

1. 运行训练脚本
2. 检查是否有运行：

   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，检查记录的参数、指标和制品