> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lighton.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Obtenir une Génération de Sortie Structurée

> Améliorez vos applications avec des sorties structurées de haute qualité en utilisant les paramètres dédiés de notre API. Cette fonctionnalité est essentielle pour créer ou analyser des données structurées, en garantissant qu'elles respectent des règles de format et de validation spécifiques.

<Info>
  À partir de la version **Victorious Vicuna** (janvier 2026) et suivantes, l'utilisation de l'[API Agent](/fr/developer-resources/chat-and-ai-models/agent-api)
  est la méthode préférée pour accomplir cette tâche. Veuillez vous référer à la section [Demander une sortie structurée](/fr/developer-resources/chat-and-ai-models/agent-api#demander-une-sortie-structuree) de cette page.
</Info>

## Paramètres supportés

Plusieurs paramètres sont disponibles pour mieux répondre à vos besoins, qui doivent être ajoutés dans votre charge utile de requête :

* `guided_choice` : la sortie sera exactement l'un des choix proposés.
* `guided_regex` : la sortie suivra le modèle regex.
* `guided_json` : la sortie suivra le schéma JSON.

Les sections suivantes vous donneront des exemples sur la façon d'utiliser chacun de ces paramètres.

## Choix Guidés

Utilisez le paramètre `guided_choice` pour forcer un modèle à choisir l'une des options que vous définissez.\
Voici un exemple ci-dessous.

<Accordion title="Exemple de Choix Guidés" icon="code" iconType="regular">
  ```python theme={null}
  import requests
  import os

  paradigm_api_key = os.environ.get("PARADIGM_API_KEY", None)

  url = "https://paradigm.lighton.ai/api/v2/chat/completions"
  headers = {
      "Authorization": f"Bearer {paradigm_api_key}",
      "Content-Type": "application/json",
  }
  payload = {
      "model": "alfred-ft5",
      "messages": [
          {"role": "user", "content": "Classifiez ce sentiment : Alfred est merveilleux !"}
      ],
      "guided_choice": ["positif", "négatif"]
  }
  response = requests.post(url, json=payload, headers=headers)
  data = response.json()

  print(data["choices"][0]["message"]["content"])
  ```

  Pour cet exemple, la sortie devrait afficher le texte `positif`.
</Accordion>

## Regex Guidée

Utilisez le paramètre guided\_regex pour générer du texte suivant un modèle regex.\
Voici un exemple ci-dessous.

<Accordion title="Exemple de Regex Guidée" icon="code" iconType="regular">
  ```python theme={null}
  import requests
  import os

  paradigm_api_key = os.environ.get("PARADIGM_API_KEY", None)

  url = "https://paradigm.lighton.ai/api/v2/chat/completions"
  headers = {
      "Authorization": f"Bearer {paradigm_api_key}",
      "Content-Type": "application/json",
  }
  payload = {
      "model": "alfred-ft5",
      "messages": [
          {
              "role": "user",
              "content": "Générez un exemple d'adresse email pour Alan Turing, qui travaille chez Enigma. Terminez par .com. Exemple de résultat : alan.turing@enigma.com\n"
          }
      ],
      "guided_regex": r"\w+@\w+\.com",
  }
  response = requests.post(url, json=payload, headers=headers)
  data = response.json()

  print(data["choices"][0]["message"]["content"])
  ```

  La sortie devrait alors suggérer une adresse email suivant le modèle regex comme `alan_turing@enigma.com` par exemple.
</Accordion>

## <Tooltip tip="">JSON Guidé</Tooltip>

<Tip>
  **Intégrité et Validation des Données**

  Le schéma JSON maintient une haute qualité des données en appliquant une structure prédéfinie et des règles de validation, minimisant le besoin de vérifications supplémentaires.
</Tip>

### Créez votre Schéma JSON

Vous avez 2 possibilités pour créer votre schéma JSON :

* Créer manuellement un [schéma JSON](https://json-schema.org/) : vous pouvez trouver un [guide étape par étape ici](https://json-schema.org/learn/getting-started-step-by-step).
* Définir un [modèle Pydantic](https://docs.pydantic.dev/latest/) et en extraire le schéma JSON.

### Le Rôle des Séquences d'Arrêt

Les séquences d'arrêt sont essentielles dans les tâches de données structurées, marquant la fin des réponses du modèle pour maintenir les sorties dans la structure de votre schéma.

<Tip>
  **Séquence d'Arrêt Obligatoire**

  Utilisez toujours une séquence d'arrêt appropriée d'un modèle (par défaut pour `mistral` c'est `stop=["</s>"]`) pour garantir une terminaison précise de la sortie du modèle, en l'alignant avec votre schéma JSON.
</Tip>

### Exemple de code

Les exemples suivants montrent comment utiliser le paramètre `guided_json` avec un schéma JSON explicite ainsi qu'avec un modèle Pydantic.

<AccordionGroup>
  <Accordion title="JSON Guidé : Schéma Explicite" icon="code">
    ```python theme={null}
    import requests
    import json
    import os

    # Récupérer la clé API Paradigm depuis l'environnement
    paradigm_api_key = os.environ.get("PARADIGM_API_KEY", None)

    # Définir le schéma JSON pour la génération de données
    json_schema = """{
      "$defs": {
        "CarType": {
          "enum": [
            "berline",
            "SUV",
            "Camion",
            "Coupé"
          ],
          "title": "CarType",
          "type": "string"
        }
      },
      "properties": {
        "marque": {
          "title": "Marque",
          "type": "string"
        },
        "modele": {
          "title": "Modèle",
          "type": "string"
        },
        "type_voiture": {
          "$ref": "#/$defs/CarType"
        }
      },
      "required": [
        "marque",
        "modele",
        "type_voiture"
      ],
      "title": "DescriptionVoiture",
      "type": "object"
    }"""

    url = "https://paradigm.lighton.ai/api/v2/chat/completions"
    headers = {
        "Authorization": f"Bearer {paradigm_api_key}",
        "Content-Type": "application/json",
    }
    payload = {
        "model": "alfred-ft5",
        "messages": [
            {
                "role": "user",
                "content": "Générez un JSON avec la marque, le modèle et le type_voiture de la voiture la plus emblématique des années 80",
            }
        ],
        "guided_json": json_schema
    }
    response = requests.post(url, json=payload, headers=headers)
    response_data = response.json()

    print(json.dumps(json.loads(response_data["choices"][0]["message"]["content"]), indent=2))
    ```
  </Accordion>

  <Accordion title="JSON Guidé : Modèle Pydantic" icon="code" iconType="regular">
    ```python theme={null}
    from pydantic import BaseModel
    from enum import Enum
    import requests
    import json
    import os

    paradigm_api_key = os.environ.get("PARADIGM_API_KEY", None)

    class TypeVoiture(str, Enum):
        berline = "berline"
        suv = "SUV"
        camion = "Camion"
        coupe = "Coupé"

    class DescriptionVoiture(BaseModel):
        marque: str
        modele: str
        type_voiture: TypeVoiture

    json_schema = DescriptionVoiture.model_json_schema()

    url = "https://paradigm.lighton.ai/api/v2/chat/completions"
    headers = {
        "Authorization": f"Bearer {paradigm_api_key}",
        "Content-Type": "application/json",
    }
    payload = {
        "model": "alfred-ft5",
        "messages": [
            {
                "role": "user",
                "content": "Générez un JSON avec la marque, le modèle et le type_voiture de la voiture la plus emblématique des années 80",
            }
        ],
        "guided_json": json_schema
    }
    response = requests.post(url, json=payload, headers=headers)
    response_data = response.json()

    print(json.dumps(json.loads(response_data["choices"][0]["message"]["content"]), indent=2))
    ```

    Voici un exemple de sortie que vous pouvez obtenir :

    ```json theme={null}
    {
      "marque": "Delorean",
      "modele": "DMC-12",
      "type_voiture": "berline"
    }
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  **Exploiter la Correspondance de Modèles**

  Utilisez l'attribut `pattern` dans le schéma JSON pour définir des expressions régulières (regex) pour faire correspondre des formats de texte spécifiques. La regex `(.+)` est particulièrement utile pour capturer des segments de texte variés, permettant une extraction précise des informations souhaitées à partir de textes. Cette fonctionnalité est essentielle pour analyser des points de données spécifiques à partir de texte non structuré ou semi-structuré.
</Tip>

## Utilisation des Données Extraites

Exploitez les données structurées de vos extractions pour enrichir les bases de données, les systèmes CRM, ou automatiser les flux de travail, améliorant ainsi l'efficacité opérationnelle.

<Warning>
  **Correspondance de Modèles Précise**

  Vérifiez que les modèles regex de votre schéma JSON s'alignent avec les formats attendus de votre texte. Des incompatibilités peuvent entraîner des erreurs d'extraction de données ou des inexactitudes.

  En utilisant le schéma JSON, vous pouvez transformer efficacement du texte non structuré en données structurées et exploitables, offrant une solution évolutive pour vos besoins de traitement de données.
</Warning>

## Conclusion

Les sorties structurées enrichissent l'expérience utilisateur avec un contenu détaillé et garantissent la cohérence des données à l'échelle de l'application. C'est crucial pour les applications qui dépendent de l'intégrité des données structurées.

<Warning>
  **Pièges Courants**

  * L'exclusion de propriétés de schéma nécessaires peut entraîner des sorties de données partielles.
  * L'imposition de contraintes trop strictes peut restreindre la capacité de l'IA à produire du contenu pertinent.
  * Négliger d'inclure des séquences d'arrêt dans les appels API peut causer des problèmes de traitement.
</Warning>