Referência da API de gerenciamento do ciclo de vida do Scorer

info

Beta

Este recurso está em fase beta.

O monitoramento da produção permite a avaliação contínua da qualidade de suas aplicações GenAI, executando automaticamente avaliadores no tráfego ao vivo. Utilizando o MLflow, é possível registrar qualquer avaliador (incluindo métricas personalizadas e juízes integrados ou personalizados LLM ) e gerenciar seu ciclo de vida por meio de registro, ativação, atualizações e exclusão.

O monitoramento da produção inclui os seguintes recursos:

registrar pontuadores e gerenciar seu ciclo de vida por meio de métodos orientados a objetos.
Taxas de amostragem configuráveis para que você possa controlar a compensação entre cobertura e custo computacional.
Use os mesmos pontuadores no desenvolvimento e na produção para garantir uma avaliação consistente.
Avaliação contínua da qualidade com monitoramento em segundo plano.
Os resultados da avaliação são automaticamente anexados como feedback aos rastreamentos avaliados.
Operações imutáveis que retornam novas instâncias do scorer para um melhor gerenciamento de estado.

Para obter informações sobre o monitoramento de produtos legados, consulte Monitoramento de produção na referência d API (legado).

Visão geral do ciclo de vida do Scorer

O novo ciclo de vida do marcador fornece uma progressão clara em estados distintos:

Não registrado : a função Scorer existe localmente, mas não é conhecida pelo servidor
Registrado : O marcador é salvo no MLflow com um nome (use .register())
Ativo : O marcador está sendo executado com uma taxa de amostragem > 0 (use .start())
Parado : o marcador está registrado, mas não está funcionando (taxa de amostragem = 0, use .stop())
Excluído : O marcador foi completamente removido do servidor (use .delete())

Todas as operações do ciclo de vida são imutáveis — elas retornam novas instâncias do avaliador em vez de modificar o original.

Referência da API

Métodos de instância do Scorer

`Scorer.register()`

Referência da API : Scorer.register

registro uma função de pontuação personalizada com o servidor. Usado para marcadores criados com o decorador @scorer.

Python
@scorer
def custom_scorer(outputs):
    return len(str(outputs.get("response", "")))

# Register the custom scorer
my_scorer = custom_scorer.register(name="response_length")

Parâmetros:

name (str): Nome exclusivo para o marcador do experimento. padrão para o nome existente do avaliador.

Retorna: Nova instância Scorer com registro de servidor

`Scorer.start()`

Referência da API : Scorer.start

Comece a avaliação on-line com a configuração de amostragem especificada.

Python
from mlflow.genai.scorers import ScorerSamplingConfig

# Start monitoring with sampling
active_scorer = registered_scorer.start(
    sampling_config=ScorerSamplingConfig(
        sample_rate=0.5,
        filter_string="trace.status = 'OK'"
    ),
)

Parâmetros:

name (str): Nome do marcador. Se não for fornecido, o padrão será o nome atual do avaliador.
sampling_config (ScorerSamplingConfig): Configuração de amostragem de rastreamento
- sample_rate (float): Fração de traços a serem avaliados (0,0-1,0). padrão: 1.0
- filter_string (str, opcional): filtro compatível com MLFlow para seleção de traços

Retorna: Nova instância Scorer em estado ativo

`Scorer.update()`

Referência da API : Scorer.update

Modifique a configuração de amostragem de um marcador ativo. Esta é uma operação imutável.

Python
# Update sampling rate (returns new scorer instance)
updated_scorer = active_scorer.update(
    sampling_config=ScorerSamplingConfig(
        sample_rate=0.8,
    ),
)

# Original scorer remains unchanged
print(f"Original: {active_scorer.sample_rate}")  # 0.5
print(f"Updated: {updated_scorer.sample_rate}")   # 0.8

Parâmetros:

name (str): Nome do marcador. Se não for fornecido, o padrão será o nome atual do avaliador.
sampling_config (ScorerSamplingConfig): Configuração de amostragem de rastreamento
- sample_rate (float): Fração de traços a serem avaliados (0,0-1,0). padrão: 1.0
- filter_string (str, opcional): filtro compatível com MLFlow para seleção de traços

Retorna: Nova instância Scorer com configuração atualizada

`Scorer.stop()`

Referência da API : Scorer.stop

Pare a avaliação on-line definindo a taxa de amostragem como 0. Mantém o marcador registrado.

Python
# Stop monitoring but keep scorer registered
stopped_scorer = active_scorer.stop()
print(f"Sample rate: {stopped_scorer.sample_rate}")  # 0

Parâmetros:

name (str): Nome do marcador. Se não for fornecido, o padrão será o nome atual do avaliador.

Retorna: Nova instância Scorer com sample_rate=0

Funções de registro de pontuadores

`mlflow.genai.scorers.get_scorer()`

Referência da API : get_scorer

Recupere um marcador registrado pelo nome.

Python
from mlflow.genai.scorers import get_scorer

# Get existing scorer by name
existing_scorer = get_scorer(name="safety_monitor")
print(f"Current sample rate: {existing_scorer.sample_rate}")

Parâmetros:

name (str): Nome do marcador registrado

Retorna: instância Scorer

`mlflow.genai.scorers.list_scorers()`

Liste todos os pontuadores registrados para o experimento atual.

Python
from mlflow.genai.scorers import list_scorers

# List all registered scorers
all_scorers = list_scorers()
for scorer in all_scorers:
    print(f"Name: {scorer._server_name}")
    print(f"Sample rate: {scorer.sample_rate}")
    print(f"Filter: {scorer.filter_string}")

Retorna: Lista de instâncias Scorer

mlflow.genai.scorers.delete_scorer ()

Referência da API : delete_scorer

Exclua um marcador registrado pelo nome.

Python
from mlflow.genai.scorers import delete_scorer

# Delete existing scorer by name
delete_scorer(name="safety_monitor")

Parâmetros:

name (str): Nome do marcador registrado

Devoluções: Nenhuma

Propriedades do marcador

`Scorer.sample_rate`

Taxa de amostragem atual (0,0-1,0). Retorna 0 para marcadores parados.

Python
print(f"Sampling {scorer.sample_rate * 100}% of traces")

`Scorer.filter_string`

Strings de filtro de rastreamento atuais para seleção de rastreamento em MLflow.

Python
print(f"Filter: {scorer.filter_string}")

Classes de configuração

`ScorerSamplingConfig`

Referência da API : ScorerSamplingConfig

Classe de dados que contém a configuração de amostragem para um marcador.

Python
from mlflow.genai import ScorerSamplingConfig

config = ScorerSamplingConfig(
    sample_rate=0.5,
    filter_string="trace.status = 'OK'"
)

Atributos:

sample_rate (flutuante, opcional): taxa de amostragem entre 0,0 e 1,0
filter_string (str, opcional): filtro de rastreamento MLflow

Padrões de uso

Ciclo de vida básico do marcador

Python
from mlflow.genai.scorers import Safety, scorer, ScorerSamplingConfig

# Built-in scorer lifecycle
safety_scorer = Safety().register(name="safety_check")
safety_scorer = safety_scorer.start(
    sampling_config=ScorerSamplingConfig(sample_rate=1.0),
)
safety_scorer = safety_scorer.update(
    sampling_config=ScorerSamplingConfig(sample_rate=0.8),
)
safety_scorer = safety_scorer.stop()
safety_scorer.delete()

# Custom scorer lifecycle
@scorer
def response_length(outputs):
    return len(str(outputs.get("response", "")))

length_scorer = response_length.register(name="length_check")
length_scorer = length_scorer.start(
    sampling_config=ScorerSamplingConfig(sample_rate=0.5),
)

Gerenciando vários marcadores

Python
from mlflow.genai.scorers import Safety, Guidelines, list_scorers

# Register multiple scorers
safety_scorer = Safety().register(name="safety")
safety_scorer = safety_scorer.start(
    sampling_config=ScorerSamplingConfig(sample_rate=1.0),
)

guidelines_scorer = Guidelines(
    name="english",
    guidelines=["Response must be in English"]
).register(name="english_check")
guidelines_scorer = guidelines_scorer.start(
    sampling_config=ScorerSamplingConfig(sample_rate=0.5),
)

# List and manage all scorers
all_scorers = list_scorers()
for scorer in all_scorers:
    if scorer.sample_rate > 0:
        print(f"{scorer.name} is active")
    else:
        print(f"{scorer.name} is stopped")

Atualizações imutáveis

Python
# Demonstrate immutability
original_scorer = Safety().register(name="safety")
original_scorer = original_scorer.start(
   sampling_config=ScorerSamplingConfig(sample_rate=0.3),
)

# Update returns new instance
updated_scorer = original_scorer.update(
    sampling_config=ScorerSamplingConfig(sample_rate=0.8),
)

# Original remains unchanged
print(f"Original: {original_scorer.sample_rate}")  # 0.3
print(f"Updated: {updated_scorer.sample_rate}")    # 0.8

preenchimento de métricas

`backfill_scorers()`

Python
from databricks.agents.scorers import backfill_scorers, BackfillScorerConfig

job_id = backfill_scorers(
    experiment_id="your-experiment-id",
    scorers=[
        BackfillScorerConfig(scorer=safety_scorer, sample_rate=0.8),
        BackfillScorerConfig(scorer=response_length, sample_rate=0.9)
    ],
    start_time=datetime(2024, 1, 1),
    end_time=datetime(2024, 1, 31)
)

Parâmetros:

Todos os parâmetros são somente para palavras-chave.

experiment_id (str, opcional) : O ID do experimento a ser preenchido. Se não for fornecido, usa o contexto atual do experimento
scorers (Union[List[BackfillScorerConfig], List[str]], obrigatório) : Lista de objetos BackfillScorerConfig com taxas de amostragem personalizadas (se sample_rate não for fornecido em BackfillScorerConfig, o padrão será a taxa de amostragem do avaliador registrado) OU lista de nomes de avaliadores (strings) para usar as taxas de amostragem atuais dos avaliadores programados do experimento. Não pode estar vazio.
start_time (datetime, opcional) : hora de início para avaliação do preenchimento retroativo. Se não for fornecido, nenhuma restrição de tempo inicial será aplicada.
end_time (data e hora, opcional) : Hora de término para avaliação do preenchimento. Se não for fornecido, nenhuma restrição de horário de término será aplicada

Retorna: Job ID da tarefa de preenchimento criada para o status acompanhamento (str)

Melhores práticas

Gestão do estado do marcador

Verifique o estado do marcador antes das operações utilizando a propriedade sample_rate.
Use padrão imutável - atribua resultados de .start(), .update(), .stop() às variáveis
Entenda o ciclo de vida - .stop() preserva o registro, .delete() remove completamente

Nomenclatura e organização

Use nomes descritivos que indiquem o objetivo do marcador
Siga convenções de nomenclatura como " safety_check ", " relevance_monitor "
Os nomes devem ser exclusivos em um experimento (máximo de 20 pontuadores por experimento)

Estratégia de amostragem

Pontuadores críticos : use sample_rate=1.0 para verificações de segurança e proteção
Avaliadores caros : utilize taxas de amostragem mais baixas (0,05-0,2) para juízes LLM complexos.
Pontuadores de desenvolvimento : use taxas moderadas (0,3-0,5) para melhoria iterativa

preenchimento de métricas

Comece pequeno : Comece com intervalos de tempo menores para estimar a duração da tarefa e o uso de recursos.
Taxas de amostragem apropriadas : considere as implicações de custo e tempo de altas taxas de amostragem

Próximos passos

Executores de tarefas na produção - Guia passo a passo para habilitar o monitoramento.
Criar um conjunto de dados de avaliação - Utilizar os resultados do monitoramento para melhorar a qualidade.
Crie marcadores personalizados - Crie marcadores adaptados às suas necessidades.

Visão geral do ciclo de vida do Scorer​

Referência da API​

Métodos de instância do Scorer​

Scorer.register()​

Scorer.start()​

Scorer.update()​

Scorer.stop()​

Funções de registro de pontuadores​

mlflow.genai.scorers.get_scorer()​

mlflow.genai.scorers.list_scorers()​

mlflow.genai.scorers.delete_scorer ()​

Propriedades do marcador​

Scorer.sample_rate​

Scorer.filter_string​

Classes de configuração​

ScorerSamplingConfig​

Padrões de uso​

Ciclo de vida básico do marcador​

Gerenciando vários marcadores​

Atualizações imutáveis​

preenchimento de métricas​

backfill_scorers()​

Melhores práticas​

Gestão do estado do marcador​

Nomenclatura e organização​

Estratégia de amostragem​

preenchimento de métricas​

Próximos passos​

Visão geral do ciclo de vida do Scorer

Referência da API

Métodos de instância do Scorer

`Scorer.register()`

`Scorer.start()`

`Scorer.update()`

`Scorer.stop()`

Funções de registro de pontuadores

`mlflow.genai.scorers.get_scorer()`

`mlflow.genai.scorers.list_scorers()`

mlflow.genai.scorers.delete_scorer ()

Propriedades do marcador

`Scorer.sample_rate`

`Scorer.filter_string`

Classes de configuração

`ScorerSamplingConfig`

Padrões de uso

Ciclo de vida básico do marcador

Gerenciando vários marcadores

Atualizações imutáveis

preenchimento de métricas

`backfill_scorers()`

Melhores práticas

Gestão do estado do marcador

Nomenclatura e organização

Estratégia de amostragem

preenchimento de métricas

Próximos passos