jevlaya
Português (Portugal)
Documentação

Padrões de arquitetura e casos de uso em produção

Laya é um motor de decisão no dispositivo e não autorregressivo, construído sobre uma arquitetura transformer de passagem direta única (ModernBERT-large e mmBERT-base). Em vez de gerar tokens sequencialmente como um LLM (o que acarreta custos variáveis de geração de tokens, sobrecarga do ciclo de descodificação e esquemas de saída imprevisíveis), Laya calcula distribuições de probabilidade calibradas sobre perguntas discretas numa única passagem.

Este documento serve como planta de arquitetura para arquitetos de sistemas e engenheiros de backend que integram o Laya em ambientes de produção.

Motor de decisão vs. LLM vs. recuperação por embeddings

Escolher a primitiva certa depende das restrições de latência, da topologia de alojamento e de a tarefa exigir geração livre ou classificação discreta:

Dimensão Recuperação por embeddings Motor de decisão Laya LLM autorregressivo
Modelo de computação Distância de cosseno entre vetores Passagem direta única (cabeça mascarada não autorregressiva) Geração sequencial token a token
Perfil de execução Procura em índice de vizinhos mais próximos Passagem direta única fixa (sem ciclo de descodificação) Ciclo de descodificação iterativo que escala com o comprimento da saída
Alojamento e topologia Em processo ou base de dados vetorial Em processo (CPU/GPU local) ou daemon HTTP autoalojado API remota alojada ou serviço GPU de modelos grandes
Atenção de contexto Representação vetorial agrupada Atenção cruzada bidirecional profunda sobre toda a entrada Atenção sequencial causal
Saída estruturada Trechos recuperados não estruturados Distribuições nativas alinhadas ao esquema (choice, score, noul) Texto livre que exige reparação de JSON ou amostragem de esquema
Carga de trabalho principal Recuperação ampla de candidatos Classificação discreta, gating de políticas e encaminhamento Síntese aberta, tradução e geração

1. Gateway de entrada inteligente

Em arquiteturas em camadas, uma grande fração dos pedidos de entrada não exige as capacidades generativas de um LLM autorregressivo. Consultas como FAQs padrão, perguntas determinísticas sobre o estado ou decisões categóricas de encaminhamento podem ser avaliadas localmente.

O Laya funciona como um gateway de entrada inteligente: classifica a intenção e a complexidade da consulta numa única passagem direta local. Os pedidos determinísticos são resolvidos localmente através de endpoints internos ou respostas em cache, enquanto as tarefas generativas complexas são encaminhadas para LLMs a montante.

Arquitetura

graph TD
    A[User Request] --> B["<b>Laya Gateway Router</b><br/>• query_complexity: simple | moderate | complex<br/>• intent: faq | account_lookup | creative_synthesis"]
    B -->|Simple & High Confidence| C["<b>Local In-Process Resolution</b><br/>Deterministic FAQ / Internal API"]
    B -->|Complex or Low Confidence| D["<b>Upstream Generative LLM</b><br/>Open-ended synthesis & reasoning"]

Implementação

import laya

agent = laya.load("convaiinnovations/laya")

GATEWAY_QUESTIONS = {
    "complexity": {
        "type": "choice",
        "instructions": "How complex is the user's request?",
        "criteria": {
            "canned": "A greeting, standard FAQ, or simple status request.",
            "structured": "A deterministic data query that can be answered by an API.",
            "complex": "Requires creative generation, multi-step code, or complex analysis.",
        },
    },
    "requires_reasoning": {
        "type": "noul",
        "instructions": "Does this query require frontier model reasoning?",
    },
}

def route_request(user_prompt: str):
    res = agent.system_one(user_prompt, GATEWAY_QUESTIONS, min_confidence=0.85)
    answers = res["answers"]

    complexity = answers["complexity"]["choice"]
    low_confidence = answers["complexity"].get("low_confidence", False)

    # Abstain or escalate if complex or unconfident
    if low_confidence or complexity == "complex" or answers["requires_reasoning"]["noul"] > 0.5:
        return call_frontier_llm(user_prompt)

    if complexity == "canned":
        return lookup_faq_response(user_prompt)
    return execute_internal_api(user_prompt)

2. Router de troca de turnos e interrupção de voz de baixa latência

Agentes de voz conversacionais (WebRTC, telefonia) operam sob restrições rigorosas de troca de turnos: os atrasos a detetar quando um utilizador fala ou interrompe criam silêncios antinaturais na conversa. Esperar que um modelo generativo completo produza o seu primeiro token introduz um atraso evitável quando quem liga apenas confirma ou interrompe.

O Laya pode ser colocado imediatamente a seguir à transcrição de fala para texto (STT) para classificar o fluxo da conversa e a intenção do utilizador numa única passagem direta: acionar áudio de preenchimento rápido ou interromper a reprodução de áudio de imediato quando é detetada uma interrupção, ao mesmo tempo que delega consultas complexas ao pipeline de síntese completo.

Arquitetura

graph TD
    A[User Voice Audio] --> B["<b>Speech-to-Text</b><br/>Streaming Audio Transcription"]
    B --> C["<b>Laya Voice Router</b><br/>• intent: ack | reject | interrupt | inquiry<br/>• is_interruption: noul probability"]
    C -->|Interruption: score &gt; 0.6| D["<b>Halt Audio Playback</b><br/>Immediate playback cutoff"]
    C -->|Quick Intent: ack / reject| E["<b>Immediate Audio Filler</b><br/>Conversational confirmation"]
    C -->|Complex Inquiry| F["<b>Upstream Pipeline</b><br/>Full response synthesis"]

Implementação

from laya import Agent

agent = Agent("convaiinnovations/laya")

VOICE_QUESTIONS = {
    "intent": {
        "type": "choice",
        "instructions": "Caller conversational intention",
        "criteria": {
            "ack": "Caller said yes, ok, sure, or agreed.",
            "reject": "Caller said no, cancel, or disagreed.",
            "interrupt": "Caller said hold on, wait, or wants to stop.",
            "inquiry": "Caller is asking a detailed question.",
        },
    },
    "is_interruption": {
        "type": "noul",
        "instructions": "Is the caller interrupting the current speech playback?",
    },
}

def on_voice_chunk(transcript: str, is_speaking: bool):
    decision = agent.system_one(transcript, VOICE_QUESTIONS)
    answers = decision["answers"]

    # Halt playback immediately if caller interrupts
    if answers["is_interruption"]["noul"] > 0.6:
        stop_audio_playback()

    intent = answers["intent"]["choice"]
    if intent in ("ack", "reject"):
        play_immediate_filler_audio(intent)
    else:
        dispatch_to_background_pipeline(transcript)

3. Segurança pré-LLM e firewall de prompts

Proteger sistemas contra injeções de prompt adversariais, jailbreaks e fuga de dados sensíveis tem de acontecer antes de o prompt chegar à janela de contexto do LLM. Executar um modelo generativo separado apenas para julgar se um prompt é seguro acrescenta latência redundante e sobrecarga operacional.

O Laya atua como um firewall de segurança inline e não autorregressivo, avaliando injeções de prompt, escalonamentos de privilégio e tarefas fora de âmbito numa única passagem direta antes do processamento a jusante.

Arquitetura

graph TD
    A[User Input] --> B["<b>Inline Security Hook</b><br/>• prompt_injection (noul)<br/>• system_prompt_extraction (noul)<br/>• pii_present (noul)"]
    B -->|Policy Violation: score &ge; 0.5| C["<b>Abort &amp; Reject</b><br/>Raise policy exception &amp; audit event"]
    B -->|Clean: score &lt; 0.5| D["<b>Dispatch to Main Workflow</b><br/>Safe to execute"]

Implementação

Os hooks no Laya são duck-typed: qualquer objeto que implemente os métodos de ciclo de vida de Hook (ou que herde de BaseHook em laya.hooks) pode ser anexado a um Agent ou Router.

Sob a semântica padrão de lançamento de hooks do Laya (hooks_raise=True):

  • Lançar uma exceção dentro de on_predict_start aborta a execução imediatamente antes de ocorrerem a tokenização ou a inferência do modelo.
  • A exceção propaga-se diretamente para fora de system_one() / predict() até quem chamou.
  • As limpezas de ciclo de vida (on_error e on_predict_end) são ainda executadas, com ctx.error definido como a exceção lançada, garantindo que os registos de auditoria e a telemetria registam o pedido bloqueado.
import laya
from laya import Router
from laya.hooks import BaseHook, PredictContext

SECURITY_SCHEMA = {
    "is_jailbreak": {
        "type": "noul",
        "instructions": "Is the user attempting a prompt injection, exploit, or jailbreak?",
    },
    "extracts_system_prompt": {
        "type": "noul",
        "instructions": "Is the user asking to reveal instructions, system prompts, or hidden rules?",
    },
    "pii_leak": {
        "type": "noul",
        "instructions": "Does the input contain passwords, API keys, or credentials?",
    },
}

class SecurityFirewallHook(BaseHook):
    """Inspect inputs before inference; raises on policy violation.

    With hooks_raise=True (the default), raising from on_predict_start aborts
    inference immediately and propagates the exception to the caller, while
    allowing any downstream on_error or audit logging hooks to record the event.
    """
    def __init__(self, guard_agent):
        self.guard = guard_agent

    def on_predict_start(self, ctx: PredictContext):
        for state in ctx.states:
            check = self.guard.system_one(state, SECURITY_SCHEMA)
            ans = check["answers"]
            if ans["is_jailbreak"]["noul"] > 0.5 or ans["extracts_system_prompt"]["noul"] > 0.5:
                raise PermissionError("Request blocked by security firewall: adversarial prompt detected.")

# Attach to Router or Agent; hooks_raise=True ensures policy exceptions propagate
guard_agent = laya.load("convaiinnovations/laya")
router = Router(hooks=[SecurityFirewallHook(guard_agent)], hooks_raise=True)

[!TIP] Para workflows do CrewAI, o Laya também fornece LayaTaskGuard pronto a usar em laya.integrations.crewai para exatamente este padrão de porta de segurança pré-execução.

4. Router RAG de periferia em rede isolada

Em ambientes empresariais seguros (defesa, saúde, conformidade financeira, dispositivos de periferia), as APIs externas estão indisponíveis ou são proibidas. As coleções de documentos são frequentemente separadas em domínios distintos (por exemplo, ensaios clínicos, registos de pacientes, relatórios financeiros, especificações técnicas).

Em vez de consultar um único índice vetorial monolítico com embeddings não relacionados, o Laya atua como um router de periferia local que encaminha as consultas do utilizador para o índice vetorial local específico ou para a base de dados SQLite antes da recuperação.

Arquitetura

graph TD
    A["<b>User Query</b><br/>Local / Edge Workstation"] --> B["<b>Laya Edge Router</b><br/>• target_domain: clinical | billing | compliance<br/><i>In-process local routing</i>"]
    B -->|Clinical Domain| C[("<b>Clinical Vector Store</b><br/>Medical trials, dosages & EHR")]
    B -->|Billing Domain| D[("<b>Billing Vector Store</b><br/>Invoices, claims & ICD-10 codes")]
    B -->|Compliance Domain| E[("<b>Compliance Vector Store</b><br/>HIPAA policies & audit guidelines")]

Implementação

from laya import Router

# Automatically routes between local English and Multilingual models
router = Router()

INDEX_QUESTIONS = {
    "target_domain": {
        "type": "choice",
        "instructions": "Which domain index contains the source truth for this query?",
        "criteria": {
            "clinical": "Medical conditions, medications, dosages, and clinical trials.",
            "billing": "Invoices, payment claims, ICD-10 billing codes, and insurance.",
            "compliance": "HIPAA compliance rules, privacy policies, and data audits.",
        },
    }
}

def query_airgapped_rag(user_query: str):
    decision = router.predict(user_query, INDEX_QUESTIONS)
    domain = decision["answers"]["target_domain"]["choice"]

    # Load and search only the relevant isolated local index
    local_index = get_isolated_vector_store(domain)
    return local_index.similarity_search(user_query, k=4)

5. Delegação hierárquica de tarefas entre vários agentes

Os frameworks multiagente recorrem frequentemente a um nó «gestor» ou «supervisor» baseado em LLM para decidir qual agente especializado deve executar o passo seguinte.

Como os nós gestores generativos geram tokens sequencialmente, a delegação pelo supervisor pode introduzir uma sobrecarga de orquestração substancial por salto. Substituir o supervisor generativo por um modelo de decisão não autorregressivo realiza a delegação numa única passagem direta, proporcionando encaminhamento determinístico entre os agentes.

O Laya disponibiliza integrações próprias para frameworks de orquestração populares:

  • CrewAI: Usa o LayaCrewRouter para encaminhamento hierárquico de tarefas entre vários agentes e guardrails.
  • LlamaIndex: Usa o LayaSingleSelector para motores de consulta de router de passagem direta única.
  • LangChain / LangGraph: Usa laya.integrations.langchain para despacho de arestas condicionais.

Arquitetura

graph TD
    A["<b>Task Input / Workflow State</b>"] --> B["<b>Laya Orchestrator</b><br/>• assignee: researcher | coder | writer<br/>• priority: score (1–5 urgency)"]
    B -->|Research Assignment| C["<b>Researcher Agent</b><br/>Literature search & fact-checking"]
    B -->|Code Assignment| D["<b>Coder Agent</b><br/>Implementation, bug-fixing & tests"]
    B -->|Writing Assignment| E["<b>Copywriter Agent</b><br/>Drafting, copy editing & summary"]

Implementação (exemplo CrewAI / LangGraph)

from laya import Router

router = Router()

DELEGATION_QUESTIONS = {
    "assignee": {
        "type": "choice",
        "instructions": "Assign this task to the most qualified specialist.",
        "criteria": {
            "researcher": "Needs literature search, fact checking, or data collection.",
            "coder": "Needs bug fixing, script writing, or unit test generation.",
            "writer": "Needs article drafting, copy editing, or summary composition.",
        },
    },
    "priority": {
        "type": "score",
        "instructions": "Urgency score from 1 (low) to 5 (critical)",
        "criteria": ["1", "2", "3", "4", "5"],
    },
}

def supervisor_node(state):
    task_description = state["task"]
    decision = router.predict(task_description, DELEGATION_QUESTIONS)
    answers = decision["answers"]

    return {
        "next_agent": answers["assignee"]["choice"],
        "urgency": answers["priority"]["score"],
    }

6. Triagem de tickets e suporte de alto throughput

As organizações de suporte ao cliente e os centros de operações processam diariamente grandes volumes de tickets, e-mails e alertas. Utilizar APIs de LLM generativo alojadas para triagem categórica pode introduzir:

  1. Limites de taxa de rede: Limitação durante picos repentinos de volume.
  2. Amplificação de custos: Custos variáveis de tokens apenas para classificação discreta.
  3. Deriva de esquema: Modelos generativos que devolvem JSON malformado ou blocos de código markdown.

Os pipelines de processamento em lote podem avaliar fluxos de tickets em passagens diretas partilhadas usando predict_batch ou decide_batch(), emitindo dados estritamente tipados que cumprem diretamente os esquemas da aplicação.

Arquitetura

graph TD
    A["<b>Incoming Ticket Stream</b><br/>Message Broker / Webhook"] --> B["<b>Laya Batch Worker</b><br/>decide_batch()<br/>• department: billing | tech | sales | general<br/>• severity: 1..5<br/>• escalate_to_human: true | false"]
    B -->|Department: billing| C["<b>Billing & Invoicing Queue</b>"]
    B -->|Severity &ge; 4 or Human Escalation| D["<b>Tier-3 Escalation Queue</b><br/>Human On-Call Pager"]
    B -->|Low Severity & Standard Inquiry| E["<b>Automated Resolution Pipeline</b>"]

Implementação

from laya.structured import decide_batch
from laya import Agent

agent = Agent("convaiinnovations/laya")

# Strict typed schema
TICKET_SCHEMA = {
    "type": "object",
    "properties": {
        "department": {
            "type": "string",
            "enum": ["billing", "technical_support", "sales", "general"],
            "description": "Primary support category",
        },
        "severity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5,
            "description": "Severity level from 1 (minor) to 5 (outage)",
        },
        "escalate_to_human": {
            "type": "boolean",
            "description": "True if customer is angry, threatening churn, or reporting a legal issue",
        },
    },
}

def process_ticket_batch(tickets: list[str]):
    # Returns typed dictionaries conforming exactly to TICKET_SCHEMA
    results = decide_batch(agent, tickets, TICKET_SCHEMA)
    for ticket_text, structured in zip(tickets, results):
        enqueue_ticket(
            department=structured["department"],
            severity=structured["severity"],
            human_required=structured["escalate_to_human"],
            raw_text=ticket_text,
        )

Lista de verificação para implantação em produção

Antes de lançar qualquer um dos padrões acima em produção, verifica:

  1. Dimensionamento de hardware: Garante memória de host suficiente para os pesos residentes do modelo. Em CPU, configura os pools de threads de forma adequada (torch.set_num_threads).
  2. Limiares de confiança: Define min_confidence (por exemplo, 0.80–0.90) nas portas críticas para que o sistema recorra a uma alternativa segura quando as consultas forem ambíguas.
  3. Encaminhamento multilingue: Usa Router() em vez de um Agent() estático quando o tráfego de utilizadores incluir entradas mistas ou não inglesas.
  4. Implantação por etapas: Segue o Guia de adoção por etapas para observar o tráfego de produção em modo sombra antes de tornar as decisões autoritativas.