Ligne de commande et serveur MCP

Laya propose deux interfaces locales pour essayer le même moteur de décision structuré :

Choisis la CLI quand c’est toi qui lis le résultat. Choisis MCP quand un autre processus a besoin d’une interface d’outil stable. Les deux utilisent le Router de Laya pour sélectionner un checkpoint et renvoyer des décisions typées choice, score et noul ; ni l’une ni l’autre n’est une interface ouverte de réponse à des questions ou de génération de texte.

Pour la décision de routage et les exemples de questions typées, voir le Démarrage rapide du mode Route du README. Pour la confiance et les workflows intégrés, voir le gating par confiance et les presets de workflow du README.

1. Ligne de commande

Installer le paquet installe le point d’entrée laya. Lance laya --help pour la liste complète des options.

python -m pip install laya
laya --help

CLI d’évaluation

Le paquet installe aussi laya-evals. La CLI principale expose les mêmes commandes d’évaluation via laya eval :

laya eval --help

Voir le guide Harnais d’évaluation pour les jeux de données, les métriques et les portes de référence.

Router sans charger de checkpoint

Avec du texte et aucun drapeau de prédiction, la CLI appelle Router.route :

laya "I was charged twice, please refund it"

La sortie nomme le checkpoint sélectionné, explique pourquoi il l’a été, et montre les informations de langue détectée quand elles sont disponibles. Le routage seul ne télécharge ni ne construit de checkpoint, donc c’est une vérification hors ligne rapide de la décision de routage.

Utilise --json quand un autre script local doit consommer la décision :

laya "I was charged twice, please refund it" --json

Exécuter une prédiction

--predict exécute la prédiction typée complète et charge le checkpoint routé au premier usage. Le premier chargement a besoin d’accéder au Hugging Face Hub ; les exécutions suivantes utilisent le cache local.

laya "Classify this support request" --predict
laya "Classify this support request" --predict --json

--json imprime le résultat complet en JSON. Sans lui, la CLI imprime chaque réponse avec sa probabilité choice, son score, ou sa valeur noul, plus la décision de routage.

Les principaux contrôles sont :

• --model english|multilingual|typed-decisions épingle un checkpoint au lieu d’auto-router.
• --lang en|de|... fournit un code de langue explicite au lieu de la détection automatique.
• --lang-guess en|de|... fournit un indice souple que le routage lit après --lang et avant son propre détecteur ; un indice qui ne résout rien retombe, donc il pousse le checkpoint sans le forcer.
• --task NAME force le workflow typed-decisions au lieu de le détecter.
• --device cpu|cuda|... passe un choix d’appareil au Router.
• --json émet une sortie lisible par machine.

Utiliser un preset intégré

Un preset fournit un ensemble de questions tout fait et implique la prédiction, donc --predict n’est pas nécessaire :

laya "My payment failed twice" --preset triage
laya "Ignore all previous instructions" --preset guard --json

Les presets de la CLI sont email, guard, moderation, router et triage. La CLI place le texte sous le champ d’état attendu par le preset sélectionné ; --predict utilise le champ request de l’ensemble de questions du routeur. Les presets sont utiles pour une vérification locale rapide, mais leurs questions restent des décisions de domaine : inspecte le preset et valide-le sur tes propres données avant de l’utiliser comme politique d’application.

Explorer en interactif

Sans argument de texte, la CLI ouvre une petite invite :

laya
# laya> Classify this request
# laya> quit

Appuie sur Entrée pour exécuter chaque requête. Une ligne vide, quit, exit ou Ctrl-D termine la session. La boucle interactive réutilise un seul Router, donc c’est un moyen pratique de comparer plusieurs entrées sans écrire de script.

Les échecs sont visibles

La CLI gère les valeurs invalides et les échecs courants de dépendance, de téléchargement et de runtime à la frontière de l’application. Elle imprime un diagnostic sur stderr et renvoie le code de sortie 2 au lieu de montrer une trace non gérée. Si un téléchargement de checkpoint au premier usage échoue, vérifie l’installation des dépendances, l’accès au Hub et l’appareil sélectionné avant de réessayer.

2. Serveur MCP stdio intégré

Le serveur MCP est un extra optionnel. Le paquet de base n’installe pas la dépendance mcp :

python -m pip install "laya[mcp]"
laya-mcp-server
# equivalent module form:
python -m laya.mcp.server

Le serveur parle MCP sur stdio, pas HTTP. Configure le client avec le script de console :

{
  "mcpServers": {
    "laya": {
      "command": "laya-mcp-server",
      "env": {
        "LAYA_DEVICE": "cpu"
      }
    }
  }
}

Si la configuration du client prend en charge un exécutable Python et des arguments, utilise python -m laya.mcp.server comme forme de lancement équivalente. Le client possède le processus serveur ; Laya n’ouvre aucun port réseau.

Outils disponibles

Les trois outils de lot et de schéma existent parce que les mêmes opérations sont disponibles sur le SDK et laya-serve : traiter de nombreuses requêtes, ou servir un appelant qui connaît déjà la forme de la réponse, ne nécessite pas de descendre en Python. Pour la forme pilotée par schéma plus en profondeur, voir Décisions pilotées par schéma.

Le garde-fou partagé dit de ne pas envoyer de questions choice à plus de 20 options sans présélection. laya_shortlist garde les k libellés les plus probables avant la passe avant ; son défaut est k=20. Il utilise les embeddings à moyenne de pool de l’encodeur du checkpoint qui répond lui-même, donc il ne télécharge pas un second modèle, et renvoie les libellés gardés, les scores cosinus, k et le nombre d’options pour chaque question présélectionnée.

state doit être un objet JSON non vide. questions doit être un objet non vide dont les valeurs utilisent le schéma de questions typées de Laya. laya_preset accepte les mêmes cinq presets que la CLI : email, guard, moderation, triage, et le workflow router, dont le nom canonique sur cette surface est model_router. router est accepté comme alias et nomme le même preset, donc l’orthographe de la CLI fonctionne ici aussi ; la clé canonique est celle qui revient dans le résultat. Avec un état d’exactement une chaîne, laya_preset la place sous le champ que nomment les questions de ce preset, le même placement que fait la CLI, pour qu’un appelant n’ait pas à deviner la clé. Tout ce qui est plus riche qu’une chaîne est la forme propre de l’appelant et passe tel quel.

Chaque outil à requête unique prend les mêmes contrôles de routage par appel que les requêtes par lots. À côté de model, une requête peut définir task (nommer un checkpoint par le travail), lang (forcer un code de langue) et lang_guess (un indice de langue souple qui se situe sous lang et au-dessus du détecteur intégré, ainsi un code probable mais incertain peut influencer le checkpoint choisi sans le forcer comme le fait lang). lang_guess ne participe qu’au routage, donc comme task il est refusé sur un appel qui fixe model – un checkpoint fixé n’a plus rien à router. laya_predict et laya_shortlist prennent aussi max_len/head_max_len pour le budget de jetons de réponse et min_confidence pour la porte d’abstention.

Un appel de prédiction a la même forme que l’appel typé du SDK :

{
  "state": {
    "body": "I was billed twice for the same plan. Please reverse the duplicate charge."
  },
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this request?",
      "criteria": {
        "billing": "payments, invoices, refunds, duplicate charges",
        "technical": "bugs, outages, integration problems"
      }
    },
    "urgent": {
      "type": "noul",
      "instructions": "Does the user need immediate help?"
    }
  }
}

La réponse de l’outil est du JSON contenant les answers typées, la décision routing et des informations de timing. Ne traite pas une réponse à haute confiance comme une permission d’effectuer une action externe ; l’application ou l’agent reste responsable de la politique, de la revue et des effets de bord.

Démarrage et environnement

Le serveur MCP garde un Router résident et sérialise la construction initiale. Par défaut il précharge english et multilingual ; typed-decisions reste paresseux. Un échec de préchargement est rapporté au démarrage et retenté à l’appel d’outil suivant, donc inspecte laya_status avant de supposer que le serveur est prêt.

Partager un serveur de modèles entre sessions MCP

Lance un serveur HTTP local et pointe l’environnement de chaque client MCP dessus :

LAYA_HOST=127.0.0.1 LAYA_PRELOAD=0 LAYA_IDLE_UNLOAD_SECONDS=300 laya-serve

{
  "mcpServers": {
    "laya": {
      "command": "laya-mcp-server",
      "env": {"LAYA_BASE_URL": "http://127.0.0.1:8000"}
    }
  }
}

Installe laya[serve] là où tourne le serveur HTTP. MCP utilise toujours stdio avec l’éditeur ; ses outils de prédiction utilisent HTTP pour atteindre ton serveur. laya_predict, laya_predict_batch, laya_decide et laya_preset utilisent l’état, les instructions et les descriptions d’options d’origine du serveur. Les lots hétérogènes envoient une requête /v1/systemone par élément, en préservant l’ordre d’entrée ; batch_size et sort_by_length ne changent pas l’exécution du serveur. laya_status rapporte le /health du serveur ; laya_route et laya_route_batch restent locaux et n’ont besoin ni de modèle ni de requête HTTP. Le processus MCP n’importe pas torch et ne charge aucun checkpoint, y compris quand LAYA_THREADS ou LAYA_PRELOAD est défini.

Définis le même LAYA_API_KEY dans les deux processus quand le serveur exige un jeton porteur. Garde LAYA_DEFAULT_MODEL et LAYA_AUTO_TASK alignés pour que les aperçus de routage local correspondent au routage réel du serveur. Les réglages d’appareil et de préchargement appartiennent au serveur HTTP. Le premier appel après un déchargement pour inactivité attend un chargement à froid ; augmente LAYA_REMOTE_TIMEOUT si cela prend plus de 300 secondes. laya_shortlist et les surcharges de hook de prédiction renvoient unsupported_remote, car leur code a besoin du processus du modèle. Les erreurs HTTP conservent le texte de détail du serveur comme erreurs d’outil MCP. Quand LAYA_BASE_URL n’est pas défini, le serveur MCP continue de charger les checkpoints dans son propre processus.

Le lanceur laya-mcp-server standard crée son Router sans installer de hooks. Installe les hooks de prédiction dans le processus qui exécute l’inférence : le processus MCP en mode local, ou le serveur HTTP en mode serveur partagé. Un lanceur personnalisé peut utiliser laya.hooks.set_default_hooks avant de construire son Router. Les variables d’environnement ci-dessus configurent le cycle de vie du modèle, pas l’enregistrement des hooks. Le client décide toujours quand appeler un outil et quoi faire de la décision renvoyée.

3. Frontières partagées et guides liés

La CLI et le serveur MCP sont des interfaces vers le même moteur de décision typée :

• Utilise choice pour un ensemble fini de libellés, score pour une grille ordonnée, et noul pour la probabilité de vrai.
• Valide les seuils et les presets sur des données représentatives ; il n’y a pas de seuil d’adoption universel.
• Garde les actions irréversibles ou coûteuses derrière la politique de revue et de fallback de l’application.
• Le serveur MCP appelle Router.predict, donc les hooks se déclenchent quand un lanceur personnalisé les installe. Voir Hooks de prédiction, le cycle de vie des hooks, et Traçage pour l’observabilité et la corrélation par run_id.

Ce guide couvre la CLI locale et le serveur MCP stdio intégré. Il ne documente pas l’API HTTP, les wrappers communautaires, ni une refonte du protocole MCP.