Sortie structurée pour les modèles ouverts

Les sorties structurées permettent à un modèle de générer des sorties qui respectent toujours un schéma spécifique. Par exemple, un schéma de réponse peut être fourni à un modèle pour s'assurer que la réponse produit un code JSON valide. Tous les modèles ouverts disponibles sur Vertex AI Model as a Service (MaaS) sont compatibles avec les sorties structurées.

Pour en savoir plus sur la fonctionnalité de sortie structurée, consultez Présentation des sorties structurées.

Utiliser des sorties structurées

Le cas d'utilisation suivant définit un schéma de réponse qui garantit que la sortie du modèle est un objet JSON avec les propriétés suivantes : nom, date et participants. Le code Python utilise le SDK OpenAI et les objets Pydantic pour générer le schéma JSON.

from pydantic import BaseModel
from openai import OpenAI

client = OpenAI()

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

completion = client.beta.chat.completions.parse(
    model="MODEL_NAME",
    messages=[
        {"role": "system", "content": "Extract the event information."},
        {"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
    ],
    response_format=CalendarEvent,
)

print(completion.choices[0].message.parsed)

La sortie du modèle respectera le schéma JSON suivant :

{ "name": STRING, "date": STRING, "participants": [STRING] }

Si vous fournissez la requête "Alice et Bob vont à une exposition scientifique vendredi", le modèle peut générer la réponse suivante :

{
  "name": "science fair",
  "date": "Friday",
  "participants": [
    "Alice",
    "Bob"
  ]
}

Exemple détaillé

Le code suivant est un exemple de schéma récursif. La classe UI contient une liste de children, qui peuvent également appartenir à la classe UI.

from pydantic import BaseModel
from openai import OpenAI
from enum import Enum
from typing import List

client = OpenAI()

class UIType(str, Enum):
  div = "div"
  button = "button"
  header = "header"
  section = "section"
  field = "field"
  form = "form"

class Attribute(BaseModel):
  name: str
  value: str

class UI(BaseModel):
  type: UIType
  label: str
  children: List["UI"]
  attributes: List[Attribute]

UI.model_rebuild() # This is required to enable recursive types

class Response(BaseModel):
  ui: UI

completion = client.beta.chat.completions.parse(
  model="MODEL_NAME",
  messages=[
    {"role": "system", "content": "You are a UI generator AI. Convert the user input into a UI."},
    {"role": "user", "content": "Make a User Profile Form"}
  ],
  response_format=Response,
)

print(completion.choices[0].message.parsed)

La sortie du modèle respectera le schéma de l'objet Pydantic spécifié dans l'extrait précédent. Dans cet exemple, le modèle pourrait générer le formulaire d'UI suivant :

Form
  Input
    Name
    Email
    Age

Une réponse peut ressembler à ce qui suit :

ui = UI(
    type=UIType.div,
    label='Form',
    children=[
        UI(
            type=UIType.div,
            label='Input',
            children=[],
            attributes=[
                Attribute(name='label', value='Name')
            ]
        ),
        UI(
            type=UIType.div,
            label='Input',
            children=[],
            attributes=[
                Attribute(name='label', value='Email')
            ]
        ),
        UI(
            type=UIType.div,
            label='Input',
            children=[],
            attributes=[
                Attribute(name='label', value='Age')
            ]
        )
    ],
    attributes=[
        Attribute(name='name', value='John Doe'),
        Attribute(name='email', value='john.doe@example.com'),
        Attribute(name='age', value='30')
    ]
)

Obtenir des réponses d'objet JSON

Vous pouvez contraindre le modèle à n'afficher que des objets JSON valides sur le plan syntaxique en définissant le champ response_format sur { "type": "json_object" }. C'est ce qu'on appelle souvent le mode JSON. Le mode JSON est utile pour générer du code JSON à utiliser avec l'appel de fonction ou d'autres tâches en aval nécessitant une entrée JSON.

Lorsque le mode JSON est activé, le modèle est limité à la génération de chaînes qui peuvent être analysées en objets JSON valides. Bien que ce mode garantisse que la sortie est un JSON syntaxiquement correct, il n'applique aucun schéma spécifique. Pour vous assurer que le modèle génère un fichier JSON qui suit un schéma spécifique, vous devez inclure des instructions dans la requête, comme illustré dans l'exemple suivant.

Les exemples suivants montrent comment activer le mode JSON et demander au modèle de renvoyer un objet JSON avec une structure spécifique :

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide de Vertex AI sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI pour Python.

Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

Avant d'exécuter cet exemple, assurez-vous de définir la variable d'environnement OPENAI_BASE_URL. Pour en savoir plus, consultez Authentification et identifiants.

from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
  model="MODEL",
  response_format={ "type": "json_object" },
  messages=[
    {"role": "user", "content": "List 5 rivers in South America. Your response must be a JSON object with a single key \"rivers\", which has a list of strings as its value."},
  ]
)
print(response.choices[0].message.content)

Remplacez MODEL par le nom du modèle que vous souhaitez utiliser, par exemple meta/llama3-405b-instruct-maas.

REST

Une fois que vous avez configuré votre environnement, vous pouvez utiliser REST pour tester un prompt textuel. L'exemple suivant envoie une requête au point de terminaison du modèle de l'éditeur.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud.
  • LOCATION : région compatible avec les modèles ouverts.
  • MODEL : nom du modèle que vous souhaitez utiliser, par exemple meta/llama3-405b-instruct-maas.

Méthode HTTP et URL : 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions

Corps JSON de la requête : 

{
  "model": "MODEL",
  "response_format": {
    "type": "json_object"
  },
  "messages": [
    {
      "role": "user",
      "content": "List 5 rivers in South America. Your response must be a JSON object with a single key \"rivers\", which has a list of strings as its value."
    }
  ]
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions"

PowerShell

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON semblable à la suivante.

Étapes suivantes