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étodo | O 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.
analysisJobIdfalha 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ãoanalysis_not_found,not_analysis,analysis_failed,analysis_not_readyeinvalid_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égia | strategyConfig | O 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ão | Todas as entradas unidas em um único texto |
first-non-empty | nenhuma | A primeira entrada que não está vazia |
count | nenhuma | O número de entradas |
vote | { caseSensitive? }, false por padrão | A 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 itO 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.
Páginas relacionadas
Escolher o melhor
Executar nós
Tarefas e execuções
Seletores, predefinições e prompts
Última atualização
Apps e templates
Explore e execute apps publicados do Nodaro em TypeScript, leia o histórico de execuções, clone templates de workflow em um projeto e liste os tutoriais.
Mídia e uploads
Envie arquivos ao Nodaro, liste sua biblioteca, importe vídeos de links, corte clipes, embuta legendas e componha imagens e vídeos em TypeScript.