Adoção por etapas

O Laya devolve uma decisão tipada, não permissão para a executar. Adota um motor de decisão por etapas para que a aplicação mantenha o controlo da ação real enquanto as evidências se acumulam.

Este guia descreve a implementação gradual 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 em vigor, da política de implementação, do limite de revisão e do rollback.

1. Shadow: observar sem efeitos secundários

Corre o Laya sobre tráfego real representativo, mas mantém a ação em vigor como autoritativa. Um registo de shadow deve conter contexto suficiente para reproduzir uma comparação mais tarde:

• a classe do pedido e o esquema de perguntas do Laya;
• a resposta do Laya, as probabilidades por opção, a confiança, o checkpoint e o run_id;
• a ação em vigor e o resultado eventual revisto ou de referência;
• a latência, os erros e qualquer decisão de fallback ou de revisão.

Usa os hooks de predição existentes para as evidências do lado do Laya. As funções de logging abaixo pertencem à aplicação e são apenas marcadores; 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)

Mantém os campos sensíveis censurados de acordo com a política da aplicação. Apanha e registra exceções em torno de router.predict(...) no limite da aplicação. O hook de predição cobre o ciclo de vida da predição, mas as falhas anteriores a esse ciclo de vida exigem captura ao nível da aplicação; não assumas que o on_predict_end as viu. Um logger de shadow não deve transformar o logging numa nova ação voltada ao utilizador.

Vê os Hooks de predição, o ciclo de vida dos hooks e o Tracing para a ordem dos eventos e a correlação pelo run_id.

2. Comparar: a divergência é um sinal, não um veredicto

Compara o Laya com o sistema em vigor no mesmo pedido e com o mesmo significado de pergunta. Uma divergência não é automaticamente um erro: o sistema em vigor pode estar errado, os casos podem ser ambíguos, ou a ação pode exigir julgamento humano. Usa etiquetas revistas ou resultados de referência quando disponíveis, e mantém um unknown explícito ou um balde de revisão em vez de forçar cada divergência num score binário.

Revê as comparações por checkpoint, idioma ou rota, esquema de perguntas, tipo de ação e classe de risco. Regista a cobertura e a divergência a par da precisão. Uma taxa de concordância elevada num subconjunto fácil não justifica a promoção para um idioma, ação ou forma de pergunta diferentes.

3. Escolher 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. Ajusta ou calibra os scores de decisão sobre dados reservados representativos, e depois escolhe um limiar a partir da precisão e do custo de erro medidos na cobertura que a tua aplicação consegue tolerar. Não há um número universal que se transfira entre checkpoints, tipos de pergunta, idiomas ou riscos de ação.

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

Quatro desses seis vêm do harness de avaliação: um relatório laya-evals run --json regista 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). O método de calibração e o responsável são a aplicação que os regista. Vê o Harness de avaliação para a identidade da execução e a verificação de comparabilidade entre uma linha de base e um candidato.

As secções Automated Confidence Gating, Calibration e Honest limits do README dão o contexto existente de calibração e confiança. Mantém as ações irreversíveis ou de custo elevado atrás de um limite de revisão explícito, mesmo quando a sua confiança é alta.

4. Promover uma fatia limitada

A promoção deve ser uma mudança medida e reversível, e não um interruptor global de ligar/desligar. Define um limite de elegibilidade antes de ativar a automatizaçã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;
• o pedido não tem contexto obrigatório em falta e não tem erro do Laya;
• a fatia tem um limite de tamanho ou de tráfego e uma condição de rollback nomeada.

Começa com um canário pequeno. Mantém a revisão ou o fallback para os casos inelegíveis, ambíguos e falhados. Continua a amostrar as decisões promovidas, compara-as com o sistema em vigor e com os resultados revistos, e monitoriza a divergência, a cobertura, a taxa de fallback, os erros e a latência. Faz 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.

Limite aplicação/Laya

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

Uma implementação prática é, portanto:

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

Lista de verificação da implementação

• O logging de shadow não tem efeitos secundários e é correlacionado pelo run_id.
• Os dados de comparação incluem o resultado em vigor e as etiquetas revistas ou de referência quando disponíveis.
• Os limiares são ajustados e validados sobre dados reservados representativos.
• As ações irreversíveis ou de custo elevado têm um limite de revisão explícito.
• 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 registados.

Ver também

• Hooks de predição — o ponto de extensão para auditoria, métricas e gating.
• Harness de avaliação — a identidade da execução que uma linha de base transporta e a verificação de comparabilidade entre uma linha de base e um candidato.
• Referência da API de hooks — campos de PredictContext e eventos do ciclo de vida.
• Tracing — correlação de run_id e spans.
• README: Automated Confidence Gating — a confiança é uma entrada de política, não uma garantia de correção.
• README: Calibration e Honest limits.