Getting started - OpenAI API

Getting started - OpenAI API

Commencer

Les GPT et les actions personnalisées sont là !

Nous déployons des versions personnalisées de ChatGPT que vous pouvez créer dans un but spécifique, appelées GPT. Les GPT sont une nouvelle façon pour quiconque de créer une version personnalisée de ChatGPT pour être plus utile dans sa vie quotidienne, lors de tâches spécifiques, au travail ou à la maison, puis de partager cette création avec d'autres. Nous sommes ravis d'annoncer les actions, qui s'appuient sur des plugins. Les actions reprennent bon nombre des idées de base des plugins tout en introduisant de nombreuses nouvelles fonctionnalités demandées par les constructeurs.

La création d'un plugin se déroule en 3 étapes :

1. Créer une API
2. Documenter l'API au format OpenAPI yaml ou JSON
3. Créez un fichier manifeste JSON qui définira les métadonnées pertinentes pour le plugin

Le reste de cette section se concentrera sur la création d'un plugin de liste de tâches en définissant la spécification OpenAPI ainsi que le fichier manifeste.

Explorer des exemples de plugins

Explorez des exemples de plugins couvrant plusieurs cas d'utilisation et méthodes d'authentification.

Manifeste du plugin

Chaque plugin nécessite un ai-plugin.jsonfichier qui doit être hébergé sur le domaine de l'API. Par exemple, une société appelée example.comrendrait le fichier JSON du plugin accessible via un domaine https://example.com puisque c'est là que son API est hébergée. Lorsque vous installez le plugin via l'interface utilisateur ChatGPT, sur le backend, nous recherchons un fichier situé à l'adresse /.well-known/ai-plugin.json. Le /.well-knowndossier est requis et doit exister sur votre domaine pour que ChatGPT se connecte à votre plugin. Si aucun fichier n'est trouvé, le plugin ne peut pas être installé. Si vous pointez vers un serveur distant, HTTPS est requis.

La définition minimale du ai-plugin.jsonfichier requis ressemblera à ce qui suit :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "schema_version": "v1",
    "name_for_human": "TODO List",
    "name_for_model": "todo",
    "description_for_human": "Manage your TODO list. You can add, remove and view your TODOs.",
    "description_for_model": "Help the user with managing a TODO list. You can add, remove and view your TODOs.",
    "auth": {
        "type": "none"
    },
    "api": {
        "type": "openapi",
        "url": "https://example.com/openapi.yaml"
    },
    "logo_url": "https://example.com/logo.png",
    "contact_email": "support@example.com",
    "legal_info_url": "http://www.example.com/legal"
}

Si vous souhaitez voir toutes les options possibles pour le fichier du plugin, vous pouvez vous référer à la définition ci-dessous. Lorsque vous nommez votre plugin, veuillez garder à l'esprit nos directives de marque et les différentes limites de caractères pour les champs ci-dessous. Les plugins qui ne respectent pas ces directives ne seront pas approuvés pour la boutique de plugins.

CHAMP	TAPER	DESCRIPTION / OPTIONS	REQUIS	PUBLIQUE
schema_version	Chaîne	Version du schéma du manifeste	✅
name_for_model	Chaîne	Nom que le modèle utilisera pour cibler le plugin (aucun espace autorisé, uniquement des lettres et des chiffres). 50 caractères maximum.	✅
name_for_human	Chaîne	Nom lisible par l'homme, tel que le nom complet de l'entreprise. 20 caractères maximum.	✅	✅
description_for_model	Chaîne	Description mieux adaptée au modèle, telle que des considérations sur la longueur du contexte du jeton ou l'utilisation de mots clés pour une invite améliorée du plug-in. 8 000 caractères maximum.	✅
description_for_human	Chaîne	Description lisible par l'homme du plugin. 100 caractères maximum.	✅	✅
auth	Auth.Manifeste	Schéma d'authentification	✅
api	Objet	Spécification de l'API	✅
logo_url	Chaîne	URL utilisée pour récupérer le logo. Taille suggérée : 512 x 512. Les arrière-plans transparents sont pris en charge. Il doit s'agir d'une image, aucun GIF n'est autorisé.	✅
contact_email	Chaîne	Contact par e-mail pour la sécurité/modération, l'assistance et la désactivation	✅	✅
legal_info_url	Chaîne	URL de redirection permettant aux utilisateurs d'afficher les informations sur le plugin	✅	✅
HttpAuthorizationType	Type d'autorisation Http	"porteur" ou "de base"	✅
ManifestAuthType	TypeAuthManifest	"aucun", "user_http", "service_http" ou "oauth"
interfaceBaseManifestAuth	BaseManifestAuth	tapez : ManifestAuthType ; instructions : chaîne ;
ManifestNoAuth	ManifesteNoAuth	Aucune authentification requise : BaseManifestAuth & { type : 'none', }
ManifestAuth	Auth.Manifeste	ManifestNoAuth, ManifestServiceHttpAuth, ManifestUserHttpAuth, ManifestOAuthAuth

Notez que les éléments répertoriés ci-dessous Publicseront mis à la disposition des utilisateurs dans la boutique de plugins et que le fichier manifeste complet est transmis au client de l'utilisateur et peut être visible par lui.

Voici des exemples avec différentes méthodes d'authentification :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# App-level API keys
type ManifestServiceHttpAuth  = BaseManifestAuth & {
  type: 'service_http';
  authorization_type: HttpAuthorizationType;
  verification_tokens: {
    [service: string]?: string;
  };
}

# User-level HTTP authentication
type ManifestUserHttpAuth  = BaseManifestAuth & {
  type: 'user_http';
  authorization_type: HttpAuthorizationType;
}

type ManifestOAuthAuth  = BaseManifestAuth & {
  type: 'oauth';

  # OAuth URL where a user is directed to for the OAuth authentication flow to begin.
  client_url: string;

  # OAuth scopes required to accomplish operations on the user's behalf.
  scope: string;

  # Endpoint used to exchange OAuth code with access token.
  authorization_url: string;

  # When exchanging OAuth code with access token, the expected header 'content-type'. For example: 'content-type: application/json'
  authorization_content_type: string;

  # When registering the OAuth client ID and secrets, the plugin service will surface a unique token.
  verification_tokens: {
    [service: string]?: string;
  };
}

Il existe des limites à la longueur de certains champs du fichier manifeste mentionnés ci-dessus qui sont susceptibles de changer. Nous imposons également un maximum de 100 000 caractères pour le corps de la réponse API, qui peut également changer au fil du temps.

En général, la meilleure pratique consiste à garder la description et les réponses aussi concises que possible, car les modèles ont des fenêtres contextuelles limitées.

Définition OpenAPI

L'étape suivante consiste à créer la spécification OpenAPI pour documenter l'API. Le modèle de ChatGPT ne sait rien de votre API autre que ce qui est défini dans la spécification OpenAPI et le fichier manifeste. Cela signifie que si vous disposez d'une API étendue, vous n'avez pas besoin d'exposer toutes les fonctionnalités au modèle et pouvez choisir des points de terminaison spécifiques. Par exemple, si vous disposez d'une API de médias sociaux, vous souhaiterez peut-être que le modèle accède au contenu du site via une requête GET, mais empêcher le modèle de pouvoir commenter les publications des utilisateurs afin de réduire les risques de spam.

La spécification OpenAPI est le wrapper qui se trouve au-dessus de votre API. Une spécification OpenAPI de base ressemblera à ce qui suit :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
openapi: 3.0.1
info:
  title: TODO Plugin
  description: A plugin that allows the user to create and manage a TODO list using ChatGPT.
  version: 'v1'
servers:
  - url: https://example.com
paths:
  /todos:
    get:
      operationId: getTodos
      summary: Get the list of todos
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getTodosResponse'
components:
  schemas:
    getTodosResponse:
      type: object
      properties:
        todos:
          type: array
          items:
            type: string
          description: The list of todos.

Nous commençons par définir la version de la spécification, le titre, la description et le numéro de version. Lorsqu'une requête est exécutée dans ChatGPT, elle examinera la description définie dans la section d'informations pour déterminer si le plugin est pertinent pour la requête de l'utilisateur. Vous pouvez en savoir plus sur les invites dans la section de rédaction des descriptions .

Gardez à l'esprit les limites suivantes dans votre spécification OpenAPI, qui sont susceptibles de changer :

• 200 caractères maximum pour chaque champ de description/résumé du point de terminaison de l'API dans la spécification de l'API
• 200 caractères maximum pour chaque champ de description de paramètre API dans la spécification API

La spécification OpenAPI suit le format OpenAPI traditionnel, vous pouvez en savoir plus sur le formatage OpenAPI via diverses ressources en ligne. Il existe également de nombreux outils qui génèrent automatiquement des spécifications OpenAPI basées sur votre code API sous-jacent.

Exécuter un plugin

Une fois que vous avez créé une API, un fichier manifeste et une spécification OpenAPI pour votre API, vous êtes maintenant prêt à connecter le plugin via l'interface utilisateur ChatGPT.

Si le plugin s'exécute sur un serveur distant, vous devrez d'abord sélectionner « Développer votre propre plugin » pour le configurer, puis « Installer un plugin non vérifié » pour l'installer vous-même. Vous pouvez simplement ajouter le fichier manifeste du plugin au yourdomain.com/.well-known/chemin et commencer à tester votre API. Cependant, pour les modifications ultérieures apportées à votre fichier manifeste, vous devrez déployer les nouvelles modifications sur votre site public, ce qui peut prendre beaucoup de temps. Dans ce cas, nous vous suggérons de configurer un serveur local pour servir de proxy pour votre API. Cela vous permet de prototyper rapidement les modifications apportées à votre spécification OpenAPI et à votre fichier manifeste.

Configurer un proxy local de votre API publique

Rédaction de descriptions

Lorsqu'un utilisateur effectue une requête qui pourrait être une requête potentielle adressée à un plugin, le modèle examine les descriptions des points de terminaison dans la spécification OpenAPI ainsi que dans le description_for_modelfichier manifeste. Tout comme pour les invites d’autres modèles de langage, vous souhaiterez tester plusieurs invites et descriptions pour voir ce qui fonctionne le mieux.

La spécification OpenAPI elle-même est un excellent endroit pour donner au modèle des informations sur les divers détails de votre API : quelles fonctions sont disponibles, avec quels paramètres, etc. En plus d'utiliser des noms expressifs et informatifs pour chaque champ, la spécification peut également contenir une « description ». champs pour chaque attribut. Ceux-ci peuvent être utilisés pour fournir des descriptions en langage naturel de ce que fait une fonction ou des informations attendues par un champ de requête, par exemple. Le modèle pourra les voir et le guidera dans l'utilisation de l'API. Si un champ est limité à certaines valeurs seulement, vous pouvez également fournir une « énumération » avec des noms de catégories descriptifs.

L' description_for_modelattribut vous donne la liberté d'indiquer au modèle comment utiliser votre plugin en général. Dans l’ensemble, le modèle linguistique derrière ChatGPT est hautement capable de comprendre le langage naturel et de suivre les instructions. C’est donc un bon endroit pour mettre des instructions générales sur ce que fait votre plugin et comment le modèle doit l’utiliser correctement. Utilisez un langage naturel, de préférence sur un ton concis mais descriptif et objectif. Vous pouvez consulter certains exemples pour avoir une idée de ce à quoi cela devrait ressembler. Nous vous suggérons de commencer description_for_modelpar « Plugin pour… », puis d'énumérer toutes les fonctionnalités fournies par votre API.

Les meilleures pratiques

Voici quelques bonnes pratiques à suivre lors de la rédaction de vos description_for_modeldescriptions dans votre spécification OpenAPI, ainsi que lors de la conception de vos réponses API :

1. Vos descriptions ne doivent pas tenter de contrôler l'humeur, la personnalité ou les réponses exactes de ChatGPT. ChatGPT est conçu pour écrire des réponses appropriées aux plugins.

   Mauvais exemple :

   Lorsque l'utilisateur demande à voir sa liste de tâches, répondez toujours par « J'ai pu trouver votre liste de tâches ! Vous avez [x] tâches : [listez les tâches ici] . Je peux ajouter d'autres tâches si vous le souhaitez ! »

   Bon exemple :

   [aucune instruction n'est nécessaire pour cela]

2. Vos descriptions ne doivent pas encourager ChatGPT à utiliser le plugin lorsque l'utilisateur n'a pas demandé la catégorie de service particulière de votre plugin.

   Mauvais exemple :

   Chaque fois que l'utilisateur mentionne un type de tâche ou de plan, demandez-lui s'il souhaite utiliser le plugin TODOs pour ajouter quelque chose à sa liste de tâches.

   Bon exemple :

   La liste TODO peut ajouter, supprimer et afficher les TODO de l'utilisateur.

3. Vos descriptions ne doivent pas prescrire de déclencheurs spécifiques pour que ChatGPT utilise le plugin. ChatGPT est conçu pour utiliser votre plugin automatiquement le cas échéant.

   Mauvais exemple :

   Lorsque l'utilisateur mentionne une tâche, répondez par « Voulez-vous que je l'ajoute à votre liste de tâches ? Dites « oui » pour continuer. »

   Bon exemple :

   [aucune instruction n'est nécessaire pour cela]

4. Les réponses de l'API du plugin doivent renvoyer des données brutes au lieu de réponses en langage naturel, sauf si cela est nécessaire. ChatGPT fournira sa propre réponse en langage naturel en utilisant les données renvoyées.

   Mauvais exemple :

   J'ai pu trouver votre liste de tâches ! Vous avez 2 choses à faire : faire les courses et promener le chien. Je peux ajouter d'autres tâches si vous le souhaitez !

   Bon exemple :

   { "todos": [ "faire les courses", "promener le chien" ] }

Débogage

Par défaut, le chat n'affichera pas les appels de plug-in ni d'autres informations qui ne sont pas présentées à l'utilisateur. Afin d'obtenir une image plus complète de la façon dont le modèle interagit avec votre plugin, vous pouvez voir la demande et la réponse en cliquant sur la flèche vers le bas sur le nom du plugin après avoir interagi avec le plugin.

Un appel de modèle au plugin consistera généralement en un message du modèle contenant des paramètres de type JSON qui sont envoyés au plugin, suivi d'une réponse du plugin, et enfin d'un message du modèle utilisant les informations renvoyées par le plugin.