Kommandozeile und MCP-Server

Laya hat zwei lokale Schnittstellen, um dieselbe Engine für strukturierte Entscheidungen auszuprobieren:

Wähle die CLI, wenn du die Person bist, die das Ergebnis liest. Wähle MCP, wenn ein anderer Prozess eine stabile Tool-Schnittstelle braucht. Beide nutzen Layas Router, um einen Checkpoint auszuwählen und typisierte Entscheidungen choice, score und noul zurückzugeben; keine von beiden ist eine offene Schnittstelle zur Beantwortung von Fragen oder zur Textgenerierung.

Für die Routing-Entscheidung und Beispiele typisierter Fragen siehe den Route-Mode-Schnellstart des README. Für Konfidenz und eingebaute Workflows siehe das Konfidenz-Gating und die Workflow-Presets des README.

1. Kommandozeile

Das Installieren des Pakets installiert den Einstiegspunkt laya. Führe laya --help für die vollständige Optionsliste aus.

python -m pip install laya
laya --help

Evaluierungs-CLI

Das Paket installiert auch laya-evals. Die Haupt-CLI stellt dieselben Evaluierungsbefehle über laya eval bereit:

laya eval --help

Siehe die Anleitung Evaluierungs-Harness für Datensätze, Metriken und Baseline-Gates.

Routen ohne einen Checkpoint zu laden

Mit Text und ohne Vorhersage-Flag ruft die CLI Router.route auf:

laya "I was charged twice, please refund it"

Die Ausgabe benennt den ausgewählten Checkpoint, erklärt, warum er ausgewählt wurde, und zeigt erkannte Sprachinformationen, wenn verfügbar. Das Routing allein lädt oder baut keinen Checkpoint, ist also eine schnelle Offline-Prüfung der Routing-Entscheidung.

Nutze --json, wenn ein anderes lokales Skript die Entscheidung konsumieren soll:

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

Eine Vorhersage ausführen

--predict führt die vollständige typisierte Vorhersage aus und lädt den gerouteten Checkpoint beim ersten Gebrauch. Der erste Ladevorgang braucht Zugriff auf den Hugging Face Hub; spätere Läufe nutzen den lokalen Cache.

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

--json gibt das vollständige Ergebnis als JSON aus. Ohne es gibt die CLI jede Antwort zusammen mit ihrer choice-Wahrscheinlichkeit, ihrem score oder ihrem noul-Wert aus, dazu die Routing-Entscheidung.

Die wichtigsten Steuerungen sind:

• --model english|multilingual|typed-decisions fixiert einen Checkpoint, statt automatisch zu routen.
• --lang en|de|... liefert einen expliziten Sprachcode statt automatischer Erkennung.
• --lang-guess en|de|... liefert einen weichen Hinweis, den das Routing nach --lang und vor seinem eigenen Detektor liest; ein Hinweis, der zu nichts aufgelöst wird, fällt durch, sodass er den Checkpoint anstößt, ohne ihn zu erzwingen.
• --task NAME erzwingt den Workflow typed-decisions, statt ihn zu erkennen.
• --device cpu|cuda|... übergibt eine Gerätewahl an den Router.
• --json gibt maschinenlesbare Ausgabe aus.

Ein eingebautes Preset verwenden

Ein Preset liefert ein fertiges Fragenset und impliziert eine Vorhersage, sodass --predict nicht nötig ist:

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

Die CLI-Presets sind email, guard, moderation, router und triage. Die CLI legt den Text unter das Zustandsfeld, das das ausgewählte Preset erwartet; --predict nutzt das Feld request des Router-Fragensets. Presets sind für eine schnelle lokale Prüfung nützlich, aber ihre Fragen sind weiterhin Domänenentscheidungen: Untersuche das Preset und validiere es an deinen eigenen Daten, bevor du es als Anwendungsrichtlinie verwendest.

Interaktiv erkunden

Ohne Textargument öffnet die CLI eine kleine Eingabeaufforderung:

laya
# laya> Classify this request
# laya> quit

Drücke Enter, um jede Anfrage auszuführen. Eine leere Zeile, quit, exit oder Ctrl-D beendet die Sitzung. Die interaktive Schleife verwendet einen einzigen Router wieder, ist also eine bequeme Möglichkeit, mehrere Eingaben zu vergleichen, ohne ein Skript zu schreiben.

Fehler sind sichtbar

Die CLI behandelt ungültige Werte und häufige Fehler bei Abhängigkeiten, Downloads und zur Laufzeit an der Anwendungsgrenze. Sie gibt eine Diagnose auf stderr aus und gibt den Exit-Code 2 zurück, statt einen unbehandelten Traceback zu zeigen. Wenn ein Checkpoint-Download beim ersten Gebrauch fehlschlägt, prüfe die Installation der Abhängigkeiten, den Hub-Zugriff und das ausgewählte Gerät, bevor du es erneut versuchst.

2. Eingebauter MCP-stdio-Server

Der MCP-Server ist ein optionales Extra. Das Kernpaket installiert die Abhängigkeit mcp nicht:

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

Der Server spricht MCP über stdio, nicht HTTP. Konfiguriere den Client mit dem Konsolenskript:

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

Wenn die Client-Konfiguration eine Python-ausführbare Datei und Argumente unterstützt, nutze python -m laya.mcp.server als äquivalente Startform. Der Client besitzt den Serverprozess; Laya öffnet keinen Netzwerkport.

Verfügbare Tools

Die drei Batch- und Schema-Tools existieren, weil dieselben Operationen im SDK und in laya-serve verfügbar sind: viele Anfragen zu bedienen oder einen Aufrufer, der die Antwortform bereits kennt, erfordert keinen Wechsel zu Python. Für die schemagesteuerte Form ausführlicher siehe Schemagesteuerte Entscheidungen.

Die gemeinsame Leitplanke besagt, keine choice-Fragen mit mehr als 20 Optionen ohne Vorauswahl zu senden. laya_shortlist behält die k wahrscheinlichsten Labels vor dem Forward-Pass; sein Standard ist k=20. Es nutzt mean-gepoolte Embeddings aus dem eigenen Encoder des antwortenden Checkpoints, sodass es kein zweites Modell herunterlädt, und gibt die behaltenen Labels, Kosinus-Scores, k und die Optionsanzahl für jede vorausgewählte Frage zurück.

state muss ein nicht leeres JSON-Objekt sein. questions muss ein nicht leeres Objekt sein, dessen Werte Layas Schema für typisierte Fragen nutzen. laya_preset akzeptiert dieselben fünf Presets wie die CLI: email, guard, moderation, triage und den Router-Workflow, dessen kanonischer Name auf dieser Oberfläche model_router ist. router wird als Alias akzeptiert und benennt dasselbe Preset, sodass die CLI-Schreibweise auch hier funktioniert; der kanonische Schlüssel ist der, der im Ergebnis zurückkommt. Bei einem Zustand von genau einem String legt laya_preset ihn unter das Feld, das die Fragen dieses Presets benennen, dieselbe Platzierung, die die CLI vornimmt, sodass ein Aufrufer den Schlüssel nicht erraten muss. Alles, was reicher als ein String ist, ist die eigene Form des Aufrufers und wird unverändert durchgereicht.

Jedes Einzelanfrage-Tool nimmt dieselben Routing-Steuerungen pro Aufruf entgegen wie die Batch-Anfragen. Neben model kann eine Anfrage task setzen (einen Checkpoint nach der Arbeit benennen), lang (einen Sprachcode erzwingen) und lang_guess (einen weichen Sprachhinweis, der unter lang und über dem eingebauten Detektor sitzt, sodass ein wahrscheinlicher, aber unsicherer Code beeinflussen kann, welcher Checkpoint gewählt wird, ohne ihn so zu erzwingen wie lang). lang_guess nimmt nur am Routing teil, also wird es wie task bei einem Aufruf abgelehnt, der model pinnt – ein gepinnter Checkpoint hat nichts mehr zu routen. laya_predict und laya_shortlist nehmen außerdem max_len/head_max_len für das antwortende Token-Budget und min_confidence für das Enthaltungs-Gate.

Ein Vorhersageaufruf hat dieselbe Form wie der typisierte Aufruf des 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?"
    }
  }
}

Die Tool-Antwort ist JSON mit den typisierten answers, der routing-Entscheidung und Zeitinformationen. Behandle eine Antwort mit hoher Konfidenz nicht als Erlaubnis, eine externe Aktion auszuführen; die Anwendung oder der Agent bleibt für Richtlinie, Überprüfung und Nebenwirkungen verantwortlich.

Start und Umgebung

Der MCP-Server hält einen residenten Router und serialisiert den erstmaligen Aufbau. Standardmäßig lädt er english und multilingual vor; typed-decisions bleibt lazy. Ein Vorladefehler wird beim Start gemeldet und beim nächsten Tool-Aufruf erneut versucht, also prüfe laya_status, bevor du annimmst, dass der Server bereit ist.

Einen Modellserver über MCP-Sitzungen hinweg teilen

Führe einen lokalen HTTP-Server aus und richte die Umgebung jedes MCP-Clients darauf aus:

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

Installiere laya[serve] dort, wo der HTTP-Server läuft. MCP verwendet mit dem Editor weiterhin stdio; seine Vorhersage-Tools erreichen deinen Server über HTTP. laya_predict, laya_predict_batch, laya_decide und laya_preset verwenden den ursprünglichen State, die Instructions und die Optionsbeschreibungen des Servers. Heterogene Batches senden eine /v1/systemone-Anfrage pro Element und bewahren die Eingabereihenfolge; batch_size und sort_by_length ändern die Ausführung des Servers nicht. laya_status meldet das /health des Servers; laya_route und laya_route_batch bleiben lokal und brauchen weder Modell noch HTTP-Anfrage. Der MCP-Prozess importiert kein torch und lädt keinen Checkpoint, auch wenn LAYA_THREADS oder LAYA_PRELOAD gesetzt ist.

Setze denselben LAYA_API_KEY in beiden Prozessen, wenn der Server ein Bearer-Token verlangt. Halte LAYA_DEFAULT_MODEL und LAYA_AUTO_TASK aufeinander abgestimmt, damit lokale Routing-Vorschauen zum tatsächlichen Routing des Servers passen. Geräte- und Vorladeeinstellungen gehören zum HTTP-Server. Der erste Aufruf nach einem Idle-Unload wartet auf einen Kaltstart; erhöhe LAYA_REMOTE_TIMEOUT, wenn das länger als 300 Sekunden dauert. laya_shortlist und Prediction-Hook-Überschreibungen geben unsupported_remote zurück, da ihr Code den Modellprozess braucht. HTTP-Fehler behalten den Detailtext des Servers als MCP-Tool-Fehler. Wenn LAYA_BASE_URL nicht gesetzt ist, lädt der MCP-Server weiterhin Checkpoints in seinem eigenen Prozess.

Der Standard-Launcher laya-mcp-server erstellt seinen Router, ohne Hooks zu installieren. Installiere Vorhersage-Hooks in dem Prozess, der die Inferenz ausführt: den MCP-Prozess im lokalen Modus oder den HTTP-Server im Shared-Server-Modus. Ein eigener Launcher kann laya.hooks.set_default_hooks verwenden, bevor er seinen Router aufbaut. Die obigen Umgebungsvariablen konfigurieren den Modell-Lebenszyklus, nicht die Hook-Registrierung. Der Client entscheidet weiterhin, wann er ein Tool aufruft und was er mit der zurückgegebenen Entscheidung tut.

3. Gemeinsame Grenzen und verwandte Anleitungen

Die CLI und der MCP-Server sind Schnittstellen zu derselben typisierten Entscheidungs-Engine:

• Nutze choice für eine endliche Labelmenge, score für eine geordnete Rubrik und noul für die Wahrscheinlichkeit von wahr.
• Validiere Schwellenwerte und Presets an repräsentativen Daten; es gibt keinen universellen Einführungsschwellenwert.
• Halte irreversible oder teure Aktionen hinter der Überprüfungs- und Fallback-Richtlinie der Anwendung.
• Der MCP-Server ruft Router.predict auf, sodass Hooks ausgelöst werden, wenn ein eigener Launcher sie installiert. Siehe Vorhersage-Hooks, Hook-Lebenszyklus und Tracing für Observability und run_id-Korrelation.

Diese Anleitung behandelt die lokale CLI und den eingebauten MCP-stdio-Server. Sie dokumentiert nicht die HTTP-API, Community-Wrapper oder ein Redesign des MCP-Protokolls.