Compartir a través de

Etiqueta durante el desarrollo

Como desarrollador que construye aplicaciones GenAI, necesita una manera de realizar un seguimiento de las observaciones sobre la calidad de los resultados de su aplicación. El seguimiento de MLflow le permite agregar comentarios o expectativas directamente a los seguimientos durante el desarrollo, lo que le proporciona una manera rápida de registrar problemas de calidad, marcar ejemplos correctos o agregar notas para referencia futura.

Prerrequisitos

  • Tu aplicación está instrumentada con MLflow Tracing
  • Ha generado seguimientos mediante la ejecución de la aplicación

Adición de etiquetas de evaluación

Las evaluaciones adjuntan comentarios estructurados, puntuaciones o verdades básicas a trazas y tramos para la evaluación y mejora de la calidad en MLflow.

Interfaz de usuario de Databricks

MLflow facilita la adición de anotaciones (etiquetas) directamente a los seguimientos a través de la interfaz de usuario de MLflow.

Nota:

Si está utilizando un notebook de Databricks, también puede realizar estos pasos desde la Trace UI que se presenta en línea en el notebook.

comentarios humanos

  1. Vaya a la pestaña Trazas en la interfaz de usuario del experimento de MLflow.
  2. Abrir un seguimiento individual
  3. Dentro de la interfaz de usuario de seguimiento, haga clic en el intervalo específico que desea etiquetar.
    • Al seleccionar el tramo raíz, se asocian comentarios a todo el seguimiento.
  4. Expanda la pestaña Evaluaciones en el extremo derecho.
  5. Rellene el formulario para agregar sus comentarios.
    • Tipo de evaluación
      • Comentarios: Evaluación subjetiva de la calidad (clasificaciones, comentarios)
      • Expectativa: la salida o el valor esperados (lo que se debe haber producido)
    • Nombre de la evaluación
      • Un nombre único para el tema de los comentarios
    • Tipo de dato
      • Número
      • Booleano
      • Cuerda
    • Valor
      • Su evaluación
    • Fundamento
      • Notas opcionales sobre el valor
  6. Haga clic en Crear para guardar la etiqueta.
  7. Al volver a la pestaña Seguimientos, la etiqueta aparecerá como una nueva columna.

MLflow SDK

Puede agregar etiquetas a seguimientos mediante programación mediante el SDK de MLflow. Esto es útil para el etiquetado automatizado en función de la lógica de la aplicación o para el procesamiento por lotes de rastros.

MLflow proporciona dos API:

  • mlflow.log_feedback() - Registra los comentarios que evalúan las salidas reales de la aplicación o los pasos intermedios (por ejemplo, "¿La respuesta es buena?", clasificaciones, comentarios).
  • mlflow.log_expectation() - Registra las expectativas que definen el resultado deseado o correcto (verdad básica) que la aplicación debe haber generado.
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",
    ),
)

Visualización de evaluaciones en el resumen

Databricks REST API

Cree evaluaciones utilizando la API REST de Databricks para programáticamente registrar comentarios y evaluaciones en los seguimientos de cualquier entorno.

Consulte la documentación de la API rest de Databricks.

Punto de conexión de la API REST

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

Solicitud de ejemplo:

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
    }
  }'

Respuesta de ejemplo:

{
  "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
  }
}

Pasos siguientes

Continúe su recorrido con estas acciones y tutoriales recomendados.

Guías de referencia

Explore la documentación detallada de los conceptos y características mencionados en esta guía.

  • Last updated on