Diseño del SDK de TypeScript

laya-client es un cliente HTTP sin dependencias para un servidor laya-serve autoalojado. Usa el endpoint POST /v1/systemone y no añade código Python de producción ni dependencias de servidor. El paquete npm empieza en la versión 0.1.0, con independencia de las publicaciones de Python.

Fronteras

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

El SDK exporta predict y una sonda health exclusiva de Laya. Se distribuye como ESM, CommonJS y declaraciones, conservando los ids de pregunta y las etiquetas de choice inferidos. Usa laya-client cuando una aplicación JavaScript o TypeScript hable por HTTP con un laya-serve de Python autoalojado. Usa laya-ts cuando la inferencia deba ejecutarse directamente dentro de JavaScript a través de su runtime ONNX local, sin un servidor Python.

Contrato compartido

Las solicitudes contienen state y questions. A menos que se configure o se aporte para una predicción, laya-client omite model, dejando que laya-serve seleccione un checkpoint local automáticamente. Un model a nivel de cliente o por llamada puede seleccionar un checkpoint local, igual que los demás controles por solicitud de la tabla de abajo. Los arrays de etiquetas de choice se normalizan a mapas con descripciones nulas antes del transporte.

Las respuestas conservan model, answers y el usage de tokens. Los campos routing de Laya y action de la respuesta son extensiones opcionales; la confianza de Noul también es opcional. La confianza de Choice y Score, las distribuciones y las leyendas de Score siguen siendo obligatorias. Cada respuesta lleva answer_confidence, la masa max(p) sobre la respuesta informada, que es la misma cantidad en los tres tipos de pregunta. Una llamada a la que se pasó min_confidence informa abstention y abstention_threshold en cada una de sus respuestas y low_confidence: true en las que están por debajo del umbral; sin umbral definido, no se envía ninguna de esas tres claves, y esa ausencia es el informe. Las extensiones opcionales se validan cuando están presentes.

/v1/systemone es el único endpoint que llama el cliente, y no tiene un método de enrutamiento independiente: laya-client expone predict y health y nada más, y el test de integración en vivo comprueba que el servidor responde 404 a /v1/route. Los controles que el endpoint sí respeta son por solicitud, y cada uno se envía solo cuando el llamador aportó la opción – una opción ausente deja a cargo la propia configuración de Router(...) del despliegue en lugar de sobrescribirla con un valor predeterminado del cliente:

Una opción que no puede significar nada se rechaza localmente, antes de que salga la solicitud: un task en blanco, un presupuesto que no es un entero positivo, un umbral fuera de [0, 1], o un mapa de umbrales vacío o con un valor fuera de [0, 1]. Nada se ignora en silencio. El /health público de Laya devuelve status, loaded y device. La predicción nunca sondea la salud primero.

Las cadenas de detalle de FastAPI y los arrays de validación se conservan como mensajes/detalles de LayaAPIError. También se aceptan sobres de error estructurados de backends compatibles. Las solicitudes tienen plazos límite configurables y cancelación por parte del llamador, y nunca se reintentan automáticamente.

Verificación y publicación

Los tests unitarios cubren la construcción de solicitudes, todas las formas de respuesta, las extensiones de Laya, los errores de FastAPI, la validación de JSON, los plazos límite y la cancelación, y atan la tabla de controles de esta página a los campos que el cliente realmente pone en el cable. Las comprobaciones de tipos cubren metadatos opcionales, tipos de respuesta inferidos y consumidores de ESM/CommonJS. El test de integración en vivo arranca la aplicación laya.serve sin cambios con un checkpoint offline diminuto, compara las predicciones del SDK con la inferencia directa de Python, y ejercita el enrutamiento, los presets, la autenticación y los límites de solicitud. CI ejecuta las comprobaciones del SDK en Node.js 22 y 24.

Unos pesos aleatorios diminutos verifican el transporte y la paridad numérica, no la calidad ni el rendimiento del modelo preentrenado.

Consulta la guía del SDK para la configuración, los ejemplos y la publicación en npm. El paquete se publicará bajo el nombre laya-client. Los flujos de trabajo de publicación de Python quedan sin cambios.