Routage

Router choisit un checkpoint pour chaque requête et charge son Agent quand la prédiction en a besoin. Le routeur par défaut envoie le texte anglais au checkpoint anglais et les autres langues prises en charge au checkpoint multilingue. Tu peux remplacer ce choix, fournir ton propre indice de langue, ou sélectionner explicitement le checkpoint typed-decisions.

Ce guide porte sur le choix du modèle et le cycle de vie. Pour les types de question acceptés par la prédiction, voir Décisions pilotées par schéma ; pour les callbacks de cycle de vie, voir Hooks de prédiction.

Démarrage rapide

from laya import Router

router = Router()

questions = {
    "department": {
        "type": "choice",
        "instructions": "Which department should handle this request?",
        "criteria": {
            "billing": "invoices, payments, refunds",
            "technical": "bugs, outages, system errors",
            "other": "everything else",
        },
    }
}

result = router.predict("We were billed twice. Please refund the duplicate charge.", questions)
print(result["answers"]["department"]["choice"])
print(result["routing"]["model"])

Créer Router() ne télécharge pas de checkpoints par défaut. predict() route la requête, puis charge le checkpoint choisi au premier usage. La première prédiction peut donc prendre plus de temps pendant le téléchargement des fichiers et l’initialisation du modèle ; les prédictions suivantes réutilisent l’agent chargé.

Comment un checkpoint est sélectionné

Router.route(state, questions, ...) renvoie un RouteDecision sans charger de checkpoint ni exécuter d’inférence. La décision contient le modèle choisi, une raison lisible par un humain, et des détails de détection de langue lorsque la détection intégrée a été utilisée.

Le routage examine les entrées dans cet ordre :

model= sélectionne un checkpoint directement.
task= sélectionne un checkpoint pour la tâche nommée.
Si auto_task_detection=True, une correspondance exacte avec l’un des ensembles d’ID de question typed-decisions connus sélectionne typed-decisions.
Une valeur lang= reconnue sélectionne l’anglais ou le multilingue.
Un lang_guess= par appel, ou le lang_guess configuré du routeur, est consulté.
Une analyse intégrée de l’écriture et de la langue sélectionne un checkpoint. S’il n’y a pas de signal de langue fiable, le routeur utilise son default configuré (l’anglais par défaut).

La première règle qui correspond l’emporte. Par exemple, model="multilingual" l’emporte sur lang="en". Les noms de modèle invalides lèvent ValueError au lieu de retomber sur la détection.

decision = router.route(
    "La aplicación se cierra cada vez que abro la configuración.",
    questions,
)
print(decision.model)   # multilingual
print(decision.reason)  # why that checkpoint was selected

RouteDecision est compatible avec dict, donc ses champs sont aussi accessibles avec des clés comme decision["model"] et decision["reason"]. Router.predict() inclut la même décision sous la clé "routing" du résultat.

Remplacer le routage par langue

Utilise lang= quand l’application connaît déjà la langue de la requête. Les étiquettes de langue comme "en", "en-US" et "en_US.UTF-8" sont acceptées. L’anglais route vers english ; les autres codes de langue reconnus routent vers multilingual.

result = router.predict(state, questions, lang="de")
assert result["routing"]["model"] == "multilingual"

Si l’application a son propre détecteur de langue, passe son résultat comme code de langue avec lang_guess=. Un callable reçoit l’état et peut renvoyer un code ou None pour s’abstenir :

def detect_request_language(state):
    # Replace this with the application's detector.
    return "en" if "invoice" in str(state).lower() else None

router = Router(lang_guess=detect_request_language)

Un indice qui s’abstient ne force pas de checkpoint ; le routage passe à la règle suivante. Cela couvre None, une chaîne vide, et les codes qui ne nomment aucune langue (C, POSIX, C.UTF-8, und, zxx, mul), ce que renvoie un détecteur quand il n’a rien à dire, donc une abstention ne peut pas épingler silencieusement les requêtes sur le mauvais modèle.

Un indice non reconnu n’est pas une abstention. Toute autre valeur, y compris "xx", False et 0, est lue comme « non anglais » et route vers le checkpoint multilingue. Ainsi, un détecteur qui renvoie un code invalide plutôt que None choisit bel et bien un checkpoint, et si cela compte, associe son cas inconnu à None avant de le transmettre.

La détection intégrée est une heuristique légère d’écriture et de langue, pas un modèle d’identification de langue généraliste. Elle analyse les valeurs de chaîne dans les états de type text, dict et list ; les clés de dictionnaire sont ignorées car ce sont souvent des noms de champ en anglais. Un texte court ou ambigu peut utiliser le checkpoint par défaut. Pour des charges de travail connues, une langue explicite ou un indice fourni par l’application est plus prévisible.

Sélectionner typed-decisions

Le checkpoint typed-decisions n’est pas sélectionné automatiquement par défaut. Sélectionne-le explicitement :

result = router.predict(state, questions, model="typed-decisions")
# `task="typed_decisions"` is also accepted.

Sinon, définis auto_task_detection=True. Le routeur vérifie alors si les ID de question correspondent exactement à l’un de ses flux de travail typed-decision connus. Il ne déduit pas la tâche de la formulation de la question, et ajouter des ID de question sans rapport empêche une correspondance exacte.

router = Router(auto_task_detection=True)

Inspecter le routage sans charger de modèles

Utilise route() pour inspecter une seule décision ou route_batch() pour inspecter une séquence. Aucune des deux méthodes ne charge de checkpoints, donc les deux sont utiles pour déboguer les règles de routage avant d’exécuter l’inférence.

requests = [
    {"state": "Please refund the duplicate charge.", "questions": questions},
    {"state": "Necesito ayuda con mi factura.", "questions": questions},
]

decisions = router.route_batch(requests)
for decision in decisions:
    print(decision.model, decision.reason)

Chaque élément de route_batch() a besoin de state et questions ; les remplacements de routage facultatifs (model, task, lang et lang_guess) se précisent par élément. Les décisions restent dans l’ordre d’entrée.

Chargement et mémoire

Par défaut, le routeur charge un checkpoint la première fois qu’il est nécessaire et garde au plus deux agents résidents. Le routage automatique par langue n’a normalement besoin que des checkpoints anglais et multilingue. Si les requêtes peuvent aussi sélectionner typed-decisions, un petit max_loaded peut évincer un autre agent et le faire recharger la prochaine fois qu’il est nécessaire.

# Load only the checkpoints this process serves, before accepting requests.
router = Router()
router.preload(["english", "multilingual"])

print(router.loaded)  # currently resident checkpoint names
router.unload("multilingual")

Router(preload=True) précharge tous les checkpoints configurés. Le préchargement relève la limite de modèles résidents pour correspondre à l’ensemble demandé. Pour contrôler une charge de travail à trois checkpoints sans préchargement, définis max_loaded=3. Utilise unload() pour libérer un agent ou router.unload() pour les libérer tous. Un routeur utilisé comme gestionnaire de contexte décharge ses agents à la sortie du bloc :

with Router(preload=True) as router:
    result = router.predict(state, questions)

Tu peux aussi passer device="cpu", device="cuda" ou un autre appareil PyTorch pris en charge lors de la construction du routeur. La disponibilité et la mémoire déterminent quels appareils peuvent exécuter un modèle donné.

Lots mixtes

predict_batch() accepte des requêtes avec des états, des modèles, des langues et des schémas de question différents. Le routeur prend d’abord une décision pour chaque requête, regroupe le travail par checkpoint et schéma de question compatible, puis restaure les résultats dans l’ordre d’entrée d’origine.

requests = [
    {"state": "Please refund the duplicate charge.", "questions": questions},
    {"state": "Mi cuenta fue cobrada dos veces.", "questions": questions},
    {"state": "A third request", "questions": questions, "model": "typed-decisions"},
]

results = router.predict_batch(requests, batch_size=8)

Chaque requête nécessite state et questions ; elle peut aussi inclure model, task, lang ou lang_guess. Les requêtes qui partagent un checkpoint et un schéma de question peuvent partager une passe avant par lot de l’Agent. Les schémas ou checkpoints différents sont traités dans des groupes séparés. batch_size limite le nombre d’états passés ensemble à l’Agent ; les résultats correspondent toujours à l’ordre des requêtes.

Choisir un point d’entrée

Utilise route() ou route_batch() quand tu dois inspecter des décisions sans charger de modèles.
Utilise predict() pour une seule requête et predict_batch() pour plusieurs requêtes éventuellement hétérogènes.
Utilise Agent directement quand l’application a déjà choisi et chargé un checkpoint et n’a pas besoin de routage automatique.

Voir la référence de l’API de Router pour les détails du constructeur et des méthodes.