NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações
SDK para TypeScript

LLM e Reduce

Obtenha JSON validado de um modelo de linguagem com client.llm e use client.reduce para escolher o melhor de vários resultados, votar, juntar ou mesclar.

client.llm pede a um modelo de linguagem uma saída estruturada: você envia um prompt de sistema, uma entrada e um JSON Schema, e recebe de volta um objeto que segue o schema. client.reduce executa isoladamente a etapa de fan-in do Reduce: escolhe o melhor de vários resultados, conta os resultados, faz uma votação, junta textos ou mescla JSON. É o trabalho que o nó Escolher o melhor faz em um workflow. Uma chamada a um modelo de linguagem em qualquer um dos dois é cobrada pelos tokens que usa, pela tarifa do modelo. Veja Como as chamadas de LLM são cobradas.

Métodos

MétodoO que faz
llm.structured(input)Obtém um objeto validado de um modelo de linguagem, em uma única requisição
llm.structuredJob(input)A mesma chamada, como uma tarefa que você consulta periodicamente
reduce.run(input)Escolhe, conta, vota, junta ou mescla muitas entradas em uma só

client.llm

Saída estruturada: entram seu prompt de sistema e seu JSON Schema, sai um objeto validado. A plataforma escolhe a rota do modelo, força a saída em JSON, valida essa saída com o seu schema e devolve as respostas inválidas ao modelo antes de desistir. A cobrança é feita como llm-structured, pelos tokens que a chamada usou, pela tarifa do modelo na rota que a atendeu. Primeiro, uma reserva é feita, e um saldo abaixo dela lança InsufficientCreditsError. A chamada é então cobrada pelo que usou. Uma falha que o provedor cobrou é cobrada por esse uso. O Claude Fable 5 é oferecido. Para cotar uma chamada típica, passe llmPriceKey("llm-structured", model) para credits.modelCosts().

llm.structured(input)

Pergunta ao modelo e espera a resposta (POST /v1/llm/structured). Uma chamada pode levar vários minutos, mais que o tempo limite padrão de 60 segundos do cliente. Para ela, crie o cliente com um timeoutMs maior ou use structuredJob().

structured<T>(input: LlmStructuredInput): Promise<{
  jobId: string
  output: T
  usage: { inputTokens: number; outputTokens: number }
}>

Propriedade

Tipo

type Plan = { title: string; scenes: string[] }

const { output } = await client.llm.structured<Plan>({
  system: "You write production plans for short films.",
  input: "A rainy chase through Rome, 60 seconds.",
  jsonSchema: {
    type: "object",
    properties: {
      title: { type: "string" },
      scenes: { type: "array", items: { type: "string" } },
    },
    required: ["title", "scenes"],
  },
  schemaName: "production_plan",
})
console.log(output.title, output.scenes.length)

llm.structuredJob(input)

A mesma chamada, como uma tarefa (POST /v1/llm/structured/jobs). Retorna um jobId na hora; consulte a tarefa periodicamente com client.jobs.getStatus(). Uma tarefa também pode criar o rascunho a partir de um vídeo: a plataforma analisa o vídeo primeiro e depois acrescenta a análise à sua entrada.

structuredJob(input: LlmStructuredJobInput): Promise<{ jobId: string }>

Propriedade

Tipo

const { jobId } = await client.llm.structuredJob({
  system: "You write production plans.",
  input: "A rainy chase through Rome.",
  jsonSchema: { type: "object", properties: { title: { type: "string" } }, required: ["title"] },
  origin: "my-app",
  label: "Rome chase",
})

// later, even from another session
const { data } = await client.jobs.getStatus(jobId)
if (data.status === "completed") {
  console.log((data.output_data as { output: { title: string } }).output.title)
}
const { data: runs } = await client.jobs.list({ type: "llm-structured", origin: "my-app" })

Enquanto a tarefa é executada, o output_data dela contém stage: analyzing (nos rascunhos a partir de vídeo) ou drafting. Quando a tarefa termina, output_data contém output, inputTokens e outputTokens, além de analysisJobId e analysisCredits no caso de um rascunho a partir de vídeo.

  • analysisJobId falha com 422 quando a tarefa não é sua, não existe ou não é uma análise de vídeo concluída. Os códigos são analysis_not_found, not_analysis, analysis_failed, analysis_not_ready e invalid_analysis.
  • Em uma plataforma sem esta rota, o método lança NotFoundError.
  • Uma instância auto-hospedada que envia as chamadas de modelo de linguagem ao Nodaro Cloud responde 503 provider_unavailable. Trate isso como um recurso indisponível nessa instância, não como um erro passageiro.

client.reduce

reduce.run(input)

Reduz muitas entradas a uma só. Equivale à ferramenta reduce do MCP e ao nó Escolher o melhor.

run(input: ReduceInput): Promise<ReduceResult>

Propriedade

Tipo

EstratégiastrategyConfigO que retorna
pick-best-llm{ criteria, inputKind?, llmModel? }. inputKind é "text" ou "image-url". llmModel escolhe o modelo juiz. A chamada do juiz é cobrada por token, pela tarifa desse modelo.A entrada que um modelo de linguagem julga a melhor, com o índice e o raciocínio
concat{ separator? }, uma linha em branco por padrãoTodas as entradas unidas em um único texto
first-non-emptynenhumaA primeira entrada que não está vazia
countnenhumaO número de entradas
vote{ caseSensitive? }, false por padrãoA entrada mais frequente. Em caso de empate, vence a primeira.
merge-json{ strategy? }: "deep" (o padrão) ou "shallow"As entradas JSON mescladas em um único objeto
const result = await client.reduce.run({
  strategyId: "pick-best-llm",
  strategyConfig: { criteria: "The sharpest image with no artifacts", inputKind: "image-url" },
  inputs: [url1, url2, url3, url4, url5],
})
console.log(result.output)             // the chosen URL
console.log(result.meta.selectedIndex) // 0 to 4
console.log(result.meta.reasoning)     // why the model chose it

O resultado é { jobId, output, meta }. output é o valor escolhido ou combinado, como string. meta.summary sempre vem preenchido. pick-best-llm e vote preenchem meta.selectedIndex, e pick-best-llm também preenche meta.reasoning.

// Majority vote
const winner = await client.reduce.run({ strategyId: "vote", inputs: ["red", "blue", "red"] })

// Deep-merge JSON fragments
const merged = await client.reduce.run({
  strategyId: "merge-json",
  inputs: [JSON.stringify({ a: 1, nested: { x: 1 } }), JSON.stringify({ b: 2, nested: { y: 2 } })],
})
JSON.parse(merged.output) // { a: 1, b: 2, nested: { x: 1, y: 2 } }

Quando todas as entradas estão vazias ou têm só espaços em branco, a chamada falha com um NodaroError de status 400 e code igual a no_valid_inputs. Os créditos são reservados como em qualquer geração, então um saldo insuficiente lança InsufficientCreditsError.

Perguntas frequentes

Como obter de um modelo de linguagem um JSON que siga o meu schema?

Chame client.llm.structured com um prompt de sistema, uma entrada e um objeto JSON Schema. A plataforma obriga o modelo a responder nesse formato, valida a resposta, tenta de novo quando ela é inválida e retorna o JSON já convertido em objeto.

Quando usar structuredJob em vez de structured?

Use structuredJob para chamadas longas. structured espera a resposta em uma única requisição, o que pode levar minutos, mais que o tempo limite padrão de 60 segundos. structuredJob retorna um jobId na hora.

Como escolher a melhor entre várias imagens geradas?

Chame client.reduce.run com strategyId pick-best-llm, seus critérios e inputKind image-url, e passe as URLs das imagens como inputs. O resultado indica a URL escolhida, o índice dela e o raciocínio do modelo.

Quanto custa uma chamada de LLM estruturada?

Ela é cobrada pelos tokens que realmente usou, pela tarifa do modelo na rota que a atendeu. Primeiro, uma reserva é feita, e depois a chamada é cobrada pelo que usou. client.credits.modelCosts com a chave llm-structured:<model> retorna uma estimativa de uma chamada típica.

Quais estratégias do Reduce não precisam de um modelo de linguagem?

concat, first-non-empty, count, vote e merge-json são executadas sem modelo. Apenas pick-best-llm pede a um modelo de linguagem que faça o julgamento.

Última atualização

Nesta página