Documentation - mise à jour des spécifications des API

mborne commented 5 months ago

Contexte

Les LLM tels ChatGPT sont désormais capables de générer du code et d'appeler des API en s'appuyant sur les spécifications OpenAPI des API en ligne. Les spécifications APICARTO actuelles rédigées pour la mise en oeuvre d'une documentation interactive avec Swagger posent problème pour une exploitation avec ChatGPT.

Proposition

Pour chaque module :

Convertir les spécifications swagger: 2.0 en spécification openapi: 3.1.0

Version à valider avec NORMA IGN ou en inspectant les spécifications des nouvelles OGC API.

Ne plus s'appuyer sur des schémas externes (par exemple pour les schémas GeoJSON décrivant Geometry, Point,...)

La résolution était possible avec swagger: 2.0. Elle n'est pas disponible en openapi: 3.0 et n'est pas supportée par certains outils tels ChatGPT.

Définir un operationId pour chaque endpoint

Certains outils tels ChatGPT s'en servent pour identifier des actions

Remarques

Tester la génération de code et l'intégration sous forme d'actions avec des LLM tels ChatGPT sur la base des spécifications semble être une approche intéressante pour améliorer et valider les spécifications OpenAPI.
Il n'est pas garanti que ces améliorations soient suffisantes pour répondre à des cas d'utilisation avancés impliquant plusieurs appels d'API

Doute sur la capacité de ChatGPT à chaîner des appels pour répondre à des questions du type "Quelles est la superficie de la parcelle située à l'adresse suivante : ..." => (GéoCodage d'adresse -(lon,lat)-> Récupération de la parcelle -> extraction de la superficie

Idée de "services chaînés" à envisager le cas échéant?

mborne commented 5 months ago

ping @RubenGres : tu peux me confirmer que j'ai bien compris les échanges?

RubenGres commented 5 months ago

Parfaitement résumé!

mborne commented 4 months ago

Quelques compléments pour utilisation dans ChatGPT :

Il est possible de charger un seul schéma OpenAPI par domaine (ex : apicarto.ign.fr)

@RubenGres a fait une PR avec un seul schéma

Il est possible de charger au maximum de 30 endpoints par domaine côté ChatGPT
La présence des géométries complexes dans les réponses (ex : polygones de parcelles cadastrales apporte peu à ChatGPT et pose des problèmes de taille de réponse)

Il faudrait éventuellement faire un peu de logique sur l'User-Agent=ChatGPT-User ( https://platform.openai.com/docs/plugins/bot )

mborne commented 4 months ago

Les réponses volumineuses ne sont effectivement pas acceptée en contexte de ChatGPT. Une erreur ResponseTooLargeError est effectivement présente quand les réponses d'API sont trop lourdes pour être exploitées :

Capture d’écran du 2024-07-26 15-17-07

Ceci renforce l'idée qu'il faut adapter les API avec un mode dédié par exemple (sans géométrie, limite basse du nombre de réponse,...)

mborne commented 4 months ago

Nous allons tâcher de déterminer les critères pour faire des API "ChatGPT friendly" avec quelques tests complémentaires dans un premier temps mais il est à craindre que des API spécifiques soient à développer pour en optimiser l'utilisation.

mborne commented 4 months ago

Le chaînage transparent des appels est bien possible :

Capture d’écran du 2024-07-26 17-02-58

Par contre, dès que des géométries sont présentes dans les réponses, nous sommes obligés de forcer l'utilisation d'une limites basses (@RubenGres j'adapte en ce sens le schéma pour forcer les appels avec _limit=10 (max) quand c'est possible.

RubenGres commented 3 months ago

Super travail, les résultats sont super encourageants!

100% pour limiter les géométries dans les réponses, à priori on reste ici sur du traitement "texte uniquement", tant que l'on a pas de SIG rattaché les géométries nous encombrent plus qu'autre chose

IGNF / apicarto