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

O MLflow facilita a adição de anotações (rótulos) diretamente aos rastreamentos pela interface 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 de usuário do experimento MLflow
Abrir um rastreamento individual
Dentro da interface de rastreamento, clique no segmento específico que você deseja rotular
- Selecionar o intervalo raiz anexará comentários a todo o rastreamento
Expanda a aba Avaliações à 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ê retornar à guia Rastreamentos, seu rótulo será exibido 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 2025-12-19