Командная строка и сервер MCP

У Laya есть два локальных интерфейса, чтобы опробовать один и тот же движок структурированных решений:

Выбирайте CLI, когда результат читает человек. Выбирайте MCP, когда другому процессу нужен стабильный интерфейс инструментов. Оба используют Router из Laya, чтобы выбрать чекпойнт и вернуть типизированные решения choice, score и noul; ни один из них не является открытым интерфейсом для ответов на вопросы или генерации текста.

Примеры решения о маршрутизации и типизированных вопросов см. в разделе Краткое руководство по Route Mode файла README. Об уверенности и встроенных рабочих процессах см. в разделах gating по уверенности и пресеты рабочих процессов файла README.

1. Командная строка

Установка пакета устанавливает точку входа laya. Запустите laya --help, чтобы увидеть полный список опций.

python -m pip install laya
laya --help

CLI для оценки

Пакет также устанавливает laya-evals. Основной CLI предоставляет те же команды оценки через laya eval:

laya eval --help

См. руководство Harness оценки о наборах данных, метриках и порогах baseline.

Маршрутизация без загрузки чекпойнта

Если передать текст без флага предсказания, CLI вызывает Router.route:

laya "I was charged twice, please refund it"

Вывод называет выбранный чекпойнт, объясняет, почему он выбран, и показывает информацию об определённом языке, когда она доступна. Одна лишь маршрутизация не скачивает и не собирает чекпойнт, поэтому это быстрая офлайн-проверка решения о маршрутизации.

Используйте --json, когда решение должен потребить другой локальный скрипт:

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

Запуск предсказания

--predict выполняет полное типизированное предсказание и загружает выбранный при маршрутизации чекпойнт при первом использовании. Первой загрузке нужен доступ к Hugging Face Hub; последующие запуски используют локальный кэш.

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

--json выводит полный результат в виде JSON. Без него CLI выводит каждый ответ вместе с его вероятностью choice, score или значением noul, а также решение о маршрутизации.

Основные параметры:

• --model english|multilingual|typed-decisions фиксирует чекпойнт вместо автоматической маршрутизации.
• --lang en|de|... задаёт явный код языка вместо автоматического определения.
• --lang-guess en|de|... задаёт мягкую подсказку, которую маршрутизация читает после --lang и до собственного определителя; подсказка, которая ни к чему не приводит, пропускается, так что она подталкивает чекпойнт, не вынуждая его.
• --task NAME принудительно включает рабочий процесс typed-decisions вместо его определения.
• --device cpu|cuda|... передаёт выбор устройства в Router.
• --json выдаёт машиночитаемый вывод.

Использование встроенного пресета

Пресет предоставляет готовый набор вопросов и подразумевает предсказание, поэтому --predict не нужен:

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

Пресеты CLI — это email, guard, moderation, router и triage. CLI помещает текст в поле state, которого ожидает выбранный пресет; --predict использует поле request из набора вопросов router. Пресеты полезны для быстрой локальной проверки, но их вопросы — всё равно решения предметной области: изучите пресет и проверьте его на своих данных, прежде чем использовать как политику приложения.

Интерактивное исследование

Без текстового аргумента CLI открывает небольшое приглашение:

laya
# laya> Classify this request
# laya> quit

Нажмите Enter, чтобы выполнить каждый запрос. Пустая строка, quit, exit или Ctrl-D завершают сессию. Интерактивный цикл переиспользует один Router, поэтому это удобный способ сравнить несколько вариантов ввода без написания скрипта.

Сбои видны

CLI обрабатывает недопустимые значения и типичные сбои зависимостей, загрузок и среды выполнения на границе приложения. Он выводит диагностику в stderr и возвращает код выхода 2, вместо того чтобы показывать необработанный traceback. Если загрузка чекпойнта при первом использовании не удалась, проверьте установку зависимостей, доступ к Hub и выбранное устройство, прежде чем повторять.

2. Встроенный MCP-сервер stdio

MCP-сервер — это необязательное дополнение. Базовый пакет не устанавливает зависимость mcp:

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

Сервер общается по MCP через stdio, а не HTTP. Настройте клиент с помощью консольного скрипта:

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

Если конфигурация клиента поддерживает исполняемый файл Python и аргументы, используйте python -m laya.mcp.server как эквивалентную форму запуска. Процессом сервера владеет клиент; Laya не открывает сетевой порт.

Доступные инструменты

Три инструмента для пакетной обработки и работы со схемой существуют потому, что те же операции доступны в SDK и laya-serve: обработка множества запросов или обслуживание вызывающего кода, который уже знает форму ответа, не требует перехода на Python. Подробнее о форме, управляемой схемой, см. в разделе Решения на основе схемы.

Общий ограничитель (guardrail) требует не отправлять choice-вопросы с более чем 20 вариантами без шортлиста. laya_shortlist оставляет k наиболее вероятных меток перед прямым проходом; значение по умолчанию — k=20. Он использует эмбеддинги с усреднением (mean-pooling) из собственного энкодера отвечающего чекпойнта, поэтому не скачивает вторую модель, и возвращает оставленные метки, косинусные оценки, k и число вариантов для каждого вопроса из шортлиста.

state должен быть непустым JSON-объектом. questions должен быть непустым объектом, значения которого используют типизированную схему вопросов Laya. laya_preset принимает те же пять пресетов, что и CLI: email, guard, moderation, triage и рабочий процесс router, каноническое имя которого на этой поверхности — model_router. router принимается как псевдоним и называет тот же пресет, поэтому написание из CLI работает и здесь; канонический ключ — тот, что возвращается в результате. Если state — ровно одна строка, laya_preset помещает её в поле, которое называют вопросы этого пресета, — то же размещение, что делает CLI, — так что вызывающему не нужно угадывать ключ. Всё, что богаче одной строки, — это собственная форма вызывающего кода, и она передаётся без изменений.

Каждый инструмент одиночного запроса принимает те же управляющие элементы маршрутизации на каждый вызов, что и пакетные запросы. Помимо model, запрос может задать task (назвать чекпойнт по работе), lang (принудительно задать код языка) и lang_guess (мягкую языковую подсказку, которая находится ниже lang и выше встроенного определителя, так что вероятный, но неопределённый код может подтолкнуть выбор чекпойнта, не вынуждая его так, как это делает lang). lang_guess участвует только в маршрутизации, поэтому, как и task, он отвергается при вызове, который закрепляет model – закреплённому чекпойнту нечего маршрутизировать. laya_predict и laya_shortlist также принимают max_len/head_max_len для бюджета токенов ответа и min_confidence для гейта воздержания.

Вызов предсказания имеет ту же форму, что и типизированный вызов 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?"
    }
  }
}

Ответ инструмента — это JSON, содержащий типизированные answers, решение routing и информацию о времени. Не считайте ответ с высокой уверенностью разрешением выполнять внешнее действие; приложение или агент по-прежнему отвечает за политику, проверку и побочные эффекты.

Запуск и окружение

MCP-сервер держит постоянный Router и сериализует первое создание. По умолчанию он предзагружает english и multilingual; typed-decisions остаётся ленивым. Сбой предзагрузки сообщается при запуске и повторяется при следующем вызове инструмента, поэтому проверьте laya_status, прежде чем считать сервер готовым.

Один сервер модели на несколько сессий MCP

Запустите один локальный HTTP-сервер и направьте на него окружение каждого MCP-клиента:

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

Установите laya[serve] там, где работает HTTP-сервер. MCP по-прежнему использует stdio с редактором; его инструменты предсказаний используют HTTP, чтобы достичь вашего сервера. laya_predict, laya_predict_batch, laya_decide и laya_preset используют исходные состояние, инструкции и описания вариантов сервера. Неоднородные пакеты отправляют один запрос /v1/systemone на элемент, сохраняя порядок ввода; batch_size и sort_by_length не меняют выполнение сервера. laya_status сообщает о /health сервера; laya_route и laya_route_batch остаются локальными и не нуждаются ни в модели, ни в HTTP-запросе. Процесс MCP не импортирует torch и не загружает ни один чекпойнт, в том числе когда заданы LAYA_THREADS или LAYA_PRELOAD.

Задайте один и тот же LAYA_API_KEY в обоих процессах, когда сервер требует bearer-токен. Держите LAYA_DEFAULT_MODEL и LAYA_AUTO_TASK согласованными, чтобы локальные предпросмотры маршрутизации совпадали с фактической маршрутизацией сервера. Настройки устройства и предзагрузки принадлежат HTTP-серверу. Первый вызов после простоя при выгрузке ждёт холодной загрузки; увеличьте LAYA_REMOTE_TIMEOUT, если это занимает больше 300 секунд. laya_shortlist и переопределения хуков предсказаний возвращают unsupported_remote, так как их код нужен процессу модели. HTTP-ошибки сохраняют текст подробностей сервера как ошибки инструмента MCP. Если LAYA_BASE_URL не задан, MCP-сервер продолжает загружать чекпойнты в своём собственном процессе.

Штатный лаунчер laya-mcp-server создаёт свой Router без установки hooks. Устанавливайте хуки предсказаний в процессе, который выполняет инференс: в процессе MCP в локальном режиме или в HTTP-сервере в режиме общего сервера. Собственный лаунчер может использовать laya.hooks.set_default_hooks до построения своего Router. Переменные окружения выше настраивают жизненный цикл модели, а не регистрацию hooks. Клиент по-прежнему решает, когда вызывать инструмент и что делать с возвращённым решением.

3. Общие границы и связанные руководства

CLI и MCP-сервер — это интерфейсы к одному и тому же движку типизированных решений:

• Используйте choice для конечного набора меток, score для упорядоченной рубрики, а noul для вероятности истинности.
• Проверяйте пороги и пресеты на репрезентативных данных; универсального порога внедрения не существует.
• Держите необратимые или дорогостоящие действия за политикой проверки и отката приложения.
• MCP-сервер вызывает Router.predict, поэтому hooks срабатывают, когда их устанавливает собственный лаунчер. См. Hooks предсказания, жизненный цикл hooks и Трассировка для наблюдаемости и корреляции по run_id.

Это руководство охватывает локальный CLI и встроенный MCP-сервер stdio. Оно не описывает HTTP API, обёртки сообщества или переработку протокола MCP.