Suporte a saída estruturada para a API Prompt

Thomas Steiner

Publicado em: 13 de maio de 2025

Os modelos de linguagem grandes (LLMs) são conhecidos por respostas longas ocasionais. Mesmo que você peça para o modelo responder apenas com "verdadeiro" ou "falso", ele pode responder com uma saída amigável e mais do que você pediu, como: "Com certeza, a resposta é: verdadeiro".

Para resolver esse problema, a API Prompt permite especificar um formato de saída JSON da resposta do modelo transmitindo um esquema JSON para os métodos LanguageModel.prompt() e LanguageModel.promptStreaming(). O suporte à saída estruturada está disponível a partir da versão 137 do Chrome.

O que é o JSON Schema?

O esquema JSON é um vocabulário que permite consistência, validade e interoperabilidade de dados JSON em grande escala. Quando se trata de troca de dados, o esquema JSON se destaca como um padrão eficiente para definir a estrutura e as regras dos dados JSON. Ele usa um conjunto de palavras-chave para definir as propriedades dos seus dados.

O esquema JSON é o padrão do setor para garantir uma saída estruturada, usado, entre outros, pela API OpenAI e pela API Gemini.

Por exemplo, você pede ao modelo para atribuir no máximo três hashtags a uma postagem em uma rede social on-line, como o Mastodon. A saída ideal pode ser semelhante ao seguinte JSON:

{
  "hashtags": [
    "#pottery",
    "#dyi"
  ] 
}

O esquema JSON correspondente para esse formato de objeto de saída solicitado seria assim:

{
  "type": "object",
  "properties": {
    "hashtags": {
      "type": "array",
      "maxItems": 3,
      "items": {
        "type": "string",
        "pattern": "^#[^\\s#]+$"
      }
    }
  },
  "required": ["hashtags"],
  "additionalProperties": false
}

Esse esquema JSON define uma estrutura para um objeto que precisa conter um campo hashtags com as seguintes restrições:

• "type": "object": o valor da raiz precisa ser um objeto JSON.
• "properties": { "hashtags": ... }: o objeto pode (e, neste caso, deve) ter uma propriedade chamada hashtags.

• "hashtags":

  • "type": "array": o valor precisa ser uma matriz.
  • "maxItems": 3: a matriz pode conter no máximo três itens.
  • "items": { "type": "string", "pattern": "^#[^\\s#]+$" }: cada item na matriz precisa ser uma string que corresponda ao padrão de expressão regular fornecido: ^#[^\\s#]+$:
    • ^# → precisa começar com um #.
    • [^\\s#]+ → seguido por um ou mais caracteres que não são um espaço (\s) ou outro #.
    • $ → deve terminar aí.

• "required": ["hashtags"]: o objeto precisa conter a propriedade hashtags.

• "additionalProperties": false: nenhuma outra propriedade além das hashtags é permitida.

Leia a documentação Fundamentos do esquema JSON para uma descrição completa das funcionalidades do formato.

Na verdade, os LLMs são muito bons em criar esquemas JSON. Descreva as restrições em linguagem natural no comando e forneça um exemplo válido de objeto JSON. Assim, você já está na metade do caminho. Em seguida, valide os objetos JSON com o esquema JSON gerado usando um dos validadores de esquema JSON, por exemplo, o validador de esquema JSON Newtonsoft on-line.

Transmitir um esquema JSON para a API Prompt

Para garantir que o modelo respeite um esquema JSON solicitado, transmita o esquema JSON como um argumento para o objeto de opções dos métodos prompt() ou promptStreaming() como o valor de um campo responseConstraint.

Confira um exemplo muito básico de esquema JSON que garante que o modelo responda com true ou false ao classificar se uma determinada mensagem como esta postagem do Mastodon é sobre cerâmica.

const session = await LanguageModel.create();

const schema = {
  "type": "boolean"
};

const post = "Mugs and ramen bowls, both a bit smaller than intended- but that's
how it goes with reclaim. Glaze crawled the first time around, but pretty happy
with it after refiring.";

const result = await session.prompt(  
  `Is this post about pottery?\n\n${post}`,
  {  
    responseConstraint: schema,
  }
);
console.log(JSON.parse(result));
// true

Suporte a saídas previsíveis

O suporte a saída estruturada da API Prompt torna as respostas do LLM muito mais previsíveis. Em vez de extrair um objeto de uma resposta em Markdown ou outro pós-processamento, os desenvolvedores agora podem presumir que a resposta do modelo é um JSON válido.

Isso aproxima a IA integrada das APIs baseadas na nuvem, com todos os benefícios de executar a IA local do lado do cliente.