Salidas estructuradas en Azure Databricks

Las salidas estructuradas en Azure Databricks te permiten generar respuestas en un formato JSON definido como parte de los flujos de trabajo de tu aplicación de IA. Funcionan con cualquier modelo de chat soportado a través de un response_format campo. Usas el mismo formato de solicitud independientemente del proveedor del modelo subyacente. Azure Databricks se encarga de cualquier traducción específica del proveedor por ti, por lo que no necesitas usar el formato nativo de salidas estructuradas del proveedor.

Tip

Genie Code (modo agente) puede hacerlo automáticamente. Pruebe esta indicación de ejemplo:

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.

¿Qué son las salidas estructuradas?

Las salidas estructuradas proporcionan una manera de generar datos estructurados en forma de objetos JSON a partir de los datos de entrada. Puede optar por generar texto, objetos JSON no estructurados y objetos JSON que se adhieren a un esquema JSON específico. Se admiten salidas estructuradas para modelos de chat servidos mediante las API de modelos base con pago por token y puntos de conexión de rendimiento aprovisionados.

Databricks recomienda usar salidas estructuradas para los escenarios siguientes:

Extracción de datos de grandes cantidades de documentos. Por ejemplo, identificar y clasificar los comentarios de revisión del producto como negativos, positivos o neutros.
Tareas de inferencia por lotes que requieren que las salidas estén en un formato especificado.
Procesamiento de datos, como convertir datos no estructurados en datos estructurados.

Uso de salidas estructuradas

Especifique las salidas estructuradas mediante response_format en la solicitud de chat. Consulte la referencia de la API REST del modelo fundacional.

A continuación se muestra un ejemplo de extracción de datos de documentos de investigación en un esquema JSON específico.

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 continuación se muestra un ejemplo de extracción de JSON, pero el esquema JSON no se conoce antes.

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

Las API de Foundation Model admiten ampliamente salidas estructuradas aceptadas por OpenAI. Sin embargo, el uso de un esquema JSON más sencillo para las definiciones de esquema JSON da como resultado una generación de JSON de mayor calidad. Para favorecer una generación de mayor calidad, las API de Foundation Model solo admiten un subconjunto de especificaciones de esquema JSON.

No se admiten las siguientes claves de definición de llamada a funciones:

Expresiones regulares con pattern.
Composición y validación de esquemas o anidados complejos mediante anyOf, oneOf, allOf, prefixItems o $ref.
Listas de tipos, excepto en el caso especial de [type, “null”], donde un tipo de la lista es un tipo JSON válido y el otro es "null".

Salidas estructuradas con modelos de Anthropic Claude

El siguiente ejemplo extrae datos a un esquema JSON específico usando un modelo Claude. El único cambio respecto a los ejemplos anteriores es el model valor.

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))

Los modelos Claude tienen restricciones adicionales para salidas estructuradas. Consulta la sección de Limitaciones.

Uso de tokens

Se utilizan la inyección de prompts y otras técnicas para mejorar la calidad de las salidas estructuradas. Hacer esto influye en el número de tokens de entrada y salida consumidos por el modelo, lo que a su vez repercute en la facturación.

Limitaciones

El número máximo de claves especificadas en el esquema JSON es 64.
Las API de Foundation Model no aplican restricciones de longitud ni tamaño para objetos y matrices.
- Esto incluye palabras clave como maxProperties, minProperties y maxLength.
Los esquemas JSON muy anidados dan lugar a una generación de menor calidad. Si es posible, intente aplanar el esquema JSON para obtener mejores resultados.

Los modelos Anthropic Claude tienen las siguientes restricciones adicionales para salidas estructuradas:

Solo se soporta el tipo de json_schema salida estructurada. No se admite json_object. Para la salida sin restricciones, omite response_format.
No se admiten salidas estructuradas con streaming. Configura stream para false cuando especifiques un response_format.
El response_format parámetro para salidas estructuradas de Claude no puede combinarse con tools o tool_choice.

Comentarios

¿Le resultó útil esta página?

Last updated on 2026-07-31