Дизайн TypeScript SDK

laya-client — это HTTP-клиент без зависимостей для самостоятельно размещённого сервера laya-serve. Он использует конечную точку POST /v1/systemone и не добавляет продакшен-кода на Python или серверных зависимостей. Пакет npm начинается с версии 0.1.0, независимо от выпусков Python.

Границы

Компонент	Ответственность
`sdk/typescript`	Типы вопросов/ответов, пресеты, валидация, нативный fetch, ошибки и отмена
`laya/serve.py`	Существующая конечная точка HTTP, аутентификация Bearer, проверка работоспособности и лимиты запросов
`laya/router.py`	Выбор чекпойнта, загрузка и маршрутизация инференса
`laya/agent.py`	Токенизация, инференс на PyTorch и форматирование калиброванных ответов
`laya/presets.py`	Источник для пяти сгенерированных пресетов вопросов TypeScript

flowchart LR
    A[JavaScript or TypeScript application] --> B[laya-client]
    B -->|POST /v1/systemone| C[Existing Laya server]
    C --> E[Router and local checkpoint]

SDK экспортирует predict и проверку health, специфичную для Laya. Он поставляется в виде ESM, CommonJS и деклараций, сохраняя выведенные идентификаторы вопросов и метки choice. Используйте laya-client, когда приложение на JavaScript или TypeScript общается по HTTP с самостоятельно размещённым Python-сервером laya-serve. Используйте laya-ts, когда инференс должен выполняться напрямую внутри JavaScript через его локальную среду выполнения ONNX, без Python-сервера.

Общий контракт

Запросы содержат state и questions. Если model не задан в конфигурации и не передан для предсказания, laya-client опускает его, позволяя laya-serve автоматически выбрать локальный чекпойнт. model на уровне клиента или отдельного вызова может выбрать локальный чекпойнт, как и остальные управляющие элементы на каждый запрос из таблицы ниже. Массивы меток choice нормализуются к словарям с описаниями null перед передачей.

Ответы сохраняют model, answers и usage токенов. Поля routing у Laya и action у ответа — необязательные расширения; уверенность Noul тоже необязательна. Уверенность Choice и Score, распределения и легенды Score остаются обязательными. Каждый ответ несёт answer_confidence — массу max(p) на сообщаемом ответе, которая для всех трёх типов вопросов одна и та же величина. Вызов, которому передали min_confidence, сообщает abstention и abstention_threshold на каждом своём ответе и low_confidence: true на тех, что ниже порога; если порог не задан, ни один из этих трёх ключей не отправляется, и это отсутствие и есть отчёт. Необязательные расширения проверяются, когда присутствуют.

/v1/systemone — единственная конечная точка, которую вызывает клиент, и у неё нет отдельного метода маршрутизации: laya-client предоставляет predict и health и ничего больше, а интеграционный тест на живом сервере утверждает, что сервер отвечает 404 на /v1/route. Управляющие элементы, которые эта конечная точка действительно учитывает, действуют на каждый запрос, и каждый отправляется только тогда, когда вызывающий код передал опцию – отсутствующая опция оставляет в силе собственные настройки Router(...) развёртывания, вместо того чтобы переопределять их клиентским значением по умолчанию:

опция	поле запроса
`model`	`model`
`task`	`task`
`lang`	`lang`
`langGuess`	`lang_guess`
`maxLen`	`max_len`
`headMaxLen`	`head_max_len`
`minConfidence`	`min_confidence`

Опция, которая не может ничего означать, отклоняется локально, до отправки запроса: пустой task, бюджет, не являющийся положительным целым числом, порог вне [0, 1], или карта порогов, которая пуста или содержит значение вне [0, 1]. Ничто не игнорируется молча. Публичный /health у Laya возвращает status, loaded и device. Предсказание никогда не проверяет работоспособность заранее.

Строки с подробностями FastAPI и массивы валидации сохраняются как сообщения/детали LayaAPIError. Структурированные конверты ошибок от совместимых бэкендов также принимаются. У запросов есть настраиваемые сроки и отмена со стороны вызывающего кода, и они никогда не повторяются автоматически.

Проверка и выпуск

Юнит-тесты охватывают построение запросов, все формы ответов, расширения Laya, ошибки FastAPI, валидацию JSON, сроки и отмену, и привязывают таблицу управляющих элементов этой страницы к полям, которые клиент действительно кладёт в провод. Проверки типов охватывают необязательные метаданные, выведенные типы ответов и потребителей ESM/CommonJS. Интеграционный тест на живом сервере запускает неизменённое приложение laya.serve с крошечным офлайн-чекпойнтом, сравнивает предсказания SDK с прямым инференсом Python и проверяет маршрутизацию, пресеты, аутентификацию и лимиты запросов. CI запускает проверки SDK на Node.js 22 и 24.

Крошечные случайные веса проверяют передачу и числовую согласованность, а не качество или производительность предобученной модели.

См. руководство по SDK по настройке, примерам и публикации в npm. Пакет будет опубликован под именем laya-client. Рабочие процессы выпуска Python не изменились.