For AI agents: the complete documentation index is available at https://docs.ovhcloud.com/fr/llms.txt, the full documentation bundle is available at https://docs.ovhcloud.com/fr/llms-full.txt, and this page is available as Markdown at https://docs.ovhcloud.com/fr/guides/public-cloud/ai-machine-learning/ai-endpoints-structured-output.md.

AI Endpoints - Sorties structurées

Voir en Markdown

Découvrez comment utiliser les sorties structurées avec OVHcloud AI Endpoints

Info

AI Endpoints est couvert par les Conditions particulières OVHcloud Public Cloud (voir l’Annexe 10 – « Conditions spécifiques – AI Endpoints »).

Introduction

AI Endpoints est une plateforme serverless proposée par OVHcloud qui offre un accès simplifié à une sélection de modèles d'IA pré-entraînés, mondialement reconnus. La plateforme est conçue pour être simple, sécurisée et intuitive, ce qui en fait une solution idéale pour les développeurs souhaitant enrichir leurs applications avec des capacités d'IA sans expertise poussée en IA ni préoccupations sur la confidentialité des données.

Les sorties structurées (Structured Output) sont une fonctionnalité puissante qui vous permet d'imposer des formats spécifiques aux réponses des modèles d'IA. En utilisant le paramètre response_format dans vos appels API, vous pouvez définir la structure souhaitée de la sortie, garantissant ainsi cohérence et facilité d'intégration avec vos applications. Ceci est particulièrement utile lorsque vous avez besoin que le modèle d'IA renvoie des données dans un format JSON spécifique. La spécification JSON schema peut être utilisée pour décrire la structure de données que la sortie doit respecter, et le modèle d'IA génèrera des réponses qui y correspondent. Cette fonctionnalité permet une intégration fluide des données générées par l'IA dans vos applications, vous permettant de construire des workflows robustes et cohérents.

Objectif

Cette documentation présente un aperçu de l'utilisation des sorties structurées avec les différents modèles d'IA proposés sur AI Endpoints.

Les exemples fournis dans ce guide utilisent le modèle Llama 3.3 70b.

Consultez notre Catalogue pour découvrir quels modèles sont compatibles avec les sorties structurées.

Les formats de sortie gérés par chaque modèle sont définis dans la section Response Format :

Model Specs

Prérequis

Les exemples fournis dans ce guide peuvent être utilisés avec l'un des environnements suivants :

Python

Un environnement Python avec le client openai et la bibliothèque pydantic installés.

pip install openai pydantic

Javascript

Un environnement Node.js avec la bibliothèque request. Request peut être installée via NPM :

npm install request

Curl

Un terminal standard, avec curl installé sur le système.

Authentification et limitation du débit

La plupart des exemples fournis dans ce guide utilisent une authentification anonyme, ce qui simplifie leur usage mais peut entraîner des limitations de débit (rate limiting). Si vous souhaitez activer l'authentification avec votre propre token, indiquez simplement votre clé API dans les requêtes.

Suivez les instructions du guide AI Endpoints - Premiers pas pour plus d'informations sur l'authentification.

En pratique

Le paramètre response_format de l'API Chat Completion nous permet d'activer et de configurer les fonctionnalités de sorties structurées.

Les modèles prenant en charge les sorties structurées peuvent gérer les trois modes suivants :

  • {"type": "text"} Le format textuel par défaut. C'est équivalent à ne spécifier aucun response_format.

  • {"type": "json_object"} Le format JSON object est un format legacy introduit avec la première itération des sorties structurées. Ce mode est non déterministe et permet au modèle de produire un objet JSON sans validation stricte.

  • {"type": "json_schema", "json_schema": .. } JSON schema est un outil très puissant utilisé pour spécifier et valider une structure de données JSON. Ce type de response_format, le plus récent, nous permet d'imposer des formats de sortie personnalisés dans les réponses des LLM à l'aide de cette spécification, et d'assurer cohérence et interopérabilité avec une variété de plateformes et d'applications.

Lors de l'utilisation du mode JSON schema, les sorties sont déterministes et respecteront toujours le schéma spécifié.

Nous recommandons d'utiliser JSON schema plutôt que JSON object dès que possible.

JSON schema

Les exemples de code suivants fournissent un exemple simple de spécification d'un JSON schema, à l'aide du paramètre response_format.

Python
Curl
Javascript

Pour cet exemple, nous pouvons utiliser la bibliothèque Python openai, combinée à pydantic pour une gestion avancée du JSON schema.

from pydantic import BaseModel
import openai
import os

# Define the prompts
messages = [
    { "content": "You are a helpful assistant that help users rank different things. You always answer in JSON format.", "role": "system" },
    { "content": "What are the top 3 most popular programming languages ?", "role": "user" }
]

# Define the data model
class Language(BaseModel):
    name: str
    website: str
    ranking: int

class LanguageRankings(BaseModel):
    languages: list[Language]

# Initialise the client
api_key = os.environ['AI_ENDPOINT_API_KEY'] # Assuming your API key is available in this environment variable (export AI_ENDPOINT_API_KEY='your_api_key')
openai_client = openai.OpenAI(
    base_url='https://oai.endpoints.kepler.ai.cloud.ovh.net/v1',
    api_key=api_key
)

# Optionally, print the json schema infered from the pydantic model
print(f'JSON schema: {LanguageRankings.model_json_schema()}')

# Run the query
response = openai_client.beta.chat.completions.parse(
    model='Meta-Llama-3_3-70B-Instruct',
    messages=messages,
    response_format=LanguageRankings,
    temperature=0 # Ensure deterministic output for this guide's purpose
)

# Print the parsed response
language_rankings = response.choices[0].message.parsed
for language in language_rankings.languages:
    print(f"{language.name} is the n°{language.ranking} language ({language.website})")

Sortie :

JSON schema: {'$defs': {'Language': {'properties': {'name': {'title': 'Name', 'type': 'string'}, 'website': {'title': 'Website', 'type': 'string'}, 'ranking': {'title': 'Ranking', 'type': 'integer'}}, 'required': ['name', 'website', 'ranking'], 'title': 'Language', 'type': 'object'}}, 'properties': {'languages': {'items': {'$ref': '#/$defs/Language'}, 'title': 'Languages', 'type': 'array'}}, 'required': ['languages'], 'title': 'LanguageRankings', 'type': 'object'}
JavaScript is the n°1 language (https://www.javascript.com/)
Python is the n°2 language (https://www.python.org/)
Java is the n°3 language (https://www.java.com/)

NOTE : cet exemple utilise openai_client.beta.chat.completions.parse pour tirer parti de l'analyse automatique avec pydantic, mais il est également possible d'utiliser openai_client.chat.completions.create, en utilisant le paramètre response_format et en spécifiant le JSON schema manuellement.

JSON object

Les exemples de code suivants fournissent un exemple simple d'utilisation du mode legacy JSON object, à l'aide du paramètre response_format. Notez qu'avec le mode JSON object, il n'est pas possible de spécifier explicitement le schéma de la sortie.

Python
Curl
Javascript
import json
import openai
import os

# Define the prompts
messages = [
    { "content": "You are a helpful assistant that help users rank different things. You always answer in JSON format.", "role": "system" },
    { "content": "What are the top 3 most popular programming languages ?", "role": "user" }
]

# Initialise the client
api_key = os.environ['AI_ENDPOINT_API_KEY'] # Assuming your API key is available in this environment variable (export AI_ENDPOINT_API_KEY='your_api_key')
openai_client = openai.OpenAI(
    base_url='https://oai.endpoints.kepler.ai.cloud.ovh.net/v1',
    api_key=api_key
)

# Run the query
response = openai_client.chat.completions.create(
    model='Meta-Llama-3_3-70B-Instruct',
    messages=messages,
    response_format={
        "type": "json_object",
    },
    temperature=0 # Ensure deterministic output for this guide's purpose
)

# Print the response
output = json.loads(response.choices[0].message.content)
print(json.dumps(output, indent=2))

Sortie :

{
  "rank": [
    {
      "position": 1,
      "language": "JavaScript",
      "popularity": "94.5%"
    },
    {
      "position": 2,
      "language": "HTML/CSS",
      "popularity": "83.6%"
    },
    {
      "position": 3,
      "language": "Python",
      "popularity": "78.9%"
    }
  ]
}

Astuces et bonnes pratiques

Cette section contient des astuces supplémentaires qui peuvent améliorer la performance des requêtes de sorties structurées.

Streaming

Tous les types de response_format sont compatibles avec le streaming. Pour activer le streaming, utilisez simplement "streaming": true dans le corps de votre requête et traitez le flux en conséquence.

Exemple avec python :

from pydantic import BaseModel
import openai
import os

# Define the prompts
messages = [
    { "content": "You are a helpful assistant that help users rank different things. You always answer in JSON format.", "role": "system" },
    { "content": "What are the top 3 most popular programming languages ?", "role": "user" }
]

# Define the data model
class Language(BaseModel):
    name: str
    website: str
    ranking: int

class LanguageRankings(BaseModel):
    languages: list[Language]

# Initialise the client
api_key = os.environ['AI_ENDPOINT_API_KEY'] # Assuming your API key is available in this environment variable (export AI_ENDPOINT_API_KEY='your_api_key')
openai_client = openai.OpenAI(
    base_url='https://oai.endpoints.kepler.ai.cloud.ovh.net/v1',
    api_key=api_key
)

# Run the query
with openai_client.beta.chat.completions.stream(
    model='Meta-Llama-3_3-70B-Instruct',
    messages=messages,
    response_format=LanguageRankings,
    temperature=0,
) as stream:
    for event in stream:
        if event.type == "response.refusal.delta":
            print(event.delta, end="")
        elif event.type == "response.output_text.delta":
            print(event.delta, end="")
        elif event.type == "response.error":
            print(event.error, end="")
        elif event.type == "response.completed":
            print("Completed")
        elif event.type == "chunk":
            if len(event.chunk.choices):
                print(event.chunk.choices[0].delta.content, end="")

    response = stream.get_final_completion()

# Print the parsed response
language_rankings = response.choices[0].message.parsed
for language in language_rankings.languages:
    print(f"{language.name} is the n°{language.ranking} language ({language.website})")

Réponse en sortie du streaming :

{"languages": [
    {"name": "JavaScript", "ranking": 1, "website": "https://www.javascript.com/"},
    {"name": "Python", "ranking": 2, "website": "https://www.python.org/"},
    {"name": "Java", "ranking": 3, "website": "https://www.java.com/"}
]}
JavaScript is the n°1 language (https://www.javascript.com/)
Python is the n°2 language (https://www.python.org/)
Java is the n°3 language (https://www.java.com/)

Définition du schéma

Quelques considérations sur la définition du JSON schema :

  • Les sorties structurées prennent actuellement en charge un sous-ensemble de la spécification JSON schema. Certaines fonctionnalités peuvent ne pas être compatibles.
  • Les modèles génèrent la sortie en suivant l'ordre alphabétique des clés du JSON schema. Il peut être utile de renommer vos champs pour imposer un ordre spécifique lors de la génération.
  • Pour éviter toute divergence, nous recommandons de définir les propriétés additionnelles sur false et de définir explicitement les champs requis.

N'hésitez pas à expérimenter différentes variations de vos JSON schemas pour obtenir les meilleures performances !

Prompting et paramètres additionnels

Quelques considérations supplémentaires concernant les prompts et les paramètres du modèle :

  • Bien que response_format puisse être utilisé pour activer les sorties structurées, les modèles ont généralement de meilleures performances lorsqu'on leur demande de produire des sorties JSON directement dans le prompt (champ messages).
  • La plupart des modèles ont tendance à mieux fonctionner avec une température plus basse pour les sorties structurées.
  • Certains fournisseurs de modèles peuvent recommander des system prompts et paramètres spécifiques pour les sorties structurées et l'appel de fonctions. N'hésitez pas à consulter les pages des modèles pour approfondir leurs spécificités (exemple pour Llama 3.3 sur HuggingFace).

Conclusion

Dans ce guide, nous avons expliqué comment utiliser les sorties structurées avec les modèles AI Endpoints. Nous avons fourni un aperçu complet de cette fonctionnalité qui peut vous aider à parfaire l'intégration du LLM dans votre propre application.

Aller plus loin

Parcourez la documentation AI Endpoints complète pour mieux comprendre les concepts principaux et démarrer.

Pour découvrir comment créer des applications complètes et performantes avec AI Endpoints, explorez nos guides AI Endpoints dédiés.

Pour une formation ou une assistance technique sur la mise en œuvre de nos solutions, contactez votre commercial ou consultez la page Professional Services pour obtenir un devis et faire analyser votre projet par nos experts.

Votre avis nous intéresse !

N’hésitez pas à nous faire part de vos questions, retours et suggestions pour améliorer le service :

Cette page vous a-t-elle aidé ?