jevlaya
Português (Brasil)
Documentação

Adoção por etapas

O Laya devolve uma decisão tipada, não permissão para executá-la. Adote um motor de decisão por etapas para que a aplicação mantenha o controle da ação real enquanto as evidências se acumulam.

Este guia descreve o rollout do lado da aplicação em torno do Laya. O Laya fornece a decisão, as probabilidades, a confiança e os eventos de hook; a aplicação é dona da ação incumbente, da política de rollout, da fronteira de revisão e do rollback.

1. Sombra: observe sem efeitos colaterais

Rode o Laya em tráfego real representativo, mas mantenha a ação incumbente como autoritativa. Um registro de sombra deve conter contexto suficiente para reproduzir uma comparação depois:

  • a classe da solicitação e o esquema de perguntas do Laya;
  • a resposta do Laya, probabilidades por opção, confiança, checkpoint e run_id;
  • a ação incumbente e o desfecho final revisado ou de verdade de referência;
  • latência, erros e qualquer decisão de fallback ou revisão.

Use os hooks de predição existentes para a evidência do lado do Laya. As funções de log abaixo são placeholders da aplicação; elas não são APIs do Laya:

from laya import Router

class ShadowLog:
    def on_predict_end(self, ctx):
        result = ctx.results[0] if ctx.results else None
        write_shadow_record({
            "run_id": ctx.run_id,
            "model": ctx.model,
            "decision": ctx.decision,
            "result": result,
            "elapsed_ms": ctx.elapsed_ms,
            "error": None if ctx.error is None else repr(ctx.error),
        })

router = Router(hooks=[ShadowLog()])

def handle(request):
    try:
        laya_result = router.predict(request.state, request.questions)
    except Exception as exc:
        record_laya_failure(request, exc)
        return run_incumbent_action(request)
    # The shadow result is recorded by the hook; do not execute it here.
    return run_incumbent_action(request)

Mantenha os campos sensíveis censurados conforme a política da aplicação. Capture e registre exceções em torno de router.predict(...) na fronteira da aplicação. O hook de predição cobre o ciclo de vida da predição, mas falhas anteriores a esse ciclo de vida exigem captura no nível da aplicação; não suponha que on_predict_end as viu. Um logger de sombra não deve transformar o logging em uma nova ação voltada ao usuário.

Veja Hooks de predição, o ciclo de vida dos hooks e o Tracing para a ordem dos eventos e a correlação por run_id.

2. Compare: a discordância é um sinal, não um veredito

Compare o Laya com o incumbente na mesma solicitação e no mesmo significado de pergunta. Uma discordância não é automaticamente um erro: o incumbente pode estar errado, os casos podem ser ambíguos, ou a ação pode exigir julgamento humano. Use rótulos revisados ou desfechos de verdade de referência quando disponíveis, e mantenha um bucket explícito de unknown ou revisão em vez de forçar toda discordância em um score binário.

Revise as comparações por checkpoint, idioma ou rota, esquema de perguntas, tipo de ação e classe de risco. Registre cobertura e discordância ao lado da precisão. Uma alta taxa de concordância em um subconjunto fácil não justifica a promoção para outro idioma, ação ou formato de pergunta.

3. Escolha uma política a partir de evidências reservadas

Um limiar de confiança é uma política da aplicação, não uma propriedade fornecida pelo Laya. Ajuste ou calibre os scores de decisão em dados reservados representativos, depois escolha um limiar a partir da precisão medida e do custo do erro na cobertura que a sua aplicação tolera. Não há um número universal que se transfira entre checkpoints, tipos de pergunta, idiomas ou riscos de ação.

Registre o checkpoint e a versão do esquema de perguntas, o método de calibração, o limiar, o conjunto de avaliação e o responsável junto com a política. Reavalie-a quando essas entradas mudarem. A confiança ordena decisões; ela não estabelece que uma decisão está correta, e alta confiança nunca é permissão de execução por si só.

Quatro desses seis vêm do harness de avaliação: um relatório laya-evals run --json registra o commit do checkpoint que respondeu (config.revisions), os bytes do conjunto de dados e o esquema de perguntas (config.dataset_sha256, config.questions_sha256) e o gate sob o qual foi pontuado (config.thresholds). Método de calibração e responsável são da aplicação registrar. Veja Harness de avaliação para a identidade da execução e a checagem de comparabilidade entre uma linha de base e um candidato.

As seções do README Automated Confidence Gating, Calibration e Honest limits dão o contexto existente de calibração e confiança. Mantenha ações irreversíveis ou de alto custo atrás de uma fronteira de revisão explícita mesmo quando a confiança for alta.

4. Promova uma fatia limitada

A promoção deve ser uma mudança medida e reversível, não um interruptor global de liga/desliga. Defina uma fronteira de elegibilidade antes de habilitar a automação, por exemplo:

  • o checkpoint, o idioma/rota e o esquema de perguntas estão no conjunto avaliado;
  • a ação é reversível ou tem um caminho explícito de revisão humana;
  • a solicitação não está sem contexto obrigatório e não tem erro do Laya;
  • a fatia tem um teto de tamanho ou tráfego e uma condição de rollback nomeada.

Comece com um canário pequeno. Mantenha revisão ou fallback para casos inelegíveis, ambíguos e falhos. Continue amostrando as decisões promovidas, compare-as com o incumbente e com os desfechos revisados, e monitore discordância, cobertura, taxa de fallback, erros e latência. Faça rollback quando o guardrail acordado for violado; a promoção é um passo limitado, não uma declaração permanente de que o modelo está correto.

Fronteira aplicação/Laya

O Laya fornece a evidência de decisão e a expõe através da API e dos hooks existentes. A aplicação é dona do resultado incumbente, da execução da ação, das regras de elegibilidade, do limiar, da revisão, do fallback e do rollback. Os hooks podem registrar ou anotar evidências, mas não tornam uma ação de alto impacto segura de executar.

Um rollout prático é, portanto:

real request
    ├─ incumbent action (authoritative)
    └─ Laya shadow decision ──> log, compare, evaluate
                                  └─ bounded eligible slice
                                      └─ review / fallback / rollback

Checklist de rollout

  • O log de sombra é livre de efeitos colaterais e correlacionado por run_id.
  • Os dados de comparação incluem o desfecho incumbente e rótulos revisados ou de verdade de referência quando disponíveis.
  • Os limiares são ajustados e validados em dados reservados representativos.
  • Ações irreversíveis ou de alto custo têm uma fronteira de revisão explícita.
  • A promoção é limitada, amostrada e reversível, com um caminho nomeado de fallback e rollback.
  • O responsável pela política e o gatilho de reavaliação estão registrados.

Veja também