jevlaya
Français
Documentation

Modèles d’architecture et cas d’usage en production

Laya est un moteur de décision embarqué et non autorégressif, bâti sur une architecture transformer à passe avant unique (ModernBERT-large et mmBERT-base). Au lieu de générer des jetons de façon séquentielle comme un LLM (ce qui entraîne des coûts variables de génération de jetons, une surcharge de boucle de décodage et des schémas de sortie imprévisibles), Laya calcule des distributions de probabilité calibrées sur des questions discrètes en une seule passe.

Ce document sert de plan d’architecture pour les architectes système et les ingénieurs backend qui intègrent Laya dans des environnements de production.

Moteur de décision vs LLM vs récupération par embeddings

Choisir la bonne primitive dépend des contraintes de latence, de la topologie d’hébergement et du point de savoir si la tâche exige une génération libre ou une classification discrète :

Dimension Récupération par embeddings Moteur de décision Laya LLM autorégressif
Modèle de calcul Distance cosinus entre vecteurs Passe avant unique (tête masquée non autorégressive) Génération séquentielle jeton par jeton
Profil d’exécution Recherche dans un index des plus proches voisins Passe avant unique fixe (pas de boucle de décodage) Boucle de décodage itérative croissant avec la longueur de sortie
Hébergement et topologie En processus ou base de données vectorielle En processus (CPU/GPU local) ou démon HTTP auto-hébergé API hébergée à distance ou service GPU pour grands modèles
Attention de contexte Représentation vectorielle agrégée Attention croisée bidirectionnelle profonde sur toute l’entrée Attention séquentielle causale
Sortie structurée Fragments récupérés non structurés Distributions natives alignées sur le schéma (choice, score, noul) Texte libre nécessitant une réparation JSON ou un échantillonnage de schéma
Charge de travail principale Récupération large de candidats Classification discrète, gating de politiques et routage Synthèse ouverte, traduction et génération

1. Passerelle d’entrée intelligente

Dans les architectures en couches, une grande fraction des requêtes entrantes n’exige pas les capacités génératives d’un LLM autorégressif. Des requêtes telles que les FAQ standard, les interrogations déterministes sur l’état ou les décisions de routage catégorielles peuvent être évaluées localement.

Laya fait office de passerelle d’entrée intelligente : il classe l’intention et la complexité de la requête en une seule passe avant locale. Les requêtes déterministes sont résolues localement via des points de terminaison internes ou des réponses en cache, tandis que les tâches génératives complexes sont transmises à des LLM en amont.

Architecture

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"]

Implémentation

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. Routeur de tours de parole et d’interruption vocale à faible latence

Les agents vocaux conversationnels (WebRTC, téléphonie) opèrent sous de strictes contraintes de tours de parole : les délais à détecter quand un utilisateur parle ou interrompt créent des silences contre-naturels. Attendre qu’un modèle génératif complet produise son premier jeton introduit un retard évitable quand l’appelant ne fait que confirmer ou interrompre.

Laya peut être placé directement après la transcription parole-texte (STT) pour classer le flux conversationnel et l’intention de l’utilisateur en une seule passe avant : déclencher une bande-son de remplissage rapide ou interrompre immédiatement la lecture audio lorsqu’une interruption est détectée, tout en déléguant les demandes complexes au pipeline de synthèse complet.

Architecture

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"]

Implémentation

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. Sécurité pré-LLM et pare-feu de prompts

Protéger les systèmes contre les injections de prompts adverses, les jailbreaks et les fuites de données sensibles doit se faire avant que le prompt n’atteigne la fenêtre de contexte du LLM. Faire tourner un modèle génératif distinct uniquement pour juger si un prompt est sûr ajoute de la latence redondante et une surcharge opérationnelle.

Laya opère comme un pare-feu de sécurité en ligne et non autorégressif, évaluant les injections de prompts, les élévations de privilèges et les tâches hors périmètre en une seule passe avant, en amont du traitement.

Architecture

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"]

Implémentation

Les hooks de Laya sont duck-typés : tout objet implémentant les méthodes du cycle de vie de Hook (ou héritant de BaseHook dans laya.hooks) peut être attaché à un Agent ou un Router.

Sous la sémantique de levée de hook par défaut de Laya (hooks_raise=True) :

  • Lever une exception dans on_predict_start interrompt immédiatement l’exécution avant que la tokenisation ou l’inférence du modèle n’ait lieu.
  • L’exception se propage directement hors de system_one() / predict() jusqu’à l’appelant.
  • Les nettoyages du cycle de vie (on_error et on_predict_end) s’exécutent quand même, avec ctx.error défini sur l’exception levée, ce qui garantit que les journaux d’audit et la télémétrie enregistrent la requête bloquée.
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] Pour les workflows CrewAI, Laya fournit aussi LayaTaskGuard clé en main dans laya.integrations.crewai pour ce motif exact de porte de sécurité avant exécution.

4. Routeur RAG en périphérie isolée

Dans les environnements d’entreprise sécurisés (défense, santé, conformité financière, appareils en périphérie), les API externes sont indisponibles ou interdites. Les collections de documents sont souvent cloisonnées en domaines distincts (par exemple, essais cliniques, dossiers patients, rapports financiers, spécifications techniques).

Plutôt que d’interroger un unique index vectoriel monolithique avec des embeddings sans rapport, Laya agit comme un routeur de périphérie local qui dirige les requêtes des utilisateurs vers l’index vectoriel local spécifique ou la base de données SQLite avant la récupération.

Architecture

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")]

Implémentation

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. Délégation hiérarchique de tâches entre plusieurs agents

Les frameworks multi-agents emploient souvent un nœud « manager » ou « superviseur » basé sur un LLM pour décider quel agent spécialisé doit exécuter l’étape suivante.

Comme les nœuds gestionnaires génératifs génèrent des jetons de façon séquentielle, la délégation par un superviseur peut introduire une surcharge d’orchestration substantielle par saut. Remplacer le superviseur génératif par un modèle de décision non autorégressif réalise la délégation en une seule passe avant, ce qui offre un routage déterministe entre les agents.

Laya livre des intégrations de première partie pour les frameworks d’orchestration populaires :

  • CrewAI : Utilise LayaCrewRouter pour le routage hiérarchique de tâches entre plusieurs agents et les garde-fous.
  • LlamaIndex : Utilise LayaSingleSelector pour les moteurs de requête de routeur à passe avant unique.
  • LangChain / LangGraph : Utilise laya.integrations.langchain pour la répartition d’arêtes conditionnelles.

Architecture

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"]

Implémentation (exemple 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. Tri de tickets et de support à haut débit

Les organisations de support client et les centres d’opérations traitent quotidiennement de gros volumes de tickets, d’e-mails et d’alertes. Utiliser des API de LLM génératif hébergées pour le tri catégoriel peut introduire :

  1. Limites de débit réseau : Bridage lors de pics soudains de volume.
  2. Amplification des coûts : Coûts variables de jetons uniquement pour une classification discrète.
  3. Dérive de schéma : Modèles génératifs renvoyant du JSON malformé ou des blocs de code markdown.

Les pipelines de traitement par lots peuvent évaluer des flux de tickets sur des passes avant partagées avec predict_batch ou decide_batch(), et produire des données strictement typées conformes directement aux schémas de l’application.

Architecture

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>"]

Implémentation

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,
        )

Liste de vérification pour le déploiement en production

Avant de mettre en production l’un des motifs ci-dessus, vérifie :

  1. Dimensionnement matériel : Assure une mémoire hôte suffisante pour les poids résidents du modèle. Sur CPU, configure les pools de threads de manière appropriée (torch.set_num_threads).
  2. Seuils de confiance : Définis min_confidence (par exemple 0.80–0.90) sur les portes critiques pour que le système retombe en sécurité quand les requêtes sont ambiguës.
  3. Routage multilingue : Utilise Router() plutôt qu’un Agent() statique quand le trafic utilisateur comporte des entrées mixtes ou non anglaises.
  4. Déploiement progressif : Suis le Guide d’adoption par étapes pour observer le trafic de production en miroir avant que les décisions ne fassent autorité.