文档导航

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 checkpoint 选择、加载和推理路由
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 和一个 Laya 专用的 health 探针。它提供 ESM、CommonJS 和声明文件,并保留 推断出的 question ID 和 choice 标签。当 JavaScript 或 TypeScript 应用通过 HTTP 与自托管的 Python laya-serve 通信时,用 laya-client。当推理必须在 JavaScript 内部通过它本地的 ONNX 运行时直接跑、不需要 Python 服务器时,用 laya-ts。

共享契约

请求包含 state 和 questions。除非为一次预测另外配置或提供,laya-client 会省略 model, 让 laya-serve 自动选择一个本地 checkpoint。客户端级或逐调用的 model 可以选择一个本地 checkpoint,下面表格里的其它逐请求控制项也一样。choice 标签数组在传输之前会被规范化成带 null 描述的映射。

响应保留 model、answers 和 token usage。Laya 的 routing 和答案 action 字段是可选 扩展;Noul 的置信度也是可选的。Choice 和 Score 的置信度、分布,以及 Score 的档位说明仍是必需的。 每条答案都携带 answer_confidence,即报告出来的那个答案上的 max(p) 概率质量,它在三种问题类型上是同一个量。一次传入了 min_confidence 的调用会在它的每条答案上报出 abstention 和 abstention_threshold,并对低于阈值的那些答案报出 low_confidence: true;没有设置阈值时,这三个键一个都不会发送,而这种缺席本身就是那份报告。 可选扩展在场时会被校验。

/v1/systemone 是客户端唯一调用的端点,它没有独立的路由方法:laya-client 只暴露 predict 和 health,别的什么都没有,而实时集成测试断言服务器对 /v1/route 返回 404。该端点确实支持的这些控制项都是逐请求的,而且只有当调用方提供了该选项时才会发送 —— 缺省的选项会让部署自己的 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] 之外值的阈值映射。没有任何东西会被静默忽略。Laya 公开的 /health 返回 status、loaded、revisions、device、device_is_preference、checkpoint_devices 和 cpu_fallbacks —— 与 laya-serve 部署页记录的正是同样这七个键;见 HTTP API。预测从不先探测健康。

FastAPI 的 detail 字符串和校验数组会保留为 LayaAPIError 的 messages/details。来自兼容后端的 结构化错误信封也会被接受。请求有可配置的截止时间和调用方取消,且从不自动重试。

验证与发布

单元测试覆盖请求构建、所有答案形状、Laya 扩展、FastAPI 错误、JSON 校验、截止时间和取消,并把这一页的控制表钉在客户端实际放到线上的那些字段上。类型 检查覆盖可选元数据、推断出的答案类型,以及 ESM/CommonJS 消费者。实时 集成测试用一个小型离线 checkpoint 启动未改动的 laya.serve 应用,把 SDK 的预测与直接 Python 推理对比,并演练路由、预设、认证和请求上限。CI 在 Node.js 22 和 24 上跑 SDK 检查。

极小的随机权重验证的是传输和数值一致性,不是预训练质量或性能。

设置、示例和 npm 发布见 SDK 指南。 这个包会以 laya-client 这个名字发布。Python 的发布工作流不变。