GenAI 的 MLflow 评估示例

本页提供了评估工具的一些常见使用模式，包括数据模式和 predict_fn 模式。

常见数据输入模式

使用 MLflow 评估数据集进行评估（建议）

MLflow 评估数据集提供版本控制、世系跟踪和与 Unity 目录的集成，以便进行生产就绪评估。 当你需要评估数据的版本控制和世系跟踪时，以及需要将跟踪转换为评估记录时，它们非常有用。

import mlflow
from mlflow.genai.scorers import Correctness, Safety
from my_app import agent  # Your GenAI app with tracing

# Load versioned evaluation dataset
dataset = mlflow.genai.datasets.get_dataset("catalog.schema.eval_dataset_name")

# Run evaluation
results = mlflow.genai.evaluate(
    data=dataset,
    predict_fn=agent,
    scorers=[Correctness(), Safety()],
)

若要从跟踪或从头开始创建数据集，请参阅 生成评估数据集。

使用字典列表进行评估

使用简单的字典列表进行快速原型制作，而无需创建正式的评估数据集。 这对于快速原型制作、小型数据集（少于 100 个示例）和非正式开发测试非常有用。

import mlflow
from mlflow.genai.scorers import Correctness, RelevanceToQuery
from my_app import agent  # Your GenAI app with tracing

# Define test data as a list of dictionaries
eval_data = [
    {
        "inputs": {"question": "What is MLflow?"},
        "expectations": {"expected_facts": ["open-source platform", "ML lifecycle management"]}
    },
    {
        "inputs": {"question": "How do I track experiments?"},
        "expectations": {"expected_facts": ["mlflow.start_run()", "log metrics", "log parameters"]}
    },
    {
        "inputs": {"question": "What are MLflow's main components?"},
        "expectations": {"expected_facts": ["Tracking", "Projects", "Models", "Registry"]}
    }
]

# Run evaluation
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=agent,
    scorers=[Correctness(), RelevanceToQuery()],
)

对于生产，请转换为 MLflow 评估数据集。

使用 Pandas DataFrame 进行评估

使用 Pandas 数据帧在处理 CSV 文件或现有数据科学工作流时进行评估。 这对于快速原型制作、小型数据集（少于 100 个示例）和非正式开发测试非常有用。

import mlflow
import pandas as pd
from mlflow.genai.scorers import Correctness, Safety
from my_app import agent  # Your GenAI app with tracing

# Create evaluation data as a Pandas DataFrame
eval_df = pd.DataFrame([
    {
        "inputs": {"question": "What is MLflow?"},
        "expectations": {"expected_response": "MLflow is an open-source platform for ML lifecycle management"}
    },
    {
        "inputs": {"question": "How do I log metrics?"},
        "expectations": {"expected_response": "Use mlflow.log_metric() to log metrics"}
    }
])

# Run evaluation
results = mlflow.genai.evaluate(
    data=eval_df,
    predict_fn=agent,
    scorers=[Correctness(), Safety()],
)

使用 Spark 数据帧进行评估

使用 Spark 数据帧进行大规模评估，或者当数据已在 Delta Lake 或 Unity 目录中时。 当 Delta Lake 或 Unity 目录中已存在数据时，或者在运行评估之前需要筛选 MLflow 评估数据集中的记录时，这非常有用。

DataFrame 必须符合 评估数据集架构。

import mlflow
from mlflow.genai.scorers import Safety, RelevanceToQuery
from my_app import agent  # Your GenAI app with tracing

# Load evaluation data from a Delta table in Unity Catalog
eval_df = spark.table("catalog.schema.evaluation_data")

# Or load from any Spark-compatible source
# eval_df = spark.read.parquet("path/to/evaluation/data")

# Run evaluation
results = mlflow.genai.evaluate(
    data=eval_df,
    predict_fn=agent,
    scorers=[Safety(), RelevanceToQuery()],
)

常见 predict_fn 模式

直接调用应用

当参数名称与评估数据集密钥匹配时，直接将应用作为 predict_fn 传递。 这对于具有与评估数据集中匹配 inputs 的参数名称的应用非常有用。

import mlflow
from mlflow.genai.scorers import RelevanceToQuery, Safety

# Your GenAI app that accepts 'question' as a parameter
@mlflow.trace
def my_chatbot_app(question: str) -> dict:
    # Your app logic here
    response = f"I can help you with: {question}"
    return {"response": response}

# Evaluation data with 'question' key matching the function parameter
eval_data = [
    {"inputs": {"question": "What is MLflow?"}},
    {"inputs": {"question": "How do I track experiments?"}}
]

# Pass your app directly since parameter names match
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=my_chatbot_app,  # Direct reference, no wrapper needed
    scorers=[RelevanceToQuery(), Safety()]
)

在可调用对象中包装应用

如果应用需要与评估数据集 inputs不同的参数名称或数据结构，请将其包装在可调用函数中。 当您的应用程序参数与评估数据集 input 键（例如，user_input 与 question）之间存在参数名称不匹配，或者需要进行数据格式转换（例如，将字符串转换为列表，或进行 JSON 解析）时，这会非常有用。

import mlflow
from mlflow.genai.scorers import RelevanceToQuery, Safety

# Your existing GenAI app with different parameter names
@mlflow.trace
def customer_support_bot(user_message: str, chat_history: list = None) -> dict:
    # Your app logic here
    context = f"History: {chat_history}" if chat_history else "New conversation"
    return {
        "bot_response": f"Helping with: {user_message}. {context}",
        "confidence": 0.95
    }

# Wrapper function to translate evaluation data to your app's interface
def evaluate_support_bot(question: str, history: str = None) -> dict:
    # Convert evaluation dataset format to your app's expected format
    chat_history = history.split("|") if history else []

    # Call your app with the translated parameters
    result = customer_support_bot(
        user_message=question,
        chat_history=chat_history
    )

    # Translate output to standard format if needed
    return {
        "response": result["bot_response"],
        "confidence_score": result["confidence"]
    }

# Evaluation data with different key names
eval_data = [
    {"inputs": {"question": "Reset password", "history": "logged in|forgot email"}},
    {"inputs": {"question": "Track my order"}}
]

# Use the wrapper function for evaluation
results = mlflow.genai.evaluate(
    data=eval_data,
    predict_fn=evaluate_support_bot,  # Wrapper handles translation
    scorers=[RelevanceToQuery(), Safety()]
)

评估部署的终结点

使用该 to_predict_fn 函数评估马赛克 AI 代理框架、模型服务聊天终结点和自定义终结点。

此函数创建一个与这些终结点兼容的预测函数，并自动从已启用跟踪的终结点中提取跟踪以实现完全可观测性。

模型部署聊天

模型服务聊天终结点需要使用 messages 密钥格式化的数据。

import mlflow
from mlflow.genai.scorers import RelevanceToQuery

# Create predict function for a chat endpoint
predict_fn = mlflow.genai.to_predict_fn("endpoints:/my-chatbot-endpoint")

# Evaluate the chat endpoint
results = mlflow.genai.evaluate(
    data=[{"inputs": {"messages": [{"role": "user", "content": "How does MLflow work?"}]}}],
    predict_fn=predict_fn,
    scorers=[RelevanceToQuery()]
)

代理框架

代理框架终结点可以具有不同的输入接口。 以下示例显示了一个 input 键：

import mlflow
from mlflow.genai.scorers import RelevanceToQuery

# Create a predict function for a Knowledge Assistant agent endpoint
predict_fn = mlflow.genai.to_predict_fn("endpoints:/ka-56a301ab-endpoint")

# Evaluate the agent endpoint
results = mlflow.genai.evaluate(
    data=[{"inputs": {"input": [{"role": "user", "content": "How do I use the Models from Code feature in MLflow?"}]}}],
    predict_fn=predict_fn,
    scorers=[RelevanceToQuery()]
)

自定义终结点

自定义终结点可能具有完全不同的访问模式，用于向它们提交数据。 确保 data 输入格式与用于评估的终结点兼容。

如果评估数据格式与端点不兼容，请对模型的接口进行封装。 转换层可以确保将正确的有效负载提交到评估终结点。

import mlflow
from mlflow.genai.scorers import RelevanceToQuery

def custom_predict_fn(inputs):
    # Transform inputs to match your endpoint's expected format
    # For example, if your endpoint expects a 'query' key instead of 'messages'
    transformed_inputs = {
        "query": inputs["messages"][0]["content"],
        "context": inputs.get("context", "")
    }

    # Call your endpoint with the transformed data
    original_predict_fn = mlflow.genai.to_predict_fn("endpoints:/my-custom-endpoint")
    return original_predict_fn(transformed_inputs)

# Use your wrapper function for evaluation
results = mlflow.genai.evaluate(
    data=[{"inputs": {"messages": [{"role": "user", "content": "What is machine learning?"}], "context": "technical documentation"}}],
    predict_fn=custom_predict_fn,
    scorers=[RelevanceToQuery()]
)

评估记录的模型

包装记录的 MLflow 模型，以在评估中的命名参数和模型的单参数接口之间进行转换。

大多数已记录的模型（例如使用 PyFunc 或日志变体，如 LangChain）接受一个单一输入参数（例如 model_inputs 对于 PyFunc），而 predict_fn 则需要与评估数据集中的键名对应的命名参数。

import mlflow
from mlflow.genai.scorers import Safety

# Make sure to load your logged model outside of the predict_fn so MLflow only loads it once!
model = mlflow.pyfunc.load_model("models:/chatbot/staging")

def evaluate_model(question: str) -> dict:
    return model.predict({"question": question})

results = mlflow.genai.evaluate(
    data=[{"inputs": {"question": "Tell me about MLflow"}}],
    predict_fn=evaluate_model,
    scorers=[Safety()]
)