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 的发布工作流不变。