Rótulo durante o desenvolvimento

Como um desenvolvedor que cria aplicativos GenAI, você precisa de uma maneira de acompanhar suas observações sobre a qualidade das saídas do aplicativo. O Rastreamento do MLflow permite que você adicione comentários ou expectativas diretamente aos rastreamentos durante o desenvolvimento, oferecendo uma maneira rápida de registrar problemas de qualidade, marcar exemplos bem-sucedidos ou adicionar anotações para referência futura.

Pré-requisitos

Seu aplicativo está instrumentado com MLflow Tracing
Você gerou rastreamentos executando seu aplicativo

Adicionar rótulos de avaliação

As avaliações anexam comentários estruturados, pontuações ou verdade básica a rastreamentos e intervalos para avaliação e melhoria de qualidade no MLflow.

Interface do usuário do Databricks

Você pode adicionar anotações (rótulos) diretamente aos rastreamentos por meio da interface do usuário do MLflow.

Observação

Se você estiver usando um caderno do Databricks, também poderá executar essas etapas da interface de rastreamento que é integrada ao caderno.

comentários humanos

Navegue até a guia Rastreamentos na interface do usuário do experimento MLflow.
Abra um rastreamento individual.
Na interface de rastreamento, clique no span específico ao qual você deseja atribuir um rótulo.
- Selecionar o span raiz associa feedback à trace inteira.
Expanda a guia Avaliações na extrema direita.
Preencha o formulário para adicionar seus comentários.
- Tipo de avaliação
  - Comentários: Avaliação subjetiva da qualidade (classificações, comentários)
  - Expectativa: a saída ou o valor esperado (o que deveria ter sido produzido)
- Nome da avaliação
  - Um nome exclusivo sobre o que é o feedback
- Tipo de Dados
  - Número
  - booleano
  - fio
- Valor
  - Sua avaliação
- Lógica
  - Notas opcionais sobre o valor
Clique em Criar para salvar seu rótulo.
Quando você retorna à guia Rastreamentos, seu rótulo aparece como uma nova coluna.

MLflow SDK

Você pode adicionar rótulos programaticamente a rastreamentos usando o SDK do MLflow. Isso é útil para rotulagem automatizada com base na lógica do aplicativo ou no processamento em lote de rastreamentos.

O MLflow fornece duas APIs:

mlflow.log_feedback() - Registra comentários que avaliam as saídas reais do aplicativo ou as etapas intermediárias (por exemplo, "A resposta foi boa?", classificações, comentários).
mlflow.log_expectation() – Registra as expectativas que definem o resultado desejado ou correto (verdade básica) que seu aplicativo deve ter produzido.

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",
    ),
)

Exibir avaliações no resumo

Databricks REST API

Crie avaliações usando a API REST do Databricks para registrar comentários e avaliações programaticamente em rastreamentos de qualquer ambiente.

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

Ponto de extremidade da API REST

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

Solicitação de exemplo:

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

Exemplo de resposta:

{
  "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 seu percurso com essas ações e tutoriais recomendados.

Coletar comentários de especialistas em domínio – Configurar sessões de rotulagem estruturada
Criar conjuntos de dados de avaliação – Use seus rastreamentos rotulados para criar conjuntos de dados de teste
Coletar comentários do usuário final – Capturar comentários de aplicativos implantados

Guias de referência

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

Esquemas de rotulagem – Saiba mais sobre a coleção de comentários estruturados

Comentários

Esta página foi útil?

Last updated on 2026-06-01