Aller au contenu principal
Dernière mise à jour le

Sorties structurées sur Databricks

Les sorties structurées sur Databricks vous permettent de générer des réponses dans un format JSON défini dans le cadre de vos workflows d’application d’IA. Ils fonctionnent avec n’importe quel modèle de chat pris en charge via un champ response_format. Vous utilisez le même format de requête, quel que soit le fournisseur de modèle sous-jacent. Databricks gère pour vous toute traduction spécifique au fournisseur ; vous n’avez donc pas besoin d’utiliser le format de sorties structurées natif du fournisseur.

prompt

Genie Code (mode Agent) peut le faire pour vous. Essayez cet exemple de prompt :

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.

Que sont les sorties structurées ?​

Les sorties structurées permettent de générer des données structurées sous forme d'objets JSON à partir de vos données d'entrée. Vous pouvez choisir de générer du texte, des objets JSON non structurés et des objets JSON qui adhèrent à un schéma JSON spécifique. Les sorties structurées sont prises en charge pour les modèles de chat servis via les APIs de modèle de fondation avec paiement au jeton et les endpoints de throughput provisionné.

Databricks recommande d’utiliser des sorties structurées dans les scénarios suivants :

  • Extraction de données à partir de grandes quantités de documents. Par exemple, l'identification et la classification des commentaires d'avis sur un produit comme négatifs, positifs ou neutres.
  • Tâches d'inférence batch qui nécessitent que les sorties soient dans un format spécifié.
  • Traitement des données, comme la transformation des données non structurées en données structurées.

Utiliser des sorties structurées​

Spécifiez vos sorties structurées en utilisant response_format dans votre requête de discussion. Consulter la référence d’API REST du modèle de fondation.

Voici un exemple d’extraction de données d’articles de recherche vers un schéma JSON spécifique.

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

Voici un exemple d’extraction JSON, mais le schéma JSON n’est pas connu à l’avance.

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

Schéma JSON​

Les APIs de modèle de fondation prennent généralement en charge les sorties structurées acceptées par OpenAI. Cependant, l'utilisation d'un schéma JSON plus simple pour les définitions de schéma JSON donne une génération JSON de meilleure qualité. Pour promouvoir une génération de meilleure qualité, les APIs Foundation Model ne prennent en charge qu'un sous-ensemble des spécifications de schémas JSON.

Les clés de définition d'appel de fonction suivantes ne sont pas prises en charge :

  • Expressions régulières utilisant pattern.
  • Composition et validation de schémas complexes ou imbriqués à l'aide de : anyOf, oneOf, allOf, prefixItems, ou $ref.
  • Listes de types à l'exception du cas particulier de [type, “null”] où un type de la liste est un type JSON valide et l'autre est "null"

Sorties structurées avec les modèles Anthropic Claude​

L'exemple suivant permet d'extraire des données vers un schéma JSON spécifique à l'aide d'un modèle Claude. Le seul changement par rapport aux exemples précédents est la valeur 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))

Les modèles Claude ont des contraintes supplémentaires pour les sorties structurées. Consultez la section Limitations.

Utilisation des jetons​

L'injection de prompt et d'autres techniques sont utilisées pour améliorer la qualité des sorties structurées. Cela a un impact sur le nombre de jetons d'entrée et de sortie consommés par le modèle, ce qui entraîne des implications de facturation.

Limitations​

  • Le nombre maximal de clés spécifié dans le schéma JSON est de 64.

  • Les APIs Foundation Model n'imposent pas de contraintes de longueur ou de taille pour les objets et les tableaux.

    • Cela inclut des mots-clés comme maxProperties, minProperties et maxLength.

  • Les schémas JSON fortement imbriqués entraînent une génération de moindre qualité. Si possible, essayez d'aplatir le schéma JSON pour de meilleurs résultats.

Les modèles Claude d'Anthropic présentent les contraintes supplémentaires suivantes pour les sorties structurées :

  • Seul le type de sortie structurée json_schema est pris en charge. json_object n'est pas pris en charge. Pour une sortie sans contrainte, omettez response_format.
  • Les sorties structurées ne sont pas prises en charge avec le streaming. Définissez stream sur false lorsque vous spécifiez un response_format.
  • Le parameter response_format pour les sorties structurées de Claude ne peut pas être combiné avec tools ou tool_choice.
Sur cette page