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 suas respostas longas ocasionais. Mesmo que você peça ao modelo para responder apenas com "verdadeiro" ou "falso", ele pode responder com uma saída amigável e mais do que você pediu, como: "Claro, 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 esquema JSON

O esquema JSON é um vocabulário que permite a 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 de dados JSON. Ele usa um conjunto de palavras-chave para definir as propriedades dos dados.

O esquema JSON é o padrão do setor para garantir a saída estruturada, usado, entre outros, pela API OpenAI e 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 JSON a seguir:

{
  "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 raiz precisa ser um objeto JSON.
• "properties": { "hashtags": ... }: o objeto pode (e, nesse caso, precisa) 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 #.
    • $ → precisa terminar ali.

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

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

Leia a documentação sobre os conceitos básicos do esquema JSON para conferir uma descrição completa dos recursos do formato.

Na verdade, os LLMs são muito bons em criar esquemas JSON. Descreva as restrições em linguagem natural no prompt e forneça um exemplo válido de objeto JSON. Você já está na metade do caminho. Em seguida, valide os objetos JSON em relação ao esquema JSON gerado com 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 de esquema JSON muito básico 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 à saída estruturada para a API Prompt torna as respostas do LLM muito mais previsíveis. Em vez de extrair um objeto de uma resposta do Markdown ou outra 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 da execução de IA local no lado do cliente.