rótulo durante o desenvolvimento

Como desenvolvedor que está criando aplicativos GenAI, você precisa de uma maneira de rastrear suas observações sobre a qualidade dos resultados do seu aplicativo. O MLflow Tracing permite adicionar feedback ou expectativas diretamente aos traços durante o desenvolvimento, oferecendo uma maneira rápida de registrar problemas de qualidade, marcar exemplos bem-sucedidos ou adicionar notas para referência futura.

Pré-requisitos

• Seu aplicativo é instrumentado com o MLflow Tracing
• Você gerou rastreamentos ao executar seu aplicativo

Adicionar avaliação

As avaliações associam feedback estruturado, pontuações ou dados de referência a rastros e trechos para avaliação e melhoria da qualidade no MLflow.

Databricks UI

Você pode adicionar anotações (rótulo) diretamente aos rastreamentos através da interface do usuário MLflow .

nota

Se você estiver usando um Notebook Databricks , também poderá executar essas etapas na interface de rastreamento que é renderizada diretamente no Notebook.

1. Acesse a tab "Traces" na interface do usuário do experimento MLflow .

2. Abra um rastro individual.

3. Na interface de rastreamento, clique no trecho específico que deseja rotular.

   • Selecionar o trecho raiz adiciona feedback a todo o rastreamento.

4. Expanda a tab Avaliações, localizada no canto direito.

5. Preencha o formulário para adicionar seu feedback.

   • Tipo de avaliação

     • Feedback : avaliação subjetiva da qualidade (avaliações, comentários)
     • Expectativa : A produção ou valor esperado (o que deveria ter sido produzido)

   • Nome da avaliação

     • Um nome exclusivo para o assunto do feedback

   • Tipo de dados

     • Número
     • Booleana
     • String

   • Valor

     • Sua avaliação

   • Fundamentação

     • Notas opcionais sobre o valor

6. Clique em Criar para salvar seu rótulo.

7. Ao retornar à tab Rastreamentos, seu rótulo aparecerá como uma nova coluna.

MLflow SDK

O senhor pode adicionar rótulos aos traços de forma programática usando MLflow's SDK. Isso é útil para o rótulo automatizado com base na lógica do aplicativo ou para o processamento de lotes de traços.

O MLflow fornece duas APIs:

• mlflow.log_feedback() - registra o feedback que avalia as saídas reais do seu aplicativo ou os passos intermediários (por exemplo, "A resposta foi boa?", classificações, comentários).
• mlflow.log_expectation() - registra as expectativas que definem o resultado desejado ou correto (verdade fundamental) que seu aplicativo deveria ter produzido.

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

Crie avaliações usando a API REST Databricks para log programaticamente feedbacks e avaliações em rastreamentos de qualquer ambiente.

Consulte a documentação da API REST do Databricks.

endpointAPI REST

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

Exemplo de solicitação:

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

Resposta de exemplo:

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

Próximas etapas

Continue sua jornada com estas ações recomendadas e o tutorial.

• Coletar feedback de especialistas no domínio - Estabelecer sessões estruturadas de rótulo
• Crie um conjunto de dados de avaliação - Use os traços do rótulo para criar um conjunto de dados de teste
• Coletar feedback do usuário final - Capturar feedback dos aplicativos implantados

Guia de referência

Explore a documentação detalhada dos conceitos e recursos mencionados neste guia.

• rótulo schemas - Saiba mais sobre a coleta de feedback estruturado