Criar e gerenciar sessões de rótulo

As sessões de rótulo oferecem uma maneira estruturada de coletar feedback de especialistas da área sobre o comportamento de seus aplicativos GenAI. Uma sessão de rótulo é um tipo especial de execução MLflow que contém um conjunto específico de rastreamentos que você deseja que especialistas no domínio revisem usando o aplicativo MLflow Review.

O objetivo de uma sessão de rótulo é coletar avaliações geradas por humanos (rótulo) sobre os Traces existentesMLflow. Você pode capturar Feedback ou Expectations, que podem então ser usados para melhorar seu aplicativo GenAI por meio de avaliação sistemática. Para obter mais informações sobre a coleta de avaliações durante o desenvolvimento do aplicativo, consulte o rótulo durante o desenvolvimento.

nota

Como uma sessão de rótulo é uma execução MLflow , os dados coletados (rastreamentos e avaliações associadas) podem ser acessados programaticamente usando SDKs MLflow (como mlflow.search_runs()) e visualizados na interface do usuário MLflow . Cada sessão de rótulo aparece na tab Avaliações .

Como funcionam as sessões

Ao criar uma sessão de rótulo, você define:

• Nome : Um identificador descritivo para a sessão
• Usuários designados : Especialistas no domínio que fornecerão o rótulo
• Agente : (Opcional) O aplicativo GenAI para gerar respostas, se necessário
• rótulo Schemas : As perguntas e o formato para a coleta de feedback
• Bate-papo com várias voltas : Se o rótulo é compatível com o estilo de conversação

A sessão funciona como um contêiner para traços e seu rótulo associado, permitindo a coleta sistemática de feedback que pode impulsionar a avaliação e o fluxo de trabalho de melhoria.

Criando sessões de criação de rótulo

Use mlflow.genai.labeling.create_labeling_session() para criar novas sessões com configurações específicas.

Crie sessões usando a interface do usuário.

Navegue até o rótulo tab na UI MLflow para criar sessões visualmente. Isso proporciona uma interface intuitiva para definir parâmetros de sessão, atribuir usuários e selecionar esquemas de rótulos sem escrever código.

visualizar sessões usando a interface do usuário

Navegue até o rótulo tab na interface do usuário MLflow para view sessões visualmente.

Criar sessões programaticamente

Use o MLflow SDK para criar sessões com controle programático total sobre todas as opções de configuração.

Criar uma sessão básica

Python

import mlflow.genai.labeling as labeling
import mlflow.genai.label_schemas as schemas

# Create a simple labeling session with built-in schemas
session = labeling.create_labeling_session(
    name="customer_service_review_jan_2024",
    assigned_users=["alice@company.com", "bob@company.com"],
    label_schemas=[schemas.EXPECTED_FACTS]  # Required: at least one schema needed
)

print(f"Created session: {session.name}")
print(f"Session ID: {session.labeling_session_id}")

atenção

Os nomes das sessões do rótulo não têm garantia de serem exclusivos. Várias sessões podem ter o mesmo nome. Para obter acesso programático confiável, armazene e faça referência às sessões pelo ID de execução do MLflow (session.mlflow_run_id) em vez de pelo nome.

nota

Os esquemas de rótulo são necessários ao criar uma sessão de rótulo. Você pode usar esquemas integrados (EXPECTED_FACTS, EXPECTED_RESPONSE, GUIDELINES) ou criar esquemas personalizados. Consulte Criar e gerenciar esquemas de rótulos para obter informações detalhadas sobre como criar e usar esquemas.

Criar uma sessão usando esquemas de rótulos personalizados

Python

import mlflow.genai.labeling as labeling
import mlflow.genai.label_schemas as schemas

# Create custom schemas first
quality_schema = schemas.create_label_schema(
    name="response_quality",
    type="feedback",
    title="Rate the response quality",
    input=schemas.InputCategorical(options=["Poor", "Fair", "Good", "Excellent"]),
    overwrite=True,
)

# Create session using the schemas
session = labeling.create_labeling_session(
    name="quality_assessment_session",
    assigned_users=["expert@company.com"],
    label_schemas=["response_quality", schemas.EXPECTED_FACTS],
)

reg sessões

atenção

Como os nomes das sessões de rótulos não são exclusivos, encontrar sessões pelo nome pode retornar várias correspondências ou resultados inesperados. Para o fluxo de trabalho de produção, recomenda-se armazenar e referenciar as sessões pelo ID de execução MLflow.

Recuperar sessões

Python

import mlflow.genai.labeling as labeling

# Get all labeling sessions
all_sessions = labeling.get_labeling_sessions()
print(f"Found {len(all_sessions)} sessions")

for session in all_sessions:
    print(f"- {session.name} (ID: {session.labeling_session_id})")
    print(f"  Assigned users: {session.assigned_users}")

Agende uma sessão específica.

Python

import mlflow
import mlflow.genai.labeling as labeling
import pandas as pd

# Get all labeling sessions first
all_sessions = labeling.get_labeling_sessions()

# Find session by name (note: names may not be unique)
target_session = None
for session in all_sessions:
    if session.name == "customer_service_review_jan_2024":
        target_session = session
        break

if target_session:
    print(f"Session name: {target_session.name}")
    print(f"Experiment ID: {target_session.experiment_id}")
    print(f"MLflow Run ID: {target_session.mlflow_run_id}")
    print(f"Label schemas: {target_session.label_schemas}")
else:
    print("Session not found")

# Alternative: Get session by MLflow Run ID (if you know it)
run_id = "your_labeling_session_run_id"
run = mlflow.search_runs(
    experiment_ids=["your_experiment_id"],
    filter_string=f"tags.mlflow.runName LIKE '%labeling_session%' AND attribute.run_id = '{run_id}'"
).iloc[0]

print(f"Found labeling session run: {run['run_id']}")
print(f"Session name: {run['tags.mlflow.runName']}")

nota

Como não é garantido que os nomes das sessões do rótulo sejam exclusivos, recomenda-se armazenar e referenciar as sessões pelo ID de execução MLflow quando o senhor precisar recuperar sessões específicas programaticamente.

Excluir sessões

Python

import mlflow.genai.labeling as labeling

# Find the session to delete by name
all_sessions = labeling.get_labeling_sessions()
session_to_delete = None
for session in all_sessions:
    if session.name == "customer_service_review_jan_2024":
        session_to_delete = session
        break

if session_to_delete:
    # Delete the session (removes from Review App)
    review_app = labeling.delete_labeling_session(session_to_delete)
    print(f"Deleted session: {session_to_delete.name}")
else:
    print("Session not found")

Adicionar rastreamentos às sessões

Depois de criada, preencha sua sessão com rastreamentos para análise de especialistas usando o método add_traces().

nota

Para obter detalhes sobre como os rastros são renderizados e exibidos aos rotuladores na interface do usuário do aplicativo Review, incluindo como diferentes tipos de dados (dicionários, mensagens OpenAI, chamadas de ferramentas) são apresentados, consulte a seção Renderização de conteúdo do aplicativo Review.

Adicione rastreamentos usando a interface do usuário.

O senhor também pode adicionar traços diretamente pela interface do usuário MLflow navegando até Traces tab, selecionando os traços que deseja incluir e usando a funcionalidade de exportação para adicioná-los a uma sessão de rótulo.

Adicionar rastros dos resultados da pesquisa

1. Inicialize um cliente OpenAI para se conectar a LLMs hospedados pela Databricks ou LLMs hospedados pela OpenAI.

Databricks-hosted LLMs

Use o MLflow para obter um cliente OpenAI que se conecta aos LLMs hospedados pela Databricks. Selecione um modelo dentre os modelos de base disponíveis.

Python

import mlflow
from databricks.sdk import WorkspaceClient

# Enable MLflow's autologging to instrument your application with Tracing
mlflow.openai.autolog()

# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/docs-demo")

# Create an OpenAI client that is connected to Databricks-hosted LLMs
w = WorkspaceClient()
client = w.serving_endpoints.get_open_ai_client()

# Select an LLM
model_name = "databricks-claude-sonnet-4"

OpenAI-hosted LLMs

Use o SDK nativo do OpenAI para se conectar a modelos hospedados pelo OpenAI. Selecione um modelo dentre os modelos OpenAI disponíveis.

Python

import mlflow
import os
import openai

# Ensure your OPENAI_API_KEY is set in your environment
# os.environ["OPENAI_API_KEY"] = "<YOUR_API_KEY>" # Uncomment and set if not globally configured

# Enable auto-tracing for OpenAI
mlflow.openai.autolog()

# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/docs-demo")

# Create an OpenAI client connected to OpenAI SDKs
client = openai.OpenAI()

# Select an LLM
model_name = "gpt-4o-mini"

2. Crie traços de amostra e adicione-os a uma sessão rótulo:

   Python

   import mlflow.genai.labeling as labeling
   
   
   # First, create some sample traces with a simple app
   @mlflow.trace
   def support_app(question: str):
    """Simple support app that generates responses"""
    mlflow.update_current_trace(tags={"test_tag": "C001"})
    response = client.chat.completions.create(
        model=model_name,  # This example uses Databricks hosted Claude 3.5 Sonnet. If you provide your own OpenAI credentials, replace with a valid OpenAI model e.g., gpt-4o, etc.
        messages=[
            {"role": "system", "content": "You are a helpful customer support agent."},
            {"role": "user", "content": question},
        ],
    )
    return {"response": response.choices[0].message.content}
   
   # Generate some sample traces
   with mlflow.start_run():
    # Create traces with negative feedback for demonstration
    support_app("My order is delayed")
   
    support_app("I can't log into my account")
   
   # Now search for traces to label
   traces_df = mlflow.search_traces(
    filter_string="tags.test_tag = 'C001'", max_results=50
   )
   
   # Create session and add traces
   session = labeling.create_labeling_session(
    name="negative_feedback_review",
    assigned_users=["quality_expert@company.com"],
    label_schemas=["response_quality", "expected_facts"]
   )
   
   # Add traces from search results
   session.add_traces(traces_df)
   print(f"Added {len(traces_df)} traces to session")

Adicionar objetos de rastreamento individuais

1. Inicialize um cliente OpenAI para se conectar a LLMs hospedados pela Databricks ou LLMs hospedados pela OpenAI.

Databricks-hosted LLMs

Use o MLflow para obter um cliente OpenAI que se conecta aos LLMs hospedados pela Databricks. Selecione um modelo dentre os modelos de base disponíveis.

Python

import mlflow
from databricks.sdk import WorkspaceClient

# Enable MLflow's autologging to instrument your application with Tracing
mlflow.openai.autolog()

# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/docs-demo")

# Create an OpenAI client that is connected to Databricks-hosted LLMs
w = WorkspaceClient()
client = w.serving_endpoints.get_open_ai_client()

# Select an LLM
model_name = "databricks-claude-sonnet-4"

OpenAI-hosted LLMs

Use o SDK nativo do OpenAI para se conectar a modelos hospedados pelo OpenAI. Selecione um modelo dentre os modelos OpenAI disponíveis.

Python

import mlflow
import os
import openai

# Ensure your OPENAI_API_KEY is set in your environment
# os.environ["OPENAI_API_KEY"] = "<YOUR_API_KEY>" # Uncomment and set if not globally configured

# Enable auto-tracing for OpenAI
mlflow.openai.autolog()

# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/docs-demo")

# Create an OpenAI client connected to OpenAI SDKs
client = openai.OpenAI()

# Select an LLM
model_name = "gpt-4o-mini"

2. Crie e adicione objetos de rastreamento individuais a uma sessão de rótulo:

   Python

   import mlflow.genai.labeling as labeling
   
   
   # Set up the app to generate traces
   @mlflow.trace
   def support_app(question: str):
    """Simple support app that generates responses"""
    mlflow.update_current_trace(tags={"test_tag": "C001"})
    response = client.chat.completions.create(
        model=model_name,  # This example uses Databricks hosted Claude 3.5 Sonnet. If you provide your own OpenAI credentials, replace with a valid OpenAI model e.g., gpt-4o, etc.
        messages=[
            {"role": "system", "content": "You are a helpful customer support agent."},
            {"role": "user", "content": question},
        ],
    )
    return {"response": response.choices[0].message.content}
   
   # Generate specific traces for edge cases
   with mlflow.start_run() as run:
    # Create traces for specific scenarios
    support_app("What's your refund policy?")
    trace_id_1 = mlflow.get_last_active_trace_id()
   
    support_app("How do I cancel my subscription?")
    trace_id_2 = mlflow.get_last_active_trace_id()
   
    support_app("The website is down")
    trace_id_3 = mlflow.get_last_active_trace_id()
   
   # Get the trace objects
   trace1 = mlflow.get_trace(trace_id_1)
   trace2 = mlflow.get_trace(trace_id_2)
   trace3 = mlflow.get_trace(trace_id_3)
   
   # Create session and add traces
   session = labeling.create_labeling_session(
    name="negative_feedback_review",
    assigned_users=["nikhil.thorat@databricks.com"],
    label_schemas=["response_quality", schemas.EXPECTED_FACTS],
   )
   
   # Add individual traces
   session.add_traces([trace1, trace2, trace3])

gerenciar usuários atribuídos

Requisitos de acesso do usuário

Qualquer usuário em Databricks account pode ser atribuído a uma sessão de rótulo, independentemente de ter acesso a workspace. No entanto, conceder permissão a um usuário para uma sessão de rótulo dará a ele acesso ao experimento MLflow da sessão de rótulo.

Configurar permissões para usuários

• Para usuários que não têm acesso workspace ao, um administrador do account usa accounto SCIM provisionamento de nível para sincronizar usuários e grupos automaticamente do provedor de identidade para o Databricks account. O senhor também pode registrar manualmente esses usuários e grupos para dar-lhes acesso quando configurar identidades em Databricks. Consulte Gerenciamento de usuários e grupos.
• Para os usuários que já têm acesso ao site workspace que contém o aplicativo de revisão, não é necessária nenhuma configuração adicional.

importante

Ao atribuir usuários a uma sessão de rótulo, o sistema concede automaticamente as permissões WRITE necessárias no Experimento MLflow que contém a sessão de rótulo. Isso concede aos usuários designados acesso para view e interagir com os dados do experimento.

Adicionar usuários a sessões existentes

Python

import mlflow.genai.labeling as labeling

# Find existing session by name
all_sessions = labeling.get_labeling_sessions()
session = None
for s in all_sessions:
    if s.name == "customer_review_session":
        session = s
        break

if session:
    # Add more users to the session
    new_users = ["expert2@company.com", "expert3@company.com"]
    session.set_assigned_users(session.assigned_users + new_users)
    print(f"Session now has users: {session.assigned_users}")
else:
    print("Session not found")

Substituir usuários atribuídos

Python

import mlflow.genai.labeling as labeling

# Find session by name
all_sessions = labeling.get_labeling_sessions()
session = None
for s in all_sessions:
    if s.name == "session_name":
        session = s
        break

if session:
    # Replace all assigned users
    session.set_assigned_users(["new_expert@company.com", "lead_reviewer@company.com"])
    print("Updated assigned users list")
else:
    print("Session not found")

Sincronizar com o conjunto de dados de avaliação

Um recurso poderoso é a capacidade de sincronizar os dados coletados Expectations para o conjunto de dados de avaliação.

Como funciona a sincronização dataset

O método sync() executa uma operação de upsert inteligente:

• Chave exclusiva : As entradas de cada rastreamento servem como um key exclusivo para identificar registros na dataset
• Atualizações de expectativa : Para traços com entradas correspondentes, as expectativas da sessão de rótulo substituem as expectativas existentes no site dataset (se os nomes das expectativas forem os mesmos)
• Novos registros : Os traços da sessão de rótulo que não existem no site dataset (com base na correspondência de entrada) são adicionados como novos registros
• Preservação : Os registros existentes no site dataset com diferentes entradas permanecem inalterados

Essa abordagem permite que o senhor melhore iterativamente sua avaliação dataset adicionando novos exemplos e atualizando a verdade básica para os existentes sem perder o trabalho anterior.

sincronização de conjuntos de dados

Python

import mlflow.genai.labeling as labeling

# Find session with completed labels by name
all_sessions = labeling.get_labeling_sessions()
session = None
for s in all_sessions:
    if s.name == "completed_review_session":
        session = s
        break

if session:
    # Sync expectations to dataset
    session.sync(dataset_name="customer_service_eval_dataset")
    print("Synced expectations to evaluation dataset")
else:
    print("Session not found")

Melhores práticas

Organização da sessão

• Nomes descritivos: use nomes claros e marcados com data, como customer_service_review_march_2024
• Escopo focado : mantenha as sessões focadas em metas ou períodos de avaliação específicos
• Tamanho apropriado : procure 25 a 100 traços por sessão para evitar a fadiga do revisor

atenção

Identificação da sessão: como os nomes das sessões não são exclusivos, sempre armazene o session.mlflow_run_id ao criar uma sessão. Use o ID de execução para acesso programático em vez de depender de nomes de sessão.

Python

import mlflow.genai.labeling as labeling

# Good: Store run ID for later reference
session = labeling.create_labeling_session(name="my_session", ...)
session_run_id = session.mlflow_run_id  # Store this!

# Later: Use run ID to find session via mlflow.search_runs()
# rather than searching by name through all sessions

Gestão de usuários

• Atribuições claras : atribua usuários com base na experiência e disponibilidade do domínio
• Carga de trabalho equilibrada : Distribuir o trabalho do rótulo uniformemente entre vários especialistas
• Conhecimento das permissões : Lembre-se de que os usuários precisam de acesso ao Databricks Workspace

Próximos passos

• rótulo existing traces - Guia passo a passo para usar o rótulo sessions
• Criar esquemas de rótulos personalizados - Definir perguntas de feedback estruturado
• Criar conjunto de dados de avaliação - Converter sessões de rótulo em conjunto de dados de teste