Juge RetrievalSufficiency

Le juge RetrievalSufficiency évalue si le contexte récupéré (des applications RAG, des agents ou tout système qui récupère des documents) contient suffisamment d'informations pour répondre adéquatement à la demande de l'utilisateur en fonction de l'étiquette de vérité terrain fournie en tant que expected_facts ou un expected_response. Ce juge LLM intégré est conçu pour l'évaluation des systèmes RAG où vous devez vous assurer que votre processus d'extraction fournit toutes les informations nécessaires.

Pour plus de détails sur l'API, consultez la documentation MLflow.

Pour la documentation détaillée et des exemples supplémentaires, consultez la documentation MLflow RetrievalSufficiency.

Prérequis pour l'exécution des exemples

1. Installez MLflow et les packages requis.

   Python

   %pip install --upgrade "mlflow[databricks]>=3.4.0"
   dbutils.library.restartPython()

2. Créez une expérience MLflow en suivant le guide de démarrage rapide de configuration de votre environnement.

Exemples d’utilisation

Le juge RetrievalSufficiency peut être appelé directement pour une évaluation de trace unique ou utilisé avec le cadre d'évaluation de MLflow pour l'évaluation par batch.

Exigences :

• Exigences de traçabilité :

  • La trace MLflow doit contenir au moins un span avec span_type défini sur RETRIEVER
  • inputs et outputs doit être sur la portée racine de la trace

• Labels de vérité terrain : requis - vous devez fournir soit expected_facts soit expected_response dans le dictionnaire expectations

Invoke directly

Python

from mlflow.genai.scorers import retrieval_sufficiency
import mlflow

# Get a trace from a previous run
trace = mlflow.get_trace("<your-trace-id>")

# Assess if the retrieved context is sufficient for the expected facts
feedback = retrieval_sufficiency(
    trace=trace,
    expectations={
        &quot;expected_facts&quot;: [
            &quot;MLflow has main components&quot;,
            &quot;Components include Tracing&quot;,
            &quot;Components include Evaluation&quot;,
            &quot;Components include Prompt Engineering&quot;,
            &quot;Components include Model Registry&quot;
        ]
    }
)
print(feedback)

Invoke with evaluate()

Python

import mlflow
from mlflow.genai.scorers import RetrievalSufficiency

# Evaluate traces from previous runs with ground truth expectations
results = mlflow.genai.evaluate(
    data=eval_dataset,  # Dataset with trace data and expected_facts
    scorers=[RetrievalSufficiency()]
)

Exemple de RAG

Voici un exemple complet montrant comment créer une application RAG et évaluer si le contexte récupéré est suffisant :

1. Initialisez un client OpenAI pour vous connecter soit à des LLM hébergés par Databricks, soit à des LLM hébergés par OpenAI.

Databricks-hosted LLMs

Utilisez databricks-openai pour obtenir un client OpenAI qui se connecte aux LLM hébergés par Databricks. Sélectionnez un modèle parmi les modèles de fondation disponibles.

Python

import mlflow
from databricks_openai import DatabricksOpenAI

# Enable MLflow's autologging to instrument your application with Tracing
mlflow.openai.autolog()

# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/docs-demo")

# Create an OpenAI client that is connected to Databricks-hosted LLMs
client = DatabricksOpenAI()

# Select an LLM
model_name = "databricks-claude-sonnet-4"

OpenAI-hosted LLMs

Utilisez le SDK natif OpenAI pour vous connecter aux modèles hébergés par OpenAI. Sélectionnez un modèle parmi les modèles OpenAI disponibles.

Python

import mlflow
import os
import openai

# Ensure your OPENAI_API_KEY is set in your environment
# os.environ["OPENAI_API_KEY"] = "<YOUR_API_KEY>" # Uncomment and set if not globally configured

# Enable auto-tracing for OpenAI
mlflow.openai.autolog()

# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/docs-demo")

# Create an OpenAI client connected to OpenAI SDKs
client = openai.OpenAI()

# Select an LLM
model_name = "gpt-4o-mini"

2. Définir et évaluer votre application RAG :

   Python

   from mlflow.genai.scorers import RetrievalSufficiency
   from mlflow.entities import Document
   from typing import List
   
   
   # Define a retriever function with proper span type
   @mlflow.trace(span_type="RETRIEVER")
   def retrieve_docs(query: str) -> List[Document]:
       # Simulated retrieval - some queries return insufficient context
       if "capital of france" in query.lower():
           return [
               Document(
                   id="doc_1",
                   page_content="Paris is the capital of France.",
                   metadata={"source": "geography.txt"}
               ),
               Document(
                   id="doc_2",
                   page_content="France is a country in Western Europe.",
                   metadata={"source": "countries.txt"}
               )
           ]
       elif "mlflow components" in query.lower():
           # Incomplete retrieval - missing some components
           return [
               Document(
                   id="doc_3",
                   page_content="MLflow has multiple components including Tracing and Evaluation.",
                   metadata={"source": "mlflow_intro.txt"}
               )
           ]
       else:
           return [
               Document(
                   id="doc_4",
                   page_content="General information about data science.",
                   metadata={"source": "ds_basics.txt"}
               )
           ]
   
   # Define your RAG app
   @mlflow.trace
   def rag_app(query: str):
       # Retrieve documents
       docs = retrieve_docs(query)
       context = "\n".join([doc.page_content for doc in docs])
   
       # Generate response
       messages = [
           {"role": "system", "content": f"Answer based on this context: {context}"},
           {"role": "user", "content": query}
       ]
   
       response = client.chat.completions.create(
           # This example uses Databricks hosted Claude.  If you provide your own OpenAI credentials, replace with a valid OpenAI model e.g., gpt-4o, etc.
           model=model_name,
           messages=messages
       )
   
       return {"response": response.choices[0].message.content}
   
   # Create evaluation dataset with ground truth
   eval_dataset = [
       {
           "inputs": {"query": "What is the capital of France?"},
           "expectations": {
               "expected_facts": ["Paris is the capital of France."]
           }
       },
       {
           "inputs": {"query": "What are all the MLflow components?"},
           "expectations": {
               "expected_facts": [
                   "MLflow has main components",
                   "Components include Tracing",
                   "Components include Evaluation",
                   "Components include Prompt Engineering",
                   "Components include Model Registry"
               ]
           }
       }
   ]
   
   # Run evaluation with RetrievalSufficiency scorer
   eval_results = mlflow.genai.evaluate(
       data=eval_dataset,
       predict_fn=rag_app,
       scorers=[
           RetrievalSufficiency(
               model="databricks:/databricks-gpt-oss-120b",  # Optional. Defaults to custom Databricks model.
           )
       ]
   )

Comprendre les résultats

Le marqueur RetrievalSufficiency évalue chaque étendue de récupérateur séparément. Il fera :

• Renvoyer « yes » si les documents récupérés contiennent toutes les informations nécessaires pour générer les faits attendus
• Retournez « non » si les documents récupérés manquent d'informations critiques, ainsi qu'une justification expliquant ce qui manque.

Cela vous aide à identifier le moment où votre système de récupération ne parvient pas à obtenir toutes les informations nécessaires, ce qui est une cause fréquente de réponses incomplètes ou incorrectes dans les applications RAG.

Sélectionnez le LLM qui alimente le juge

Par défaut, les juges intégrés utilisent un LLM hébergé par Databricks, conçu pour effectuer des évaluations de la qualité de l'IA. Vous pouvez changer le modèle de juge en utilisant l'argument model lorsque vous créez le juge. Le modèle doit être spécifié au format <provider>:/<model-name>, où <provider> est un fournisseur de modèles compatible LiteLLM. Si vous utilisez databricks comme fournisseur de modèles, le nom du modèle est le même que le nom de l'Endpoint de diffusion.

Vous pouvez personnaliser le juge en fournissant un modèle de juge différent :

Python

from mlflow.genai.scorers import RetrievalSufficiency

# Use a different judge model
sufficiency_judge = RetrievalSufficiency(
    model="databricks:/databricks-gpt-5-mini"  # Or any LiteLLM-compatible model
)

# Use in evaluation
eval_results = mlflow.genai.evaluate(
    data=eval_dataset,
    predict_fn=rag_app,
    scorers=[sufficiency_judge]
)

Interpréter les résultats

Le juge renvoie un objet Feedback avec :

• value : « oui » si le contexte est suffisant, « non » si insuffisant
• rationale : Explication des faits attendus que le contexte couvre ou ne couvre pas

Ressources supplémentaires

• Évaluer la pertinence du contexte - Assurez-vous que les documents récupérés sont pertinents avant de vérifier leur suffisance
• Évaluer l'ancrage – Vérifiez que les réponses n'utilisent que le contexte fourni
• Créez des dataset d’évaluation – Créez des dataset de vérité terrain avec les faits attendus pour les tests.