Étiquette pendant le développement

Lorsque vous développez votre application GenAI, MLflow Tracing vous permet d’ajouter des retours ou des attentes directement aux traces. Vous pouvez enregistrer les problèmes de qualité, marquer les exemples réussis ou ajouter des notes pour référence future. Cela vous permet de suivre la qualité pendant le développement, avant de mettre en place une évaluation formelle.

Prérequis

• Votre application est instrumentée avec MLflow Tracing
• Vous avez généré des traces en exécutant votre application

Ajouter des étiquettes d'évaluation

Les évaluations associent un retour structuré, des scores ou la vérité terrain aux traces et aux spans pour l'évaluation et l'amélioration de la qualité dans MLflow.

Databricks UI

Vous pouvez ajouter des annotations (étiquettes) directement aux traces via l'interface utilisateur MLflow.

remarque

Si vous utilisez un notebook Databricks, vous pouvez également effectuer ces étapes depuis l'interface utilisateur de Trace qui s'affiche en ligne dans le notebook.

1. Accédez à la tab Traces dans l'interface utilisateur de MLflow Experimentation.

2. Ouvrir une trace individuelle.

3. Dans l’interface utilisateur de la trace, cliquez sur le span spécifique que vous souhaitez étiqueter.

   • La sélection du span racine associe un feedback à l’intégralité de la trace.

4. Développez l'onglet tab à l'extrême droite.

5. Remplissez le formulaire pour ajouter votre feedback.

   • Type d'évaluation

     • Rétroaction : Évaluation subjective de la qualité (notes, commentaires)
     • Attente : La sortie ou la valeur attendue (ce qui aurait dû être produit)

   • Nom de l’évaluation

     • Un nom unique pour les commentaires

   • Type de données

     • Nombre
     • Booléen
     • Chaîne

   • Valeur

     • Votre évaluation

   • Justification

     • Notes facultatives concernant la valeur

6. Cliquez sur Créer pour enregistrer votre libellé.

7. Lorsque vous revenez au tab Traces, votre étiquette apparaît comme une nouvelle colonne.

MLflow SDK

Vous pouvez ajouter des labels par programmation aux traces à l'aide du SDK de MLflow. Ceci est utile pour l'étiquetage automatisé basé sur la logique de votre application ou pour le traitement batch des traces.

MLflow fournit deux APIs :

• mlflow.log_feedback() - Logs feedback that evaluates your app's actual outputs or intermediate steps (for example, « La réponse était-elle bonne ? », les notes et les commentaires).
• mlflow.log_expectation() – Logs les attentes qui définissent le résultat souhaité ou correct (vérité terrain) que votre application aurait dû produire.

Python

import mlflow
from mlflow.entities.assessment import (
    AssessmentSource,
    AssessmentSourceType,
    AssessmentError,
)


@mlflow.trace
def my_app(input: str) -> str:
    return input + "_output"


# Create a sample trace to demonstrate assessment logging
my_app(input="hello")

trace_id = mlflow.get_last_active_trace_id()

# Handle case where trace_id might be None
if trace_id is None:
    raise ValueError("No active trace found. Make sure to run a traced function first.")

print(f"Using trace_id: {trace_id}")


# =============================================================================
# LOG_FEEDBACK - Evaluating actual outputs and performance
# =============================================================================

# Example 1: Human rating (integer scale)
# Use case: Domain experts rating response quality on a 1-5 scale
mlflow.log_feedback(
    trace_id=trace_id,
    name="human_rating",
    value=4,  # int - rating scale feedback
    rationale="Human evaluator rating",
    source=AssessmentSource(
        source_type=AssessmentSourceType.HUMAN,
        source_id="evaluator@company.com",
    ),
)

# Example 2: LLM judge score (float for precise scoring)
# Use case: Automated quality assessment using LLM-as-a-judge
mlflow.log_feedback(
    trace_id=trace_id,
    name="llm_judge_score",
    value=0.85,  # float - precise scoring from 0.0 to 1.0
    rationale="LLM judge evaluation",
    source=AssessmentSource(
        source_type=AssessmentSourceType.LLM_JUDGE,
        source_id="gpt-4o-mini",
    ),
    metadata={"temperature": "0.1", "model_version": "2024-01"},
)

# Example 3: Binary feedback (boolean for yes/no assessments)
# Use case: Simple thumbs up/down or correct/incorrect evaluations
mlflow.log_feedback(
    trace_id=trace_id,
    name="is_helpful",
    value=True,  # bool - binary assessment
    rationale="Boolean assessment of helpfulness",
    source=AssessmentSource(
        source_type=AssessmentSourceType.HUMAN,
        source_id="reviewer@company.com",
    ),
)

# Example 4: Multi-category feedback (list for multiple classifications)
# Use case: Automated categorization or multi-label classification
mlflow.log_feedback(
    trace_id=trace_id,
    name="automated_categories",
    value=["helpful", "accurate", "concise"],  # list - multiple categories
    rationale="Automated categorization",
    source=AssessmentSource(
        source_type=AssessmentSourceType.CODE,
        source_id="classifier_v1.2",
    ),
)

# Example 5: Complex analysis with metadata (when you need structured context)
# Use case: Detailed automated analysis with multiple dimensions stored in metadata
mlflow.log_feedback(
    trace_id=trace_id,
    name="response_analysis_score",
    value=4.2,  # single score instead of dict - keeps value simple
    rationale="Analysis: 150 words, positive sentiment, includes examples, confidence 0.92",
    source=AssessmentSource(
        source_type=AssessmentSourceType.CODE,
        source_id="analyzer_v2.1",
    ),
    metadata={  # Use metadata for structured details
        "word_count": "150",
        "sentiment": "positive",
        "has_examples": "true",
        "confidence": "0.92",
    },
)

# Example 6: Error handling when evaluation fails
# Use case: Logging when automated evaluators fail due to API limits, timeouts, etc.
mlflow.log_feedback(
    trace_id=trace_id,
    name="failed_evaluation",
    source=AssessmentSource(
        source_type=AssessmentSourceType.LLM_JUDGE,
        source_id="gpt-4o",
    ),
    error=AssessmentError(  # Use error field when evaluation fails
        error_code="RATE_LIMIT_EXCEEDED",
        error_message="API rate limit exceeded during evaluation",
    ),
    metadata={"retry_count": "3", "error_timestamp": "2024-01-15T10:30:00Z"},
)

# =============================================================================
# LOG_EXPECTATION - Defining ground truth and desired outcomes
# =============================================================================

# Example 1: Simple text expectation (most common pattern)
# Use case: Defining the ideal response for factual questions
mlflow.log_expectation(
    trace_id=trace_id,
    name="expected_response",
    value="The capital of France is Paris.",  # Simple string - the "correct" answer
    source=AssessmentSource(
        source_type=AssessmentSourceType.HUMAN,
        source_id="content_curator@example.com",
    ),
)

# Example 2: Complex structured expectation (advanced pattern)
# Use case: Defining detailed requirements for response structure and content
mlflow.log_expectation(
    trace_id=trace_id,
    name="expected_response_structure",
    value={  # Complex dict - detailed specification of ideal response
        "entities": {
            "people": ["Marie Curie", "Pierre Curie"],
            "locations": ["Paris", "France"],
            "dates": ["1867", "1934"],
        },
        "key_facts": [
            "First woman to win Nobel Prize",
            "Won Nobel Prizes in Physics and Chemistry",
            "Discovered radium and polonium",
        ],
        "response_requirements": {
            "tone": "informative",
            "length_range": {"min": 100, "max": 300},
            "include_examples": True,
            "citations_required": False,
        },
    },
    source=AssessmentSource(
        source_type=AssessmentSourceType.HUMAN,
        source_id="content_strategist@example.com",
    ),
    metadata={
        "content_type": "biographical_summary",
        "target_audience": "general_public",
        "fact_check_date": "2024-01-15",
    },
)

# Example 3: Multiple acceptable answers (list pattern)
# Use case: When there are several valid ways to express the same fact
mlflow.log_expectation(
    trace_id=trace_id,
    name="expected_facts",
    value=[  # List of acceptable variations of the correct answer
        "Paris is the capital of France",
        "The capital city of France is Paris",
        "France's capital is Paris",
    ],
    source=AssessmentSource(
        source_type=AssessmentSourceType.HUMAN,
        source_id="qa_team@example.com",
    ),
)

Databricks REST API

Créez des évaluations à l'aide de l'API REST Databricks pour consigner programmatiquement les commentaires et les évaluations sur les traces de n'importe quel environnement.

Consultez la documentation de l'API REST Databricks.

Endpoint d'API REST

POST https://<workspace-host>.databricks.com/api/3.0/mlflow/traces/{trace_id}/assessments

Exemple de requête :

Bash

curl -X POST \
  "https://<workspace-host>.databricks.com/api/3.0/mlflow/traces/<trace-id>/assessments" \
  -H "Authorization: Bearer <databricks-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "assessment": {
      "assessment_name": "string",
      "create_time": "2019-08-24T14:15:22Z",
      "expectation": {
        "serialized_value": {
          "serialization_format": "string",
          "value": "string"
        },
        "value": {}
      },
      "feedback": {
        "error": {
          "error_code": "string",
          "error_message": "string",
          "stack_trace": "string"
        },
        "value": {}
      },
      "last_update_time": "2019-08-24T14:15:22Z",
      "metadata": {
        "property1": "string",
        "property2": "string"
      },
      "overrides": "string",
      "rationale": "string",
      "source": {
        "source_id": "string",
        "source_type": "HUMAN"
      },
      "span_id": "string",
      "valid": true
    }
  }'

Exemple de réponse :

JSON

{
  "assessment": {
    "assessment_id": "string",
    "assessment_name": "string",
    "create_time": "2019-08-24T14:15:22Z",
    "expectation": {
      "serialized_value": {
        "serialization_format": "string",
        "value": "string"
      },
      "value": {}
    },
    "feedback": {
      "error": {
        "error_code": "string",
        "error_message": "string",
        "stack_trace": "string"
      },
      "value": {}
    },
    "last_update_time": "2019-08-24T14:15:22Z",
    "metadata": {
      "property1": "string",
      "property2": "string"
    },
    "overrides": "string",
    "rationale": "string",
    "source": {
      "source_id": "string",
      "source_type": "HUMAN"
    },
    "span_id": "string",
    "trace_id": "string",
    "valid": true
  }
}

Ressources supplémentaires

• Recueillir les commentaires d'experts du domaine - Configurer des sessions d'étiquetage structurées
• Créez des datasets d'évaluation : Utilisez vos traces étiquetées pour créer des datasets de test.
• Collecter les commentaires des utilisateurs finaux – Capturez les commentaires des applications déployées

Guides de référence

Explorez la documentation détaillée des concepts et fonctionnalités mentionnés dans ce guide.

• Schémas d'étiquetage — Découvrez la collecte structurée de commentaires