Gerar saídas estruturadas

info

Beta

Esse recurso está em Beta. Administradores da conta podem controlar o acesso a este recurso na página Prévias do console da conta. Consulte Gerenciar prévias do Databricks.

Estes artigos descrevem as saídas estruturadas na Databricks e como usá-las como parte de seus fluxos de trabalho de aplicativo de AI generativa. Saídas estruturadas funcionam com modelos OpenAI que oferecem suporte a modelos estruturados.

O que são saídas estruturadas?

Saídas estruturadas fornecem uma maneira de gerar dados estruturados na forma de objetos JSON a partir de seus dados de entrada. Você pode optar por gerar texto, objetos JSON não estruturados e objetos JSON que aderem a um esquema JSON específico. Saídas estruturadas são suportadas para modelos de chat servidos por serviços de modelo no Unity AI Gateway.

A Databricks recomenda o uso de saídas estruturadas para os seguintes cenários:

• Extração de dados de grandes volumes de documentos. Por exemplo, identificar e classificar o feedback de avaliação de produto como negativo, positivo ou neutro.
• tarefas de inferência em lotes que exigem que as saídas estejam em um formato especificado.
• Processamento de dados, como transformar dados não estruturados em dados estruturados.

Usar saídas estruturadas

Especifique suas saídas estruturadas usando response_format na sua solicitação de chat. Consulte Referência da API REST do modelo de base.

A seguir, um exemplo de extração de dados de artigos de pesquisa para um esquema JSON específico.

Python

import os
import json
from openai import OpenAI

client = OpenAI(
  api_key=os.environ.get('DATABRICKS_TOKEN'),
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"
  )

response_format = {
      "type": "json_schema",
      "json_schema": {
        "name": "research_paper_extraction",
        "schema": {
          "type": "object",
          "properties": {
            "title": { "type": "string" },
            "authors": {
              "type": "array",
              "items": { "type": "string" }
            },
            "abstract": { "type": "string" },
            "keywords": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
        },
        "strict": True
      }
    }

messages = [{
        "role": "system",
        "content": "You are an expert at structured data extraction. You will be given unstructured text from a research paper and should convert it into the given structure."
      },
      {
        "role": "user",
        "content": "..."
      }]

response = client.chat.completions.create(
    model="system.ai.gpt-oss-20b",
    messages=messages,
    response_format=response_format
)

print(json.dumps(response.choices[0].message.model_dump()['content'], indent=2))

A seguir, um exemplo de extração JSON, mas o esquema JSON não é conhecido antecipadamente.

Python

import os
import json
from openai import OpenAI

client = OpenAI(
  api_key=os.environ.get('DATABRICKS_TOKEN'),
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"
  )

response_format = {
      "type": "json_object",
    }

messages = [
      {
        "role": "user",
        "content": "Extract the name, size, price, and color from this product description as a JSON object:\n<description>\nThe SmartHome Mini is a compact smart home assistant available in black or white for only $49.99. It's 5 inches wide.\n</description>"
      }]

response = client.chat.completions.create(
    model="system.ai.gpt-oss-20b",
    messages=messages,
    response_format=response_format
)

print(json.dumps(response.choices[0].message.model_dump()['content'], indent=2))

Esquema JSON

Os serviços de modelo suportam amplamente saídas estruturadas aceitas pela OpenAI. No entanto, usar um esquema JSON mais simples para definições de esquema JSON resulta em uma geração JSON de maior qualidade. Para promover uma geração de maior qualidade, os serviços de modelo suportam apenas um subconjunto de especificações de esquema JSON.

As seguintes keys de definição de chamada de função não são suportadas:

• Expressões regulares usando pattern.
• Composição e validação complexas aninhadas ou de esquema usando: anyOf, oneOf, allOf, prefixItems ou $ref.
• Listas de tipos, exceto para o caso especial de [type, “null”], onde um tipo na lista é um tipo JSON válido e o outro é "null"

Uso dos tokens

A injeção de prompts e outras técnicas são usadas para melhorar a qualidade das saídas estruturadas. Isso impacta o número de tokens de entrada e saída consumidos pelo modelo, o que, por sua vez, resulta em implicações de faturamento.

Limitações

• O número máximo de key especificado no esquema JSON é 64.

• Serviços de modelo não impõem restrições de comprimento ou tamanho para objetos e arrays.

  • Isso inclui palavras-chave como maxProperties, minProperties e maxLength.

• Esquemas JSON muito aninhados resultam em geração de menor qualidade. Se possível, tente nivelar o esquema JSON para melhores resultados.

• Os modelos Anthropic Claude podem aceitar apenas json_schema saídas estruturadas. json_object não é compatível.