Suporte a saída estruturada para a API Prompt

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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ê diga ao modelo para responder apenas com "true" ou "false", o modelo pode responder com uma saída amigável e mais do que você pediu, como: "Certamente, a resposta é: true".

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 a saída estruturada está disponível na versão 137 do Chrome.

O que é o esquema JSON

O esquema JSON é um vocabulário que permite a consistência, a validade e a interoperabilidade dos dados JSON em grande escala. Quando se trata de troca de dados, o esquema JSON se destaca como um padrão poderoso 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 a saída estruturada, usada, entre outras, pela API OpenAI e pela API Gemini.

Por exemplo, você solicita que o modelo atribua 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 essa forma de objeto de saída solicitada ficaria 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, neste 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 sejam um espaço (\s) ou outro #.
    • $ → precisa terminar aí.

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

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

Leia a documentação Noções básicas do esquema JSON para conferir uma descrição completa dos recursos do formato.

Na verdade, os LLMs são muito bons na criação de esquemas JSON. Descreva as restrições em linguagem natural no comando e forneça um exemplo válido de objeto JSON. Em seguida, é possível validar objetos JSON em relação ao esquema JSON gerado com um dos validadores de esquema JSON, por exemplo, o Newtonsoft JSON Schema Validator on-line.

Transmitir um esquema JSON para a API Prompt

Para garantir que o modelo respeite um esquema JSON solicitado, é necessário transmitir 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 para 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  

Oferecer 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 Markdown ou outro pós-processamento, os desenvolvedores agora podem presumir que a resposta do modelo é JSON válido.

Isso aproxima a IA integrada das APIs baseadas em nuvem, com todos os benefícios da execução local da IA do lado do cliente.