Pular para o conteúdo principal
Última atualização em

Saídas estruturadas em Databricks

As saídas estruturadas no Databricks permitem gerar respostas em um formato JSON definido como parte dos fluxos de trabalho da sua aplicação de AI. Eles funcionam com qualquer modelo de chat compatível por meio de um campo response_format. Você usa o mesmo formato de solicitação, independentemente do provedor de modelo subjacente. O Databricks lida com qualquer tradução específica do provedor para você, portanto, não é necessário usar o formato de saídas estruturadas nativo do provedor.

prompt

Genie Code (modo Agente) pode fazer isso por você. Experimente este prompt de exemplo:

Query the databricks-gpt-oss-20b model with a JSON schema response format to extract title, authors, abstract, and keywords from a research paper description. Note: this model returns content as a list of blocks; extract the block with type "text" and parse it.

O que são saídas estruturadas?​

As saídas estruturadas oferecem uma maneira de gerar dados estruturados na forma de objetos JSON a partir de seus dados de entrada. O senhor pode optar por gerar texto, objetos JSON não estruturados e objetos JSON que aderem a um esquema JSON específico. As saídas estruturadas são compatíveis com os modelos de bate-papo atendidos usando o Foundation Model APIs pay-per-tokens e o endpoint de provisionamento da Taxa de transferência.

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

  • extração de dados de grandes quantidades de documentos. Por exemplo, identificar e classificar o feedback da avaliação do produto como negativo, positivo ou neutro.
  • A tarefa de inferência de lotes que exige que os resultados estejam em um formato específico.
  • Processamento de dados, como transformar dados não estruturados em dados estruturados.

Use saídas estruturadas​

Especifique suas saídas estruturadas usando response_format em sua solicitação de bate-papo. Consulte a referência da API REST do modelo Foundation.

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

DATABRICKS_TOKEN = os.environ.get('YOUR_DATABRICKS_TOKEN')
DATABRICKS_BASE_URL = os.environ.get('YOUR_DATABRICKS_BASE_URL')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url=DATABRICKS_BASE_URL
  )

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="databricks-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 de JSON, mas o esquema JSON não é conhecido de antemão.

Python
import os
import json
from openai import OpenAI

DATABRICKS_TOKEN = os.environ.get('YOUR_DATABRICKS_TOKEN')
DATABRICKS_BASE_URL = os.environ.get('YOUR_DATABRICKS_BASE_URL')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url=DATABRICKS_BASE_URL
  )

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="databricks-gpt-oss-20b",
    messages=messages,
    response_format=response_format
)

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

Esquema JSON​

As APIs do Foundation Model suportam amplamente as saídas estruturadas aceitas pela OpenAI. No entanto, o uso de um esquema JSON mais simples para definições de esquema JSON resulta em uma geração de JSON de maior qualidade. Para promover uma geração de maior qualidade, as APIs do Foundation Model suportam apenas um subconjunto de especificações de esquema JSON.

A seguinte chave de definição de chamada de função não é suportada:

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

Saídas estruturadas com modelos Anthropic Claude​

O exemplo a seguir faz extração de dados para um esquema JSON específico usando um modelo Claude. A única mudança em relação aos exemplos anteriores é o valor model.

Python
import os
import json
from openai import OpenAI

DATABRICKS_TOKEN = os.environ.get('YOUR_DATABRICKS_TOKEN')
DATABRICKS_BASE_URL = os.environ.get('YOUR_DATABRICKS_BASE_URL')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url=DATABRICKS_BASE_URL
  )

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="databricks-claude-sonnet-4-5",
    messages=messages,
    response_format=response_format
)

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

Os modelos Claude possuem restrições adicionais para saídas estruturadas. Consulte a seção Limitações.

uso de tokens​

A injeção rápida e outras técnicas são usadas para melhorar a qualidade das saídas estruturadas. Isso afeta 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 chaves especificado no esquema JSON é 64.

  • As APIs do Foundation Model não impõem restrições de comprimento ou tamanho para objetos e matrizes.

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

  • Os esquemas JSON muito aninhados resultam em uma geração de qualidade inferior. Se possível, tente achatar o esquema JSON para obter melhores resultados.

Os modelos Anthropic Claude têm as seguintes restrições adicionais para saídas estruturadas:

  • Apenas o tipo de saída estruturada json_schema é compatível. json_object não é compatível. Para uma saída sem restrições, omita response_format.
  • Saídas estruturadas não são compatíveis com a transmissão. Defina stream como false ao especificar um response_format.
  • O parâmetro response_format para saídas estruturadas do Claude não pode ser combinado com tools ou tool_choice.
Nesta página