TypeScript SDK 설계

laya-client는 자체 호스팅 laya-serve 서버를 위한 무의존성 HTTP 클라이언트입니다. POST /v1/systemone 엔드포인트를 사용하며 Python 프로덕션 코드나 서버 의존성을 추가하지 않습니다. npm 패키지는 Python 릴리스와 독립적으로 버전 0.1.0에서 시작합니다.

경계

구성 요소	책임
`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와 Laya 전용 health 프로브를 내보냅니다. ESM, CommonJS, 선언을 함께 제공하며, 추론된 질문 ID와 choice 레이블을 유지합니다. JavaScript나 TypeScript 애플리케이션이 HTTP로 자체 호스팅 Python laya-serve와 통신할 때는 laya-client를 쓰십시오. 추론이 Python 서버 없이 로컬 ONNX 런타임을 통해 JavaScript 안에서 직접 실행되어야 할 때는 laya-ts를 쓰십시오.

공유 계약

요청은 state와 questions를 담습니다. 설정되었거나 예측을 위해 제공되지 않는 한, laya-client는 model을 생략하여 laya-serve가 로컬 체크포인트를 자동으로 선택하게 합니다. 클라이언트 전역 또는 호출별 model이 로컬 체크포인트를 선택할 수 있으며, 아래 표의 다른 요청별 제어도 마찬가지입니다. choice 레이블 배열은 전송 전에 null 설명을 가진 맵으로 정규화됩니다.

응답은 model, answers, 토큰 usage를 보존합니다. Laya의 routing과 답의 action 필드는 선택적 확장이고, Noul 신뢰도도 선택 사항입니다. Choice와 Score의 신뢰도, 분포, Score legend는 여전히 필수입니다. 모든 답은 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, device를 돌려줍니다. 예측은 결코 먼저 헬스를 프로브하지 않습니다.

FastAPI의 detail 문자열과 검증 배열은 LayaAPIError 메시지/detail로 보존됩니다. 호환 백엔드의 구조화된 오류 봉투도 받습니다. 요청에는 설정 가능한 기한과 호출자 취소가 있고, 자동으로 재시도되지 않습니다.

검증과 릴리스

단위 테스트는 요청 구성, 모든 답 형태, Laya 확장, FastAPI 오류, JSON 검증, 기한, 취소를 커버하고, 이 페이지의 제어 표를 클라이언트가 실제로 와이어에 올리는 필드에 고정합니다. 타입 검사는 선택적 메타데이터, 추론된 답 타입, ESM/CommonJS 소비자를 커버합니다. 라이브 통합 테스트는 변경되지 않은 laya.serve 애플리케이션을 아주 작은 오프라인 체크포인트로 시작하고, SDK 예측을 직접 Python 추론과 비교하며, 라우팅, 프리셋, 인증, 요청 한도를 시험합니다. CI는 Node.js 22와 24에서 SDK 검사를 실행합니다.

아주 작은 랜덤 가중치는 전송과 수치적 동등성을 검증할 뿐, 사전 학습된 품질이나 성능을 검증하지 않습니다.

설정, 예제, npm 게시는 SDK 가이드를 참고하십시오. 패키지는 laya-client 이름으로 게시될 예정입니다. Python 릴리스 워크플로는 변경되지 않습니다.