Documentation - mise à jour des spécifications des API

[mborne]

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]

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

[RubenGres]

Parfaitement résumé!

[mborne]

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]

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 :

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]

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]

Le chaînage transparent des appels est bien possible :

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]

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