Design do SDK TypeScript

laya-client é um cliente HTTP sem dependências para um servidor laya-serve auto-hospedado. Ele usa o endpoint POST /v1/systemone e não adiciona nenhum código Python de produção nem dependências de servidor. O pacote npm começa na versão 0.1.0, independentemente das versões do Python.

Fronteiras

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

O SDK exporta predict e uma sonda health exclusiva do Laya. Ele distribui ESM, CommonJS e declarações, preservando ids de pergunta e rótulos de escolha inferidos. Use laya-client quando uma aplicação JavaScript ou TypeScript conversa por HTTP com um laya-serve Python auto-hospedado. Use laya-ts quando a inferência precisa rodar diretamente dentro do JavaScript, através do seu runtime ONNX local, sem um servidor Python.

Contrato compartilhado

As solicitações contêm state e questions. A menos que configurado ou fornecido para uma predição, laya-client omite model, deixando o laya-serve selecionar um checkpoint local automaticamente. Um model para o cliente inteiro ou por chamada pode selecionar um checkpoint local, assim como os demais controles por solicitação da tabela abaixo. Arrays de rótulos de escolha são normalizados para mapas com descrições nulas antes do transporte.

As respostas preservam model, answers e o usage de tokens. Os campos routing do Laya e action da resposta são extensões opcionais; a confiança de Noul também é opcional. A confiança de Choice e Score, as distribuições e as legendas de Score continuam obrigatórias. Toda resposta carrega answer_confidence, a massa max(p) sobre a resposta reportada, que é a mesma quantidade nos três tipos de pergunta. Uma chamada à qual foi passado min_confidence reporta abstention e abstention_threshold em cada uma de suas respostas e low_confidence: true nas que ficam abaixo do limiar; sem limiar definido, nenhuma dessas três chaves é enviada, e essa ausência é o relatório. Extensões opcionais são validadas quando presentes.

O /v1/systemone é o único endpoint que o cliente chama, e ele não tem um método de roteamento autônomo: laya-client expõe predict e health e nada mais, e o teste de integração ao vivo afirma que o servidor responde 404 para /v1/route. Os controles que o endpoint de fato respeita são por solicitação, e cada um é enviado só quando o chamador forneceu a opção – uma opção ausente deixa as próprias configurações de Router(...) da implantação no comando, em vez de sobrescrevê-las com um padrão do lado do cliente:

Uma opção que não pode significar nada é recusada localmente, antes de a solicitação sair: um task em branco, um orçamento que não é um inteiro positivo, um limiar fora de [0, 1], ou um mapa de limiares vazio ou com um valor fora de [0, 1]. Nada é ignorado em silêncio. O /health público do Laya retorna status, loaded e device. A predição nunca sonda o health primeiro.

As strings de detalhe e os arrays de validação do FastAPI são preservados como mensagens/detalhes de LayaAPIError. Envelopes de erro estruturados de backends compatíveis também são aceitos. As solicitações têm prazos configuráveis e cancelamento pelo chamador, e nunca são repetidas automaticamente.

Verificação e lançamento

Os testes unitários cobrem a construção de solicitações, todos os formatos de resposta, extensões do Laya, erros do FastAPI, validação de JSON, prazos e cancelamento, e prendem a tabela de controles desta página aos campos que o cliente realmente coloca no fio. As checagens de tipo cobrem metadados opcionais, tipos de resposta inferidos e consumidores ESM/CommonJS. O teste de integração ao vivo inicia a aplicação laya.serve sem alterações com um checkpoint offline minúsculo, compara as predições do SDK com a inferência direta em Python, e exercita roteamento, presets, autenticação e limites de solicitação. A CI roda as checagens do SDK em Node.js 22 e 24.

Pesos aleatórios minúsculos verificam o transporte e a paridade numérica, não a qualidade ou o desempenho pré-treinados.

Veja o guia do SDK para configuração, exemplos e publicação no npm. O pacote será publicado sob o nome laya-client. Os fluxos de lançamento do Python não mudam.