# Bienvenue sur la documentation IA dans l'État ! Cette documentation est portée par le département "Intelligence Artificielle dans l'État" de la Direction interministérielle du numérique (DINUM). {% hint style="warning" %} Cette documentation est en construction. Merci de signaler à l'équipe ALLiaNCE si vous y trouvez des informations erronées ou des coquilles à l'adresse . Les suggestions à l'équipe et les participations volontaires pour l'améliorer sont également les bienvenues. {% endhint %} ### Le Socle Interministériel d'Intelligence Artificielle Générative ALLiaNCE porte le Socle Interministériel d'Intelligence Artificielle Générative, un socle technique mutualisé qui permet aux administrations d’accéder rapidement et en toute sécurité à des services d’IA générative prêts à l’emploi. Ce socle s’appuie sur des technologies souveraines, hébergées en France sur des infrastructures certifiées SecNumCloud, et offre une gamme complète de fonctionnalités pour répondre aux besoins des ministères, des collectivités et des opérateurs publics. ### Un accélérateur IA pour le service public **ALLiaNCE est un incubateur et une communauté d'acteurs développant des IA publiques**, destinées aux agents de l’État souhaitant intégrer l’IA pour améliorer les service publics pour les citoyens et des citoyennes. Nous nous appuyons sur la stratégie IA de la direction interministérielle du numérique (DINUM) pour proposer des produits numériques innovants et ouverts, à la pointe de la technologie, directement utilisables et adaptables à divers cas d’usage dans la sphère publique. ### À qui s'adresse cette documentation ? Cette documentation est à destination des **équipes produits, des innovateurs et des décideurs publics** que nous accompagnons. ### Comment en savoir plus sur le travail de la DINUM sur l'IA ? Ce site fait office de documentation pratique et technique. Pour plus d'informations sur le travail de la DINUM sur le sujet, retrouvez le site IA dans l'État. IA dans l'État # La Direction interministérielle du numérique (DINUM) ### Présentation de la direction interministérielle du numérique La direction interministérielle du numérique (DINUM) a pour mission d’élaborer la stratégie numérique de l’État et de piloter sa mise en œuvre. Elle exerce aussi les missions de « chief data officer » et de DRH du numérique de l’État. En tant que cheffe de file du numérique de l’État, elle a pour objectif de rendre l’État plus efficace, plus simple et plus souverain grâce au numérique et collabore à cet effet avec l’ensemble des directions numériques des ministères et ses partenaires. #### Les missions La DINUM oriente, soutient et coordonne les actions des administrations de l’État et celles des organismes placés sous sa tutelle, visant à améliorer la qualité, l’efficacité et la fiabilité des services rendus par le système d’information et de communication de l’État. Elle conseille le Premier ministre et les ministres compétents sur la prise en compte du numérique dans les politiques publiques mises en œuvre par les ministères.
En savoir plus # Le département Intelligence Artificielle dans l'État (IAE) Le département Intelligence artificielle dans l'État (IAE) pilote et met en œuvre la stratégie de l’Etat en matière d’intelligence artificielle au service de l’action publique. * Il coordonne et met en œuvre la stratégie IA pour le secteur public, en lien avec le gouvernement, les référents IA dans les ministères, et l’écosystème privé de l’IA ; * Il construit et opère un socle interministériel d’IA générative constitué d’applications, d’outils et d’infrastructures mutualisées pour permettre aux administrations d’intégrer rapidement de l’IA dans leurs applications et process métiers ; * Il accompagne des administrations publiques sur des cas d’usages IA et anime la communauté IA de l’État, à travers l’offre ALLiaNCE. # La communauté "IA dans l'État" Chaque mois, lors des rencontres "IA dans l'État", l'incubateur ALLiaNCE rassemble une communauté d'acteurs de l'IA au sein de l'État. {% hint style="info" %} **Rejoignez dès maintenant l'espace Tchap 🤖**[**IA dans l'État**](https://tchap.gouv.fr/#/room/#IAdansltatSpKrvQH2Odu:agent.dinum.tchap.gouv.fr) **avec tous les salons associés.** {% endhint %} ### "Family & friends" #### Family (les produits accompagnés ou en investigation) Ce sont les services publics incubés chez ALLiaNCE, dont vous allez retrouver des fiches produits sur notre site : Compar’IA, Mon assistant parquet, Recocyber, Dépenses éclairées, L'IA dans démarches simplifiées (Liane) etc. {% embed url="" %} #### **Friends** Ce sont les communautés produits et programmes proches de nous, qui sont aussi des acteurs de l'IA servicielle au sein de l'État : * **Les produits albert-apisés**, soit les équipes qui utilisent la solution Albert-api pour appeler facilement et de manière souveraine des LLMs dans leur service numérique ; * **Les alumnis des hackathons,** notamment les anciens participants du hackathon *GenIA for public good*, qui s'est déroulé pendant le sommet pour l'action sur l'IA français en février 2025 ; * **La communauté datascience interministérielle,** soit les laboratoires data et IA dans les ministères, souvent situés dans les directions du numérique (DNUM). {% embed url="" %} ### Les partenaires institutionnels et privés #### Le réseau institutionnel de l'IA dans l'État Les forums ALLiaNCE réunissent aussi les partenaires institutionnels métiers, Administrateurs Ministériels des Données, des Algorithmes et des Codes sources (AMDACS) et autres acteurs de la donnée publique, qui souhaitent se tenir au courant ou rencontrer l'écosystème de l'IA publique française. #### Les partenaires de la société civile Les partenaires issus de la société civile, désireux de co-construire autour de standards communs les services publics IA de demain sont aussi les bienvenus. À leur intention, un appel à manifestation d'intérêt est actuellement en cours afin qu'ils puissent proposer leur solution. {% embed url="" %} ### 📆 On se retrouve pour les rencontres "IA dans l'État" Participez aux [rencontres](/a-propos/la-communaute/rencontres-alliance) sous format de **Forum Ouvert**, un moment convivial de partage et d’échange pour toute la communauté.\ Dans ce format participatif, chacun peut proposer un sujet, animer un atelier, ou simplement prendre part aux discussions. {% hint style="info" %} 💡 Venez présenter vos avancées, demander un coup de main en co-développement, ou faire une démo de votre produit — tout le monde est le bienvenu ! {% endhint %}
# Rencontres "IA dans l'État" Le rendez-vous des membres de la communauté pour se rencontrer et échanger sur nos sujets communs. **Tous les deux mois**, la communauté "IA dans l'État" se réunit. Il s’agit d’une journée de rencontres et d’échanges en présentiel pour favoriser le partage d’expérience entre les différentes équipes, les différents ministères et les acteurs privés. Entre 60 et 100 membres de la communauté participent à cette matinée : chefs de projets, équipes produit, intrapreneurs et intrapreneuses, curieux, développeurs et développeuses, responsables d’incubateurs ministériels, coachs, designers du secteur public ou privé etc. Les rencontres "IA dans l'État" se déroulent au Lieu de la Transformation Publique sous format de **forum ouvert**. {% hint style="success" %} Un forum ouvert est une méthode de d'événement où l'ordre du jour est défini par les participants eux-mêmes. Contrairement aux réunions traditionnelles, il n'y a pas de programme préétabli. Voici comment cela fonctionne :thumbsup: * **Proposition des sujets :** à l'ouverture de la réunion, chaque participant peut proposer un sujet qu'il souhaite aborder et l'inscrire à l'ordre du jour. * **Flexibilité des sessions :** les participants sont libres de choisir les discussions auxquelles ils veulent assister et peuvent se déplacer entre les différentes sessions en cours. * **Collaboration et échanges :** l'objectif est de favoriser des échanges riches et collaboratifs autour de sujets d'intérêt commun. * **Auto-organisation :** les participants sont responsables de l'animation et de la gestion des discussions qu'ils proposent. {% endhint %} #### **Informations pratiques** **👉 Les informations pratiques (date, heure et lieu) sont communiquées par email ou via le salon tchap de la communauté.** Un formulaire vous sera communiqué pour vous inscrire, dans lequel il est possible de proposer des sujets d'atelier. **Déroulé-type d'une rencontre** RDV de 10h à 13h pour une demi-journée au format *forum ouvert* : l’ordre du jour est défini par les participants. * À **10h**, chaque participant peut, s'il le souhaite présenter un sujet et l'inscrire à l'ordre du jour en l'inscrivant sur le tableau central * De **10h à 12h30, le forum ouvert** * À **12h30** se tient **le *****stand-up***** produit ALLiaNCE**. #### **Quels sujets sont abordés lors des rencontres ?** Tout sujet lié au déploiement de l'IA dans l'Etat est le bienvenu. Le sujet peut être technique, opérationnel, politique, philosophique... Le format est libre aussi : atelier collaboratif, présentation, débat... Les sujets sont proposés sur un tableau blanc affiché dans la salle du forum. Quelques exemples de sujets qui ont été abordés lors des derniers forums : * Comment fine-tuner un modèle pour l'analyse juridique * RETEX sur le déploiement d'un serveur MCP * Atelier sur les gains de productivité liés à l'IA * Office hours Albert API * Office hours Assistant IA * Comparatifs des outils d'analyse juridique. # Entraide communautaire Offrir son soutient à la communauté. Au sein de la communauté ALLiaNCE 🌟, nous partageons l'idée que nos connaissances et nos outils peuvent faire avancer tout le monde. Que vous soyez une équipe ou un membre individuel, voici comment vous pouvez contribuer et bénéficier de l'entraide au sein de notre communauté. ### **🎬 Proposez une démonstration de votre produit** On adore voir ce que vous faites ! Proposez une démonstration de votre produit aux membres du réseau. Voici ce que vous pouvez faire : * Présenter un service peu connu de la communauté. * Recueillir des retours et des conseils en créant des salons Tchap Support et Retext. * Vous entraîner avant une présentation importante. * Poser une question spécifique ou demander de l'aide (financement, appui stratégique, recrutement, etc.). ### **💬 Aidez dans les salons tchap support produits et retex** Il y a plusieurs salons Tchap dans l'espace [**Support/Retex**](https://www.tchap.gouv.fr/#/room/!IwhlHPuHgkYixvZYmY:agent.dinum.tchap.gouv.fr?via=agent.dinum.tchap.gouv.fr) où les utilisateurs posent des questions. Si vous avez du temps et l'expertise, venez répondre aux questions des usagers ! * **Salons Tchap de support produit :** * Salon tchap [Albert Conversation](https://matrix.to/#/!gpLYRJyIwdkcHBGYeC:agent.dinum.tchap.gouv.fr?via=agent.dinum.tchap.gouv.fr\&via=agent.education.tchap.gouv.fr\&via=agent.pm.tchap.gouv.fr) * Salon tchap [Albert API](https://matrix.to/#/!gnHrNiKdlrgzfQqiyN:agent.dinum.tchap.gouv.fr?via=agent.dinum.tchap.gouv.fr\&via=agent.education.tchap.gouv.fr\&via=agent.tchap.gouv.fr) * **Groupes de conversation sur les fonctionnalités IA "betalbert" :** * [RAG](https://matrix.to/#/!rJjGiMiszTopBAGRSk:agent.dinum.tchap.gouv.fr?via=agent.dinum.tchap.gouv.fr\&via=agent.finances.tchap.gouv.fr\&via=agent.education.tchap.gouv.fr) * [Speech to Text](https://tchap.gouv.fr/#/room/!oZPMozJdTtSzJdJTnk:agent.dinum.tchap.gouv.fr?via=agent.dinum.tchap.gouv.fr\&via=agent.interieur.tchap.gouv.fr\&via=agent.finances.tchap.gouv.fr) * [Traduction](https://tchap.gouv.fr/#/room/#betalberteditorialisationtraductionXWWS3OFhhsQ:agent.dinum.tchap.gouv.fr) * [Extraction](https://tchap.gouv.fr/#/room/!bPGCjqgXjNqDmLRvIm:agent.dinum.tchap.gouv.fr?via=agent.dinum.tchap.gouv.fr\&via=agent.finances.tchap.gouv.fr\&via=agent.dev-durable.tchap.gouv.fr) * [Classification](https://tchap.gouv.fr/#/room/!KQcnlkHbFJlhXmZcPy:agent.dinum.tchap.gouv.fr?via=agent.dinum.tchap.gouv.fr\&via=agent.finances.tchap.gouv.fr\&via=agent.justice.tchap.gouv.fr) ### **📰 Documentez vos actualités** On envoie une **newsletter** à toute la communauté une à deux fois par mois. C'est l'occasion parfaite pour partager les dernières actualités de votre produit ou de votre ministère (rapports IA, nouveautés, etc.). \ Vous pouvez aussi partager des infos et vos apprentissages en direct via le salon tchap [**Général ALLiaNCE**](https://tchap.gouv.fr/#/room/!tPzThAoNsAAClYSczG:agent.dinum.tchap.gouv.fr?via=agent.dinum.tchap.gouv.fr\&via=agent.finances.tchap.gouv.fr\&via=agent.justice.tchap.gouv.fr)**.** ### **🎓 Animez des ateliers lors des Rencontres ALLiaNCE** Venez proposer des ateliers lors des rencontres ALLiaNCE, qui ont lieu tous les deux mois en format forum ouvert. Plus d'infos sur le [**Rituel ALLiaNCE**](/a-propos/la-communaute/rencontres-alliance) # Se former en IA Explorer le panorama des formations IA disponibles L’intelligence artificielle transforme les métiers et les services publics. Pour accompagner cette évolution, un large écosystème de formations est mis à disposition des agents de l’État, pour leur permettre de se familiariser avec l’IA, d’en comprendre les usages et de se former selon leurs besoins. De nombreuses formations, proposées par des acteurs publics, sont aujourd’hui disponibles pour permettre aux agents de l’État de se former selon leurs besoins et leurs niveaux. En lien avec ses partenaires, ALLiaNCE contribue à recenser et à mettre en visibilité ces ressources, afin de faciliter l’accès des agents publics aux formations existantes et d’encourager la diffusion d’une culture partagée de l’IA au sein des administrations. ### Des formation pour découvrir l'IA Pour s’initier à l’intelligence artificielle, plusieurs formats courts et accessibles sont proposés : * [Mentor - Initiez-vous à l’intelligence artificielle](https://mentor.gouv.fr/local/catalog/pages/training.php?trainingid=8) (Institut Montaigne / OpenClassRooms, 6h) * [Découvrir les IA génératives](https://mentor.gouv.fr/local/catalog/pages/training.php?trainingid=3189) (DINUM-INRIA, 1h) * [MOOC "L'intelligence artificielle générative et moi"](https://www.fun-mooc.fr/fr/cours/lintelligence-artificielle-generative-et-moi/) (France Université Numérique / CNAM, 5h sur 3 semaines) * [MOOC Objectif IA](https://www.francenum.gouv.fr/formations/objectif-ia-initiez-vous-lintelligence-artificielle) (France Num / OpenClassRooms, 6h) * [Pix Fonction Publique d'État (FPE)](https://campus.numerique.gouv.fr/pix-fonction-publique-d%C3%A9tat/) avec 15 modules incluant l’IA * [Pix+Edu – Intelligence artificielle](https://tube.reseau-canope.fr/w/p/pAAnSdo1Rt4baXrKZyV8Df?playlistPosition=1) (Education nationale, 14 vidéos courtes) : pour les plus jeunes. ### Se perfectionner dans les usages de l'IA Pour aller plus loin et comprendre comment intégrer l’IA dans les projets publics : * [Cursus Intelligence artificielle](https://www.bpifrance-universite.fr/formation/cursus-intelligence-artificielle/) (BPI France Université, 16h) * [Apprivoiser l'intelligence artificielle](https://www.insp.gouv.fr/formation-continue/formations-courtes/offre-interministerielle/apprivoiser-lintelligence) (INSP, 2 jours) * [Cycle supérieur d'intelligence artificielle](https://www.ihemi.fr/formations/cycle-superieur-dintelligence-artificielle) (IHEMI, 5 modules de 3 jours et un voyage d’études) * [Les fondamentaux de l'IA](https://www.fun-mooc.fr/fr/cours/acculturation-a-lintelligence-artificielle-pour-les-collectivite/) (FUN / CNFPT, 6h sur 3 semaines) * [Replay de webinaires du CNFPT sur l'IA](https://www.cnfpt.fr/se-former/decouvrir-offres-thematiques/lintelligence-artificielle/rendez-vous-transition-numerique/inset-dunkerque) * [Formations IGPDE sur l’IA](https://catalogue.igpde.finances.gouv.fr/recherche?controller=search\&orderby=position\&orderway=desc\&search_query=Intelligence+artificielle\&submit_search=) - IGPDE * [Le potentiel de l'IA en établissements de santé](https://formation-continue.ehesp.fr/formation/le-potentiel-de-lia-en-etablissement-de-sante-decryptage-et-applications) (EHESP, 2,5 jours) ### Approfondir les dimensions techniques Pour ceux qui souhaitent développer une culture technique autour de l’IA, notamment le machine learning et le deep learning : * [FIDLE (CNRS)](https://www.youtube.com/@CNRS-FIDLE) : Formation Introduction au Deep Learning via une chaîne YouTube (126 vidéos et 3 parcours thématiques) * [Comment créer des prompts efficaces](https://www.francenum.gouv.fr/guides-et-conseils/pilotage-de-lentreprise/gestion-traitement-et-analyse-des-donnees/comment-creer) : guide du débutant (France Num) * [Multi-agents - Faire du tooling "avec les mains"](https://medium.com/@camille_andre/multi-agents-faire-du-tooling-avec-les-mains-f004a4550c55) : L'article décrit une architecture de multi-agents pour améliorer les LLM (Etalab, 2024) * [Enhancing Language Model Performance: Insights into Retrieval-Augmented Generation and Chunking Techniques](https://medium.com/@camille_andre/enhancing-language-model-performance-insights-into-rag-and-chunking-augmentation-techniques-897ba15a04d6) : comment booster un RAG avec un meilleur découpage, des embeddings adaptés et du reranking (Etalab, 2024) # Le socle interministériel d'intelligence artificielle générative Introduction au SIIAG ### Pourquoi un socle mutualisé ? Depuis 2023, l'ensemble des ministères s'est engagé dans le déploiement de l'intelligence artificielle générative. Si quelques projets ont atteint une maturité opérationnelle, la grande majorité demeure au stade expérimental. Ce constat révèle une difficulté récurrente : chaque administration consacre l'essentiel de ses ressources à reconstruire les mêmes briques techniques de base plutôt qu'à développer ses applications métiers spécifiques. Cette dispersion des efforts produit trois effets indésirables : * **Un gaspillage de ressources publiques** : duplication des investissements en infrastructure, en compétences techniques et en solutions logicielles similaires d'un ministère à l'autre ; * **Une lenteur de déploiement** : les équipes métiers passent plus de temps à résoudre des problèmes techniques communs qu'à concevoir leurs cas d'usage spécifiques ; * **Un impact limité** : peu de projets sont passés à l'échelle pour produire des gains tangibles pour les agents ou les usagers \[1]. **La phase d'expérimentation est achevée. L'État entre désormais dans une phase d'industrialisation de l'intelligence artificielle générative.** Cette transition exige une stratégie technique structurée, qui tire les enseignements des deux années écoulées pour permettre un déploiement à grande échelle, efficace et maîtrisé. ### Le socle Face à ce constat et à cette nécessité, la Direction Interministérielle du Numérique (DINUM) se dote d'une stratégie technique 2026 fondée sur une répartition claire des rôles entre niveau interministériel et niveau ministériel : **La DINUM conçoit, opère et met à disposition un Socle Interministériel d'Intelligence Artificielle Générative** comprenant : * L'infrastructure technique commune (puissance de calcul, modèles, sécurité) et l'accompagnement à son utilisation par les ministères ; * Une boîte à outils transverses (transcription, traduction, interrogation documentaire) ; * Une plateforme de données partagées ; * Des applicatifs génériques de base (chatbot, transcription, etc). **Les ministères conservent l'entière responsabilité de leurs applications métiers** : * Conception des cas d'usage adaptés à leurs politiques publiques ; * Acquisition (ou développement) de solutions spécifiques à leurs besoins ; * Gestion de leurs données sensibles et de leurs processus métiers. **Des ministères peuvent devenir chefs de file sur des briques à vocation interministérielle** : * En développant des composants réutilisables qui enrichissent le Socle (instanciés et opérés par la DINUM) ; * En opérant directement pour l'interministériel des services d'intérêt commun qu'ils hébergent et maintiennent ; * En partageant leur expertise et leurs solutions avec l'ensemble de l'administration. Cette permet aux administrations de se concentrer sur leur cœur de mission – concevoir et déployer des services publics augmentés par l'IA – tout en s'appuyant sur une infrastructure commune robuste, sécurisée et souveraine. Elle valorise également les développements ministériels d'intérêt général en les rendant accessibles à toute l'administration. ### Principes directeurs **Mutualiser, sans centraliser** L'idée centrale de ce socle est de proposer des sources de mutualisation sur des briques de fondation, ainsi qu'un accompagnement au déploiement et à l'accélération de projets IA. Les ministères gardent une totale autonomie pour acheter les solutions métiers ou les développer, préservant ainsi la richesse de leurs cas d'usages. **Autonomie technologie et subsidiarité** Le Socle développe et privilégie systématiquement des solutions dont le code source est ouvert, auditables et dont l'État peut assurer l'opération et la maintenance à long terme. Chaque composant du Socle, qu'il soit développé par la DINUM ou par une entreprise, doit pouvoir être remplacé indépendamment sans affecter le reste du système Chaque application s'appuyant sur le Socle doit pouvoir substituer des outils du Socle par des outils du marché, et vice versa. Les interfaces entre couches respectent des standards ouverts et largement adoptés dans l'industrie, (ex : le standard OpenAI pour les API d'inférence). La DINUM et les ministères gardent, autant que possible, la maîtrise technologie des outils IA déployés. **Sécurité « by-design »** La sécurité, aussi bien d'un point de vue cyber, que de sécurité de systèmes IA, n'est pas une couche ajoutée mais un principe intégré à chaque niveau de l'architecture. Les systèmes proposés dans le Socle sont, autant que possible, compatible avec l'usage de données sensibles, et font l'objet d'homologation de sécurité. L'hébergement doit être effectué sur des infrastructures certifiées SecNumCloud, et proposer un silotage des données dès que possible. **Observabilité** Toutes les opérations effectuées sur le socle sont tracées, mesurées et analysables. Les métriques de performance, coût, qualité et usage sont collectées en temps réel et mises à disposition des équipes techniques et des instances de gouvernance. Cette transparence (qui peut parfois être limitée au regard des besoins de sécurité) permet l'amélioration continue et le respect des obligations de redevabilité démocratique. **Privilégier la qualité à la quantité** Le Socle s'inscrit dans une logique de concentration des efforts sur l'essentiel. Les ressources publiques sont allouées de manière ciblée sur les briques techniques à plus forte valeur ajoutée pour l'ensemble de l'administration, tout en préservant la capacité d'innovation des ministères pour explorer des cas d'usage et des solutions adaptées à leurs besoins spécifiques. Le Socle adopte donc une philosophie fondée sur la qualité plutôt que la quantité : proposer un nombre limité de fonctionnalités fondamentales, mais garantir l'excellence dans la qualité des services et leur fiabilité. # Albert API, l'infrastructure IA souveraine de l'État Albert API permet fournir des services d'IA générative aux administrations Retrouvez la documentation Albert API **Albert API** est une infrastructure publique de services d’intelligence artificielle générative, développée par la DINUM pour permettre aux administrations d’expérimenter, construire et opérer des produits numériques à impact, en s’appuyant sur des modèles d’IA performants, dans un cadre souverain, sécurisé et mutualisé. **Albert API** propose une interface simple (compatible OpenAI), permettant d’accéder à des modèles open source (ex : Llama, Mistral, etc), mais aussi à des services avancés (RAG, OCR, classification, vectorisation de documents…) directement utilisables dans les produits publics. ### Objectifs **Abaisser la barrière à l’entrée**, éviter que chaque ministère réinvente la roue, et orienter l’usage de l’IA vers des cas d’usage concrets, utiles, et éthiques. ### Fonctionnement L’infrastructure repose sur une API centralisée (API Gateway), interopérable avec plusieurs fournisseurs de modèles et hébergements (y compris SecNumCloud). Une version sécurisée et homologuée pour les données internes de l’État est en cours de finalisation. À horizon 2025, Albert API sera l’un des piliers techniques du déploiement de l’IA générative dans les services publics. ### Résultats Albert API est déjà utilisée dans plus de 200 projets publics, avec plus de 100 000 requêtes hebdomadaires, et des retours très positifs sur sa simplicité d’usage, sa fiabilité, et ses performances. ### Pour en savoir plus Site web Documentation\
# DocumentIA, votre pipeline d'analyse documentaire Cette documentation vous guide dans l'intégration et l'usage de l'API DocumentIA, pipeline d'analyse documentaire. Documentation ### Contexte et présentation du projet #### Bénéfices et cas d'usage Une solution d'intelligence documentaire permet notamment : | Cas d'usage | Bénéfices | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Retour direct à l'usager** | Satisfaction usager, qualité des dossiers en instruction, diminution des coûts. L'usager peut corriger son dossier immédiatement, sans attendre l'instructeur | | **Automatisation de l'instruction** | Réduction des coûts et délais, amélioration de l'expérience utilisateur. Passage d'une analyse manuelle à une extraction automatisée des données | | **Lutte contre la fraude** | Assistance des agents, détection améliorée grâce au croisement de sources de données | | **Constitution de bases de données** | Numérisation et analyse de documents historiques, patrimoniaux ou non structurés | Voir la page produit beta.gouv.fr #### Guide de mise en œuvre Un **guide plus complet** sur la mise en œuvre de solutions d'intelligence documentaire est disponible. Il couvre notamment l'investigation métier et technique, le prototypage, l'évaluation des performances, les enjeux juridiques et les bonnes pratiques pour les administrations. → Consultez le Guide Intelligence Documentaire pour une approche globale. *** ### Introduction technique Document-IA est une solution **générique, souveraine** et **sécurisée** d’**analyse automatique** de pièces justificatives, disponible par API. L’API Document-IA déploie les fonctionnalités principales suivantes : * **Catégorisation** du type de document * **Extraction** des informations présentes dans le document sous un format standardisé * **Identification** et lecture de **codes à barres** : QRcode, 2DDOC ### Concepts clés #### Workflow Un **workflow** est une pipeline de traitement de document qui décrit quelles sont **les étapes à réaliser et dans quel ordre**. Dans un workflow, on peut préciser des règles : quels sont les types de fichiers supportés, quel modèle OCR ou LLM utiliser etc. Chaque étape est une brique atomique du workflow : une étape de traitement (ex: télécharger, pré-traiter, extraire le texte via OCR, extraire les informations via LLM, sauvegarder les résultats). Liste des **workflows disponibles** en environnement de sandbox : 🔗 *Note : Il est également possible d'obtenir la liste des workflows via l'endpoint* `GET /api/v2/workflows/`*.* #### Schéma Un **schéma de document** décrit **quelles informations sont attendues** pour un type de document donné, et **comment elles doivent être nommées et structurées**. C’est la définition typée des données à extraire pour un type de pièce (CNI, passeport, avis d’imposition, etc.). * Exemple (carte d’identité) : prénom, nom, date de naissance, numéro de document, etc. Liste des **schémas disponibles** en environnement de sandbox : 🔗 *** ### Environnement (Sandbox) **URL de base :** `https://api.sandbox.document-ia.beta.gouv.fr` ### Authentification L'API utilise une authentification par clé API (token). Vous devez inclure votre clé dans l'en-tête de vos requêtes HTTP avec le header `X-API-KEY` {% hint style="info" icon="lightbulb" %} Pour disposer d’une clé d’API, vous devez contacter l’équipe Document-IA {% endhint %} *** ### Ressources #### Documentation API Pour plus de détails sur les paramètres et les réponses, consultez la documentation. Documentation #### Collection API Une collection [Bruno](https://www.usebruno.com/) est disponible pour tester l'API facilement 🔗 *** ### Exécution des workflows (endpoint v2) {% hint style="warning" %} **Dépréciation :** Les anciens endpoints `v1` (`/api/v1/workflows/...`) sont dépréciés. Il faut dorénavant utiliser les endpoints `v2` (`/api/v2/workflows/...`) pour lancer des analyses. {% endhint %} Une documentation détaillée sur l'exécution des workflows V2 est disponible [ici](https://github.com/betagouv/document-ia/blob/main/document-ia-api/docs/WORKFLOW_V2.md). Il est possible d’appeler l’API de 2 manières : * **asynchrone (recommandé en production)** via la route `POST /api/v2/workflows/{workflow_id}/execute`. Le endpoint répond avec un id d’exécution `execution_id`, le résultat de l’exécution peut être récupéré alors par : * appel API, pulling sur la route de récupération d'une exécution * par webhook sur l’url de votre choix (contacter l’équipe Document-IA pour la configuration du webhook) * **synchrone** via la route `POST /api/v2/workflows/{workflow_id}/execute-sync`. Le résultat de l’exécution est dans ce cas directement disponible dans la réponse de la requête. {% hint style="info" %} Le fonctionnement synchrone décrit n'est possible qu'en expérimentation en sandbox. En production, seul le fonctionnement asynchrone est disponible et recommandé. {% endhint %} ### Workflow spécifique : Extraction de codes-barres Pour l'extraction de codes-barres 2D-DOC sans analyse par LLM, utilisez le workflow : **`document-barcode-extraction-v2`** Ce workflow : * N'utilise pas de LLM * N'utilise pas d'OCR * Extrait directement les codes-barres des documents et vérifie les signatures 2DDOC. {% hint style="info" icon="lightbulb" %} L’utilisation de ce workflow dans le cadre d’appel API synchrone est recommandé (faible latence : \~500ms). {% endhint %} # Une plateforme de données pour l'IA {% hint style="info" %} Cette offre est en cours de construction. La DINUM est toujours intéressée par vos besoins ? {% endhint %} La plateforme de données pour l'IA est une brique du socle interministériel d'IA générative opéré par la DINUM. Elle permet aux administrations d'adapter leur projet IA avec des données publiques pertinentes. Elle s'articule autour de trois composantes : 1. **RAG as a service**, pour interroger des corpus documentaires via Albert API 2. [**data.gouv.fr**](http://data.gouv.fr) comme socle de données de référence 3. **MediaTech**, une bibliothèque de jeux de données publics pré-traités et prêts à l'emploi *** ### RAG as a service — Interroger des corpus documentaires via Albert API #### Qu'est-ce que le RAG ? Le RAG (Retrieval Augmented Generation) est une technique qui permet à un modèle de langage de répondre à des questions en s'appuyant sur un corpus documentaire spécifique, plutôt que sur ses seules connaissances générales. C'est la méthode la plus répandue pour créer des assistants IA spécialisés sur un domaine métier. {% hint style="info" %} **Pour aller plus loin :** Un guide RAG est disponible pour accompagner les équipes dans la compréhension du RAG et dans la mise en place de leur premier cas d'usage. {% endhint %} #### L'offre RAG d'Albert API Albert API propose un **RAG as a service** qui permet aux administrations de : * **Créer un espace documentaire** (collection) dans lequel déposer des documents * **Interroger ces documents** en langage naturel via l'API * **S'appuyer sur des collections publiques** pré-constituées (issues de MediaTech) comme Légifrance ou [service-public.fr](http://service-public.fr) **L'intérêt :** Les équipes techniques n'ont pas à gérer l'infrastructure de vectorisation, de stockage et de recherche sémantique. Albert API le fait pour elles. #### Trois niveaux de service | Niveau | Usage | Données | | -------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------- | | **Mutualisé** | Collections publiques partagées entre ministères | Données non sensibles (Légifrance, [service-public.fr](http://service-public.fr), etc.) | | **Dédié** | Espace documentaire propre à une administration | Données sensibles (notes internes, circulaires, etc.) | | **On-premise** | Instance auto-hébergée par l'administration | Données confidentielles | #### Comment démarrer 1. **Demander un accès** à Albert API via [le formulaire dédié](https://albert-api.numerique.gouv.fr/) 2. **Choisir son mode** : utiliser les collections publiques existantes ou créer sa propre collection 3. **Intégrer l'API** dans son application métier — Albert API est compatible avec les standards OpenAI *** ### [data.gouv.fr](http://data.gouv.fr) — Le socle de données de référence #### Le rôle de [data.gouv.fr](http://data.gouv.fr) dans le socle IA [data.gouv.fr](http://data.gouv.fr) est la plateforme nationale d'open data. Elle référence plus de 50 000 jeux de données produits par les administrations françaises. Dans le cadre du socle IA interministériel, [data.gouv.fr](http://data.gouv.fr) joue un rôle central : celui de **point d'accès unifié aux données publiques françaises pour les systèmes d'IA**. Plutôt que de multiplier les sources et les formats, [data.gouv.fr](http://data.gouv.fr) fournit un catalogue de référence dans lequel les applications IA peuvent puiser. **Concrètement,** [**data.gouv.fr**](http://data.gouv.fr) **offre :** * Une **API de référence** pour rechercher des jeux de données, accéder aux métadonnées et interroger les ressources * Un **catalogue structuré** avec des métadonnées normalisées (organisation productrice, format, fréquence de mise à jour, licence) * Un accès à des **données tabulaires interrogeables** directement via l'API #### Le serveur MCP [data.gouv.fr](http://data.gouv.fr) Depuis début 2026, [data.gouv.fr](http://data.gouv.fr) expose un **serveur MCP** (Model Context Protocol) expérimental. Le MCP est un protocole ouvert qui permet aux systèmes d'IA d'interagir avec des sources de données externes de manière structurée. **Ce que permet le MCP data.gouv :** | Outil | Description | | ------------------------ | ---------------------------------------------------------------------- | | `search_datasets` | Rechercher des jeux de données par mots-clés, organisation ou format | | `get_dataset_info` | Récupérer les métadonnées complètes d'un jeu de données | | `list_dataset_resources` | Lister les ressources disponibles d'un dataset | | `get_resource_info` | Accéder aux détails d'une ressource | | `query_resource_data` | Interroger directement les données tabulaires | | `get_metrics` | Consulter les statistiques d'usage | | `search_dataservices` | Rechercher des API référencées sur [data.gouv.fr](http://data.gouv.fr) | **Comment l'utiliser :** Le serveur MCP data.gouv est disponible en open source. Il peut être connecté à tout assistant IA compatible MCP (Claude, ChatGPT, etc.) pour permettre à un agent conversationnel de rechercher et d'exploiter les données publiques françaises en contexte. Il est en cours d'intégration dans l'**Assistant IA** de la DINUM pour permettre aux agents publics d'accéder aux données publiques directement depuis leur interface de travail. {% hint style="info" %} **Statut :** Expérimental — le serveur MCP est en phase de test et d'évaluation. Un dispositif de monitoring et d'évaluation de la qualité des réponses est en cours de mise en place. {% endhint %} #### L'écosystème MCP dans l'État Le MCP data.gouv n'est pas un projet isolé. Plusieurs serveurs MCP liés aux données publiques françaises émergent ou sont en réflexion. Citons notamment celui de l'**Éducation nationale** qui permet d'accès aux données issus du portail open-data du Ministère. *** ### MediaTech — Collections publiques prêtes pour l'IA #### Qu'est-ce que MediaTech ? MediaTech est une **bibliothèque de jeux de données publics pré-traités**, découpés et structurés pour être directement utilisables dans des applications d'IA générative (RAG, recherche sémantique, etc.). Le problème que MediaTech résout : avant de pouvoir utiliser un corpus public dans une application IA, il faut le collecter, le nettoyer, le découper en segments pertinents (chunking) et le vectoriser. Ce travail prend des semaines. MediaTech le fait une fois pour toutes et met le résultat à disposition. #### Collections disponibles Les collections MediaTech sont publiées sur Hugging Face et [data.gouv](https://www.data.gouv.fr/organizations/direction-interministerielle-du-numerique/datasets). Elles seront bientôt intégrées dans Albert API en tant que Collections publiques.\ Voici les collections disponibles : | Collection | Source | Description | | --------------------------------- | --------------------------------------------- | ------------------------------------ | | `legi` | Légifrance | Codes et lois en vigueur | | `service-public` | [service-public.fr](http://service-public.fr) | Fiches pratiques pour les usagers | | `data-gouv-datasets-catalog` | [data.gouv.fr](http://data.gouv.fr) | Catalogue de jeux de données | | `travail-emploi` | Ministère du Travail | Documentation travail et emploi | | `dole` | DOLE | Documentation administrative | | `local-administrations-directory` | Annuaire | Annuaire des administrations locales | | `state-administrations-directory` | Annuaire | Annuaire des administrations d'État | | `cnil` | CNIL | Documentation CNIL | | `constit` | Conseil constitutionnel | Décisions et textes constitutionnels | #### Ce que contiennent les collections Chaque collection fournit : * Les **documents sources** nettoyés * Un **découpage en segments** (chunks) * Des **métadonnées structurées** (source, date, type de document) Les embeddings ne sont volontairement pas imposés : les retours utilisateurs montrent que chaque équipe préfère utiliser son propre modèle d'embeddings selon son cas d'usage. #### Comment utiliser MediaTech 1. **Via Hugging Face** ou **data.gouv** — Téléchargement direct des datasets pour intégration dans votre propre vector store 2. **Via Albert API** — Les collections MediaTech sont progressivement intégrées comme collections de référence dans le RAG as a service d'Albert API (voir section suivante) *** ### Pour aller plus loin * **Documentation technique Albert API** : * **Collections MediaTech sur Hugging Face** : [huggingface.co/etalab-ia](https://huggingface.co/etalab-ia) * **Code source du MCP data.gouv** : # L'Assistant L'assistant IA conversationnel souverain pour les agents de la fonction publique d'État. Retrouvez la documentation Assistant IA **L'Assistant** est une interface d'échange avec un modèle d'intelligence artificielle générative, à destination des agents de l'administration de l'État et de ses organismes de tutelle. Il permet aux agents, débutants ou expérimenter, de profiter des fonctionalités des *chatbots* généralistes dans un environnement sécurisé, souverain et mutualisé. **L'Assistant** propose une interface simple et épurée, avec de nombreuses fonctionalités d'interconnexions avec [La Suite](https://lasuite.numerique.gouv.fr/) en cours de développement. ### Objectifs **Permmettre aux agents d'utiliser une IA de confiance au niveau de la protection des données**, éviter que chaque ministère réinvente la roue, et leur permettre d'orienter leurs développements et investissements dans l’IA vers des cas d’usage concrets, utiles, et éthiques. ### Résultats L'Assistant a démontré pendant sa phase d'utilisation un fort impact, avec plus d'un demi millions de messages et plus de 150k documents téléversés pour 10k utilisateurs pendant les 6 premiers mois. ### Pour en savoir plus Découvrir l'Assistant Documentation\
# L'IA dans LaSuite Apporter de l’IA là où les agents travaillent déjà, sans changer leurs habitudes, tout en garantissant un cadre souverain et sécurisé. Dans le cadre du plan interministériel sur l’IA générative, l’intégration progressive de fonctionnalités IA dans les outils de [**LaSuite**](https://lasuite.numerique.gouv.fr/) vise à améliorer l’efficacité des agents dans leurs usages quotidiens : rédaction, organisation de fichiers, prise de note, gestion collaborative. L’objectif est clair : **apporter de l’IA là où les agents travaillent déjà**, sans changer leurs habitudes, tout en garantissant un cadre souverain et sécurisé. ### Qu'est-ce que LaSuite ? LaSuite de l’État comprend des services déjà largement déployés comme **Tchap**, **Grist**, des services en cours de déploiement comme **Visio**, **Docs**, **Messagerie** et des services à venir comme **Fichiers**. L’intégration de l’IA dans ces outils est aujourd’hui émergente. La DINUM engage une démarche structurée pour faire de la Suite Numérique un **écosystème nativement compatible avec les agents IA**, en lien avec Albert API. {% embed url="" %} ### Quels sont les cas d'usage concrets ? Concrètement, il s'agit de permettre à un agent de **résumer une réunion Visio**, **discuter avec un assistant dans Tchap, aider à la rédaction ou à la reformulation de mail dans Messagerie, interroger son corpus documentaire stocké dans Fichiers**, ou encore **extraire des données automatiquement dans Grist**. L’ensemble des intégrations s’appuie sur des modèles hébergés sur des infrastructures conformes (SecNumCloud), et documentés dans une logique de commun numérique. ### Comment utiliser l'Assistant IA dans LaSuite ? Il est déjà possible d'utiliser l'IA dans LaSuite, notamment dans le tableur collaboratif Grist, ainsi que dans Docs, l'éditeur de notes, et Visio, l'outil de visioconférence. #### Générer des formules dans GRIST
{% embed url="" %} #### Utiliser un prompt directeur dans Docs {% hint style="success" %} **Cas d'usage :** utiliser les fonctionnalités d’intelligence textuelle de Docs pour reformuler une portion du texte officiel en langage facile à lire et à écrire (FALC). {% endhint %}
{% stepper %} {% step %} Sélectionner la portion du texte qui décrit votre requête (en bleu), puis clique droit ; {% endstep %} {% step %} Cliquer sur l’icône en forme d'étoiles scintillantes :sparkles: ; {% endstep %} {% step %} Ouvrir le menu d’options contextuelles et cliquer sur `Utiliser comme un prompt` : * **`Reformuler`** * **`Résumer`** * **`Corriger`** * **`Langue`** * **`Utiliser comme un prompt`** {% endstep %} {% endstepper %} {% embed url="" %} ### Transcription dans Visio {% hint style="success" %} **Cas d'usage :** transcrire automatiquement des réunions pour pouvoir se concentrer sur l'écoute active et la participation, et ainsi gagner un temps considérable. {% endhint %} Visio est l'outil de visioconférence de LaSuite, et depuis janvier 2026 l'outil préconisé pour l'ensemble de la fonction publique.
{% stepper %} {% step %} Cliquez sur "..." en bas de la visio (seulement accessible à l'organisateur) {% endstep %} {% step %} Cliquez sur "Commencer l'enregistrement" {% endstep %} {% step %} Quelques temps après la réunion, vous recevez la transcription par email ! {% endstep %} {% endstepper %} ### Vous en voulez plus ? L'incubateur ALLiaNCE accompagne les équipes qui souhaitent développer des services IA sur leur cas d'usage, directement intégrés dans les outils de LaSuite :
* **Tchap** : messagerie instantanée sécurisée pour les agents publics, permettant des échanges professionnels confidentiels. * **France Transfert** : service d'envoi de fichiers volumineux, simple et sécurisé, entre agents de l’État et avec des partenaires externes. * **Grist** : outil collaboratif pour la gestion et l'édition de jeux de données, facilitant le travail en équipe sur des bases de données personnalisées. * **Visio** : solution de visioconférence adaptée aux besoins des administrations. * **Docs** (BETA) : application de traitement de texte en ligne pour la rédaction et le partage de documents. * **Messagerie** (BETA) : service de messagerie électronique sécurisé pour les communications professionnelles. # Guide de construction d'un assistant conversationnel basé sur du RAG {% hint style="info" %} * Ce guide s'appuie sur la connaissance acquise au cours des accompagnements de la DINUM lors de l'investigation et la construction d'assistants conversationnels basés sur une architecture RAG. * Ce guide vulgarisé s'adresse **en priorité aux profils fonctionnels** (chef.fe de produit, chef.fe de projets, intrapreneur, référent métier) ou aux profils techniques non expert des sujets IA. {% endhint %} ## Contexte général Chaque administration construit, accumule et modifie de la documentation : notes internes, procédures internes, références réglementaires, guides d’usage, manuels techniques, FAQ, supports de formation, contrats, emails structurants, tickets, historiques projets, etc. Cette connaissance constitue **le patrimoine intellectuel de l’organisation**, mais elle reste souvent : * éparpillée * redondante, contradictoire ou obsolète * peu consultée, car complexe ou peu accessible * dépendante de quelques experts sur-sollicités * insuffisamment utilisée pour la prise de décision **Résultats** : * temps perdu à chercher l’information * erreurs opérationnelles pourtant évitables * ralentissement des projets * coûts de support interne élevés * perte de savoir lors des départs collaborateurs ## La génération augmentée par génération (RAG) L'IA générative, seule, hallucine, invente, simplifie ou décontextualise. Le système de Génération Augmentée par Récupération (RAG - Retrieval-Augmented-Generation) apporte la solution : **retrouver et exploiter les documents réels avant de générer une réponse**. Concrètement, un système RAG est un système qui va d’abord identifier les passages pertinents, en lien avec l’instruction, dans des documents fiables et définis; puis s’en servir pour générer une réponse, plutôt que de répondre uniquement sur la base des données pré-enregistrées. Il combine deux composants : * un **système de** **recherche/récupération** (retrieval) qui trouve les documents pertinents, * un **grand modèle de langage (LLM)** qui génère une réponse basée sur ces documents. Cette combinaison permet de **réduire les hallucinations**, d’ancrer les réponses dans un **corpus maîtrisé** et de **proposer un service plus fiable**. Grâce à l’accompagnement d’ALLiaNCE auprès de plusieurs équipes produits travaillant sur des architectures RAG, des **bonnes pratiques** ont pu être identifiées pour initier efficacement la construction d’un assistant conversationnel.\ \ Le guide propose un **cadre méthodologique et pratique** pour concevoir, évaluer et faire évoluer un assistant conversationnel basé sur une architecture RAG. Il se veut volontairement pragmatique et actionnable, afin d’accompagner des équipes en phase d’exploration ou de mise en œuvre. {% hint style="info" icon="list" %} * [**L'investigation**](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/investigation-metier) : un système d'IA n'est pertinent que s'il résout un irritant réel, répété et/ou coûteux * **L'**[**expertise technique**](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/competences-a-reunir) : rassembler les bonnes compétences pour mener à bien le projet * **La construction** d'un système IA RAG : une approche itérative et collaborative permet de déployer un RAG fiable, performant et aligné sur les attentes des utilisateurs. * [Prototypage](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/prototypage) * [Evaluations par des référents métiers](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/evaluations-referents-metier) * [Evaluations automatisées](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/evaluations-automatisees) * [Evaluations continues ](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/evaluations-continues) * **Les enjeux parallèles** : la mise en production d'un assistant conversationnel basé sur l'IA s'accompagne d'enjeu d'acculturation et d'enjeux juridiques * Les enjeux d'[acculturation des usagers](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/les-enjeux-dacculturation) * Les [enjeux juridiques](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/les-enjeux-juridiques) {% endhint %} # « Faire du RAG » : deux réalités très différentes Aujourd'hui, de nombreuses solutions permettent de "faire du RAG" en quelques clics : importer ses documents dans un outil clé en main, poser une question, et obtenir une réponse fondée sur ces documents. Pour un certain nombre de cas d'usage, cette approche fonctionne et suffit. Pour d'autres, elle ne suffira pas et c'est précisément là que commence le travail décrit dans ce guide. ## **Quand une solution clé en main peut suffire** Une approche simple et "naïve" du RAG donne généralement des résultats satisfaisants lorsque plusieurs conditions sont réunies. * Le **corpus est restreint et stable** : quelques dizaines de documents qui ne changent pas souvent (une documentation interne, un guide de procédures, une FAQ). * Les **documents sont bien structurés et principalement textuels**, sans tableaux complexes, sans annexes graphiques, sans renvois croisés entre articles. * Les questions attendues sont relativement prévisibles et portent sur des informations explicitement présentes dans les textes. * La **tolérance à l'erreur est raisonnable** : une imprécision dans la réponse n'a pas de conséquence juridique, financière ou réputationnelle grave. * L'équipe ne dispose pas de profils techniques dédiés pour maintenir un pipeline sur mesure. **Dans ce cas, un assistant généraliste est le bon choix. Il permet de tester rapidement la valeur d'un assistant conversationnel sans mobiliser de ressources techniques lourdes.** ## **Quand le travail technique doit être approfondi** En revanche, dès que l'on s'éloigne de ces conditions, les limites apparaissent. C'est le cas notamment lorsque : * le **corpus est volumineux et hétérogène**, plusieurs centaines ou milliers de documents de formats variés (arrêtés, notes, règlements, tableaux, images, cartes). Les outils clé en main n'offrent généralement pas de contrôle sur la manière dont ces documents sont découpés, indexés et recherchés; * le **vocabulaire est très spécialisé ou technique** (codes de zone, références juridiques, nomenclatures métier), la recherche purement sémantique peut passer à côté de correspondances exactes pourtant essentielles; * les **documents évoluent fréquemment** et qu'il faut garantir que le système répond toujours sur la version en vigueur, pas sur un texte obsolète; * la **précision factuelle est critique** : un montant erroné, une date incorrecte, une zone géographique confondue peuvent avoir des conséquences réelles pour l'usager ou l'agent qui s'appuie sur la réponse; * on a besoin de filtrer finement les résultats par métadonnées (type de texte, zone géographique, date de validité) pour éviter que le système remonte des documents hors contexte. Dans ces situations, il ne s'agit plus simplement d'alimenter un outil avec des fichiers. Il faut comprendre et maîtriser chaque étape du pipeline, du parsing au chunking, du choix du modèle d'embedding à la stratégie de recherche, de la conception du prompt à l'évaluation des réponses. C'est un **travail d'ingénierie itératif, qui nécessite des compétences techniques**, une collaboration étroite avec les métiers, et une capacité de mesure dès le départ. **Ce guide s'adresse à cette seconde situation. Il accompagne les équipes qui ont identifié un cas d'usage où la qualité des réponses est un enjeu fort, et où un pipeline RAG maîtrisé est nécessaire pour atteindre le niveau de fiabilité attendu. Il ne s'oppose pas aux solutions clé en main, il commence là où elles s'arrêtent.** # Investigation métier {% hint style="info" icon="arrows-to-circle" %} **Vérifier que le problème à résoudre par un système IA / RAG existe bel et bien** {% endhint %} ## **Démarche générale** Comme tout produit numérique, un système IA n’est pertinent que s’il résout un irritant réel, répété et/ou coûteux. L’investigation est la première étape de tout projet IA. Elle consiste à **clarifier le problème à résoudre, à vérifier la faisabilité** (notamment la disponibilité des données nécessaires au bon fonctionnement d'un système IA) et à préparer les conditions d’un futur produit. #### **Démarche pas à pas** * **Investigation métier** : identifier et quantifier l'irritant concret à résoudre * **Hypothèses IA** : interroger la pertinence de l'IA pour répondre à l'irritant * **Recensement des données** : cartographier qualité, disponibilité, complexité. * **Validation de faisabilité** : vérifier que le corpus documentaire et les cas d’usage sont adaptés à une approche RAG. #### **Les livrables attendus** À l’issue de cette étape, l’équipe doit être en mesure de produire trois éléments concrets : * un **parcours utilisateur** décrivant les parcours et scénarii d’usage ; * un **répertoire de données**, précisant leur disponibilité, leur qualité, leur complexité et leur priorité métier; * une **présentation d’investigation**, destinée à un comité stratégique, qui synthétise l'irritant, les hypothèses de solution, la faisabilité et le budget. Ces livrables posent les bases. Ils ne garantissent pas encore la réussite du produit, mais ils permettent de valider que le problème est réel, que des données existent et qu’une expérimentation IA est envisageable. {% hint style="info" %} Si vous n'êtes familier du mode produit dans lequel s'inscrit la démarche d'investigation, [ce document](https://doc.incubateur.net/communaute/gerer-son-produit/approche-produit) vous apportera une explication fine des enjeux. {% endhint %} ## Identifier et quantifier l'irritant auprès des équipes métiers La question centrale est : **« ****Quel est l'irritant concret que rencontrent les équipes, les usagers ?**** ».** Trop de projets IA échouent parce qu’ils partent de la technologie avant de partir de l’usage. L’investigation permet de mettre l’accent sur l’analyse métier, l’écoute des utilisateurs. Un produit démarre souvent par une intuition, des observations ou une expérience vécue, ou, pour l'IA, une volonté d'ajouter de l'IA dans les pratiques professionnelles. {% hint style="success" icon="magnifying-glass" %} ***Exemple d'irritants observables /*** ***intuitifs*** * *L'embarquement de nouvelles personnes dépend beaucoup du tutorat humain* * *Les informations existent mais personne ne sait où les trouver* * *La recherche d'information prend une part importante des missions* * *Les collaborateurs, les usagers posent toujours les mêmes questions* * *Les experts sont saturés et deviennent des « points de goulot »* * *La documentation est trop longue, trop technique, trop juridique, trop dispersée* {% endhint %} **La phase d'investigation permet de vérifier / généraliser cette intuition, la situation vécue, le besoin réel de l'IA****. Nous cherchons à répondre aux questions suivantes :** * Quel est **l'irritant métier** et comment se manifeste-t-il ? * Qui en souffre ? **Combien** de personnes ? * Quelle activité est ralentie, risquée, inefficace ? * **Combien de temps, d’argent, de qualité** cela coûte-t-il ? * Existe-t-il déjà une solution non utilisée ? Pourquoi ? * Quelles données sont utilisées, pertinentes et disponibles ? * Quel est l'intérêt de l'IA par rapport au coût ? * Quel serait **l’impact** si on réglait ce problème demain ? #### Recueillir les informations Pour concevoir un produit ou un service qui réponde véritablement aux attentes des utilisateurs, il est **essentiel de bien comprendre leurs besoins, leurs habitudes et leurs difficultés**. Voici cinq méthodes couramment utilisées pour recueillir ces informations lors de la phase d'investigation : | **Objectif** | **Méthode** | **Description** | **Avantages** | | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **Pour comprendre de manière approfondie et qualitative (1)** | Mener des **entretiens individuels** avec les personnes cibles |

Cette méthode consiste à organiser des échanges individuels (en face-à-face ou à distance) avec des usagers représentatifs de la cible.

L’objectif est d’approfondir leur expérience, leurs attentes et leurs frustrations.

|

- Permet d’obtenir des réponses détaillées et personnalisées


- Favorise une compréhension fine des motivations et des comportements.

| | **Pour comprendre de manière approfondie et qualitative (2)** | Réaliser des **immersions** sur le terrain |



L’immersion consiste à observer les utilisateurs dans leur environnement naturel, en situation réelle d’utilisation.

Cela permet de voir comment ils interagissent avec un produit ou un service, et d’identifier des besoins non exprimés.

|

- Révèle des comportements ou des problèmes invisibles en entretien


- Offre une vision concrète et contextuelle

| | **Pour valider des hypothèses à grande échelle.** | Effectuer des enquêtes via des **questionnaires** | Les questionnaires sont des outils structurés (en ligne ou papier) permettant de recueillir des données quantitatives ou qualitatives auprès d’un grand nombre de personnes. |

- Permet de toucher un large échantillon rapidement.


- Facilite l’analyse statistique des réponses

| | **Pour s’inspirer et se positionner par rapport à la concurrence.** | S'appuyer sur des enquêtes, des **benchmarks** | Cette méthode consiste à analyser des études existantes (études sectorielles, rapports, données publiques) ou à comparer les pratiques de la concurrence (benchmark) |

- Donne une vision globale du marché et des tendances.


- Permet de s’inspirer des bonnes pratiques ou d’identifier des opportunités.

| | **Pour explorer des idées ou des concepts de manière collaborative** | Organiser des **focus groupes** |

Un focus groupe réunit un petit groupe d’utilisateurs (6 à 10 personnes) pour discuter d’un sujet spécifique, animé par un modérateur.

L’objectif est de recueillir des opinions, des idées et des réactions collectives.

|

- Stimule les échanges et les idées grâce à la dynamique de groupe.


- Permet de tester des concepts ou des prototypes rapidement

| Dans un premier temps, il est pertinent de cibler largement les profils à interroger pour avoir une vue générale des frictions rencontrées dans les équipes. À l'issue de la phase d'investigation, l'équipe pourra définir un irritant principal pour démarrer la construction. La phase d'investigation continue jusqu'à que vous n'appreniez plus d'éléments supplémentaires lors des échanges avec les usagers. La phase d'investigation donne lieu à un **irritant clairement énoncé, validé et quantifié.** {% hint style="info" icon="presentation-screen" %} Illustration de présentation d'un [comité de fin d'investigation](https://fichiers.numerique.gouv.fr/explorer/items/files/cf09a960-90af-4283-b3fb-04d515c514b1). Le comité d'investissement (dont le premier est le comité de fin d'investigation) est l'instance de pilotage principal d'un produit numérique dans le programme beta.gouv.fr. Il a lieu tous les 6 mois et permet de faire le point sur l'impact obtenu par le produit. En fonction des résultats, les sponsors qui financent le service doivent arbitrer la nouvelle demande d'investissement. {% endhint %} ## Investiguer la donnée nécessaire Dans le domaine de l’intelligence artificielle, et plus particulièrement des systèmes de génération augmentée par récupération (RAG), une règle d’or s’impose : « **Garbage in, Garbage out** ». Autrement dit, la qualité des résultats dépend directement de la qualité des données en entrée. Une documentation pauvre, incomplète ou mal structurée se traduira inévitablement par des réponses médiocres, voire inefficaces. **Le RAG ne se substitue pas à la documentation**** — il en amplifie l’usage et en optimise l’accès**. Ainsi, avant même de concevoir ou d’implémenter un système de RAG, une vérification rigoureuse s’impose pour garantir que les données utilisées sont pertinentes, fiables et exploitables. Les échanges préalables avec les usagers ont permis d’identifier les irritants majeurs et de recenser les besoins en termes de données. Cette phase vise à **approfondir la connaissance de ces données** sous plusieurs angles : * **Localisation** : où se trouve l’information ? * **Priorité** : toutes les sources ont-elles la même importance pour les usagers ? * **Périmètre** : les usagers ont-ils besoin de toute la donnée dans les sources ? * **Format** : sous quel format la donnée est stockée * **Traitement antérieur** : cette information a-t-elle déjà été analysée, transformée ou enrichie ? * **Mise à jour** : à quelle fréquence la donnée est-elle mise à jour ? * **Conformité** : existe-t-il des évolutions réglementaires à prendre en compte ? * **Restrictions** : quel est le niveau de sensibilité ou de confidentialité de l’information ? les droits d'accès sont-ils ouverts ou restreints ? Ces questions permettent de dresser un état des lieux précis et d’identifier les éventuels obstacles à lever avant toute implémentation. Pour qu’une donnée soit adaptée à un système de RAG, elle doit répondre à **plusieurs critères fondamentaux** : * **accessible et conforme** : la documentation doit être accessible aux équipes et aux outils, et son utilisation doit être autorisée sur le plan juridique (droits d’auteur, protection des données, etc.). Si un doute subsiste, échanger avec vos experts juridiques dès la phase d'investigation pour assurer un usage conforme. * **stable** : les données doivent être suffisamment stables pour être indexées sans risque de désuétude immédiate. Une information trop volatile peut nuire à la pertinence des réponses générées. * **gouvernée** : * Les propriétaires de chaque source doivent être clairement identifiés pour faciliter les mises à jour et les validations. * L’organisation doit accepter la transparence et la traçabilité des données, afin de garantir leur fiabilité et leur auditabilité. 🚧 Négliger cette étape revient à construire un système sur des fondations fragiles. Un RAG performant repose sur des données **complètes, à jour et bien gouvernées**. Sans cette rigueur, les risques sont multiples : * Réponses inexactes ou obsolètes. * Non-conformité réglementaire. * Difficultés à maintenir et faire évoluer le système. {% hint style="info" icon="presentation-screen" %} *Illustration*\ *Dans le cadre d’un projet pilote Q4 2025, une équipe incubée a initié la conception d’un assistant conversationnel dédié aux rapporteurs des sections consultatives. Afin de préciser les exigences techniques, une analyse exhaustive des données mobilisées lors de la rédaction des avis a été réalisée.*\ \ *Cette étude a révélé que certaines données critiques étaient soumises à des restrictions d’accès, limitant leur exploitabilité directe. Pour évaluer la faisabilité et la pertinence de l’outil, une cartographie détaillée des sources de données a été établie.*\ \ ***L’objectif était d’identifier les sources pertinentes, techniquement accessibles** (c’est-à-dire ne nécessitant pas de contournement complexe des restrictions) et **exploitables** sans dépendance à des autorisations spécifiques pour mener à bien la première itération (toujours dans l'optique de valider la valeur de la solution pressentie).* \ \ [exemple de répertoire de données](https://grist.numerique.gouv.fr/o/albert/cUZuufp1xnYP/JACEPAIR-repertoire-des-donnees?utm_id=share-doc) {% endhint %} # Compétences à réunir {% hint style="info" icon="arrows-to-circle" %} **Clarifier le besoin de compétences métier / techniques / fonctionnels** {% endhint %} Au démarrage d’un **assistant conversationnel RAG**, il n’est pas nécessaire de disposer d’une équipe experte et complète. En revanche, certaines **compétences minimales** sont indispensables pour éviter les erreurs structurelles et poser des bases solides. Nous proposons une distinction entre la "mise en place" du système RAG et le "passage à l'échelle" lorsque cela est nécessaire. Au minimum, nous préconisons la réunion de 4 compétences. Chaque compétence est décrite dans les paragraphes suivants : * compétence fonctionnelle : produit et cadrage * compétence métier : expertise et connaissance des données * compétences techniques RAG * compétences techniques en évaluations et monitoring Ces compétences peuvent être articulées différemment selon les ressources disponibles (profils présents dans l'équipe, ou ressources financières limitées). Le domaine des assistants conversationnels et des architectures RAG évolue rapidement. Si des outils et des méthodologies existent, les pratiques restent en consolidation et fortement dépendantes du contexte d’usage. Dans ce cadre, au-delà des compétences techniques formelles, la curiosité, la capacité d’expérimentation et l’apprentissage continu constituent des atouts déterminants. ## Compétences produit et cadrage **Rôle :** Transformer un problème métier en un assistant conversationnel testable et utile. **Missions attendues** * définir un **cas d’usage clair** (cible, objectifs, périmètre, hors périmètre) ; * comprendre les **besoins utilisateurs réels** et les situations de travail concrètes ; * prioriser efficacement (MVP, périmètre initial, erreurs acceptables vs critiques). Un assistant RAG est un produit conversationnel : l’expérience utilisateur est aussi importante que la performance technique. **Profils types :** chef de produit / product owner ; responsable métier fortement impliqué. ## Expertise métier et connaissance des données **Rôle :** Garantir la qualité des sources documentaires et la pertinence métier des réponses. **Missions attendues** * connaissance du **domaine métier couvert par l’assistant** ; * connaissance des **sources documentaires existantes** ; * capacité à qualifier et à versioner la **qualité, la fraîcheur et la fiabilité** des documents ; * identification de **questions réalistes** et de cas d’usage concrets ; * validation de premier niveau des réponses (au moins *manifestement fausses* vs *plausibles*). **Profils types :** référent métier ; utilisateur avancé du domaine. ## Compétences techniques RAG #### Rôles clé * Mettre en œuvre un système RAG fonctionnel, compréhensible et itérable, sans sur-complexité. * Lors du déploiement à plus grande échelle, assurer une **qualité stable dans le temps**, malgré l’augmentation des usages et des données. **Missions attendues en première itération** * compréhension du fonctionnement d’un RAG (retrieval → génération) ; * mise en place d’un pipeline simple (indexation, recherche, génération) ; * capacité à itérer rapidement (prompts, paramètres, modèles). **Missions attendues lors du passage à l'échelle** * optimisation des pipelines (recherche, indexation, reranker) à grande échelle ; * gestion des mises à jour documentaires ; * maîtrise des versions (modèles, prompts, index) ; * gestion des erreurs et des comportements dégradés. **Profils types :** ingénieur data, ingénieur IA * dans le cas où la compétence n'est pas présente dans l'équipe, un développeur expérimenté peut prendre en charge la mise en place du socle technique pour lA première itération. ## Compétences en évaluation #### Phase : mise en place (souvent oubliée, mais critique) **Rôle clé :** Doter le projet d’une première capacité de mesure afin de guider les itérations. **Missions attendues** * définition de **questions de test réalistes** ; * constitution d’un **jeu de données de référence minimal** ; * compréhension des différences entre : * qualité perçue, * qualité mesurée, * limites des évaluations automatisées. **Profils types :** profil hybride produit / data / IA. #### Phase : passage à l’échelle (pilotage continu) **Rôle clé :** Détecter les dérives, comparer les versions et soutenir les décisions produit. **Missions attendues** * mise en place de **métriques automatisées** (qualité, performance, sécurité) ; * exploitation structurée des retours humains ; * détection des régressions et dérives ; * analyse des résultats et aide à la décision. **Profils types :** Data engineer / ML engineer ## Compétences Infra / Ops Selon le cadre organisationnel dans lequel vous construisez votre assistant conversationnel RAG, il peut être nécessaire de penser aux compétences Ops / Infra **Rôle clé** : garantir la disponibilité, la performance et la fiabilité du service. **Missions attendues** * Déploiement et hébergement * Supervision, monitoring des erreurs * Gestion de montée en charge **Profils types :** DevOps / Ingénieur cloud / Ingénieur data * Lorsque le projet s’inscrit dans un environnement structuré avec une DSI définissant les standards d’hébergement, de sécurité ou de supervision, ces besoins sont largement cadrés. * Dans les petites équipes, ce rôle est souvent assuré par un développeur expérimenté ou un ingénieur data ayant des compétences cloud. {% hint style="info" %} 👉 pour aller plus loin, [observatoire des TJM](https://doc.incubateur.net/communaute/travailler-chez-beta.gouv.fr/les-differents-statuts/independants-freelances/observatoire-revenus) beta.gouv.fr pour les indépendants 👉 prestations intellectuelles via [l'UGAP](https://www.ugap.fr/informatique-et-telephonie-2/prestations-informatiques-12301/prestations-intellectuelles-16504?totalNews=8) 👉 [marchés publics interministériels](https://doc.incubateur.net/communaute/gerer-son-produit/gestion-au-quotidien/marches) beta pour des prestations de construction produit et de mentorat. {% endhint %} # Prototypage {% hint style="info" icon="arrows-to-circle" %} **Comprendre les premières étapes de construction et le fonctionnement d'une architecture RAG simple** {% endhint %} Un système RAG (Retrieval-Augmented Generation) repose sur quatre piliers : **les connaissances (sources)**, **la transformation des sources**, **le modèle de langage** et **l’interface utilisateur**. Pour en garantir l’efficacité, son déploiement doit suivre une démarche structurée, alliant rigueur technique et collaboration avec les métiers. **Cette démarche ne s'applique qu'une fois les données répertoriées, priorisées, disponibles et accessibles** (section [​Investigation métier](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/investigation-metier)). L’IA générative est souvent perçue comme un agent conversationnel. Démarrer par une brique simple sous forme de *chat* permet d’expérimenter rapidement, de comprendre les usages réels et de préparer une version plus adaptée dans un second temps. \ Lors de cette première itération, l’équipe se concentre sur un enjeu central : **la qualité de l’information et la robustesse technique du *****pipeline***** RAG.** L’interface reste volontairement simple et générique. ## Objectif de la première itération **Avant d’engager les travaux, il est indispensable de (re)clarifier le cadre** sur la base des apprentissages de la phase de l'[​Investigation métier](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/investigation-metier) : * À quoi doit servir l'assistant conversationnel IA ? À qui ? * Sur quel périmètre, les expérimentateurs testeront la première version ? * Quel est le niveau de précision attendu selon les usages ? * Quelles sont les erreurs critiques à éviter absolument (juridiques, métiers, éthiques, réputationnelles) ? **Un prototype ne doit pas être généraliste. Il doit tester un cas d’usage prioritaire et priorisé.** Ce périmètre conditionne les dimensions techniques : sélection des sources, le volume de données à indexer, la taille du stockage nécessaire (vector store), le choix du modèle (LLM et embeddings). Un périmètre mal défini rend l’évaluation impossible. Lors de cette première itération, **l'effort repose principalement sur les profils techniques**. Les profils métier interviennent ponctuellement pour qualifier la pertinence des réponses. **Cette première itération permet de :** * assembler les composants techniques d’un système RAG fonctionnel (sections suivantes); * tester la qualité des réponses sur les sources prioritaires (section [Evaluations référents métier](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/evaluations-referents-metier)); * identifier rapidement les premiers points de friction ; * préparer les itérations suivantes. ## Architecture minimale du prototype La construction d’un prototype d’assistant conversationnel basé sur une architecture RAG repose sur une succession d’étapes techniques. L’objectif est de **transformer un corpus documentaire brut en un système capable de retrouver les informations pertinentes et de générer une réponse contextualisée** pour l'utilisateur. Schématiquement, l'architecture d'un assistant conversationnel basé sur une architecture RAG repose sur quatre briques principales : * **Base de connaissances** : données sources qui alimentent les réponses du RAG * **Moteur de recherche** (retrieval) : composant chargé d’identifier les documents ou passages les plus pertinents par rapport à la question de l’utilisateur. * **Modèle de génération** (LLM) : modèle qui génère les réponses à partir des données récupérées * **Interface** : interface utilisateur conversationnelle simple permettant de poser une question, de consulter la réponse et d'évaluer

Vue d’ensemble de l’architecture

Cette architecture se construit de manière progressive. Les différentes étapes de mise en œuvre sont détaillées dans les sections suivantes. **Sources → Parsing → Chunking → Embedding → Stockage → Recherche → Génération** 💡 Le but n’est pas d’être innovant. Le but est d’être **fiable, maintenable et mesurable.** {% columns %} {% column %} {% hint style="success" %} **À privilégier** * composants standards et maintenus * comparaison rapide de variantes * évaluation dès le début * simplicité technique {% endhint %} {% endcolumn %} {% column %} {% hint style="warning" %} **À éviter** * entraîner son propre modèle * choisir une base vectorielle exotique * construire un chatbot généraliste * complexifier l’interface * ignorer les métriques {% endhint %} {% endcolumn %} {% endcolumns %} ### Sources : alimenter le système avec des sources fiables La première étape consiste à **rassembler les sources documentaires** qui constitueront la base de connaissance de l’assistant : documents PDF (textes ou images), fichiers bureautiques (Word, Excel, etc.), pages web ou intranet, bases documentaires internes, API. La collecte des données requiert une connaissance métier des sources disponibles et pertinentes pour le système. Elle donc prise en charge par les profils métier de l'équipe. Cette phase implique des enjeux de gouvernance des données (qualité, versionning, fréquence de mise à jour, droits d’accès) et d’hébergement (où sont stockées les données, avec quelles garanties de sécurité). Une base pauvre ou obsolète dégradera immédiatement la qualité des réponses. ### Base de connaissance : transformer les documents en données exploitables Avant de pouvoir interroger les documents en langage naturel, il est nécessaire de les **transformer en données techniquement exploitables** par le système RAG. Cette préparation constitue en plusieurs étapes fondamentales : elle conditionne directement la qualité de la recherche documentaire et, par conséquent, la fiabilité des réponses générées. 1. **Parsing : ****transformer les documents en texte exploitable** Les modèles de langage travaillent sur du texte brut. Il est donc nécessaire de convertir tous les documents dans un format homogène (généralement `.txt`). Cette étape inclut : * l’extraction du texte depuis des PDF ou fichiers bureautiques ; * l’OCR (reconnaissance optique de caractères) pour les documents scannés ou les images ; * la suppression d’éléments parasites (pieds de page, numéros de page, artefacts). Cette phase permet **d'obtenir un corpus textuel propre et exploitable.** 2. **Chunking : ****découper les textes** Les modèles de langage ont une limite de contexte : ils ne peuvent pas traiter des documents trop longs en une seule fois.\ \ Il est donc nécessaire de découper les textes en segments (“chunks”). Plusieurs paramètres peuvent être ajustés : * taille des chunks ; * chevauchement entre chunks ; * segmentation par structure (titres, sections). Le chunking est stratégique : un **mauvais découpage peut dégrader** fortement la qualité de la récupération (retrieval). 3. **Embedding : ****transformer et stocker le texte en représentation vectorielle** Chaque chunk est ensuite transformé en vecteur numérique (embedding), c’est-à-dire une représentation mathématique du contenu sémantique. Deux textes proches en sens auront des vecteurs proches dans l’espace vectoriel. * Un modèle d’embedding est utilisé. * Le choix du modèle peut influencer significativement la qualité de la récupération (retrieval). Chaque chunk est stocké sous la forme : texte original + vecteur associé Ces paires sont enregistrées dans une **base appelée vector store**, optimisée pour les recherches par similarité. Cette étape est une étape cœur du mécanisme de recherche documentaire. À l'issue de ces trois étapes, les données sont exploitables par le système de recherche. {% hint style="info" %} L'ensemble des étapes de transformation de la donnée peut être effectué via [Albert API](https://albert.sites.beta.gouv.fr/access/), plateforme interministérielle d'inférence. Pour le modèle d'embedding, Albert API propose un seul modèle par défaut. \ \ Des outils comme *chunk visualizer* (Hugging Face) permettent de comprendre les différents paramètres de chunking et d’analyser l’impact de ces choix.\ \ [Mediatech](https://huggingface.co/collections/AgentPublic/mediatech) propose des jeux de données du service public français vectorisées, prêt à l'emploi pour l'IA. {% endhint %} ### Recherche : récupérer les contenus pertinents L'étape de recherche (retriever) vise à **identifier, dans le corpus vectorisé, les segments de texte les plus pertinents par rapport à la question de l’utilisateur**. Lorsqu’un utilisateur pose une question : * La question est transformée en vecteur (embedding) à l’aide du même modèle utilisé pour les documents. * Le vecteur de la question est comparé à l’ensemble des vecteurs du corpus stockés dans le vector store, via une métrique de similarité. * Les chunks les plus proches, selon la métrique de similarité, sont sélectionnés. 🚧 C’est une étape critique : si les bons documents ne sont pas retrouvés, le modèle de génération ne pourra pas produire une réponse fiable, lors de l'étape suivante. {% hint style="info" %} Cette étape peut également être effectuée via [Albert API](https://albert.sites.beta.gouv.fr/access/) qui propose plusieurs méthode de recherche [Techniques avancées de RAG dans Albert API](/guides/albert-api-rag-techniques-avancees-rerank). {% endhint %} ### Réponse : générer la réponse en langage naturel Une fois les documents pertinents identifiés, **la phase de génération consiste à produire une réponse pertinente** : la génération se doit de rester fidèle au corpus sélectionné. La génération de la réponse ne doit pas inventer ce que la recherche n’a pas trouvé. Cette étape repose sur un modèle de langage (LLM), mais son comportement dépend fortement de la manière dont le contexte lui est présenté, contexte qui comprend : * la question utilisateur * le prompt * les chunks récupérés (contexte documentaire) Il n'est pas nécessairement pertinent d'utiliser un "gros" modèle (LLM), plus consommateur d'énergie. Le choix du LLM et de ses paramètres (prompts, températures, et limites de tokens) est à effectuer en perspective du cas d'usage. {% hint style="info" %} Pour la sélection du modèle, le [classement Compar:IA](https://comparia.beta.gouv.fr/ranking) permet de comparer des grands modèles de langage (LLM) sur différents critères d'évaluation. \ \ [Albert API](https://albert.sites.beta.gouv.fr/access/) permet d'accéder à des LLM en SecNumCloud. {% endhint %} ### Interface minimale À ce stade du prototype, une interface minimale suffit généralement, comprenant : * un champ de saisie permettant à l’utilisateur de poser une question en langage naturel ; * l’affichage clair de la réponse générée par le modèle ; * l’affichage des sources utilisées, afin de renforcer la transparence et faciliter la vérification ; * un mécanisme simple de feedback utilisateur (pertinent / non pertinent ou notation, commentaire libre, etc.), indispensable pour alimenter les itérations. L’enjeu est de tester le fonctionnement du système RAG, pas l’expérience utilisateur finale.\ \ Une interface complexe ou trop intégrée peut ralentir l’itération technique et détourner l’attention du véritable enjeu : la qualité de la recherche et de la génération. Il est important de ne pas sur-investir le front-end à cette étape. **Le prototype doit être simple, testable et évolutif. L’optimisation de l’expérience utilisateur viendra dans un second temps, une fois la qualité informationnelle stabilisée.** {% hint style="info" %} Pour cette première version, des solutions simples et rapides à mettre en œuvre sont généralement privilégiées :
\- **Streamlit**, pour créer rapidement une interface web légère. Streamlit est notamment prisé des ingénieurs IA, habitués à l'outil. \ \ \- une **interface sur mesure minimale**, développée rapidement par l’équipe technique si les compétences sont présentes. {% endhint %} ## Infrastructure et hébergement La mise en place d’un prototype RAG ne se limite pas aux briques fonctionnelles (base vectorielle, retrieval, génération, interface). Elle suppose également de **définir un cadre d’infrastructure clair, garantissant la sécurité, la performance et la pérennité du système**. Même si nous préconisons une solution simple lors de la première itération, selon le type d'information que vous traitez, certaines réflexions doivent être anticipées. Plusieurs dimensions doivent être analysées dès le départ : * **Type d’hébergement** : * Cloud public, cloud privé, infrastructure interne (on-premise). * Le choix dépend des contraintes réglementaires, du niveau de sensibilité des données et des pratiques de l’organisation. * **Sécurité et conformité** : * Protection des données (RGPD), gestion des accès, chiffrement des échanges et des données stockées. * Dans certains contextes (administration, secteur réglementé), des exigences spécifiques peuvent s’appliquer dès le démarrage (ex. : SecNumCloud, HDS). * **Latence et performance** : * Le temps de réponse est un facteur clé de l’expérience utilisateur. * Une architecture mal dimensionnée peut dégrader la fluidité des échanges. * **Scalabilité** : * Même si le prototype cible un nombre limité d’utilisateurs, il est utile d’anticiper une montée en charge future. * Les évolutions d’architecture doivent être réfléchies pour éviter de tout reconstruire ou pour avoir une première version temporaire volontairement. * **Coût** : * Les coûts peuvent provenir de plusieurs éléments : * appels API au LLM, * stockage des données, * puissance de calcul, * Un suivi dès le prototype permet d’éviter les mauvaises surprises lors du passage à l’échelle. En phase prototype, l’objectif est de trouver un équilibre entre simplicité et conformité.\ Il ne s’agit pas de construire une architecture définitive, mais de poser des bases suffisamment solides pour tester le système sans compromettre la sécurité ou la conformité réglementaire.
{% hint style="info" %} Selon les contraintes et le niveau de maturité de l’équipe, plusieurs solutions peuvent être mobilisées :
\- **Albert API** : pour accéder à des modèles de langage dans un cadre sécurisé (notamment en environnement SecNumCloud).
\- **Hébergement interne - dans l'environnement de DSI** : pertinent lorsque les données sont sensibles ou que l’organisation impose un hébergement maîtrisé.
\- **Scalingo ou autres PaaS** : solutions simples pour déployer rapidement un prototype web.
\- **Kubernetes** : adapté à des environnements plus structurés ou à des projets visant une montée en charge progressive.\ \ [Portail de l'UGAP](https://www.ugap.fr/cloud-services-d-informatique-en-nuage-c4544324) pour sélectionner un hébergement cloud pertinent {% endhint %} ## Quelques pistes de travail pour l'amélioration Les premières implémentations "naïves" d’un assistant RAG donnent rarement des résultats parfaitement satisfaisants. Un système RAG est une chaîne de traitement composée de plusieurs briques interdépendantes, et chacune d’elles peut être optimisée. Chaque étape du pipeline peut alors faire l’objet d’optimisations ciblées, dont nous donnons quelques exemples de manière non exhaustive pour démarrer. * **Améliorer le traitement des sources** * parsing : convertir les images dans les documents en texte en amont du traitement * chunking : ajouter, grâce à un LLM, du contenu dans les chunks afin d'améliorer leur retrouvabilité * embedding : si l'équipe a accès à des GPU, tester différents modèles d'embedding * **Améliorer le traitement de la question** * "query enhancement" : mécanisme qui retraduit la question de l'utilisateur pour qu'elle devienne plus claire pour la recherche * **Améliorer la recherche** * recherche hybride : combiner recherche vectorielle avec d'autres méthodes de recherche * reranker : mécanisme qui appelle un modèle de rerank pour reclasser les résultats de la recherche dans l'optique d'affiner la pertinence. Cela peut être perçu comme un second filtre sur les données. Ce mécanisme n'est pas applicable sur l'ensemble des données pour des raisons de charge / temps. * **Améliorer la génération de la réponse** * "Fact checking" : mécanisme de vérification de la réponse envoyée avec un modèle LLM. Un second LLM vérifie la qualité de la réponse générée. Le besoin d'amélioration provient d'une analyse des réponses via notamment la mise en place de l'évaluation des composants. Ces évaluations vont aiguiller les travaux nécessaires à l'amélioration du système. ## Dès la première itération : penser évaluations La qualité de l'expérience utilisateur dépend directement de la **capacité à générer une réponse pertinente, fiable, adéquate** aux questions des utilisateurs. Après avoir démarré sur une approche "naïve", c'est à dire après avoir assemblé naïvement les différents composants techniques nécessaires, la conception d’un assistant RAG performant repose sur un **cycle structuré d'évaluations**, couvrant à la fois ces composants techniques et les usages métiers. Il existe des métriques statistiques "classiques" qui permettent d'évaluer la qualité d'une réponse grâce à la distance sémantique de deux réponses. Hors ces métriques peuvent montrer des limites sur l'évaluation des réponses issues d'un système RAG comme le montre l'exemple ci-dessous. **Question : Je dois refaire ma carte d'identité après une perte. Combien cela va-t-il me coûter ?** {% columns %} {% column %} ***Réponse A***\ *En cas de perte, le renouvellement de la carte nationale d’identité coûte **25**** ****€**, à payer sous forme de timbre fiscal (achat possible en ligne ou chez certains buralistes).* *Cas où c’est gratuit :* * *Première demande ou renouvellement avec l’ancienne carte présentée : gratuit.* * *Le paiement est dû uniquement parce que la carte est perdue (ou volée) et donc non restituée.* *Il est également nécessaire de faire la déclaration de perte (en mairie, commissariat ou gendarmerie selon le cas) avant ou pendant la demande de nouvelle carte.* {% endcolumn %} {% column %} ***Réponse B***\ *En cas de perte, le renouvellement de la carte nationale d’identité coûte **250**** ****€**, à payer sous forme de timbre fiscal (achat possible en ligne ou chez certains buralistes).* *Cas où c’est gratuit :* * *Première demande ou renouvellement avec l’ancienne carte présentée : gratuit.* * *Le paiement est dû uniquement parce que la carte est perdue (ou volée) et donc non restituée.* *Il est également nécessaire de faire la déclaration de perte (en mairie, commissariat ou gendarmerie selon le cas) avant ou pendant la demande de nouvelle carte.* {% endcolumn %} {% endcolumns %} Dans cet exemple, les réponses sont sémantiquement très proches, quasiment identiques. Les métriques statistiques dites "classiques" évalueraient ces réponses comme similaires et potentiellement pertinentes. Hors un caractère essentiel impacte la pertinence de la réponse : le coût est indiqué à 25€ dans la première réponse (vérité), 250€ dans la seconde (erreur). Pour parvenir à une évaluation efficace de la qualité des réponses, deux méthodes, développées dans les pages suivantes, doivent donc être combinées : * [Évaluations référents métiers](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/evaluations-referents-metier): les référents métier évaluent les critères de qualité (la pertinence, la clarté, fidélité, sources,...) * [​Évaluations automatisées](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/evaluations-automatisees) (LLM-as-a-judge) : Un juge LLM évalue la qualité des réponse selon les critères définis. En parallèle, lors de la mise en production, d'autres métriques permettront d'évaluer en temps réel les tendances d'usage des utilisateurs (notation, clics, adoption,...) et les performances de l'outil (latence, consommation énergétique, sécurité...). **🚧 ****Sans une évaluation rigoureuse et continue, l'assistant conversationnel peut:** * répondre à côté (documents non pertinents ou mal récupérés) ; * ou halluciner (génération incorrecte ou non sourcée) ; * ou produire des réponses incohérentes, sensibles ou dangereuses, posant des problèmes de confiance, de sécurité ou de conformité. # Evaluations référents métier {% hint style="info" icon="arrows-to-circle" %} **Assurer l’évaluation de la qualité métier du système RAG par une mobilisation progressive et structurée de testeurs métiers engagés** {% endhint %} Contrairement aux modèles de langage classiques, qui génèrent des réponses à partir de patterns appris, les systèmes RAG s'appuient sur des sources externes (base de connaissance) pour enrichir leurs réponses. Cela introduit une complexité supplémentaire : la **qualité de la réponse** dépend non seulement de la capacité du modèle à **générer un texte cohérent**, mais **aussi de sa capacité à identifier, extraire et synthétiser les informations pertinentes** à partir de documents parfois volumineux et hétérogènes. Une évaluation purement automatique [Évaluations automatisées](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/evaluations-automatisees), basée sur des métriques comme la précision ou le rappel, ne suffit pas. Elle ne peut pas juger de la pertinence contextuelle des sources, de la fluidité de la synthèse, ... C'est là que l'évaluation humaine intervient, en apportant une dimension qualitative et critique indispensable. ## Concevoir des protocoles de test adaptés L’évaluation d’un système RAG doit s’appuyer sur des **protocoles de test différenciés selon les phases du projet**. Les objectifs, les critères d’évaluation et les profils mobilisés ne sont pas les mêmes selon que l’on se situe dans une phase de validation métier ou dans une phase d’usage opérationnel. ### Distinguer les phases d’évaluation 💡 Lors des premières phases d’évaluation de l'assistant conversationnel, en cas d’absence de référents métiers, l’équipe projet peut porter un regard critique «naïf» sur les réponses produites par l’assistant conversationnel. Sans disposer d’une connaissance experte de la réponse attendue, l’équipe est généralement en capacité d’identifier les réponses manifestement incorrectes, incohérentes ou hors sujet. Cette première analyse permet ainsi de disposer d’une autonomie initiale dans les phases amont de l’évaluation. La mobilisation des référents métiers intervient alors de manière plus ciblée, lorsque l’équipe estime que la majorité des réponses n’est plus clairement erronée mais potentiellement correcte, et que l’enjeu porte désormais sur la justesse fine, la conformité métier et la valeur d’usage. **Phase 1 – Évaluations métiers** Les premières évaluations, ou les évaluations liées aux évolutions du système, doivent être menées par des experts métiers (sachants). Leur rôle est de valider la qualité métier du moteur en cours de construction, indépendamment des conditions réelles de déploiement. Ces tests visent notamment à : * vérifier la pertinence fonctionnelle des réponses ; * contrôler l’exactitude et la fiabilité des informations produites ; * identifier les lacunes documentaires ou les défauts de raisonnement du système. **Phase 2 – Tests utilisateurs (beta-tests)** Une fois la qualité métier jugée satisfaisante par les sachants, des tests utilisateurs élargis pourront être engagés. Ils impliquent un cercle plus diversifié d’agents publics, représentatif des futurs utilisateurs finaux. Cette phase vise à évaluer : * l’impact réel de l’outil sur les pratiques professionnelles ; * l’appropriation par les équipes ; * la compréhension des réponses et la confiance accordée au système. ## Tester dans des conditions proches de l’usage réel Pour évaluer un système RAG, il est essentiel de **simuler des questions réelles d'utilisation**. Cela peut inclure : * Des **questions types** représentatives des cas d'usage (ex. : questions techniques pour un assistant juridique, demandes grand public pour un chatbot usager). * Des **scénarios de "stress test"** : * des questions comportant des ambiguïtés, des fautes d’orthographe ou une formulation imprécise ; * Questions pièges pour évaluer la robustesse (ex. : "Quelle est la capitale de la France en 2050 ?"). * Questions liées à l'éthique, à la discrimination, et aux biais Lors de la session d'évaluation, les référents métiers formulent le plus souvent des questions directement issues de leur **expérience professionnelle et de situations concrètes rencontrées**** au quotidien**. Ces questions spontanées constituent une source précieuse d’évaluation, car elles reflètent fidèlement les usages réels et les attentes opérationnelles. En complément, l’équipe projet peut **préparer en amont un ensemble de questions types**, organisées par thématiques ou par cas d’usage. Cette préparation permet de structurer les séances d’évaluation, de garantir une couverture homogène des principaux scénarios et de faciliter la comparaison des résultats dans le temps. La combinaison de questions spontanées issues du terrain et de scénarios préparés en amont offre ainsi un **équilibre efficace entre réalisme, exhaustivité et reproductibilité** dans l’évaluation de l’assistant conversationnel. Afin d’harmoniser et de rendre exploitables les retours des référents métiers et des testeurs, il est recommandé d’utiliser une **grille d’évaluation standardisée et la possibilité de compléter la notation par une annotation**, dont on propose des exemples ci-dessous : | **Critère** | **Description** | | ------------------------------- | ---------------------------------------------------------------------------------------- | | **Pertinence des sources** | Les documents récupérés sont-ils adaptés à la question et à jour ? | | **Exactitude des informations** | Les informations extraites et générées sont-elles correctes ? | | **Fidélité à la génération** | La réponse reflète-t-elle fidèlement les sources, sans déformation ni hallucination ? | | **Transparence** | Le système cite-t-il clairement ses sources et indique-t-il ses limites ? | | **Fluidité de la réponse** | La réponse est-elle naturelle, bien structurée et facile à comprendre ? | | **Robustesse aux ambiguïtés** | Le système gère-t-il les questions mal formulées ou complexes de manière satisfaisante ? | | **Absence de biais** | Les sources et la réponse sont-elles exemptes de biais (culturels, idéologiques, etc.) ? |

Illustration des critères d'évaluation dans l'outil

**Annoter les réponses pour une analyse fine** L'annotation manuelle des réponses est une mine d'or pour l'équipe. Elle permet d'identifier des **patterns d'erreurs** ou des **points forts** récurrents. Les référents peuvent, par exemple : * Surligner les passages **fidèles aux sources** et ceux qui sont **générés ou extrapolés ;** * Signaler les **incohérences**, imprécisions ou manques de clarté ; * Identifier un besoin de précision sur les acronymes. Cette même grille peut s'appliquer pour les premières expériences de beta-tests afin de bien comprendre dès le départ les forces et les limites de l'outil. ## Impliquer des référents métiers et testeurs engagés > Des utilisateurs métiers motivés, critiques et engagés sont un levier clé pour améliorer la qualité et la pertinence d’un moteur d’IA dans la durée. Pour couvrir tous les angles, selon la phase d'évaluations, il est important de faire appel à des référents aux profils variés : * **Référents métiers** pour évaluer la **pertinence métier** des réponses. * **Utilisateurs finaux** pour tester la **clarté** et l'**utilisabilité**. Cette diversité permet de recueillir des retours complets et de s'assurer que le système est **robuste** dans différents contextes. **Cibler les bons profils dès le départ** L’implication de profils métiers dans l’évaluation d’un moteur d’IA représente un réel challenge. Cela leur demande un investissement en temps sur leurs horaires professionnels, un temps dont les agents publics ne disposent pas toujours. Par ailleurs, si les améliorations du moteur ne sont pas perçues comme suffisamment rapides ou qualitatives, un risque de démobilisation progressive peut apparaître. Dans ce contexte, il est recommandé de **limiter volontairement le nombre de participants lors des premières phases**. Un cercle restreint permet de mieux valoriser les contributions, de maintenir l’engagement et de piloter plus efficacement les retours. **Sélectionner des personnes motivées et lucides sur les limites de l’IA générative. Il est essentiel d’identifier des profils :** * **volontaires et impliqués**, prêts à consacrer du temps à l’expérimentation ; * disposant d’une **expertise métier avérée**, leur permettant d’évaluer la pertinence fonctionnelle, la justesse des réponses et l’adéquation aux usages réels pour les phases d'évaluation de la qualité métier de l'outil ; * **conscients des limites** de l’IA générative, afin de formuler des retours réalistes et exploitables ; * **motivés par l’amélioration de leurs pratiques professionnelles**, même s’ils ne sont pas experts de la technologie. Ces personnes ne sont pas nécessairement déjà convaincues ou technophiles. Elles peuvent se montrer sceptiques ou interrogatives, ce qui constitue un atout : leurs retours sont souvent plus exigeants, plus concrets et plus proches des usages réels que ceux de profils déjà acquis à la technologie. Selon les phases du projet, l’ensemble de ces critères n’est pas nécessairement requis. Le prérequis essentiel reste de s’appuyer sur des personnes motivées et engagées, faisant preuve d’enthousiasme et prêtes à s’investir dans la démarche. Ces profils sont généralement capables de dégager du temps pour participer activement aux travaux d’évaluation et sont souvent directement confrontés aux problématiques identifiées lors de la phase d’investigation, ce qui rend leurs retours particulièrement pertinents et actionnables. | | **Profils** | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | **Phase 1 – Évaluations métier** |

- volontaires et impliqués
- sachants
- conscients des limites

| | **Phase 2 – Tests utilisateurs (beta-tests)** |

- volontaires et impliqués
- motivés par l’amélioration de leurs pratiques professionnelles

| ## Alléger et structurer l’effort d’évaluation Les agents publics mobilisés comme testeurs ne disposent pas toujours, dans leur quotidien professionnel, du temps nécessaire pour contribuer régulièrement aux travaux d’évaluation. Cette participation peut alors être perçue comme une charge mentale supplémentaire : *« Il faut que j’évalue, quand vais-je trouver le temps ? »*, *« J’ai oublié »*, etc. Cette difficulté est particulièrement marquée lors de la constitution du jeu de données de référence, une activité exigeante, répétitive et souvent peu valorisante. Pour limiter ces freins, il est recommandé de mettre en place un accompagnement rapproché des phases de participation. L’objectif est de faciliter la collecte des retours tout en réduisant la dépendance à la disponibilité individuelle et aux contraintes organisationnelles des agents. Il est ainsi préférable de **privilégier des temps d’évaluation formalisés et organisés**, en bloquant des créneaux dédiés dans les agendas des participants. Il est en effet plus simple et moins contraignant pour un testeur de savoir, par exemple, que mardi de 10 h à 11 h est consacré aux évaluations, plutôt que de devoir intégrer cette tâche de manière diffuse dans son emploi du temps. Cette organisation contribue à alléger la charge mentale et à sécuriser la participation. La mise en place de sessions collectives et l’animation d’un véritable cercle de testeurs constituent des leviers efficaces d’engagement. Des temps partagés avec d’autres testeurs apportent une dimension plus conviviale et stimulante, en rupture avec le quotidien de travail, ce qui favorise la motivation et la régularité des contributions. Il est important d’anticiper que les premiers testeurs et expérimentateurs pourront, à terme, jouer un **rôle clé de relais**. En partageant leur retour d’expérience, en expliquant les objectifs et les bénéfices du projet, ils pourront devenir de véritables ambassadeurs au sein de leurs équipes et faciliter l’appropriation du dispositif à plus grande échelle # Jeu de données de référence ## Jeu de données de référence La création d’un **jeu de données de référence (golden dataset)** est un pré-requis à toute évaluation automatique fiable. Ce jeu de données regroupe un ensemble de questions représentatives des usages réels, associées à des **réponses attendues**, des **documents de référence**. Il permet notamment de : * comparer différentes versions du système RAG dans le temps ; * détecter des régressions fonctionnelles ; * mesurer l’impact des évolutions techniques (indexation, prompting, changement de modèle, etc.). Ce jeu de données devient votre **référence de qualité** pour suivre les progrès du produit dans le temps. C’est une base de scénarios typiques utilisateurs : * 20 à 50 questions réelles ou simulées sur une thématique * Pour chaque question : une **bonne réponse** (rédigée par un expert ou validée à la main) * Et la **source officielle** (document, base, page intranet…) * La date de création du couple questions-réponses et sa mise à jour Ce jeu de données, initié par la personne référent métier de l'équipe, doit être co-construit avec les référents métier expérimentateurs, **maintenu dans la durée et enrichi de manière itérative**, en particulier à partir des cas problématiques identifiés lors des évaluations humaines. 💡 Il n’est pas rare que l’équipe rencontre des difficultés lors de la construction du jeu de données de référence, notamment parce qu’il est complexe de définir *la* vérité terrain unique ou *la* réponse parfaitement correcte à une question donnée. Il est important de garder à l’esprit qu’**il peut exister plusieurs réponses acceptables**, et que l’objectif n’est pas d’identifier *la* bonne réponse, mais une réponse de référence cohérente et justifiable. **Les évaluations automatisées doivent ainsi être comprises comme des outils de mesure de tendance, visant à apprécier l’évolution de la qualité du système dans le temps plutôt qu’à produire des verdicts absolus**. Par ailleurs, de nombreuses métriques reposent sur des juges basés sur des modèles de langage, dont les résultats peuvent être non déterministes. Il est donc essentiel de conserver un recul critique sur les résultats d’évaluation. La valeur du jeu de données de référence réside avant tout dans sa capacité à permettre des comparaisons relatives entre versions du système, afin d’analyser les progrès, les régressions ou les effets de certaines décisions techniques, plutôt que de fournir une mesure exacte et définitive de la qualité. #### Construction d'un jeu de données de référence Selon les contraintes et le stade du projet, nous identifions trois approches principales pour construire un jeu de données de référence, approches que l’on peut également combiner : * Création du jeu de données de référence avec **des référents métier** Cette approche consiste à mobiliser des **experts du domaine** pour rédiger les couples de questions - réponses. C’est l’approche la plus robuste en termes de fiabilité. Les réponses servent de **vérités de référence** pour tester la factualité et la complétude des réponses de l’agent. Elle est particulièrement recommandée dans les **domaines sensibles** (santé, droit, réglementation) mais peut-être coûteuse en terme de mobilisation. * Création du jeu de données de référence **sur un historique de données réelles** Cette approche consiste à utiliser des données existantes (FAQ, historique de service usager, ...) ou les premières questions posées par de vrais utilisateurs en production. Les réponses générées par l’agent sont ensuite corrigées ou validées par des validateurs métier. Cette approche est idéale pour l’accélération et la pérennisation, quand l'outil est déjà utilisé par une communauté élargie. * Création du jeu de données de **référence "synthétique"** Cette approche consiste à générer des couples questions-réponses via un LLM, sur la base du corpus documentaire existant. On peut par exemple demander à un LLM de produire des questions que poserait un utilisateur et d’y répondre en s’appuyant sur les documents fournis. Cette approche est utile en début de construction, pour itérer vite et détecter rapidement les points faibles de l’agent mais elle doit être consolidée par d’autres méthodes sur le moyen / long terme. Ces données synthétiques peuvent également initier la collaboration avec des experts métier, qui corrigeront ou valideront la réponse générée par le LLM. # Evaluations automatisées {% hint style="info" icon="arrows-to-circle" %} **Automatiser l’évaluation du système RAG via des métriques de qualité, de conformité et de performance** {% endhint %} L'évaluation automatisée d’un système RAG désigne l’ensemble des méthodes et outils permettant de **mesurer de manière systématique, reproductible et à grande échelle** la qualité, la performance et la robustesse d’un assistant, sans intervention humaine directe sur chaque test. Elle repose généralement sur : * un [jeu de données de référence](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/jeu-de-donnees-de-reference) représentatif des usages réels ; * des métriques objectivables, correspondant aux critères de qualité attendus, appliquées à la fois à la recherche documentaire (retriever) et à la génération de réponses ; * des outils d’exécution et de comparaison automatique, permettant d’évaluer différentes versions du système dans le temps. L’évaluation automatique ne se substitue pas à l’évaluation humaine, indispensable pour juger la pertinence métier, l’utilité et la confiance, mais constitue un **socle indispensable pour avoir une équipe autonome dans l'évolution de l'outil et industrialiser le pilotage de la qualité d’un système RAG**, en particulier lors du passage à l’échelle et en production. L'effort de la mise en place repose sur l'ensemble de l'équipe : les profils métier sur la création du jeu de données de référence et les profils techniques sur l'implémentation technique des évaluations automatisées. ## Critères de qualité attendus et métriques associées L’évaluation de la qualité d’un système RAG ne peut pas se limiter à un indicateur unique. La performance globale d’un assistant conversationnel repose sur plusieurs dimensions complémentaires, qu’il est nécessaire de définir en amont pour éviter toute analyse partielle ou biaisée. La première étape consiste donc à **clarifier les critères de qualité attendus au regard des usages métier**. * **Pertinence** La pertinence constitue un premier critère fondamental. Il s’agit d’évaluer si **la réponse produite correspond réellement à la question posée** par l’utilisateur. Cette analyse ne porte pas uniquement sur le contenu textuel de la réponse, mais également sur son **adéquation avec l’intention exprimée et sur la pertinence des sources mobilisées**. Une réponse peut être techniquement correcte tout en étant mal orientée ou insuffisamment contextualisée par rapport au besoin réel. * **Fidélité** La **fidélité aux sources** représente un second critère essentiel. Dans un système RAG, la réponse doit être strictement ancrée dans les documents récupérés par le moteur de recherche. Il convient donc de vérifier que le contenu généré reflète fidèlement les informations présentes dans les sources et qu’aucun élément n’est inventé ou extrapolé de manière abusive.\ \ La capacité du système à **s’abstenir de répondre** lorsqu’aucune information pertinente n’est disponible constitue également un indicateur important de maturité et de fiabilité. * **Performance de l'expérience :** La qualité d’un système RAG ne se limite toutefois pas au contenu informationnel. La performance de l’expérience utilisateur doit également être prise en compte. La **rapidité** de réponse, la **stabilité du service** et, dans certains contextes, la **consommation de ressources** ou le **coût énergétique** participent à l’évaluation globale. Un assistant précis mais trop lent ou instable peut difficilement être déployé à grande échelle. Ces différents **critères doivent être analysés à la lumière de l’architecture** même du système. Pour mémoire, un RAG repose sur deux composants étroitement interdépendants : * le moteur de recherche (retriever), chargé d’identifier les documents pertinents dans la base de connaissances, * le modèle de génération (LLM), qui rédige la réponse à partir des éléments récupérés. **Les métriques d’évaluation doivent donc couvrir ces deux briques distinctes, en mesurant à la fois la qualité de la recherche documentaire et celle de la génération.** **Dans la pratique**, les critères métier sont traduits en familles de métriques implémentées par les profils techniques de l’équipe. À terme, ces indicateurs ont vocation à être automatisés, visualisables dans des tableaux de bord et partagés avec les profils fonctionnels afin d’objectiver les décisions d’amélioration. {% hint style="info" %} *Il existe peu de références universelles sur les seuils à atteindre pour considérer qu’un système RAG est satisfaisant. Une approche pragmatique consiste à définir d’abord les critères métier prioritaires, à les décliner en métriques mesurables, puis à établir une baseline sur la première version du système. Les évolutions ultérieures doivent viser une amélioration progressive de cette baseline, tout en étant systématiquement confrontées aux retours utilisateurs, qui demeurent un indicateur déterminant de la qualité réelle perçue.* {% endhint %} Les **métriques** permettent de mesurer, **de manière standardisée, l’écart entre la réponse produite par le système et la réponse attendue** sur différents critères d'analyse. Ces métriques sont généralement calculées à partir d’un jeu de données de référence. Pour chaque question de ce jeu, le système génère une réponse qui est ensuite comparée à la réponse attendue définie en amont. Cette démarche permet d’objectiver les progrès, d’identifier les régressions et d’ancrer l’amélioration du système dans une logique mesurable et continue. Nous décrivons, de manière théorique, quatre grande familles de métriques avec des objectifs de mesure complémentaires. ## Familles de métriques #### Métriques liées à la récupération (Retriever) Ces métriques évaluent la capacité du système à **identifier et sélectionner les documents pertinents** en amont de la génération : * taux de rappel et de précision des documents récupérés ; * position des documents pertinents dans les résultats (ranking) ; * couverture des sources attendues. Une faiblesse à ce niveau impacte mécaniquement la qualité de la réponse finale, indépendamment du modèle de langage utilisé. #### Métriques liées à la génération de la réponse (LLM) Les métriques de génération visent à évaluer la **qualité du texte produit** à partir des documents récupérés : * cohérence et complétude de la réponse ; * fidélité aux sources (absence d’hallucination) ; * adéquation avec la réponse attendue du jeu de référence. Certaines métriques reposent sur des comparaisons textuelles, tandis que d’autres utilisent des modèles de langage comme juges\* pour évaluer la qualité ou la conformité des réponses. #### Métriques liées à l'éthique et la conformité Il est également nécessaire d’intégrer des métriques spécifiques pour : * détecter des biais potentiels (culturels, sociaux, idéologiques) ; * identifier des réponses discriminantes ou inappropriées ; * vérifier le respect des règles de sécurité, de neutralité et de conformité réglementaire. #### Métriques liées aux performances techniques Enfin, l’évaluation automatique doit inclure des métriques techniques, telles que : * le temps de réponse ; * la stabilité du système ; * le taux d’erreurs ou d’échecs ; * la consommation de ressources (CPU, mémoire, appels API) * la consommation énergétique Ces éléments conditionnent directement l’expérience utilisateur et la capacité de passage à l’échelle. Le calcul des métriques s'effectue sur la base d'un jeu de données de référence. ## Métriques simples pour évaluer un assistant RAG Pour démarrer la construction d'un assistant conversationnel basé sur un système RAG, parmi l'ensemble des métriques disponibles, nous préconisons un sous-ensemble de démarrage : | Métrique | pour vérifier que l'outil | composant | | ---------------------- | ---------------------------------------------------- | ---------- | | Recall\@k | trouve les bons documents | retriever | | Precision\@k | évite le bruit | retriever | | Faithfulness | s'ancre dans les sources | generation | | Answer Relevancy | répond utilement à la question | generation | | Toxicity, biais | évite les contenus nocifs | generation | | Multi-turn consistency | conserve le contexte tout au long de la conversation | generation | | Latence | est réactif pour les utilisateurs | infra | | Consommation | reste frugal compte tenu du besoin fonctionnel | infra | Ces métriques forment un baromètre équilibré automatisable quotidiennement sans annotation humaine coûteuse. Elles couvrent les trois dimensions critiques d’un système RAG conversationnel : * Qualité du retrieval (contexte) * Qualité de la génération (réponse) * Sécurité et conformité Ce socle constitue une base générique extensible, pouvant être enrichie selon les exigences métier et techniques. #### Evaluation la récupération (retriever) {% hint style="info" icon="cubes-stacked" %} #### Recall\@k **Question clé** : est-ce que les documents nécessaires à la réponse sont présents parmi les k premiers résultats ?\ **Mesure :** évalue si l’information nécessaire à la bonne réponse est bien présente dans le contexte transmis au modèle de génération. **Formule :** Recall\@k = (Documents pertinents retrouvés dans le top-k) / (Documents pertinents attendus) **Échelle :** Score de 0 à 1 **Exemple d’interprétation :** > 3 documents sont considérés comme pertinents pour répondre à une question.\ > Le système en retrouve 2 dans les 5 premiers résultats (k=5) → Recall\@5 = 2 / 3 = **0,67**\ > Le retriever retrouve une majorité des documents utiles, mais pas tous. **Points d’attention** * dépend fortement de la qualité du jeu de données de référence (gold set) * Peut être élevé même si les résultats contiennent beaucoup de bruit {% endhint %} {% hint style="info" icon="cubes-stacked" %} #### Precision\@k **Question clé** : parmi les documents récupérés, combien sont réellement utiles ? **Mesure :** évalue si les documents proposés dans les k premiers résultats sont réellement pertinents, ou s’ils contiennent du bruit. **Formule :** Precision\@k = (Documents pertinents retrouvés dans le top-k) / k **Échelle :** Score de 0 à 1 **Exemple d’interprétation :** > Le système retourne 5 documents (k=5).\ > 3 sont réellement pertinents → Precision\@5 = 3 / 5 = **0,60**\ > Les résultats contiennent encore du bruit, mais une majorité est pertinente **Point d'attention** Dans des environnements complexes, il peut être pertinent d’ajouter : * F1\@k (équilibre Recall / Precision) * MRR (Mean Reciprocal Rank) pour mesurer la position du premier document pertinent {% endhint %} #### Evaluation de la génération {% hint style="info" icon="cubes-stacked" %} #### Faithfulness **Question clé** : la réponse est-elle strictement basée sur les informations fournies ? **Mesure :** évalue la fiabilité factuelle du système **Formule** **:** une réponse est fidèle si toutes ses affirmations factuelles peuvent être justifiées par les documents sources fournis.\ Score de fidélité = (Assertions correctes) / (Assertions totales)\ ou Score de fidélité LLM = un modèle évaluateur attribut un score de fidélité en comparant réponse et contexte **Échelle :** Score de **0 à 1** **Exemple d’interprétation :** > Contexte : “La Tour Eiffel a été inaugurée en 1889.”\ > Réponse : “La Tour Eiffel a été construite en 1895.” → **0.2 (faible fidélité)** **Point d'attention** * Faithfulness ≠ exactitude absolue * Une réponse peut être factuellement vraie mais non fidèle si l’information n’est pas dans le contexte {% endhint %} {% hint style="info" icon="cubes-stacked" %} #### Answer relevancy **Question clé** : la réponse traite-t-elle vraiment la demande de l’utilisateur ? **Mesure :** analyse la similarité de sens entre la question et la réponse **Formule -** deux approches combinables : * évaluation par un modèle juge si la réponse à la question pour déterminer si elle y répond complètement, partiellement ou pas du tout. * calcul de similarité sémantique via embeddings vectoriels (cosine similarity). **Échelle :** score continu entre **0** (hors sujet) et **1** (parfaitement pertinent). **Exemple d’interprétation :** > Question : “Qu’est-ce qu’un modèle de langage ?”\ > Réponse A : “C’est un système d’IA entraîné à prédire du texte.” → **0.95**\ > Réponse B : “Les modèles d’IA peuvent générer des images.” → **0.4** **Point d'attention** * La similarité vectorielle ne capture pas toujours la complétude * Un score élevé ne garantit pas la correction factuelle {% endhint %} #### Evaluation de la sécurité et de la conformité {% hint style="info" icon="cubes-stacked" %} #### Toxicity **Question clé :** la réponse contient-elle des propos agressifs, insultants ou haineux ? **Mesure :** détecte la présence de contenu offensant, violent ou discriminant. **Formule** * Modèles spécialisés de classification * Score probabiliste de toxicité * Détection multi-classes (insulte, menace, harcèlement, etc.) **Échelle :** 0 à 1 **Exemple d’interprétation :** > Réponse : “C’est une idée stupide.” → **0.4**\ > Réponse : “Tu es un imbécile.” → **0.9** **Point d'attention** * Sensibilité au contexte culturel * Faux positifs possibles dans certains débats {% endhint %} {% hint style="info" icon="cubes-stacked" %} #### Bias **Question clé :** la réponse contient-elle des préjugés, des stéréotypes ou des jugements discriminants ? **Mesure :** analyse pour détecter les signes de partialité. **Formule** * Analyse lexicale et sémantique * Tests contrastifs (même requête avec variables démographiques modifiées) * Évaluation par LLM-as-judge ou humain **Échelle :** 0 à 1 **Exemple d’interprétation :** > “Les jeunes sont forcément moins compétents.” → **0.9 (biais fort)** > {% endhint %} {% hint style="info" icon="cubes-stacked" %} #### **Consistency** (multi-turn) **Question clé** : le modèle reste-t-il cohérent au fil des échanges ? **Mesure** : compare les affirmations précédentes avec les nouvelles réponses **Formule** : consistency = (Assertions cohérentes) / (Assertions comparées) **Echelle** : 0 à 1 **Exemples d'interprétation** > Réponse 1 : “Votre contrat dure jusqu'en novembre.”\ > Réponse 4 : "Votre contrat dure jusqu'en mars\ > → **incohérence** > {% endhint %} #### Evaluations des performance technique {% hint style="info" icon="cubes-stacked" %} #### Latence **Question clé** : le système répond-il suffisamment vite pour garantir une expérience utilisateur fluide? **Mesure** : mesure le temps moyen de réponse\ **Formule** : * Latence moyenne = (Somme des temps de réponse) / (Nombre total de requêtes) * Percentile - P95 = valeur en dessous de laquelle se situent 95 % des temps de réponse. **Unité** : ms ou secondes **Exemples d'interprétation** > Si 1 000 requêtes ont été traitées :\ > Moyenne = 2,4 s\ > P95 = 4,8 → 95 % des utilisateurs reçoivent une réponse en moins de 4,8 secondes.\ > 5 % subissent une latence plus élevée. > {% endhint %} {% hint style="info" icon="cubes-stacked" %} #### Consommation énergétique **Question clé** : Quelle quantité d’énergie est nécessaire pour produire une réponse ? **Mesure** : consommation énergétique moyenne par requête / token généré / conversation complète **Formule** * Consommation moyenne par requête = (Énergie totale consommée sur une période) / (Nombre total de requêtes) * Consommation par token = (Énergie totale consommée) / (Nombre total de tokens générés) **Unité** : Wh ou kWh **Exemple d'interprétation** > Sur une journée : Énergie totale consommée de12 kWh pour 10 000 requêtes traitées\ > Consommation moyenne = 12 000 Wh / 10 000 = 1,2 Wh par requête\ > Si une version optimisée descend à 0,8 Wh par requête, le système devient 33 % plus efficient à qualité équivalente. > {% endhint %} *** *\* 💡 Prendre en compte le coût des modèles de langage utilisés comme juges* *Lorsque des modèles de langage sont utilisés pour évaluer automatiquement les réponses (LLM-as-a-judge), il est indispensable d’intégrer une analyse de coût dans la stratégie d’évaluation.* *Chaque appel à un LLM génère :* * *un coût financier, idéalement coût par point de qualité gagné (qualité vs coût) ;* * *une latence supplémentaire ;* * *une empreinte énergétique non négligeable.* *Sinon on risque d’avoir un système “bien évalué” mais une boucle d’évaluation trop chère/lente pour itérer. Les bonnes pratiques d’évaluations insistent sur la conception d’évaluations adaptées à la prod (coût/latence/fiabilité)* *Il convient donc de :* * *réserver ces métriques aux phases ou aux cas à forte valeur ajoutée ;* * *limiter leur usage à des échantillons représentatifs plutôt qu’à l’ensemble des données ;* * *arbitrer entre modèles plus ou moins coûteux selon le niveau de finesse attendu.* # Sources de régression en production *Page en construction* {% hint style="info" icon="arrows-to-circle" %} **Comprendre pourquoi un agent conversationnel RAG peut voir ses performances se dégrader en production, et l'importance du cycle d'évaluations continu** {% endhint %} Un agent conversationnel RAG peut afficher des résultats moins bons en production pour de nombreuses raisons, qui tiennent autant à l’évolution du contexte réel d’usage qu’aux contraintes techniques et organisationnelles. **Un système RAG ne “se dégrade” pas spontanément en production : il est exposé à des usages réels, des données vivantes et des contraintes opérationnelles que seule une évaluation continue permet de maîtriser**. Pour appuyer l'importance de mesurer régulièrement la qualité du système et l'ensemble des composants, voici quelques facteurs d'explication d'une dégradation de la satisfaction des utilisateurs. #### Écart entre les usages réels et les hypothèses de conception En production, les utilisateurs posent : * des questions plus variées, ambiguës ou mal formulées ; * des demandes hors périmètre initial ; * des questions multi-intentions ou conversationnelles longues. Le jeu de tests initial ne couvre pas toujours cette diversité, ce qui dégrade la pertinence perçue des réponses. #### Évolution ou dérive de la documentation (data drift) La base documentaire évolue en continu : * ajout de nouveaux documents ; * mise à jour ou suppression de contenus existants ; * coexistence de versions contradictoires. Ces changements peuvent altérer la qualité du retrieval, introduire du bruit ou des incohérences, sans modification du modèle lui-même. #### Problèmes de retrieval à l’échelle À mesure que le volume de documents augmente : * les embeddings deviennent moins discriminants ; * le moteur de recherche remonte plus de documents non pertinents ; * le contexte fourni au LLM se dégrade. Même un bon modèle de génération ne peut compenser un mauvais contexte. #### Contraintes de performance et d’optimisation en production En production, des arbitrages sont souvent faits sur : * la taille du contexte ; * le nombre de documents récupérés ; * le modèle utilisé (coût / latence). Ces optimisations peuvent réduire la qualité par rapport à l’environnement de test. #### Évolution du modèle ou des dépendances techniques * mise à jour du LLM (nouvelle version, nouveau fournisseur) ; * modification des embeddings ; * évolution des librairies ou des paramètres par défaut. Ces évolutions peuvent introduire des régressions invisibles sans évaluation systématique. #### Effets de charge et de montée à l’échelle Sous forte charge : * augmentation de la latence ; * timeouts ; * comportements dégradés ou incomplets. L’expérience utilisateur se dégrade, même si la qualité intrinsèque reste correcte. #### Problèmes de sécurité et de garde-fous En production : * manœuvres visant à contourner les règles ou les limites, exploitation des failles techniques de l'outil * prompts utilisateurs imprévus ; * conflits entre règles de sécurité et qualité de réponse. Des garde-fous trop stricts ou mal calibrés peuvent conduire à des refus excessifs ou à des réponses vagues. # Evaluations continues {% hint style="info" icon="arrows-to-circle" %} **Mettre en place un cycle d’évaluation continue en production pour piloter simultanément l’évolution du système, le monitoring des performances et la satisfaction des utilisateurs** {% endhint %} Une fois l’assistant déployé en production, les besoins d’évaluation évoluent. Il ne s’agit plus uniquement de valider la faisabilité ou la qualité initiale du système, mais de **piloter sa performance dans la durée**, d’accompagner la montée en charge et de garantir une valeur constante pour les utilisateurs. Nous pouvons donc distinguer deux catégorie d'évaluations : * les évaluations off-line dans lesquelles s'inscrivent les évaluations par les référents métier et les évaluations automatisées présentées dans les pages précédentes. La matière première est le jeu de données de référence en phase de développement, puis peut devenir les traces en phase de production. * les évaluations on-line (en temps réel) dont la matière première correspond aux interactions des utilisateurs avec l'application en production {% hint style="info" %} Ce guide vous accompagne dans les premières étapes de la conception de votre assistant conversationnel, fondé sur une architecture RAG. Il propose des éléments clés pour structurer un cycle complet d’évaluation et de monitoring de l’outil, sans entrer dans les détails techniques lors d'un passage à l'échelle. {% endhint %} Tout au long du cycle, vous surveillez des alertes sur les métriques critiques (baisse de performance, augmentation de latence, diminution de la satisfaction utilisateurs) et maintenez un tableau de bord avec l'évolution des indicateurs clés dans le temps. D'une manière générale, les évaluations en production incluent automatisation et humains : * **Automatique** : métriques continues sur le jeu de données de référence, qui peuvent être approfondies après les premières phases de construction. 🏗️​Évaluations automatisées * **Humain** : une équipe de référents vérifie ponctuellement / régulièrement un échantillon de résultats récents, notamment pour les cas de "référence" ou les cas problématiques identifiés par le monitoring * **Retours utilisateurs** : métriques d'usage et satisfaction des utilisateurs Il s'agit de créer un **compromis** : pas d'humain à chaque itération (trop coûteux), mais pas d'absence totale (trop risqué).

Illustration des évaluations selon la phase de développement

#### Déroulé du cycle d'évaluations continues * **Observer et collecter des données de performance :** Feedbacks utilisateurs, conversations, signaux d’adoption. * **Mesurer automatiquement :** qualité RAG (retrieval & génération), performances, conformité. * **Analyser et qualifier :** revue humaine ciblée des cas en échec ou à risque. * **Décider :** Ajustement du corpus, des prompts, du modèle ou des règles. * **Tester et déployer :** évaluations en pré-production, puis monitoring post-déploiement. * **Enrichir :** jeux de données de références, métriques, process Le cycle se répète en continu, en intégrant progressivement les nouveaux usages dans le référentiel d’évaluation. **Collecter -> Mesurer -> Analyser -> Prioriser -> Développer -> Tester -> Déployer -> Enrichir** ## Observer et collecter des données de performance Le cycle démarre par la collecte de signaux issus de l’utilisation réelle de l’assistant : * conversations utilisateurs (les requêtes posées, les documents retrievés, les réponses générées) * feedbacks explicites (notes, commentaires, signalements) ; * données d’usage (fréquence, récurrence, abandons). Au-delà des métriques spécifiques à l’IA (fidélité, précision du retrieval, hallucinations, etc.), les **indicateurs produit classiques jouent également un rôle déterminant**. Le taux d’adoption, la fréquence d’usage, la récurrence des utilisateurs, la durée des sessions ou encore le taux d’abandon fournissent des informations précieuses sur la valeur réelle perçue par les agents. Un assistant techniquement performant mais peu utilisé révèle souvent un problème de positionnement, d’ergonomie ou de confiance. Croiser métriques IA et métriques produit permet ainsi d’obtenir une vision complète : qualité technique d’un côté, utilité et appropriation de l’autre. L'objectif est donc de collecter les informations nécessaires pour comprendre comment le système est réellement utilisé, identifier les cas utiles, les irritants et les zones de risque. ## Mesurer de manière automatique En parallèle, des **évaluations automatisées** sont exécutées de manière régulière ou déclenchées par un événement (nouvelle version, mise à jour documentaire). Elles s’appuient sur : * le [**jeu de données de référence**](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/jeu-de-donnees-de-reference) ; * les [**métriques RAG**](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/evaluations-automatisees) couvrant les métriques définies pour le système : * la recherche documentaire (ex. Recall\@k, Precision\@k) ; * la génération (fidélité aux sources, pertinence) ; * la performance technique (latence, taux d’erreur, coût). * la satisfaction utilisateur (basée sur les feedbacks explicites ou implicites) L'objectif est de **détecter rapidement des régressions, mesurer les gains ou pertes liés aux évolutions** du système. Ces métriques peuvent être exécutées de manière hebdomadaire une fois l'assistant conversationnel en production dans l'optique d'être alerté spontanément en cas de régression du système. ## Analyser les usages L’analyse vise une compréhension approfondie des usages réels. Il s’agit d’examiner les informations collectées et / ou mesurer (conversations, les requêtes fréquentes ou atypiques, les abandons et les retours utilisateurs) afin d’**identifier les besoins sous-jacents, explicites ou implicites**. Les métriques automatiques constituent un point d’alerte, mais leur interprétation doit s’appuyer sur une analyse humaine structurée : revue de conversations représentatives, compréhension métier des cas en difficulté, et distinction entre incident ponctuel et tendance significative. Cette approche permet de remonter aux causes profondes des défaillances — qu’elles relèvent du retrieval, de la génération, du corpus documentaire ou du cadrage produit — et d’orienter les priorités d’amélioration en cohérence avec les usages réels. L’équipe doit donc **régulièrement analyser un échantillon de questions-réponses en production** pour comprendre comment l’assistant est réellement utilisé, dans quels contextes, et avec quelles attentes. Cette lecture qualitative permet de détecter des décalages entre le périmètre initial et les usages observés, de repérer des besoins émergents ou mal couverts, et d’identifier des zones de fragilité dans le système. {% hint style="info" %} Alors que les projets numériques nécessitent souvent des enquêtes spécifiques pour identifier les besoins non couverts (interview utilisateur, sondage, retours utilisateurs), un assistant conversationnel offre un accès direct aux attentes des utilisateurs : chaque question posée reflète un besoin réel. Les données d’usage deviennent ainsi un levier central pour nourrir la feuille de route produit. {% endhint %} ## Décider et prioriser les améliorations Sur la base de ces analyses, l'équipe définit et priorise les actions correctives ou évolutives : * enrichissement ou nettoyage du corpus documentaire ; * ajustement des paramètres de recherche ; * évolution des prompts ou du modèle ; * ajout de garde-fous ou règles de refus ; * réflexion sur le périmètre du produit et priorisation des cas d'usage. L'objectif est de **concentrer les efforts là où l’impact utilisateur est le plus fort**. {% hint style="info" %} #### Rédaction d'un besoin fonctionnel Dans le cadre d’un assistant conversationnel, les spécifications fonctionnelles gagnent à être formulées de manière très concrète, en s’appuyant sur la logique besoin = questions / réponses. Plutôt que de décrire uniquement des fonctionnalités, il est recommandé d’exprimer le besoin métier sous forme de situations réelles :\ \- Quelles questions un utilisateur doit-il pouvoir poser ?\ \- Dans quel contexte ?\ \- Quel type de réponse est attendu (explication synthétique, référence réglementaire, procédure détaillée, renvoi vers une source) ?\ \ Cette approche permet d’ancrer les spécifications dans l’usage réel et de constituer progressivement un jeu de cas représentatifs.\ \ Les critères d’acceptation doivent ensuite être traduits en niveaux de qualité mesurables, adossés à des métriques dont il convient de préciser le niveau attendu.\ \ Pour chaque question représentative, on définit la réponse attendue et les indicateurs permettant d’évaluer objectivement si le système est conforme. Cette articulation entre cas d’usage concrets et métriques cibles facilite le pilotage des itérations et limite les débats subjectifs sur la “qualité” de l’assistant. {% endhint %} ## Tester les évolutions en pré-production Avant déploiement, les modifications techniques sont évaluées en pré-production via les [évaluations automatisées](/guides/guide-de-construction-dun-assistant-conversationnel-base-sur-du-rag/evaluations-automatisees) : * exécution des évaluations automatiques sur le jeu de données de référence ; * comparaison avec la version en production ; * validation humaine sur un échantillon critique. L'objectif est de s’assurer que l’évolution améliore le système sans introduire de nouveaux risques. ## Déployer et monitorer Le cycle recommence régulièrement (quotidien, hebdomadaire, mensuel selon l'évolution du système), permettant une amélioration incrémentale et adaptée à l'usage réel.
Une fois déployée, la nouvelle version est monitorée en continu : * suivi des métriques clés ; * observation de la satisfaction utilisateur ; * surveillance des signaux de dérive ou de non-conformité. L'objectif est de **sécuriser la mise en production** et détecter rapidement tout comportement inattendu. ## Boucler et enrichir le référentiel d’évaluation Enfin, le cycle se referme par : * l’enrichissement du jeu de données de référence avec de nouveaux cas réels ; * l’ajustement des métriques ou des seuils ; * l’amélioration des processus d’évaluation eux-mêmes. **L'objectif est de faire évoluer le dispositif d’évaluation au même rythme que le système et ses usages.** # Les enjeux d'acculturation {% hint style="info" icon="arrows-to-circle" %} **Anticiper les enjeux de communication, formation, de transformation des pratiques** {% endhint %} La mise en production d’un assistant conversationnel basé sur l’IA ne constitue pas uniquement un projet technique. Elle s’accompagne d’enjeux forts de formation, d’appropriation et de transformation des pratiques professionnelles. Sous-estimer ces dimensions expose le projet à un risque de non-adoption, de mésusage ou de perte de confiance de la part des utilisateurs, indépendamment de la qualité technique du système. ## Repositionner l’assistant conversationnel comme un outil d’aide L’un des enjeux majeurs de la transformation consiste à **placer l’assistant conversationnel à sa juste place** : celle d’un outil d’aide à la décision, à la recherche d’information ou à la formulation, et non celle d’un substitut à l’expertise humaine. La formation doit insister sur le fait que : * l’assistant soutient le travail des agents, sans le remplacer ; * la responsabilité finale reste humaine ; * l’esprit critique demeure indispensable. Ce positionnement est essentiel pour favoriser une adoption durable, préserver les compétences métiers et intégrer l’IA comme un levier d’amélioration des pratiques, et non comme une contrainte ou une menace. ## Communiquer clairement sur le périmètre et les limites de l’outil La confiance dans un assistant IA repose en grande partie sur une **compréhension claire de ce qu’il peut et ne peut pas faire**. Une communication insuffisante sur le périmètre fonctionnel et les limites de l’outil peut conduire à : * des attentes irréalistes ; * des usages hors périmètre ; * une dégradation rapide de la confiance en cas d’erreur. Il est donc indispensable d’expliquer aux utilisateurs : * les types de questions pour lesquelles l’assistant est pertinent ; * le périmètre métier qu'il couvre aux moments de l'utilisation ; * les situations dans lesquelles il peut être en difficulté ; * les règles de prudence et de vérification à adopter. Cette transparence contribue à un usage responsable et maîtrisé de l’assistant. {% hint style="info" %} 👉 pour aller plus loin, exemple de la [documentation de l'Assistant IA](https://doc.incubateur.net/alliance/assistant-ia) 👉 pour aller plus, [guide l'usage de l'IA](https://ia.numerique.gouv.fr/ressources/guide-dusage-de-lia/) 👉 pour aller plus loin, [exemples de chartes d'usage de l'IA](https://ia.numerique.gouv.fr/ressources/portail-des-chartes-ia-dans-ladministration/) {% endhint %} #### L’importance de l’UX et du wording dans la perception de l’IA Au-delà des messages explicatifs, la conception de l’interface (UX) et le choix des mots jouent un rôle déterminant dans la manière dont les utilisateurs comprennent et utilisent l’assistant. Plusieurs éléments sont particulièrement structurants : * la présence de **messages d’alerte ou de rappel indiquant que l’assistant repose sur une IA**, qu’il peut se tromper et qu’il ne remplace pas l’expertise humaine (exemple : "L'IA peut commettre des erreurs. Il est recommandé de vérifier les informations.") * un **vocabulaire clair et non ambigu pour les mécanismes d’évaluation** (par exemple : distinguer la *pertinence* de la réponse, son *utilité* pour l’utilisateur, ou sa *clarté*, afin d’éviter toute confusion) ; * l’**affichage explicite des sources** utilisées pour générer la réponse, lorsque cela est possible, afin de renforcer la transparence et la confiance ; * la mise en évidence du fonctionnement du système IA développé (exemples : "recherche dans les données, "accès à internet" ...) * la **mise en évidence visuelle des limites du système** (périmètre non couvert, latence, ...). Ces choix d’UX et de formulation contribuent à encadrer les usages, à limiter les interprétations erronées et à installer une relation de confiance réaliste entre l’utilisateur et l’assistant. Une interface bien conçue ne se contente pas de “présenter” l’IA : elle guide l’utilisateur dans un usage responsable, critique et éclairé de l’outil. ## Développer la capacité à bien questionner l’assistant Un assistant conversationnel n’est pas un moteur de recherche traditionnel : **la qualité des réponses dépend fortement de la formulation des questions**. Il est donc essentiel d’accompagner les utilisateurs dans l’apprentissage de nouvelles pratiques, notamment : * comprendre comment structurer une instruction (prompt) claire et contextualisée ; * savoir reformuler une question lorsque la réponse est incomplète ou imprécise ; * utiliser le dialogue pour affiner progressivement une réponse. Former au prompting ne vise pas à transformer les utilisateurs en experts techniques, mais à leur donner les réflexes nécessaires pour interagir efficacement avec l’outil dans leur quotidien professionnel. {% hint style="info" %} 👉 pour aller plus loin, [atelier de pratique du prompting animé par le Campus du Numérique](https://www.campus.numerique.gouv.fr/catalogue/atelier-de-pratique-du-prompting/) {% endhint %} # Les enjeux juridiques {% hint style="info" icon="arrows-to-circle" %} **Sensibiliser les équipes** sur les enjeux juridiques de leur projet. {% endhint %} Les enjeux juridiques se pensent dès le début du projet. C'est pour cela qu'il est nécessaire d'aller consulter le service juridique de votrz administration de ratttachement dès le début afin que votre projet puisse évoluer en toute conformité. {% hint style="warning" %} En cas de non respect des différents cadres juridiques évoqués en dessous, les risques peuvent aller de l'annulation de la décision administrative individuelle à la sanction pénale, c'est à dire 5 ans d'emprisonnement et 5000€ d'amendes.\ \ **Attention : les cadres juridiques présentés ne sont pas exhaustifs. Seul votre service juridique sera en mesure de savoir si d'autres cadres doivent s'ajouter en raison de votre projet.** {% endhint %} Plusieurs cadres juridiques sont à prendre en compte lors de la conception et du déploiement d'un agent conversationnel. Ce système d'intelligence artificielle (IA) repose avant tout sur des algorithmes et des données, auxquels s'appliquent plusieurs cadres juridiques. ## 💻 Traitement de données à caractère personnel Dans le cas où votre projet à vocation à traiter des données à caractère personnel, le **Règlement général sur la protection des données** s'applique (RGPD), règlement que l'on retrouve également en droit national dans la Loi informatique et libertés (LIL). {% hint style="info" %} Une donnée à caractère personnel se définit comme toute information relative à une personne physique permettant de l'identifier directement (nom, prénom, courriel nominatif, etc.) ou indirectement (numéro de téléphone, plaque d'immatriculation, adresse postale, voix, image, etc.). {% endhint %} Ainsi vous devrez penser au fait que : * vous utilisez des données personnelles pour des **finalités** déterminées, explicites et légitimes ; * votre collecte de données personnelles doit reposer sur une **base légale**, le plus souvent votre mission d'intérêt public en tant qu'administration. Celle-ci ne se présume pas et il importe de motiver que votre administration soit tenue, par un texte juridique, de réaliser une activité ou une mission rendant nécessaire ce traitement de données ; * vous respectez le principe de **minimisation des données** (ne pas traiter plus que nécessaire) ; * vous devez **informer les personnes**, lors de la collecte ou de l'utilisation de leurs données, de la manière dont vous allez traiter celles-ci ; * les données traitées doivent être **exactes** ; * vous devez **conserver** les données pendant une durée n'excédant pas celle nécessaire au regard des finalités ; * vous devez garantir la **sécurité** des données traitées ; * vous devez **permettre aux personnes dont vous traitez les données d'exercer leurs droits** (accès, rectification, suppression dans certains cas) ; **Vous rapprocher du service juridique de votre administration vous permettra de répondre à ces exigences dès le début de la construction de votre projet et de pouvoir évoluer dans la bonne direction.** ## 📑 Décision automatisée ou aide à la décision Parfois votre IA pourra permettre de rendre **des décisions administratives individuelles**, c'est à dire des décisions qui nomment précisément une personne ou une entreprise. Il se peut qu'elle aide à prendre une décision (outil d'aide à la décision) ou qu'elle automatise la décision (décision automatisée). Dès lors que votre IA - et même plus largement votre traitement algorithmique - permet de rendre de telles décisions, un cadre juridique spécifique est applicable. Ce cadre s'applique plus largement aux traitements algorithmiques qui fondent des décisions administratives individuelles. {% hint style="info" %} Selon le Larousse, un algorithme est un "*ensemble de règles opératoires dont l'application permet de résoudre un problème énoncé au moyen d'un nombre fini d'opérations. Un algorithme peut être traduit, grâce à un langage de programmation, en un programme exécutable par un ordinateur*". La [CNIL ](https://www.cnil.fr/sites/default/files/atoms/files/cnil_rapport_garder_la_main_web.pdf)définit un algorithme comme *"une suite finie et non ambigüe d’instructions permettant d’aboutir à un résultat à partir de données fournies en entrée."*\ \ Ainsi, un algorithme peut donc exister **indépendamment d'un traitement informatique**. Une grille de notation "papier" utilisée par une administration est considérée comme un algorithme. {% endhint %} Des principes de transparence algorithmiques s'appliquent aux décisions automatisées aussi bien qu'aux simples décisions issues d'outils d'aide à la décision : * **Information générale** : en application de l’article L. 312-1-3 du code des relations entre le public et l'administration (CRPA), les **administrations publient en ligne les règles** définissant les principaux traitements algorithmiques utilisés dans l'accomplissement de leurs missions lorsqu'ils fondent des décisions individuelles ; * **Mention explicite pour la personne concernée** : en application des l’article L. 311-3-1 et R. 311-3-1 du CRPA, lorsqu’une décision individuelle est prise sur le fondement d'un traitement algorithmique elle doit comporter une **mention explicite en informant l'intéressé**. Cette mention précise la finalité du traitement algorithmique ainsi que le droit pour l’intéressé de recevoir, s’il le demande, la communication des règles définissant ce traitement ainsi que les principales caractéristiques de sa mise en œuvre ; * **Une information individuelle à la demande de l'intéressé** : en application de l’article R. 311-3-2 du CRPA, lorsque la personne en a **fait la demande, l’administration communique** sous une forme intelligible : le degré et le mode de contribution du traitement algorithmique à la prise de décision, les données traitées et leurs sources, les paramètres de traitement et, le cas échéant, leur pondération, appliqués à la situation de l'intéressé ainsi que les opérations effectuées par le traitement : * **Accès et publication du code source** : les codes sources font parties des documents administratifs communicables (article L. 300-2 du CRPA) qui peuvent donc être communiqués à toute personne qui le demande ou encore qui sont diffusables en *open data*. Plus précisément, en principe il est **interdit de prendre une décision individuelle entièrement fondée sur un traitement automatisé** de données à caractère personnel (article 47 de la LIL).\ \ **Toutefois**, il est possible de le faire si certaines conditions sont respectées : * **Mention explicite pour la personne concernée** (*cf supra*) ; * L'administration doit s'assurer de la **maitrise du traitement algorithmique** et de ses évolutions pour **pouvoir expliquer**, en détail et de manière intelligible, la manière dont le traitement a été mis en œuvre à l'égard de la personne (ce qui permet d'informer individuellement l'intéressé à sa demande) ; * La décision **n'est pas un recours administratif** ; * La décision **n’est pas prise à partir de données sensibles** au sens du RGPD. ## 🇪🇺 Règlement européen sur l'intelligence artificielle (RIA) : qu'est ce que ça change ? Le RIA propose une approche fondée sur les risques pour les systèmes d'intelligence artificielle (SIA). #### ❌ Les pratiques interdites en matière d'IA Pour éviter des utilisation considérés comme néfastes ou abusives, **certaines IA sont rendues interdites**. Quelques exemples : * la notation sociale ; * la déduction des émotions d’une personne sur le lieu de travail ou dans un établissement d’éducation ; * la prédiction de risques criminels ; * la manipulation et l'exploitation de vulnérabilités ... #### 📌 Les SIA à haut risque Cette qualification résulte des **risques d'impacts négatifs de ces SIA sur la sécurité, la santé ou les droits fondamentaux.** Deux catégories coexistent : 1. **Les SIA qui répondent à deux conditions :** * ils constituent des composants de sécurité de produits relevant de certaines législations d’harmonisation de l’Union, ou sont eux-mêmes de tels produits ; * ils sont utilisés par un produit, ou sont eux-mêmes, soumis à une procédure d’évaluation de leur conformité par un organisme tiers conformément à la législation d’harmonisation de l’Union correspondante. *Exemple : une voiture, des jouets, l'aviation ...* 2. **Les SIA visés à l'annexe III du RIA** Quelques exemples : * les SIA destinés à être utilisés pour déterminer l’accès ou l’affectation de personnes physiques aux établissements d’enseignement et de formation professionnelle ; * Les SIA utilisés pour déterminer l'accès et le droit aux services privés essentiels et aux services publics et prestations sociales essentiels ... Peuvent déroger les SIA qui ne présentent pas de risques significatifs d'atteinte à la santé, à la sécurité aux droits fondamentaux des personnes physiques, y compris en n’influençant pas sensiblement le résultat d'une prise de décision. Si votre SIA est à haut risque certaines exigences, notamment avant sa mise sur le marché ou en service, devront être respectées. Certaines documentations techniques, de système de gestion des risques ou encore de mesures devront être accomplies. #### 🔎 Des obligations de transparence pour certaines SIA En raison de leurs risques spécifiques de manipulation, certains SIA devront répondre à des exigences de transparence, afin de renforcer la confiance des utilisateurs envers l'IA.\ Quelque exemple : * Lorsque le SIA est **destiné à interagir directement avec des personnes**, ils doivent être informés qu’ils interagissent avec ce SIA ; * Lorsque le SIA **génère des contenus de synthèse**, il doit indiquer et marquer que le contenu a été généré par SIA. A ces obligations de transparence prévues par le RIA viennent s'ajouter les éventuelles obligations précitées pour le cadre des données personnelles ou des décisions administratives. #### ▶️ Des SIA présentant un risque minimal Pour tous les autres SIA, aucune obligation spécifique n’est retenue au sein du RIA. Cependant, les développeurs et utilisateurs de SIA pourront volontairement choisir d’appliquer des exigences relatives à une IA en adhérant, notamment, à des **codes de conduite** #### 🎯 Obligations spécifiques pour les modèles d'IA à usage général dont les modèles IA génératifs Leur avantage premier est de servir un grand nombre de tâches diverses.\ Ces derniers ont des applications très diverses et constituent de plus en plus souvent la base de nombreux systèmes d'IA dans l'UE. Certains de ces modèles pourraient comporter des risques systémiques s'ils sont très puissants ou si leur utilisation est très répandue.\ \ Le RIA organise pour cette catégorie plusieurs niveaux d’obligations : * Pour les **modèles d’IA à usage général** : nous retrouvons des obligations de documentation et de transparence dans l’objectif de mieux comprendre le modèle lorsqu’il doit par exemple être intégré dans un SIA d’un fournisseur ; * Pour les **modèles d’IA à usage général présentant un risque systémique** : pour les fournisseurs, nous retrouvons des obligations d’évaluation des SIA en vue d’identifier et d’atténuer les risques systémiques. Le Bureau de l’IA encourage l’élaboration de **code de bonnes pratiques sur les IA Génératives** afin d’assurer le respect du règlement. ## Et le reste ? D'autres cadres juridiques pourront se voir appliquer tels que le choix de licence, l'open data des documents administratifs, ou encore des cadres relatifs à votre activité (code de l'environnement, code du travail ...). Seul votre service juridique sera en mesure de vous orienter et d'encadrer votre projet dès le début. Dans tous les cas, il sera nécessaire d'identifier le cadre juridique s'appliquant à votre utilisation d'un SIA et de documenter tous vos choix. Cette documentation sera nécessaire en cas de contrôle. {% hint style="info" %} 👉 pour aller plus loin, [Cellule de conformité de la DINUM ](https://ia.numerique.gouv.fr/ressources/cellule-conformit%C3%A9-ia/) {% endhint %} # Guide d'usage de l'IA pour les agents publics de l'État Ce guide a été rédigé par la direction interministérielle du numérique (DINUM), en lien avec la direction interministérielle de la transformation publique (DITP) et la direction générale de l'administration et de la fonction publique (DGAFP), à partir des travaux déjà conduits dans plusieurs administrations de l'État. Il a pour objet de fournir aux agents publics de l'État un cadre commun, pratique et directement mobilisable pour l'usage de l'intelligence artificielle dans leurs activités professionnelles. Il constitue un document de référence interministériel destiné à harmoniser les pratiques et à accompagner les agents ; il n'a pas, en tant que tel, de portée réglementaire. Son parti pris est d'aller à l'essentiel, en privilégiant les recommandations opérationnelles, les exemples concrets et les points de vigilance immédiatement utiles. Il a vocation à être actualisé régulièrement afin de tenir compte des évolutions technologiques, juridiques et des retours d'expérience des administrations. ## Guide d'usage de l'IA pour les agents publics de l'État # Introduction ### Introduction Depuis l'avènement des assistants conversationnels et des grands modèles de langage (LLM) fin 2022, l'intelligence artificielle générative (IAG) est entrée dans le quotidien professionnel de millions d'utilisateurs. Ces technologies permettent de rédiger un texte, synthétiser un document ou élaborer une ébauche de note en quelques secondes, ouvrant des perspectives nouvelles pour l'exercice des missions de service public : automatisation de tâches répétitives, aide à la rédaction, retranscription de réunions, création de supports visuels, etc. Nombre d'agents publics utilisent déjà ces outils dans leur activité quotidienne. Cette adoption rapide appelle un cadre partagé, garantissant un usage responsable, conforme au droit et respectueux des principes éthiques qui fondent l'action publique. #### L'objet de ce guide Le présent guide a pour vocation de fournir aux agents publics de l'État un socle de référence commun pour l'utilisation de l'IAG. Il rappelle les obligations juridiques incontournables, précise les principes éthiques à observer et formule des recommandations pratiques pour un usage éclairé et maîtrisé de ces technologies. Il a également vocation à nourrir le dialogue interne aux administrations sur les conditions d'usage de l'intelligence artificielle, notamment lorsqu'il s'agit de préciser ces principes dans des chartes ministérielles, des cadres métiers ou, le cas échéant, des accords collectifs. #### Un cadre interministériel complété par des chartes sectorielles Ce guide s'inscrit dans une démarche interministérielle et s'adresse à l'ensemble des agents publics de l'État. Il constitue un référentiel généraliste, destiné à être complété, le cas échéant, par des chartes ministérielles ou métiers spécifiques, adaptées aux enjeux propres à chaque administration ou famille professionnelle. Plusieurs ministères et opérateurs se sont ainsi dotés ou se doteront prochainement de chartes sectorielles : c'est le cas du ministère de l'Éducation nationale, de l'Agriculture et de la Souveraineté alimentaire, ou encore des communicants de l'État. Une liste actualisée de ces documents est accessible [**en ligne**](https://alliance.numerique.gouv.fr/ressources/portail-des-chartes-ia-dans-ladministration/). **Lorsqu'une charte ministérielle ou métier existe, elle** **s'applique en priorité** et vient préciser ou compléter les principes généraux énoncés dans le présent guide. En l'absence de charte spécifique ou de note ministérielle, ce guide constitue le cadre de référence applicable. Dans ce cadre, les administrations peuvent utilement associer les collectifs de travail et, selon les modalités qui leur sont propres, les représentants du personnel à la définition et à l'actualisation de leurs règles d'usage. {% hint style="info" %} **CE GUIDE EN BREF**\ ✅ L'IA est autorisée pour les agents publics, dans un cadre défini : respect des données, choix des outils, validation humaine.\ ✅ Utilisez prioritairement les outils de votre administration ou ceux mis à disposition au niveau interministériel (par exemple : Assistant IA, Assistant Transcripts, Visio) ; référez-vous aux consignes de votre administration pour les autres.\ ✅ En cas de doute sur vos données : utilisez uniquement les outils explicitement autorisés par votre administration.\ ✅ Vérifiez toujours les résultats produits par l'outil.\ ✅ N'utilisez l'IA que lorsqu'elle apporte un gain réel : pour des tâches simples, un outil classique suffit souvent.\ ✅ Signalez l'usage de l'IA lorsque celle-ci joue un rôle substantiel dans la production d'un contenu, dans l'analyse ou dans la préparation d'une décision. {% endhint %} # Partie 1 : qu'est-ce que l'IA générative ### Une technologie qui crée du contenu Le présent guide porte sur l'intelligence artificielle générative (IAG), qui désigne les outils capables de produire du contenu original (textes, images, sons ou code informatique) à partir d'une simple instruction en langage naturel. Il aborde également, lorsqu'ils sont d'usage courant aux côtés de l'IAG, certains outils d'IA spécialisés tels que la transcription audio, la reconnaissance de caractères ou la traduction automatique, qui ne reposent pas tous sur les mêmes technologies. Contrairement aux logiciels classiques qui suivent des règles programmées, l'IA générative fonctionne par apprentissage statistique. Elle a analysé des millions de documents et apprend à prédire ce qui devrait suivre dans une phrase, un paragraphe ou une image. On peut la comparer à un assistant très rapide et très utile, capable de produire un texte convaincant sans que son exactitude soit pour autant garantie. ### Ce qu'elle peut faire pour les agents publics Pour les agents publics, l'IA générative peut faire gagner un temps précieux sur des tâches répétitives : * **Transcrire automatiquement** une réunion ou un entretien avec un usager ; * **Résumer** un rapport de plusieurs dizaines de pages en quelques points clés ; * **Reformuler** un texte technique pour le rendre accessible au grand public ; * **Traduire** rapidement un document administratif ; * **Structurer** vos idées avant de rédiger une note ou une présentation. Ce temps libéré peut être réinvesti dans des tâches à plus forte valeur ajoutée, comme l'amélioration de la relation avec les usagers, la qualité du service rendu ou l'analyse de situations complexes. ### Les limites à connaître L'IA générative n'est pas infaillible. Elle présente plusieurs limites qu'il est essentiel de comprendre avant de l'utiliser : * **Elle peut inventer des informations de toutes pièces.** L'IA produit parfois des contenus qui paraissent vrais mais qui sont factuellement faux. On appelle cela des "hallucinations". Elle peut citer des textes de loi qui n'existent pas, inventer des références bibliographiques ou affirmer des faits historiques erronés. * **Elle ne comprend pas vraiment ce qu'elle dit.** L'IA fonctionne par probabilités statistiques, pas par compréhension du monde réel. Elle peut produire un texte cohérent sur un sujet sans en saisir les enjeux pratiques ou les conséquences concrètes. * **Elle reproduit les biais de ses données d'entraînement.** Si l'IA a été entraînée sur des contenus comportant des stéréotypes ou des discriminations, elle peut les reproduire dans ses réponses. * **Elle peut être détournée ou manipulée.** Comme tout système informatique, l'IA présente des vulnérabilités : injection d'instructions cachées dans un document fourni en entrée, exploitation de failles du modèle, fuite involontaire d'informations sensibles. Une vigilance technique est donc requise, particulièrement pour les usages les plus sensibles. * **Les modèles d'IA de base ne citent pas leurs sources.** Certains outils avec accès "recherche internet" ou connexion avec une base documentaire peuvent afficher des sources, mais ceux-ci ne sont pas toujours pertinents ou exacts. Dans tous les cas, vous devez vérifier les informations de manière indépendante. * **Ses connaissances sont figées.** Les modèles d'IA sont entraînés à un moment donné et ne sont pas systématiquement mis à jour. Ils peuvent donc ignorer les évolutions récentes de la réglementation ou de l'actualité. * **Elle consomme beaucoup de ressources.** Chaque requête nécessite de l'énergie et de l'eau pour refroidir les serveurs. L'empreinte environnementale de l'IA est significative et doit être prise en compte dans vos choix d'utilisation. ### Les conditions d'un usage réussi Pour que l'IA soit vraiment utile dans votre travail quotidien, quatre conditions sont essentielles : 1. **Vous maîtrisez déjà la tâche.** L'IA doit assister votre expertise, pas la remplacer. Vous devez être capable de vérifier et corriger ce qu'elle produit. Ne confiez pas à l'IA une mission que vous ne sauriez pas accomplir vous-même. 2. **L'IA est intégrée par ceux qui connaissent le métier.** Les meilleurs usages de l'IA sont ceux portés par les agents experts eux-mêmes, qui savent où elle peut apporter de la valeur et où elle serait inadaptée. 3. **L'IA ne doit pas devenir un réflexe automatique.** Avant de l'utiliser, interrogez-vous sur la pertinence de votre démarche : un outil plus simple suffirait-il (moteur de recherche, traducteur classique) ? Le processus gagnerait-il à être simplifié plutôt qu'automatisé ? La bonne réponse à un besoin est parfois organisationnelle avant d'être technologique. 4. **Vous vérifiez les sources lorsqu'elles sont disponibles.** Certains outils permettent d'afficher les sources mobilisées pour produire une réponse. Lorsque cette fonction est disponible, consultez-les systématiquement et vérifiez leur fiabilité. {% hint style="success" icon="lightbulb" %} **L'IA générative est un outil d'assistance, pas de substitution. Elle vous fait gagner du temps sur des tâches répétitives, à condition que vous gardiez toujours un œil critique et que vous vérifiiez ses productions.** {% endhint %} *** # Partie 2 : l'IA en pratique pour les agents publics ### Les différents types d'outils d'IA Les outils d'intelligence artificielle générative se présentent sous plusieurs formes, chacune adaptée à des usages spécifiques. **Les assistants conversationnels** sont les plus connus. Ce sont des interfaces de discussion où vous posez une question et l'IA vous répond : rédaction, résumé, reformulation, brainstorming... Ce sont les outils les plus polyvalents. **Les outils spécialisés** intègrent l'IA pour une tâche précise : * **OCR (reconnaissance de caractères)** pour numériser et rendre modifiable un document papier ou scanné ; * **Speech-to-text** pour transcrire automatiquement une réunion ou un entretien ; * **Traduction ou traduction automatique** intégrées dans vos outils de bureautique ; * **Génération d'images** pour créer des visuels ou illustrations. ### Trois catégories d'outils, trois niveaux de sécurité Tous les outils d'IA ne se valent pas en matière de protection des données. Il existe trois grandes catégories, du plus sécurisé au moins sécurisé. **1) Les outils des administrations publiques (à privilégier)** Ces solutions sont développées ou déployées par l'État. Elles constituent le premier choix pour les usages professionnels, en privilégiant les outils explicitement approuvés par votre administration de rattachement. **Outils interministériels** : * **Assistant IA interministériel** ([assistant.numerique.gouv.fr](http://assistant.numerique.gouv.fr)) : assistant conversationnel sécurisé pour la rédaction, le résumé et la reformulation ; * **Assistant Transcripts** ([transcripts.numerique.gouv.fr](https://transcripts.numerique.gouv.fr)) : enregistrement automatique des réunions en présentiel ; * **Visio** ([visio.numerique.gouv.fr](http://visio.numerique.gouv.fr)) : transcription automatique et résumé de réunions en visioconférence ; **Outils ministériels** : Certains ministères disposent également d’outils propres, adaptés à leurs besoins ou à leurs contraintes spécifiques. En 2026, ces outils s’inscrivent dans une trajectoire de convergence avec les offres mutualisées de l’État. **👉 Pour vos usages professionnels, privilégiez les outils mis à disposition ou explicitement approuvés par votre administration.** **2) Les outils commerciaux payants mis à disposition par votre administration (avec précautions)** Certaines administrations de l'État peuvent acheter des licences d'outils commerciaux, par exemple les versions payantes de ChatGPT (OpenAI), Claude (Anthropic) ou d'autres outils spécialisés, notamment d'aide juridique ou de création graphique assistée par l'intelligence artificielle, avec des garanties contractuelles renforcées. **Ces versions offrent :** * Des engagements contractuels sur la non-réutilisation des données ; * Un meilleur niveau de sécurité ; * Un support technique dédié ; {% hint style="warning" %} **Attention :** même avec une licence payante, vérifiez toujours auprès de votre direction des systèmes d'information (DSI) ou de votre responsable les types de données autorisées. {% endhint %} {% hint style="warning" %} **À vérifier également** : la maîtrise juridique et opérationnelle de l’hébergement des données. La localisation des serveurs ne suffit pas : il faut aussi examiner le pays d’établissement du fournisseur, sa structure capitalistique, les entités qui opèrent le service et les sous-traitants mobilisés. Ainsi, un service hébergé dans l’Union européenne peut rester soumis à une législation étrangère, notamment au Cloud Act américain, s’il est opéré ou contrôlé par une entreprise relevant de ce droit. Pour les usages sensibles, privilégier des solutions offrant de fortes garanties de maîtrise, idéalement qualifiées SecNumCloud par l’ANSSI. {% endhint %} **3) Les outils commerciaux gratuits (usage très limité voire interdit)** Ce sont les outils accessibles librement sur Internet, parfois sans création de compte : versions gratuites de ChatGPT, Claude, Gemini, NoteBookLM, Vibe (ex Le Chat de Mistral AI), etc. **⚠️ Conditions d'utilisation strictes :** * **Vérifiez que votre ministère autorise leur accès et leur utilisation à titre professionnel** (dans certaines administrations, ces services sont bloqués sur le réseau) ; * **Ne les utilisez que pour des** **données qui pourraient être rendues publiques** (pas de données personnelles, pas de données sensibles, etc.); * **Évitez l'utilisation professionnelle en utilisant votre compte personnel ;** **Usages possibles (exemples)** : résumer un texte de loi ou un rapport déjà publics, reformuler un document accessible en ligne, générer une image d'illustration, créer un quiz de formation à partir de contenus publics, travailler sur du code pour un projet informatique open source ou non sensible. **Usages interdits (exemples)** : analyser un dossier d'usager, résumer un compte-rendu de réunion interne, travailler sur des données RH ou médicales, traiter des informations couvertes par le secret professionnel. {% hint style="info" %} **Le réflexe à avoir** : posez-vous la question suivante : « Est-ce que je pourrais publier ces informations sur un site Internet accessible à tous ? » Si la réponse est non, n'utilisez pas un outil commercial grand public. En cas d'hésitation, utilisez uniquement un outil mis à disposition par votre administration. {% endhint %} ### Bien utiliser votre outil d'IA : les bonnes pratiques du "prompt" Un **prompt** (ou "instruction") est la **consigne** que vous donnez à l'IA. C'est votre question, votre demande, votre brief. Plus votre instruction est claire et précise, meilleure sera la réponse de l'IA. Rédiger un bon prompt, c'est comme briefer une personne en stage : il faut lui donner le contexte, préciser ce que vous attendez, et être explicite sur le format souhaité. {% hint style="success" icon="lightbulb" %} Pour en savoir plus, consultez la fiche pratique "Bien rédiger ses prompts" en annexe de ce guide. {% endhint %} ### En cas de doute : qui contacter ? Vous ne savez pas quel outil utiliser ?\ Vous vous demandez si vos données sont sensibles ? **Voici les personnes qui peuvent vous aider :** | **Qui contacter ?** | **Dans quel cas ?** | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Votre hiérarchie | Vous souhaitez utiliser l'IA pour une décision importante ou un usage inhabituel | | Votre service informatique (DNUM, DSI) | Vous avez une question sur les outils autorisés dans votre administration | | Votre référent cybersécurité | Vous voulez savoir si vos données sont sensibles | | Votre délégué à la protection des données (DPD) | Vous voulez vérifier qu'un traitement de données est compatible avec le RGPD ou inscrit au registre des traitements | {% hint style="warning" %} Si vous envisagez un usage régulier de l'IA pour traiter des données personnelles, vérifiez avec votre délégué à la protection des données (DPD) que ce traitement figure au registre des activités de traitement de votre administration. {% endhint %} # Partie 3 : les 5 principes fondamentaux Ce guide propose cinq principes essentiels qui garantissent un usage responsable de l'IA générative pour les agents publics de l'État, conforme au droit et respectueux des valeurs du service public. **Les 5 principes en résumé :** 1. **L'IA vous assiste mais vous restez responsable de vos décisions.** 2. **Les données sensibles ne peuvent être traitées qu'avec les outils autorisés par votre administration.** 3. **Informez vos destinataires internes ou externes lorsque vous utilisez l'IA.** 4. **N'utilisez l'IA que lorsqu'elle est utile, en restant vigilant à ses biais, au respect du droit d'auteur et à son impact environnemental.** 5. **Formez-vous pour maîtriser l'IA et ses enjeux.** *** ### Principe 1 : L'agent public reste responsable ***L'IA est un outil d'assistance, pas un décideur. Vous gardez la responsabilité finale de vos actes et productions.*** #### Vous gardez le contrôle Toute production ou décision doit être validée par vous. L'IA propose, suggère, aide à structurer votre réflexion, mais c'est vous qui décidez. Elle ne peut en aucun cas se substituer à votre jugement professionnel et à votre expertise métier. Même si l’IA a produit le contenu, c’est vous qui le publiez ou le transmettez : vous en demeurez responsable. Cette responsabilité peut, en cas d’erreur, d’imprécision ou de manquement, entraîner des suites selon les règles applicables aux agents publics, notamment celles prévues par le Code général de la fonction publique et par les chartes ministérielles en vigueur. Le non-respect de ces règles peut engager votre responsabilité dans les conditions du droit commun. #### Vous vérifiez avant d'agir Ne lancez pas d'action automatique sans contrôle humain, particulièrement pour des actions critiques qui pourraient impacter des personnes ou des systèmes sensibles : {% columns %} {% column %} **❌ À ne jamais faire :** * Configurer l'IA pour qu'elle envoie automatiquement des courriels à des usagers ou des partenaires extérieurs sans supervision ; * Lui donner accès à des systèmes critiques sans votre validation ; * Publier directement un contenu généré sans relecture ; {% endcolumn %} {% column %} **✅ La bonne pratique :** * Utilisez l'IA pour préparer un brouillon ; * Relisez avec un regard critique ; * Effectuez les modifications nécessaires ; * Validez et envoyez vous-même ; {% endcolumn %} {% endcolumns %} #### Vous évaluez la criticité de l'activité Avant de recourir à l'IA, assurez-vous que la nature de la tâche est compatible avec les limites connues de ces outils : risque d'hallucination, obsolescence des informations, biais, absence de sources fiables. Plus l'activité est sensible (décision individuelle, document juridique, données touchant des personnes), plus la vérification humaine doit être rigoureuse, et plus l'usage de l'IA doit être encadré, voire écarté lorsque la vérification a posteriori n'est pas possible à votre niveau. *** ### Principe 2 : Choisissez le bon outil selon vos données ***Tous les outils d'IA n'offrent pas les mêmes garanties de protection. Adaptez votre choix à la nature de vos données.*** #### La règle simple à retenir Pour vos usages professionnels, utilisez les outils mis à disposition par votre administration. Ils sont conçus pour répondre aux exigences de sécurité du service public. Le recours à un outil commercial (ChatGPT, Claude, Gemini...) doit rester exceptionnel et n'est possible qu'à deux conditions cumulatives : * votre administration l'autorise explicitement ; * les informations traitées pourraient être publiées librement sur Internet. En cas de doute, n'utilisez pas d'outil commercial : tournez-vous vers les outils de votre administration ou sollicitez votre hiérarchie. #### Chaque administration a ses règles Votre ministère peut avoir des règles plus strictes que ce guide général. **Renseignez-vous auprès de votre DSI / DNUM ou de votre hiérarchie** pour connaître : * Quels outils sont autorisés dans votre administration ; * Pour quels types d'usages ; * Quelles données vous pouvez ou ne pouvez pas traiter ; **En cas de doute, trois réflexes :** 1. **Utilisez l'outil de votre administration** plutôt qu'un outil commercial. 2. **Si vous êtes en mesure de le faire simplement, anonymiser les informations** ("Madame X", "un usager", "un agent"...) avant de les transmettre à l'outil d'IA. 3. **Demandez conseil** à votre hiérarchie, votre direction des systèmes d'information (DSI), votre délégué à la protection des données (DPD) ou votre référent cybersécurité. #### Le cadre juridique qui vous protège Votre usage de l'IA doit respecter plusieurs textes de loi qui protègent les personnes et leurs données : * **Le** **règlement général sur la protection des données (RGPD)** impose de protéger les données personnelles et de n'utiliser que les données strictement nécessaires. * **Le règlement européen sur l'IA (RIA)** encadre les usages de l'IA à risque (justice, santé, RH, police...). * **Votre obligation déontologique de secret professionnel** vous interdit de divulguer des informations couvertes par le secret. **Vous n'avez pas besoin de maîtriser tous ces textes en détail.** Suivez simplement la règle pratique : en cas de doute sur une donnée, utilisez l'outil de votre administration ou abstenez-vous. **Au-delà des données personnelles** La vigilance ne porte pas seulement sur les données personnelles au sens du RGPD. Elle vaut aussi pour les **informations professionnelles non publiques** : notes en cours d'arbitrage, projets confidentiels, éléments couverts par le secret des délibérations gouvernementales, données stratégiques ou économiques sensibles. Ces informations ne doivent pas être confiées à un outil commercial grand public. **Pour les données classifiées** ou portant une mention de protection (Diffusion Restreinte, Confidentiel Défense, et plus généralement toute donnée relevant de l'IGI 1300), seuls les outils explicitement homologués par votre administration peuvent être employés. {% hint style="info" icon="thumbtack-angle" %} **Exemples pratiques** **Situation 1 : Résumer un rapport public**\ *Vous devez résumer un rapport parlementaire disponible sur le site de l'Assemblée nationale.*\ → ✅ Document public, pas de données personnelles → Vous pouvez utiliser un outil commercial (si autorisé par votre ministère) ou l'outil de votre administration. **Situation 2 : Préparer un compte-rendu de réunion**\ *Vous voulez résumer les échanges d'une réunion interne avec les noms des participants et leurs positions.*\ → ❌ Noms + informations internes → Utilisez uniquement l'outil de votre administration **Situation 3 : Analyser et évaluer des candidatures à un poste**\ *Vous devez comparer plusieurs candidatures pour un recrutement.*\ → 🚫 Usage à haut risque au sens du règlement européen sur l'IA (RIA, annexe III). Le tri ou l'évaluation de candidatures par un système d'IA fait l'objet d'obligations renforcées : analyse d'impact, supervision humaine, transparence vis-à-vis des candidats. Avant tout usage, consultez votre délégué à la protection des données (DPD) et votre service RH. En l'absence d'un cadre formellement validé dans votre administration, abstenez-vous. {% endhint %} *** ### Principe 3 : Soyez transparent ***Lorsque l'intelligence artificielle joue un rôle substantiel dans la production d'un contenu, dans une analyse ou dans la préparation d'une décision, son usage doit pouvoir être explicité à vos interlocuteurs.*** #### Informer vos destinataires La transparence permet à vos interlocuteurs de mieux comprendre le contenu, de garder un œil critique et de savoir qu'une relecture humaine a été effectuée. Cette exigence de transparence doit être appréciée de manière proportionnée. Une assistance ponctuelle à la reformulation n'appelle pas les mêmes modalités qu'un rôle substantiel dans un document, un service automatisé ou une décision administrative. **Cette transparence est obligatoire :** * Par le RGPD (art. 22) : les décisions produisant des effets juridiques lorsqu'elles reposent exclusivement sur le recours à un traitement automatisé sont strictement encadrées et doivent donner lieu à une information appropriée des personnes concernées. * Par le code des relations entre le public et l'administration (art. L. 311-3-1) : une décision administrative individuelle prise sur le fondement d'un algorithme doit comporter une mention explicite. #### Qu'entend-on par « rôle substantiel » ? Deux cas de figure permettent d'apprécier le degré d'implication de l'IA : | **Usage** | **Mention** | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | Reformulation, correction, mise en forme d'un texte que vous avez rédigé | Aucune mention requise | | Production de contenu par l'IA (analyse, note, courrier, synthèse), même ajusté ensuite | Mention obligatoire : *« Généré partiellement par intelligence artificielle »* | #### Comment mentionner l'usage de l'IA **Pour un document interne** (note, compte-rendu, présentation) : * **Mention orale :** « J'ai utilisé l'IA pour préparer cette première version. » * **Mention écrite en pied de page :** « Document rédigé avec l'assistance d'un outil d'IA générative et vérifié par \[votre nom] » **Pour un document externe** (courrier à un usager, publication, rapport officiel) : * **Mention formelle :** « Contenu partiellement généré par une IA et vérifié par un agent » * Cette formule est recommandée par le système de design de l'État. **Si un usager interagit directement avec l'IA** (agent conversationnel, assistant virtuel) : * Il doit le savoir. * Exemple : « Bonjour, je suis un assistant virtuel. Je peux répondre à vos questions sur nos services. Pour toute demande complexe, un agent vous recontactera. » #### Traçabilité des décisions Si l'IA vous a aidé dans une décision administrative importante (attribution d'une aide, refus d'un dossier, évaluation d'un agent), conservez une trace : **Ce qu'il faut documenter :** * Quel outil d'IA a été utilisé. * Quel était le résultat proposé par l'IA. * Quelle décision a finalement été prise. * Sur la base de quels critères et motivations. **Pourquoi c'est important :** * En cas de contestation, vous devez pouvoir expliquer votre décision. * Cela garantit l'équité et la transparence du processus. * C'est une obligation légale pour les décisions à fort impact. **📌 Exemples de mentions** | **Situation** | **Mention appropriée** | | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | **Note interne pour votre direction** | En pied de page : "Première version générée avec l'Assistant IA interministériel, relue et complétée par \[nom]" | | **Rapport officiel destiné au ministre** | En introduction ou pied de page : "Contenu partiellement généré par une IA et vérifié par les services" | | **Courriel à un usager** | Pas de mention nécessaire si l'IA a seulement aidé à la reformulation. Mention obligatoire si l'IA a contribué à la décision. | | **Assistant conversationnel sur un site public** | Message d'accueil : "Je suis un assistant virtuel. Mes réponses sont générées automatiquement. Un agent peut vous aider si besoin." | | **Présentation en réunion** | À l'oral en début de réunion : "Pour préparer cette présentation, j'ai utilisé l'IA pour structurer mes idées et créer certains visuels." | *** ### Principe 4 : Adoptez un usage éthique et sobre ***L'IA doit être utilisée de manière responsable, en limitant son impact environnemental et en respectant le droit et l'éthique.*** #### Limiter l'impact environnemental (IA frugale) L'IA générative consomme de l'énergie et de l'eau pour faire tourner et refroidir les serveurs. À titre de comparaison, une requête texte sur un assistant conversationnel équivaut à environ une à dix recherches Google ; la génération d'une image consomme environ 60 fois plus, et les modèles de raisonnement plusieurs dizaines de fois plus. **Avant d'utiliser l'IA, demandez-vous :** * Est-ce que j'en ai réellement besoin ? * Est-ce que je peux obtenir un résultat satisfaisant autrement ? * Est-ce que le recours à l'IA est proportionné au gain attendu ? **Comment rationaliser l'usage :** * **Minimisez le nombre de prompts** : rédigez un prompt clair dès le départ plutôt que d'enchaîner 10 tentatives * **Évitez le recours automatique** : ne sollicitez pas l'IA par réflexe pour des tâches simples * **Privilégiez les outils sobres** : certaines IA sont plus économes en ressources (renseignez-vous auprès de votre DSI) **❌ Usage excessif :** Utiliser l'IA pour reformuler un courriel de 3 lignes **✅ Usage pertinent :** Utiliser l'IA pour résumer un rapport de 100 pages {% hint style="info" icon="thumbtack-angle" %} **Exemple concret**\ *Vous devez traduire un courriel de 5 lignes en anglais.*\ → ❌ N'utilisez pas l'IA : utilisez un traducteur en ligne classique (moins énergivore) ou traduisez vous-même.\ → ✅ Réservez l'IA pour des traductions longues et complexes. {% endhint %} #### Respecter le droit d'auteur L'IA apprend en analysant des millions de documents, y compris des contenus protégés. Elle peut reproduire involontairement du contenu sous droit d'auteur. **Pour une diffusion externe, vérifiez que le contenu n'est pas copié :** * Relisez attentivement les textes générés * Faites des recherches pour identifier d'éventuelles sources et citez-les * En cas de doute, reformulez ou créez vous-même {% columns %} {% column %} **❌ Ce que vous ne devez pas faire :** * "Génère une image dans le style de Pixar" (marque et style protégés) * "Écris un texte qui ressemble à un article du Monde" (style éditorial protégé) * Utiliser une image générée par IA pour une communication officielle sans vérification {% endcolumn %} {% column %} **✅ Ce que vous pouvez faire :** * "Génère une illustration moderne représentant un bureau" (description générique sans référence à une œuvre protégée) * "Reformule cette note en t'appuyant sur les éléments que je te transmets" (l'IA travaille sur votre contenu original, pas sur des œuvres protégées) * Vérifier l'origine des contenus avant diffusion externe {% endcolumn %} {% endcolumns %} {% hint style="info" icon="thumbtack-angle" %} **Exemple concret**\ *Vous préparez une affiche pour une campagne interne et demandez : "Génère une affiche dans le style de Pixar".*\ → ❌ Risque de violation du droit d'auteur (œuvre et style protégés).\ → ✅ Alternative : "Génère une affiche simple et poétique avec des étoiles et des tons pastels." {% endhint %} #### Rester vigilant sur les biais L'IA reproduit ce qu'elle a appris. Si elle a été entraînée sur des données biaisées, elle peut reproduire ces biais : stéréotypes de genre, préjugés culturels, surreprésentation de certains points de vue... **Exemples de biais à surveiller :** * **Stéréotypes de genre** : associer automatiquement certains métiers à un sexe (infirmière = femme, ingénieur = homme) * **Biais culturels** : privilégier une perspective occidentale ou urbaine * **Biais socio-économiques** : faire des suppositions sur les revenus ou le niveau d'éducation **Comment s'en prémunir :** * **Gardez un œil critique** : relisez attentivement et interrogez-vous sur les présupposés * **Vérifiez l'équité** : le contenu traite-t-il toutes les catégories de personnes de manière égale ? * **Corrigez si nécessaire** : n'hésitez pas à reformuler pour neutraliser les biais * **Testez avec différents angles** : posez la même question de plusieurs manières pour détecter des incohérences {% hint style="info" icon="thumbtack-angle" %} **Exemple concret**\ *Vous demandez à l'IA de rédiger une offre d'emploi pour un poste d'assistant(e). L'IA utilise systématiquement le féminin et suggère des compétences relationnelles plutôt que techniques.*\ → ⚠️ Biais de genre détecté : l'IA associe ce poste aux femmes et aux savoir-être plutôt qu'aux compétences techniques.\ → ✅ Corrigez : reformulez l'offre de manière neutre et équilibrée, dans le respect des règles applicables à la rédaction administrative (circulaire du Premier ministre du 21 novembre 2017). {% endhint %} *** ### Principe 5 : Développez vos compétences **Pour utiliser l'IA de façon responsable, vous devez comprendre comment elle fonctionne, ses limites et ses risques.** #### Comprendre le fonctionnement de l'IA L'IA générative n'est pas magique : mieux vous la comprenez, mieux vous l'utilisez. Gardez en tête ces éléments essentiels : **L'IA peut produire des erreurs convaincantes** * Elle génère des réponses probables statistiquement, pas nécessairement vraies * Elle peut inventer des références, des données, des textes de loi qui n'existent pas et ne peut pas citer précisément ses sources (sauf dans le cas d'une recherche dans un corpus documentaire ou d'une recherche Internet) * Ses connaissances sont figées à une date donnée, elle ne peut actualiser ses connaissances que si l'utilisateur lui donne du contexte ou autorise la recherche sur Internet **Elle ne comprend pas vraiment ce qu'elle dit** * Elle fonctionne par probabilités, pas par compréhension du monde réel * Elle peut être cohérente sans être pertinente **Elle ne remplace pas votre expertise métier** * Vous restez l'expert de votre domaine * L'IA est un assistant, pas un substitut à votre jugement #### Se former en continu sur l'IA et sur votre métier L'IA évolue rapidement. Il est important de mettre à jour régulièrement vos connaissances pour en faire un usage éclairé et responsable. **Pourquoi se former ?** * Mieux identifier les cas d'usage pertinents * Éviter les pièges et les erreurs courantes * Comprendre les enjeux éthiques et juridiques * Échanger avec d'autres agents sur leurs pratiques #### Ressources disponibles **Campus du numérique public et Mentor** Les agents publics peuvent s’appuyer sur les ressources proposées par le Campus du numérique public et sur les formations disponibles sur Mentor pour renforcer leur compréhension de l’intelligence artificielle, de ses usages et de ses limites. Ces ressources permettent notamment de mieux comprendre le fonctionnement de l’IA générative, d’identifier les cas d’usage pertinents, d’adopter les bonnes pratiques de formulation des demandes et de maîtriser les principaux points de vigilance liés à la sécurité, aux données, aux biais et à l’impact environnemental. Exemples de formations disponibles sur Mentor : * Objectif IA : initiez-vous à l’intelligence artificielle ; * Découvrir les IA génératives ; * Kit atelier prompting ; * 3 minutes pour comprendre : intelligence artificielle et données. Une liste plus complète des formations et ressources disponibles est proposée dans la section « Pour aller plus loin ». **Formations ministérielles** Renseignez-vous auprès de votre service formation ou RH pour connaître les formations proposées dans votre administration. **Chartes et guides sectoriels** Consultez les chartes spécifiques à votre ministère, administration ou métier, notamment dans la section « Pour aller plus loin ». **Communautés de pratiques** Échangez avec d'autres agents utilisateurs de l'IA dans votre administration. Certains ministères mettent en place des groupes de travail ou des espaces d'échange, par exemple sur Tchap ou sur des forums internes. # Annexe : cas d'usage et exemples de prompts par famille de métier Cette annexe a pour objectif de vous inspirer et de vous montrer concrètement comment l'intelligence artificielle générative peut vous aider au quotidien dans vos missions Les exemples présentés ci-dessous sont directement testables avec les outils mis à disposition par les administrations publiques (par exemple, l'Assistant ([assistant.numerique.gouv.fr](https://assistant.numerique.gouv.fr)), Visio ([visio.numerique.gouv.fr](https://visio.numerique.gouv.fr)) ou Transcripts ([transcripts.numerique.gouv.fr](https://transcripts.numerique.gouv.fr)), ou tout autre **outil ministériel** autorisé dans votre administration (exemple : GenIAl) Chaque cas d'usage est présenté sous forme de **scénario concret** avec : * Le contexte et le besoin de l'agent * Le prompt utilisé (que vous pouvez réutiliser et adapter) * Le résultat obtenu * Les points de vigilance * Des variantes possibles **💡 Ces exemples sont des points de départ.** N'hésitez pas à les adapter à votre situation, votre métier et votre style. L'IA est d'autant plus efficace que vous personnalisez vos demandes. *** ### 📝 Fiche pratique : les 5 règles d'or du bon prompt Le "prompt" est l'instruction que vous donnez à l'outil d'IA générative. Cette fiche mémo vous informe sur les bonnes pratiques de cet exercice. ✅ Un bon prompt = contexte + document de référence (si nécessaire) + consigne précise + format attendu **1. Soyez précis sans être trop long** **❌ Trop vague :** "Écris un mail professionnel" **❌ Trop long :** "Rédige un courriel professionnel expliquant à l'ensemble des participants qu'une réunion prévue initialement pour le mardi 15 janvier à 14h30 est finalement reportée au jeudi 17 janvier à la même heure en raison d'une indisponibilité du directeur..." **✅ Juste ce qu'il faut :** "Rédige un courriel de 5 lignes pour reporter une réunion du 15 au 17 janvier. Ton formel." **2. Donnez du contexte** L'IA produit de meilleures réponses si elle comprend votre rôle et votre objectif. * Qui êtes-vous ? (votre rôle, votre service) * Pour qui travaillez-vous ? (le destinataire) * Quel est l'objectif ? Fournissez un document de référence si nécessaire * Joignez le document à votre demande (lorsque l'outil le permet) ou copiez-collez le texte source (circulaire, compte-rendu, rapport...) * Indiquez clairement de quoi il s'agit **❌ Sans contexte :** "Explique la procédure de délivrance de titres de séjour" **✅ Avec contexte :** "Je travaille dans une préfecture. Je dois expliquer la nouvelle procédure de délivrance de titres de séjour aux agents d'accueil. Voici en pièce-jointe la fiche présentant les règles applicables. Utilise un langage simple et pratique." 💡 **Astuce :** Vous pouvez même donner votre rôle à l'IA : *"Tu es un agent d'une préfecture. Tu dois expliquer..."* **3. Précisez le format attendu** Indiquez clairement ce que vous voulez : longueur, structure, ton... **Exemples :** * "Résume ce rapport en 5 points clés, sous forme de liste" * "Rédige un courriel de 10 lignes maximum, sur un ton formel" * "Crée un tableau comparatif en 3 colonnes" * "Propose 3 versions : une courte, une moyenne, une longue" **4. Demandez des révisions si nécessaire** L'IA n'est pas parfaite du premier coup. N'hésitez pas à affiner progressivement. **Exemples de révisions :** * "Raccourcis cette version de moitié" * "Utilise un ton plus formel" * "Sois plus exhaustif sur le point 3" * "Reformule en évitant le jargon technique" * "Réorganise en commençant par les enjeux" **5. Demandez à l'IA de vous poser des questions** Si votre besoin est complexe, laissez l'IA vous aider à clarifier votre demande. **Exemple :** "Je veux créer une présentation sur la réforme de la fonction publique. Pose-moi des questions pour être sûr de bien comprendre mon besoin avant de commencer." L'IA vous demandera alors : public cible, durée, niveau de détail, angle d'approche… Elle peut aussi vous aider à reformuler votre prompt initial pour le rendre plus efficace. #### ⚠️ Et n'oubliez jamais de : * **Vérifier** le résultat avec un œil critique * **Adapter** le contenu à votre contexte spécifique * **Relire** avant de diffuser *** ### Liste des exemples de cas d'usages #### 💼 RH et gestion du personnel * Reformuler une circulaire RH pour les managers * Créer une FAQ à partir d'un règlement Exemples #### 📢 Communication interne et externe * Créer des posts pour les réseaux sociaux internes (Tchap, intranet) Exemples #### 🚀 Gestion de projets et réunions * Transcrire et résumer une réunion avec Visio * Transformer des notes éparses en ordre du jour structuré Exemples #### ⚖️ Juridique et réglementation * Résumer un texte de loi ou une jurisprudence * Vulgariser un document juridique pour les agents Exemples #### 📈 Finances et gestion budgétaire * Résumer un rapport d'audit ou de contrôle * Préparer une note de synthèse sur l'exécution budgétaire Exemples #### 🧑‍💼 Management et encadrement * Préparer une réponse à une question parlementaire à partir de notes existantes * Rédiger un feedback constructif pour un entretien annuel Exemples #### 👨‍💻 Développement et numérique * Documenter du code ou une procédure technique * Générer des tests ou des cas d'usage à partir des spécifications * Traduire de la documentation technique Exemples *** ## **RH et gestion du personnel** {% hint style="success" icon="lightbulb" %} **Cas d'usage 1 : Reformuler une circulaire RH pour les managers**\ \ 👤 **PROFIL** : Sophie, chargée de mission RH dans une DRAC\ 🎯 **BESOIN** : rendre une circulaire RH nationale compréhensible et opérationnelle pour les managers de proximité.\ 📍 **CONTEXTE** : Sophie vient de recevoir une circulaire RH de plusieurs pages, rédigée dans un langage juridique et administratif. Les managers de la direction lui demandent une version synthétique et pratique, mettant en évidence ce qu’ils doivent concrètement appliquer dans leurs équipes.\ 🔧 **OUTIL** : Assistant IA interministériel. {% endhint %} **💬 PROMPT UTILISÉ** : > Je suis chargée de mission RH dans une direction régionale.\ > Voici une circulaire RH nationale destinée aux services RH \[copier-coller de la circulaire]. Reformule ce document pour des managers de proximité. Objectif : leur expliquer de manière claire et opérationnelle ce qu’ils doivent appliquer dans leur équipe.\ > Structure :\ > \- Contexte et objectif de la circulaire (5 lignes maximum)\ > \- Ce qui change par rapport aux pratiques actuelles\ > \- Ce que le manager doit faire concrètement\ > \- Points de vigilance pour le manager\ > Ton clair, pratique et pédagogique. Longueur maximale : 2 pages.\ > N’invente aucune règle et ne modifie pas le sens juridique des dispositions. \ ✨ **RÉSULTAT** : une note synthétique et structurée à destination des managers, mettant en avant les changements introduits par la circulaire et ses principales règles à respecter. Sophie n'a plus qu'à compléter avec les contacts internes (référent RH, service support) et adapte aux spécificités de sa direction. ⚠️ **VIGILANCE** : * Vérifier la parfaite conformité avec le texte officiel : une reformulation peut introduire des simplifications qui modifient le sens juridique, et une exception ou cas particulier important peut être omis. * Adapter certains passages au contexte local (organisation interne, circuits de validation, outils utilisés). * Faire relire la version finale par un référent juridique ou RH avant diffusion. * Indiquer en pied de page que la note a été préparée avec l'assistance d'une IA et validée par le rédacteur (et le cas échéant par le référent juridique ou RH). 🎯 **Conseil de Sophie :** "Je demande toujours à l’IA une version très opérationnelle, mais je garde la circulaire sous les yeux pour vérifier chaque règle. C’est à moi de garantir la conformité réglementaire." {% hint style="success" %} **Cas d'usage 2 : Créer une FAQ à partir d’un règlement interne sur le télétravail**\ \ 👤 **PROFIL** : Marc, responsable RH à la DGFiP\ 🎯 **BESOIN** : répondre aux questions récurrentes des agents et des managers sur les règles de télétravail, à partir du règlement interne existant.\ 📍 **CONTEXTE** : le service de Marc dispose d’un règlement interne détaillé sur le télétravail (conditions, nombre de jours autorisés, modalités de demande...).\ Ce document est jugé trop long et peu lisible par les agents. Marc souhaite produire une FAQ simple et directement exploitable pour l’intranet.\ 🔧 **OUTIL** : Assistant IA interministériel {% endhint %} **💬 PROMPT UTILISÉ** : > Je suis responsable RH dans un service interrégional.\ > Voici le règlement interne de mon administration sur le télétravail \[copier-coller du règlement]. À partir de ce document, crée une FAQ à destination des agents et des managers.\ > La FAQ doit répondre aux questions suivantes (et à toute autre question pertinente issue du texte) :\ > \- Qui peut demander le télétravail ?\ > \- Combien de jours par semaine sont autorisés ?\ > \- Comment faire une demande et qui valide ?\ > \- Dans quels cas le télétravail peut être refusé ou suspendu ?\ > \- Quels sont les équipements et obligations de l’agent ?\ > Tu peux éventuellement proposer d'autres questions qui auraient leur place dans cette FAQ, et dont la réponse se situe dans le règlement. Structure : une question claire suivie d’une réponse courte et précise.\ > Ton accessible et pédagogique. N’invente aucune règle et ne complète pas avec des informations absentes du règlement. \ ✨ **RÉSULTAT** : une FAQ structurée et facilement lisible, reprenant fidèlement les règles du règlement interne et les traduisant en réponses concrètes aux questions les plus fréquentes des agents et des managers. ⚠️ **VIGILANCE** : * Vérifier que toutes les réponses correspondent strictement au règlement en vigueur. * S’assurer qu’aucune règle locale ou dérogation spécifique n’a été oubliée. * Être attentif aux formulations trop générales, qui peuvent masquer des conditions ou des exceptions prévues par le texte. * Mettre à jour la FAQ à chaque évolution du règlement. * Préciser sur l'intranet que la FAQ a été élaborée avec l'aide d'une IA et vérifiée par le service RH avant publication. 🎯 **Conseil de Marc :** "Je relis chaque question avec le règlement ouvert à côté. La FAQ doit être fiable à 100 %, sinon elle crée plus de confusion qu’elle n’en résout." ## **Communication interne et externe** {% hint style="success" icon="lightbulb" %} **Cas d'usage : Créer des posts pour les réseaux sociaux internes (Tchap, intranet)**\ \ 👤 **PROFIL** : Claire, chargée de communication interne au Ministère de la Justice\ 🎯 **BESOIN** : créer rapidement des posts clairs et engageants pour informer les agents sur des actualités de service (nouveaux outils, événements internes, rappels de procédures).\ 📍 **CONTEXTE** : Claire reçoit régulièrement des informations provenant de plusieurs services (notes internes, mails, comptes rendus de réunions). Les contenus sont souvent hétérogènes et trop techniques pour être diffusés tels quels sur l’intranet ou sur Tchap. Elle doit produire des messages courts, compréhensibles par tous les agents et adaptés aux différents canaux internes.\ 🔧 **OUTIL** : Assistant IA interministériel {% endhint %} **💬 PROMPT UTILISÉ** : > Je suis chargée de communication interne dans une administration centrale.\ > Voici les informations sources à diffuser aux agents \[copier-coller de la note, du mail ou du compte rendu].\ > À partir de ces éléments, rédige deux messages de communication interne :\ > \- Un message pour Tchap (court, dynamique, maximum 600 caractères)\ > \- Un message pour l’intranet (un peu plus détaillé, maximum 1 200 caractères)\ > Contraintes : langage clair et accessible à tous les agents, pas de verbatims métier, mettre en avant l’intérêt concret pour les agents et ne pas inventer d’informations. \ ✨ **RÉSULTAT** : deux versions prêtes à l’emploi sont produites. Claire n'a plus qu'à vérifier la conformité des messages avec les informations officielles, ajuster le ton selon la culture de la direction et ajouter, si besoin, un lien vers la source interne ou le service référent. ⚠️ **VIGILANCE** : * Vérifier que toutes les informations diffusées sont validées et à jour (dates, périmètre concerné, contacts). * S’assurer que le message ne contient aucune information sensible ou confidentielle non destinée à l’ensemble des agents. * Harmoniser le ton avec la ligne éditoriale de la direction (ni trop promotionnel, ni trop institutionnel selon le canal). * Préciser, sur l'intranet ou en bas du post, que le message a été préparé avec l'assistance d'une IA et validé par le service communication. 🎯 **Conseil de Claire :** "Je prépare toujours un petit extrait des informations vraiment utiles pour les agents avant de lancer l’IA. Elle m’aide surtout à adapter un même contenu à plusieurs supports, mais je garde la main sur la validation finale et la diffusion : en communication interne, une formulation mal ajustée peut créer beaucoup d’incompréhensions." ## **Gestion de projets et réunions** {% hint style="success" icon="lightbulb" %} **Cas d'usage 1 : Transcrire et résumer une réunion en visioconférence avec Visio**\ 👤 **PROFIL** : Daniel, chargé de mission à la DGE\ 🎯 **BESOIN** **et** **CONTEXTE** : gagner du temps après une réunion en produisant rapidement un compte rendu exploitable et diffusable.\ 🔧 **OUTIL** : Visio, Assistant IA interministériel {% endhint %} **💬 PROMPT UTILISÉ** (après avoir utilisé la fonction "Transcription IA" de Visio) : > Voici la transcription automatique d'une réunion réalisée en présence de \[interlocuteurs], dans le cadre de \[contexte] : \[copier-coller de la transcription].\ > Rédige un compte rendu synthétique destiné aux participants, avec la structure suivante :\ > \- Synthèse des sujets abordés ;\ > \- Décisions prises ;\ > \- Points en discussion / arbitrages à venir ;\ > \- Actions à mener ;\ > Ton clair, professionnel et factuel. Maximum 500 mots. N’invente aucune information. \ ✨ **RÉSULTAT** : un compte rendu court et structuré, centré sur les décisions et les actions, facilement diffusable aux participants. Daniel vérifie ensuite les éléments sensibles, complète les responsables ou échéances manquants et ajuste la priorisation des points en fonction de l’actualité du projet ⚠️ **VIGILANCE** : * Vérifier la fiabilité de la transcription : certaines interventions peuvent être mal attribuées ou mal interprétées. * Contrôler les décisions et actions listées : l’IA peut confondre un échange informel avec une décision réelle. * Supprimer ou reformuler les éléments sensibles avant diffusion (désaccords internes, propos informels...) * Informer les participants que le compte-rendu a été produit à partir d'une transcription automatique et d'un résumé généré par IA, puis vérifié par le rédacteur. 🎯 **Conseil de Daniel :** "Je prends toujours cinq minutes après la réunion pour relire la transcription avant de demander un résumé. L’IA est très efficace pour structurer, mais c’est à moi de différencier décisions et pistes de travail." {% hint style="success" icon="lightbulb" %} **Cas d'usage 2 : Transformer des notes éparses en ordre du jour structuré**\ \ 👤 **PROFIL** : Fanny, chargée de mission pilotage et coordination dans une administration centrale\ 🎯 **BESOIN** : construire rapidement un ordre du jour clair et cohérent pour une réunion de pilotage.\ 📍 **CONTEXTE** : Fanny prépare une réunion mensuelle réunissant plusieurs responsables de projets. Elle dispose de notes hétérogènes recueillies par mails, messages internes et comptes rendus précédents : points à arbitrer, informations à partager, alertes, propositions de sujets. Elle souhaite transformer cet ensemble de notes en un ordre du jour structuré, hiérarchisé et directement utilisable pour l’animation de la réunion.\ 🔧 **OUTIL** : Assistant IA interministériel {% endhint %} **💬 PROMPT UTILISÉ** : > Je suis chargée de mission pilotage.\ > Voici mes notes préparatoires pour une réunion de pilotage \[copier-coller de notes éparses : mails, points listés, extraits de comptes rendus].\ > À partir de ces notes, construis un ordre du jour structuré et hiérarchisé selon le format suivant :\ > \- Introduction et objectifs de la réunion ;\ > \- Points d’information ;\ > \- Points de suivi de projets ;\ > \- Points de décision / arbitrage ;\ > \- Questions diverses.\ > Pour chaque point, précise rapidement l’objectif du sujet (information, décision, échange) et propose un temps indicatif.\ > Ton clair et opérationnel. Maximum 400 mots. N'invente aucun sujet. \ ✨ **RÉSULTAT** : un ordre du jour organisé par grandes catégories, qui distingue clairement les points d’information et les points nécessitant une décision. Fanny ajuste ensuite la priorisation des sujets et modifie les temps indicatifs pour tenir compte des contraintes réelles de la réunion. ⚠️ **VIGILANCE** : * Vérifier la priorisation des sujets : l’IA ne peut pas hiérarchiser les enjeux politiques ou stratégiques attachés à certains points. * S’assurer que les points à fort enjeu sont bien positionnés dans l’ordre du jour et disposent d’un temps suffisant. * Mentionner brièvement, en début de réunion ou en pied de l'ordre du jour, que celui-ci a été structuré avec l'aide d'une IA à partir des notes préparatoires. 🎯 **Conseil de Fanny :** "Je donne toujours à l’IA des notes aussi complètes que possible, même si elles sont désordonnées. Elle est très efficace pour structurer un premier ordre du jour, mais la hiérarchisation finale des sujets relève de moi." {% hint style="success" icon="lightbulb" %} **Cas d'usage 3 : Enregistrer et transcrire une réunion en présentiel avec Transcripts**\ \ 👤 **PROFIL** : Élodie, chargée de mission dans une direction d'administration centrale\ 🎯 **BESOIN** : produire un compte rendu fidèle d'une réunion tenue en salle, sans mobiliser un agent dédié à la prise de notes.\ 📍 **CONTEXTE** : Élodie anime des réunions de coordination réunissant plusieurs services. Les participants sont présents physiquement ; personne ne peut consacrer l'intégralité de son attention à la retranscription des échanges. Elle utilise Transcripts pour enregistrer automatiquement la réunion et obtenir une transcription structurée dans Docs.\ 🔧 **OUTIL** : Transcripts, disponible dans LaSuite {% endhint %} **💬 PROMPT UTILISÉ** **(dans l'Assistant IA interministériel, à partir de la transcription générée par Transcripts)** : > Voici la transcription automatique d'une réunion de coordination tenue le \[date], réunissant \[rôles des participants, sans noms si non nécessaire], dans le cadre de \[contexte du projet ou de la réunion] : \[copier-coller de la transcription Transcripts]. Rédige un compte rendu synthétique destiné aux participants, structuré comme suit :\ > \- Sujets abordés\ > \- Décisions prises\ > \- Points en suspens ou arbitrages à venir\ > \- Actions à mener (avec responsable et échéance si mentionnés) -- Ton factuel et professionnel. Maximum 400 mots. N'invente aucune information. \ ✨ **RÉSULTAT** : un compte rendu structuré, directement diffusable aux participants après relecture, généré à partir de la transcription produite par Transcripts. Élodie vérifie l'attribution correcte des prises de parole, complète les responsables et échéances manquants, et supprime les échanges informels non destinés à figurer dans le document final. ⚠️ **VIGILANCE** : * Informer les participants en début de séance que la réunion est enregistrée à des fins de transcription. * Ne pas utiliser Transcripts pour des réunions portant sur des données classifiées ou à diffusion restreinte. * Vérifier l'attribution des interventions : la transcription automatique peut confondre des voix proches ou mal restituer des propos tenus à voix basse. * Relire la liste des décisions et actions avant diffusion : l'IA peut traiter un échange exploratoire comme une décision arrêtée. * Mentionner en pied du compte rendu que celui-ci a été produit à partir d'une transcription automatique et vérifié par le rédacteur. 🎯 **Conseil d'Élodie :** "Je lance Transcripts dès le début de la réunion et je préviens les participants. Cela libère tout le monde de la prise de notes et permet à chacun d'être pleinement dans les échanges. Je prends quand même quelques notes manuscrites sur les décisions clés : elles me servent de filet de sécurité à la relecture." ## **Juridique et réglementation** {% hint style="success" icon="lightbulb" %} **Cas d'usage 1 : Résumer un texte de loi ou une jurisprudence**\ \ 👤 **PROFIL** : Élise, chargée de mission juridique à la DGEFP\ 🎯 **BESOIN** : comprendre rapidement l’impact opérationnel d’un nouveau texte de loi ou d’une décision de justice récente pour préparer un point d’information à sa hiérarchie.\ 📍 **CONTEXTE** : Élise reçoit un projet de loi adopté ainsi qu’une décision de jurisprudence récente ayant un impact potentiel sur les procédures internes de son service. Les documents sont longs, techniques et doivent être analysés rapidement afin d’identifier les changements concrets pour l’administration.\ 🔧 **OUTIL** : Assistant IA interministériel {% endhint %} **💬 PROMPT UTILISÉ** : > Je suis chargée de mission juridique dans une direction d’administration centrale.\ > \ > Voici un texte de loi / une décision de jurisprudence que je dois analyser pour informer ma hiérarchie : \[copier-coller intégral du texte].\ > À partir de ce document, rédige une synthèse claire et structurée.\ > Structure attendue :\ > -Objet du texte ou de la décision (2 lignes)\ > -Principes juridiques essentiels\ > -Changements ou apports majeurs par rapport à la situation antérieure\ > -Impacts opérationnels possibles pour une administration de l’État\ > \ > Ton neutre, juridique mais accessible. Maximum 350 mots.\ > N’invente aucun élément et appuie-toi uniquement sur le document fourni. \ ✨ **RÉSULTAT** : une note de synthèse courte et structurée, permettant d’identifier rapidement l’objet du texte, et les conséquences potentielles pour l'administration. Élise peut ensuite préparer un message clair à destination de sa hiérarchie et des services concernés. ⚠️ **VIGILANCE** : * Vérifier systématiquement les références juridiques (articles, numéros de décisions, dates, liens). * Contrôler que l’IA n’a pas résumé de manière excessive certaines nuances juridiques importantes. * S’assurer que les "impacts opérationnels" proposés ne relèvent pas d’une interprétation trop large ou spéculative. * En cas de jurisprudence, vérifier que le contexte factuel de l’affaire est correctement compris. * Indiquer en pied de page que la synthèse a été préparée avec l'assistance d'une IA et vérifiée par le rédacteur, en renvoyant systématiquement au texte source pour toute citation ou décision opérationnelle. 🎯 **Conseil d’Élise :** "Je demande toujours à l’IA une première synthèse pour aller vite, mais je relis le texte source pour les points sensibles, et compare les deux documents pour m'assurer que rien n'a été omis." {% hint style="success" %} **Cas d'usage 2 : Vulgariser un document juridique pour les agents**\ \ 👤 **PROFIL** : Karim, responsable de pôle réglementation en DREAL\ 🎯 **BESOIN** : expliquer simplement à ses agents un nouveau texte environnemental réglementaire afin de faciliter sa mise en œuvre sur le terrain.\ 📍 **CONTEXTE** : une nouvelle instruction ministérielle et un décret modifient certaines procédures métier. Les agents non juristes doivent comprendre rapidement ce qui change, ce qui ne change pas, et ce qu’ils doivent appliquer concrètement dans leur travail quotidien.\ 🔧 **OUTIL** : Assistant IA interministériel {% endhint %} **💬 PROMPT UTILISÉ** : > Je suis responsable de pôle dans un service de l’État.\ > Je dois expliquer à des agents non juristes un nouveau document réglementaire.\ > Voici le texte juridique de référence : \[copier-coller du décret, de la circulaire ou de l’instruction].\ > Rédige une note de vulgarisation à destination des agents, sans jargon juridique.\ > Structure attendue :\ > -À quoi sert ce texte ? (contexte et objectif, en quelques lignes)\ > -Ce qui change concrètement pour les agents\ > -Ce qui ne change pas\ > -Ce qui est attendu des agents à partir de maintenant\ > \ > Ton clair, pédagogique et opérationnel. Maximum 400 mots. Ne crée aucune règle qui ne figure pas dans le texte fourni. \ ✨ **RÉSULTAT** : une note claire et directement exploitable par les agents, mettant en évidence les évolutions de procédures et les actions attendues, sans reproduire les verbatims juridiques du texte d’origine. Karim dispose ainsi d’un support homogène pour accompagner la mise en œuvre de la nouvelle réglementation. ⚠️ **VIGILANCE** : * Vérifier que la simplification ne modifie pas le sens juridique des obligations. * S’assurer que les exceptions, cas particuliers ou délais spécifiques ne sont pas oubliés. * Contrôler que la note ne crée pas de nouvelles règles ou interprétations internes. * Adapter les exemples et les formulations aux situations réelles du service. * Ne pas utiliser la note produite par l'IA comme fondement direct d'une décision sans retour au texte source et validation humaine. * Préciser en pied de page que la note a été élaborée avec l'aide d'une IA et validée par le responsable de pôle, en renvoyant au texte juridique de référence. 🎯 **Conseil de Karim :** "Je fournis toujours à l’IA le texte complet et je lui demande une structure très précise. Ensuite, j’ajoute mes propres exemples métier. L’IA est idéale pour rendre le message plus lisible, mais je reste vigilant pour ne jamais simplifier au détriment de la conformité réglementaire." ## **Finances et gestion budgétaire** {% hint style="success" icon="lightbulb" %} **Cas d'usage 1 : Résumer un rapport d'audit ou de contrôle**\ \ 👤 **PROFIL** : Hélène, cheffe du bureau du pilotage budgétaire et du contrôle interne à la DGRI.\ 🎯 **BESOIN ET CONTEXTE** : disposer rapidement d’une synthèse claire d’un rapport d’audit ou de contrôle volumineux, afin d’en présenter les principaux enseignements à sa direction.\ 🔧 **OUTIL** : Assistant IA interministériel {% endhint %} **💬 PROMPT UTILISÉ** : > Je suis responsable du pilotage budgétaire dans une administration centrale.\ > Voici un rapport d’audit interne portant sur la gestion financière de mon service : \[copier-coller du rapport d’audit ou téléchargement du document].\ > À partir uniquement de ce document, rédige une synthèse destinée à un comité de direction. Structure attendue :\ > \- Objet et périmètre de l’audit (3 lignes maximum)\ > \- Principaux constats (5 points maximum)\ > \- Principaux risques identifiés\ > \- Recommandations prioritaires de l’audit (5 maximum)\ > \- Points de vigilance pour la direction\ > Ton clair, professionnel et factuel. Maximum 500 mots.\ > N’invente aucun élément et ne reformule que des informations présentes dans le rapport. \ ✨ **RÉSULTAT** : une synthèse structurée, courte et directement exploitable en réunion de direction, reprenant les constats essentiels du rapport, les risques majeurs et les recommandations prioritaires. Hélène a ensuite vérifié la formulation de chaque point sensible et ajusté certaines expressions pour les rendre plus compréhensibles par des non-spécialistes de la gestion budgétaire. ⚠️ **VIGILANCE** : * Vérifier que les constats n’ont pas été simplifiés à l’excès ou sortis de leur contexte. * Vérifier la fidélité exacte des recommandations (certaines peuvent être conditionnelles ou formulées avec des réserves dans le rapport). * Indiquer en introduction de la note que la synthèse a été préparée avec l'assistance d'une IA à partir du rapport d'audit, puis relue et validée par la rédactrice. 🎯 **Conseil de Hélène :** "Je demande toujours une synthèse courte, mais je m’appuie systématiquement sur le document original pour sécuriser les messages les plus sensibles." {% hint style="success" icon="lightbulb" %} **Cas d'usage 2 : Préparer une note de synthèse sur l'exécution budgétaire**\ \ 👤 **PROFIL** : Camille, chef de bureau finances\ 🎯 **BESOIN** : préparer une note de synthèse sur l’exécution budgétaire à destination de sa direction générale.\ 📍 **CONTEXTE** : Camille dispose de plusieurs documents de suivi : tableaux d’exécution (autorisations d'engagement et crédits de paiement), commentaires de gestion transmis par les services, éléments d’alerte sur certains postes de dépenses et un point d’étape sur les recettes.\ Il doit produire, à partir de ces éléments dispersés, une note courte permettant à la direction de comprendre rapidement la situation d’exécution à mi-année et les éventuels écarts par rapport à la programmation.\ 🔧 **OUTIL** : Assistant IA interministériel {% endhint %} **💬 PROMPT UTILISÉ** : > Je suis chef du bureau finances dans une administration centrale.\ > Voici les documents de suivi de l’exécution budgétaire à mi-année : \[copier-coller des tableaux, commentaires de gestion et éléments de contexte].\ > À partir uniquement de ces documents, rédige une note de synthèse à destination de la direction générale. Structure attendue :\ > \- Rappel du périmètre et de la période couverte (2 lignes)\ > \- Situation globale de l’exécution (AE et CP)\ > \- Principaux écarts par rapport à la programmation initiale\ > \- Analyse des postes de dépenses et de recettes les plus sensibles\ > \- Points d’attention pour la fin de gestion\ > \ > Ton institutionnel, clair et factuel. Maximum 400 mots.\ > N’invente aucun chiffre et utilise uniquement ceux figurant dans les documents fournis. \ ✨ **RÉSULTAT** : un document de synthèse mettant en évidence la situation globale d’exécution, les écarts significatifs, les principaux points de tension budgétaire... Camille dispose ainsi d’une base prête à être intégrée dans la note de pilotage transmise à la direction générale, qu’il a ensuite complétée par quelques précisions sur les arbitrages en cours. ⚠️ **VIGILANCE** : * Vérifier l’exactitude de **tous les montants** et la cohérence entre AE et CP. * Vérifier que les écarts sont bien interprétés (certains peuvent être liés à des décalages calendaires et non à des dérives). * Vérifier la cohérence entre les commentaires qualitatifs des services et la présentation chiffrée. * Adapter le niveau de détail au public de direction, en évitant un excès de technicité. * Mentionner en pied de page que la note a été structurée avec l'assistance d'une IA et validée par le chef de bureau, le rédacteur restant garant de l'exactitude des chiffres et de l'interprétation des écarts. 🎯 **Conseil de Camille :** "Je prépare toujours des tableaux aussi propres que possible pour éviter toute complication. L'IA m’aide à structurer rapidement le message pour la direction, mais je reste très vigilant sur l’interprétation des écarts, car c’est là que se joue la crédibilité du pilotage budgétaire." *** ## **Management et encadrement** {% hint style="success" icon="lightbulb" %} **Cas d'usage 1 : Préparer une réponse à une question parlementaire à partir de notes existantes**\ \ 👤 **PROFIL** : Alexandre, directeur de projet à la direction générale des entreprises\ 🎯 **BESOIN** : répondre à une question parlementaire sur un dispositif d'aide aux entreprises dont il a la charge\ 📍 **CONTEXTE** : Alexandre a rédigé au cours des 6 derniers mois plusieurs notes validées par sa direction et par le cabinet ministériel sur ce dispositif : note de lancement, bilan à 3 mois, réponse à une polémique médiatique, chiffres clés. Il doit maintenant répondre à une question parlementaire précise qui porte sur l'efficacité du dispositif.\ 🔧 **OUTIL** : Assistant IA interministériel {% endhint %} **💬 PROMPT UTILISÉ** : > Je suis directeur de projet à la direction générale des entreprises. Voici 4 notes que j'ai rédigées sur le dispositif d'aide aux entreprises \[copier-coller ou téléchargement des 4 notes validées].\ > Voici la question parlementaire reçue : \[copier-coller de la question].\ > \ > À partir de ces éléments de contexte validés, rédige une première version\ > de réponse à la question parlementaire.\ > Structure :\ > *Rappel du dispositif (2 lignes)*\ > Réponse factuelle à la question posée\ > *Chiffres clés si pertinent*\ > Conclusion (perspectives)\ > \ > Ton institutionnel et factuel. Maximum 400 mots.\ > N'invente aucun chiffre, utilise uniquement ceux présents dans mes notes. \ ✨ **RÉSULTAT** : une première version de réponse structurée, qui reprend les éléments factuels validés des notes précédentes. Alexandre a ensuite vérifié chaque chiffre, ajusté le ton pour le rendre plus politique, et fait valider par son directeur de cabinet. ⚠️ **VIGILANCE** : * Vérifier TOUS les chiffres : l'IA peut mélanger des données de périodes différentes * Vérifier la cohérence : les notes sources peuvent contenir des informations contradictoires si elles datent de périodes différentes * Adapter le ton : passer d'un ton technique à un ton politique adapté au contexte parlementaire * Pas de mention dans la réponse parlementaire elle-même (rédigée à partir de notes validées par la hiérarchie). En revanche, mentionner dans la chaîne interne de validation que la première version a été préparée avec l'aide d'une IA. 🎯 **Conseil d'Alexandre :** "Je constitue systématiquement un dossier par grande politique publique avec toutes les notes validées. Cela me permet de gagner un temps fou quand je dois répondre à une commande urgente. L'IA me fait gagner du temps sur la synthèse, mais la relecture et la validation restent essentielles." {% hint style="success" icon="lightbulb" %} **Cas d'usage 2 : Rédiger un feedback constructif pour un entretien annuel**\ \ 👤 **PROFIL** : Martine, cheffe de service dans une DREAL\ 🎯 **BESOIN** et **CONTEXTE** : préparer des feedbacks constructifs pour les entretiens annuels de ses 12 collaborateurs\ 🔧 **OUTIL** : Assistant IA interministériel {% endhint %} \ **💬 PROMPT UTILISÉ** : > Je suis manager. Je prépare l'entretien annuel d'un agent. Voici mes notes sur l'année écoulée \[copier-coller des notes : "l'agent A a bien géré le dossier X, mais a eu des difficultés sur le projet Y, manque d'autonomie sur les sujets techniques"].\ > Rédige un feedback constructif en 3 paragraphes pour m'aider à préparer l'entretien annuel :\ > 1\. Points forts (ce qui a bien fonctionné)\ > 2\. Axes d'amélioration (formulés de manière positive et encourageante)\ > 3\. Objectifs pour l'année prochaine\ > Ton bienveillant et professionnel. Maximum 300 mots. ✨ **RÉSULTAT** : une première version de feedback, structurée et équilibrée, pour chaque agent :\ les points forts sont clairement valorisés, les axes d’amélioration sont formulés de manière constructive et non stigmatisante, et des objectifs concrets pour l’année suivante sont proposés. ⚠️ **VIGILANCE** : * Vérifier la justesse des faits : l’IA reformule à partir des notes fournies, mais peut simplifier ou atténuer certains éléments importants. * Éviter les formulations trop génériques : un feedback doit rester personnalisé et refléter la réalité du travail de l’agent. * S’assurer que les objectifs proposés sont réalistes et compatibles avec les priorités du service et les moyens disponibles. * Relire attentivement le ton pour qu’il soit adapté à la sensibilité et au profil de l’agent (ancienneté, situation individuelle, contexte particulier). * Aucune mention dans le document final transmis à l'agent : l'IA n'a servi qu'à préparer une trame, le contenu reste celui du manager. En revanche, mentionner à l'oral en début d'entretien que vous vous êtes appuyée sur des notes structurées avec l'aide d'un outil si vous le souhaitez. 🎯 **Conseil de Martine :** "Je prépare toujours quelques notes très factuelles avant de solliciter l’IA. Elle m’aide surtout à trouver le bon équilibre entre valorisation et pistes de progression. Malgré tout, je prends le temps de personnaliser chaque feedback." *** ## **Développement et numérique** {% hint style="success" icon="lightbulb" %} **Cas d'usage 1 : Documenter du code ou une procédure technique**\ \ 👤 **PROFIL** : Sébastien, chef de projet numérique à la DNUM des ministères sociaux\ 🎯 **BESOIN** : documenter une procédure technique afin de la rendre compréhensible par des équipes non développeuses et faciliter la maintenance.\ 📍 **CONTEXTE** : Sébastien pilote un outil développé en interne. La procédure de déploiement et de mise à jour est décrite uniquement dans des scripts techniques et dans quelques commentaires dispersés. Plusieurs agents doivent pouvoir reprendre la main sur l’exploitation de l’outil sans dépendre systématiquement de l’équipe de développement.\ 🔧 **OUTIL** : Assistant IA interministériel. {% endhint %} **💬 PROMPT UTILISÉ** : > Je suis chef de projet numérique dans une administration.\ > Voici une procédure technique et des extraits de scripts utilisés pour le déploiement et la maintenance d’un outil interne : \[copier-coller de la procédure et des extraits de code].\ > À partir de ces éléments, rédige une documentation opérationnelle à destination d’agents non développeurs.\ > Structure attendue :\ > \- Objectif de la procédure\ > \- Prérequis techniques\ > \- Étapes détaillées pas à pas\ > \- Points d’attention et erreurs fréquentes\ > Ton clair, pédagogique et professionnel. Ne modifie pas le fonctionnement technique existant. \ ✨ **RÉSULTAT** : une documentation structurée, compréhensible par des agents non techniques, que Sébastien complète ensuite avec les références spécifiques à son environnement. ⚠️ **VIGILANCE** : * Vérifier la conformité technique de chaque étape décrite : l’IA peut reformuler correctement mais mal interpréter certaines dépendances entre composants. * S’assurer que les commandes, chemins et paramètres sont strictement identiques à ceux utilisés en production. * Vérifier que la documentation reste alignée avec la version réelle du code et des outils. * Préciser dans l'en-tête de la documentation qu'une première version a été générée avec l'assistance d'une IA, puis vérifiée et validée techniquement par le chef de projet. 🎯 **Conseil de Sébastien :** "Je fournis toujours à l’IA uniquement des extraits validés et à jour. Elle est très efficace pour rendre une procédure lisible, mais je garde la main sur la validation technique finale avant toute diffusion." {% hint style="success" icon="lightbulb" %} **Cas d'usage 2 : Générer des tests ou des cas d'usage à partir de spécifications techniques**\ \ 👤 **PROFIL** : Nadia, responsable produit numérique à l'ANCT\ 🎯 **BESOIN** : préparer rapidement des cas de tests fonctionnels et des scénarios d’usage à partir de spécifications fonctionnelles existantes.\ 📍 **CONTEXTE** : Nadia dispose d’un cahier de spécifications décrivant les fonctionnalités d’un nouveau service numérique. Avant le démarrage des développements, elle doit fournir aux équipes projet une première liste structurée de cas de tests et de scénarios représentatifs des usages métiers.\ 🔧 **OUTIL** : Assistant IA interministériel {% endhint %} **💬 PROMPT UTILISÉ** : > Je suis responsable produit numérique dans une administration.\ > Voici les spécifications fonctionnelles d’un service numérique : \[copier-coller des spécifications].\ > À partir de ces éléments, génère une liste de cas de tests fonctionnels et de scénarios d’usage.\ > Pour chaque cas de test, indique :\ > \- le contexte ;\ > \- l’action réalisée par l’utilisateur ;\ > \- le résultat attendu ;\ > \ > Regroupe les cas par fonctionnalité, et n’invente pas de fonctionnalités qui ne figurent pas dans les spécifications. \ ✨ **RÉSULTAT** : Nadia dispose d’une base de travail homogène pour préparer les ateliers avec les équipes métier et les équipes de développement. ⚠️ **VIGILANCE** : * Vérifier que tous les cas générés correspondent bien à des fonctionnalités existantes. * Compléter les scénarios par des cas limites et des situations particulières propres aux métiers concernés. * Adapter le niveau de détail en fonction des pratiques de l’équipe de test et de la méthodologie projet. * Indiquer aux équipes destinataires que la première liste de cas de tests a été générée avec l'aide d'une IA à partir des spécifications, et qu'elle nécessite une revue métier avant validation. 🎯 **Conseil de Nadia :** "Je m’appuie sur l’IA pour obtenir une première couverture fonctionnelle rapide. Ensuite, je retravaille systématiquement les scénarios avec les métiers pour intégrer les vrais usages terrain et les exceptions." {% hint style="success" icon="lightbulb" %} **Cas d'usage 3 : Traduire de la documentation technique**\ \ 👤 **PROFIL** : Thomas, ingénieur systèmes et réseaux au service numérique du Ministère de la Culture\ 🎯 **BESOIN ET** **CONTEXTE** : Thomas utilise des outils open source dont la documentation officielle est exclusivement en anglais. Il doit produire une version française pour les équipes d’exploitation et d’assistance, sans altérer le sens technique des procédures.\ 🔧 **OUTIL** : Assistant IA interministériel {% endhint %} **💬 PROMPT UTILISÉ** : > Je suis ingénieur systèmes dans une administration.\ > Voici une documentation technique en anglais concernant un outil utilisé en production :\ > \[copié-collé de la documentation].\ > Traduis ce document en français. Conserve le vocabulaire technique approprié et ne modifie pas les commandes, paramètres, noms de fichiers ou extraits de code.\ > Ton professionnel et technique. \ ✨ **RÉSULTAT** : une traduction complète et structurée de la documentation, directement exploitable par les équipes techniques francophones. ⚠️ **VIGILANCE** : * Vérifier la traduction des termes techniques sensibles, qui peuvent avoir plusieurs équivalents selon le contexte. * S’assurer que les exemples de commandes, scripts et paramètres n’ont pas été modifiés. * Harmoniser le vocabulaire avec celui déjà utilisé dans la documentation interne existante. * Préciser en en-tête de la documentation que la traduction a été réalisée avec l'assistance d'une IA et relue par l'ingénieur, en conservant la documentation originale en référence. 🎯 **Conseil de Thomas :** "Je demande toujours à l’IA de ne pas toucher aux blocs techniques et je relis systématiquement les passages critiques. Elle me fait gagner beaucoup de temps sur la traduction, mais la validation technique reste indispensable avant diffusion." # Techniques avancées de RAG dans Albert API Albert API propose un endpoint POST `/v1/rerank` qui permet d'appeler des modèles de reranking. Ces modèles sont particulièrement intéressants pour améliorer votre pipeline de RAG (Retrieval Augmented Generation). **Dans ce tutoriel nous allons voir :** * **pourquoi utiliser un modèle de reranking,** * **qu'est-ce qu'un modèle reranking**, * **quand l'utiliser** * **comment l'utiliser.** ## Prérequis * Connaissance des notions de RAG, de vector-store, d'embeddings et de chunks * Connaissance de l'upload et de la recherche de documents avec Albert API. Pour en savoir plus sur ces notions, voir le guide Construire un RAG avec Albert API *(à venir)*. ## Pourquoi utiliser le reranking ? Lorsque vous construisez un système de RAG, vous devez : 1. Rechercher des documents pertinents dans un vector store 2. Sélectionner les meilleurs passages 3. Les envoyer au modèle de génération Le problème : la recherche vectorielle retourne souvent **des résultats approximatifs**. En effet, que ce soit avec une recherche sémantique, lexicale ou hybride, **la recherche dans un vector store est une recherche à larges mailles**. Elle permet ainsi de retrouver les *chunks* qui gravitent autour de la requête recherchée mais cela peut prendre dans le filet des chunks relativement éloignés contextuellement. En conséquence, un moteur vectoriel est très rapide, mais il peut retourner : * des résultats **un peu hors sujet** * des passages **moins pertinents que d'autres** * des résultats dans **un ordre sous-optimal** Ainsi si certains résultats de recherche sont pertinents, d'autres beaucoup moins. C'est précisément le rôle de l'endpoint **`/v1/rerank`** : **réordonner les résultats de recherche pour ne garder que les passages les plus pertinents pour une requête.** *** ## Qu'est ce que le reranking ? Le **reranking** utilise un petit modèle puissant pour : * comparer **la requête utilisateur** * avec **chaque document trouvé** * et produire **un score de pertinence** Albert API propose un modèle de reranking ***openweight-rerank***. Pour plus d'informations sur ce modèle, voir les [modèles disponibles](https://albert.sites.beta.gouv.fr/solutions/models/). Pour connaître quels sont les modèles de reranking disponibles, faites une requête au endpoint `/v1/models` . Parmi ceux retourné, les modèles de reranking ont le type `text-classification`. {% hint style="info" %} Un modèle de reranking est généralement un modèle de classification de quelques millions de paramètres spécialement entraîné sur des paires questions-documents. Lors de son entrainement le modèle a appris à inférer sur la base de millions d'exemples des patterns permettant d'attribuer un score à la pertinence d'un document vis-à-vis d'une question. {% endhint %} ## Quand utiliser le reranking ? Le reranking est utile lorsque : * vous avez beaucoup de documents * le contexte du LLM est limité (ex : openweight-large) * les capacités du LLM à analyser un grand contexte sont limitées (ex : openweight-small) *** ## Comment utiliser le reranking ? ### Fonctionnement général L'endpoint `/v1/rerank` prend : * une **query** * une **liste de documents** et retourne les documents **triés par pertinence.** Chaque document reçoit un **score de pertinence**. ### Pipeline de RAG avec le reranking Si vous souhaitez un RAG avec 5 chunks pour augmenter le contexte de la requête utilisateur, alors dans un premier temps récupérez 40 chunks proches avec `/v1/search`. Puis vous affinez avec `/v1/rerank` pour obtenir les 5 chunks les plus pertinents. 
graph TD
  user_request(Requête utilisateur)
  response(Réponse)
  
  
  user_request 
  --> /v1/search 
  --"40 chunks" --> /v1/rerank 
  -- "5 chunks" --> /v1/chat/completions 
  --> response
### Étape 1. Recherche vectorielle On commence par récupérer les documents les plus proches de la requête utilisateur. {% tabs %} {% tab title="Python" %} ```python import os import requests response = requests.post( url="https://api.albert.etalab.gouv.fr/v1/rerank", headers={"Authorization": f"Bearer {os.environ.get('ALBERT_API_KEY')}"}, json={ "query": "Comment déployer une application Docker ?", "method": "semantic", "limit": 40, }, ) data = response.json()["data"] chunks = [chunk.content for chunk in data.chunk] ``` {% endtab %} {% endtabs %} À ce stade, les documents sont **proches sémantiquement**, mais pas forcément les plus pertinents pour répondre précisément à la question. C’est pourquoi on ajoute une étape de **reranking**. {% hint style="info" %} Le reranking est utile quelque soit la méthode de recherche utilisée (sémantique, lexicale, hybride). Attention toutefois, il peut être inutile, voir contre-productif. Voir les [bonnes pratiques](#bonnes-pratiques) pour plus d'informations. {% endhint %} ### Étape 2. Reranking Le reranker réévalue les documents retournés par la recherche vectorielle afin de déterminer **les plus pertinents pour la requête**. {% tabs %} {% tab title="Python" %} ```python import os import requests user_query = "Comment déployer une application Docker ?" response = requests.post( url="https://api.albert.etalab.gouv.fr/v1/rerank", headers={"Authorization": f"Bearer {os.environ.get('ALBERT_API_KEY')}"}, json={ "model": "openweight-rerank", "query": user_query, "documents": chunks, "top_n": 5, }, ) data = response.json() ``` {% endtab %} {% endtabs %} **Réponse** ```json { "results": [ { "index": 2, // Position du document dans la liste d'entrée "relevance_score": 0.98 // Score de pertinence calculé par le modèle }, ... ] } ``` ### Étape 3. Reconstruction des documents triés On récupère les documents dans le bon ordre à partir des indices retournés. {% tabs %} {% tab title="Python" %} ``` ranked_chunks = [chunks[result["index"]] for result in data["results"]] ``` {% endtab %} {% endtabs %} ### Étape 4. Génération avec le contexte On injecte les documents les plus pertinents dans le prompt du LLM comme *openweight-small* par exemple. {% tabs %} {% tab title="Python" %} ```python rag_template = """Réponds à la question en te basant sur les documents suivants. Si la réponse à la question n'est pas dans les documents, indique que tu ne t'es pas appuyé sur ces documents pour générer la réponse, sinon cite les sources de ta réponse. [QUESTION] {user_query} [DOCS] {chunks} """ query = rag_template % {"user_query": user_query, "chunks": "\n\n".join(chunks)} response = requests.post( url="https://api.albert.etalab.gouv.fr/v1/chat/completions", headers={"Authorization": f"Bearer {os.environ.get('ALBERT_API_KEY')}"}, json={ "model": "openweight-small", "messages": [{"role": "user", "content": query}], }, ) data = response.json() ``` {% endtab %} {% endtabs %} Le modèle utilise alors **le contexte fourni pour générer une réponse plus fiable et précise**. *** ## Bonnes pratiques ### 1. Reranker plus de documents que nécessaire Pipeline recommandée : * Search : limit = 20 à 50 * Rerank : top\_n = 3 à 10 Cela permet au reranker de choisir les documents les plus pertinents parmi un ensemble suffisamment large. ### 2. Utiliser des chunks courts La qualité du reranking dépend fortement de la taille des documents. Nous recommandons 100 à 500 tokens par chunk. Les documents trop longs diluent l’information importante et réduisent la précision du reranker. ### 3. Le reranking peut être inutile ou contre-productif Le reranking est un outil puissant, mais il ne faut pas l'utiliser à chaque fois. Vous devez déterminer si le reranking est nécessaire pour votre cas d'usage en testant des requêtes sur vos documents. Par exemple, la recherche hybride peut obtenir des scores de pertinence dans certains cas plus précis que le reranking. Dans ce cas, ce dernier va éliminer des documents pertinents. Comme pour toute technique, il faut tester et mesurer les performances à l'aide d'un processus de d'évaluation. # Utiliser l'IA générative dans l'administration ## Bonnes pratiques d’utilisation des solutions d'IA générative Ces bonnes pratiques s’appuient largement sur la [charte interne du ministère de la Culture](https://cdip.bnf.fr/Record.htm?record=19143501124919617839\&idlist=1) pour un usage responsable de l’IA générative​. * **Examinez d’un œil critique les propositions qui vous sont faites et vérifiez toujours l’exactitude des réponses :** l’IA générative peut produire des informations inexactes ou biaisées et le vraisemblable n’est pas le véritable. Il s’agit ici d’adopter la même vigilance que vous pourriez avoir dans le contrôle des sources plus classiques que vous utilisez : chacun est responsable de la manière dont il vérifie, apprécie et réutilise une information. * **Soyez transparent(e) :** si un document ou une analyse a été produit avec l’aide d’une IA, il est recommandé d’en informer ses collègues, sa hiérarchie ou ses destinataires, en particulier si ce sont des usagers du service public. * **Respectez la propriété intellectuelle** : l’origine des données utilisées par ces outils n’est pas toujours clairement documentée. N’utilisez pas, notamment pour une diffusion externe, un contenu que vous pourriez légitimement suspecter de réutiliser du contenu protégé. * **Soyez conscient(e) des biais** : gardez à l'esprit qu'il s'agit seulement d'un outil et essayez de comprendre comment il fonctionne. * **Raisonnez votre usage pour limiter l’impact environnemental** : l’IA générative est très consommatrice en énergie. Son usage doit être raisonné et pertinent. ## Usages non sensibles Certains cas d'usages de l'IAG au sein de l'administration peuvent être considérés comme "non sensibles" au sens où, par exemple, les données traitées sont publiques ou pourraient être rendues publiques ou qu'elles ne contiennent pas de données personnelles. Pour ces cas d'usages, il est possible d'utiliser des solutions commerciales disponibles sur Internet ou de recourir à l'achat public pour en acheter sur étagère en respectant le cadre de la commande publique (*ex : achat hors marché (< 40k €) par une administration de licences pour un outil de génération d'images, non hébergé sur un hébergement "SecNumCloud".)* Voici quelques exemples : * **Synthèse automatique de documents publics** (ex : rapports, délibérations, comptes rendus). * **Génération ou relecture de brouillons de textes** (notes, FAQ), quand cela ne nécessite pas de dévoiler des informations confidentielles * **Aide à la production de code** pour outiller les développeurs publics. * **FAQ enrichies par IA** pour des guides à destination des agents ou intranets ou espaces agents. * **Synthèse ou quiz de formation** générés automatiquement. * **Aide à la réflexion** (brainstorming) * **Transcription automatique** de vidéos publiques * **Production de visuels** pour illustrer des présentations ou des rapports * **Exploration et visualisation automatisées** de données publiques. * **Rédaction de résumés ou d’analyses** sur des jeux de données non sensibles. {% hint style="success" %} **Pour ces usages, il est important de veiller à saisir uniquement des informations qui peuvent être rendues publiques :** ne communiquez pas de données personnelles, les vôtres ou celles de vos collègues ou d’usagers, de données protégées par le droit de la propriété intellectuelle ou industrielle, de données confidentielles liées à l’exercice de vos fonctions ou liées au secret des affaires des acteurs avec lesquels vous interagissez, etc. Ce qui est transmis à ces outils peut être stocké et utilisé ultérieurement. {% endhint %} ### **Situations où les solutions non souveraines ne doivent pas être utilisées** * Lorsqu’il y a un risque de divulgation de données protégées ou sensibles. * Lorsque les conditions d’utilisation du service ne sont pas claires ou conformes à la réglementation européenne. Les conditions d'utilisation des principales plateformes d'IA générative sont suivies via OpenTermsArchive [à ce lien](https://github.com/OpenTermsArchive/genai-versions). * Lorsque sa hiérarchie l'interdit pour certains usages Si vous avez des doutes ou des besoins spécifiques, nous vous recommandons de vous rapprocher de votre DSI ou de votre référent cybersécurité. ## Usages sensibles Pour les cas d’usage impliquant des [**données sensibles**](https://www.legifrance.gouv.fr/jorf/article_jo/JORFARTI000049563610), il est impératif d’utiliser **des solutions souveraines**, hébergées sur des infrastructures conformes à **SecNumCloud** ou équivalentes. La DINUM met à disposition des outils interministériels pour répondre à ces usages. Pour en savoir plus : [L'IA dans LaSuite](/socle-interministerielle-dintelligence-artificielle-generative/lia-dans-lasuite) # Guide d'installation des LLMs (2024) Le projet KALLM (Kit avancé LLM) est un guide pratique destiné aux administrations publiques souhaitant adopter des modèles de langage à grande échelle (LLM) pour des tâches d’analyse textuelle. {% hint style="danger" %} Ce guide a été rédigé en 2024. Nous le maintenons ici pour valoriser ce travail de grande qualité et en accord avec les principes de transparence de la vie publique, mais la nature et l'usage des LLMs ont grandement évolué depuis son écriture. {% endhint %} **Développé dans le cadre de la troisième saison du Programme 10% d’Etalab**, en partenariat entre plusieurs administrations, ce guide accompagne les techniques pour la mise en production d’un modèle adapté à leur besoin au sein de l'État. Il propose des recommandations concrètes sur le **choix des modèles**, les **infrastructures nécessaires**, les **techniques de fine-tuning**, d’**évaluation et de déploiement**, tout en abordant les **aspects environnementaux et financiers liés à l’utilisation des LLM**. Aller vers le guide {% hint style="info" %} #### Ce guide est particulièrement adapté si vous êtes : * Un datascientist au sein d'un service de l'État * Un ingénieur ou architecte de la donnée * Un développeur au sein d'une équipe produit qui veut intégrer l'IA dans son service {% endhint %} #### Ce que couvre le guide en bref * l’infrastructure minimale pour faire tourner un LLM * benchmarking des “principaux” LLM * exemple d’utilisation dans un cas simple (cas d’utilisation dit “fil rouge”) sous forme de tutoriel * finetuner un modèle LLM * quantizer un modèle LLM * Evaluer un LLM * mettre en production un modèle LLM * une bibliographie concise et non exhaustive * d’autres exemples plus complexes de cas d’utilisation dans l’administration * une approximation du coût environnemental et financier des différents LLM #### Ce que ne couvre pas (encore) ce guide * les fondements théoriques de l’optimisation * cas spécifique d’une administration * comment débiaiser un LLM # Le panorama des solutions IA dans l'État Une carte qui vous permet de naviguer dans les solutions IA de l'État. #### À quoi ça sert ? Ce recensement vise à **cartographier les projets d’intelligence artificielle (IA)** dans l’administration publique française afin de : * Valoriser les solutions existantes, * Améliorer la transparence des projets, * Soutenir la stratégie de commande publique et la mutualisation des outils IA. *** #### À qui est-ce destiné ? À **toutes les administrations, services publics et opérateurs de l’État** qui conçoivent, développent ou exploitent une solution intégrant de l’IA, quel que soit son stade d’avancement (prototype, développement, production, etc.). *** #### Comment ajouter ma solution ? {% stepper %} {% step %} **Avant de commencer**, vous pouvez : * [Consulter les projets déjà recensés](https://grist.numerique.gouv.fr/o/etalab/2BXtzHFoPVB9/Produits-IA-dans-lEtat?utm_id=share-doc) * [Rejoindre le canal Tchap pour modifier un projet existant](https://tchap.gouv.fr/#/room/!MqmVrWuAPzbaCTeOQh:agent.dinum.tchap.gouv.fr?via=agent.dinum.tchap.gouv.fr) {% endstep %} {% step %} **Remplissez le formulaire dédié** en décrivant votre produit, ses usages et ses briques techniques. {% endstep %} {% step %} **Votre projet est sensible ?** Cochez la case : *Je ne souhaite pas que les informations concernant ce projet soient publiées.* {% endstep %} {% endstepper %} Recenser ma solution IA Voir le panorama {% hint style="warning" %} Il faut être connecté sur Grist via Proconnect pour avoir accès au panorama. {% endhint %} {% hint style="info" %} ✉️ **Une question ?**\ Utilisez le champ libre à la fin du formulaire pour nous écrire. {% endhint %} # Liens utiles Culture produit, sécurité et stratégie française... les ressources à lire pour tout comprendre. ### Culture produit IA * [**Le guide pour faire de l'IA chez beta.gouv**](https://doc.incubateur.net/communaute/gerer-son-produit/faire-de-lia-chez-beta/guide-pour-definir-un-probleme-metier-actionnable-par-lia), *beta.gouv.fr* ### Sécurité et souveraineté * [**Quels points de vigilance avoir lorsque vous dialoguez avec ChatGPT ?**](https://pad.numerique.gouv.fr/teCWpmkGSlG970GLe4aTDQ), par Numéricité pour [beta.gouv.fr](http://beta.gouv.fr/) * [**Recommandations de sécurité pour un système d’IA générative**](https://cyber.gouv.fr/publications/recommandations-de-securite-pour-un-systeme-dia-generative), *Agence nationale de la sécurité des systèmes d'information (ANSSI)*, 2024 * [**Les fiches pratiques IA de la CNIL**](https://www.cnil.fr/fr/les-fiches-pratiques-ia), orientées traitement des données personnelles * [**Entrée en vigueur du règlement européen sur l’IA : les premières questions-réponses de la CNIL**](https://www.cnil.fr/fr/entree-en-vigueur-du-reglement-europeen-sur-lia-les-premieres-questions-reponses-de-la-cnil)**,** juillet 2024 ### Stratégie IA de l'État * [**Faire de la France un puissance de l'IA**](https://projets.beta.numerique.gouv.fr/cards/1459378389935719479)**,** *Comité interministériel de l’Intelligence artificielle*\ 6 février 2025 * [**IA, notre ambition pour la France**](https://www.bercynumerique.finances.gouv.fr/le-rapport-ia-notre-ambition-pour-la-france), *Comité national pour l’intelligence artificielle*, mars 2024 # Retours d'expériences Des histoires de réussite et de résilience ! **Dans un écosystème qui évolue aussi rapidement que celui de l'intelligence artificielle, la mutualisation des apprentissages est essentielle.** Quand promouvoir et faire converger les meilleures solutions respectueuses de nos standards est une priorité, échouer rapidement pour raconter son histoire devient une démonstration d'impact et évite que les mêmes écueils se répètent. Cet espace est dédié au retour des équipes accompagnées par l'incubateur et ses communautés amies. Il est également destiné à ceux qui les suivront dans leurs expérimentations et tireront bénéfice de leurs histoires. {% content-ref url="/pages/lCKB9izTxDSY3FUwcUmK" %} [Beta-test d'Albert-Api, 5 mois d'expérimentations｜3 avril 2025](/ressources/retours-dexperiences/beta-test-dalbert-api-5-mois-dexperimentations-3-avril-2025) {% endcontent-ref %} {% content-ref url="/pages/me1k1aUYaB8PMRdTkPTR" %} [Retex assistant de réponses virtuel｜ Forum ALLiaNCE du 9 avril 2025](/ressources/retours-dexperiences/retex-assistant-de-reponses-virtuel-forum-alliance-du-9-avril-2025) {% endcontent-ref %} # Beta-test d'Albert-Api, 5 mois d'expérimentations｜3 avril 2025 En marge du forum beta, les startups d'État font leurs retours d'expérience sur quelques mois d'expérimentation libre sur Albert-api. {% hint style="info" %} **Date** : 03/04/2025\ **Animé par** : Elsa Le Duigou et Jules Pondard\ **Les participants** : services numériques de l’État de la communauté beta.gouv\ **L'objectif** : faire le bilan, à 5 mois, de l’expérimentation sur l’Albert API {% endhint %} {% embed url="" %} ### Présentation d'Albert API Albert API est une **boîte à outils d’IA souveraine** conçue pour faciliter l’intégration de l’IA générative dans les services publics. Elle vise à fournir : * Des briques prêtes à l’emploi (LLM, OCR, RAG, etc.) * Une infrastructure mutualisée * Une interface unifiée via une API Gateway * Des usages sécurisés et peu coûteux #### Ses caractéristiques | **Avantages clés** | Souveraineté, sécurité, puissance, faible coût | | -------------------------- | ------------------------------------------------------------------------ | | **Profils ciblés** | Explorateurs (analystes), constructeurs (développeurs), opérateurs | | **Services disponibles** | LLM, speech-to-text, RAG sur fichiers PDF | | **À venir** | OCR amélioré, deepsearch, suivi précis par utilisateur | | **Chiffres clefs d’usage** | 50k requêtes/semaines, 62 produits utilisateurs, 1/2 de part d’embedding | ## Les cas d'usage expérimentés par les services numérique de la communauté
Coop de la médiation numérique * **Finalité** : Assistant conversationnel à destination des médiateurs numériques. * **Fonctionnalités** : Recherche documentaire et web (filtrée via Brave), réponse aux questions des usagers. * **Albert utilisé pour** : Embedding des contenus. * **Limites identifiées** : * Performance aléatoire sur l’infrastructure Scaleway. * Impossibilité de spécifier une whitelist de domaines pour la recherche.
Conseil de l’évaluation de l’École (CEE) * **Finalité** : Analyse des rapports d’évaluation produits chaque année par le conseil d'évaluation de l'école (env. 12 000/an, 60 000 en base). * **Objectif** : Identifier des tendances et générer des synthèses pour orienter les politiques publiques. * **Albert utilisé pour** : Embedding + RAG sur corpus documentaire. * **Défis** : * Format des documents très hétérogène (PDF image, tableaux complexes…). * Taux d’erreur de \~20% sur certaines extractions (numéros de page notamment). * Produit encore en phase de test.
SignalConso * **Finalité** : Optimiser le traitement automatisé des signalements citoyens. * **Fonctionnalités IA** : * Résumé automatique avec détection d’insultes * Vérification de la compétence DGCCRF via le Code conso (RAG) * Identification de l’entreprise à partir du signalement * **Albert utilisé pour** : RAG juridique + résumés * **Points de vigilance** : * Hallucinations lors de l’analyse juridique * Difficultés à harmoniser les libellés pour les statistiques * Distinction délicate entre insultes directes et rapportées
Mon Devis Sans Oubli * **Finalité** : Analyse automatique de devis dans le cadre de rénovations énergétiques. * **Pipeline technique** : * Extraction de données personnelles via Albert (PDF → texte) * Reconnaissance des gestes de travaux via Mistral * **Volumétrie** : 1300 devis pour 1000 utilisateurs * **Albert utilisé pour** : Traitement structuré initial avant anonymisation * **Défis** : * Problèmes d’OCR sur les scans * Limites du traitement synchrone (réponse attendue < 5 min) * Possibilité de recentrer l’ensemble du traitement dans Albert à terme
Barnabé * **Finalité** : Synthèse thématique de lots de documents (ex. Contrats de Ville, Quartiers 2030) * **Albert utilisé pour** : * Embedding * OCR * Traitement batch (asynchrone) * **Technos associées** : LlamaParse * **Limites** : * Taille de fenêtre de contexte trop restreinte pour certains cas d’analyse * Usage uniquement batch à ce stade, mais bonne complémentarité avec les objectifs d’Albert
## :sparkles: Conclusions et perspectives #### Forces identifiées * Mutualisation des outils IA entre administrations * Large panel d’usages déjà opérationnels * Flexibilité dans les architectures déployées (embedding, RAG, OCR, etc.) * Coût d’usage maîtrisé #### Axes d’amélioration * Stabilisation des performances sur l'infra * Amélioration de l’OCR sur documents complexes * Meilleure adaptation aux spécificités des langages administratifs et juridiques * Extension de l’API aux cas d’usage batch (type Barnabé) ### Contact {% hint style="success" %} **📅 Pour prendre rendez-vous avec l’équipe Albert :**\ 👉 [albertapi.youcanbook.me](http://albertapi.youcanbook.me) 📧 Pour toute question produit, contacter l’équipe via vos canaux habituels sur [beta.gouv.fr](http://beta.gouv.fr) {% endhint %} ### # Retex assistant de réponses virtuel｜ Forum ALLiaNCE du 9 avril 2025 La présentation des retours d'expérience de deux assistants virtuels propulsés par de l'IA proposés aux agents des maisons France services et des services de renseignement en droit du travail. {% embed url="" %} # Écrire sa fiche action La fiche action permet d'accéder à un accompagnement chez ALLiaNCE. {% hint style="success" %} Cette fiche vise à structurer et analyser votre produit d’IA selon la méthode [beta.gouv.fr](http://beta.gouv.fr). Elle vous permettra de qualifier le problème que vous souhaitez résoudre, d’expliciter la solution, démontrer et mesurer son impact, tout en identifiant les étapes nécessaires pour passer à l’échelle. {% endhint %} ## Intitulé du produit * **Nom du produit + slogan** {% hint style="info" %} *Exemple : Signaux Faibles – Mieux cibler les interventions vers les entreprises en difficulté.* {% endhint %} **Administration ou structure porteuse :** **Chef de produit identifié :** prénom, nom, fonction. * **Quel est le problème à résoudre ?** * Quels irritants rencontrent vos bénéficiaires (surcoûts, sous-qualité, non-recours, délais) ? * En quoi ce problème limite-t-il l’efficacité de votre structure ou nuit-il aux usagers ? * **Coût du *****statu quo***** :** quel est le préjudice ou coût de ne pas avoir de solution IA ? * Impact mesurable : temps perdu, erreurs, manque à gagner, surcharge pour les agents. * Impact sur les bénéficiaires finaux : délais, non-recours, insatisfaction. {% hint style="info" %} *Exemple : Chaque année, les DIRECCTE détectent mal ou trop tard les entreprises en difficulté, entraînant un manque à gagner de X millions d’euros.* {% endhint %} ### Solution (la bonne idée) * **Approche proposée :** comment l’IA répond à cet irritant ? * **Singularité de la solution :** utilisation d’un modèle libre ou propriétaire, algorithme spécifique, innovation technique ou organisationnelle. * **Transformation grâce à l’IA :** décrivez ce qui change avec la solution proposée. {% hint style="info" %} *Exemple : Croiser des bases de données aujourd’hui en silo pour détecter et prévenir les difficultés des entreprises afin de mieux cibler les interventions en remédiation de l’État.* {% endhint %} **Évaluation du coût (TCO)** * **Budget annuel total :** montant incluant développement, infrastructure et maintenance. * **Ressources nécessaires :** * Infrastructures techniques : GPU, stockage, logiciels spécifiques. * Ressources humaines : experts en IA, développeurs, agents utilisateurs. * **Co-financements :** contributions internes ou externes, par exemple financements incubateurs. * **Amortissement :** précisez les coûts annualisés sur 6 mois, 1 an ou plus. {% hint style="info" %} *Exemple : 200 000 €/an incluant GPU et expertise, cofinancé à 50 % par l’administration.* {% endhint %} ### Stratégie de déploiement et mise en marché #### Stade de développement * **Votre produit est-il actuellement en production, même modeste ?**
**Expérimentation et itérations** * **Population pilote :** qui sera impliqué dans les tests initiaux ? Quel périmètre géographique ou organisationnel ? * **Calendrier des itérations :** précisez un plan d’action sur 6 mois pour mesurer l’impact et affiner le produit. * **Avez-vous l’intention d’itérer en conditions réelles ?** Si oui, précisez quand et sur quelle population pilote. {% hint style="info" %} *Exemple : Déploiement auprès d’un département pilote avec X agents et un échantillon de Y dossiers à traiter.* {% endhint %} #### Indicateurs de performance technique Les indicateurs d'impact doivent démontrer la capacité de l’outil à résoudre les irritants identifiés : * **Qualité des résultats :** mesurée par le taux de faux positifs/négatifs, la précision des prédictions ou la fiabilité du modèle dans des cas réels. **Impact attendu et retour sur investissement (ROI)** Le ROI doit refléter des gains quantifiables et des bénéfices qualitatifs : * **Gains quantifiables :** * Réduction des coûts (montants évités par dossier traité, économies d’échelle). * Temps économisé par les agents ou les utilisateurs finaux (en heures ou jours). * **Bénéfices qualitatifs :** * Satisfaction des bénéficiaires grâce à des réponses plus rapides et fiables. * Amélioration des processus internes, réduisant la surcharge administrative.
**Potentiel de mutualisation et réplicabilité** * **Réplicabilité :** * Votre solution peut-elle devenir un **outil générique** réutilisable dans d’autres administrations ou contextes ? * Si oui, décrivez les adaptations nécessaires. * **Mutualisation :** Modalités pour intégrer votre produit dans une offre commune (ex. Albert API). {% hint style="info" %} *Exemple : Développer un module générique de traitement automatisé des recours, applicable dans plusieurs ministères.* {% endhint %} {% hint style="info" %} #### Conseils et bonnes pratiques 1. **Évitez le solutionnisme technologique :** L’IA doit répondre à un problème réel et mesurable, et non être utilisée pour elle-même. 2. **Pensez modulaire et itératif :** Une petite solution bien déployée vaut mieux qu’une ambition démesurée au départ. 3. **Priorisez l’impact :** Identifiez des améliorations concrètes, mesurables et immédiatement perceptibles. 4. **Expliquez le pari d’impact :** En 6 mois, que se passe-t-il de mieux pour vos bénéficiaires ? {% endhint %} # S'embarquer Bienvenue chez ALLiaNCE ! Voici la page qui facilitera ton intégration au sein de la communauté de l'incubateur IA de l’État. ## La première semaine : se mettre en selle ### 👥 Quelque soit ton profil {% stepper %} {% step %} **Créer ton compte sur l'**[**espace membre beta.gouv.fr**](https://espace-membre.incubateur.net/dashboard). Cela permet d'avoir accès à tous les outils de la communauté, et d'obtenir une adresse mail dédiée. * [ ] \[Si tu es porteur de produit ou premier arrivé dans l'équipe] **Rédige ou actualise ta fiche action** pour qu'elle soit présentée sur le site d'ALLiaNCE. Tu peux la gérer toi-même à partir de l'espace membre. {% endstep %} {% step %} **Rejoindre les différents canaux** **Tchap d'ALLiaNCE** **pour avoir accès aux discussions des équipes** * [ ] Rejoins la communauté ALLiaNCE sur l'espace parent **🤖**[**IA dans l’État**](https://tchap.gouv.fr/#/room/#IAdansltatSpKrvQH2Odu:agent.dinum.tchap.gouv.fr) ; * [ ] Pour avoir les dernières actualités sur l'incubateur, rejoins le salon [**🎙️Général ALLiaNCE**](https://tchap.gouv.fr/#/room/!tPzThAoNsAAClYSczG:agent.dinum.tchap.gouv.fr?via=agent.dinum.tchap.gouv.fr) **;** * [ ] Si ce n'est pas déjà fait, demande à l'équipe dans [**🎙️Général ALLiaNCE**](https://tchap.gouv.fr/#/room/!nESqGCRMjtMlIVkByv:agent.dinum.tchap.gouv.fr?via=agent.dinum.tchap.gouv.fr) de créer un canal dédié avec le nom de ton produit. * [ ] Ajoute les espaces que tu juges les plus intéressants dans le domaine de **IA dans l'État** : * [ ] 📚[Produits incubés](https://tchap.gouv.fr/#/room/!hQnbTJkBsuWMVUFrZI:agent.dinum.tchap.gouv.fr?via=agent.dinum.tchap.gouv.fr) * [ ] 🫶[Communautés IA](https://tchap.gouv.fr/#/room/!tiGSNoyMPdVBMDAaZx:agent.dinum.tchap.gouv.fr?via=agent.dinum.tchap.gouv.fr) * [ ] [🛠️Support/Retext](https://tchap.gouv.fr/#/room/!IwhlHPuHgkYixvZYmY:agent.dinum.tchap.gouv.fr?via=agent.dinum.tchap.gouv.fr) *
```

Tu peux explorer l’espace dédié à l’IA dans l’État. En bas de la page d’accueil, tu trouveras tous les sous-espaces disponibles.

``` {% endstep %} {% step %} **Se familiariser avec les principaux outils numériques utilisés par la communauté** (Grist, Docs, Visio...) * [ ] **Créer un compte** [**ProConnect**](https://www.proconnect.gouv.fr/) : c'est l'outil d'identification qui permet de se connecter facilement à tout l'univers de la suite numérique, qui propose des équivalents souverains aux outils d'organisation d'équipe propriétaires. Grâce à ton adresse mail, obtenue suite à la création de ton compte sur l'espace membre, tu devrais pouvoir te connecter facilement. {% hint style="info" %} [**La suite numérique**](https://lasuite.numerique.gouv.fr/)\ **Grist** est un gestionnaire de bases de données, équivalent à Airtable ; **Docs** est un gestionnaire de notes collaboratives ; **Visio** permet de faire des réunions vidéos. Le tout de manière souveraine et en toute sécurité !
{% endhint %} {% endstep %} {% step %} **Mieux comprendre l'écosystème d'ALLiaNCE :** * [ ] Consulter la documentation [beta.gouv.fr](https://beta.gouv.fr) pour tout ce qui concerne la philosophie de travail de l'incubateur ; * [ ] Consulter le reste de la documentation propre à [ALLiaNCE, ](https://guides.ia.numerique.gouv.fr/)avec des spécificités liées aux produits IA ; * [ ] Découvrir les produits du [portefeuille ](https://alliance.numerique.gouv.fr/les-produits-incub%C3%A9s/)ALLiaNCE et rencontrer les autres équipes ; * [ ] Consulter la [page](https://alliance.numerique.gouv.fr/albert/)/le site dédié à Albert API {% hint style="info" %} ALLiaNCE fait partie du réseau d'incubateurs **beta.gouv**, une communauté plurielle qui regroupe les incubateurs répartis dans tous les ministères et opérateurs de l'État. La méthode, les outils ainsi que les événements proposés par la communauté sont aussi les vôtres. {% endhint %} {% endstep %} {% endstepper %} {% hint style="info" %} ### La to-do pour 💻 Développeurs / développeuses * #### Rencontrer le CTO de l'incubateur Luis Arias, disponible sur Tchap * #### Te familiariser avec [Albert-api](/socle-interministerielle-dintelligence-artificielle-generative/albert-api-linfrastructure-ia-souveraine-de-letat) et l'[Assistant IA](/socle-interministerielle-dintelligence-artificielle-generative/lassistant-ia). {% endhint %} ## 🌟 Les premiers mois {% stepper %} {% step %} **Participer à une des rencontres ALLiaNCE organisées tous les deux mois** Et pourquoi pas y animer un atelier afin de présenter vos dernières avancées, proposer un co-dev pour qu'on vous aide à trouver des solutions, ou faire une démo sur votre produit ! {% endstep %} {% step %} **Rencontrer les équipes d'ALLiaNCE en venant travailler à la DINUM au 20 Avenue de Ségur, Paris 15ème, dans les locaux d'Étalab au 5ème étage.** {% endstep %} {% step %} **Participer aux événements et formations de la communauté beta** * [ ] **Les événements** par [là](https://espace-membre.incubateur.net/events). * [ ] **Les formations** par [ici](https://espace-membre.incubateur.net/formations). {% endstep %} {% endstepper %} # Qu'est-ce qu'Albert API ? Albert API permet aux applications et agents d’appeler des modèles de **génération de texte**, d’**embeddings**, de **classification** (rerank), de **reconnaissance vocale**, d’**OCR** et des services de **recherche** sur des corpus indexés, via des routes et des schémas calqués sur l’**API OpenAI** là où c’est pertinent. ## À qui s’adresse cette documentation Cette documentation vise les **développeurs et développeuses** qui intègrent l’API dans un produit ou un script : authentification, choix de modèles, appels HTTP et bonnes pratiques opérationnelles (quotas, erreurs, retries). ## URL et spécification * **URL de base :** `https://albert.api.etalab.gouv.fr` * **OpenAPI 3.1 :** [Référence OpenAPI interactive et schémas](https://doc.incubateur.net/alliance/albert-api/api-reference/liste-des-endpoint) ## Prochaines étapes 1. [Authentification](broken://pages/kAnuH9jbzC0DENsy17Pl) — en-tête Bearer et obtention d’un jeton. 2. [Démarrage rapide](/albert-api/prise-en-main/quickstart) — premier appel `POST /v1/chat/completions`. 3. [Guides](/albert-api/guides/chat-completions) — paramètres avancés, streaming, outils et RAG. ## Obtenir un accès Si vous êtes agent de la fonction publique d’État, l’accès à Albert API se fait automatiquement via ProConnect. Si vous rencontrez des problèmes de connexion, veuillez consulter notre [FAQ](https://guides.ia.numerique.gouv.fr/albert-api/ressources/faq#pourquoi-mon-compte-nest-pas-autorise) ## Tarifs & quotas (vision par modèle) La page “Tarifs et limites” liste, pour des familles de modèles, des quotas d’usage en mode **expérimentation** et **production** (RPM/RPD/TPM/TPD). [Tarifs et limites](https://ia.numerique.gouv.fr/outils-ia/albert-api/tarifs-et-limites/) {% hint style="warning" %} ⚠️ Les quotas indiqués sur le site sont une vue “tarifs” : pour connaître vos limites exactes (compte, routeurs, fenêtres), consultez l’objet `limits` dans **`GET /v1/me/info`** et la page [Quotas & limites](/albert-api/compte-and-usage/quotas). {% endhint %} ## Sécurité & hébergement souverain Albert API bénéficie d’un environnement cloud souverain (certification **SecNumCloud** via Outscale) et a des engagements de traitement des données : * Albert API ne conserve aucune trace des conversations envoyées aux modèles (voir [la page dédiée](/albert-api/ressources/absence-de-retention-des-donnees-metier-sur-le-chemin-dinference)) * Albert API n’envoie aucune de vos données sur Internet. [Sécurité & hébergement](https://ia.numerique.gouv.fr/outils-ia/albert-api/infrastructure-s%C3%A9curis%C3%A9e/) ## Compatibilité OpenAI Albert API est **compatible OpenAI** sur les endpoints courants : en conservant votre code basé sur le SDK ou sur des appels HTTP OpenAI, vous changez en principe uniquement la **base URL** (ici `https://albert.api.etalab.gouv.fr/v1`) et la **clé** (jeton Albert). Pour aller plus loin : [Chat completions](/albert-api/guides/chat-completions), [page de l’endpoint Chat](https://doc.incubateur.net/alliance/albert-api/api-reference/liste-des-endpoint/chat). ## Statut en production Pour suivre le statut opérationnel de l’API (quand publié), voir : [Statut en production](https://ia.numerique.gouv.fr/outils-ia/albert-api/statuts-de-lapi/) # Démarrage rapide Pour envoyer des requêtes à Albert API vous devez posséder créer une clef d'API depuis l'interface [Playground](https://albert.playground.etalab.gouv.fr/) d'Albert API. {% hint style="info" %} Une clef d'API est un identifiant de connexion (*Bearer token*) permettant de vous authentifier lors de vos appels API. Elle commence par `sk-eyJhbG...`. {% endhint %} {% stepper %} {% step %} ### Se connecter au playground Rendez vous sur [https://albert.playground.etalab.gouv.fr](https://albert.playground.etalab.gouv.fr/) et connectez vous avec Proconnect ([en savoir plus](https://www.proconnect.gouv.fr/)). Si vous êtes redirigez sur une page vous indiquant que votre accès est refusé, merci de consulter [la section de la FAQ dédiée](/albert-api/ressources/faq#pourquoi-mon-compte-nest-pas-autorise). {% endstep %} {% step %} ### Créer une clef d'API Une fois connectez à l'interface Playground, rendez-vous sur la page [*API Keys*](https://albert.playground.etalab.gouv.fr/keys). Sur cette page créer vous une clef en lui attribuant un nom. Vous pouvez configurer la durée d'expiration de votre clef jusqu'à un an. {% hint style="info" %} Après création, la clé est affichée **une seule fois**. Copiez-la immédiatement et conservez-la dans un gestionnaire de secrets (ou variable d’environnement), car **vous ne pourrez pas l'afficher** ensuite. Pour en savoir plus sur les clefs d'API, consultez la documentation dédiée [ici](/albert-api/compte-and-usage/api-keys). {% endhint %} {% endstep %} {% step %} ### Appeler un modèle Pour cette première requête nous allons appelez le modèle `openweight-small`. Ouvrez un terminal et exécutez le code ci-dessous. {% hint style="info" %} Remplacez la valeur `$ALBERT_API_KEY` par la valeur de votre clef API. {% endhint %} {% tabs %} {% tab title="Bash" icon="square-terminal" %} ```bash curl -x POST "https://albert.api.etalab.gouv.fr/v1/chat/completions" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "REMPLACER_PAR_ID_MODELE", "messages": [ {"role": "system", "content": "Tu réponds en français, de façon concise."}, {"role": "user", "content": "Explique ce qu’est une API compatible OpenAI en deux phrases."} ] }' ``` {% endtab %} {% tab title="Python" icon="python" %} ```python import os from openai import OpenAI client = OpenAI( base_url="https://albert.api.etalab.gouv.fr/v1", api_key=os.environ["ALBERT_API_KEY"], ) r = client.chat.completions.create( model="REMPLACER_PAR_ID_MODELE", messages=[ {"role": "system", "content": "Tu réponds en français, de façon concise."}, {"role": "user", "content": "Explique ce qu’est une API compatible OpenAI en deux phrases."}, ], ) print(r.choices[0].message.content) ``` {% endtab %} {% tab title="JavaScript" icon="js" %} ```javascript import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://albert.api.etalab.gouv.fr/v1", apiKey: process.env.ALBERT_API_KEY, }); const r = await client.chat.completions.create({ model: "REMPLACER_PAR_ID_MODELE", messages: [ { role: "system", content: "Tu réponds en français, de façon concise." }, { role: "user", content: "Explique ce qu’est une API compatible OpenAI en deux phrases." } ], }); console.log(r.choices[0].message.content); ``` {% endtab %} {% endtabs %} {% endstep %} {% step %} ### Explorer les fonctionnalités et les modèles disponibles * [Consulter les endpoints disponibles](/albert-api/api-reference/liste-des-endpoint) * [Consulter les modèles disponibles](/albert-api/modeles/available-models) * [Consulter nos guides thématiques](/albert-api/guides/chat-completions) {% endstep %} {% endstepper %} # Liste des Endpoint # Audio ## POST /v1/audio/transcriptions > Create Audio Transcription ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Audio"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"Body_create_audio_transcription_v1_audio_transcriptions_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"The audio file object (not file name) to transcribe, in one of these formats: mp3 or wav."},"model":{"type":"string","title":"Model","description":"ID of the model to use. Call `/v1/models` endpoint to get the list of available models, only `automatic-speech-recognition` model type is supported."},"language":{"anyOf":[{"$ref":"#/components/schemas/AudioTranscriptionLanguage"},{"type":"null"}],"description":"The language of the output audio. If the output language is different than the audio language, the audio language will be translated into the output language. Output language must be supplied in ISO-639-1 format (e.g. en, fr) format."},"prompt":{"type":"string","title":"Prompt","description":"An optional text to tell the model what to do with the input audio.","default":""},"response_format":{"$ref":"#/components/schemas/AudioTranscriptionsResponseFormat","description":"The format of the transcript output: `json` (default), `text`, `diarized_json` to return per-segment speaker labels, `srt` or `vtt` for subtitle formats.","default":"json"},"temperature":{"type":"number","maximum":1,"minimum":0,"title":"Temperature","description":"The sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit.","default":0}},"type":"object","required":["file","model"],"title":"Body_create_audio_transcription_v1_audio_transcriptions_post"},"AudioTranscriptionLanguage":{"type":"string","enum":["af","afrikaans","albanian","am","amharic","ar","arabic","armenian","as","assamese","az","azerbaijani","ba","bashkir","basque","be","belarusian","bengali","bg","bn","bo","bosnian","br","breton","bs","bulgarian","burmese","ca","cantonese","castilian","catalan","chinese","croatian","cs","cy","czech","da","danish","de","dutch","el","en","english","es","estonian","et","eu","fa","faroese","fi","finnish","flemish","fo","fr","french","galician","georgian","german","gl","greek","gu","gujarati","ha","haitian","haitian creole","hausa","haw","hawaiian","he","hebrew","hi","hindi","hr","ht","hu","hungarian","hy","icelandic","id","indonesian","is","it","italian","ja","japanese","javanese","jw","ka","kannada","kazakh","khmer","kk","km","kn","ko","korean","la","lao","latin","latvian","lb","letzeburgesch","lingala","lithuanian","ln","lo","lt","luxembourgish","lv","macedonian","malagasy","malay","malayalam","maltese","mandarin","maori","marathi","mg","mi","mk","ml","mn","moldavian","moldovan","mongolian","mr","ms","mt","my","myanmar","ne","nepali","nl","nn","no","norwegian","nynorsk","oc","occitan","pa","panjabi","pashto","persian","pl","polish","portuguese","ps","pt","punjabi","pushto","ro","romanian","ru","russian","sa","sanskrit","sd","serbian","shona","si","sindhi","sinhala","sinhalese","sk","sl","slovak","slovenian","sn","so","somali","spanish","sq","sr","su","sundanese","sv","sw","swahili","swedish","ta","tagalog","tajik","tamil","tatar","te","telugu","tg","th","thai","tibetan","tk","tl","tr","tt","turkish","turkmen","uk","ukrainian","ur","urdu","uz","uzbek","valencian","vi","vietnamese","welsh","yi","yiddish","yo","yoruba","yue","zh"],"title":"AudioTranscriptionLanguage"},"AudioTranscriptionsResponseFormat":{"type":"string","enum":["json","text","verbose_json","diarized_json","srt","vtt"],"title":"AudioTranscriptionsResponseFormat"},"AudioTranscriptionsResponse":{"properties":{"id":{"type":"string","title":"Id","description":"A unique identifier for the audio transcription."},"text":{"type":"string","title":"Text","description":"The transcription text."},"model":{"type":"string","title":"Model","description":"The model used to generate the transcription."},"segments":{"anyOf":[{"items":{"$ref":"#/components/schemas/Segment"},"type":"array"},{"type":"null"}],"title":"Segments","description":"Diarized segments, only set when `response_format=diarized_json`."},"usage":{"$ref":"#/components/schemas/api__domain__usage__entities__Usage","description":"Usage information for the request."}},"additionalProperties":true,"type":"object","required":["id","text","model"],"title":"AudioTranscriptionsResponse"},"Segment":{"properties":{"id":{"type":"integer","title":"Id","description":"A unique identifier for the segment."},"type":{"type":"string","title":"Type","description":"The type of the segment.","default":"transcript.text.segment"},"text":{"type":"string","title":"Text","description":"The segment text."},"start":{"type":"number","title":"Start","description":"Start time of the segment in seconds."},"end":{"type":"number","title":"End","description":"End time of the segment in seconds."},"speaker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Speaker","description":"Speaker label assigned by diarization, if available."}},"additionalProperties":true,"type":"object","required":["id","text","start","end"],"title":"Segment"},"api__domain__usage__entities__Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","default":0},"total_tokens":{"type":"integer","title":"Total Tokens","default":0},"cost":{"type":"number","title":"Cost","default":0},"impacts":{"$ref":"#/components/schemas/api__domain__usage__entities__EnvironmentalImpacts","default":{"kWh":0,"kgCO2eq":0}}},"additionalProperties":true,"type":"object","title":"Usage"},"api__domain__usage__entities__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"}}},"paths":{"/v1/audio/transcriptions":{"post":{"tags":["Audio"],"summary":"Create Audio Transcription","operationId":"create_audio_transcription_v1_audio_transcriptions_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_create_audio_transcription_v1_audio_transcriptions_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudioTranscriptionsResponse"}}}},"400":{"description":"Insufficient budget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"404":{"description":"Model {name} not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"413":{"description":"File size limit exceeded. Expected: {expected_size}. Actual: {size}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Model has wrong type. Expected: {expected_type}. Actual: {actual_type}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"429":{"description":"Token/request limit per minute/day exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"503":{"description":"Model is too busy, please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}}}}}}} ``` # Chat ## Chat Completions > Creates a model response for the given chat conversation. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Chat"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"CreateChatCompletion":{"properties":{"messages":{"items":{},"type":"array","title":"Messages","description":"A list of messages comprising the conversation so far."},"model":{"type":"string","title":"Model","description":"ID of the model to use. Call `/v1/models` endpoint to get the list of available models, only `text-generation` model type is supported."},"frequency_penalty":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Frequency Penalty","description":"Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.","default":0},"logit_bias":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Logit Bias","description":"Modify the likelihood of specified tokens appearing in the completion. Accepts a JSON object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token."},"logprobs":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Logprobs","description":"Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the `content` of `message`.","default":false},"top_logprobs":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top Logprobs","description":"An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. `logprobs` must be set to `true` if this parameter is used."},"presence_penalty":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Presence Penalty","description":"Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.","default":0},"max_completion_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Completion Tokens","description":"An upper bound for the number of tokens that can be generated for a completion."},"n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"N","description":"How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep `n` as `1` to minimize costs.","default":1},"response_format":{"anyOf":[{},{"type":"null"}],"title":"Response Format","description":"Setting to `{ \"type\": \"json_schema\", \"json_schema\": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the Structured Outputs guide. Setting to `{ \"type\": \"json_object\" }` enables JSON mode, which ensures the message the model generates is valid JSON.
**Important**: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly \"stuck\" request. Also note that the message content may be partially cut off if `finish_reason=\"length\"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length."},"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Seed","description":"If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result. Determinism is not guaranteed, and you should refer to the system_fingerprint response parameter to monitor changes in the backend."},"stop":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Stop","description":"Up to 4 sequences where the API will stop generating further tokens."},"stream":{"anyOf":[{"type":"boolean","enum":[true,false]},{"type":"null"}],"title":"Stream","description":"If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a data: [DONE] message.","default":false},"stream_options":{"anyOf":[{},{"type":"null"}],"title":"Stream Options","description":"Options for streaming response. Only set this when you set `stream: true`."},"temperature":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Temperature","description":"What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both."},"top_p":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Top P","description":"An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.
We generally recommend altering this or `temperature` but not both."},"tools":{"anyOf":[{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"description":"A list of tools the model may call. Currently, only functions are supported as a tool."},{"type":"null"}],"title":"Tools"},"tool_choice":{"title":"Tool Choice","description":"Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools. Specifying a particular tool via `{\"type\": \"function\", \"function\": {\"name\": \"my_function\"}}` forces the model to call that tool.
`none` is the default when no tools are present. `auto` is the default if tools are present.","default":"none"},"parallel_tool_calls":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Parallel Tool Calls","description":"Whether to call tools in parallel or sequentially. If true, the model will call tools in parallel. If false, the model will call tools sequentially. If None, the model will call tools in parallel if the model supports it, otherwise it will call tools sequentially.","default":false},"user":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User","description":"A unique identifier representing the user."}},"additionalProperties":true,"type":"object","required":["messages","model"],"title":"CreateChatCompletion"},"ChatCompletion":{"properties":{"id":{"type":"string","title":"Id","description":"A unique identifier for the chat completion."},"choices":{"items":{"$ref":"#/components/schemas/openai__types__chat__chat_completion__Choice"},"type":"array","title":"Choices"},"created":{"type":"integer","title":"Created"},"model":{"type":"string","title":"Model"},"object":{"type":"string","const":"chat.completion","title":"Object"},"service_tier":{"anyOf":[{"type":"string","enum":["auto","default","flex","scale","priority"]},{"type":"null"}],"title":"Service Tier"},"system_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Fingerprint"},"usage":{"$ref":"#/components/schemas/api__schemas__usage__Usage","description":"Usage information for the request."}},"additionalProperties":true,"type":"object","required":["choices","created","model","object"],"title":"ChatCompletion"},"openai__types__chat__chat_completion__Choice":{"properties":{"finish_reason":{"type":"string","enum":["stop","length","tool_calls","content_filter","function_call"],"title":"Finish Reason"},"index":{"type":"integer","title":"Index"},"logprobs":{"anyOf":[{"$ref":"#/components/schemas/ChoiceLogprobs"},{"type":"null"}]},"message":{"$ref":"#/components/schemas/ChatCompletionMessage"}},"additionalProperties":true,"type":"object","required":["finish_reason","index","message"],"title":"Choice"},"ChoiceLogprobs":{"properties":{"content":{"anyOf":[{"items":{"$ref":"#/components/schemas/ChatCompletionTokenLogprob"},"type":"array"},{"type":"null"}],"title":"Content"},"refusal":{"anyOf":[{"items":{"$ref":"#/components/schemas/ChatCompletionTokenLogprob"},"type":"array"},{"type":"null"}],"title":"Refusal"}},"additionalProperties":true,"type":"object","title":"ChoiceLogprobs","description":"Log probability information for the choice."},"ChatCompletionTokenLogprob":{"properties":{"token":{"type":"string","title":"Token"},"bytes":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Bytes"},"logprob":{"type":"number","title":"Logprob"},"top_logprobs":{"items":{"$ref":"#/components/schemas/TopLogprob"},"type":"array","title":"Top Logprobs"}},"additionalProperties":true,"type":"object","required":["token","logprob","top_logprobs"],"title":"ChatCompletionTokenLogprob"},"TopLogprob":{"properties":{"token":{"type":"string","title":"Token"},"bytes":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Bytes"},"logprob":{"type":"number","title":"Logprob"}},"additionalProperties":true,"type":"object","required":["token","logprob"],"title":"TopLogprob"},"ChatCompletionMessage":{"properties":{"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content"},"refusal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Refusal"},"role":{"type":"string","const":"assistant","title":"Role"},"annotations":{"anyOf":[{"items":{"$ref":"#/components/schemas/Annotation"},"type":"array"},{"type":"null"}],"title":"Annotations"},"audio":{"anyOf":[{"$ref":"#/components/schemas/ChatCompletionAudio"},{"type":"null"}]},"function_call":{"anyOf":[{"$ref":"#/components/schemas/FunctionCall"},{"type":"null"}]},"tool_calls":{"anyOf":[{"items":{"anyOf":[{"$ref":"#/components/schemas/ChatCompletionMessageFunctionToolCall"},{"$ref":"#/components/schemas/ChatCompletionMessageCustomToolCall"}]},"type":"array"},{"type":"null"}],"title":"Tool Calls"}},"additionalProperties":true,"type":"object","required":["role"],"title":"ChatCompletionMessage","description":"A chat completion message generated by the model."},"Annotation":{"properties":{"type":{"type":"string","const":"url_citation","title":"Type"},"url_citation":{"$ref":"#/components/schemas/AnnotationURLCitation"}},"additionalProperties":true,"type":"object","required":["type","url_citation"],"title":"Annotation","description":"A URL citation when using web search."},"AnnotationURLCitation":{"properties":{"end_index":{"type":"integer","title":"End Index"},"start_index":{"type":"integer","title":"Start Index"},"title":{"type":"string","title":"Title"},"url":{"type":"string","title":"Url"}},"additionalProperties":true,"type":"object","required":["end_index","start_index","title","url"],"title":"AnnotationURLCitation","description":"A URL citation when using web search."},"ChatCompletionAudio":{"properties":{"id":{"type":"string","title":"Id"},"data":{"type":"string","title":"Data"},"expires_at":{"type":"integer","title":"Expires At"},"transcript":{"type":"string","title":"Transcript"}},"additionalProperties":true,"type":"object","required":["id","data","expires_at","transcript"],"title":"ChatCompletionAudio","description":"If the audio output modality is requested, this object contains data\nabout the audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio)."},"FunctionCall":{"properties":{"arguments":{"type":"string","title":"Arguments"},"name":{"type":"string","title":"Name"}},"additionalProperties":true,"type":"object","required":["arguments","name"],"title":"FunctionCall","description":"Deprecated and replaced by `tool_calls`.\n\nThe name and arguments of a function that should be called, as generated by the model."},"ChatCompletionMessageFunctionToolCall":{"properties":{"id":{"type":"string","title":"Id"},"function":{"$ref":"#/components/schemas/Function"},"type":{"type":"string","const":"function","title":"Type"}},"additionalProperties":true,"type":"object","required":["id","function","type"],"title":"ChatCompletionMessageFunctionToolCall","description":"A call to a function tool created by the model."},"Function":{"properties":{"arguments":{"type":"string","title":"Arguments"},"name":{"type":"string","title":"Name"}},"additionalProperties":true,"type":"object","required":["arguments","name"],"title":"Function","description":"The function that the model called."},"ChatCompletionMessageCustomToolCall":{"properties":{"id":{"type":"string","title":"Id"},"custom":{"$ref":"#/components/schemas/Custom"},"type":{"type":"string","const":"custom","title":"Type"}},"additionalProperties":true,"type":"object","required":["id","custom","type"],"title":"ChatCompletionMessageCustomToolCall","description":"A call to a custom tool created by the model."},"Custom":{"properties":{"input":{"type":"string","title":"Input"},"name":{"type":"string","title":"Name"}},"additionalProperties":true,"type":"object","required":["input","name"],"title":"Custom","description":"The custom tool that the model called."},"api__schemas__usage__Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","description":"Number of prompt tokens (e.g. input tokens).","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","description":"Number of completion tokens (e.g. output tokens).","default":0},"total_tokens":{"type":"integer","title":"Total Tokens","description":"Total number of tokens (e.g. input and output tokens).","default":0},"cost":{"type":"number","title":"Cost","description":"Total cost of the request.","default":0},"carbon":{"$ref":"#/components/schemas/CarbonFootprintUsage","deprecated":true},"impacts":{"$ref":"#/components/schemas/api__schemas__usage__EnvironmentalImpacts"},"requests":{"type":"integer","title":"Requests","description":"Number of model requests.","default":0}},"additionalProperties":true,"type":"object","title":"Usage"},"CarbonFootprintUsage":{"properties":{"kWh":{"$ref":"#/components/schemas/CarbonFootprintUsageKWh","deprecated":true},"kgCO2eq":{"$ref":"#/components/schemas/CarbonFootprintUsageKgCO2eq","deprecated":true}},"additionalProperties":true,"type":"object","title":"CarbonFootprintUsage"},"CarbonFootprintUsageKWh":{"properties":{"min":{"type":"number","title":"Min","description":"Minimum carbon footprint in kWh.","default":0,"deprecated":true},"max":{"type":"number","title":"Max","description":"Maximum carbon footprint in kWh.","default":0,"deprecated":true}},"additionalProperties":true,"type":"object","title":"CarbonFootprintUsageKWh"},"CarbonFootprintUsageKgCO2eq":{"properties":{"min":{"type":"number","title":"Min","description":"Minimum carbon footprint in kgCO2eq (global warming potential).","default":0,"deprecated":true},"max":{"type":"number","title":"Max","description":"Maximum carbon footprint in kgCO2eq (global warming potential).","default":0,"deprecated":true}},"additionalProperties":true,"type":"object","title":"CarbonFootprintUsageKgCO2eq"},"api__schemas__usage__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","description":"Carbon footprint in kWh.","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","description":"Carbon footprint in kgCO2eq (global warming potential).","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"},"ChatCompletionChunk":{"properties":{"id":{"type":"string","title":"Id"},"choices":{"items":{"$ref":"#/components/schemas/openai__types__chat__chat_completion_chunk__Choice"},"type":"array","title":"Choices"},"created":{"type":"integer","title":"Created"},"model":{"type":"string","title":"Model"},"object":{"type":"string","const":"chat.completion.chunk","title":"Object"},"service_tier":{"anyOf":[{"type":"string","enum":["auto","default","flex","scale","priority"]},{"type":"null"}],"title":"Service Tier"},"system_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Fingerprint"},"usage":{"anyOf":[{"$ref":"#/components/schemas/CompletionUsage"},{"type":"null"}]}},"additionalProperties":true,"type":"object","required":["id","choices","created","model","object"],"title":"ChatCompletionChunk"},"openai__types__chat__chat_completion_chunk__Choice":{"properties":{"delta":{"$ref":"#/components/schemas/ChoiceDelta"},"finish_reason":{"anyOf":[{"type":"string","enum":["stop","length","tool_calls","content_filter","function_call"]},{"type":"null"}],"title":"Finish Reason"},"index":{"type":"integer","title":"Index"},"logprobs":{"anyOf":[{"$ref":"#/components/schemas/ChoiceLogprobs"},{"type":"null"}]}},"additionalProperties":true,"type":"object","required":["delta","index"],"title":"Choice"},"ChoiceDelta":{"properties":{"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content"},"function_call":{"anyOf":[{"$ref":"#/components/schemas/ChoiceDeltaFunctionCall"},{"type":"null"}]},"refusal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Refusal"},"role":{"anyOf":[{"type":"string","enum":["developer","system","user","assistant","tool"]},{"type":"null"}],"title":"Role"},"tool_calls":{"anyOf":[{"items":{"$ref":"#/components/schemas/ChoiceDeltaToolCall"},"type":"array"},{"type":"null"}],"title":"Tool Calls"}},"additionalProperties":true,"type":"object","title":"ChoiceDelta","description":"A chat completion delta generated by streamed model responses."},"ChoiceDeltaFunctionCall":{"properties":{"arguments":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arguments"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"}},"additionalProperties":true,"type":"object","title":"ChoiceDeltaFunctionCall","description":"Deprecated and replaced by `tool_calls`.\n\nThe name and arguments of a function that should be called, as generated by the model."},"ChoiceDeltaToolCall":{"properties":{"index":{"type":"integer","title":"Index"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"function":{"anyOf":[{"$ref":"#/components/schemas/ChoiceDeltaToolCallFunction"},{"type":"null"}]},"type":{"anyOf":[{"type":"string","const":"function"},{"type":"null"}],"title":"Type"}},"additionalProperties":true,"type":"object","required":["index"],"title":"ChoiceDeltaToolCall"},"ChoiceDeltaToolCallFunction":{"properties":{"arguments":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arguments"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"}},"additionalProperties":true,"type":"object","title":"ChoiceDeltaToolCallFunction"},"CompletionUsage":{"properties":{"completion_tokens":{"type":"integer","title":"Completion Tokens"},"prompt_tokens":{"type":"integer","title":"Prompt Tokens"},"total_tokens":{"type":"integer","title":"Total Tokens"},"completion_tokens_details":{"anyOf":[{"$ref":"#/components/schemas/CompletionTokensDetails"},{"type":"null"}]},"prompt_tokens_details":{"anyOf":[{"$ref":"#/components/schemas/PromptTokensDetails"},{"type":"null"}]}},"additionalProperties":true,"type":"object","required":["completion_tokens","prompt_tokens","total_tokens"],"title":"CompletionUsage","description":"Usage statistics for the completion request."},"CompletionTokensDetails":{"properties":{"accepted_prediction_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Accepted Prediction Tokens"},"audio_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Audio Tokens"},"reasoning_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reasoning Tokens"},"rejected_prediction_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rejected Prediction Tokens"}},"additionalProperties":true,"type":"object","title":"CompletionTokensDetails","description":"Breakdown of tokens used in a completion."},"PromptTokensDetails":{"properties":{"audio_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Audio Tokens"},"cached_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cached Tokens"}},"additionalProperties":true,"type":"object","title":"PromptTokensDetails","description":"Breakdown of tokens used in the prompt."},"api__schemas__exception__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","maximum":599,"minimum":100,"title":"Status Code","description":"HTTP status code to send to the client."},"detail":{"title":"Detail","description":"Any data to be sent to the client in the `detail` key of the JSON response."},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers","description":"Any headers to send to the client in the response."}},"type":"object","required":["status_code","detail","headers"],"title":"HTTPExceptionModel"}}},"paths":{"/v1/chat/completions":{"post":{"tags":["Chat"],"summary":"Chat Completions","description":"Creates a model response for the given chat conversation.","operationId":"chat_completions_v1_chat_completions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChatCompletion"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ChatCompletion"},{"$ref":"#/components/schemas/ChatCompletionChunk"}],"title":"Response Chat Completions V1 Chat Completions Post"}}}},"404":{"description":"Model not found. Collection not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__schemas__exception__HTTPExceptionModel"}}}},"422":{"description":"Wrong model type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__schemas__exception__HTTPExceptionModel"}}}},"503":{"description":"Model is too busy, please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__schemas__exception__HTTPExceptionModel"}}}}}}}}} ``` # Collections ## Get Collections > Get list of collections. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Collections"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"CollectionVisibility":{"type":"string","enum":["private","public"],"title":"CollectionVisibility"},"Collections":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Collection"},"type":"array","title":"Data"}},"additionalProperties":true,"type":"object","required":["data"],"title":"Collections"},"Collection":{"properties":{"object":{"type":"string","const":"collection","title":"Object","default":"collection"},"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"owner":{"type":"integer","title":"Owner"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"visibility":{"anyOf":[{"$ref":"#/components/schemas/CollectionVisibility"},{"type":"null"}]},"created":{"type":"integer","title":"Created"},"updated":{"type":"integer","title":"Updated"},"documents":{"type":"integer","title":"Documents","default":0},"size":{"type":"integer","title":"Size","default":0}},"additionalProperties":true,"type":"object","required":["id","name","owner","created","updated"],"title":"Collection"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/collections":{"get":{"tags":["Collections"],"summary":"Get Collections","description":"Get list of collections.","operationId":"get_collections_v1_collections_get","parameters":[{"name":"name","in":"query","required":false,"schema":{"type":"string","description":"Filter by collection name.","title":"Name"},"description":"Filter by collection name."},{"name":"visibility","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/CollectionVisibility"},{"type":"null"}],"description":"Filter by collection visibility.","title":"Visibility"},"description":"Filter by collection visibility."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"The offset of the collections to get.","default":0,"title":"Offset"},"description":"The offset of the collections to get."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"The limit of the collections to get.","default":10,"title":"Limit"},"description":"The limit of the collections to get."},{"name":"order_by","in":"query","required":false,"schema":{"enum":["id","name","created","updated"],"type":"string","description":"The order by field to sort the collections by.","default":"id","title":"Order By"},"description":"The order by field to sort the collections by."},{"name":"order_direction","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","description":"The direction to order the collections by.","default":"asc","title":"Order Direction"},"description":"The direction to order the collections by."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collections"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Create Collection > Create a new collection. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Collections"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"CollectionRequest":{"properties":{"name":{"type":"string","minLength":1,"title":"Name","description":"The name of the collection."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"The description of the collection."},"visibility":{"$ref":"#/components/schemas/CollectionVisibility","description":"The type of the collection. Public collections are available to all users, private collections are only available to the user who created them.","default":"private"}},"additionalProperties":true,"type":"object","required":["name"],"title":"CollectionRequest"},"CollectionVisibility":{"type":"string","enum":["private","public"],"title":"CollectionVisibility"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/collections":{"post":{"tags":["Collections"],"summary":"Create Collection","description":"Create a new collection.","operationId":"create_collection_v1_collections_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Collection > Get a collection by ID. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Collections"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"Collection":{"properties":{"object":{"type":"string","const":"collection","title":"Object","default":"collection"},"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"owner":{"type":"integer","title":"Owner"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"visibility":{"anyOf":[{"$ref":"#/components/schemas/CollectionVisibility"},{"type":"null"}]},"created":{"type":"integer","title":"Created"},"updated":{"type":"integer","title":"Updated"},"documents":{"type":"integer","title":"Documents","default":0},"size":{"type":"integer","title":"Size","default":0}},"additionalProperties":true,"type":"object","required":["id","name","owner","created","updated"],"title":"Collection"},"CollectionVisibility":{"type":"string","enum":["private","public"],"title":"CollectionVisibility"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/collections/{collection_id}":{"get":{"tags":["Collections"],"summary":"Get Collection","description":"Get a collection by ID.","operationId":"get_collection_v1_collections__collection_id__get","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"integer","description":"The collection ID","title":"Collection Id"},"description":"The collection ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Delete Collection > Delete a collection. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Collections"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/collections/{collection_id}":{"delete":{"tags":["Collections"],"summary":"Delete Collection","description":"Delete a collection.","operationId":"delete_collection_v1_collections__collection_id__delete","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"integer","description":"The collection ID","title":"Collection Id"},"description":"The collection ID"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Update Collection > Update a collection. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Collections"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"CollectionUpdateRequest":{"properties":{"name":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Name","description":"The name of the collection."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"The description of the collection."},"visibility":{"anyOf":[{"$ref":"#/components/schemas/CollectionVisibility"},{"type":"null"}],"description":"The type of the collection. Public collections are available to all users, private collections are only available to the user who created them."}},"additionalProperties":true,"type":"object","title":"CollectionUpdateRequest"},"CollectionVisibility":{"type":"string","enum":["private","public"],"title":"CollectionVisibility"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/collections/{collection_id}":{"patch":{"tags":["Collections"],"summary":"Update Collection","description":"Update a collection.","operationId":"update_collection_v1_collections__collection_id__patch","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"integer","description":"The collection ID","title":"Collection Id"},"description":"The collection ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionUpdateRequest","description":"The collection to update."}}}},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` # Documents ## Get Documents > Get all documents ID from a collection. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Documents"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/documents":{"get":{"tags":["Documents"],"summary":"Get Documents","description":"Get all documents ID from a collection.","operationId":"get_documents_v1_documents_get","parameters":[{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter documents by name","title":"Name"},"description":"Filter documents by name"},{"name":"collection_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}],"description":"Filter documents by collection ID","title":"Collection Id"},"description":"Filter documents by collection ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"The number of documents to return","default":10,"title":"Limit"},"description":"The number of documents to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","description":"The offset of the first document to return","default":0,"title":"Offset"},"description":"The offset of the first document to return"},{"name":"order_by","in":"query","required":false,"schema":{"enum":["id","name","created"],"type":"string","description":"The order by field to sort the documents by.","default":"id","title":"Order By"},"description":"The order by field to sort the documents by."},{"name":"order_direction","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","description":"The direction to order the documents by.","default":"asc","title":"Order Direction"},"description":"The direction to order the documents by."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Create Document > Upload a file, parse and split it into chunks, then create a document. If no file is provided, the document will be created without content, use POST \`/v1/documents/{document\_id}/chunks\` to fill it. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Documents"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"Body_create_document_v1_documents_post":{"properties":{"file":{"anyOf":[{"type":"string","contentMediaType":"application/octet-stream"},{"type":"null"}],"title":"File","description":"The file to create a document from. If not provided, the document will be created without content, use POST `/v1/documents/{document_id}/chunks` to fill it."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Name of document if no file is provided or to override file name."},"collection_id":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}],"title":"Collection Id","description":"The collection ID to use for the file upload. The file will be vectorized with model defined by the collection."},"disable_chunking":{"type":"boolean","title":"Disable Chunking","description":"Whether to disable `RecursiveCharacterTextSplitter` chunking for the upload file.","default":false},"chunk_size":{"type":"integer","minimum":0,"title":"Chunk Size","description":"The size in characters of the chunks to use for the upload file. If not provided, the document will not be split into chunks.","default":2048},"chunk_min_size":{"type":"integer","minimum":0,"title":"Chunk Min Size","description":"The minimum size in characters of the chunks to use for the upload file.","default":0},"chunk_overlap":{"type":"integer","minimum":0,"title":"Chunk Overlap","description":"The overlap in characters of the chunks to use for the upload file.","default":0},"is_separator_regex":{"type":"boolean","title":"Is Separator Regex","description":"Whether the separator is a regex to use for the upload file.","default":false},"separators":{"items":{"type":"string"},"type":"array","minItems":0,"title":"Separators","description":"Delimiters used by RecursiveCharacterTextSplitter for further splitting. If provided, `preset_separators` is ignored.","default":[]},"preset_separators":{"$ref":"#/components/schemas/PresetSeparators","description":"Preset separators used by RecursiveCharacterTextSplitter for further splitting. See [implemented details](https://github.com/langchain-ai/langchain/blob/eb122945832eae9b9df7c70ccd8d51fcd7a1899b/libs/text-splitters/langchain_text_splitters/character.py#L164).","default":"markdown"},"metadata":{"type":"string","title":"Metadata","description":"Optional additional metadata to add to each chunk if a file is provided. Provide a stringified JSON object matching the Metadata schema.","default":""}},"type":"object","title":"Body_create_document_v1_documents_post"},"PresetSeparators":{"type":"string","enum":["cpp","go","java","kotlin","js","ts","php","proto","python","r","rst","ruby","rust","scala","swift","markdown","latex","html","sol","csharp","cobol","c","lua","perl","haskell","elixir","powershell","visualbasic6"],"title":"PresetSeparators"},"DocumentResponse":{"properties":{"id":{"type":"integer","minimum":0,"title":"Id","description":"The ID of the document created."}},"additionalProperties":true,"type":"object","required":["id"],"title":"DocumentResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/documents":{"post":{"tags":["Documents"],"summary":"Create Document","description":"Upload a file, parse and split it into chunks, then create a document. If no file is provided, the document will be created without content, use POST `/v1/documents/{document_id}/chunks` to fill it.","operationId":"create_document_v1_documents_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_create_document_v1_documents_post"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Document > Get a document by ID. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Documents"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"Document":{"properties":{"object":{"type":"string","const":"document","title":"Object","description":"The type of the object.","default":"document"},"id":{"type":"integer","exclusiveMinimum":0,"title":"Id","description":"The ID of the document."},"name":{"type":"string","minLength":1,"title":"Name","description":"The name of the document."},"collection_id":{"type":"integer","exclusiveMinimum":0,"title":"Collection Id","description":"The ID of the collection the document belongs to."},"created":{"type":"integer","title":"Created","description":"The date of the document creation."},"chunks":{"type":"integer","minimum":0,"title":"Chunks","description":"The number of chunks the document has.","default":0},"size":{"type":"integer","minimum":0,"title":"Size","description":"The size of the document in tokens.","default":0}},"additionalProperties":true,"type":"object","required":["id","name","collection_id","created"],"title":"Document"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/documents/{document_id}":{"get":{"tags":["Documents"],"summary":"Get Document","description":"Get a document by ID.","operationId":"get_document_v1_documents__document_id__get","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"integer","minimum":0,"description":"The document ID","title":"Document Id"},"description":"The document ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Delete Document > Delete a document. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Documents"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/documents/{document_id}":{"delete":{"tags":["Documents"],"summary":"Delete Document","description":"Delete a document.","operationId":"delete_document_v1_documents__document_id__delete","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"description":"The document ID","title":"Document Id"},"description":"The document ID"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Document Chunks > Get chunks of a document. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Documents"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/documents/{document_id}/chunks":{"get":{"tags":["Documents"],"summary":"Get Document Chunks","description":"Get chunks of a document.","operationId":"get_document_chunks_v1_documents__document_id__chunks_get","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"description":"The document ID","title":"Document Id"},"description":"The document ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"The number of chunks to return","default":10,"title":"Limit"},"description":"The number of chunks to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","description":"The offset of the first chunk to return","default":0,"title":"Offset"},"description":"The offset of the first chunk to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Create Document Chunks > Fill document with chunks. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Documents"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"CreateChunks":{"properties":{"chunks":{"items":{"$ref":"#/components/schemas/InputChunk"},"type":"array","maxItems":64,"minItems":1,"title":"Chunks","description":"The list of chunks to create."}},"additionalProperties":true,"type":"object","required":["chunks"],"title":"CreateChunks"},"InputChunk":{"properties":{"content":{"type":"string","title":"Content","description":"The content of the chunk."},"metadata":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"integer","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"number","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"boolean"}]},"propertyNames":{"maxLength":255,"minLength":1},"type":"object","maxProperties":10,"minProperties":1,"description":"Extra metadata for the source"},{"type":"null"}],"title":"Metadata","description":"Metadata of the chunk"}},"additionalProperties":true,"type":"object","required":["content"],"title":"InputChunk"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/documents/{document_id}/chunks":{"post":{"tags":["Documents"],"summary":"Create Document Chunks","description":"Fill document with chunks.","operationId":"create_document_chunks_v1_documents__document_id__chunks_post","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"description":"The document ID","title":"Document Id"},"description":"The document ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChunks"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Document Chunk > Get a chunk of a document. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Documents"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/documents/{document_id}/chunks/{chunk_id}":{"get":{"tags":["Documents"],"summary":"Get Document Chunk","description":"Get a chunk of a document.","operationId":"get_document_chunk_v1_documents__document_id__chunks__chunk_id__get","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"description":"The document ID","title":"Document Id"},"description":"The document ID"},{"name":"chunk_id","in":"path","required":true,"schema":{"type":"integer","minimum":0,"description":"The chunk ID","title":"Chunk Id"},"description":"The chunk ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Delete Document Chunk > Delete a chunk of a document. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Documents"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/documents/{document_id}/chunks/{chunk_id}":{"delete":{"tags":["Documents"],"summary":"Delete Document Chunk","description":"Delete a chunk of a document.","operationId":"delete_document_chunk_v1_documents__document_id__chunks__chunk_id__delete","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"description":"The document ID","title":"Document Id"},"description":"The document ID"},{"name":"chunk_id","in":"path","required":true,"schema":{"type":"integer","minimum":0,"description":"The chunk ID","title":"Chunk Id"},"description":"The chunk ID"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` # Embeddings ## POST /v1/embeddings > Create Embeddings ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Embeddings"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"CreateEmbeddingsBody":{"properties":{"model":{"type":"string","minLength":1,"title":"Model","description":"ID of the model to use. Call `/v1/models` endpoint to get the list of available models, only `text-embeddings-inference` model type is supported."},"input":{"anyOf":[{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"items":{"items":{"type":"integer"},"type":"array","minItems":1},"type":"array"},{"type":"string"},{"items":{"type":"string"},"type":"array"}],"minLength":1},{"type":"null"}],"title":"Input","description":"Input text to embed, encoded as a string or array of tokens. To embed multiple inputs in a single request, pass an array of strings or array of token arrays. The input must not exceed the max input tokens for the model (call `/v1/models` endpoint to get the `max_context_length` by model) and cannot be an empty string."},"dimensions":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}],"title":"Dimensions","description":"The number of dimensions the resulting output embeddings should have."},"encoding_format":{"$ref":"#/components/schemas/EncodingFormat","description":"The format of the output embeddings.","default":"float"}},"additionalProperties":true,"type":"object","required":["model"],"title":"CreateEmbeddingsBody"},"EncodingFormat":{"type":"string","enum":["float","base64"],"title":"EncodingFormat"},"EmbeddingsResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Embedding"},"type":"array","title":"Data"},"model":{"type":"string","title":"Model"},"object":{"type":"string","const":"list","title":"Object","description":"The type of object returned.","default":"list"},"usage":{"$ref":"#/components/schemas/api__domain__usage__entities__Usage","description":"Usage information for the request."},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"A unique identifier for the request."}},"additionalProperties":true,"type":"object","required":["data","model"],"title":"EmbeddingsResponse"},"Embedding":{"properties":{"embedding":{"items":{"type":"number"},"type":"array","title":"Embedding"},"index":{"type":"integer","title":"Index"},"object":{"type":"string","const":"embedding","title":"Object"}},"additionalProperties":true,"type":"object","required":["embedding","index","object"],"title":"Embedding","description":"Represents an embedding vector returned by embedding endpoint."},"api__domain__usage__entities__Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","default":0},"total_tokens":{"type":"integer","title":"Total Tokens","default":0},"cost":{"type":"number","title":"Cost","default":0},"impacts":{"$ref":"#/components/schemas/api__domain__usage__entities__EnvironmentalImpacts","default":{"kWh":0,"kgCO2eq":0}}},"additionalProperties":true,"type":"object","title":"Usage"},"api__domain__usage__entities__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"}}},"paths":{"/v1/embeddings":{"post":{"tags":["Embeddings"],"summary":"Create Embeddings","operationId":"create_embeddings_v1_embeddings_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEmbeddingsBody","description":"The embeddings creation request."}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingsResponse"}}}},"400":{"description":"Insufficient budget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"404":{"description":"Model {name} not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Model has wrong type. Expected: {expected_type}. Actual: {actual_type}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"429":{"description":"Token/request limit per minute/day exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"503":{"description":"Model is too busy, please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}}}}}}} ``` # Health ## Get Health > Get the health of the API. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Health"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"paths":{"/health":{"get":{"tags":["Health"],"summary":"Get Health","description":"Get the health of the API.","operationId":"get_health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}}} ``` ## Get Health Models > Get the health of the models. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Health"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"}}},"paths":{"/health/models":{"get":{"tags":["Health"],"summary":"Get Health Models","description":"Get the health of the models.","operationId":"get_health_models_health_models_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}}}}}}} ``` # Keys ## Get Keys > Get all your keys. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Keys"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"SortField":{"type":"string","enum":["id","name","created"],"title":"SortField"},"SortOrder":{"type":"string","enum":["asc","desc"],"title":"SortOrder"},"KeysResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Type of the object.","default":"list"},"total":{"type":"integer","title":"Total","description":"Total number of keys."},"offset":{"type":"integer","title":"Offset","description":"Offset of the keys list."},"limit":{"type":"integer","title":"Limit","description":"Limit of the keys list."},"data":{"items":{"$ref":"#/components/schemas/KeyResponse"},"type":"array","title":"Data","description":"List of keys."}},"additionalProperties":true,"type":"object","required":["total","offset","limit","data"],"title":"KeysResponse"},"KeyResponse":{"properties":{"object":{"type":"string","const":"key","title":"Object","description":"Type of the object.","default":"key"},"id":{"type":"integer","title":"Id","description":"ID of the key."},"name":{"type":"string","title":"Name","description":"Name of the key."},"value":{"type":"string","title":"Value","description":"Value of the key."},"user":{"type":"integer","title":"User","description":"ID of the user that owns the key."},"expires":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires","description":"Time of expiration, as Unix timestamp. If None, the key never expires."},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."}},"additionalProperties":true,"type":"object","required":["id","name","value","user","created"],"title":"KeyResponse"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/keys":{"get":{"tags":["Keys"],"summary":"Get Keys","description":"Get all your keys.","operationId":"get_keys_v1_keys_get","parameters":[{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of keys to skip.","default":0,"title":"Offset"},"description":"Number of keys to skip."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of keys to return.","default":10,"title":"Limit"},"description":"Maximum number of keys to return."},{"name":"sort_by","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SortField","description":"Field to sort by.","default":"id"},"description":"Field to sort by."},{"name":"sort_order","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SortOrder","description":"Sort order.","default":"asc"},"description":"Sort order."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeysResponse"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Create Key > Create a new API key for the authenticated user. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Keys"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"CreateKeyBody":{"properties":{"name":{"type":"string","minLength":1,"title":"Name","description":"Name of the key."},"expires":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires","description":"Expiration time, as Unix timestamp. If None, uses the configured maximum key lifetime when set, otherwise the key never expires."}},"additionalProperties":true,"type":"object","required":["name"],"title":"CreateKeyBody"},"KeyResponse":{"properties":{"object":{"type":"string","const":"key","title":"Object","description":"Type of the object.","default":"key"},"id":{"type":"integer","title":"Id","description":"ID of the key."},"name":{"type":"string","title":"Name","description":"Name of the key."},"value":{"type":"string","title":"Value","description":"Value of the key."},"user":{"type":"integer","title":"User","description":"ID of the user that owns the key."},"expires":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires","description":"Time of expiration, as Unix timestamp. If None, the key never expires."},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."}},"additionalProperties":true,"type":"object","required":["id","name","value","user","created"],"title":"KeyResponse"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/keys":{"post":{"tags":["Keys"],"summary":"Create Key","description":"Create a new API key for the authenticated user.","operationId":"create_key_v1_keys_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKeyBody","description":"The key creation request."}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyResponse"}}}},"400":{"description":"Key expiration timestamp cannot be greater than {max_expiration_days} days from now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"404":{"description":"User {user_id}|{email} not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"409":{"description":"Key {name} already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Keys > Get all your keys. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Keys"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"SortField":{"type":"string","enum":["id","name","created"],"title":"SortField"},"SortOrder":{"type":"string","enum":["asc","desc"],"title":"SortOrder"},"KeysResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Type of the object.","default":"list"},"total":{"type":"integer","title":"Total","description":"Total number of keys."},"offset":{"type":"integer","title":"Offset","description":"Offset of the keys list."},"limit":{"type":"integer","title":"Limit","description":"Limit of the keys list."},"data":{"items":{"$ref":"#/components/schemas/KeyResponse"},"type":"array","title":"Data","description":"List of keys."}},"additionalProperties":true,"type":"object","required":["total","offset","limit","data"],"title":"KeysResponse"},"KeyResponse":{"properties":{"object":{"type":"string","const":"key","title":"Object","description":"Type of the object.","default":"key"},"id":{"type":"integer","title":"Id","description":"ID of the key."},"name":{"type":"string","title":"Name","description":"Name of the key."},"value":{"type":"string","title":"Value","description":"Value of the key."},"user":{"type":"integer","title":"User","description":"ID of the user that owns the key."},"expires":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires","description":"Time of expiration, as Unix timestamp. If None, the key never expires."},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."}},"additionalProperties":true,"type":"object","required":["id","name","value","user","created"],"title":"KeyResponse"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/me/keys":{"get":{"tags":["Keys"],"summary":"Get Keys","description":"Get all your keys.","operationId":"get_keys_v1_me_keys_get","deprecated":true,"parameters":[{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of keys to skip.","default":0,"title":"Offset"},"description":"Number of keys to skip."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of keys to return.","default":10,"title":"Limit"},"description":"Maximum number of keys to return."},{"name":"sort_by","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SortField","description":"Field to sort by.","default":"id"},"description":"Field to sort by."},{"name":"sort_order","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SortOrder","description":"Sort order.","default":"asc"},"description":"Sort order."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeysResponse"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Create Key > Create a new API key for the authenticated user. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Keys"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"CreateKeyBody":{"properties":{"name":{"type":"string","minLength":1,"title":"Name","description":"Name of the key."},"expires":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires","description":"Expiration time, as Unix timestamp. If None, uses the configured maximum key lifetime when set, otherwise the key never expires."}},"additionalProperties":true,"type":"object","required":["name"],"title":"CreateKeyBody"},"KeyResponse":{"properties":{"object":{"type":"string","const":"key","title":"Object","description":"Type of the object.","default":"key"},"id":{"type":"integer","title":"Id","description":"ID of the key."},"name":{"type":"string","title":"Name","description":"Name of the key."},"value":{"type":"string","title":"Value","description":"Value of the key."},"user":{"type":"integer","title":"User","description":"ID of the user that owns the key."},"expires":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires","description":"Time of expiration, as Unix timestamp. If None, the key never expires."},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."}},"additionalProperties":true,"type":"object","required":["id","name","value","user","created"],"title":"KeyResponse"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/me/keys":{"post":{"tags":["Keys"],"summary":"Create Key","description":"Create a new API key for the authenticated user.","operationId":"create_key_v1_me_keys_post","deprecated":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKeyBody","description":"The key creation request."}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyResponse"}}}},"400":{"description":"Key expiration timestamp cannot be greater than {max_expiration_days} days from now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"404":{"description":"User {user_id}|{email} not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"409":{"description":"Key {name} already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Key > Get one of your API keys by ID. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Keys"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"KeyResponse":{"properties":{"object":{"type":"string","const":"key","title":"Object","description":"Type of the object.","default":"key"},"id":{"type":"integer","title":"Id","description":"ID of the key."},"name":{"type":"string","title":"Name","description":"Name of the key."},"value":{"type":"string","title":"Value","description":"Value of the key."},"user":{"type":"integer","title":"User","description":"ID of the user that owns the key."},"expires":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires","description":"Time of expiration, as Unix timestamp. If None, the key never expires."},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."}},"additionalProperties":true,"type":"object","required":["id","name","value","user","created"],"title":"KeyResponse"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/keys/{key_id}":{"get":{"tags":["Keys"],"summary":"Get Key","description":"Get one of your API keys by ID.","operationId":"get_key_v1_keys__key_id__get","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"integer","description":"The ID of the key to get.","title":"Key Id"},"description":"The ID of the key to get."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyResponse"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"404":{"description":"Key {key_id} not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Delete Key > Delete an API key. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Keys"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"KeyResponse":{"properties":{"object":{"type":"string","const":"key","title":"Object","description":"Type of the object.","default":"key"},"id":{"type":"integer","title":"Id","description":"ID of the key."},"name":{"type":"string","title":"Name","description":"Name of the key."},"value":{"type":"string","title":"Value","description":"Value of the key."},"user":{"type":"integer","title":"User","description":"ID of the user that owns the key."},"expires":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires","description":"Time of expiration, as Unix timestamp. If None, the key never expires."},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."}},"additionalProperties":true,"type":"object","required":["id","name","value","user","created"],"title":"KeyResponse"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/keys/{key_id}":{"delete":{"tags":["Keys"],"summary":"Delete Key","description":"Delete an API key.","operationId":"delete_key_v1_keys__key_id__delete","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"integer","description":"The ID of the key to delete.","title":"Key Id"},"description":"The ID of the key to delete."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyResponse"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"404":{"description":"Key {key_id} not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Key > Get one of your API keys by ID. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Keys"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"KeyResponse":{"properties":{"object":{"type":"string","const":"key","title":"Object","description":"Type of the object.","default":"key"},"id":{"type":"integer","title":"Id","description":"ID of the key."},"name":{"type":"string","title":"Name","description":"Name of the key."},"value":{"type":"string","title":"Value","description":"Value of the key."},"user":{"type":"integer","title":"User","description":"ID of the user that owns the key."},"expires":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires","description":"Time of expiration, as Unix timestamp. If None, the key never expires."},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."}},"additionalProperties":true,"type":"object","required":["id","name","value","user","created"],"title":"KeyResponse"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/me/keys/{key_id}":{"get":{"tags":["Keys"],"summary":"Get Key","description":"Get one of your API keys by ID.","operationId":"get_key_v1_me_keys__key_id__get","deprecated":true,"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"integer","description":"The ID of the key to get.","title":"Key Id"},"description":"The ID of the key to get."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyResponse"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"404":{"description":"Key {key_id} not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Delete Key > Delete an API key. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Keys"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"KeyResponse":{"properties":{"object":{"type":"string","const":"key","title":"Object","description":"Type of the object.","default":"key"},"id":{"type":"integer","title":"Id","description":"ID of the key."},"name":{"type":"string","title":"Name","description":"Name of the key."},"value":{"type":"string","title":"Value","description":"Value of the key."},"user":{"type":"integer","title":"User","description":"ID of the user that owns the key."},"expires":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires","description":"Time of expiration, as Unix timestamp. If None, the key never expires."},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."}},"additionalProperties":true,"type":"object","required":["id","name","value","user","created"],"title":"KeyResponse"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/me/keys/{key_id}":{"delete":{"tags":["Keys"],"summary":"Delete Key","description":"Delete an API key.","operationId":"delete_key_v1_me_keys__key_id__delete","deprecated":true,"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"integer","description":"The ID of the key to delete.","title":"Key Id"},"description":"The ID of the key to delete."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyResponse"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"404":{"description":"Key {key_id} not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` # Me ## Get Me > Get my user information. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Me"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"MeResponse":{"properties":{"object":{"type":"string","const":"userInfo","title":"Object","description":"The user info object type.","default":"userInfo"},"id":{"type":"integer","title":"Id","description":"The user ID."},"email":{"type":"string","title":"Email","description":"The user email."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"The user name."},"organization_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Organization Id","description":"The user organization ID."},"budget":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Budget","description":"The user budget. If None, the user has unlimited budget."},"permissions":{"items":{"$ref":"#/components/schemas/PermissionType"},"type":"array","title":"Permissions","description":"The user permissions."},"limits":{"items":{"$ref":"#/components/schemas/Limit"},"type":"array","title":"Limits","description":"The user rate limits."},"expires":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires","description":"The user expiration timestamp. If None, the user will never expire."}},"additionalProperties":true,"type":"object","required":["id","email","permissions","limits"],"title":"MeResponse"},"PermissionType":{"type":"string","enum":["admin","read_metric","provide_models"],"title":"PermissionType"},"Limit":{"properties":{"router_id":{"type":"integer","title":"Router Id","description":"The router ID."},"type":{"$ref":"#/components/schemas/LimitType","description":"The limit type."},"value":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Value","description":"The limit value."}},"additionalProperties":true,"type":"object","required":["router_id","type"],"title":"Limit"},"LimitType":{"type":"string","enum":["tpm","tpd","rpm","rpd"],"title":"LimitType"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"}}},"paths":{"/v1/me":{"get":{"tags":["Me"],"summary":"Get Me","description":"Get my user information.","operationId":"get_me_v1_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}}}}}}} ``` ## Update Me > Update information about the current user. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Me"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"UpdateMeBody":{"properties":{"name":{"type":"string","minLength":1,"title":"Name","description":"The user name."},"email":{"type":"string","maxLength":254,"minLength":1,"title":"Email","description":"The user email."},"current_password":{"anyOf":[{"type":"string","maxLength":72,"minLength":6},{"type":"null"}],"title":"Current Password","description":"The current user password. If None, the password is not changed and `password` is ignored."},"password":{"anyOf":[{"type":"string","maxLength":72,"minLength":6},{"type":"null"}],"title":"Password","description":"The new user password. Required when `current_password` is provided. Ignored when `current_password` is None."}},"additionalProperties":true,"type":"object","required":["name","email"],"title":"UpdateMeBody"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/me":{"patch":{"tags":["Me"],"summary":"Update Me","description":"Update information about the current user.","operationId":"update_me_v1_me_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMeBody","description":"The user update request."}}},"required":true},"responses":{"204":{"description":"Successful Response"},"401":{"description":"Invalid current password.
Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"404":{"description":"User {user_id}|{email} not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"409":{"description":"User {email} already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Me > Get my user information. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Me"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"MeResponse":{"properties":{"object":{"type":"string","const":"userInfo","title":"Object","description":"The user info object type.","default":"userInfo"},"id":{"type":"integer","title":"Id","description":"The user ID."},"email":{"type":"string","title":"Email","description":"The user email."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"The user name."},"organization_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Organization Id","description":"The user organization ID."},"budget":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Budget","description":"The user budget. If None, the user has unlimited budget."},"permissions":{"items":{"$ref":"#/components/schemas/PermissionType"},"type":"array","title":"Permissions","description":"The user permissions."},"limits":{"items":{"$ref":"#/components/schemas/Limit"},"type":"array","title":"Limits","description":"The user rate limits."},"expires":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires","description":"The user expiration timestamp. If None, the user will never expire."}},"additionalProperties":true,"type":"object","required":["id","email","permissions","limits"],"title":"MeResponse"},"PermissionType":{"type":"string","enum":["admin","read_metric","provide_models"],"title":"PermissionType"},"Limit":{"properties":{"router_id":{"type":"integer","title":"Router Id","description":"The router ID."},"type":{"$ref":"#/components/schemas/LimitType","description":"The limit type."},"value":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Value","description":"The limit value."}},"additionalProperties":true,"type":"object","required":["router_id","type"],"title":"Limit"},"LimitType":{"type":"string","enum":["tpm","tpd","rpm","rpd"],"title":"LimitType"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"}}},"paths":{"/v1/me/info":{"get":{"tags":["Me"],"summary":"Get Me","description":"Get my user information.","operationId":"get_me_v1_me_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}}},"deprecated":true}}}} ``` ## Update Me > Update information about the current user. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Me"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"UpdateMeBody":{"properties":{"name":{"type":"string","minLength":1,"title":"Name","description":"The user name."},"email":{"type":"string","maxLength":254,"minLength":1,"title":"Email","description":"The user email."},"current_password":{"anyOf":[{"type":"string","maxLength":72,"minLength":6},{"type":"null"}],"title":"Current Password","description":"The current user password. If None, the password is not changed and `password` is ignored."},"password":{"anyOf":[{"type":"string","maxLength":72,"minLength":6},{"type":"null"}],"title":"Password","description":"The new user password. Required when `current_password` is provided. Ignored when `current_password` is None."}},"additionalProperties":true,"type":"object","required":["name","email"],"title":"UpdateMeBody"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/me/info":{"patch":{"tags":["Me"],"summary":"Update Me","description":"Update information about the current user.","operationId":"update_me_v1_me_info_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMeBody","description":"The user update request."}}},"required":true},"responses":{"204":{"description":"Successful Response"},"401":{"description":"Invalid current password.
Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"404":{"description":"User {user_id}|{email} not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"409":{"description":"User {email} already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"deprecated":true}}}} ``` # Models ## Get Models > Lists the currently available models and provides basic information. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Models"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"ModelsResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Type of the object.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Model"},"type":"array","title":"Data","description":"List of models."}},"additionalProperties":true,"type":"object","required":["data"],"title":"ModelsResponse"},"Model":{"properties":{"object":{"type":"string","const":"model","title":"Object","description":"Type of the object.","default":"model"},"id":{"type":"string","title":"Id","description":"The model identifier, which can be referenced in the API endpoints."},"type":{"anyOf":[{"$ref":"#/components/schemas/ModelType"},{"type":"null"}],"description":"The type of the model, which can be used to identify the model type."},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases","description":"Aliases of the model. It will be used to identify the model by users."},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."},"owned_by":{"type":"string","title":"Owned By","description":"The organization that owns the model."},"max_context_length":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Context Length","description":"Maximum amount of tokens a context could contains. Makes sure it is the same for all models."},"costs":{"$ref":"#/components/schemas/ModelCosts","description":"Costs of the model."}},"additionalProperties":true,"type":"object","required":["id","created","owned_by"],"title":"Model"},"ModelType":{"type":"string","enum":["automatic-speech-recognition","image-text-to-text","image-to-text","text-classification","text-embeddings-inference","text-generation"],"title":"ModelType"},"ModelCosts":{"properties":{"prompt_tokens":{"type":"number","minimum":0,"title":"Prompt Tokens","description":"Cost of a million prompt tokens (decrease user budget)","default":0},"completion_tokens":{"type":"number","minimum":0,"title":"Completion Tokens","description":"Cost of a million completion tokens (decrease user budget)","default":0}},"additionalProperties":true,"type":"object","title":"ModelCosts"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"}}},"paths":{"/v1/models":{"get":{"tags":["Models"],"summary":"Get Models","description":"Lists the currently available models and provides basic information.","operationId":"get_models_v1_models_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelsResponse"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}}}}}}} ``` ## Get Model > Get a model by name and provide basic information. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Models"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"Model":{"properties":{"object":{"type":"string","const":"model","title":"Object","description":"Type of the object.","default":"model"},"id":{"type":"string","title":"Id","description":"The model identifier, which can be referenced in the API endpoints."},"type":{"anyOf":[{"$ref":"#/components/schemas/ModelType"},{"type":"null"}],"description":"The type of the model, which can be used to identify the model type."},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases","description":"Aliases of the model. It will be used to identify the model by users."},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."},"owned_by":{"type":"string","title":"Owned By","description":"The organization that owns the model."},"max_context_length":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Context Length","description":"Maximum amount of tokens a context could contains. Makes sure it is the same for all models."},"costs":{"$ref":"#/components/schemas/ModelCosts","description":"Costs of the model."}},"additionalProperties":true,"type":"object","required":["id","created","owned_by"],"title":"Model"},"ModelType":{"type":"string","enum":["automatic-speech-recognition","image-text-to-text","image-to-text","text-classification","text-embeddings-inference","text-generation"],"title":"ModelType"},"ModelCosts":{"properties":{"prompt_tokens":{"type":"number","minimum":0,"title":"Prompt Tokens","description":"Cost of a million prompt tokens (decrease user budget)","default":0},"completion_tokens":{"type":"number","minimum":0,"title":"Completion Tokens","description":"Cost of a million completion tokens (decrease user budget)","default":0}},"additionalProperties":true,"type":"object","title":"ModelCosts"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/models/{model}":{"get":{"tags":["Models"],"summary":"Get Model","description":"Get a model by name and provide basic information.","operationId":"get_model_v1_models__model__get","parameters":[{"name":"model","in":"path","required":true,"schema":{"type":"string","description":"The name of the model to get.","title":"Model"},"description":"The name of the model to get."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Model"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"404":{"description":"Model {name} not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` # Monitoring ## GET /metrics > Get Metrics ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Monitoring"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}},"paths":{"/metrics":{"get":{"tags":["Monitoring"],"summary":"Get Metrics","operationId":"get_metrics_metrics_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}}} ``` # OCR ## Create Ocr > Extracts text from files using Mistral Document AI pipeline ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"OCR"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"CreateOCRBody":{"properties":{"bbox_annotation_format":{"anyOf":[{"$ref":"#/components/schemas/ResponseFormat"},{"type":"null"}],"description":"Specify the format that the model must output for the bounding boxes. By default it will use `{ \"type\": \"text\" }`. Setting to `{ \"type\": \"json_object\" }` enables JSON mode, which guarantees the message the model generates is in JSON. When using JSON mode you MUST also instruct the model to produce JSON yourself with a system or a user message. Setting to `{ \"type\": \"json_schema\" }` enables JSON schema mode, which guarantees the message the model generates is in JSON and follows the schema you provide."},"document":{"anyOf":[{"$ref":"#/components/schemas/DocumentURLChunk"},{"$ref":"#/components/schemas/ImageURLChunk"}],"title":"Document","description":"Document to run OCR on."},"document_annotation_format":{"anyOf":[{"$ref":"#/components/schemas/ResponseFormat"},{"type":"null"}],"description":"Specify the format that the model must output for the document. By default it will use `{ \"type\": \"text\" }`. Setting to `{ \"type\": \"json_object\" }` enables JSON mode, which guarantees the message the model generates is in JSON. When using JSON mode you MUST also instruct the model to produce JSON yourself with a system or a user message. Setting to `{ \"type\": \"json_schema\" }` enables JSON schema mode, which guarantees the message the model generates is in JSON and follows the schema you provide."},"document_annotation_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Annotation Prompt","description":"Optional prompt to guide the model in extracting structured output from the entire document. A document_annotation_format must be provided."},"extract_footer":{"type":"boolean","title":"Extract Footer","description":"Whether to extract the footer of the document.","default":false},"extract_header":{"type":"boolean","title":"Extract Header","description":"Whether to extract the header of the document.","default":false},"image_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Image Limit","description":"Max images to extract"},"image_min_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Image Min Size","description":"Minimum height and width of image to extract"},"include_image_base64":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Include Image Base64","description":"Include image URLs in response"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"The model to use for the OCR, call `/v1/models` endpoint to get the list of available models, only `image-to-text` model type is supported."},"pages":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Pages","description":"Specific pages to process. Accepts a list of integers or a string of comma-separated numbers and ranges (e.g. '0,1,2' or '0-5' or '0,2-4'). Page numbers start from 0."},"table_format":{"anyOf":[{"type":"string","enum":["markdown","html"]},{"type":"null"}],"title":"Table Format","description":"Format for table extraction: 'markdown' (default) or 'html'."}},"additionalProperties":true,"type":"object","required":["document"],"title":"CreateOCRBody"},"ResponseFormat":{"properties":{"type":{"type":"string","enum":["text","json_object","json_schema"],"title":"Type","description":"Specify the format that the model must output. By default it will use `{ \"type\": \"text\" }`. Setting to `{ \"type\": \"json_object\" }` enables JSON mode, which guarantees the message the model generates is in JSON. When using JSON mode you MUST also instruct the model to produce JSON yourself with a system or a user message. Setting to `{ \"type\": \"json_schema\" }` enables JSON schema mode, which guarantees the message the model generates is in JSON and follows the schema you provide.","default":"text"},"json_schema":{"anyOf":[{"$ref":"#/components/schemas/JsonSchema"},{"type":"null"}],"description":"The JSON schema definition. Required when type is 'json_schema'."}},"additionalProperties":true,"type":"object","title":"ResponseFormat"},"JsonSchema":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the JSON schema."},"schema":{"additionalProperties":true,"type":"object","title":"Schema","description":"The JSON schema definition."},"strict":{"type":"boolean","title":"Strict","description":"Whether to use strict mode.","default":false},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional description of the schema."}},"additionalProperties":true,"type":"object","required":["name","schema"],"title":"JsonSchema"},"DocumentURLChunk":{"properties":{"document_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Name","description":"The filename of the document."},"document_url":{"type":"string","title":"Document Url","description":"The URL of the document."},"type":{"type":"string","const":"document_url","title":"Type","description":"The type of the document.","default":"document_url"}},"additionalProperties":true,"type":"object","required":["document_url"],"title":"DocumentURLChunk"},"ImageURLChunk":{"properties":{"image_url":{"anyOf":[{"$ref":"#/components/schemas/api__infrastructure__fastapi__schemas__ocr__ImageURL"},{"type":"string"}],"title":"Image Url","description":"The URL of the image to OCR."},"type":{"type":"string","const":"image_url","title":"Type","description":"The type of the image.","default":"image_url"}},"additionalProperties":true,"type":"object","required":["image_url"],"title":"ImageURLChunk"},"api__infrastructure__fastapi__schemas__ocr__ImageURL":{"properties":{"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"The detail of the image."},"url":{"type":"string","title":"Url","description":"The URL of the image."}},"additionalProperties":true,"type":"object","required":["url"],"title":"ImageURL"},"OCRResponse":{"properties":{"document_annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Annotation","description":"Formatted response in the request_format if provided in json str"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"The ID of the OCR request."},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"The model used to generate the OCR."},"pages":{"items":{"$ref":"#/components/schemas/OCRPageObject"},"type":"array","title":"Pages","description":"List of OCR info for pages."},"usage":{"anyOf":[{"$ref":"#/components/schemas/api__domain__usage__entities__Usage"},{"type":"null"}],"description":"Usage information for the request."},"usage_info":{"anyOf":[{"$ref":"#/components/schemas/OCRUsage"},{"type":"null"}],"description":"Usage information for the request."}},"additionalProperties":true,"type":"object","required":["pages"],"title":"OCRResponse"},"OCRPageObject":{"properties":{"dimensions":{"anyOf":[{"$ref":"#/components/schemas/OCRPageDimensions"},{"type":"null"}],"description":"The dimensions of the PDF Page's screenshot image"},"footer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Footer","description":"The footer of the page, returned when extract_footer is enabled"},"header":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Header","description":"The header of the page, returned when extract_header is enabled"},"hyperlinks":{"items":{"type":"string"},"type":"array","title":"Hyperlinks","description":"The hyperlinks extracted from the page.","default":[]},"images":{"items":{"$ref":"#/components/schemas/OCRImageObject"},"type":"array","title":"Images","description":"List of all extracted images in the page."},"index":{"type":"integer","title":"Index","description":"The page index in a pdf document starting from 0"},"markdown":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Markdown","description":"The markdown string response of the page"},"tables":{"items":{"$ref":"#/components/schemas/OCRTableObject"},"type":"array","title":"Tables","description":"The tables extracted from the page, in the requested table_format.","default":[]}},"additionalProperties":true,"type":"object","required":["images","index"],"title":"OCRPageObject"},"OCRPageDimensions":{"properties":{"dpi":{"type":"integer","title":"Dpi","description":"Dots per inch of the page-image"},"height":{"type":"integer","title":"Height","description":"Height of the image in pixels"},"width":{"type":"integer","title":"Width","description":"Width of the image in pixels"}},"additionalProperties":true,"type":"object","required":["dpi","height","width"],"title":"OCRPageDimensions"},"OCRImageObject":{"properties":{"bottom_right_x":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bottom Right X","description":"X coordinate of bottom-right corner of the extracted image"},"bottom_right_y":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bottom Right Y","description":"Y coordinate of bottom-right corner of the extracted image"},"id":{"type":"string","title":"Id","description":"Image ID for extracted image in a page"},"image_annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Annotation","description":"Annotation of the extracted image in json str"},"image_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Base64","description":"Base64 string of the extracted image"},"top_left_x":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top Left X","description":"X coordinate of top-left corner of the extracted image"},"top_left_y":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top Left Y","description":"Y coordinate of top-left corner of the extracted image"}},"additionalProperties":true,"type":"object","required":["id"],"title":"OCRImageObject"},"OCRTableObject":{"properties":{"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"The content of the extracted table, in the requested table format"},"format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Format","description":"The format of the extracted table: 'markdown' or 'html'"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Table ID for the extracted table in a page"}},"additionalProperties":true,"type":"object","title":"OCRTableObject"},"api__domain__usage__entities__Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","default":0},"total_tokens":{"type":"integer","title":"Total Tokens","default":0},"cost":{"type":"number","title":"Cost","default":0},"impacts":{"$ref":"#/components/schemas/api__domain__usage__entities__EnvironmentalImpacts","default":{"kWh":0,"kgCO2eq":0}}},"additionalProperties":true,"type":"object","title":"Usage"},"api__domain__usage__entities__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"},"OCRUsage":{"properties":{"doc_size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Doc Size Bytes","description":"Document size in bytes"},"pages_processed":{"type":"integer","title":"Pages Processed","description":"Number of pages processed"}},"additionalProperties":true,"type":"object","required":["pages_processed"],"title":"OCRUsage"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"}}},"paths":{"/v1/ocr":{"post":{"tags":["OCR"],"summary":"Create Ocr","description":"Extracts text from files using Mistral Document AI pipeline","operationId":"create_ocr_v1_ocr_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOCRBody","description":"The OCR creation request."}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OCRResponse"}}}},"400":{"description":"Insufficient budget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"404":{"description":"Model {name} not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Model has wrong type. Expected: {expected_type}. Actual: {actual_type}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"429":{"description":"Token/request limit per minute/day exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"503":{"description":"Model is too busy, please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}}}}}}} ``` # Rerank ## POST /v1/rerank > Create Rerank ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Rerank"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"CreateRerankBody":{"properties":{"query":{"type":"string","minLength":1,"title":"Query","description":"The search query to use for the reranking. `query` and `prompt` cannot both be provided."},"documents":{"items":{"type":"string","minLength":1},"type":"array","title":"Documents"},"model":{"type":"string","minLength":1,"title":"Model","description":"The model to use for the reranking, call `/v1/models` endpoint to get the list of available models, only `text-classification` model type is supported."},"top_n":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Top N","description":"The number of top results to return. If set to None, all results will be returned."}},"additionalProperties":true,"type":"object","required":["query","documents","model"],"title":"CreateRerankBody"},"RerankResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Type of object.","default":"list"},"id":{"type":"string","title":"Id","description":"A unique identifier for the request."},"results":{"items":{"$ref":"#/components/schemas/RerankResult"},"type":"array","title":"Results","description":"The list of reranked texts."},"model":{"type":"string","title":"Model","description":"The model used to generate the reranking."},"usage":{"$ref":"#/components/schemas/api__domain__usage__entities__Usage","description":"Usage information for the request."}},"additionalProperties":true,"type":"object","required":["id","results","model"],"title":"RerankResponse"},"RerankResult":{"properties":{"relevance_score":{"type":"number","title":"Relevance Score","description":"The relevance score of the reranked text."},"index":{"type":"integer","title":"Index","description":"The index of the reranked text."}},"additionalProperties":true,"type":"object","required":["relevance_score","index"],"title":"RerankResult"},"api__domain__usage__entities__Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","default":0},"total_tokens":{"type":"integer","title":"Total Tokens","default":0},"cost":{"type":"number","title":"Cost","default":0},"impacts":{"$ref":"#/components/schemas/api__domain__usage__entities__EnvironmentalImpacts","default":{"kWh":0,"kgCO2eq":0}}},"additionalProperties":true,"type":"object","title":"Usage"},"api__domain__usage__entities__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"}}},"paths":{"/v1/rerank":{"post":{"tags":["Rerank"],"summary":"Create Rerank","operationId":"create_rerank_v1_rerank_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRerankBody","description":"The rerank creation request."}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RerankResponse"}}}},"400":{"description":"Insufficient budget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"404":{"description":"Model {name} not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Model has wrong type. Expected: {expected_type}. Actual: {actual_type}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"429":{"description":"Token/request limit per minute/day exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"503":{"description":"Model is too busy, please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}}}}}}} ``` # Search ## Search > Get relevant chunks from the collections and a query. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Search"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"CreateSearch":{"properties":{"collection_ids":{"items":{"type":"integer","exclusiveMinimum":0},"type":"array","maxItems":100,"minItems":0,"title":"Collection Ids","description":"List of collections ID.","default":[]},"document_ids":{"items":{"type":"integer","exclusiveMinimum":0},"type":"array","maxItems":100,"minItems":0,"title":"Document Ids","description":"List of document IDs","default":[]},"metadata_filters":{"anyOf":[{"$ref":"#/components/schemas/ComparisonFilter"},{"$ref":"#/components/schemas/CompoundFilter"},{"type":"null"}],"title":"Metadata Filters","description":"Metadata filters to apply to the search."},"limit":{"type":"integer","maximum":100,"exclusiveMinimum":0,"title":"Limit","description":"Number of results to return.","default":10},"offset":{"type":"integer","minimum":0,"title":"Offset","description":"Offset for pagination, specifying how many results to skip from the beginning.","default":0},"method":{"$ref":"#/components/schemas/SearchMethod","description":"Search method to use.","default":"semantic"},"rff_k":{"type":"integer","maximum":16384,"minimum":0,"title":"Rff K","description":"Smoothing constant for Reciprocal Rank Fusion (RRF) algorithm in hybrid search (recommended: from 10 to 100).","default":60},"score_threshold":{"type":"number","maximum":1,"minimum":0,"title":"Score Threshold","description":"Score of cosine similarity threshold for filtering results, only available for semantic search method.","default":0},"query":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Query","description":"Query related to the search."}},"additionalProperties":true,"type":"object","title":"CreateSearch"},"ComparisonFilter":{"properties":{"key":{"type":"string","maxLength":255,"minLength":1,"title":"Key"},"type":{"$ref":"#/components/schemas/ComparisonFilterType"},"value":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"integer","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"number","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"boolean"}],"title":"Value"}},"additionalProperties":true,"type":"object","required":["key","type","value"],"title":"ComparisonFilter"},"ComparisonFilterType":{"type":"string","enum":["eq","sw","ew","co"],"title":"ComparisonFilterType","description":"Comparison filter type for metadata filters."},"CompoundFilter":{"properties":{"filters":{"items":{"$ref":"#/components/schemas/ComparisonFilter"},"type":"array","maxItems":4,"minItems":2,"title":"Filters","description":"List of filters to apply to the search."},"operator":{"$ref":"#/components/schemas/CompoundFilterOperator","description":"Operator to use for the compound filter."}},"additionalProperties":true,"type":"object","required":["filters","operator"],"title":"CompoundFilter"},"CompoundFilterOperator":{"type":"string","enum":["and","or"],"title":"CompoundFilterOperator","description":"Compound filter operator for metadata filters."},"SearchMethod":{"type":"string","enum":["hybrid","semantic","lexical"],"title":"SearchMethod"},"Searches":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"The type of the object.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Search"},"type":"array","title":"Data","description":"List of search results."},"usage":{"$ref":"#/components/schemas/Usage","description":"Usage information for the request."}},"additionalProperties":true,"type":"object","required":["data"],"title":"Searches"},"Search":{"properties":{"method":{"$ref":"#/components/schemas/SearchMethod","description":"Search method used."},"score":{"type":"number","title":"Score","description":"Score of the search result."},"chunk":{"$ref":"#/components/schemas/Chunk","description":"Chunk of the search result."}},"additionalProperties":true,"type":"object","required":["method","score","chunk"],"title":"Search"},"Chunk":{"properties":{"object":{"type":"string","const":"chunk","title":"Object","description":"The type of the object.","default":"chunk"},"id":{"type":"integer","minimum":0,"title":"Id","description":"The ID of the chunk."},"collection_id":{"type":"integer","minimum":0,"title":"Collection Id","description":"The ID of the collection the chunk belongs to."},"document_id":{"type":"integer","minimum":0,"title":"Document Id","description":"The ID of the document the chunk belongs to."},"content":{"type":"string","minLength":1,"title":"Content","description":"The content of the chunk."},"metadata":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"integer","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"number","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"boolean"}]},"propertyNames":{"maxLength":255,"minLength":1},"type":"object","maxProperties":10,"minProperties":1,"description":"Extra metadata for the source"},{"type":"null"}],"title":"Metadata","description":"Metadata of the chunk"},"created":{"type":"integer","title":"Created","description":"The date of the chunk creation."}},"additionalProperties":true,"type":"object","required":["id","collection_id","document_id","content"],"title":"Chunk"},"Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","default":0},"total_tokens":{"type":"integer","title":"Total Tokens","default":0},"cost":{"type":"number","title":"Cost","default":0},"impacts":{"$ref":"#/components/schemas/EnvironmentalImpacts","default":{"kWh":0,"kgCO2eq":0}}},"additionalProperties":true,"type":"object","title":"Usage"},"EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/search":{"post":{"tags":["Search"],"summary":"Search","description":"Get relevant chunks from the collections and a query.","operationId":"search_v1_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSearch"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Searches"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` # Usage ## Get Usages > Get usage for the current user. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Usage"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"EndpointUsage":{"type":"string","enum":["/v1/audio/transcriptions","/v1/chat/completions","/v1/embeddings","/v1/ocr","/v1/rerank","/v1/search"],"title":"EndpointUsage"},"UsagesResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Type of the object.","default":"list"},"total":{"type":"integer","title":"Total","description":"Total number of usages."},"offset":{"type":"integer","title":"Offset","description":"Offset of the usages list."},"limit":{"type":"integer","title":"Limit","description":"Limit of the usages list."},"data":{"items":{"$ref":"#/components/schemas/UsageResponse"},"type":"array","title":"Data","description":"List of usages."}},"additionalProperties":true,"type":"object","required":["total","offset","limit","data"],"title":"UsagesResponse"},"UsageResponse":{"properties":{"object":{"type":"string","const":"usage","title":"Object","description":"Type of the object.","default":"usage"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"Model used for the request."},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"Key used for the request."},"endpoint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint","description":"Endpoint used for the request."},"usage":{"$ref":"#/components/schemas/UsageDetail"},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."}},"additionalProperties":true,"type":"object","required":["created"],"title":"UsageResponse"},"UsageDetail":{"properties":{"prompt_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prompt Tokens","description":"Number of prompt tokens (e.g. input tokens)."},"completion_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Completion Tokens","description":"Number of completion tokens (e.g. output tokens)."},"total_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Tokens","description":"Total number of tokens (e.g. input and output tokens)."},"cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost","description":"Total cost of the request."},"impacts":{"$ref":"#/components/schemas/api__infrastructure__fastapi__schemas__usage__EnvironmentalImpacts"}},"additionalProperties":true,"type":"object","title":"UsageDetail"},"api__infrastructure__fastapi__schemas__usage__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","description":"Energy consumption in kWh.","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","description":"Carbon footprint in kgCO2eq (global warming potential).","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/usage":{"get":{"tags":["Usage"],"summary":"Get Usages","description":"Get usage for the current user.","operationId":"get_usages_v1_usage_get","parameters":[{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of usages to skip.","default":0,"title":"Offset"},"description":"Number of usages to skip."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of usages to return.","default":10,"title":"Limit"},"description":"Maximum number of usages to return."},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Start time as Unix timestamp (if not provided, will be set to 30 days ago).","title":"Start Time"},"description":"Start time as Unix timestamp (if not provided, will be set to 30 days ago)."},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"End time as Unix timestamp (if not provided, will be set to now).","title":"End Time"},"description":"End time as Unix timestamp (if not provided, will be set to now)."},{"name":"endpoint","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/EndpointUsage"},{"type":"null"}],"description":"The endpoint to get usage for.","title":"Endpoint"},"description":"The endpoint to get usage for."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsagesResponse"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Usages > Get usage for the current user. ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"tags":[{"name":"Usage"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"EndpointUsage":{"type":"string","enum":["/v1/audio/transcriptions","/v1/chat/completions","/v1/embeddings","/v1/ocr","/v1/rerank","/v1/search"],"title":"EndpointUsage"},"UsagesResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Type of the object.","default":"list"},"total":{"type":"integer","title":"Total","description":"Total number of usages."},"offset":{"type":"integer","title":"Offset","description":"Offset of the usages list."},"limit":{"type":"integer","title":"Limit","description":"Limit of the usages list."},"data":{"items":{"$ref":"#/components/schemas/UsageResponse"},"type":"array","title":"Data","description":"List of usages."}},"additionalProperties":true,"type":"object","required":["total","offset","limit","data"],"title":"UsagesResponse"},"UsageResponse":{"properties":{"object":{"type":"string","const":"usage","title":"Object","description":"Type of the object.","default":"usage"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"Model used for the request."},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"Key used for the request."},"endpoint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint","description":"Endpoint used for the request."},"usage":{"$ref":"#/components/schemas/UsageDetail"},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."}},"additionalProperties":true,"type":"object","required":["created"],"title":"UsageResponse"},"UsageDetail":{"properties":{"prompt_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prompt Tokens","description":"Number of prompt tokens (e.g. input tokens)."},"completion_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Completion Tokens","description":"Number of completion tokens (e.g. output tokens)."},"total_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Tokens","description":"Total number of tokens (e.g. input and output tokens)."},"cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost","description":"Total cost of the request."},"impacts":{"$ref":"#/components/schemas/api__infrastructure__fastapi__schemas__usage__EnvironmentalImpacts"}},"additionalProperties":true,"type":"object","title":"UsageDetail"},"api__infrastructure__fastapi__schemas__usage__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","description":"Energy consumption in kWh.","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","description":"Carbon footprint in kgCO2eq (global warming potential).","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/me/usage":{"get":{"tags":["Usage"],"summary":"Get Usages","description":"Get usage for the current user.","operationId":"get_usages_v1_me_usage_get","deprecated":true,"parameters":[{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of usages to skip.","default":0,"title":"Offset"},"description":"Number of usages to skip."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of usages to return.","default":10,"title":"Limit"},"description":"Maximum number of usages to return."},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Start time as Unix timestamp (if not provided, will be set to 30 days ago).","title":"Start Time"},"description":"Start time as Unix timestamp (if not provided, will be set to 30 days ago)."},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"End time as Unix timestamp (if not provided, will be set to now).","title":"End Time"},"description":"End time as Unix timestamp (if not provided, will be set to now)."},{"name":"endpoint","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/EndpointUsage"},{"type":"null"}],"description":"The endpoint to get usage for.","title":"Endpoint"},"description":"The endpoint to get usage for."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsagesResponse"}}}},"401":{"description":"Invalid authentication scheme.
Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` # Models ## The Body\_create\_document\_v1\_documents\_post object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"Body_create_document_v1_documents_post":{"properties":{"file":{"anyOf":[{"type":"string","contentMediaType":"application/octet-stream"},{"type":"null"}],"title":"File","description":"The file to create a document from. If not provided, the document will be created without content, use POST `/v1/documents/{document_id}/chunks` to fill it."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Name of document if no file is provided or to override file name."},"collection_id":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}],"title":"Collection Id","description":"The collection ID to use for the file upload. The file will be vectorized with model defined by the collection."},"disable_chunking":{"type":"boolean","title":"Disable Chunking","description":"Whether to disable `RecursiveCharacterTextSplitter` chunking for the upload file.","default":false},"chunk_size":{"type":"integer","minimum":0,"title":"Chunk Size","description":"The size in characters of the chunks to use for the upload file. If not provided, the document will not be split into chunks.","default":2048},"chunk_min_size":{"type":"integer","minimum":0,"title":"Chunk Min Size","description":"The minimum size in characters of the chunks to use for the upload file.","default":0},"chunk_overlap":{"type":"integer","minimum":0,"title":"Chunk Overlap","description":"The overlap in characters of the chunks to use for the upload file.","default":0},"is_separator_regex":{"type":"boolean","title":"Is Separator Regex","description":"Whether the separator is a regex to use for the upload file.","default":false},"separators":{"items":{"type":"string"},"type":"array","minItems":0,"title":"Separators","description":"Delimiters used by RecursiveCharacterTextSplitter for further splitting. If provided, `preset_separators` is ignored.","default":[]},"preset_separators":{"$ref":"#/components/schemas/PresetSeparators","description":"Preset separators used by RecursiveCharacterTextSplitter for further splitting. See [implemented details](https://github.com/langchain-ai/langchain/blob/eb122945832eae9b9df7c70ccd8d51fcd7a1899b/libs/text-splitters/langchain_text_splitters/character.py#L164).","default":"markdown"},"metadata":{"type":"string","title":"Metadata","description":"Optional additional metadata to add to each chunk if a file is provided. Provide a stringified JSON object matching the Metadata schema.","default":""}},"type":"object","title":"Body_create_document_v1_documents_post"},"PresetSeparators":{"type":"string","enum":["cpp","go","java","kotlin","js","ts","php","proto","python","r","rst","ruby","rust","scala","swift","markdown","latex","html","sol","csharp","cobol","c","lua","perl","haskell","elixir","powershell","visualbasic6"],"title":"PresetSeparators"}}}} ``` ## The Chunk object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"Chunk":{"properties":{"object":{"type":"string","const":"chunk","title":"Object","description":"The type of the object.","default":"chunk"},"id":{"type":"integer","minimum":0,"title":"Id","description":"The ID of the chunk."},"collection_id":{"type":"integer","minimum":0,"title":"Collection Id","description":"The ID of the collection the chunk belongs to."},"document_id":{"type":"integer","minimum":0,"title":"Document Id","description":"The ID of the document the chunk belongs to."},"content":{"type":"string","minLength":1,"title":"Content","description":"The content of the chunk."},"metadata":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"integer","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"number","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"boolean"}]},"propertyNames":{"maxLength":255,"minLength":1},"type":"object","maxProperties":10,"minProperties":1,"description":"Extra metadata for the source"},{"type":"null"}],"title":"Metadata","description":"Metadata of the chunk"},"created":{"type":"integer","title":"Created","description":"The date of the chunk creation."}},"additionalProperties":true,"type":"object","required":["id","collection_id","document_id","content"],"title":"Chunk"}}}} ``` ## The Collection object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"Collection":{"properties":{"object":{"type":"string","const":"collection","title":"Object","default":"collection"},"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"owner":{"type":"integer","title":"Owner"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"visibility":{"anyOf":[{"$ref":"#/components/schemas/CollectionVisibility"},{"type":"null"}]},"created":{"type":"integer","title":"Created"},"updated":{"type":"integer","title":"Updated"},"documents":{"type":"integer","title":"Documents","default":0},"size":{"type":"integer","title":"Size","default":0}},"additionalProperties":true,"type":"object","required":["id","name","owner","created","updated"],"title":"Collection"},"CollectionVisibility":{"type":"string","enum":["private","public"],"title":"CollectionVisibility"}}}} ``` ## The CollectionRequest object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"CollectionRequest":{"properties":{"name":{"type":"string","minLength":1,"title":"Name","description":"The name of the collection."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"The description of the collection."},"visibility":{"$ref":"#/components/schemas/CollectionVisibility","description":"The type of the collection. Public collections are available to all users, private collections are only available to the user who created them.","default":"private"}},"additionalProperties":true,"type":"object","required":["name"],"title":"CollectionRequest"},"CollectionVisibility":{"type":"string","enum":["private","public"],"title":"CollectionVisibility"}}}} ``` ## The CollectionUpdateRequest object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"CollectionUpdateRequest":{"properties":{"name":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Name","description":"The name of the collection."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"The description of the collection."},"visibility":{"anyOf":[{"$ref":"#/components/schemas/CollectionVisibility"},{"type":"null"}],"description":"The type of the collection. Public collections are available to all users, private collections are only available to the user who created them."}},"additionalProperties":true,"type":"object","title":"CollectionUpdateRequest"},"CollectionVisibility":{"type":"string","enum":["private","public"],"title":"CollectionVisibility"}}}} ``` ## The CollectionVisibility object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"CollectionVisibility":{"type":"string","enum":["private","public"],"title":"CollectionVisibility"}}}} ``` ## The Collections object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"Collections":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Collection"},"type":"array","title":"Data"}},"additionalProperties":true,"type":"object","required":["data"],"title":"Collections"},"Collection":{"properties":{"object":{"type":"string","const":"collection","title":"Object","default":"collection"},"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"owner":{"type":"integer","title":"Owner"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"visibility":{"anyOf":[{"$ref":"#/components/schemas/CollectionVisibility"},{"type":"null"}]},"created":{"type":"integer","title":"Created"},"updated":{"type":"integer","title":"Updated"},"documents":{"type":"integer","title":"Documents","default":0},"size":{"type":"integer","title":"Size","default":0}},"additionalProperties":true,"type":"object","required":["id","name","owner","created","updated"],"title":"Collection"},"CollectionVisibility":{"type":"string","enum":["private","public"],"title":"CollectionVisibility"}}}} ``` ## The ComparisonFilter object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ComparisonFilter":{"properties":{"key":{"type":"string","maxLength":255,"minLength":1,"title":"Key"},"type":{"$ref":"#/components/schemas/ComparisonFilterType"},"value":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"integer","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"number","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"boolean"}],"title":"Value"}},"additionalProperties":true,"type":"object","required":["key","type","value"],"title":"ComparisonFilter"},"ComparisonFilterType":{"type":"string","enum":["eq","sw","ew","co"],"title":"ComparisonFilterType","description":"Comparison filter type for metadata filters."}}}} ``` ## The ComparisonFilterType object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ComparisonFilterType":{"type":"string","enum":["eq","sw","ew","co"],"title":"ComparisonFilterType","description":"Comparison filter type for metadata filters."}}}} ``` ## The CompoundFilter object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"CompoundFilter":{"properties":{"filters":{"items":{"$ref":"#/components/schemas/ComparisonFilter"},"type":"array","maxItems":4,"minItems":2,"title":"Filters","description":"List of filters to apply to the search."},"operator":{"$ref":"#/components/schemas/CompoundFilterOperator","description":"Operator to use for the compound filter."}},"additionalProperties":true,"type":"object","required":["filters","operator"],"title":"CompoundFilter"},"ComparisonFilter":{"properties":{"key":{"type":"string","maxLength":255,"minLength":1,"title":"Key"},"type":{"$ref":"#/components/schemas/ComparisonFilterType"},"value":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"integer","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"number","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"boolean"}],"title":"Value"}},"additionalProperties":true,"type":"object","required":["key","type","value"],"title":"ComparisonFilter"},"ComparisonFilterType":{"type":"string","enum":["eq","sw","ew","co"],"title":"ComparisonFilterType","description":"Comparison filter type for metadata filters."},"CompoundFilterOperator":{"type":"string","enum":["and","or"],"title":"CompoundFilterOperator","description":"Compound filter operator for metadata filters."}}}} ``` ## The CompoundFilterOperator object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"CompoundFilterOperator":{"type":"string","enum":["and","or"],"title":"CompoundFilterOperator","description":"Compound filter operator for metadata filters."}}}} ``` ## The CreateChunks object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"CreateChunks":{"properties":{"chunks":{"items":{"$ref":"#/components/schemas/InputChunk"},"type":"array","maxItems":64,"minItems":1,"title":"Chunks","description":"The list of chunks to create."}},"additionalProperties":true,"type":"object","required":["chunks"],"title":"CreateChunks"},"InputChunk":{"properties":{"content":{"type":"string","title":"Content","description":"The content of the chunk."},"metadata":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"integer","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"number","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"boolean"}]},"propertyNames":{"maxLength":255,"minLength":1},"type":"object","maxProperties":10,"minProperties":1,"description":"Extra metadata for the source"},{"type":"null"}],"title":"Metadata","description":"Metadata of the chunk"}},"additionalProperties":true,"type":"object","required":["content"],"title":"InputChunk"}}}} ``` ## The CreateSearch object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"CreateSearch":{"properties":{"collection_ids":{"items":{"type":"integer","exclusiveMinimum":0},"type":"array","maxItems":100,"minItems":0,"title":"Collection Ids","description":"List of collections ID.","default":[]},"document_ids":{"items":{"type":"integer","exclusiveMinimum":0},"type":"array","maxItems":100,"minItems":0,"title":"Document Ids","description":"List of document IDs","default":[]},"metadata_filters":{"anyOf":[{"$ref":"#/components/schemas/ComparisonFilter"},{"$ref":"#/components/schemas/CompoundFilter"},{"type":"null"}],"title":"Metadata Filters","description":"Metadata filters to apply to the search."},"limit":{"type":"integer","maximum":100,"exclusiveMinimum":0,"title":"Limit","description":"Number of results to return.","default":10},"offset":{"type":"integer","minimum":0,"title":"Offset","description":"Offset for pagination, specifying how many results to skip from the beginning.","default":0},"method":{"$ref":"#/components/schemas/SearchMethod","description":"Search method to use.","default":"semantic"},"rff_k":{"type":"integer","maximum":16384,"minimum":0,"title":"Rff K","description":"Smoothing constant for Reciprocal Rank Fusion (RRF) algorithm in hybrid search (recommended: from 10 to 100).","default":60},"score_threshold":{"type":"number","maximum":1,"minimum":0,"title":"Score Threshold","description":"Score of cosine similarity threshold for filtering results, only available for semantic search method.","default":0},"query":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Query","description":"Query related to the search."}},"additionalProperties":true,"type":"object","title":"CreateSearch"},"ComparisonFilter":{"properties":{"key":{"type":"string","maxLength":255,"minLength":1,"title":"Key"},"type":{"$ref":"#/components/schemas/ComparisonFilterType"},"value":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"integer","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"number","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"boolean"}],"title":"Value"}},"additionalProperties":true,"type":"object","required":["key","type","value"],"title":"ComparisonFilter"},"ComparisonFilterType":{"type":"string","enum":["eq","sw","ew","co"],"title":"ComparisonFilterType","description":"Comparison filter type for metadata filters."},"CompoundFilter":{"properties":{"filters":{"items":{"$ref":"#/components/schemas/ComparisonFilter"},"type":"array","maxItems":4,"minItems":2,"title":"Filters","description":"List of filters to apply to the search."},"operator":{"$ref":"#/components/schemas/CompoundFilterOperator","description":"Operator to use for the compound filter."}},"additionalProperties":true,"type":"object","required":["filters","operator"],"title":"CompoundFilter"},"CompoundFilterOperator":{"type":"string","enum":["and","or"],"title":"CompoundFilterOperator","description":"Compound filter operator for metadata filters."},"SearchMethod":{"type":"string","enum":["hybrid","semantic","lexical"],"title":"SearchMethod"}}}} ``` ## The Document object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"Document":{"properties":{"object":{"type":"string","const":"document","title":"Object","description":"The type of the object.","default":"document"},"id":{"type":"integer","exclusiveMinimum":0,"title":"Id","description":"The ID of the document."},"name":{"type":"string","minLength":1,"title":"Name","description":"The name of the document."},"collection_id":{"type":"integer","exclusiveMinimum":0,"title":"Collection Id","description":"The ID of the collection the document belongs to."},"created":{"type":"integer","title":"Created","description":"The date of the document creation."},"chunks":{"type":"integer","minimum":0,"title":"Chunks","description":"The number of chunks the document has.","default":0},"size":{"type":"integer","minimum":0,"title":"Size","description":"The size of the document in tokens.","default":0}},"additionalProperties":true,"type":"object","required":["id","name","collection_id","created"],"title":"Document"}}}} ``` ## The DocumentResponse object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"DocumentResponse":{"properties":{"id":{"type":"integer","minimum":0,"title":"Id","description":"The ID of the document created."}},"additionalProperties":true,"type":"object","required":["id"],"title":"DocumentResponse"}}}} ``` ## The EnvironmentalImpacts object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"}}}} ``` ## The HTTPValidationError object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## The InputChunk object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"InputChunk":{"properties":{"content":{"type":"string","title":"Content","description":"The content of the chunk."},"metadata":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"integer","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"number","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"boolean"}]},"propertyNames":{"maxLength":255,"minLength":1},"type":"object","maxProperties":10,"minProperties":1,"description":"Extra metadata for the source"},{"type":"null"}],"title":"Metadata","description":"Metadata of the chunk"}},"additionalProperties":true,"type":"object","required":["content"],"title":"InputChunk"}}}} ``` ## The PresetSeparators object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"PresetSeparators":{"type":"string","enum":["cpp","go","java","kotlin","js","ts","php","proto","python","r","rst","ruby","rust","scala","swift","markdown","latex","html","sol","csharp","cobol","c","lua","perl","haskell","elixir","powershell","visualbasic6"],"title":"PresetSeparators"}}}} ``` ## The Search object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"Search":{"properties":{"method":{"$ref":"#/components/schemas/SearchMethod","description":"Search method used."},"score":{"type":"number","title":"Score","description":"Score of the search result."},"chunk":{"$ref":"#/components/schemas/Chunk","description":"Chunk of the search result."}},"additionalProperties":true,"type":"object","required":["method","score","chunk"],"title":"Search"},"SearchMethod":{"type":"string","enum":["hybrid","semantic","lexical"],"title":"SearchMethod"},"Chunk":{"properties":{"object":{"type":"string","const":"chunk","title":"Object","description":"The type of the object.","default":"chunk"},"id":{"type":"integer","minimum":0,"title":"Id","description":"The ID of the chunk."},"collection_id":{"type":"integer","minimum":0,"title":"Collection Id","description":"The ID of the collection the chunk belongs to."},"document_id":{"type":"integer","minimum":0,"title":"Document Id","description":"The ID of the document the chunk belongs to."},"content":{"type":"string","minLength":1,"title":"Content","description":"The content of the chunk."},"metadata":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"integer","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"number","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"boolean"}]},"propertyNames":{"maxLength":255,"minLength":1},"type":"object","maxProperties":10,"minProperties":1,"description":"Extra metadata for the source"},{"type":"null"}],"title":"Metadata","description":"Metadata of the chunk"},"created":{"type":"integer","title":"Created","description":"The date of the chunk creation."}},"additionalProperties":true,"type":"object","required":["id","collection_id","document_id","content"],"title":"Chunk"}}}} ``` ## The SearchMethod object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"SearchMethod":{"type":"string","enum":["hybrid","semantic","lexical"],"title":"SearchMethod"}}}} ``` ## The Searches object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"Searches":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"The type of the object.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Search"},"type":"array","title":"Data","description":"List of search results."},"usage":{"$ref":"#/components/schemas/Usage","description":"Usage information for the request."}},"additionalProperties":true,"type":"object","required":["data"],"title":"Searches"},"Search":{"properties":{"method":{"$ref":"#/components/schemas/SearchMethod","description":"Search method used."},"score":{"type":"number","title":"Score","description":"Score of the search result."},"chunk":{"$ref":"#/components/schemas/Chunk","description":"Chunk of the search result."}},"additionalProperties":true,"type":"object","required":["method","score","chunk"],"title":"Search"},"SearchMethod":{"type":"string","enum":["hybrid","semantic","lexical"],"title":"SearchMethod"},"Chunk":{"properties":{"object":{"type":"string","const":"chunk","title":"Object","description":"The type of the object.","default":"chunk"},"id":{"type":"integer","minimum":0,"title":"Id","description":"The ID of the chunk."},"collection_id":{"type":"integer","minimum":0,"title":"Collection Id","description":"The ID of the collection the chunk belongs to."},"document_id":{"type":"integer","minimum":0,"title":"Document Id","description":"The ID of the document the chunk belongs to."},"content":{"type":"string","minLength":1,"title":"Content","description":"The content of the chunk."},"metadata":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"integer","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"number","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"boolean"}]},"propertyNames":{"maxLength":255,"minLength":1},"type":"object","maxProperties":10,"minProperties":1,"description":"Extra metadata for the source"},{"type":"null"}],"title":"Metadata","description":"Metadata of the chunk"},"created":{"type":"integer","title":"Created","description":"The date of the chunk creation."}},"additionalProperties":true,"type":"object","required":["id","collection_id","document_id","content"],"title":"Chunk"},"Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","default":0},"total_tokens":{"type":"integer","title":"Total Tokens","default":0},"cost":{"type":"number","title":"Cost","default":0},"impacts":{"$ref":"#/components/schemas/EnvironmentalImpacts","default":{"kWh":0,"kgCO2eq":0}}},"additionalProperties":true,"type":"object","title":"Usage"},"EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"}}}} ``` ## The Usage object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","default":0},"total_tokens":{"type":"integer","title":"Total Tokens","default":0},"cost":{"type":"number","title":"Cost","default":0},"impacts":{"$ref":"#/components/schemas/EnvironmentalImpacts","default":{"kWh":0,"kgCO2eq":0}}},"additionalProperties":true,"type":"object","title":"Usage"},"EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"}}}} ``` ## The ValidationError object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## The Annotation object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"Annotation":{"properties":{"type":{"type":"string","const":"url_citation","title":"Type"},"url_citation":{"$ref":"#/components/schemas/AnnotationURLCitation"}},"additionalProperties":true,"type":"object","required":["type","url_citation"],"title":"Annotation","description":"A URL citation when using web search."},"AnnotationURLCitation":{"properties":{"end_index":{"type":"integer","title":"End Index"},"start_index":{"type":"integer","title":"Start Index"},"title":{"type":"string","title":"Title"},"url":{"type":"string","title":"Url"}},"additionalProperties":true,"type":"object","required":["end_index","start_index","title","url"],"title":"AnnotationURLCitation","description":"A URL citation when using web search."}}}} ``` ## The AnnotationURLCitation object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"AnnotationURLCitation":{"properties":{"end_index":{"type":"integer","title":"End Index"},"start_index":{"type":"integer","title":"Start Index"},"title":{"type":"string","title":"Title"},"url":{"type":"string","title":"Url"}},"additionalProperties":true,"type":"object","required":["end_index","start_index","title","url"],"title":"AnnotationURLCitation","description":"A URL citation when using web search."}}}} ``` ## The AudioTranscriptionLanguage object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"AudioTranscriptionLanguage":{"type":"string","enum":["af","afrikaans","albanian","am","amharic","ar","arabic","armenian","as","assamese","az","azerbaijani","ba","bashkir","basque","be","belarusian","bengali","bg","bn","bo","bosnian","br","breton","bs","bulgarian","burmese","ca","cantonese","castilian","catalan","chinese","croatian","cs","cy","czech","da","danish","de","dutch","el","en","english","es","estonian","et","eu","fa","faroese","fi","finnish","flemish","fo","fr","french","galician","georgian","german","gl","greek","gu","gujarati","ha","haitian","haitian creole","hausa","haw","hawaiian","he","hebrew","hi","hindi","hr","ht","hu","hungarian","hy","icelandic","id","indonesian","is","it","italian","ja","japanese","javanese","jw","ka","kannada","kazakh","khmer","kk","km","kn","ko","korean","la","lao","latin","latvian","lb","letzeburgesch","lingala","lithuanian","ln","lo","lt","luxembourgish","lv","macedonian","malagasy","malay","malayalam","maltese","mandarin","maori","marathi","mg","mi","mk","ml","mn","moldavian","moldovan","mongolian","mr","ms","mt","my","myanmar","ne","nepali","nl","nn","no","norwegian","nynorsk","oc","occitan","pa","panjabi","pashto","persian","pl","polish","portuguese","ps","pt","punjabi","pushto","ro","romanian","ru","russian","sa","sanskrit","sd","serbian","shona","si","sindhi","sinhala","sinhalese","sk","sl","slovak","slovenian","sn","so","somali","spanish","sq","sr","su","sundanese","sv","sw","swahili","swedish","ta","tagalog","tajik","tamil","tatar","te","telugu","tg","th","thai","tibetan","tk","tl","tr","tt","turkish","turkmen","uk","ukrainian","ur","urdu","uz","uzbek","valencian","vi","vietnamese","welsh","yi","yiddish","yo","yoruba","yue","zh"],"title":"AudioTranscriptionLanguage"}}}} ``` ## The AudioTranscriptionsResponse object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"AudioTranscriptionsResponse":{"properties":{"id":{"type":"string","title":"Id","description":"A unique identifier for the audio transcription."},"text":{"type":"string","title":"Text","description":"The transcription text."},"model":{"type":"string","title":"Model","description":"The model used to generate the transcription."},"segments":{"anyOf":[{"items":{"$ref":"#/components/schemas/Segment"},"type":"array"},{"type":"null"}],"title":"Segments","description":"Diarized segments, only set when `response_format=diarized_json`."},"usage":{"$ref":"#/components/schemas/api__domain__usage__entities__Usage","description":"Usage information for the request."}},"additionalProperties":true,"type":"object","required":["id","text","model"],"title":"AudioTranscriptionsResponse"},"Segment":{"properties":{"id":{"type":"integer","title":"Id","description":"A unique identifier for the segment."},"type":{"type":"string","title":"Type","description":"The type of the segment.","default":"transcript.text.segment"},"text":{"type":"string","title":"Text","description":"The segment text."},"start":{"type":"number","title":"Start","description":"Start time of the segment in seconds."},"end":{"type":"number","title":"End","description":"End time of the segment in seconds."},"speaker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Speaker","description":"Speaker label assigned by diarization, if available."}},"additionalProperties":true,"type":"object","required":["id","text","start","end"],"title":"Segment"},"api__domain__usage__entities__Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","default":0},"total_tokens":{"type":"integer","title":"Total Tokens","default":0},"cost":{"type":"number","title":"Cost","default":0},"impacts":{"$ref":"#/components/schemas/api__domain__usage__entities__EnvironmentalImpacts","default":{"kWh":0,"kgCO2eq":0}}},"additionalProperties":true,"type":"object","title":"Usage"},"api__domain__usage__entities__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"}}}} ``` ## The AudioTranscriptionsResponseFormat object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"AudioTranscriptionsResponseFormat":{"type":"string","enum":["json","text","verbose_json","diarized_json","srt","vtt"],"title":"AudioTranscriptionsResponseFormat"}}}} ``` ## The Body\_create\_audio\_transcription\_v1\_audio\_transcriptions\_post object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"Body_create_audio_transcription_v1_audio_transcriptions_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"The audio file object (not file name) to transcribe, in one of these formats: mp3 or wav."},"model":{"type":"string","title":"Model","description":"ID of the model to use. Call `/v1/models` endpoint to get the list of available models, only `automatic-speech-recognition` model type is supported."},"language":{"anyOf":[{"$ref":"#/components/schemas/AudioTranscriptionLanguage"},{"type":"null"}],"description":"The language of the output audio. If the output language is different than the audio language, the audio language will be translated into the output language. Output language must be supplied in ISO-639-1 format (e.g. en, fr) format."},"prompt":{"type":"string","title":"Prompt","description":"An optional text to tell the model what to do with the input audio.","default":""},"response_format":{"$ref":"#/components/schemas/AudioTranscriptionsResponseFormat","description":"The format of the transcript output: `json` (default), `text`, `diarized_json` to return per-segment speaker labels, `srt` or `vtt` for subtitle formats.","default":"json"},"temperature":{"type":"number","maximum":1,"minimum":0,"title":"Temperature","description":"The sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit.","default":0}},"type":"object","required":["file","model"],"title":"Body_create_audio_transcription_v1_audio_transcriptions_post"},"AudioTranscriptionLanguage":{"type":"string","enum":["af","afrikaans","albanian","am","amharic","ar","arabic","armenian","as","assamese","az","azerbaijani","ba","bashkir","basque","be","belarusian","bengali","bg","bn","bo","bosnian","br","breton","bs","bulgarian","burmese","ca","cantonese","castilian","catalan","chinese","croatian","cs","cy","czech","da","danish","de","dutch","el","en","english","es","estonian","et","eu","fa","faroese","fi","finnish","flemish","fo","fr","french","galician","georgian","german","gl","greek","gu","gujarati","ha","haitian","haitian creole","hausa","haw","hawaiian","he","hebrew","hi","hindi","hr","ht","hu","hungarian","hy","icelandic","id","indonesian","is","it","italian","ja","japanese","javanese","jw","ka","kannada","kazakh","khmer","kk","km","kn","ko","korean","la","lao","latin","latvian","lb","letzeburgesch","lingala","lithuanian","ln","lo","lt","luxembourgish","lv","macedonian","malagasy","malay","malayalam","maltese","mandarin","maori","marathi","mg","mi","mk","ml","mn","moldavian","moldovan","mongolian","mr","ms","mt","my","myanmar","ne","nepali","nl","nn","no","norwegian","nynorsk","oc","occitan","pa","panjabi","pashto","persian","pl","polish","portuguese","ps","pt","punjabi","pushto","ro","romanian","ru","russian","sa","sanskrit","sd","serbian","shona","si","sindhi","sinhala","sinhalese","sk","sl","slovak","slovenian","sn","so","somali","spanish","sq","sr","su","sundanese","sv","sw","swahili","swedish","ta","tagalog","tajik","tamil","tatar","te","telugu","tg","th","thai","tibetan","tk","tl","tr","tt","turkish","turkmen","uk","ukrainian","ur","urdu","uz","uzbek","valencian","vi","vietnamese","welsh","yi","yiddish","yo","yoruba","yue","zh"],"title":"AudioTranscriptionLanguage"},"AudioTranscriptionsResponseFormat":{"type":"string","enum":["json","text","verbose_json","diarized_json","srt","vtt"],"title":"AudioTranscriptionsResponseFormat"}}}} ``` ## The CarbonFootprintUsage object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"CarbonFootprintUsage":{"properties":{"kWh":{"$ref":"#/components/schemas/CarbonFootprintUsageKWh","deprecated":true},"kgCO2eq":{"$ref":"#/components/schemas/CarbonFootprintUsageKgCO2eq","deprecated":true}},"additionalProperties":true,"type":"object","title":"CarbonFootprintUsage"},"CarbonFootprintUsageKWh":{"properties":{"min":{"type":"number","title":"Min","description":"Minimum carbon footprint in kWh.","default":0,"deprecated":true},"max":{"type":"number","title":"Max","description":"Maximum carbon footprint in kWh.","default":0,"deprecated":true}},"additionalProperties":true,"type":"object","title":"CarbonFootprintUsageKWh"},"CarbonFootprintUsageKgCO2eq":{"properties":{"min":{"type":"number","title":"Min","description":"Minimum carbon footprint in kgCO2eq (global warming potential).","default":0,"deprecated":true},"max":{"type":"number","title":"Max","description":"Maximum carbon footprint in kgCO2eq (global warming potential).","default":0,"deprecated":true}},"additionalProperties":true,"type":"object","title":"CarbonFootprintUsageKgCO2eq"}}}} ``` ## The CarbonFootprintUsageKWh object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"CarbonFootprintUsageKWh":{"properties":{"min":{"type":"number","title":"Min","description":"Minimum carbon footprint in kWh.","default":0,"deprecated":true},"max":{"type":"number","title":"Max","description":"Maximum carbon footprint in kWh.","default":0,"deprecated":true}},"additionalProperties":true,"type":"object","title":"CarbonFootprintUsageKWh"}}}} ``` ## The CarbonFootprintUsageKgCO2eq object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"CarbonFootprintUsageKgCO2eq":{"properties":{"min":{"type":"number","title":"Min","description":"Minimum carbon footprint in kgCO2eq (global warming potential).","default":0,"deprecated":true},"max":{"type":"number","title":"Max","description":"Maximum carbon footprint in kgCO2eq (global warming potential).","default":0,"deprecated":true}},"additionalProperties":true,"type":"object","title":"CarbonFootprintUsageKgCO2eq"}}}} ``` ## The ChatCompletion object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ChatCompletion":{"properties":{"id":{"type":"string","title":"Id","description":"A unique identifier for the chat completion."},"choices":{"items":{"$ref":"#/components/schemas/openai__types__chat__chat_completion__Choice"},"type":"array","title":"Choices"},"created":{"type":"integer","title":"Created"},"model":{"type":"string","title":"Model"},"object":{"type":"string","const":"chat.completion","title":"Object"},"service_tier":{"anyOf":[{"type":"string","enum":["auto","default","flex","scale","priority"]},{"type":"null"}],"title":"Service Tier"},"system_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Fingerprint"},"usage":{"$ref":"#/components/schemas/api__schemas__usage__Usage","description":"Usage information for the request."}},"additionalProperties":true,"type":"object","required":["choices","created","model","object"],"title":"ChatCompletion"},"openai__types__chat__chat_completion__Choice":{"properties":{"finish_reason":{"type":"string","enum":["stop","length","tool_calls","content_filter","function_call"],"title":"Finish Reason"},"index":{"type":"integer","title":"Index"},"logprobs":{"anyOf":[{"$ref":"#/components/schemas/ChoiceLogprobs"},{"type":"null"}]},"message":{"$ref":"#/components/schemas/ChatCompletionMessage"}},"additionalProperties":true,"type":"object","required":["finish_reason","index","message"],"title":"Choice"},"ChoiceLogprobs":{"properties":{"content":{"anyOf":[{"items":{"$ref":"#/components/schemas/ChatCompletionTokenLogprob"},"type":"array"},{"type":"null"}],"title":"Content"},"refusal":{"anyOf":[{"items":{"$ref":"#/components/schemas/ChatCompletionTokenLogprob"},"type":"array"},{"type":"null"}],"title":"Refusal"}},"additionalProperties":true,"type":"object","title":"ChoiceLogprobs","description":"Log probability information for the choice."},"ChatCompletionTokenLogprob":{"properties":{"token":{"type":"string","title":"Token"},"bytes":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Bytes"},"logprob":{"type":"number","title":"Logprob"},"top_logprobs":{"items":{"$ref":"#/components/schemas/TopLogprob"},"type":"array","title":"Top Logprobs"}},"additionalProperties":true,"type":"object","required":["token","logprob","top_logprobs"],"title":"ChatCompletionTokenLogprob"},"TopLogprob":{"properties":{"token":{"type":"string","title":"Token"},"bytes":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Bytes"},"logprob":{"type":"number","title":"Logprob"}},"additionalProperties":true,"type":"object","required":["token","logprob"],"title":"TopLogprob"},"ChatCompletionMessage":{"properties":{"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content"},"refusal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Refusal"},"role":{"type":"string","const":"assistant","title":"Role"},"annotations":{"anyOf":[{"items":{"$ref":"#/components/schemas/Annotation"},"type":"array"},{"type":"null"}],"title":"Annotations"},"audio":{"anyOf":[{"$ref":"#/components/schemas/ChatCompletionAudio"},{"type":"null"}]},"function_call":{"anyOf":[{"$ref":"#/components/schemas/FunctionCall"},{"type":"null"}]},"tool_calls":{"anyOf":[{"items":{"anyOf":[{"$ref":"#/components/schemas/ChatCompletionMessageFunctionToolCall"},{"$ref":"#/components/schemas/ChatCompletionMessageCustomToolCall"}]},"type":"array"},{"type":"null"}],"title":"Tool Calls"}},"additionalProperties":true,"type":"object","required":["role"],"title":"ChatCompletionMessage","description":"A chat completion message generated by the model."},"Annotation":{"properties":{"type":{"type":"string","const":"url_citation","title":"Type"},"url_citation":{"$ref":"#/components/schemas/AnnotationURLCitation"}},"additionalProperties":true,"type":"object","required":["type","url_citation"],"title":"Annotation","description":"A URL citation when using web search."},"AnnotationURLCitation":{"properties":{"end_index":{"type":"integer","title":"End Index"},"start_index":{"type":"integer","title":"Start Index"},"title":{"type":"string","title":"Title"},"url":{"type":"string","title":"Url"}},"additionalProperties":true,"type":"object","required":["end_index","start_index","title","url"],"title":"AnnotationURLCitation","description":"A URL citation when using web search."},"ChatCompletionAudio":{"properties":{"id":{"type":"string","title":"Id"},"data":{"type":"string","title":"Data"},"expires_at":{"type":"integer","title":"Expires At"},"transcript":{"type":"string","title":"Transcript"}},"additionalProperties":true,"type":"object","required":["id","data","expires_at","transcript"],"title":"ChatCompletionAudio","description":"If the audio output modality is requested, this object contains data\nabout the audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio)."},"FunctionCall":{"properties":{"arguments":{"type":"string","title":"Arguments"},"name":{"type":"string","title":"Name"}},"additionalProperties":true,"type":"object","required":["arguments","name"],"title":"FunctionCall","description":"Deprecated and replaced by `tool_calls`.\n\nThe name and arguments of a function that should be called, as generated by the model."},"ChatCompletionMessageFunctionToolCall":{"properties":{"id":{"type":"string","title":"Id"},"function":{"$ref":"#/components/schemas/Function"},"type":{"type":"string","const":"function","title":"Type"}},"additionalProperties":true,"type":"object","required":["id","function","type"],"title":"ChatCompletionMessageFunctionToolCall","description":"A call to a function tool created by the model."},"Function":{"properties":{"arguments":{"type":"string","title":"Arguments"},"name":{"type":"string","title":"Name"}},"additionalProperties":true,"type":"object","required":["arguments","name"],"title":"Function","description":"The function that the model called."},"ChatCompletionMessageCustomToolCall":{"properties":{"id":{"type":"string","title":"Id"},"custom":{"$ref":"#/components/schemas/Custom"},"type":{"type":"string","const":"custom","title":"Type"}},"additionalProperties":true,"type":"object","required":["id","custom","type"],"title":"ChatCompletionMessageCustomToolCall","description":"A call to a custom tool created by the model."},"Custom":{"properties":{"input":{"type":"string","title":"Input"},"name":{"type":"string","title":"Name"}},"additionalProperties":true,"type":"object","required":["input","name"],"title":"Custom","description":"The custom tool that the model called."},"api__schemas__usage__Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","description":"Number of prompt tokens (e.g. input tokens).","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","description":"Number of completion tokens (e.g. output tokens).","default":0},"total_tokens":{"type":"integer","title":"Total Tokens","description":"Total number of tokens (e.g. input and output tokens).","default":0},"cost":{"type":"number","title":"Cost","description":"Total cost of the request.","default":0},"carbon":{"$ref":"#/components/schemas/CarbonFootprintUsage","deprecated":true},"impacts":{"$ref":"#/components/schemas/api__schemas__usage__EnvironmentalImpacts"},"requests":{"type":"integer","title":"Requests","description":"Number of model requests.","default":0}},"additionalProperties":true,"type":"object","title":"Usage"},"CarbonFootprintUsage":{"properties":{"kWh":{"$ref":"#/components/schemas/CarbonFootprintUsageKWh","deprecated":true},"kgCO2eq":{"$ref":"#/components/schemas/CarbonFootprintUsageKgCO2eq","deprecated":true}},"additionalProperties":true,"type":"object","title":"CarbonFootprintUsage"},"CarbonFootprintUsageKWh":{"properties":{"min":{"type":"number","title":"Min","description":"Minimum carbon footprint in kWh.","default":0,"deprecated":true},"max":{"type":"number","title":"Max","description":"Maximum carbon footprint in kWh.","default":0,"deprecated":true}},"additionalProperties":true,"type":"object","title":"CarbonFootprintUsageKWh"},"CarbonFootprintUsageKgCO2eq":{"properties":{"min":{"type":"number","title":"Min","description":"Minimum carbon footprint in kgCO2eq (global warming potential).","default":0,"deprecated":true},"max":{"type":"number","title":"Max","description":"Maximum carbon footprint in kgCO2eq (global warming potential).","default":0,"deprecated":true}},"additionalProperties":true,"type":"object","title":"CarbonFootprintUsageKgCO2eq"},"api__schemas__usage__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","description":"Carbon footprint in kWh.","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","description":"Carbon footprint in kgCO2eq (global warming potential).","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"}}}} ``` ## The ChatCompletionAudio object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ChatCompletionAudio":{"properties":{"id":{"type":"string","title":"Id"},"data":{"type":"string","title":"Data"},"expires_at":{"type":"integer","title":"Expires At"},"transcript":{"type":"string","title":"Transcript"}},"additionalProperties":true,"type":"object","required":["id","data","expires_at","transcript"],"title":"ChatCompletionAudio","description":"If the audio output modality is requested, this object contains data\nabout the audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio)."}}}} ``` ## The ChatCompletionChunk object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ChatCompletionChunk":{"properties":{"id":{"type":"string","title":"Id"},"choices":{"items":{"$ref":"#/components/schemas/openai__types__chat__chat_completion_chunk__Choice"},"type":"array","title":"Choices"},"created":{"type":"integer","title":"Created"},"model":{"type":"string","title":"Model"},"object":{"type":"string","const":"chat.completion.chunk","title":"Object"},"service_tier":{"anyOf":[{"type":"string","enum":["auto","default","flex","scale","priority"]},{"type":"null"}],"title":"Service Tier"},"system_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Fingerprint"},"usage":{"anyOf":[{"$ref":"#/components/schemas/CompletionUsage"},{"type":"null"}]}},"additionalProperties":true,"type":"object","required":["id","choices","created","model","object"],"title":"ChatCompletionChunk"},"openai__types__chat__chat_completion_chunk__Choice":{"properties":{"delta":{"$ref":"#/components/schemas/ChoiceDelta"},"finish_reason":{"anyOf":[{"type":"string","enum":["stop","length","tool_calls","content_filter","function_call"]},{"type":"null"}],"title":"Finish Reason"},"index":{"type":"integer","title":"Index"},"logprobs":{"anyOf":[{"$ref":"#/components/schemas/ChoiceLogprobs"},{"type":"null"}]}},"additionalProperties":true,"type":"object","required":["delta","index"],"title":"Choice"},"ChoiceDelta":{"properties":{"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content"},"function_call":{"anyOf":[{"$ref":"#/components/schemas/ChoiceDeltaFunctionCall"},{"type":"null"}]},"refusal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Refusal"},"role":{"anyOf":[{"type":"string","enum":["developer","system","user","assistant","tool"]},{"type":"null"}],"title":"Role"},"tool_calls":{"anyOf":[{"items":{"$ref":"#/components/schemas/ChoiceDeltaToolCall"},"type":"array"},{"type":"null"}],"title":"Tool Calls"}},"additionalProperties":true,"type":"object","title":"ChoiceDelta","description":"A chat completion delta generated by streamed model responses."},"ChoiceDeltaFunctionCall":{"properties":{"arguments":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arguments"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"}},"additionalProperties":true,"type":"object","title":"ChoiceDeltaFunctionCall","description":"Deprecated and replaced by `tool_calls`.\n\nThe name and arguments of a function that should be called, as generated by the model."},"ChoiceDeltaToolCall":{"properties":{"index":{"type":"integer","title":"Index"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"function":{"anyOf":[{"$ref":"#/components/schemas/ChoiceDeltaToolCallFunction"},{"type":"null"}]},"type":{"anyOf":[{"type":"string","const":"function"},{"type":"null"}],"title":"Type"}},"additionalProperties":true,"type":"object","required":["index"],"title":"ChoiceDeltaToolCall"},"ChoiceDeltaToolCallFunction":{"properties":{"arguments":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arguments"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"}},"additionalProperties":true,"type":"object","title":"ChoiceDeltaToolCallFunction"},"ChoiceLogprobs":{"properties":{"content":{"anyOf":[{"items":{"$ref":"#/components/schemas/ChatCompletionTokenLogprob"},"type":"array"},{"type":"null"}],"title":"Content"},"refusal":{"anyOf":[{"items":{"$ref":"#/components/schemas/ChatCompletionTokenLogprob"},"type":"array"},{"type":"null"}],"title":"Refusal"}},"additionalProperties":true,"type":"object","title":"ChoiceLogprobs","description":"Log probability information for the choice."},"ChatCompletionTokenLogprob":{"properties":{"token":{"type":"string","title":"Token"},"bytes":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Bytes"},"logprob":{"type":"number","title":"Logprob"},"top_logprobs":{"items":{"$ref":"#/components/schemas/TopLogprob"},"type":"array","title":"Top Logprobs"}},"additionalProperties":true,"type":"object","required":["token","logprob","top_logprobs"],"title":"ChatCompletionTokenLogprob"},"TopLogprob":{"properties":{"token":{"type":"string","title":"Token"},"bytes":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Bytes"},"logprob":{"type":"number","title":"Logprob"}},"additionalProperties":true,"type":"object","required":["token","logprob"],"title":"TopLogprob"},"CompletionUsage":{"properties":{"completion_tokens":{"type":"integer","title":"Completion Tokens"},"prompt_tokens":{"type":"integer","title":"Prompt Tokens"},"total_tokens":{"type":"integer","title":"Total Tokens"},"completion_tokens_details":{"anyOf":[{"$ref":"#/components/schemas/CompletionTokensDetails"},{"type":"null"}]},"prompt_tokens_details":{"anyOf":[{"$ref":"#/components/schemas/PromptTokensDetails"},{"type":"null"}]}},"additionalProperties":true,"type":"object","required":["completion_tokens","prompt_tokens","total_tokens"],"title":"CompletionUsage","description":"Usage statistics for the completion request."},"CompletionTokensDetails":{"properties":{"accepted_prediction_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Accepted Prediction Tokens"},"audio_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Audio Tokens"},"reasoning_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reasoning Tokens"},"rejected_prediction_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rejected Prediction Tokens"}},"additionalProperties":true,"type":"object","title":"CompletionTokensDetails","description":"Breakdown of tokens used in a completion."},"PromptTokensDetails":{"properties":{"audio_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Audio Tokens"},"cached_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cached Tokens"}},"additionalProperties":true,"type":"object","title":"PromptTokensDetails","description":"Breakdown of tokens used in the prompt."}}}} ``` ## The ChatCompletionContentPartImageParam object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ChatCompletionContentPartImageParam":{"properties":{"image_url":{"$ref":"#/components/schemas/openai__types__chat__chat_completion_content_part_image_param__ImageURL"},"type":{"type":"string","const":"image_url","title":"Type"}},"additionalProperties":true,"type":"object","required":["image_url","type"],"title":"ChatCompletionContentPartImageParam","description":"Learn about [image inputs](https://platform.openai.com/docs/guides/vision)."},"openai__types__chat__chat_completion_content_part_image_param__ImageURL":{"properties":{"url":{"type":"string","title":"Url"},"detail":{"type":"string","enum":["auto","low","high"],"title":"Detail"}},"additionalProperties":true,"type":"object","required":["url"],"title":"ImageURL"}}}} ``` ## The ChatCompletionContentPartInputAudioParam object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ChatCompletionContentPartInputAudioParam":{"properties":{"input_audio":{"$ref":"#/components/schemas/InputAudio"},"type":{"type":"string","const":"input_audio","title":"Type"}},"additionalProperties":true,"type":"object","required":["input_audio","type"],"title":"ChatCompletionContentPartInputAudioParam","description":"Learn about [audio inputs](https://platform.openai.com/docs/guides/audio)."},"InputAudio":{"properties":{"data":{"type":"string","title":"Data"},"format":{"type":"string","enum":["wav","mp3"],"title":"Format"}},"additionalProperties":true,"type":"object","required":["data","format"],"title":"InputAudio"}}}} ``` ## The ChatCompletionContentPartTextParam object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ChatCompletionContentPartTextParam":{"properties":{"text":{"type":"string","title":"Text"},"type":{"type":"string","const":"text","title":"Type"}},"additionalProperties":true,"type":"object","required":["text","type"],"title":"ChatCompletionContentPartTextParam","description":"Learn about [text inputs](https://platform.openai.com/docs/guides/text-generation)."}}}} ``` ## The ChatCompletionMessage object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ChatCompletionMessage":{"properties":{"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content"},"refusal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Refusal"},"role":{"type":"string","const":"assistant","title":"Role"},"annotations":{"anyOf":[{"items":{"$ref":"#/components/schemas/Annotation"},"type":"array"},{"type":"null"}],"title":"Annotations"},"audio":{"anyOf":[{"$ref":"#/components/schemas/ChatCompletionAudio"},{"type":"null"}]},"function_call":{"anyOf":[{"$ref":"#/components/schemas/FunctionCall"},{"type":"null"}]},"tool_calls":{"anyOf":[{"items":{"anyOf":[{"$ref":"#/components/schemas/ChatCompletionMessageFunctionToolCall"},{"$ref":"#/components/schemas/ChatCompletionMessageCustomToolCall"}]},"type":"array"},{"type":"null"}],"title":"Tool Calls"}},"additionalProperties":true,"type":"object","required":["role"],"title":"ChatCompletionMessage","description":"A chat completion message generated by the model."},"Annotation":{"properties":{"type":{"type":"string","const":"url_citation","title":"Type"},"url_citation":{"$ref":"#/components/schemas/AnnotationURLCitation"}},"additionalProperties":true,"type":"object","required":["type","url_citation"],"title":"Annotation","description":"A URL citation when using web search."},"AnnotationURLCitation":{"properties":{"end_index":{"type":"integer","title":"End Index"},"start_index":{"type":"integer","title":"Start Index"},"title":{"type":"string","title":"Title"},"url":{"type":"string","title":"Url"}},"additionalProperties":true,"type":"object","required":["end_index","start_index","title","url"],"title":"AnnotationURLCitation","description":"A URL citation when using web search."},"ChatCompletionAudio":{"properties":{"id":{"type":"string","title":"Id"},"data":{"type":"string","title":"Data"},"expires_at":{"type":"integer","title":"Expires At"},"transcript":{"type":"string","title":"Transcript"}},"additionalProperties":true,"type":"object","required":["id","data","expires_at","transcript"],"title":"ChatCompletionAudio","description":"If the audio output modality is requested, this object contains data\nabout the audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio)."},"FunctionCall":{"properties":{"arguments":{"type":"string","title":"Arguments"},"name":{"type":"string","title":"Name"}},"additionalProperties":true,"type":"object","required":["arguments","name"],"title":"FunctionCall","description":"Deprecated and replaced by `tool_calls`.\n\nThe name and arguments of a function that should be called, as generated by the model."},"ChatCompletionMessageFunctionToolCall":{"properties":{"id":{"type":"string","title":"Id"},"function":{"$ref":"#/components/schemas/Function"},"type":{"type":"string","const":"function","title":"Type"}},"additionalProperties":true,"type":"object","required":["id","function","type"],"title":"ChatCompletionMessageFunctionToolCall","description":"A call to a function tool created by the model."},"Function":{"properties":{"arguments":{"type":"string","title":"Arguments"},"name":{"type":"string","title":"Name"}},"additionalProperties":true,"type":"object","required":["arguments","name"],"title":"Function","description":"The function that the model called."},"ChatCompletionMessageCustomToolCall":{"properties":{"id":{"type":"string","title":"Id"},"custom":{"$ref":"#/components/schemas/Custom"},"type":{"type":"string","const":"custom","title":"Type"}},"additionalProperties":true,"type":"object","required":["id","custom","type"],"title":"ChatCompletionMessageCustomToolCall","description":"A call to a custom tool created by the model."},"Custom":{"properties":{"input":{"type":"string","title":"Input"},"name":{"type":"string","title":"Name"}},"additionalProperties":true,"type":"object","required":["input","name"],"title":"Custom","description":"The custom tool that the model called."}}}} ``` ## The ChatCompletionMessageCustomToolCall object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ChatCompletionMessageCustomToolCall":{"properties":{"id":{"type":"string","title":"Id"},"custom":{"$ref":"#/components/schemas/Custom"},"type":{"type":"string","const":"custom","title":"Type"}},"additionalProperties":true,"type":"object","required":["id","custom","type"],"title":"ChatCompletionMessageCustomToolCall","description":"A call to a custom tool created by the model."},"Custom":{"properties":{"input":{"type":"string","title":"Input"},"name":{"type":"string","title":"Name"}},"additionalProperties":true,"type":"object","required":["input","name"],"title":"Custom","description":"The custom tool that the model called."}}}} ``` ## The ChatCompletionMessageFunctionToolCall object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ChatCompletionMessageFunctionToolCall":{"properties":{"id":{"type":"string","title":"Id"},"function":{"$ref":"#/components/schemas/Function"},"type":{"type":"string","const":"function","title":"Type"}},"additionalProperties":true,"type":"object","required":["id","function","type"],"title":"ChatCompletionMessageFunctionToolCall","description":"A call to a function tool created by the model."},"Function":{"properties":{"arguments":{"type":"string","title":"Arguments"},"name":{"type":"string","title":"Name"}},"additionalProperties":true,"type":"object","required":["arguments","name"],"title":"Function","description":"The function that the model called."}}}} ``` ## The ChatCompletionTokenLogprob object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ChatCompletionTokenLogprob":{"properties":{"token":{"type":"string","title":"Token"},"bytes":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Bytes"},"logprob":{"type":"number","title":"Logprob"},"top_logprobs":{"items":{"$ref":"#/components/schemas/TopLogprob"},"type":"array","title":"Top Logprobs"}},"additionalProperties":true,"type":"object","required":["token","logprob","top_logprobs"],"title":"ChatCompletionTokenLogprob"},"TopLogprob":{"properties":{"token":{"type":"string","title":"Token"},"bytes":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Bytes"},"logprob":{"type":"number","title":"Logprob"}},"additionalProperties":true,"type":"object","required":["token","logprob"],"title":"TopLogprob"}}}} ``` ## The ChoiceDelta object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ChoiceDelta":{"properties":{"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content"},"function_call":{"anyOf":[{"$ref":"#/components/schemas/ChoiceDeltaFunctionCall"},{"type":"null"}]},"refusal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Refusal"},"role":{"anyOf":[{"type":"string","enum":["developer","system","user","assistant","tool"]},{"type":"null"}],"title":"Role"},"tool_calls":{"anyOf":[{"items":{"$ref":"#/components/schemas/ChoiceDeltaToolCall"},"type":"array"},{"type":"null"}],"title":"Tool Calls"}},"additionalProperties":true,"type":"object","title":"ChoiceDelta","description":"A chat completion delta generated by streamed model responses."},"ChoiceDeltaFunctionCall":{"properties":{"arguments":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arguments"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"}},"additionalProperties":true,"type":"object","title":"ChoiceDeltaFunctionCall","description":"Deprecated and replaced by `tool_calls`.\n\nThe name and arguments of a function that should be called, as generated by the model."},"ChoiceDeltaToolCall":{"properties":{"index":{"type":"integer","title":"Index"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"function":{"anyOf":[{"$ref":"#/components/schemas/ChoiceDeltaToolCallFunction"},{"type":"null"}]},"type":{"anyOf":[{"type":"string","const":"function"},{"type":"null"}],"title":"Type"}},"additionalProperties":true,"type":"object","required":["index"],"title":"ChoiceDeltaToolCall"},"ChoiceDeltaToolCallFunction":{"properties":{"arguments":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arguments"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"}},"additionalProperties":true,"type":"object","title":"ChoiceDeltaToolCallFunction"}}}} ``` ## The ChoiceDeltaFunctionCall object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ChoiceDeltaFunctionCall":{"properties":{"arguments":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arguments"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"}},"additionalProperties":true,"type":"object","title":"ChoiceDeltaFunctionCall","description":"Deprecated and replaced by `tool_calls`.\n\nThe name and arguments of a function that should be called, as generated by the model."}}}} ``` ## The ChoiceDeltaToolCall object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ChoiceDeltaToolCall":{"properties":{"index":{"type":"integer","title":"Index"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"function":{"anyOf":[{"$ref":"#/components/schemas/ChoiceDeltaToolCallFunction"},{"type":"null"}]},"type":{"anyOf":[{"type":"string","const":"function"},{"type":"null"}],"title":"Type"}},"additionalProperties":true,"type":"object","required":["index"],"title":"ChoiceDeltaToolCall"},"ChoiceDeltaToolCallFunction":{"properties":{"arguments":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arguments"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"}},"additionalProperties":true,"type":"object","title":"ChoiceDeltaToolCallFunction"}}}} ``` ## The ChoiceDeltaToolCallFunction object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ChoiceDeltaToolCallFunction":{"properties":{"arguments":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arguments"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"}},"additionalProperties":true,"type":"object","title":"ChoiceDeltaToolCallFunction"}}}} ``` ## The ChoiceLogprobs object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ChoiceLogprobs":{"properties":{"content":{"anyOf":[{"items":{"$ref":"#/components/schemas/ChatCompletionTokenLogprob"},"type":"array"},{"type":"null"}],"title":"Content"},"refusal":{"anyOf":[{"items":{"$ref":"#/components/schemas/ChatCompletionTokenLogprob"},"type":"array"},{"type":"null"}],"title":"Refusal"}},"additionalProperties":true,"type":"object","title":"ChoiceLogprobs","description":"Log probability information for the choice."},"ChatCompletionTokenLogprob":{"properties":{"token":{"type":"string","title":"Token"},"bytes":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Bytes"},"logprob":{"type":"number","title":"Logprob"},"top_logprobs":{"items":{"$ref":"#/components/schemas/TopLogprob"},"type":"array","title":"Top Logprobs"}},"additionalProperties":true,"type":"object","required":["token","logprob","top_logprobs"],"title":"ChatCompletionTokenLogprob"},"TopLogprob":{"properties":{"token":{"type":"string","title":"Token"},"bytes":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Bytes"},"logprob":{"type":"number","title":"Logprob"}},"additionalProperties":true,"type":"object","required":["token","logprob"],"title":"TopLogprob"}}}} ``` ## The CompletionTokensDetails object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"CompletionTokensDetails":{"properties":{"accepted_prediction_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Accepted Prediction Tokens"},"audio_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Audio Tokens"},"reasoning_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reasoning Tokens"},"rejected_prediction_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rejected Prediction Tokens"}},"additionalProperties":true,"type":"object","title":"CompletionTokensDetails","description":"Breakdown of tokens used in a completion."}}}} ``` ## The CompletionUsage object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"CompletionUsage":{"properties":{"completion_tokens":{"type":"integer","title":"Completion Tokens"},"prompt_tokens":{"type":"integer","title":"Prompt Tokens"},"total_tokens":{"type":"integer","title":"Total Tokens"},"completion_tokens_details":{"anyOf":[{"$ref":"#/components/schemas/CompletionTokensDetails"},{"type":"null"}]},"prompt_tokens_details":{"anyOf":[{"$ref":"#/components/schemas/PromptTokensDetails"},{"type":"null"}]}},"additionalProperties":true,"type":"object","required":["completion_tokens","prompt_tokens","total_tokens"],"title":"CompletionUsage","description":"Usage statistics for the completion request."},"CompletionTokensDetails":{"properties":{"accepted_prediction_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Accepted Prediction Tokens"},"audio_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Audio Tokens"},"reasoning_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reasoning Tokens"},"rejected_prediction_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rejected Prediction Tokens"}},"additionalProperties":true,"type":"object","title":"CompletionTokensDetails","description":"Breakdown of tokens used in a completion."},"PromptTokensDetails":{"properties":{"audio_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Audio Tokens"},"cached_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cached Tokens"}},"additionalProperties":true,"type":"object","title":"PromptTokensDetails","description":"Breakdown of tokens used in the prompt."}}}} ``` ## The CreateChatCompletion object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"CreateChatCompletion":{"properties":{"messages":{"items":{},"type":"array","title":"Messages","description":"A list of messages comprising the conversation so far."},"model":{"type":"string","title":"Model","description":"ID of the model to use. Call `/v1/models` endpoint to get the list of available models, only `text-generation` model type is supported."},"frequency_penalty":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Frequency Penalty","description":"Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.","default":0},"logit_bias":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"title":"Logit Bias","description":"Modify the likelihood of specified tokens appearing in the completion. Accepts a JSON object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token."},"logprobs":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Logprobs","description":"Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the `content` of `message`.","default":false},"top_logprobs":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top Logprobs","description":"An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. `logprobs` must be set to `true` if this parameter is used."},"presence_penalty":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Presence Penalty","description":"Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.","default":0},"max_completion_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Completion Tokens","description":"An upper bound for the number of tokens that can be generated for a completion."},"n":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"N","description":"How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep `n` as `1` to minimize costs.","default":1},"response_format":{"anyOf":[{},{"type":"null"}],"title":"Response Format","description":"Setting to `{ \"type\": \"json_schema\", \"json_schema\": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the Structured Outputs guide. Setting to `{ \"type\": \"json_object\" }` enables JSON mode, which ensures the message the model generates is valid JSON.
**Important**: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly \"stuck\" request. Also note that the message content may be partially cut off if `finish_reason=\"length\"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length."},"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Seed","description":"If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result. Determinism is not guaranteed, and you should refer to the system_fingerprint response parameter to monitor changes in the backend."},"stop":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Stop","description":"Up to 4 sequences where the API will stop generating further tokens."},"stream":{"anyOf":[{"type":"boolean","enum":[true,false]},{"type":"null"}],"title":"Stream","description":"If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a data: [DONE] message.","default":false},"stream_options":{"anyOf":[{},{"type":"null"}],"title":"Stream Options","description":"Options for streaming response. Only set this when you set `stream: true`."},"temperature":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Temperature","description":"What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both."},"top_p":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Top P","description":"An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.
We generally recommend altering this or `temperature` but not both."},"tools":{"anyOf":[{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"description":"A list of tools the model may call. Currently, only functions are supported as a tool."},{"type":"null"}],"title":"Tools"},"tool_choice":{"title":"Tool Choice","description":"Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools. Specifying a particular tool via `{\"type\": \"function\", \"function\": {\"name\": \"my_function\"}}` forces the model to call that tool.
`none` is the default when no tools are present. `auto` is the default if tools are present.","default":"none"},"parallel_tool_calls":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Parallel Tool Calls","description":"Whether to call tools in parallel or sequentially. If true, the model will call tools in parallel. If false, the model will call tools sequentially. If None, the model will call tools in parallel if the model supports it, otherwise it will call tools sequentially.","default":false},"user":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User","description":"A unique identifier representing the user."}},"additionalProperties":true,"type":"object","required":["messages","model"],"title":"CreateChatCompletion"}}}} ``` ## The CreateEmbeddingsBody object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"CreateEmbeddingsBody":{"properties":{"model":{"type":"string","minLength":1,"title":"Model","description":"ID of the model to use. Call `/v1/models` endpoint to get the list of available models, only `text-embeddings-inference` model type is supported."},"input":{"anyOf":[{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"items":{"items":{"type":"integer"},"type":"array","minItems":1},"type":"array"},{"type":"string"},{"items":{"type":"string"},"type":"array"}],"minLength":1},{"type":"null"}],"title":"Input","description":"Input text to embed, encoded as a string or array of tokens. To embed multiple inputs in a single request, pass an array of strings or array of token arrays. The input must not exceed the max input tokens for the model (call `/v1/models` endpoint to get the `max_context_length` by model) and cannot be an empty string."},"dimensions":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}],"title":"Dimensions","description":"The number of dimensions the resulting output embeddings should have."},"encoding_format":{"$ref":"#/components/schemas/EncodingFormat","description":"The format of the output embeddings.","default":"float"}},"additionalProperties":true,"type":"object","required":["model"],"title":"CreateEmbeddingsBody"},"EncodingFormat":{"type":"string","enum":["float","base64"],"title":"EncodingFormat"}}}} ``` ## The CreateKeyBody object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"CreateKeyBody":{"properties":{"name":{"type":"string","minLength":1,"title":"Name","description":"Name of the key."},"expires":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires","description":"Expiration time, as Unix timestamp. If None, uses the configured maximum key lifetime when set, otherwise the key never expires."}},"additionalProperties":true,"type":"object","required":["name"],"title":"CreateKeyBody"}}}} ``` ## The CreateOCRBody object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"CreateOCRBody":{"properties":{"bbox_annotation_format":{"anyOf":[{"$ref":"#/components/schemas/ResponseFormat"},{"type":"null"}],"description":"Specify the format that the model must output for the bounding boxes. By default it will use `{ \"type\": \"text\" }`. Setting to `{ \"type\": \"json_object\" }` enables JSON mode, which guarantees the message the model generates is in JSON. When using JSON mode you MUST also instruct the model to produce JSON yourself with a system or a user message. Setting to `{ \"type\": \"json_schema\" }` enables JSON schema mode, which guarantees the message the model generates is in JSON and follows the schema you provide."},"document":{"anyOf":[{"$ref":"#/components/schemas/DocumentURLChunk"},{"$ref":"#/components/schemas/ImageURLChunk"}],"title":"Document","description":"Document to run OCR on."},"document_annotation_format":{"anyOf":[{"$ref":"#/components/schemas/ResponseFormat"},{"type":"null"}],"description":"Specify the format that the model must output for the document. By default it will use `{ \"type\": \"text\" }`. Setting to `{ \"type\": \"json_object\" }` enables JSON mode, which guarantees the message the model generates is in JSON. When using JSON mode you MUST also instruct the model to produce JSON yourself with a system or a user message. Setting to `{ \"type\": \"json_schema\" }` enables JSON schema mode, which guarantees the message the model generates is in JSON and follows the schema you provide."},"document_annotation_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Annotation Prompt","description":"Optional prompt to guide the model in extracting structured output from the entire document. A document_annotation_format must be provided."},"extract_footer":{"type":"boolean","title":"Extract Footer","description":"Whether to extract the footer of the document.","default":false},"extract_header":{"type":"boolean","title":"Extract Header","description":"Whether to extract the header of the document.","default":false},"image_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Image Limit","description":"Max images to extract"},"image_min_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Image Min Size","description":"Minimum height and width of image to extract"},"include_image_base64":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Include Image Base64","description":"Include image URLs in response"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"The model to use for the OCR, call `/v1/models` endpoint to get the list of available models, only `image-to-text` model type is supported."},"pages":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Pages","description":"Specific pages to process. Accepts a list of integers or a string of comma-separated numbers and ranges (e.g. '0,1,2' or '0-5' or '0,2-4'). Page numbers start from 0."},"table_format":{"anyOf":[{"type":"string","enum":["markdown","html"]},{"type":"null"}],"title":"Table Format","description":"Format for table extraction: 'markdown' (default) or 'html'."}},"additionalProperties":true,"type":"object","required":["document"],"title":"CreateOCRBody"},"ResponseFormat":{"properties":{"type":{"type":"string","enum":["text","json_object","json_schema"],"title":"Type","description":"Specify the format that the model must output. By default it will use `{ \"type\": \"text\" }`. Setting to `{ \"type\": \"json_object\" }` enables JSON mode, which guarantees the message the model generates is in JSON. When using JSON mode you MUST also instruct the model to produce JSON yourself with a system or a user message. Setting to `{ \"type\": \"json_schema\" }` enables JSON schema mode, which guarantees the message the model generates is in JSON and follows the schema you provide.","default":"text"},"json_schema":{"anyOf":[{"$ref":"#/components/schemas/JsonSchema"},{"type":"null"}],"description":"The JSON schema definition. Required when type is 'json_schema'."}},"additionalProperties":true,"type":"object","title":"ResponseFormat"},"JsonSchema":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the JSON schema."},"schema":{"additionalProperties":true,"type":"object","title":"Schema","description":"The JSON schema definition."},"strict":{"type":"boolean","title":"Strict","description":"Whether to use strict mode.","default":false},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional description of the schema."}},"additionalProperties":true,"type":"object","required":["name","schema"],"title":"JsonSchema"},"DocumentURLChunk":{"properties":{"document_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Name","description":"The filename of the document."},"document_url":{"type":"string","title":"Document Url","description":"The URL of the document."},"type":{"type":"string","const":"document_url","title":"Type","description":"The type of the document.","default":"document_url"}},"additionalProperties":true,"type":"object","required":["document_url"],"title":"DocumentURLChunk"},"ImageURLChunk":{"properties":{"image_url":{"anyOf":[{"$ref":"#/components/schemas/api__infrastructure__fastapi__schemas__ocr__ImageURL"},{"type":"string"}],"title":"Image Url","description":"The URL of the image to OCR."},"type":{"type":"string","const":"image_url","title":"Type","description":"The type of the image.","default":"image_url"}},"additionalProperties":true,"type":"object","required":["image_url"],"title":"ImageURLChunk"},"api__infrastructure__fastapi__schemas__ocr__ImageURL":{"properties":{"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"The detail of the image."},"url":{"type":"string","title":"Url","description":"The URL of the image."}},"additionalProperties":true,"type":"object","required":["url"],"title":"ImageURL"}}}} ``` ## The CreateRerankBody object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"CreateRerankBody":{"properties":{"query":{"type":"string","minLength":1,"title":"Query","description":"The search query to use for the reranking. `query` and `prompt` cannot both be provided."},"documents":{"items":{"type":"string","minLength":1},"type":"array","title":"Documents"},"model":{"type":"string","minLength":1,"title":"Model","description":"The model to use for the reranking, call `/v1/models` endpoint to get the list of available models, only `text-classification` model type is supported."},"top_n":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Top N","description":"The number of top results to return. If set to None, all results will be returned."}},"additionalProperties":true,"type":"object","required":["query","documents","model"],"title":"CreateRerankBody"}}}} ``` ## The Custom object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"Custom":{"properties":{"input":{"type":"string","title":"Input"},"name":{"type":"string","title":"Name"}},"additionalProperties":true,"type":"object","required":["input","name"],"title":"Custom","description":"The custom tool that the model called."}}}} ``` ## The DocumentURLChunk object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"DocumentURLChunk":{"properties":{"document_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Name","description":"The filename of the document."},"document_url":{"type":"string","title":"Document Url","description":"The URL of the document."},"type":{"type":"string","const":"document_url","title":"Type","description":"The type of the document.","default":"document_url"}},"additionalProperties":true,"type":"object","required":["document_url"],"title":"DocumentURLChunk"}}}} ``` ## The Embedding object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"Embedding":{"properties":{"embedding":{"items":{"type":"number"},"type":"array","title":"Embedding"},"index":{"type":"integer","title":"Index"},"object":{"type":"string","const":"embedding","title":"Object"}},"additionalProperties":true,"type":"object","required":["embedding","index","object"],"title":"Embedding","description":"Represents an embedding vector returned by embedding endpoint."}}}} ``` ## The EmbeddingMessage object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"EmbeddingMessage":{"properties":{"role":{"type":"string","enum":["system","user","assistant","developer","function","tool"],"title":"Role","description":"The role of the message."},"content":{"anyOf":[{"type":"string"},{"items":{"anyOf":[{"$ref":"#/components/schemas/ChatCompletionContentPartTextParam"},{"$ref":"#/components/schemas/ChatCompletionContentPartImageParam"},{"$ref":"#/components/schemas/ChatCompletionContentPartInputAudioParam"},{"$ref":"#/components/schemas/File"}]},"type":"array"}],"title":"Content","description":"The content of the message."}},"additionalProperties":true,"type":"object","required":["role","content"],"title":"EmbeddingMessage"},"ChatCompletionContentPartTextParam":{"properties":{"text":{"type":"string","title":"Text"},"type":{"type":"string","const":"text","title":"Type"}},"additionalProperties":true,"type":"object","required":["text","type"],"title":"ChatCompletionContentPartTextParam","description":"Learn about [text inputs](https://platform.openai.com/docs/guides/text-generation)."},"ChatCompletionContentPartImageParam":{"properties":{"image_url":{"$ref":"#/components/schemas/openai__types__chat__chat_completion_content_part_image_param__ImageURL"},"type":{"type":"string","const":"image_url","title":"Type"}},"additionalProperties":true,"type":"object","required":["image_url","type"],"title":"ChatCompletionContentPartImageParam","description":"Learn about [image inputs](https://platform.openai.com/docs/guides/vision)."},"openai__types__chat__chat_completion_content_part_image_param__ImageURL":{"properties":{"url":{"type":"string","title":"Url"},"detail":{"type":"string","enum":["auto","low","high"],"title":"Detail"}},"additionalProperties":true,"type":"object","required":["url"],"title":"ImageURL"},"ChatCompletionContentPartInputAudioParam":{"properties":{"input_audio":{"$ref":"#/components/schemas/InputAudio"},"type":{"type":"string","const":"input_audio","title":"Type"}},"additionalProperties":true,"type":"object","required":["input_audio","type"],"title":"ChatCompletionContentPartInputAudioParam","description":"Learn about [audio inputs](https://platform.openai.com/docs/guides/audio)."},"InputAudio":{"properties":{"data":{"type":"string","title":"Data"},"format":{"type":"string","enum":["wav","mp3"],"title":"Format"}},"additionalProperties":true,"type":"object","required":["data","format"],"title":"InputAudio"},"File":{"properties":{"file":{"$ref":"#/components/schemas/FileFile"},"type":{"type":"string","const":"file","title":"Type"}},"additionalProperties":true,"type":"object","required":["file","type"],"title":"File","description":"Learn about [file inputs](https://platform.openai.com/docs/guides/text) for text generation."},"FileFile":{"properties":{"file_data":{"type":"string","title":"File Data"},"file_id":{"type":"string","title":"File Id"},"filename":{"type":"string","title":"Filename"}},"additionalProperties":true,"type":"object","title":"FileFile"}}}} ``` ## The EmbeddingsResponse object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"EmbeddingsResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Embedding"},"type":"array","title":"Data"},"model":{"type":"string","title":"Model"},"object":{"type":"string","const":"list","title":"Object","description":"The type of object returned.","default":"list"},"usage":{"$ref":"#/components/schemas/api__domain__usage__entities__Usage","description":"Usage information for the request."},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"A unique identifier for the request."}},"additionalProperties":true,"type":"object","required":["data","model"],"title":"EmbeddingsResponse"},"Embedding":{"properties":{"embedding":{"items":{"type":"number"},"type":"array","title":"Embedding"},"index":{"type":"integer","title":"Index"},"object":{"type":"string","const":"embedding","title":"Object"}},"additionalProperties":true,"type":"object","required":["embedding","index","object"],"title":"Embedding","description":"Represents an embedding vector returned by embedding endpoint."},"api__domain__usage__entities__Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","default":0},"total_tokens":{"type":"integer","title":"Total Tokens","default":0},"cost":{"type":"number","title":"Cost","default":0},"impacts":{"$ref":"#/components/schemas/api__domain__usage__entities__EnvironmentalImpacts","default":{"kWh":0,"kgCO2eq":0}}},"additionalProperties":true,"type":"object","title":"Usage"},"api__domain__usage__entities__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"}}}} ``` ## The EncodingFormat object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"EncodingFormat":{"type":"string","enum":["float","base64"],"title":"EncodingFormat"}}}} ``` ## The EndpointUsage object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"EndpointUsage":{"type":"string","enum":["/v1/audio/transcriptions","/v1/chat/completions","/v1/embeddings","/v1/ocr","/v1/rerank","/v1/search"],"title":"EndpointUsage"}}}} ``` ## The File object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"File":{"properties":{"file":{"$ref":"#/components/schemas/FileFile"},"type":{"type":"string","const":"file","title":"Type"}},"additionalProperties":true,"type":"object","required":["file","type"],"title":"File","description":"Learn about [file inputs](https://platform.openai.com/docs/guides/text) for text generation."},"FileFile":{"properties":{"file_data":{"type":"string","title":"File Data"},"file_id":{"type":"string","title":"File Id"},"filename":{"type":"string","title":"Filename"}},"additionalProperties":true,"type":"object","title":"FileFile"}}}} ``` ## The FileFile object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"FileFile":{"properties":{"file_data":{"type":"string","title":"File Data"},"file_id":{"type":"string","title":"File Id"},"filename":{"type":"string","title":"Filename"}},"additionalProperties":true,"type":"object","title":"FileFile"}}}} ``` ## The Function object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"Function":{"properties":{"arguments":{"type":"string","title":"Arguments"},"name":{"type":"string","title":"Name"}},"additionalProperties":true,"type":"object","required":["arguments","name"],"title":"Function","description":"The function that the model called."}}}} ``` ## The FunctionCall object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"FunctionCall":{"properties":{"arguments":{"type":"string","title":"Arguments"},"name":{"type":"string","title":"Name"}},"additionalProperties":true,"type":"object","required":["arguments","name"],"title":"FunctionCall","description":"Deprecated and replaced by `tool_calls`.\n\nThe name and arguments of a function that should be called, as generated by the model."}}}} ``` ## The ImageURLChunk object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ImageURLChunk":{"properties":{"image_url":{"anyOf":[{"$ref":"#/components/schemas/api__infrastructure__fastapi__schemas__ocr__ImageURL"},{"type":"string"}],"title":"Image Url","description":"The URL of the image to OCR."},"type":{"type":"string","const":"image_url","title":"Type","description":"The type of the image.","default":"image_url"}},"additionalProperties":true,"type":"object","required":["image_url"],"title":"ImageURLChunk"},"api__infrastructure__fastapi__schemas__ocr__ImageURL":{"properties":{"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"The detail of the image."},"url":{"type":"string","title":"Url","description":"The URL of the image."}},"additionalProperties":true,"type":"object","required":["url"],"title":"ImageURL"}}}} ``` ## The InputAudio object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"InputAudio":{"properties":{"data":{"type":"string","title":"Data"},"format":{"type":"string","enum":["wav","mp3"],"title":"Format"}},"additionalProperties":true,"type":"object","required":["data","format"],"title":"InputAudio"}}}} ``` ## The JsonSchema object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"JsonSchema":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the JSON schema."},"schema":{"additionalProperties":true,"type":"object","title":"Schema","description":"The JSON schema definition."},"strict":{"type":"boolean","title":"Strict","description":"Whether to use strict mode.","default":false},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional description of the schema."}},"additionalProperties":true,"type":"object","required":["name","schema"],"title":"JsonSchema"}}}} ``` ## The KeyResponse object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"KeyResponse":{"properties":{"object":{"type":"string","const":"key","title":"Object","description":"Type of the object.","default":"key"},"id":{"type":"integer","title":"Id","description":"ID of the key."},"name":{"type":"string","title":"Name","description":"Name of the key."},"value":{"type":"string","title":"Value","description":"Value of the key."},"user":{"type":"integer","title":"User","description":"ID of the user that owns the key."},"expires":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires","description":"Time of expiration, as Unix timestamp. If None, the key never expires."},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."}},"additionalProperties":true,"type":"object","required":["id","name","value","user","created"],"title":"KeyResponse"}}}} ``` ## The KeysResponse object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"KeysResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Type of the object.","default":"list"},"total":{"type":"integer","title":"Total","description":"Total number of keys."},"offset":{"type":"integer","title":"Offset","description":"Offset of the keys list."},"limit":{"type":"integer","title":"Limit","description":"Limit of the keys list."},"data":{"items":{"$ref":"#/components/schemas/KeyResponse"},"type":"array","title":"Data","description":"List of keys."}},"additionalProperties":true,"type":"object","required":["total","offset","limit","data"],"title":"KeysResponse"},"KeyResponse":{"properties":{"object":{"type":"string","const":"key","title":"Object","description":"Type of the object.","default":"key"},"id":{"type":"integer","title":"Id","description":"ID of the key."},"name":{"type":"string","title":"Name","description":"Name of the key."},"value":{"type":"string","title":"Value","description":"Value of the key."},"user":{"type":"integer","title":"User","description":"ID of the user that owns the key."},"expires":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires","description":"Time of expiration, as Unix timestamp. If None, the key never expires."},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."}},"additionalProperties":true,"type":"object","required":["id","name","value","user","created"],"title":"KeyResponse"}}}} ``` ## The Limit object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"Limit":{"properties":{"router_id":{"type":"integer","title":"Router Id","description":"The router ID."},"type":{"$ref":"#/components/schemas/LimitType","description":"The limit type."},"value":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Value","description":"The limit value."}},"additionalProperties":true,"type":"object","required":["router_id","type"],"title":"Limit"},"LimitType":{"type":"string","enum":["tpm","tpd","rpm","rpd"],"title":"LimitType"}}}} ``` ## The LimitType object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"LimitType":{"type":"string","enum":["tpm","tpd","rpm","rpd"],"title":"LimitType"}}}} ``` ## The MeResponse object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"MeResponse":{"properties":{"object":{"type":"string","const":"userInfo","title":"Object","description":"The user info object type.","default":"userInfo"},"id":{"type":"integer","title":"Id","description":"The user ID."},"email":{"type":"string","title":"Email","description":"The user email."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"The user name."},"organization_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Organization Id","description":"The user organization ID."},"budget":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Budget","description":"The user budget. If None, the user has unlimited budget."},"permissions":{"items":{"$ref":"#/components/schemas/PermissionType"},"type":"array","title":"Permissions","description":"The user permissions."},"limits":{"items":{"$ref":"#/components/schemas/Limit"},"type":"array","title":"Limits","description":"The user rate limits."},"expires":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires","description":"The user expiration timestamp. If None, the user will never expire."}},"additionalProperties":true,"type":"object","required":["id","email","permissions","limits"],"title":"MeResponse"},"PermissionType":{"type":"string","enum":["admin","read_metric","provide_models"],"title":"PermissionType"},"Limit":{"properties":{"router_id":{"type":"integer","title":"Router Id","description":"The router ID."},"type":{"$ref":"#/components/schemas/LimitType","description":"The limit type."},"value":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Value","description":"The limit value."}},"additionalProperties":true,"type":"object","required":["router_id","type"],"title":"Limit"},"LimitType":{"type":"string","enum":["tpm","tpd","rpm","rpd"],"title":"LimitType"}}}} ``` ## The Model object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"Model":{"properties":{"object":{"type":"string","const":"model","title":"Object","description":"Type of the object.","default":"model"},"id":{"type":"string","title":"Id","description":"The model identifier, which can be referenced in the API endpoints."},"type":{"anyOf":[{"$ref":"#/components/schemas/ModelType"},{"type":"null"}],"description":"The type of the model, which can be used to identify the model type."},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases","description":"Aliases of the model. It will be used to identify the model by users."},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."},"owned_by":{"type":"string","title":"Owned By","description":"The organization that owns the model."},"max_context_length":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Context Length","description":"Maximum amount of tokens a context could contains. Makes sure it is the same for all models."},"costs":{"$ref":"#/components/schemas/ModelCosts","description":"Costs of the model."}},"additionalProperties":true,"type":"object","required":["id","created","owned_by"],"title":"Model"},"ModelType":{"type":"string","enum":["automatic-speech-recognition","image-text-to-text","image-to-text","text-classification","text-embeddings-inference","text-generation"],"title":"ModelType"},"ModelCosts":{"properties":{"prompt_tokens":{"type":"number","minimum":0,"title":"Prompt Tokens","description":"Cost of a million prompt tokens (decrease user budget)","default":0},"completion_tokens":{"type":"number","minimum":0,"title":"Completion Tokens","description":"Cost of a million completion tokens (decrease user budget)","default":0}},"additionalProperties":true,"type":"object","title":"ModelCosts"}}}} ``` ## The ModelCosts object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ModelCosts":{"properties":{"prompt_tokens":{"type":"number","minimum":0,"title":"Prompt Tokens","description":"Cost of a million prompt tokens (decrease user budget)","default":0},"completion_tokens":{"type":"number","minimum":0,"title":"Completion Tokens","description":"Cost of a million completion tokens (decrease user budget)","default":0}},"additionalProperties":true,"type":"object","title":"ModelCosts"}}}} ``` ## The ModelType object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ModelType":{"type":"string","enum":["automatic-speech-recognition","image-text-to-text","image-to-text","text-classification","text-embeddings-inference","text-generation"],"title":"ModelType"}}}} ``` ## The ModelsResponse object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ModelsResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Type of the object.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Model"},"type":"array","title":"Data","description":"List of models."}},"additionalProperties":true,"type":"object","required":["data"],"title":"ModelsResponse"},"Model":{"properties":{"object":{"type":"string","const":"model","title":"Object","description":"Type of the object.","default":"model"},"id":{"type":"string","title":"Id","description":"The model identifier, which can be referenced in the API endpoints."},"type":{"anyOf":[{"$ref":"#/components/schemas/ModelType"},{"type":"null"}],"description":"The type of the model, which can be used to identify the model type."},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases","description":"Aliases of the model. It will be used to identify the model by users."},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."},"owned_by":{"type":"string","title":"Owned By","description":"The organization that owns the model."},"max_context_length":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Context Length","description":"Maximum amount of tokens a context could contains. Makes sure it is the same for all models."},"costs":{"$ref":"#/components/schemas/ModelCosts","description":"Costs of the model."}},"additionalProperties":true,"type":"object","required":["id","created","owned_by"],"title":"Model"},"ModelType":{"type":"string","enum":["automatic-speech-recognition","image-text-to-text","image-to-text","text-classification","text-embeddings-inference","text-generation"],"title":"ModelType"},"ModelCosts":{"properties":{"prompt_tokens":{"type":"number","minimum":0,"title":"Prompt Tokens","description":"Cost of a million prompt tokens (decrease user budget)","default":0},"completion_tokens":{"type":"number","minimum":0,"title":"Completion Tokens","description":"Cost of a million completion tokens (decrease user budget)","default":0}},"additionalProperties":true,"type":"object","title":"ModelCosts"}}}} ``` ## The OCRImageObject object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"OCRImageObject":{"properties":{"bottom_right_x":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bottom Right X","description":"X coordinate of bottom-right corner of the extracted image"},"bottom_right_y":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bottom Right Y","description":"Y coordinate of bottom-right corner of the extracted image"},"id":{"type":"string","title":"Id","description":"Image ID for extracted image in a page"},"image_annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Annotation","description":"Annotation of the extracted image in json str"},"image_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Base64","description":"Base64 string of the extracted image"},"top_left_x":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top Left X","description":"X coordinate of top-left corner of the extracted image"},"top_left_y":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top Left Y","description":"Y coordinate of top-left corner of the extracted image"}},"additionalProperties":true,"type":"object","required":["id"],"title":"OCRImageObject"}}}} ``` ## The OCRPageDimensions object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"OCRPageDimensions":{"properties":{"dpi":{"type":"integer","title":"Dpi","description":"Dots per inch of the page-image"},"height":{"type":"integer","title":"Height","description":"Height of the image in pixels"},"width":{"type":"integer","title":"Width","description":"Width of the image in pixels"}},"additionalProperties":true,"type":"object","required":["dpi","height","width"],"title":"OCRPageDimensions"}}}} ``` ## The OCRPageObject object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"OCRPageObject":{"properties":{"dimensions":{"anyOf":[{"$ref":"#/components/schemas/OCRPageDimensions"},{"type":"null"}],"description":"The dimensions of the PDF Page's screenshot image"},"footer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Footer","description":"The footer of the page, returned when extract_footer is enabled"},"header":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Header","description":"The header of the page, returned when extract_header is enabled"},"hyperlinks":{"items":{"type":"string"},"type":"array","title":"Hyperlinks","description":"The hyperlinks extracted from the page.","default":[]},"images":{"items":{"$ref":"#/components/schemas/OCRImageObject"},"type":"array","title":"Images","description":"List of all extracted images in the page."},"index":{"type":"integer","title":"Index","description":"The page index in a pdf document starting from 0"},"markdown":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Markdown","description":"The markdown string response of the page"},"tables":{"items":{"$ref":"#/components/schemas/OCRTableObject"},"type":"array","title":"Tables","description":"The tables extracted from the page, in the requested table_format.","default":[]}},"additionalProperties":true,"type":"object","required":["images","index"],"title":"OCRPageObject"},"OCRPageDimensions":{"properties":{"dpi":{"type":"integer","title":"Dpi","description":"Dots per inch of the page-image"},"height":{"type":"integer","title":"Height","description":"Height of the image in pixels"},"width":{"type":"integer","title":"Width","description":"Width of the image in pixels"}},"additionalProperties":true,"type":"object","required":["dpi","height","width"],"title":"OCRPageDimensions"},"OCRImageObject":{"properties":{"bottom_right_x":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bottom Right X","description":"X coordinate of bottom-right corner of the extracted image"},"bottom_right_y":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bottom Right Y","description":"Y coordinate of bottom-right corner of the extracted image"},"id":{"type":"string","title":"Id","description":"Image ID for extracted image in a page"},"image_annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Annotation","description":"Annotation of the extracted image in json str"},"image_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Base64","description":"Base64 string of the extracted image"},"top_left_x":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top Left X","description":"X coordinate of top-left corner of the extracted image"},"top_left_y":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top Left Y","description":"Y coordinate of top-left corner of the extracted image"}},"additionalProperties":true,"type":"object","required":["id"],"title":"OCRImageObject"},"OCRTableObject":{"properties":{"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"The content of the extracted table, in the requested table format"},"format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Format","description":"The format of the extracted table: 'markdown' or 'html'"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Table ID for the extracted table in a page"}},"additionalProperties":true,"type":"object","title":"OCRTableObject"}}}} ``` ## The OCRResponse object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"OCRResponse":{"properties":{"document_annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Annotation","description":"Formatted response in the request_format if provided in json str"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"The ID of the OCR request."},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"The model used to generate the OCR."},"pages":{"items":{"$ref":"#/components/schemas/OCRPageObject"},"type":"array","title":"Pages","description":"List of OCR info for pages."},"usage":{"anyOf":[{"$ref":"#/components/schemas/api__domain__usage__entities__Usage"},{"type":"null"}],"description":"Usage information for the request."},"usage_info":{"anyOf":[{"$ref":"#/components/schemas/OCRUsage"},{"type":"null"}],"description":"Usage information for the request."}},"additionalProperties":true,"type":"object","required":["pages"],"title":"OCRResponse"},"OCRPageObject":{"properties":{"dimensions":{"anyOf":[{"$ref":"#/components/schemas/OCRPageDimensions"},{"type":"null"}],"description":"The dimensions of the PDF Page's screenshot image"},"footer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Footer","description":"The footer of the page, returned when extract_footer is enabled"},"header":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Header","description":"The header of the page, returned when extract_header is enabled"},"hyperlinks":{"items":{"type":"string"},"type":"array","title":"Hyperlinks","description":"The hyperlinks extracted from the page.","default":[]},"images":{"items":{"$ref":"#/components/schemas/OCRImageObject"},"type":"array","title":"Images","description":"List of all extracted images in the page."},"index":{"type":"integer","title":"Index","description":"The page index in a pdf document starting from 0"},"markdown":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Markdown","description":"The markdown string response of the page"},"tables":{"items":{"$ref":"#/components/schemas/OCRTableObject"},"type":"array","title":"Tables","description":"The tables extracted from the page, in the requested table_format.","default":[]}},"additionalProperties":true,"type":"object","required":["images","index"],"title":"OCRPageObject"},"OCRPageDimensions":{"properties":{"dpi":{"type":"integer","title":"Dpi","description":"Dots per inch of the page-image"},"height":{"type":"integer","title":"Height","description":"Height of the image in pixels"},"width":{"type":"integer","title":"Width","description":"Width of the image in pixels"}},"additionalProperties":true,"type":"object","required":["dpi","height","width"],"title":"OCRPageDimensions"},"OCRImageObject":{"properties":{"bottom_right_x":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bottom Right X","description":"X coordinate of bottom-right corner of the extracted image"},"bottom_right_y":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bottom Right Y","description":"Y coordinate of bottom-right corner of the extracted image"},"id":{"type":"string","title":"Id","description":"Image ID for extracted image in a page"},"image_annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Annotation","description":"Annotation of the extracted image in json str"},"image_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Base64","description":"Base64 string of the extracted image"},"top_left_x":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top Left X","description":"X coordinate of top-left corner of the extracted image"},"top_left_y":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top Left Y","description":"Y coordinate of top-left corner of the extracted image"}},"additionalProperties":true,"type":"object","required":["id"],"title":"OCRImageObject"},"OCRTableObject":{"properties":{"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"The content of the extracted table, in the requested table format"},"format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Format","description":"The format of the extracted table: 'markdown' or 'html'"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Table ID for the extracted table in a page"}},"additionalProperties":true,"type":"object","title":"OCRTableObject"},"api__domain__usage__entities__Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","default":0},"total_tokens":{"type":"integer","title":"Total Tokens","default":0},"cost":{"type":"number","title":"Cost","default":0},"impacts":{"$ref":"#/components/schemas/api__domain__usage__entities__EnvironmentalImpacts","default":{"kWh":0,"kgCO2eq":0}}},"additionalProperties":true,"type":"object","title":"Usage"},"api__domain__usage__entities__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"},"OCRUsage":{"properties":{"doc_size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Doc Size Bytes","description":"Document size in bytes"},"pages_processed":{"type":"integer","title":"Pages Processed","description":"Number of pages processed"}},"additionalProperties":true,"type":"object","required":["pages_processed"],"title":"OCRUsage"}}}} ``` ## The OCRTableObject object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"OCRTableObject":{"properties":{"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"The content of the extracted table, in the requested table format"},"format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Format","description":"The format of the extracted table: 'markdown' or 'html'"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Table ID for the extracted table in a page"}},"additionalProperties":true,"type":"object","title":"OCRTableObject"}}}} ``` ## The OCRUsage object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"OCRUsage":{"properties":{"doc_size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Doc Size Bytes","description":"Document size in bytes"},"pages_processed":{"type":"integer","title":"Pages Processed","description":"Number of pages processed"}},"additionalProperties":true,"type":"object","required":["pages_processed"],"title":"OCRUsage"}}}} ``` ## The PermissionType object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"PermissionType":{"type":"string","enum":["admin","read_metric","provide_models"],"title":"PermissionType"}}}} ``` ## The PromptTokensDetails object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"PromptTokensDetails":{"properties":{"audio_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Audio Tokens"},"cached_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cached Tokens"}},"additionalProperties":true,"type":"object","title":"PromptTokensDetails","description":"Breakdown of tokens used in the prompt."}}}} ``` ## The RerankResponse object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"RerankResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Type of object.","default":"list"},"id":{"type":"string","title":"Id","description":"A unique identifier for the request."},"results":{"items":{"$ref":"#/components/schemas/RerankResult"},"type":"array","title":"Results","description":"The list of reranked texts."},"model":{"type":"string","title":"Model","description":"The model used to generate the reranking."},"usage":{"$ref":"#/components/schemas/api__domain__usage__entities__Usage","description":"Usage information for the request."}},"additionalProperties":true,"type":"object","required":["id","results","model"],"title":"RerankResponse"},"RerankResult":{"properties":{"relevance_score":{"type":"number","title":"Relevance Score","description":"The relevance score of the reranked text."},"index":{"type":"integer","title":"Index","description":"The index of the reranked text."}},"additionalProperties":true,"type":"object","required":["relevance_score","index"],"title":"RerankResult"},"api__domain__usage__entities__Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","default":0},"total_tokens":{"type":"integer","title":"Total Tokens","default":0},"cost":{"type":"number","title":"Cost","default":0},"impacts":{"$ref":"#/components/schemas/api__domain__usage__entities__EnvironmentalImpacts","default":{"kWh":0,"kgCO2eq":0}}},"additionalProperties":true,"type":"object","title":"Usage"},"api__domain__usage__entities__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"}}}} ``` ## The RerankResult object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"RerankResult":{"properties":{"relevance_score":{"type":"number","title":"Relevance Score","description":"The relevance score of the reranked text."},"index":{"type":"integer","title":"Index","description":"The index of the reranked text."}},"additionalProperties":true,"type":"object","required":["relevance_score","index"],"title":"RerankResult"}}}} ``` ## The ResponseFormat object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"ResponseFormat":{"properties":{"type":{"type":"string","enum":["text","json_object","json_schema"],"title":"Type","description":"Specify the format that the model must output. By default it will use `{ \"type\": \"text\" }`. Setting to `{ \"type\": \"json_object\" }` enables JSON mode, which guarantees the message the model generates is in JSON. When using JSON mode you MUST also instruct the model to produce JSON yourself with a system or a user message. Setting to `{ \"type\": \"json_schema\" }` enables JSON schema mode, which guarantees the message the model generates is in JSON and follows the schema you provide.","default":"text"},"json_schema":{"anyOf":[{"$ref":"#/components/schemas/JsonSchema"},{"type":"null"}],"description":"The JSON schema definition. Required when type is 'json_schema'."}},"additionalProperties":true,"type":"object","title":"ResponseFormat"},"JsonSchema":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the JSON schema."},"schema":{"additionalProperties":true,"type":"object","title":"Schema","description":"The JSON schema definition."},"strict":{"type":"boolean","title":"Strict","description":"Whether to use strict mode.","default":false},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional description of the schema."}},"additionalProperties":true,"type":"object","required":["name","schema"],"title":"JsonSchema"}}}} ``` ## The Segment object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"Segment":{"properties":{"id":{"type":"integer","title":"Id","description":"A unique identifier for the segment."},"type":{"type":"string","title":"Type","description":"The type of the segment.","default":"transcript.text.segment"},"text":{"type":"string","title":"Text","description":"The segment text."},"start":{"type":"number","title":"Start","description":"Start time of the segment in seconds."},"end":{"type":"number","title":"End","description":"End time of the segment in seconds."},"speaker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Speaker","description":"Speaker label assigned by diarization, if available."}},"additionalProperties":true,"type":"object","required":["id","text","start","end"],"title":"Segment"}}}} ``` ## The SortField object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"SortField":{"type":"string","enum":["id","name","created"],"title":"SortField"}}}} ``` ## The SortOrder object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"SortOrder":{"type":"string","enum":["asc","desc"],"title":"SortOrder"}}}} ``` ## The TopLogprob object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"TopLogprob":{"properties":{"token":{"type":"string","title":"Token"},"bytes":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Bytes"},"logprob":{"type":"number","title":"Logprob"}},"additionalProperties":true,"type":"object","required":["token","logprob"],"title":"TopLogprob"}}}} ``` ## The UpdateMeBody object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"UpdateMeBody":{"properties":{"name":{"type":"string","minLength":1,"title":"Name","description":"The user name."},"email":{"type":"string","maxLength":254,"minLength":1,"title":"Email","description":"The user email."},"current_password":{"anyOf":[{"type":"string","maxLength":72,"minLength":6},{"type":"null"}],"title":"Current Password","description":"The current user password. If None, the password is not changed and `password` is ignored."},"password":{"anyOf":[{"type":"string","maxLength":72,"minLength":6},{"type":"null"}],"title":"Password","description":"The new user password. Required when `current_password` is provided. Ignored when `current_password` is None."}},"additionalProperties":true,"type":"object","required":["name","email"],"title":"UpdateMeBody"}}}} ``` ## The UsageDetail object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"UsageDetail":{"properties":{"prompt_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prompt Tokens","description":"Number of prompt tokens (e.g. input tokens)."},"completion_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Completion Tokens","description":"Number of completion tokens (e.g. output tokens)."},"total_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Tokens","description":"Total number of tokens (e.g. input and output tokens)."},"cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost","description":"Total cost of the request."},"impacts":{"$ref":"#/components/schemas/api__infrastructure__fastapi__schemas__usage__EnvironmentalImpacts"}},"additionalProperties":true,"type":"object","title":"UsageDetail"},"api__infrastructure__fastapi__schemas__usage__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","description":"Energy consumption in kWh.","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","description":"Carbon footprint in kgCO2eq (global warming potential).","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"}}}} ``` ## The UsageResponse object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"UsageResponse":{"properties":{"object":{"type":"string","const":"usage","title":"Object","description":"Type of the object.","default":"usage"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"Model used for the request."},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"Key used for the request."},"endpoint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint","description":"Endpoint used for the request."},"usage":{"$ref":"#/components/schemas/UsageDetail"},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."}},"additionalProperties":true,"type":"object","required":["created"],"title":"UsageResponse"},"UsageDetail":{"properties":{"prompt_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prompt Tokens","description":"Number of prompt tokens (e.g. input tokens)."},"completion_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Completion Tokens","description":"Number of completion tokens (e.g. output tokens)."},"total_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Tokens","description":"Total number of tokens (e.g. input and output tokens)."},"cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost","description":"Total cost of the request."},"impacts":{"$ref":"#/components/schemas/api__infrastructure__fastapi__schemas__usage__EnvironmentalImpacts"}},"additionalProperties":true,"type":"object","title":"UsageDetail"},"api__infrastructure__fastapi__schemas__usage__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","description":"Energy consumption in kWh.","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","description":"Carbon footprint in kgCO2eq (global warming potential).","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"}}}} ``` ## The UsagesResponse object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"UsagesResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Type of the object.","default":"list"},"total":{"type":"integer","title":"Total","description":"Total number of usages."},"offset":{"type":"integer","title":"Offset","description":"Offset of the usages list."},"limit":{"type":"integer","title":"Limit","description":"Limit of the usages list."},"data":{"items":{"$ref":"#/components/schemas/UsageResponse"},"type":"array","title":"Data","description":"List of usages."}},"additionalProperties":true,"type":"object","required":["total","offset","limit","data"],"title":"UsagesResponse"},"UsageResponse":{"properties":{"object":{"type":"string","const":"usage","title":"Object","description":"Type of the object.","default":"usage"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"Model used for the request."},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"Key used for the request."},"endpoint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint","description":"Endpoint used for the request."},"usage":{"$ref":"#/components/schemas/UsageDetail"},"created":{"type":"integer","title":"Created","description":"Time of creation, as Unix timestamp."}},"additionalProperties":true,"type":"object","required":["created"],"title":"UsageResponse"},"UsageDetail":{"properties":{"prompt_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prompt Tokens","description":"Number of prompt tokens (e.g. input tokens)."},"completion_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Completion Tokens","description":"Number of completion tokens (e.g. output tokens)."},"total_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Tokens","description":"Total number of tokens (e.g. input and output tokens)."},"cost":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost","description":"Total cost of the request."},"impacts":{"$ref":"#/components/schemas/api__infrastructure__fastapi__schemas__usage__EnvironmentalImpacts"}},"additionalProperties":true,"type":"object","title":"UsageDetail"},"api__infrastructure__fastapi__schemas__usage__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","description":"Energy consumption in kWh.","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","description":"Carbon footprint in kgCO2eq (global warming potential).","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"}}}} ``` ## The api\_\_domain\_\_usage\_\_entities\_\_EnvironmentalImpacts object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"api__domain__usage__entities__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"}}}} ``` ## The api\_\_domain\_\_usage\_\_entities\_\_Usage object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"api__domain__usage__entities__Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","default":0},"total_tokens":{"type":"integer","title":"Total Tokens","default":0},"cost":{"type":"number","title":"Cost","default":0},"impacts":{"$ref":"#/components/schemas/api__domain__usage__entities__EnvironmentalImpacts","default":{"kWh":0,"kgCO2eq":0}}},"additionalProperties":true,"type":"object","title":"Usage"},"api__domain__usage__entities__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"}}}} ``` ## The api\_\_infrastructure\_\_fastapi\_\_documentation\_\_HTTPExceptionModel object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"}}}} ``` ## The api\_\_infrastructure\_\_fastapi\_\_schemas\_\_ocr\_\_ImageURL object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"api__infrastructure__fastapi__schemas__ocr__ImageURL":{"properties":{"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"The detail of the image."},"url":{"type":"string","title":"Url","description":"The URL of the image."}},"additionalProperties":true,"type":"object","required":["url"],"title":"ImageURL"}}}} ``` ## The api\_\_infrastructure\_\_fastapi\_\_schemas\_\_usage\_\_EnvironmentalImpacts object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"api__infrastructure__fastapi__schemas__usage__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","description":"Energy consumption in kWh.","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","description":"Carbon footprint in kgCO2eq (global warming potential).","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"}}}} ``` ## The api\_\_schemas\_\_exception\_\_HTTPExceptionModel object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"api__schemas__exception__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","maximum":599,"minimum":100,"title":"Status Code","description":"HTTP status code to send to the client."},"detail":{"title":"Detail","description":"Any data to be sent to the client in the `detail` key of the JSON response."},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers","description":"Any headers to send to the client in the response."}},"type":"object","required":["status_code","detail","headers"],"title":"HTTPExceptionModel"}}}} ``` ## The api\_\_schemas\_\_usage\_\_EnvironmentalImpacts object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"api__schemas__usage__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","description":"Carbon footprint in kWh.","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","description":"Carbon footprint in kgCO2eq (global warming potential).","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"}}}} ``` ## The api\_\_schemas\_\_usage\_\_Usage object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"api__schemas__usage__Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","description":"Number of prompt tokens (e.g. input tokens).","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","description":"Number of completion tokens (e.g. output tokens).","default":0},"total_tokens":{"type":"integer","title":"Total Tokens","description":"Total number of tokens (e.g. input and output tokens).","default":0},"cost":{"type":"number","title":"Cost","description":"Total cost of the request.","default":0},"carbon":{"$ref":"#/components/schemas/CarbonFootprintUsage","deprecated":true},"impacts":{"$ref":"#/components/schemas/api__schemas__usage__EnvironmentalImpacts"},"requests":{"type":"integer","title":"Requests","description":"Number of model requests.","default":0}},"additionalProperties":true,"type":"object","title":"Usage"},"CarbonFootprintUsage":{"properties":{"kWh":{"$ref":"#/components/schemas/CarbonFootprintUsageKWh","deprecated":true},"kgCO2eq":{"$ref":"#/components/schemas/CarbonFootprintUsageKgCO2eq","deprecated":true}},"additionalProperties":true,"type":"object","title":"CarbonFootprintUsage"},"CarbonFootprintUsageKWh":{"properties":{"min":{"type":"number","title":"Min","description":"Minimum carbon footprint in kWh.","default":0,"deprecated":true},"max":{"type":"number","title":"Max","description":"Maximum carbon footprint in kWh.","default":0,"deprecated":true}},"additionalProperties":true,"type":"object","title":"CarbonFootprintUsageKWh"},"CarbonFootprintUsageKgCO2eq":{"properties":{"min":{"type":"number","title":"Min","description":"Minimum carbon footprint in kgCO2eq (global warming potential).","default":0,"deprecated":true},"max":{"type":"number","title":"Max","description":"Maximum carbon footprint in kgCO2eq (global warming potential).","default":0,"deprecated":true}},"additionalProperties":true,"type":"object","title":"CarbonFootprintUsageKgCO2eq"},"api__schemas__usage__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","description":"Carbon footprint in kWh.","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","description":"Carbon footprint in kgCO2eq (global warming potential).","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"}}}} ``` ## The openai\_\_types\_\_chat\_\_chat\_completion\_\_Choice object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"openai__types__chat__chat_completion__Choice":{"properties":{"finish_reason":{"type":"string","enum":["stop","length","tool_calls","content_filter","function_call"],"title":"Finish Reason"},"index":{"type":"integer","title":"Index"},"logprobs":{"anyOf":[{"$ref":"#/components/schemas/ChoiceLogprobs"},{"type":"null"}]},"message":{"$ref":"#/components/schemas/ChatCompletionMessage"}},"additionalProperties":true,"type":"object","required":["finish_reason","index","message"],"title":"Choice"},"ChoiceLogprobs":{"properties":{"content":{"anyOf":[{"items":{"$ref":"#/components/schemas/ChatCompletionTokenLogprob"},"type":"array"},{"type":"null"}],"title":"Content"},"refusal":{"anyOf":[{"items":{"$ref":"#/components/schemas/ChatCompletionTokenLogprob"},"type":"array"},{"type":"null"}],"title":"Refusal"}},"additionalProperties":true,"type":"object","title":"ChoiceLogprobs","description":"Log probability information for the choice."},"ChatCompletionTokenLogprob":{"properties":{"token":{"type":"string","title":"Token"},"bytes":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Bytes"},"logprob":{"type":"number","title":"Logprob"},"top_logprobs":{"items":{"$ref":"#/components/schemas/TopLogprob"},"type":"array","title":"Top Logprobs"}},"additionalProperties":true,"type":"object","required":["token","logprob","top_logprobs"],"title":"ChatCompletionTokenLogprob"},"TopLogprob":{"properties":{"token":{"type":"string","title":"Token"},"bytes":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Bytes"},"logprob":{"type":"number","title":"Logprob"}},"additionalProperties":true,"type":"object","required":["token","logprob"],"title":"TopLogprob"},"ChatCompletionMessage":{"properties":{"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content"},"refusal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Refusal"},"role":{"type":"string","const":"assistant","title":"Role"},"annotations":{"anyOf":[{"items":{"$ref":"#/components/schemas/Annotation"},"type":"array"},{"type":"null"}],"title":"Annotations"},"audio":{"anyOf":[{"$ref":"#/components/schemas/ChatCompletionAudio"},{"type":"null"}]},"function_call":{"anyOf":[{"$ref":"#/components/schemas/FunctionCall"},{"type":"null"}]},"tool_calls":{"anyOf":[{"items":{"anyOf":[{"$ref":"#/components/schemas/ChatCompletionMessageFunctionToolCall"},{"$ref":"#/components/schemas/ChatCompletionMessageCustomToolCall"}]},"type":"array"},{"type":"null"}],"title":"Tool Calls"}},"additionalProperties":true,"type":"object","required":["role"],"title":"ChatCompletionMessage","description":"A chat completion message generated by the model."},"Annotation":{"properties":{"type":{"type":"string","const":"url_citation","title":"Type"},"url_citation":{"$ref":"#/components/schemas/AnnotationURLCitation"}},"additionalProperties":true,"type":"object","required":["type","url_citation"],"title":"Annotation","description":"A URL citation when using web search."},"AnnotationURLCitation":{"properties":{"end_index":{"type":"integer","title":"End Index"},"start_index":{"type":"integer","title":"Start Index"},"title":{"type":"string","title":"Title"},"url":{"type":"string","title":"Url"}},"additionalProperties":true,"type":"object","required":["end_index","start_index","title","url"],"title":"AnnotationURLCitation","description":"A URL citation when using web search."},"ChatCompletionAudio":{"properties":{"id":{"type":"string","title":"Id"},"data":{"type":"string","title":"Data"},"expires_at":{"type":"integer","title":"Expires At"},"transcript":{"type":"string","title":"Transcript"}},"additionalProperties":true,"type":"object","required":["id","data","expires_at","transcript"],"title":"ChatCompletionAudio","description":"If the audio output modality is requested, this object contains data\nabout the audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio)."},"FunctionCall":{"properties":{"arguments":{"type":"string","title":"Arguments"},"name":{"type":"string","title":"Name"}},"additionalProperties":true,"type":"object","required":["arguments","name"],"title":"FunctionCall","description":"Deprecated and replaced by `tool_calls`.\n\nThe name and arguments of a function that should be called, as generated by the model."},"ChatCompletionMessageFunctionToolCall":{"properties":{"id":{"type":"string","title":"Id"},"function":{"$ref":"#/components/schemas/Function"},"type":{"type":"string","const":"function","title":"Type"}},"additionalProperties":true,"type":"object","required":["id","function","type"],"title":"ChatCompletionMessageFunctionToolCall","description":"A call to a function tool created by the model."},"Function":{"properties":{"arguments":{"type":"string","title":"Arguments"},"name":{"type":"string","title":"Name"}},"additionalProperties":true,"type":"object","required":["arguments","name"],"title":"Function","description":"The function that the model called."},"ChatCompletionMessageCustomToolCall":{"properties":{"id":{"type":"string","title":"Id"},"custom":{"$ref":"#/components/schemas/Custom"},"type":{"type":"string","const":"custom","title":"Type"}},"additionalProperties":true,"type":"object","required":["id","custom","type"],"title":"ChatCompletionMessageCustomToolCall","description":"A call to a custom tool created by the model."},"Custom":{"properties":{"input":{"type":"string","title":"Input"},"name":{"type":"string","title":"Name"}},"additionalProperties":true,"type":"object","required":["input","name"],"title":"Custom","description":"The custom tool that the model called."}}}} ``` ## The openai\_\_types\_\_chat\_\_chat\_completion\_chunk\_\_Choice object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"openai__types__chat__chat_completion_chunk__Choice":{"properties":{"delta":{"$ref":"#/components/schemas/ChoiceDelta"},"finish_reason":{"anyOf":[{"type":"string","enum":["stop","length","tool_calls","content_filter","function_call"]},{"type":"null"}],"title":"Finish Reason"},"index":{"type":"integer","title":"Index"},"logprobs":{"anyOf":[{"$ref":"#/components/schemas/ChoiceLogprobs"},{"type":"null"}]}},"additionalProperties":true,"type":"object","required":["delta","index"],"title":"Choice"},"ChoiceDelta":{"properties":{"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content"},"function_call":{"anyOf":[{"$ref":"#/components/schemas/ChoiceDeltaFunctionCall"},{"type":"null"}]},"refusal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Refusal"},"role":{"anyOf":[{"type":"string","enum":["developer","system","user","assistant","tool"]},{"type":"null"}],"title":"Role"},"tool_calls":{"anyOf":[{"items":{"$ref":"#/components/schemas/ChoiceDeltaToolCall"},"type":"array"},{"type":"null"}],"title":"Tool Calls"}},"additionalProperties":true,"type":"object","title":"ChoiceDelta","description":"A chat completion delta generated by streamed model responses."},"ChoiceDeltaFunctionCall":{"properties":{"arguments":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arguments"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"}},"additionalProperties":true,"type":"object","title":"ChoiceDeltaFunctionCall","description":"Deprecated and replaced by `tool_calls`.\n\nThe name and arguments of a function that should be called, as generated by the model."},"ChoiceDeltaToolCall":{"properties":{"index":{"type":"integer","title":"Index"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"function":{"anyOf":[{"$ref":"#/components/schemas/ChoiceDeltaToolCallFunction"},{"type":"null"}]},"type":{"anyOf":[{"type":"string","const":"function"},{"type":"null"}],"title":"Type"}},"additionalProperties":true,"type":"object","required":["index"],"title":"ChoiceDeltaToolCall"},"ChoiceDeltaToolCallFunction":{"properties":{"arguments":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arguments"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"}},"additionalProperties":true,"type":"object","title":"ChoiceDeltaToolCallFunction"},"ChoiceLogprobs":{"properties":{"content":{"anyOf":[{"items":{"$ref":"#/components/schemas/ChatCompletionTokenLogprob"},"type":"array"},{"type":"null"}],"title":"Content"},"refusal":{"anyOf":[{"items":{"$ref":"#/components/schemas/ChatCompletionTokenLogprob"},"type":"array"},{"type":"null"}],"title":"Refusal"}},"additionalProperties":true,"type":"object","title":"ChoiceLogprobs","description":"Log probability information for the choice."},"ChatCompletionTokenLogprob":{"properties":{"token":{"type":"string","title":"Token"},"bytes":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Bytes"},"logprob":{"type":"number","title":"Logprob"},"top_logprobs":{"items":{"$ref":"#/components/schemas/TopLogprob"},"type":"array","title":"Top Logprobs"}},"additionalProperties":true,"type":"object","required":["token","logprob","top_logprobs"],"title":"ChatCompletionTokenLogprob"},"TopLogprob":{"properties":{"token":{"type":"string","title":"Token"},"bytes":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Bytes"},"logprob":{"type":"number","title":"Logprob"}},"additionalProperties":true,"type":"object","required":["token","logprob"],"title":"TopLogprob"}}}} ``` ## The openai\_\_types\_\_chat\_\_chat\_completion\_content\_part\_image\_param\_\_ImageURL object ```json {"openapi":"3.1.0","info":{"title":"Albert API","version":"0.7.0"},"components":{"schemas":{"openai__types__chat__chat_completion_content_part_image_param__ImageURL":{"properties":{"url":{"type":"string","title":"Url"},"detail":{"type":"string","enum":["auto","low","high"],"title":"Detail"}},"additionalProperties":true,"type":"object","required":["url"],"title":"ImageURL"}}}} ``` # Modèles disponibles Albert API offre l’accès à une large gamme de modèles fondation open source d’IA générative. Nous mettons à jour régulièrement les modèles disponibles pour vous permettre d’utiliser les modèles qui font l’état de l’art. {% hint style="info" %} Chaque modèle est associé à un type de modèle. Pour en savoir plus sur les types de modèles, voir [Types de modèles](/albert-api/modeles/model-types). {% endhint %} Les recommandations d'usage ci-dessous proviennent de l'expérience des utilisateurs et ne sont pas garanties. Nous vous recommandons de tester différents modèles et leurs paramètres pour trouver ceux qui s'adapteront le mieux à vos besoins. Vos retours nous sont précieux pour améliorer les modèles et les recommandations d'usage. N'hésitez pas à nous les partager sur notre canal Tchap ou par mail (voir la page [Contact](https://ia.numerique.gouv.fr/outils-ia/albert-api/albert-api-contact/)).
bge-m3 Model d'embeddings de référence pour la vectorisation de texte. Model card | | | | ----------------------------------- | -------------------------------------- | | **Nombre de paramètres** | 568M | | **Type** | `text-embeddings-inference` | | **Aliases** | `BAAI/bge-m3`, `openweight-embeddings` | | **Licence** | MIT | | **Fenêtre de contexte** | 8192 | | **Dimension maximale des vecteurs** | 1024 | | **Maximum de texte par batch** | 64 | ### Capacités
Text vectorisation/v1/embeddingsEmbeddingsarrow-up-1-9.svg
bge-reranker-v2-m3 Modèle de reranking multilingue basé sur `bge-m3`. Il est le modèle de référence pour le reranking sur Albert API. Model card | | | | ------------------------------ | ---------------------------------------------- | | **Nombre de paramètres** | 568M | | **Type** | `text-classification` | | **Licence** | MIT | | **Aliases** | `BAAI/bge-reranker-v2-m3`, `openweight-rerank` | | **Fenêtre de contexte** | 8192 | | **Maximum de texte par batch** | 64 | {% hint style="success" icon="lightbulb" %} La limite architecturale est de 8192 tokens, toutefois le modèle a été finetuné pour être utilisé avec des textes de longueur maximale de 1024 tokens. Nous recommandons de ne pas dépasser cette longueur lors de la construction des chunks pour le reranking. {% endhint %} ### Capacités
Reranking/v1/rerankingRerankingranking-star.svg
deepseek-v4-flash modèle en expérimentation MoE spécialisé pour les tâches de code. {% hint style="warning" %} Ce modèle est en phase d'expérimentation du 26 juillet 2026 au 1er octobre 2026. Candidat au remplacement du modèle `openweight-code` à l'issue de cette période. Ce modèle extra-européen peut présenter certaines formes de censure des réponses. Nous recommandons de l'utiliser uniquement pour les cas d'usage de génération de code et non comme un modèle conversationnel généraliste. Cette phase d'expérimentation a notamment pour objectif d'évaluer l'impact de ces limitations afin de déterminer si elles sont compatibles avec une intégration pérenne dans Albert API. Vos retours sur ce sujet seront particulièrement précieux. {% endhint %} Model card Essayer dans Playground | | | | ------------------------------- | ------------------------------------ | | **Nombre de paramètres** | 284B | | **Nombre de paramètres actifs** | 13B | | **Licence** | MIT | | **Type** | `text-generation` | | **Aliases** | `deepseek-ai/DeepSeek-V4-Flash-0731` | | **Fenêtre de contexte** |

131072

131072

| | **Température recommandée** | 1.0 | ### Capacités
Code/v1/chat/completionsConnecter un agent de code à Albert APIterminal.svg
Reasoning/v1/chat/completionshttps://github.com/betagouv/doc.albert-api/tree/main/guides/reasoning.mdbrain.svg
Function calling/v1/chat/completionsFunction calling & outilsscrewdriver-wrench.svg
{% hint style="info" icon="screwdriver-wrench" %} **Comportement du function calling** Le paramètre `tool_choice` doit être explicitement défini à `auto` dans la requête pour que les appels d'outils fonctionnent avec ce modèle. Sans cela, le modèle n'émet pas de `tool_calls`, même si des `tools` sont fournis.\ \ Sans le streaming, modèle renvoie un tool call avec un content non vide. En streaming, les arguments sont fragmentés sur plusieurs chunks SSE, et le finish\_reason: "tool\_calls" arrive dans un chunk distinct qui ne contient plus de tool\_calls. {% endhint %}
gemma-4-31b-it modèle en expérimentation Modèle de chat pour des tâches d'une complexité modérée et d'analyse d'images. {% hint style="warning" %} Ce modèle est en phase d'expérimentation du 31 août 2026 au 1er décembre 2026. Candidat au remplacement du modèle `openweight-medium` à l'issue de cette période. A l'issue de cette phase d'expérimentation nous évaluerons a l'aide de vos retours si le modèle est viable pour une intégration pérenne dans Albert API. {% endhint %} Model card Essayer dans Playground | | | | ------------------------------- | ----------------------- | | **Nombre de paramètres** | 30.7B | | **Nombre de paramètres actifs** | 30.7B | | **Licence** | Apache 2.0 | | **Type** | `image-text-to-text` | | **Aliases** | `google/gemma-4-31B-it` | | **Fenêtre de contexte** | 262144 | | **Température recommandée** | 1.0 | ### Capacités
Cover image
Chat/v1/chat/completionsConnecter un agent de code à Albert APImessage.svg
Reasoning/v1/chat/completionshttps://github.com/betagouv/doc.albert-api/tree/main/guides/reasoning.mdbrain.svg
Function calling/v1/chat/completionsFunction calling & outilsscrewdriver-wrench.svg
Analyse d'image/v1/chat/completionseye.svg
{% hint style="info" icon="screwdriver-wrench" %} **Comportement du function calling** Sans le streaming, le modèle renvoie un tool call avec un content vide. En streaming, les arguments sont fragmentés sur plusieurs chunks SSE, et le finish\_reason: "tool\_calls" arrive dans un chunk distinct qui ne contient plus de tool\_calls. {% endhint %} {% hint style="info" icon="brain" %} **Comportement du reasoning** Gemma 4 est un modèle pouvant *raisonner* (`Thinking`). Pour l'activer, il faut fournir cet argument dans le body du payload : `"chat_template_kwargs": {"enable_thinking": true}`. {% endhint %}
gpt-oss-120b MoE généraliste de grande taille pour des tâches de complexes. Model card Essayer dans Playground | | | | ------------------------------- | ----------------------------------------- | | **Nombre de paramètres** | 117B | | **Nombre de paramètres actifs** | 5.1B | | **Type** | `text-generation` | | **Licence** | Apache 2.0 | | **Aliases** | `openai/gpt-oss-120b`, `openweight-large` | | **Fenêtre de contexte** | 131072 | {% hint style="success" icon="lightbulb" %} Les tokens de raisonnement consomment le budget `max_tokens` : prévoyez une marge confortable même pour des réponses courtes (> 1024 tokens). {% endhint %} ### Capacités
Chat/v1/chat/completionsChat completionsmessage.svg
Reasoning/v1/chat/completionshttps://github.com/betagouv/doc.albert-api/tree/main/guides/reasoning.mdbrain.svg
Function calling/v1/chat/completionsFunction calling & outilsscrewdriver-wrench.svg
{% hint style="info" icon="screwdriver-wrench" %} **Comportement du function calling** Sans le streaming, modèle renvoie un tool call avec un content vide. En streaming, les arguments sont fragmentés sur plusieurs chunks SSE, et le finish\_reason: "tool\_calls" arrive dans un chunk distinct qui ne contient plus de tool\_calls. {% endhint %}
lightonocr-2-1b Modèle multimodal spécialisé pour l'OCR. Il est le modèle de référence pour l'OCR sur Albert API. Model card Essayer dans Playground | | | | ------------------------ | -------------------------------------------- | | **Nombre de paramètres** | 1B | | **Licence** | Apache 2.0 | | **Type** | `image-text-to-text` | | **Aliases** | `lighton/LightOn-OCR-2-1B`, `openweight-ocr` | | **Fenêtre de contexte** | 16384 | {% hint style="success" icon="lightbulb" %} Nous observons certaines latences lorsque certains patterns de pixels sont présents dans l'image (un QR code par exemple). Si vous observez des latences élevées, essayez de supprimer ces patterns avant d'envoyer l'image au modèle. {% endhint %} ### Capacités
OCR (chat)/v1/chat/completionsOCRimages.svg
ministral-3-8b-instruct-2512 Modèle multimodal généraliste de petite taille, idéal pour des tâches simples comme de la classification ou de correction de texte. Model card Essayer dans Playground | | | | --------------------------- | ------------------------------------------------------------ | | **Nombre de paramètres** | 8.9B | | **Type** | `image-text-to-text` | | **Licence** | Apache 2.0 | | **Aliases** | `mistralai/Ministral-3-8B-Instruct-2512`, `openweight-small` | | **Format d'entrées** | `text`, `image` | | **Fenêtre de contexte** | 262144 | | **Température recommandée** | 0.1 | ### Capacités
Chat/v1/chat/completionsChat completionsmessage.svg
Analyse d'image/v1/chat/completionsChat completionseye.svg
Function calling/v1/chat/completionsFunction calling & outilsscrewdriver-wrench.svg
{% hint style="info" icon="screwdriver-wrench" %} **Comportement du function calling** Sans le streaming, modèle renvoie un tool call avec un content vide. En streaming, les arguments sont fragmentés sur plusieurs chunks SSE, et le finish\_reason: "tool\_calls" arrive dans un chunk distinct qui ne contient plus de tool\_calls. {% endhint %}
mistral-medium-2508 modèle partenaire {% hint style="warning" %} Ce modèle accessible uniquement aux ministères partenaires qui en font la demande. Pour en savoir plus, consultez la page [Tarifs et limites](https://ia.numerique.gouv.fr/outils-ia/albert-api/tarifs-et-limites/) de notre site. Vous pouvez utiliser le modèle `gpt-oss-120b` comme alternative à ce modèle. {% endhint %} Model card | | | | ------------------------ | --------------------- | | **Nombre de paramètres** | 123B | | **Type** | `image-text-to-text` | | **Licence** | `propriétaire` | | **Aliases** | `mistral-medium-2508` | | **Format d'entrées** | `text`, `image` | | **Fenêtre de contexte** | 131072 | ### Capacités
Chat/v1/chat/completionsChat completionsmessage.svg
Analyse d'image/v1/chat/completionsChat completionseye.svg
Tool calling/v1/chat/completionsFunction calling & outilsscrewdriver-wrench.svg
{% hint style="info" icon="screwdriver-wrench" %} **Comportement du function calling** Sans le streaming, modèle renvoie un tool call avec un content vide. En streaming, quand le tool call est valide, le tool call arrive en un seul chunk qui porte aussi la finish\_reason. {% endhint %}
mistral-ocr-2512 modèle partenaire Modèle d'OCR compatible avec la pile Document AI de Mistral (`/v1/ocr`) permettant d’extraire du texte et des images entremêlés. {% hint style="warning" %} Ce modèle accessible uniquement aux ministères partenaires qui en font la demande. Pour en savoir plus, consultez la page [Tarifs et limites](https://ia.numerique.gouv.fr/outils-ia/albert-api/tarifs-et-limites/) de notre site. Vous pouvez utiliser le modèle `lightonocr-2-1b` comme alternative à ce modèle. {% endhint %} Model card Essayer dans Playground | | | | ------------------------ | ------------------ | | **Nombre de paramètres** | 3B | | **Type** | `image-to-text` | | **Licence** | `propriétaire` | | **Aliases** | `mistral-ocr-2512` | | **Fenêtre de contexte** | 16384 | ### Capacités
Mistral Document AI/v1/ocrhttps://github.com/betagouv/doc.albert-api/tree/main/guides/mistral-document-ai.mdfile-image.svg
mistral-small-3-2-24b-instruct-2506 Modèle de chat pour des tâches d'une complexité modérée et d'analyse d'images. Model card Essayer dans Playground | | | | --------------------------- | -------------------------------------------------------------------- | | **Nombre de paramètres** | 24B | | **Type** | `image-text-to-text` | | **Licence** | Apache 2.0 | | **Aliases** | `mistralai/Mistral-Small-3.2-24B-Instruct-2506`, `openweight-medium` | | **Format d'entrées** | `text`, `image` | | **Fenêtre de contexte** | 131072 | | **Température recommandée** | 0.15 | ### Capacités
Chat/v1/chat/completionsChat completionsmessage.svg
Analyse d'image/v1/chat/completionsChat completionseye.svg
Function calling/v1/chat/completionsFunction calling & outilsscrewdriver-wrench.svg
{% hint style="info" icon="screwdriver-wrench" %} **Comportement du function calling** Sans le streaming, modèle renvoie un tool call avec un content vide. En streaming, les arguments sont fragmentés sur plusieurs chunks SSE, et le finish\_reason: "tool\_calls" arrive dans un chunk distinct qui ne contient plus de tool\_calls. {% endhint %}
qwen3-coder-30b-a3b-instruct Model card Essayer dans Playground | | | | ------------------------------- | ------------------------------------------------------ | | **Nombre de paramètres** | 30.5B | | **Nombre de paramètres actifs** | 3.3B | | **Type** | `text-generation` | | **Licence** | Apache 2.0 | | **Aliases** | `Qwen/Qwen3-Coder-30B-A3B-Instruct`, `openweight-code` | | **Fenêtre de contexte** | 262144 | MoE orienté code / agentic coding (function calling). ### Capacités {% hint style="info" icon="screwdriver-wrench" %} **Comportement du function calling** Sans le streaming, modèle renvoie un tool call avec un content non vide. En streaming, quand le tool call est valide, les arguments sont fragmentés sur plusieurs chunks SSE, et le finish\_reason: "tool\_calls" arrive dans un chunk distinct qui ne contient plus de tool\_calls. {% endhint %}
Code/v1/chat/completionsConnecter un agent de code à Albert APIterminal.svg
Function calling/v1/chat/completionsFunction calling & outilsscrewdriver-wrench.svg
qwen3-vl-embedding-8b modèle en expérimentation Embeddings multimodaux (texte, images, captures d’écran, vidéos). {% hint style="warning" %} Ce modèle est en phase d'expérimentation du 26 juillet 2026 au 1er octobre 2026. A l'issue de cette phase d'expérimentation nous évaluerons a l'aide de vos retours si le modèle est viable pour une intégration pérenne dans Albert API. {% endhint %} Model card | | | | ----------------------------------- | ---------------------------- | | **Nombre de paramètres** | 8B | | **Type** | `text-embeddings-inference` | | **Licence** | Apache 2.0 | | **Aliases** | `Qwen/Qwen3-VL-Embedding-8B` | | **Fenêtre de contexte** | 32768 | | **Dimension maximale des vecteurs** | 4096\* | \*La dimension des vecteurs n'est pas modifiable avec ce modèle. {% hint style="warning" %} Ne mélangez pas les vecteurs générés par ce modèle avec un autre modèle d'embeddings : ils ne sont pas comparables. {% endhint %} ### Capacités
Text vectorisation/v1/embeddingsEmbeddingsarrow-up-1-9.svg
whisper-large-v3 Model card Essayer dans Transcripts | | | | ------------------------ | --------------------------------------------- | | **Nombre de paramètres** | 1.55B | | **Type** | `automatic-speech-recognition` | | **Licence** | Apache 2.0 | | **Aliases** | `openai/whisper-large-v3`, `openweight-audio` | | **Fenêtre de contexte** | Fichier audio jusqu'à 20 MB | ### Capacités
Transcription/v1/audio/transcriptionshttps://github.com/betagouv/doc.albert-api/tree/main/guides/audio-transcriptions.mdmicrophone.svg
Diarization/v1/audio/transcriptionshttps://github.com/betagouv/doc.albert-api/tree/main/guides/audio-transcriptions.mdcomments.svg
## Calendrier des migrations
ModèleSupprimé leRemplacer par
qwen3-coder-30b-a3b-instruct1er octobre 2026deepseek-v4-flash
mistral-small-3-2-24b-instruct-25061er décembre 2026gemma-4-31b-it
# Types de modèles L’énumération **`ModelType`** décrit le rôle d’un modèle exposé par `GET /v1/models`. Le tableau ci-dessous relie chaque valeur aux **endpoints principaux** qui l’utilisent. | `ModelType` | Endpoint(s) typique(s) | Rôle | | ------------------------------ | ------------------------------------------- | ------------------------------------------------------------------ | | `text-generation` | `POST /v1/chat/completions` | Génération de texte conversationnel, outils inclus. | | `text-embeddings-inference` | `POST /v1/embeddings` | Vecteurs de texte pour recherche, clustering, features. | | `text-classification` | `POST /v1/rerank` | Scoring de paires (requête, document) pour réordonnancement. | | `automatic-speech-recognition` | `POST /v1/audio/transcriptions` | Transcription (et éventuelle traduction contrôlée via `language`). | | `image-text-to-text` | `POST /v1/ocr` (selon configuration modèle) | Modèles vision + langage sur documents ou images. | | `image-to-text` | `POST /v1/ocr` (selon configuration modèle) | Spécialisation plus étroite image → texte. | {% hint style="warning" %} ⚠️ À vérifier — Affectation exacte des modèles `image-text-to-text` vs `image-to-text` à l’endpoint OCR et liste blanche par environnement : contrôlez les fiches `Model` retournées par `/v1/models`. {% endhint %} ## Champs utiles sur `Model` * **`max_context_length`** — borne haute **tokens** pour la fenêtre contextuelle ; requis pour dimensionner prompts + complétions ou embeddings massifs. * **`aliases`** — raccourcis acceptés à la place de `id` dans les requêtes. * **`costs`** — objet **`ModelCosts`** : * **`prompt_tokens`** — coût monétaire **par million de tokens** consommés en entrée ; * **`completion_tokens`** — coût **par million de tokens** générés en sortie. Les unités monétaires et la décrementation du **budget** utilisateur dépendent de la politique commerciale / interministerielle appliquée à votre compte. Pour l’exploration dynamique : [Modèles disponibles](/albert-api/modeles/available-models). # Chat completions L’endpoint **`POST /v1/chat/completions`** est le point d’entrée principal pour la génération de texte. Le corps de requête et la réponse s’inspirent du modèle **OpenAI Chat Completions** : `messages`, paramètres de décodage, `response_format`, streaming et outils (`tools` / `tool_calls`). ## Quel type de modèle ? Pour **`POST /v1/chat/completions`**, vous devez utiliser un modèle de type **`text-generation`** (voir [Types de modèles](/albert-api/modeles/model-types)). {% hint style="warning" %} ⚠️ Les anciens tutoriels mélangaient parfois des modèles `image-text-to-text` / `image-to-text` avec le chat texte. En production, utilisez plutôt ces modèles pour l’OCR ou les endpoints adaptés, et gardez `text-generation` pour le chat standard. {% endhint %} ## Avant de commencer ### 1) Définir votre clé API ```bash export ALBERT_API_KEY="votre_jeton" ``` ### 2) Choisir un modèle `text-generation` {% tabs %} {% tab title="curl" %} ```bash curl -sS "https://albert.api.etalab.gouv.fr/v1/models" \ -H "Authorization: Bearer $ALBERT_API_KEY" ``` {% endtab %} {% tab title="Python" %} ```python import os from openai import OpenAI client = OpenAI( base_url="https://albert.api.etalab.gouv.fr/v1", api_key=os.environ["ALBERT_API_KEY"], ) models = client.models.list().data model = [m for m in models if m.type == "text-generation"][0].id print("Modèle chat trouvé :", model) ``` {% endtab %} {% tab title="JavaScript" %} ```javascript import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://albert.api.etalab.gouv.fr/v1", apiKey: process.env.ALBERT_API_KEY, }); const models = (await client.models.list()).data; const model = models.find((m) => m.type === "text-generation")?.id; console.log("Modèle chat trouvé :", model); ``` {% endtab %} {% endtabs %} ## Unstreamed chat {% tabs %} {% tab title="curl" %} ```bash curl -sS "https://albert.api.etalab.gouv.fr/v1/chat/completions" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "REMPLACER_PAR_MODELE_TEXT_GENERATION", "messages": [ {"role": "system", "content": "Tu réponds en français, de façon concise."}, {"role": "user", "content": "Explique ce qu’est une API compatible OpenAI en deux phrases."} ], "stream": false }' ``` {% endtab %} {% tab title="Python" %} ```python resp = client.chat.completions.create( model=model, messages=[ {"role": "system", "content": "Tu réponds en français, de façon concise."}, {"role": "user", "content": "Explique ce qu’est une API compatible OpenAI en deux phrases."}, ], stream=False, ) print(resp.choices[0].message.content) ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const resp = await client.chat.completions.create({ model, messages: [ { role: "system", content: "Tu réponds en français, de façon concise." }, { role: "user", content: "Explique ce qu’est une API compatible OpenAI en deux phrases." }, ], stream: false, }); console.log(resp.choices[0].message.content); ``` {% endtab %} {% endtabs %} ## Streaming (SSE) Pour activer le streaming, passez **`stream=True`**. Le SDK OpenAI renvoie une suite de chunks (deltas) jusqu’à la fin du flux. {% tabs %} {% tab title="curl" %} ```bash curl -N "https://albert.api.etalab.gouv.fr/v1/chat/completions" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "REMPLACER_PAR_MODELE_TEXT_GENERATION", "messages": [{"role": "user", "content": "Raconte une phrase sur la météo."}], "stream": true }' ``` {% endtab %} {% tab title="Python" %} ```python stream = client.chat.completions.create( model=model, messages=[{"role": "user", "content": "Raconte une phrase sur la météo."}], stream=True, ) for chunk in stream: delta = chunk.choices[0].delta if delta.content: print(delta.content, end="", flush=True) print() ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const stream = await client.chat.completions.create({ model, messages: [{ role: "user", content: "Raconte une phrase sur la météo." }], stream: true, }); for await (const chunk of stream) { const delta = chunk.choices?.[0]?.delta; if (delta?.content) process.stdout.write(delta.content); } process.stdout.write("\n"); ``` {% endtab %} {% endtabs %} Voir aussi le guide [Streaming](/albert-api/guides/streaming). ## Format de réponse (`response_format`) * **`{"type": "json_object"}`** : JSON valide (mode “JSON”). Vous devez aussi **demander explicitement du JSON** côté prompt (`system` / `user`) pour éviter des sorties longues inutiles. * **`{"type": "json_schema", "json_schema": { ... }}`** : sorties structurées guidées par un schéma JSON (approche proche des Structured Outputs). ## Outils et `tool_calls` Le champ **`tools`** permet forcer le modèle à gérer des fonctions au format JSON Schema. Le mécanisme `tools` / `tool_choice` est décrit dans [Function calling](/albert-api/guides/function-calling). ## Multimodal (image + texte) via `chat/completions` Albert API peut accepter des entrées multimodales via `POST /v1/chat/completions` en passant, dans un message `user`, un `content` **structuré** (liste) combinant : * `{"type": "text", "text": "..."}` * `{"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}` Choisissez un modèle dont le `type` est généralement **`image-text-to-text`** (ou `image-to-text` selon l’instance). {% tabs %} {% tab title="curl" %} ```bash IMG_BASE64=$(base64 -w 0 "archi_mistral.png") curl -sS "https://albert.api.etalab.gouv.fr/v1/chat/completions" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/json" \ -d "{ \"model\": \"REMPLACER_PAR_MODELE_MULTIMODAL\", \"messages\": [ { \"role\": \"user\", \"content\": [ {\"type\": \"text\", \"text\": \"Décris l'image et lis le texte visible (si présent). Réponds en français.\"}, {\"type\": \"image_url\", \"image_url\": {\"url\": \"data:image/png;base64,${IMG_BASE64}\"}} ] } ], \"max_tokens\": 500 }" ``` {% endtab %} {% tab title="Python" %} ```python import base64 import os from openai import OpenAI client = OpenAI( base_url="https://albert.api.etalab.gouv.fr/v1", api_key=os.environ["ALBERT_API_KEY"], ) with open("archi_mistral.png", "rb") as f: img_b64 = base64.b64encode(f.read()).decode("utf-8") r = client.chat.completions.create( model="REMPLACER_PAR_MODELE_MULTIMODAL", messages=[ { "role": "user", "content": [ {"type": "text", "text": "Décris l'image et lis le texte visible (si présent). Réponds en français."}, {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{img_b64}"}}, ], } ], max_tokens=500, ) print(r.choices[0].message.content) ``` {% endtab %} {% tab title="JavaScript" %} ```javascript import fs from "node:fs"; import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://albert.api.etalab.gouv.fr/v1", apiKey: process.env.ALBERT_API_KEY, }); const imgB64 = fs.readFileSync("archi_mistral.png").toString("base64"); const r = await client.chat.completions.create({ model: "REMPLACER_PAR_MODELE_MULTIMODAL", messages: [ { role: "user", content: [ { type: "text", text: "Décris l'image et lis le texte visible (si présent). Réponds en français." }, { type: "image_url", image_url: { url: `data:image/png;base64,${imgB64}` } }, ], }, ], max_tokens: 500, }); console.log(r.choices[0].message.content); ``` {% endtab %} {% endtabs %} {% hint style="warning" %} ⚠️ À vérifier — Champs additionnels exacts et valeurs par défaut : se référer au schéma `CreateChatCompletion` dans la page de l’endpoint Chat : [page de l’endpoint Chat](https://doc.incubateur.net/alliance/albert-api/api-reference/liste-des-endpoint/chat) {% endhint %} # Modèles (liste) Ce guide montre comment interroger **`GET /v1/models`** avec le SDK OpenAI (version “compatible OpenAI”) pour récupérer les modèles disponibles, puis filtrer par type (chat, embeddings, OCR, audio, etc.). {% hint style="info" %} Pour en savoir plus sur les modèles disponibles et leurs caractéristiques, voir la [page Modèles disponibles](/albert-api/modeles/available-models). {% endhint %} ## Pré-requis 1. Définir votre clé API : ```bash export ALBERT_API_KEY="votre_jeton" ``` 2. Installer le SDK : ```bash pip install -U openai ``` ## Liste des modèles (`GET /v1/models`) {% tabs %} {% tab title="curl" %} ```bash curl -sS "https://albert.api.etalab.gouv.fr/v1/models" \ -H "Authorization: Bearer $ALBERT_API_KEY" ``` {% endtab %} {% tab title="Python" %} ```python import os from openai import OpenAI client = OpenAI( base_url="https://albert.api.etalab.gouv.fr/v1", api_key=os.environ["ALBERT_API_KEY"], ) models = client.models.list().data for m in models[:3]: print( f"ID: {m.id}\n" f"Type: {m.type}\n" f"Owner: {m.owned_by}\n" f"Max tokens: {m.max_context_length}\n" ) ``` {% endtab %} {% tab title="JavaScript" %} ```javascript import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://albert.api.etalab.gouv.fr/v1", apiKey: process.env.ALBERT_API_KEY, }); const models = (await client.models.list()).data; for (const m of models.slice(0, 3)) { console.log(`ID: ${m.id}`); console.log(`Type: ${m.type}`); console.log(`Owner: ${m.owned_by}`); console.log(`Max tokens: ${m.max_context_length}\n`); } ``` {% endtab %} {% endtabs %} ## Filtrer selon l’usage En pratique, choisissez un modèle selon son champ `type` : * `text-generation` : **chat** (`POST /v1/chat/completions`) * `text-embeddings-inference` : **embeddings** (`POST /v1/embeddings`) * `automatic-speech-recognition` : **audio** (`POST /v1/audio/transcriptions`) * `image-to-text` ou variantes `*ocr*` : **OCR** (`POST /v1/ocr`) {% hint style="warning" %} ⚠️ À vérifier — Le mapping exact entre `type` et les endpoints dépend de la configuration de votre instance. Utilisez la liste des modèles et vérifiez le comportement sur votre environnement. {% endhint %} ## Vue catalogue (site officiel) Pour une vue “humaine” des modèles (familles, licences, aliases), vous pouvez aussi consulter : [Catalogue des modèles](https://ia.numerique.gouv.fr/outils-ia/albert-api/mod%C3%A8les/) Le site précise que les modèles proviennent de tiers (ex. Mistral, Meta) mais sont **hébergés sur nos serveurs** : aucune de vos données n’est envoyée à ces fournisseurs de modèles. ## Détail d’un modèle (`GET /v1/models/{model}`) {% tabs %} {% tab title="curl" %} ```bash curl -sS "https://albert.api.etalab.gouv.fr/v1/models/REMPLACER_PAR_MODEL_ID" \ -H "Authorization: Bearer $ALBERT_API_KEY" ``` {% endtab %} {% tab title="Python" %} ```python model_id = models[0].id model = client.models.retrieve(model=model_id) print( f"ID: {model.id}\n" f"Type: {model.type}\n" f"Owner: {model.owned_by}\n" f"Max tokens: {model.max_context_length}\n" ) ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const modelId = models[0].id; const model = await client.models.retrieve(modelId); console.log(`ID: ${model.id}`); console.log(`Type: ${model.type}`); console.log(`Owner: ${model.owned_by}`); console.log(`Max tokens: ${model.max_context_length}`); ``` {% endtab %} {% endtabs %} Pour la documentation endpoint, voir la [page “Models”](https://doc.incubateur.net/alliance/albert-api/api-reference/liste-des-endpoint/models). # Streaming Pour le chat, le streaming s’active avec **`"stream": true`** sur **`POST /v1/chat/completions`**. Le serveur renvoie des **Server-Sent Events** (SSE) : chaque événement contient un fragment JSON (delta) ; le flux se termine par une ligne `data: [DONE]` comme sur l’API OpenAI. ## Paramètre `stream_options` Lorsque `stream` est à `true`, vous pouvez renseigner **`stream_options`** pour affiner le comportement du flux (par exemple demander l’inclusion d’informations d’usage en fin de stream, sur le modèle des clients OpenAI). ```json { "model": "votre-modele-text-generation", "messages": [{"role": "user", "content": "Bonjour"}], "stream": true, "stream_options": { "include_usage": true } } ``` {% hint style="warning" %} ⚠️ À vérifier — Clés exactes supportées dans `stream_options` et compatibilité `include_usage` selon les modèles : consulter le schéma `CreateChatCompletion` dans la [page de l’endpoint Chat](https://doc.incubateur.net/alliance/albert-api/api-reference/liste-des-endpoint/chat). {% endhint %} ## Exemples (curl / Python / JavaScript) {% tabs %} {% tab title="curl" %} ```bash curl -N "https://albert.api.etalab.gouv.fr/v1/chat/completions" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "votre-modele-text-generation", "messages": [{"role": "user", "content": "Raconte une phrase sur la météo."}], "stream": true }' ``` {% endtab %} {% tab title="Python" %} ```python import os from openai import OpenAI client = OpenAI( base_url="https://albert.api.etalab.gouv.fr/v1", api_key=os.environ["ALBERT_API_KEY"], ) stream = client.chat.completions.create( model="votre-modele-text-generation", messages=[{"role": "user", "content": "Raconte une phrase sur la météo."}], stream=True, ) for chunk in stream: delta = chunk.choices[0].delta if delta.content: print(delta.content, end="", flush=True) print() ``` {% endtab %} {% tab title="JavaScript" %} ```javascript import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://albert.api.etalab.gouv.fr/v1", apiKey: process.env.ALBERT_API_KEY, }); const stream = await client.chat.completions.create({ model: "votre-modele-text-generation", messages: [{ role: "user", content: "Raconte une phrase sur la météo." }], stream: true, }); for await (const chunk of stream) { const delta = chunk.choices?.[0]?.delta; if (delta?.content) process.stdout.write(delta.content); } process.stdout.write("\n"); ``` {% endtab %} {% endtabs %} ## Bonnes pratiques * **Timeouts** : les streams longs exigent des timeouts côté client adaptés au contexte réseau. * **Reconnexion** : en cas de coupure, la requête doit être relancée ; il n’y a pas de reprise automatique standard sur un identifiant de stream. * **Erreurs mid-stream** : traiter les erreurs HTTP comme sur les appels non streamés ; voir [Codes d'erreur](broken://pages/N8WOLrEHNfTNle3o0aut). # Function calling & outils Albert API permet au modèle de chat de proposer des **appels d’outils** (`tool_calls`) décrits dans le corps de la requête. Le flux est le même que sur l’API OpenAI : le modèle émet une complétion avec des appels ; le client exécute la logique métier ; une réponse au rôle `tool` est renvoyée dans `messages` ; le modèle produit alors une réponse utilisateur finale. ## Déclarer des outils Le champ **`tools`** est une liste d’objets. Chaque outil de type fonction comporte au minimum : * un **nom** ; * une **description** ; * des **paramètres** au format JSON Schema (`parameters`) décrivant les arguments attendus. Le détail des schémas suit la convention **Chat Completions** OpenAI. Consultez le schéma `CreateChatCompletion` dans la [page de l’endpoint Chat](https://doc.incubateur.net/alliance/albert-api/api-reference/liste-des-endpoint/chat). ## `tool_choice` * **`none`** — pas d’appel d’outil (comportement par défaut lorsqu’aucun outil n’est fourni). * **`auto`** — le modèle choisit entre répondre en texte ou appeler un ou plusieurs outils (défaut lorsque des outils sont présents). * **`required`** — le modèle doit invoquer au moins un outil. * Sélection ciblée — forcer un outil précis via un objet du type `{"type": "function", "function": {"name": "nom_fonction"}}`. ## Enchaînement typique 1. **Requête initiale** — `messages` + `tools` + `tool_choice` adéquat. 2. **Réponse assistant** — peut contenir `tool_calls` avec des `arguments` JSON à parser. 3. **Exécution** — votre code appelle bases de données, HTTP internes, etc. 4. **Message `tool`** — vous ajoutez un message avec `role: "tool"`, le `tool_call_id` correspondant et le **résultat** (souvent une chaîne JSON). 5. **Nouvelle requête** — vous renvoyez toute l’historique mis à jour pour obtenir la réponse finale de l’assistant. ## Erreurs et robustesse * Validez et **sandboxez** les arguments produits par le modèle avant toute action sensible. * Limitez la profondeur des enchaînements d’outils pour éviter boucles et surcoûts tokens. # Embeddings Les **embeddings** sont des vecteurs numériques qui représentent le sens d'un contenu. Ils servent notamment à faire de la recherche sémantique, du clustering, de la déduplication, du RAG ou de la classification. Pour en savoir plus sur le RAG, voir la documentation dédiée [ici](/albert-api/guides/rag). Albert API expose l'endpoint **`POST /v1/embeddings`**, compatible avec le format OpenAI qui permet de transformer du texte ou des images en vecteurs. {% hint style="info" %} **Quel modèle choisir ?** Albert API mets à disposition différents modèles d'embeddings selon la nature du contenu que vous souhaitez vectoriser. Si votre corpus et vos requêtes sont **uniquement textuels**, utilisez le `openweight-embeddings`. Si vous voulez représenter des contenus textuels et visuels dans le même espace vectoriel, alors deux méthodes sont possibles avec des modèles différents (voir [Vectorisation d'images](#vectorisation-d-images)) En savoir plus sur ces modèles d'embeddings sur [la page des modèles disponibles](/albert-api/modeles/available-models). {% endhint %} {% hint style="warning" %} ⚠️ Il faut toujours vectoriser avec **le même modèle** ce que vous souhaitez comparer. N'indexez pas vos documents texte avec `openweight-embeddings` si vos images sont vectorisées avec `qwen3-vl-embedding-8b` : les vecteurs ne vivent pas dans le même espace et ne sont pas comparables ! {% endhint %} ## Vectorisation de texte L'endpoint **`POST /v1/embeddings`** calcule un vecteur pour une chaîne unique ou pour une liste de chaînes. La réponse suit le format OpenAI classique : vous recevez un objet par entrée dans `data[]`, avec son `embedding` et son `index`, ainsi qu'un objet `usage` pour le suivi de consommation. Pour le détail complet des clés et schémas, voir la [page de l'endpoint Embeddings](https://doc.incubateur.net/alliance/albert-api/api-reference/liste-des-endpoint/embeddings). ### Modèles recommandés Les modèles qui supportent la vectorisation de texte sont ceux de type **`text-embeddings-inference`**. Vous pouvez les lister avec `GET /v1/models` (en savoir plus [ici](/albert-api/guides/models)). **Exemple de requête :** {% tabs %} {% tab title="curl" %} ```bash curl -sS "https://albert.api.etalab.gouv.fr/v1/embeddings" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "openweight-embeddings", "input": [ "Le chat est un animal domestique.", "La France a pour capitale Paris." ] }' ``` {% endtab %} {% tab title="Python" %} ```python import os from openai import OpenAI client = OpenAI( base_url="https://albert.api.etalab.gouv.fr/v1", api_key=os.environ["ALBERT_API_KEY"], ) response = client.embeddings.create( model="openweight-embeddings", input=[ "Le chat est un animal domestique.", "La France a pour capitale Paris.", ], encoding_format="float", ) for item in response.data: print("index=", item.index, "dim=", len(item.embedding)) ``` {% endtab %} {% tab title="JavaScript" %} ```javascript import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://albert.api.etalab.gouv.fr/v1", apiKey: process.env.ALBERT_API_KEY, }); const response = await client.embeddings.create({ model: "openweight-embeddings", input: [ "Le chat est un animal domestique.", "La France a pour capitale Paris.", ], encoding_format: "float", }); for (const item of response.data) { console.log("index=", item.index, "dim=", item.embedding.length); } ``` {% endtab %} {% endtabs %} ## Vectorisation d'images Si votre objectif est de faire de la recherche ou du rapprochement entre des textes et des images ou entre des images entre elles, deux approches sont possibles avec Albert API : * utiliser un modèle d'embeddings multimodal, c'est-à-dire un modèle qui peut vectoriser à la fois du texte et des images ; * utiliser un LLM multimodal pour transformer les images en texte, puis vectoriser ce texte avec un modèle d'embeddings unimodal (autrement dit, un modèle qui ne peut vectoriser que du texte). {% hint style="info" %} **Comment choisir entre les deux approches ?** Le bon choix ne peut pas être décidé uniquement "sur le papier" : il doit être fait après une étude sur un échantillon représentatif de vos documents, en observant les corrélations de similarité cosinus obtenues sur vos cas réels. Selon la typologie des documents (scans, formulaires, slides, schémas, captures, documents très textuels ou très visuels), la méthode la plus pertinente peut varier. Constituez un petit jeu d'évaluation à partir d'extraits de documents représentatifs de votre corpus, puis comparez : * la proximité cosinus entre les éléments que vous jugez similaires ; * la séparation avec les éléments non pertinents ; * la qualité du classement obtenu pour vos requêtes réelles. Ne retenez la méthode qu'après cette vérification empirique. {% endhint %} ### Méthode 1 : vectorisation multimodale Cette approche consiste à utiliser modèle d'embeddings multimodal, c'est-à-dire un modèle qui peut vectoriser à la fois du texte et des images. Sur Albert API, ce rôle est assuré par **`qwen3-vl-embedding-8b`**. {% hint style="info" %} Pour en savoir plus sur ce modèle, voir [la documentation du modèle](/albert-api/modeles/available-models#qwen3-vl-embedding-8b). {% endhint %} Pour le **texte**, vous pouvez continuer à utiliser `/v1/embeddings` avec un champ `input` standard. Pour les **images**, Albert API expose `/v1/embeddings` au format OpenAI classique, mais la gateway supporte aussi un champ vLLM **`messages`** pour certains usages multimodaux. Cette variante image n'est pas documentée comme un usage standard OpenAI, car elle est **spécifique au modèle `qwen3-vl-embedding-8b`**. **Particularités :** * le corps de requête utilise **`messages`** au lieu de `input` ; * la réponse reste un objet d'embeddings au format habituel ; * **une seule image par requête** est supportée ; * selon votre client, il peut être plus simple d'utiliser une requête HTTP directe plutôt que le helper `embeddings.create()`. **Exemple de requête :** {% tabs %} {% tab title="curl" %} ```bash IMAGE_BASE64=$(curl -sS "https://raw.githubusercontent.com/AtharvaTaras/Cat-Images-Dataset/refs/heads/master/cute%20cat/Image_102.jpg" | base64 | tr -d '\n') curl -sS "https://albert.api.etalab.gouv.fr/v1/embeddings" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen3-vl-embedding-8b", "messages": [ {"role": "system", "content": "Represent the user's input."}, { "role": "user", "content": [ { "type": "image_url", "image_url": {"url": "data:image/jpeg;base64,${IMAGE_BASE64}"} } ] }, {"role": "assistant", "content": ""} ], "encoding_format": "float", "continue_final_message": true, "add_special_tokens": true }' ``` {% endtab %} {% tab title="Python" %} ```python import base64 import os import requests image_url = "https://raw.githubusercontent.com/AtharvaTaras/Cat-Images-Dataset/refs/heads/master/cute%20cat/Image_102.jpg" image_base64 = base64.b64encode(requests.get(image_url).content).decode("utf-8") response = requests.post( url="https://albert.api.etalab.gouv.fr/v1/embeddings", headers={"Authorization": f"Bearer {os.environ['ALBERT_API_KEY']}"}, json={ "model": "qwen3-vl-embedding-8b", "messages": [ {"role": "system", "content": "Represent the user's input."}, { "role": "user", "content": [ { "type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image_base64}"}, } ], }, {"role": "assistant", "content": ""}, ], "encoding_format": "float", "continue_final_message": True, "add_special_tokens": True, }, ) response.raise_for_status() data = response.json() print("dim=", len(data["data"][0]["embedding"])) ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const imageUrl = "https://raw.githubusercontent.com/AtharvaTaras/Cat-Images-Dataset/refs/heads/master/cute%20cat/Image_102.jpg"; const imageBuffer = await (await fetch(imageUrl)).arrayBuffer(); const imageBase64 = Buffer.from(imageBuffer).toString("base64"); const response = await fetch("https://albert.api.etalab.gouv.fr/v1/embeddings", { method: "POST", headers: { Authorization: `Bearer ${process.env.ALBERT_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ model: "qwen3-vl-embedding-8b", messages: [ { role: "system", content: "Represent the user's input." }, { role: "user", content: [ { type: "image_url", image_url: { url: `data:image/jpeg;base64,${imageBase64}` }, }, ], }, { role: "assistant", content: "" }, ], encoding_format: "float", continue_final_message: true, add_special_tokens: true, }), }); if (!response.ok) throw new Error(await response.text()); const data = await response.json(); console.log("dim=", data.data[0].embedding.length); ``` {% endtab %} {% endtabs %} ### Méthode 2 : vectorisation avec un LLM multimodal L'autre approche consiste à transformer d'abord l'image en texte à l'aide d'un LLM multimodal, puis à vectoriser ce texte avec un modèle d'embeddings unimodal (autrement dit, un modèle qui ne peut vectoriser que du texte). La chaîne de traitement est alors la suivante : 1. un LLM multimodal décrit l'image ou en extrait les informations utiles (ex. `openweight-medium`); 2. le texte produit est ensuite vectorisé avec un modèle d'embeddings texte (ex. `openweight-embeddings`); {% hint style="info" %} Pour en savoir plus sur les LLM multimodaux disponibles sur Albert API, voir [la documentation des modèles disponibles](/albert-api/modeles/available-models). {% endhint %} **Exemple de requête :** {% tabs %} {% tab title="curl" %} ```bash IMAGE_BASE64=$(curl -sS "https://raw.githubusercontent.com/AtharvaTaras/Cat-Images-Dataset/refs/heads/master/cute%20cat/Image_102.jpg" | base64 | tr -d '\n') curl -sS "https://albert.api.etalab.gouv.fr/v1/chat/completions" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "openweight-medium", "messages": [ { "role": "user", "content": [ {"role": "system", "content": "Décris l'image en quelques phrases."}, { "type": "image_url", "image_url": {"url": "data:image/jpeg;base64,${IMAGE_BASE64}"}, }, ], }, ], }' ``` {% endtab %} {% tab title="Python" %} ```python import base64 import os import requests image_url = "https://raw.githubusercontent.com/AtharvaTaras/Cat-Images-Dataset/refs/heads/master/cute%20cat/Image_102.jpg" image_base64 = base64.b64encode(requests.get(image_url).content).decode("utf-8") ``` ```python import base64 import os import requests image_url = "https://raw.githubusercontent.com/AtharvaTaras/Cat-Images-Dataset/refs/heads/master/cute%20cat/Image_102.jpg" image_base64 = base64.b64encode(requests.get(image_url).content).decode("utf-8") response = requests.post( url="https://albert.api.etalab.gouv.fr/v1/chat/completions", headers={"Authorization": f"Bearer {os.environ['ALBERT_API_KEY']}"}, json={ "model": "openweight-medium", "messages": [ {"role": "system", "content": "Décris l'image en quelques phrases."}, { "role": "user", "content": [ { "type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image_base64}"}, } ], }, ], }, ) response.raise_for_status() data = response.json() print(data["choices"][0]["message"]["content"]) ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const imageUrl = "https://raw.githubusercontent.com/AtharvaTaras/Cat-Images-Dataset/refs/heads/master/cute%20cat/Image_102.jpg"; const imageBuffer = await (await fetch(imageUrl)).arrayBuffer(); const imageBase64 = Buffer.from(imageBuffer).toString("base64"); ``` ```javascript const imageUrl = "https://raw.githubusercontent.com/AtharvaTaras/Cat-Images-Dataset/refs/heads/master/cute%20cat/Image_102.jpg"; const imageBuffer = await (await fetch(imageUrl)).arrayBuffer(); const imageBase64 = Buffer.from(imageBuffer).toString("base64"); const response = await fetch("https://albert.api.etalab.gouv.fr/v1/chat/completions", { method: "POST", headers: { Authorization: `Bearer ${process.env.ALBERT_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ model: "openweight-medium", messages: [ { role: "system", content: "Décris l'image en quelques phrases." }, { role: "user", content: [ { type: "image_url", image_url: { url: `data:image/jpeg;base64,${imageBase64}` } }, ], }, ], }), }); if (!response.ok) throw new Error(await response.text()); const data = await response.json(); console.log(data.choices[0].message.content); ``` {% endtab %} {% endtabs %} Par exemple, vous pouvez utiliser un LLM multimodal tel que **`openweight-medium`** pour produire une description structurée de l'image, puis envoyer cette description vers un modèle d'embeddings textuels. Cette approche peut être particulièrement utile lorsque la pertinence dépend davantage du contenu textuel ou sémantique explicitable de l'image que de ses caractéristiques visuelles brutes. En contrepartie, elle ajoute une étape de transformation : la qualité finale dépend donc aussi de la qualité de la description produite par le LLM. Là encore, le choix doit être validé en mesurant la similarité cosinus sur des extraits représentatifs de votre base documentaire. # Transcription audio L’endpoint **`POST /v1/audio/transcriptions`** transcrit un fichier audio via un modèle de type **`automatic-speech-recognition`** ([en savoir plus sur les types de modèles](/albert-api/modeles/model-types)). ## Transcrire un fichier audio Le endpoint `/v1/audio/transcriptions` supporte les fichiers `mp3` et `wav` jusqu'à 20 Mb par fichier. Pour plus d'information sur les paramètres du endpoint, voir la page [API reference - Audio](https://guides.ia.numerique.gouv.fr/albert-api/api-reference/liste-des-endpoint/audio). **Exemple de requête :** ```bash curl -sS "https://albert.api.etalab.gouv.fr/v1/audio/transcriptions" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -F "file=@enregistrement.mp3" \ -F "model=REMPLACER_PAR_MODELE_ASR" \ -F "language=fr" \ -F "response_format=json" ``` ## Exemples (curl / Python / JavaScript) {% tabs %} {% tab title="curl" %} ```bash curl -sS "https://albert.api.etalab.gouv.fr/v1/audio/transcriptions" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -F "file=@enregistrement.mp3" \ -F "model=REMPLACER_PAR_MODELE_ASR" \ -F "language=fr" ``` {% endtab %} {% tab title="Python" %} ```python import os from openai import OpenAI client = OpenAI( base_url="https://albert.api.etalab.gouv.fr/v1", api_key=os.environ["ALBERT_API_KEY"], ) with open("enregistrement.mp3", "rb") as f: tr = client.audio.transcriptions.create( model="REMPLACER_PAR_MODELE_ASR", file=f, language="fr", ) print(tr.text) ``` {% endtab %} {% tab title="JavaScript" %} ```javascript import fs from "node:fs"; import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://albert.api.etalab.gouv.fr/v1", apiKey: process.env.ALBERT_API_KEY, }); const tr = await client.audio.transcriptions.create({ model: "REMPLACER_PAR_MODELE_ASR", file: fs.createReadStream("enregistrement.mp3"), language: "fr", }); console.log(tr.text); ``` {% endtab %} {% endtabs %} ## Choisir `response_format` Le paramètre `response_format` permet de choisir le format de la réponse. Ce format dépend de l'usage que vous souhaitez en faire. | `response_format` | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `json` (defaut) | Réponse au format JSON, contient le texte transcrit. | | `text` | Réponse au format TXT, contient uniquement le texte transcrit. | | `verbose_json` | Réponse au format JSON en indiquant le début et la fin de chaque phrase. | | `srt` | Réponse au format SRT. | | `vtt` | Réponse au format VTT. | | `diarized_json` | Réponse au format JSON en indiquant le début et la fin de chaque phrase et les changements de speakers. Ce format utilisé pour les transcriptions des réunions. | # OCR - Reconnaissance Optique de Caractères L'**OCR** (*Optical Character Recognition*, reconnaissance optique de caractères) permet d'extraire le texte contenu dans une image ou un document scanné (PDF, photo, capture d'écran, etc.). C'est ce qui permet de rendre exploitables des contenus qui n'existent pas nativement sous forme de texte numérique : archives papier scannées, formulaires, factures, courriers reçus par mail sous forme d'image... Une fois le texte extrait, vous pouvez le rechercher, l'indexer, l'analyser ou l'envoyer à un LLM. ## Les deux façons de faire de l'OCR avec Albert API Albert API propose deux façons de faire de l'OCR : 1. **`/v1/chat/completions`** avec un LLM multimodal fine-tuné pour l'OCR, comme **`openweight-ocr`** : le modèle "lit" l'image envoyée dans le message et retourne le texte extrait (éventuellement accompagné d'un raisonnement). 2. **`/v1/ocr`** avec **`mistral-ocr-2512`** : cet endpoint reproduit l'[endpoint `/v1/ocr` de l'API SaaS de Mistral AI](https://mistral.ai/news/mistral-ocr/) et donne accès à la pipeline complète d'OCR de Mistral AI, que nous hébergeons nous-mêmes. {% hint style="warning" %} ⚠️ **`mistral-ocr-2512`** n'est **pas accessible à l'ensemble des utilisateurs**. Si vous n'y avez pas accès, utilisez `/v1/chat/completions` avec **`openweight-ocr`**, qui couvre la grande majorité des besoins d'OCR et est disponible par défaut. {% endhint %} {% hint style="info" %} **Quelle méthode choisir ?** Par défaut, utilisez `/v1/chat/completions` avec `openweight-ocr` : c'est le modèle que nous mettons à disposition de tous les utilisateurs, aussi bien pour extraire du texte que pour combiner cette extraction avec du raisonnement (résumé, question-réponse, extraction de champs précis...) en une seule requête. Si vous avez accès à `mistral-ocr-2512` et que vous avez besoin de la pipeline d'OCR complète de Mistral AI (extraction fidèle et structurée du texte d'un document entier, annotations, etc.), utilisez `/v1/ocr`, notamment pour l'intégrer ensuite dans un pipeline de [RAG](/albert-api/guides/rag). {% endhint %} Pour connaître les modèles compatibles avec ces endpoints, voir [notre documentation dédiées aux modèles disponibles](/albert-api/modeles/available-models). ## Méthode 1 (par défaut) : OCR avec l'endpoint `/v1/chat/completions` Cette méthode s'appuie sur un LLM multimodal capable d'analyser des images (voir la section [Multimodal](/albert-api/guides/chat-completions#multimodal-image-texte-via-chat-completions) du guide Chat Completions). Albert API propose **`openweight-ocr`**, un modèle multimodal fine-tuné spécifiquement pour l'OCR, disponible pour tous les utilisateurs par défaut. Cette méthode est adaptée si vous voulez, en une seule requête, extraire le texte d'un document **et**, si besoin, en tirer une information (résumé, réponse à une question, etc.). {% hint style="warning" %} Ce endpoint ne prend en entrée que des images. Si vous avez un document PDF, convertissez-le en images (une image par page) avant de l'envoyer à l'endpoint. {% endhint %} **Exemple de requête :** {% tabs %} {% tab title="curl" %} ```bash IMAGE_BASE64=$(curl -sS "https://upload.wikimedia.org/wikipedia/commons/thumb/0/0b/ReceiptSwiss.jpg/1280px-ReceiptSwiss.jpg" | base64 -w 0) curl -sS "https://albert.api.etalab.gouv.fr/v1/chat/completions" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "openweight-ocr", "messages": [ { "role": "user", "content": [ {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,${IMAGE_BASE64}"}} ] } ], "max_tokens": 4096, "temperature": 0.2, "top_p": 0.9 }' ``` {% endtab %} {% tab title="Python" %} ```python import base64 import os import requests from openai import OpenAI image_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/0/0b/ReceiptSwiss.jpg/1280px-ReceiptSwiss.jpg" image_base64 = base64.b64encode(requests.get(image_url).content).decode("utf-8") client = OpenAI( base_url="https://albert.api.etalab.gouv.fr/v1", api_key=os.environ["ALBERT_API_KEY"], ) response = client.chat.completions.create( model="openweight-ocr", messages=[ { "role": "user", "content": [{"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image_base64}"}}], } ], max_tokens=4096, temperature=0.2, top_p=0.9, ) print(response.choices[0].message.content) ``` {% endtab %} {% tab title="JavaScript" %} ```javascript import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://albert.api.etalab.gouv.fr/v1", apiKey: process.env.ALBERT_API_KEY, }); const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/thumb/0/0b/ReceiptSwiss.jpg/1280px-ReceiptSwiss.jpg"; const imageBuffer = await (await fetch(imageUrl)).arrayBuffer(); const imageBase64 = Buffer.from(imageBuffer).toString("base64"); const response = await client.chat.completions.create({ model: "openweight-ocr", messages: [ { role: "user", content: [{ type: "image_url", image_url: { url: `data:image/jpeg;base64,${imageBase64}` } }], }, ], max_tokens: 4096, temperature: 0.2, top_p: 0.9, }); console.log(response.choices[0].message.content); ``` {% endtab %} {% endtabs %} {% hint style="info" %} **OCR d'un PDF** Si votre document est un PDF, convertissez d'abord chaque page à traiter en image avant de l'envoyer à `/v1/chat/completions`. En Python, vous pouvez utiliser `pypdfium2` : ```python import base64 import io import pypdfium2 as pdfium import requests pdf_data = requests.get("https://arxiv.org/pdf/2412.13663").content pdf = pdfium.PdfDocument(pdf_data) page = pdf[0] # Rendu à 200 DPI (facteur d'échelle = 200/72 ≈ 2.77) pil_image = page.render(scale=2.77).to_pil() buffer = io.BytesIO() pil_image.save(buffer, format="PNG") image_base64 = base64.b64encode(buffer.getvalue()).decode("utf-8") ``` Conseils : * Rendez vos PDF à 200 DPI, avec une dimension la plus longue ciblée autour de 1540px. * Conservez le ratio d'aspect de la page d'origine pour ne pas déformer la géométrie du texte. {% endhint %} ## Méthode 2 (accès restreint) : OCR avec l'endpoint `/v1/ocr` {% hint style="warning" %} ⚠️ Cette méthode repose sur **`mistral-ocr-2512`**, modèle **non accessible à l'ensemble des utilisateurs**. Si vous n'y avez pas accès, utilisez plutôt la [Méthode 1](#méthode-1-par-défaut-ocr-avec-lendpoint-v1chatcompletions) avec `openweight-ocr`. {% endhint %} L'endpoint **`POST /v1/ocr`** reproduit l'endpoint `/v1/ocr` de l'API SaaS de Mistral AI et donne accès à la pipeline complète d'OCR de Mistral AI, hébergée par nos soins (offre Mistral Entreprise on-premise). Il prend en entrée un **document** ou une **image** référencé(e) dans le corps de la requête JSON et retourne, pour chaque page, le texte extrait (au format markdown) ainsi que, selon la configuration, des **annotations**. Pour le détail complet des clés et schémas, voir la [page de l'endpoint OCR](https://doc.incubateur.net/alliance/albert-api/api-reference/liste-des-endpoint/ocr). ### Modèle disponible Le seul modèle disponible sur cet endpoint est **`mistral-ocr-2512`**, de type `image-to-text` (voir le guide [Types de modèles](/albert-api/modeles/model-types)). Vous pouvez vérifier votre accès en récupérant la liste des modèles disponibles sur votre instance avec `GET /v1/models` (voir le guide [Modèles (liste)](/albert-api/guides/models)). ### Paramètres principaux * **`model`** (requis) — `mistral-ocr-2512`. * **`document`** (requis) — objet décrivant la source à traiter : * `{"type": "document_url", "document_url": "https://..."}` pour un PDF/document (URL classique ou data URL `data:application/pdf;base64,...`) ; * `{"type": "image_url", "image_url": "https://..."}` pour une image (URL classique ou data URL `data:image/...;base64,...`). * **`pages`** — liste d'indices de pages à traiter. * **`include_image_base64`** — inclut les images des pages en base64 dans la réponse (utile pour archiver ou afficher les pages traitées). * **`document_annotation_format`** / **`bbox_annotation_format`** — format de sortie des annotations (texte libre, JSON, JSON Schema), sur le même principe que le `response_format` de `/v1/chat/completions`. {% hint style="warning" %} ⚠️ Les indices de page du paramètre `pages` sont **à partir de 0** (`0` = première page). {% endhint %} **Exemple de requête :** OCR d'un PDF référencé par URL {% tabs %} {% tab title="curl" %} ```bash curl -sS "https://albert.api.etalab.gouv.fr/v1/ocr" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "mistral-ocr-2512", "document": { "type": "document_url", "document_url": "https://www.princexml.com/samples/magic6/magic.pdf" }, "include_image_base64": true }' ``` {% endtab %} {% tab title="Python" %} ```python import os import requests response = requests.post( url="https://albert.api.etalab.gouv.fr/v1/ocr", headers={"Authorization": f"Bearer {os.environ['ALBERT_API_KEY']}"}, json={ "model": "mistral-ocr-2512", "document": { "type": "document_url", "document_url": "https://www.princexml.com/samples/magic6/magic.pdf", }, "include_image_base64": True, }, ) response.raise_for_status() data = response.json() print("Pages traitées :", len(data["pages"])) print(data["pages"][0]["markdown"]) ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const response = await fetch("https://albert.api.etalab.gouv.fr/v1/ocr", { method: "POST", headers: { Authorization: `Bearer ${process.env.ALBERT_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ model: "mistral-ocr-2512", document: { type: "document_url", document_url: "https://www.princexml.com/samples/magic6/magic.pdf", }, include_image_base64: true, }), }); if (!response.ok) throw new Error(await response.text()); const data = await response.json(); console.log("Pages traitées :", data.pages.length); console.log(data.pages[0].markdown); ``` {% endtab %} {% endtabs %} ### Variante : OCR d'un PDF encodé en base64 (data URL) Cette variante est utile lorsque le document n'est pas accessible par une URL publique (fichier local, par exemple). {% tabs %} {% tab title="curl" %} ```bash PDF_BASE64=$(curl -sS "https://www.princexml.com/samples/textbook/somatosensory.pdf" | base64 -w 0) curl -sS "https://albert.api.etalab.gouv.fr/v1/ocr" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "mistral-ocr-2512", "document": { "type": "document_url", "document_url": "data:application/pdf;base64,${PDF_BASE64}" }, "include_image_base64": true }' ``` {% endtab %} {% tab title="Python" %} ```python import base64 import os import requests pdf_url = "https://www.princexml.com/samples/textbook/somatosensory.pdf" pdf_base64 = base64.b64encode(requests.get(pdf_url).content).decode("utf-8") response = requests.post( url="https://albert.api.etalab.gouv.fr/v1/ocr", headers={"Authorization": f"Bearer {os.environ['ALBERT_API_KEY']}"}, json={ "model": "mistral-ocr-2512", "document": { "type": "document_url", "document_url": f"data:application/pdf;base64,{pdf_base64}", }, "include_image_base64": True, }, ) response.raise_for_status() data = response.json() print(data["pages"][0]["markdown"][:200]) ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const pdfBuffer = await (await fetch("https://www.princexml.com/samples/textbook/somatosensory.pdf")).arrayBuffer(); const pdfBase64 = Buffer.from(pdfBuffer).toString("base64"); const response = await fetch("https://albert.api.etalab.gouv.fr/v1/ocr", { method: "POST", headers: { Authorization: `Bearer ${process.env.ALBERT_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ model: "mistral-ocr-2512", document: { type: "document_url", document_url: `data:application/pdf;base64,${pdfBase64}`, }, include_image_base64: true, }), }); if (!response.ok) throw new Error(await response.text()); const data = await response.json(); console.log(data.pages[0].markdown.slice(0, 200)); ``` {% endtab %} {% endtabs %} **Exemple de requête :** OCR d'une image référencée par URL {% tabs %} {% tab title="curl" %} ```bash curl -sS "https://albert.api.etalab.gouv.fr/v1/ocr" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "mistral-ocr-2512", "document": { "type": "image_url", "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/0/0b/ReceiptSwiss.jpg/1280px-ReceiptSwiss.jpg" }, "include_image_base64": true }' ``` {% endtab %} {% tab title="Python" %} ```python import os import requests image_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/0/0b/ReceiptSwiss.jpg/1280px-ReceiptSwiss.jpg" response = requests.post( url="https://albert.api.etalab.gouv.fr/v1/ocr", headers={"Authorization": f"Bearer {os.environ['ALBERT_API_KEY']}"}, json={ "model": "mistral-ocr-2512", "document": {"type": "image_url", "image_url": image_url}, "include_image_base64": True, }, ) response.raise_for_status() data = response.json() print(data["pages"][0]["markdown"][:200]) ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const response = await fetch("https://albert.api.etalab.gouv.fr/v1/ocr", { method: "POST", headers: { Authorization: `Bearer ${process.env.ALBERT_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ model: "mistral-ocr-2512", document: { type: "image_url", image_url: "https://upload.wikimedia.org/wikipedia/commons/thumb/0/0b/ReceiptSwiss.jpg/1280px-ReceiptSwiss.jpg", }, include_image_base64: true, }), }); if (!response.ok) throw new Error(await response.text()); const data = await response.json(); console.log(data.pages[0].markdown.slice(0, 200)); ``` {% endtab %} {% endtabs %} # RAG - Génération Augmentée par Récupération ## Qu'est-ce que le RAG ? Le RAG est une technique permettant de limiter les hallucinations du modèle en lui fournissant un contexte plus riche. Il consiste en 3 étapes : 1. Recherche des extraits de textes pertinents par rapport à une question 2. Construction d'un prompt avec le contexte trouvé 3. Envoi du prompt comprenant les textes pertinents et la question à un LLM pour obtenir une réponse ## Le RAG avec Albert API Albert API propose d'interagir avec une base de données vectorielle (*vector store*) pour permettre de réaliser du RAG. L'API propose de nourrir ce vector store en important des fichiers qui seront automatiquement traités et insérés dans le *vector store*. {% hint style="info" %} **Qu'est-ce qu'un vector store ?** Un vector store est une base de données qui permet de stocker des documents textes et leur représentation vectorielle (suite de nombres qui représentent les concepts présents dans le document). Pour plus d'informations, rendez-vous sur la section \[...] {% endhint %} Les collections sont des espaces de stockage dans ce *vector store*. Elles sont utilisées pour organiser les fichiers qui sont importés par l'API. Ces fichiers sont convertis en documents, contenant le texte extrait. Ces documents sont alors découpés en chunks et convertis en vecteurs à l'aide d'un modèle d'embeddings. Ces vecteurs ainsi que le texte qui a été vectorisé sont enregistrés dans la base de données vectorielle. L'intégration se déroule donc en 3 phases : * **File** : fichier original (non stocké) * **Document** : texte extrait d'un fichier * **Chunk** : portion de texte découpée dans un document {% hint style="info" %} Qu'est-ce qu'un chunk et pourquoi les documents sont découpés en chunks ? Un chunk est une portion de texte découpée dans un document. Nous sommes contraints de découper le texte car les LLM ont deux limitations : * leur fenêtre de contexte est limitée (par exemple 132 000 tokens). * leur capacité de traitement de longs prompts est limitée. Il arrive souvent que, lorsqu'on envoie un prompt trop long, le LLM ait des difficultés à le comprendre ou à retrouver une information noyée dans le texte. En conséquence, il est opportun de ne pas envoyer tous les documents en entier au LLM mais de ne lui envoyer que les parties des documents (chunks) qui sont pertinentes pour la question. {% endhint %} ```mermaid graph LR %% Entities (declared first) File["File"] docA["Document A"] docB["Document B"] chunkA["Chunk A"] chunkB["Chunk B"] chunkC["Chunk C"] chunkD["Chunk D"] %% Links File --> docA File --> docB docA --> chunkA docA --> chunkB docB --> chunkC docB --> chunkD %% Styling by step / entity type classDef file fill:#E3F2FD,stroke:#1E88E5,stroke-width:1px,color:#0D47A1; classDef document fill:#E8F5E9,stroke:#43A047,stroke-width:1px,color:#1B5E20; classDef chunk fill:#FFF3E0,stroke:#FB8C00,stroke-width:1px,color:#E65100; class File file; class docA,docB document; class chunkA,chunkB,chunkC,chunkD chunk; ``` Une fois importés, vous pouvez interroger l'API pour récupérer les documents ou chunks qui vous intéressent en suivant la hiérarchie suivante reposant sur les 3 entités : * **Collection** : espace de stockage des documents et chunks * **Document** : texte extrait d'un fichier * **Chunk** : portion de texte découpée dans un document ```mermaid flowchart TB %% Nested schema (Collection > Document > Chunk) subgraph COL["Collection"] direction TB subgraph DOC["Document"] direction TB CHK["Chunk"] end end %% Styling (aligned with diagram above) style COL fill:#FFCDD2,stroke:#E53935,stroke-width:1px,color:#B71C1C,rx:18,ry:18 style DOC fill:#E8F5E9,stroke:#43A047,stroke-width:1px,color:#1B5E20,rx:18,ry:18 style CHK fill:#FFF3E0,stroke:#FB8C00,stroke-width:1px,color:#E65100,rx:14,ry:14 ``` ### Les collections publiques **Il existe deux types de collections : publiques et privées.** Les collections publiques sont accessibles à tous alors que les collections privées sont accessibles uniquement à vous. {% hint style="info" %} Les collections publiques sont créées et mises à jour régulièrement par l'équipe d'Albert API. Vous n'avez pas la possibilité de créer ou de mettre à jour une collection publique. | Nom de la collection | ID | Contenu | | ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mediatech-legifrance` | 139226 | Législation et réglementation nationale consolidée : codes officiels (73 en vigueur), lois, décrets, ordonnances depuis 1945, arrêtés sélectionnés depuis 1990. Source : legifrance.gouv.fr | | `mediatech-fiches-travail-emploi` | 150277 | Fiches pédagogiques du Ministère du travail sur le droit du travail. Source : travail-emploi.gouv.fr | | `mediatech-fiches-service-public` | 150281 | Fiches pratiques à destination des usagers (droits, démarches administratives, formulaires). Source : service-public.gouv.fr | | `mediatech-annuaire-services-publics-locaux` | 139997 | Annuaire de plus de 86 000 guichets publics locaux (mairies, organismes sociaux, services de l'État) avec coordonnées et horaires. Source : data.gouv.fr | | `mediatech-annuaire-services-publics-nationaux` | 139998 | Référentiel de l'organisation administrative de l'État : \~6 000 organismes, missions, hiérarchie, coordonnées et responsables. Source : data.gouv.fr | | `mediatech-dossiers-legislatifs` | 139999 | Dossiers législatifs : lois depuis juin 2002, ordonnances depuis 2002, projets et propositions de loi en préparation. Source : data.gouv.fr | | `mediatech-decisions-conseil-constitutionnel` | 140006 | Décisions du Conseil constitutionnel depuis 1958 (DC, QPC, contentieux électoral, etc.). Source : data.gouv.fr | | `mediatech-decisions-cnil` | 140029 | Délibérations de la CNIL depuis 1979. Source : echanges.dila.gouv.fr | | {% endhint %} | | | ## Step 1 Recherche des extraits de textes pertinents par rapport à une question ### Créer une collection privée Pour créer une collection privée, vous pouvez utiliser l'endpoint `/v1/collections` en spécifiant un nom. **Exemple de requête :** {% tabs %} {% tab title="curl" %} ```bash curl -sS "https://albert.api.etalab.gouv.fr/v1/collections" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "ma-collection"}' ``` {% endtab %} {% tab title="Python" %} ```python import os import requests collection = requests.post( url="https://albert.api.etalab.gouv.fr/v1/collections", headers={"Authorization": f"Bearer {os.environ['ALBERT_API_KEY']}"}, json={"name": "ma-collection"}, ) collection_id = collection.json()["id"] ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const baseUrl = "https://albert.api.etalab.gouv.fr/v1"; const apiKey = process.env.ALBERT_API_KEY; const res = await fetch(`${baseUrl}/collections`, { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ name: "ma-collection" }), }); if (!res.ok) { throw new Error(`HTTP ${res.status}: ${await res.text()}`); } const collection = await res.json(); const collectionId = collection.id; ``` {% endtab %} {% endtabs %} ### Consulter les collections Qu'elles soient publiques ou privées, vous pouvez consulter les collections en utilisant l'endpoint `/v1/collections`. {% hint style="warning" %} Si vous ne voyez pas la collection que vous avez créée, il est possible que ce soit l'effet de la pagination. Changez les paramètres `offset` et `limit` pour parcourir les collections. De même, vous pouvez filtrer par type de collection en spécifiant le paramètre `visibility` à `private` ou `public`. {% endhint %} **Exemple de requête :** {% tabs %} {% tab title="curl" %} ```bash curl -sS "https://albert.api.etalab.gouv.fr/v1/collections?offset=0&limit=10" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/json" \ ``` {% endtab %} {% tab title="Python" %} ```python import requests import os collections = requests.get( url="https://albert.api.etalab.gouv.fr/v1/collections", params={"offset": 0, "limit": 10}, headers={"Authorization": f"Bearer {os.environ['ALBERT_API_KEY']}"}, ) collections.raise_for_status() collections = collections.json() ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const baseUrl = "https://albert.api.etalab.gouv.fr/v1"; const apiKey = process.env.ALBERT_API_KEY; const res = await fetch(`${baseUrl}/collections`, { method: "GET", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, params: { offset: 0, limit: 10 }, }); if (!res.ok) { throw new Error(`HTTP ${res.status}: ${await res.text()}`); } const collections = await res.json(); ``` {% endtab %} {% endtabs %} ### Créer un document à partir d'un fichier Une fois que vous avez créé une collection, récupérez son ID et utilisez-le pour créer un document. L'ID est retourné lors de la création de la collection ou lors de la consultation des collections. Pour uploader un fichier, vous pouvez utiliser l'endpoint `/v1/documents` en spécifiant le fichier à uploader et l'ID de la collection. L'endpoint accepte les fichiers de type `PDF`, `TXT`, `HTML` et `MARKDOWN` jusqu'à 20 Mb par fichier. Lors de cet appel, l'API va : * extraire le texte du fichier * découper le texte en chunks * vectoriser les chunks (appel au modèle d'embeddings) * stocker les chunks et leur représentation vectorielle dans la base de données vectorielle {% hint style="info" %} L'endpoint POST `/v1/documents` propose de nombreux paramètres pour configurer le traitement du document (chunking, métadonnées, etc.). Pour plus d'informations, consultez la page [API reference - Documents](https://guides.ia.numerique.gouv.fr/albert-api/api-reference/liste-des-endpoint/documents#post-v1-documents). {% endhint %} **Exemple de requête :** {% tabs %} {% tab title="curl" %} ```bash curl -sS "https://albert.api.etalab.gouv.fr/v1/documents" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/pdf" \ -F "file=@ma-collection.pdf" \ -F "collection_id=1234567890" ``` {% endtab %} {% tab title="Python" %} ```python import requests import os document = requests.post( url="https://albert.api.etalab.gouv.fr/v1/documents", headers={"Authorization": f"Bearer {os.environ['ALBERT_API_KEY']}"}, files={"file": ("ma-collection.pdf", open("ma-collection.pdf", "rb"), "application/pdf")}, data={"collection_id": "1234567890"}, ) document.raise_for_status() document_id = document.json()["id"] ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const baseUrl = "https://albert.api.etalab.gouv.fr/v1"; const apiKey = process.env.ALBERT_API_KEY; const form = new FormData(); form.append("file", new Blob(["REMPLACER_PAR_VOTRE_CONTENU_PDF"]), "ma-collection.pdf"); form.append("collection_id", "1234567890"); const res = await fetch(`${baseUrl}/documents`, { method: "POST", headers: { Authorization: `Bearer ${apiKey}` }, body: form, }); if (!res.ok) { throw new Error(`HTTP ${res.status}: ${await res.text()}`); } const document = await res.json(); const documentId = document.id; ``` {% endtab %} {% endtabs %} ### Rechercher des chunks à partir d'une question Pour rechercher des chunks à partir d'une question, vous pouvez utiliser l'endpoint `/v1/search`. Il est possible de modifier [la méthode de recherche](#les-différentes-méthodes-de-recherche) ou [les filtres de recherche](#les-filtres-de-recherche). **Exemple de requête :** {% tabs %} {% tab title="curl" %} ```bash curl -sS "https://albert.api.etalab.gouv.fr/v1/search" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "Quel est le sujet du document ?"}' ``` {% endtab %} {% tab title="Python" %} ```python import requests import os search = requests.post( url="https://albert.api.etalab.gouv.fr/v1/search", headers={"Authorization": f"Bearer {os.environ['ALBERT_API_KEY']}"}, json={"query": "Quel est le sujet du document ?"}, ) search.raise_for_status() search_results = search.json() ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const baseUrl = "https://albert.api.etalab.gouv.fr/v1"; const apiKey = process.env.ALBERT_API_KEY; const search = await fetch(`${baseUrl}/search`, { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ query: "Quel est le sujet du document ?" }), }); if (!search.ok) { throw new Error(`HTTP ${search.status}: ${await search.text()}`); } const searchResults = await search.json(); ``` {% endtab %} {% endtabs %} Il est aussi possible de dissocier la recherche du chat. Cela permet davantage de contrôle sur les chunks sélectionnés (filtrage, scoring, [rerank](https://doc.incubateur.net/alliance/albert-api/guides/reranking), etc.). 1. **Recherche** — `POST /v1/search` avec `query`, `collection_ids`, `method`, `limit`, etc. 2. **Prompt** — concaténation des `chunk.content` renvoyés pour construire le contexte. 3. **Chat** — `POST /v1/chat/completions` avec le prompt enrichi. ```python import os import requests from openai import OpenAI base_url = "https://albert.api.etalab.gouv.fr/v1" api_key = os.environ["ALBERT_API_KEY"] headers = {"Authorization": f"Bearer {api_key}"} client = OpenAI(base_url=base_url, api_key=api_key) ``` #### Les différentes méthodes de recherche L'endpoint POST `/v1/search` propose 3 méthodes de recherche configurables avec le paramètre `method` : * `semantic` (défaut) : recherche sémantique basée sur la similarité des vecteurs * `exact` : recherche exacte basée sur l'exactitude du texte * `hybrid` : la recherche hybride combine la similarité des vecteurs et la recherche exacte. Elle va classer les résultats des deux recherches par pertinence. #### Les filtres de recherche L'endpoint POST `/v1/search` propose des filtres de recherche configurables avec le paramètre `filters`. Par défaut, aucun filtre n'est appliqué et la recherche est effectuée sur toutes les collections et tous les documents. | Nom du filtre | Description | | ------------------ | ------------------------------------ | | `collection_ids` | Filtre les résultats par collection | | `document_ids` | Filtre les résultats par document | | `metadata_filters` | Filtre les résultats par métadonnées | ## Step 2 Construire un prompt avec le contexte trouvé Une fois les chunks trouvés avec l'endpoint POST `/v1/search`, vous pouvez construire un prompt avec le contexte trouvé. **Exemple de template de prompt :** ``` Réponds uniquement en t'appuyant sur les extraits fournis. [Question] { question } [Extraits] { extrait_1 } { extrait_2 } ... ``` ## Step 3 Envoyer le prompt au LLM (`/v1/chat/completions`) À partir du prompt construit à l'étape précédente, vous pouvez envoyer le prompt au LLM en utilisant l'endpoint POST `/v1/chat/completions`. **Exemple de requête :** {% tabs %} {% tab title="curl" %} ```bash curl -sS "https://albert.api.etalab.gouv.fr/v1/chat/completions" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "REMPLACER_PAR_ID_MODELE", "messages": [ {"role": "system", "content": "Réponds uniquement en t'\''appuyant sur les extraits fournis."}, {"role": "user", "content": "Quel est le sujet du document ?\n\n[Extraits]\n..."} ] }' ``` {% endtab %} {% tab title="Python" %} ```python import os from openai import OpenAI client = OpenAI( base_url="https://albert.api.etalab.gouv.fr/v1", api_key=os.environ["ALBERT_API_KEY"], ) r = client.chat.completions.create( model="REMPLACER_PAR_ID_MODELE", messages=[ {"role": "system", "content": "Réponds uniquement en t'appuyant sur les extraits fournis."}, {"role": "user", "content": "Quel est le sujet du document ?\n\n[Extraits]\n..."}, ], ) print(r.choices[0].message.content) ``` {% endtab %} {% tab title="JavaScript" %} ```javascript import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://albert.api.etalab.gouv.fr/v1", apiKey: process.env.ALBERT_API_KEY, }); const r = await client.chat.completions.create({ model: "REMPLACER_PAR_ID_MODELE", messages: [ { role: "system", content: "Réponds uniquement en t'appuyant sur les extraits fournis." }, { role: "user", content: "Quel est le sujet du document ?\n\n[Extraits]\n..." }, ], }); console.log(r.choices[0].message.content); ``` {% endtab %} {% endtabs %} # Reranking Albert API propose un endpoint POST `/v1/rerank` qui permet d'appeler des modèles de reranking. Ces modèles sont particulièrement intéressants pour améliorer votre pipeline de RAG (Retrieval Augmented Generation). {% hint style="info" %} Albert API propose un endpoint POST `/v1/rerank` sur les convention de l'API v2 de Cohere (voir [Cohere API - Reranking](https://docs.cohere.com/reference/rerank)). Cette convention permet de s'intégrer nativement dans la plupart des frameworks de IA générative comme par exemple [OpenWebUI](https://openwebui.com/). {% endhint %} **Dans ce tutoriel nous allons voir :** * **pourquoi utiliser un modèle de reranking,** * **qu'est-ce qu'un modèle reranking**, * **quand l'utiliser** * **comment l'utiliser.** ## Prérequis * Connaissance des notions de RAG, de vector-store, d'embeddings et de chunks * Connaissance de l'upload et de la recherche de documents avec Albert API. Pour en savoir plus sur ces notions, voir le guide [RAG - Génération Augmentée par Récupération](/albert-api/guides/rag). ## Pourquoi utiliser le reranking ? Lorsque vous construisez un système de RAG, vous devez : 1. Rechercher des documents pertinents dans un vector store 2. Sélectionner les meilleurs passages 3. Les envoyer au modèle de génération Le problème : la recherche vectorielle retourne souvent **des résultats approximatifs**. En effet, que ce soit avec une recherche sémantique, lexicale ou hybride, **la recherche dans un vector store est une recherche à larges mailles**. Elle permet ainsi de retrouver les *chunks* qui gravitent autour de la requête recherchée mais cela peut prendre dans le filet des chunks relativement éloignés contextuellement. En conséquence, un moteur vectoriel est très rapide, mais il peut retourner : * des résultats **un peu hors sujet** * des passages **moins pertinents que d'autres** * des résultats dans **un ordre sous-optimal** Ainsi si certains résultats de recherche sont pertinents, d'autres beaucoup moins. C'est précisément le rôle de l'endpoint **`/v1/rerank`** : **réordonner les résultats de recherche pour ne garder que les passages les plus pertinents pour une requête.** *** ## Qu'est ce que le reranking ? Le **reranking** utilise un petit modèle puissant pour : * comparer **la requête utilisateur** * avec **chaque document trouvé** * et produire **un score de pertinence** Albert API propose un modèle de reranking ***openweight-rerank***. Pour plus d'informations sur ce modèle, voir les [modèles disponibles](https://ia.numerique.gouv.fr/outils-ia/albert-api/mod%C3%A8les/). Pour connaître quels sont les modèles de reranking disponibles, faites une requête au endpoint `/v1/models` . Parmi ceux retourné, les modèles de reranking ont le type `text-classification`. {% hint style="info" %} Un modèle de reranking est généralement un modèle de classification de quelques millions de paramètres spécialement entraîné sur des paires questions-documents. Lors de son entrainement le modèle a appris à inférer sur la base de millions d'exemples des patterns permettant d'attribuer un score à la pertinence d'un document vis-à-vis d'une question. {% endhint %} ## Quand utiliser le reranking ? Le reranking est utile lorsque : * vous avez beaucoup de documents * le contexte du LLM est limité (ex : openweight-large) * les capacités du LLM à analyser un grand contexte sont limitées (ex : openweight-small) *** ## Comment utiliser le reranking ? ### Fonctionnement général L'endpoint `/v1/rerank` prend : * une **query** * une **liste de documents** et retourne les documents **triés par pertinence.** Chaque document reçoit un **score de pertinence**. ### Pipeline de RAG avec le reranking Si vous souhaitez un RAG avec 5 chunks pour augmenter le contexte de la requête utilisateur, alors dans un premier temps récupérez 40 chunks proches avec `/v1/search`. Puis vous affinez avec `/v1/rerank` pour obtenir les 5 chunks les plus pertinents. 
graph TD
  user_request(Requête utilisateur)
  response(Réponse)
  
  
  user_request 
  --> /v1/search 
  --"40 chunks" --> /v1/rerank 
  -- "5 chunks" --> /v1/chat/completions 
  --> response
### Étape 1. Recherche vectorielle On commence par récupérer les documents les plus proches de la requête utilisateur. {% tabs %} {% tab title="Python" %} ```python import os import requests response = requests.post( url="https://api.albert.etalab.gouv.fr/v1/rerank", headers={"Authorization": f"Bearer {os.environ.get('ALBERT_API_KEY')}"}, json={ "query": "Comment déployer une application Docker ?", "method": "semantic", "limit": 40, }, ) data = response.json()["data"] chunks = [chunk.content for chunk in data.chunk] ``` {% endtab %} {% endtabs %} À ce stade, les documents sont **proches sémantiquement**, mais pas forcément les plus pertinents pour répondre précisément à la question. C’est pourquoi on ajoute une étape de **reranking**. {% hint style="info" %} Le reranking est utile quelque soit la méthode de recherche utilisée (sémantique, lexicale, hybride). Attention toutefois, il peut être inutile, voir contre-productif. Voir les [bonnes pratiques](#bonnes-pratiques) pour plus d'informations. {% endhint %} ### Étape 2. Reranking Le reranker réévalue les documents retournés par la recherche vectorielle afin de déterminer **les plus pertinents pour la requête**. {% tabs %} {% tab title="Python" %} ```python import os import requests user_query = "Comment déployer une application Docker ?" response = requests.post( url="https://api.albert.etalab.gouv.fr/v1/rerank", headers={"Authorization": f"Bearer {os.environ.get('ALBERT_API_KEY')}"}, json={ "model": "openweight-rerank", "query": user_query, "documents": chunks, "top_n": 5, }, ) data = response.json() ``` {% endtab %} {% endtabs %} **Réponse** ```json { "results": [ { "index": 2, // Position du document dans la liste d'entrée "relevance_score": 0.98 // Score de pertinence calculé par le modèle }, ... ] } ``` ### Étape 3. Reconstruction des documents triés On récupère les documents dans le bon ordre à partir des indices retournés. {% tabs %} {% tab title="Python" %} ``` ranked_chunks = [chunks[result["index"]] for result in data["results"]] ``` {% endtab %} {% endtabs %} ### Étape 4. Génération avec le contexte On injecte les documents les plus pertinents dans le prompt du LLM comme *openweight-small* par exemple. {% tabs %} {% tab title="Python" %} ```python rag_template = """Réponds à la question en te basant sur les documents suivants. Si la réponse à la question n'est pas dans les documents, indique que tu ne t'es pas appuyé sur ces documents pour générer la réponse, sinon cite les sources de ta réponse. [QUESTION] {user_query} [DOCS] {chunks} """ query = rag_template % {"user_query": user_query, "chunks": "\n\n".join(chunks)} response = requests.post( url="https://api.albert.etalab.gouv.fr/v1/chat/completions", headers={"Authorization": f"Bearer {os.environ.get('ALBERT_API_KEY')}"}, json={ "model": "openweight-small", "messages": [{"role": "user", "content": query}], }, ) data = response.json() ``` {% endtab %} {% endtabs %} Le modèle utilise alors **le contexte fourni pour générer une réponse plus fiable et précise**. *** ## Bonnes pratiques ### 1. Reranker plus de documents que nécessaire Pipeline recommandée : * Search : limit = 20 à 50 * Rerank : top\_n = 3 à 10 Cela permet au reranker de choisir les documents les plus pertinents parmi un ensemble suffisamment large. ### 2. Utiliser des chunks courts La qualité du reranking dépend fortement de la taille des documents. Nous recommandons 100 à 500 tokens par chunk. Les documents trop longs diluent l’information importante et réduisent la précision du reranker. ### 3. Le reranking peut être inutile ou contre-productif Le reranking est un outil puissant, mais il ne faut pas l'utiliser à chaque fois. Vous devez déterminer si le reranking est nécessaire pour votre cas d'usage en testant des requêtes sur vos documents. Par exemple, la recherche hybride peut obtenir des scores de pertinence dans certains cas plus précis que le reranking. Dans ce cas, ce dernier va éliminer des documents pertinents. Comme pour toute technique, il faut tester et mesurer les performances à l'aide d'un processus de d'évaluation. # Connecter un agent de code à Albert API Albert API expose une API compatible OpenAI. Vous pouvez donc configurer la plupart des agents de code (en terminal et dans votre éditeur) pour qu'ils utilisent les modèles souverains de l'État hébergés sur AlbertAPI Cette page liste les configurations pour les principaux outils actuels. ## Principe général Albert API répond sur `POST /v1/chat/completions`. Tout outil capable d'appeler un point d'accès compatible OpenAI, avec une URL de base et une clé configurables, fonctionne. * URL de base : `https://albert.api.etalab.gouv.fr/v1` * Clé : votre clé Albert API, à obtenir sur Ne mettez jamais votre clé dans un fichier de configuration versionné. Passez par une variable d'environnement. ## Choix des modèles Le catalogue de modèles évolue régulièrement (ajout, suppression) et les identifiants des modèles peuvent changer de version. Les identifiants cités sur cette page servent d'exemple. Avant de configurer un outil, consultez : * la page [Modèles disponibles](https://guides.ia.numerique.gouv.fr/albert-api/modeles/available-models) pour les modèles, leurs capacités et leurs fenêtres de contexte ; * le [Changelog](https://guides.ia.numerique.gouv.fr/albert-api/ressources/changelog) pour les ajouts, retraits et migrations annoncés. Récupérez ensuite l'identifiant exact avec la liste des modèles, et utilisez le champ **`id`**, pas une valeur du champ `aliases` : les alias sont une commodité d'affichage et changent sans préavis. ```bash curl -s https://albert.api.etalab.gouv.fr/v1/models \ -H "Authorization: Bearer $ALBERT_API_KEY" \ | jq -r '.data[] | select(.type=="text-generation" or .type=="image-text-to-text") | .id' ``` Pour du code agentique, choisissez un modèle qui prend en charge les appels d'outils (voir [Function calling & outils](https://guides.ia.numerique.gouv.fr/albert-api/guides/function-calling)) et dispose d'une fenêtre de contexte large. Les exemples ci-dessous utilisent `deepseek-v4-flash-0731` (131 072 tokens de contexte au 16 septembre 2026). ## OpenCode (terminal) * Site officiel et installation : * Documentation de configuration : * Fichier de configuration utilisateur : `~/.config/opencode/opencode.json` ```json { "$schema": "https://opencode.ai/config.json", "model": "albert/deepseek-v4-flash-0731", "small_model": "albert/deepseek-v4-flash-0731", "provider": { "albert": { "npm": "@ai-sdk/openai-compatible", "name": "Albert API (DINUM)", "options": { "apiKey": "{env:ALBERT_API_KEY}", "baseURL": "https://albert.api.etalab.gouv.fr/v1" }, "models": { "deepseek-v4-flash-0731": { "name": "DeepSeek V4 Flash (Albert)", "tool_call": true, "reasoning": true, "limit": { "context": 131072, "output": 32768 }, "options": { "chat_template_kwargs": { "thinking": true } } } } } } } ``` Sous Windows avec Git Bash, ajoutez `"shell": "C:\\Program Files\\Git\\bin\\bash.exe"` à la racine du fichier. Sous macOS et Linux, cette clé est inutile. ## Pi (terminal) * Site officiel et installation : * Documentation de configuration : * Fichier de configuration utilisateur : `~/.pi/agent/models.json` ```json { "providers": { "albert": { "baseUrl": "http://127.0.0.1:8080/v1", "api": "openai-completions", "apiKey": "none", "compat": { "supportsDeveloperRole": false, "maxTokensField": "max_tokens" }, "models": [ { "id": "deepseek-v4-flash-0731", "name": "Albert · DeepSeek V4 Flash", "reasoning": false, "input": ["text"], "contextWindow": 131072, "maxTokens": 32768 }, { "id": "gpt-oss-120b", "name": "Albert · gpt-oss 120B", "reasoning": true, "input": ["text"], "contextWindow": 131072, "maxTokens": 32768, "compat": { "thinkingFormat": "reasoning_effort" } } ] } } } ``` **Pour fonctionner avec Albert API Pi doit utiliser un proxy afin que l'ensemble des tools call fonctionnent.** \ Pour faire fonction Pi, nous préconisons l'utilisation de **llm-proxy**, un proxy local développé par Jérôme Bousquié (Université Toulouse Capitole) et Olivier Booklage (académie de Bordeaux), sous Licence Ouverte 2.0 (Etalab), maintenu par ses auteurs et non par la DINUM. Llm-proxy remet les appels d'outils au format attendu par l'agent, absorbe les limites de débit (il patiente au lieu de renvoyer une erreur) et réessaie en cas d'indisponibilité passagère d'AlbertAPI. C'est lui qui détient votre clé Albert : Pi n'en a pas besoin, d'où `"apiKey": "none"`. * Dépôt et documentation : * Guide dédié à Pi : Pour l'installer, téléchargez une archive sur la page des releases du dépôt, ou compilez-le (Rust 1.85 ou plus récent) avec `cargo build --release`. Créez ensuite un fichier `.env` à côté du binaire, sur le modèle du `.env.example` fourni : ```bash ALBERT_API_KEY=votre_clé_albert STREAM_ENABLED=false ``` Lancez `llm-proxy` (il écoute sur `http://127.0.0.1:8080`) et laissez-le tourner pendant toute votre session Pi. `STREAM_ENABLED=false` correspond à la configuration que nous avons testée. ## Cline (terminal) Site officiel et installation : * Documentation de configuration : * Fichier de configuration utilisateur : `~/.cline/data/settings/providers.json` ```json { "version": 1, "lastUsedProvider": "openai-compatible", "providers": { "openai-compatible": { "settings": { "provider": "openai-compatible", "apiKey": "votre_clé_albert", "model": "deepseek-v4-flash-0731", "baseUrl": "https://albert.api.etalab.gouv.fr/v1" } } } } ``` ## Kilo Code (terminal) * Site officiel et installation : * Documentation de configuration : * Fichier de configuration utilisateur : `~/.config/kilo/kilo.jsonc` ```jsonc { "$schema": "https://app.kilo.ai/config.json", "model": "albert/deepseek-v4-flash-0731", "provider": { "albert": { "npm": "@ai-sdk/openai-compatible", "name": "Albert API (DINUM)", "options": { "apiKey": "{env:ALBERT_API_KEY}", "baseURL": "https://albert.api.etalab.gouv.fr/v1" }, "models": { "deepseek-v4-flash-0731": { "name": "DeepSeek V4 Flash (Albert)", "tool_call": true, "limit": { "context": 131072, "output": 32768 } } } } } } ``` ## Dans un IDE (VS Code, Cursor, etc.) ### Avec l'extension OpenCode Si vous avez déjà configuré OpenCode comme ci-dessus alors l'extension officielle OpenCode fonctionne dans **VS Code, Cursor, Windsurf et VSCodium**. Elle s'installe automatiquement la première fois que vous lancez `opencode` dans le terminal intégré de l'éditeur, ou manuellement depuis la place de marché des extensions. Elle apporte le raccourci d'ouverture, le partage automatique de votre sélection ou de l'onglet courant avec l'agent, et l'insertion de références de fichiers du type `@Fichier#L37-42`. Documentation : ### Les extensions Cline et Kilo Code Cline et Kilo Code proposent aussi en extension pour VS Code, Cursor, Windsurf, VSCodium et JetBrains. Si vous avez configuré l'outil comme expliqué précédemment vous n'avez rien d'autre à régler. * **Cline** : recherchez « Cline » dans le panneau des extensions (`Ctrl+Shift+X` ou `Cmd+Shift+X`). Vous pouvez aussi configurer Albert API depuis ses réglages : **API Provider** `OpenAI Compatible`, puis **Base URL**, **API Key** et **Model ID**. À la première ouverture, Cline propose de se connecter à son propre service : ce n'est pas nécessaire avec votre clé AlbertAPI.\ Documentation : * **Kilo Code** : recherchez « Kilo Code » ; sous VS Code, choisissez **Install Pre-Release Version** dans le menu du bouton **Install** (canal recommandé par l'éditeur). Vous pouvez aussi configurer Albert API depuis **Settings** → **Providers** → **Custom provider** (Provider API : `OpenAI Compatible`).\ Documentation : ## GitHub Copilot Simon Roux maintient une extension VS Code qui **enregistre AlbertAPI comme fournisseur de modèles à l'intérieur de GitHub Copilot Chat**. Ce n'est pas une extension autonome : elle suppose que GitHub Copilot est déjà installé et connecté, et VS Code en version 1.125 ou ultérieure. ### Compatibilité “théorique” (non garantie) De façon générale, **n’importe quel plugin / IDE** capable d’appeler un modèle via `POST /v1/chat/completions`, et/ou un SDK “OpenAI” peut **théoriquement** fonctionner avec Albert API. En revanche, nous ne pouvons pas **garantir** la compatibilité de toutes les combinaisons outil/IDE, ni les champs supportés par chaque client. ## Ce qui ne fonctionne pas par défaut Albert API ne répond pas sur ces endpoints : * `POST /v1/responses`, le format récent d'OpenAI, utilisé notamment par Codex CLI * `POST /v1/messages`, le format d'Anthropic, utilisé par Claude Code * `POST /v1/completions`, le format historique utilisé pour l'autocomplétion Ces outils ne peuvent donc pas être branchés directement sur Albert API. llm-proxy (voir la section Pi ci-dessus) expose ces formats en local et les traduit vers Albert API. Le dépot de llm-proxy contient un guide par outil. # Clefs API Albert API utilise un système de clef pour authentifier vos requêtes. Ces clefs sont des **Bearer** tokens, une chaine de caractères alphanumérique unique et secrète commencant par `sk-`. **Ces clefs d'API doivent être stockées en lieu sécurisé et ne doivent jamais être divulguées.** ### Création d'une clef Vous pouvez créer des clefs d'API de 2 manières, par API ou sur le Playground. {% tabs %} {% tab title="Playground" icon="globe-pointer" %} Connectez-vous sur le [playground](https://albert.playground.gouv.fr/), rendez-vous dans la page *API Keys* et cliquez sur le bouton *Create key*.
**Attention, la clef est affichée intégralement une seule fois à la création.** Vous devez la copier dans un endroit sécurisé. {% endtab %} {% tab title="API" icon="square-terminal" %} Vous pouvez créer une clef d'API en appelant le endpout POST `/v1/keys`. **Attention, vous devez disposer d'une clef API existante pour créer une nouvelle clef.** Cette méthode de création est utilisée pour renouveler des clefs de manière automatique. Si vous ne disposez pas d'une clef API existante, vous pouvez en créer une sur le Playground. Remplacez `$ALBERT_API_KEY` par une clef non expirée dans la commande ci-dessous. ``` curl -X POST "https://albert.api.etalab.gouv.fr/v1/keys" \ -H "Authorization: Bearer $ALBERT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "my-new-key", "expires": null}' ``` Pour en savoir plus sur les endpoints `/v1/keys`, consultez l'API Reference [ici](https://guides.ia.numerique.gouv.fr/albert-api/api-reference/liste-des-endpoint/keys). {% endtab %} {% endtabs %} ### Expiration des clefs **Toutes les clefs API ont une date d'expiration de maximum 1 an à compter de la date de création.** Vous pouvez configurer une clef avec une date d'expiration inférieure à 1 an lors de la création. Il est en revanche impossible d'obtenir une clef sans expiration pour des raisons de sécurité. **Exemple de requête :** ### Consulter ses clefs {% tabs %} {% tab title="Playground" icon="globe-pointer" %} Vous pouvez consulter vos clefs sur la page *API Keys* du [Playground](https://albert.playground.gouv.fr/). {% endtab %} {% tab title="API" icon="square-terminal" %} Vous pouvez consulter vos clefs en appelant le endpoint GET `/v1/keys`. Remplacez `$ALBERT_API_KEY` par une clef non expirée dans la commande ci-dessous. ``` curl -X GET "https://albert.api.etalab.gouv.fr/v1/keys" \ -H "Authorization: Bearer $ALBERT_API_KEY" ``` Vous pouvez également récupérer le détail d'une clef en appelant le endpoint GET `/v1/keys/{key}`. ``` curl -X GET "https://albert.api.etalab.gouv.fr/v1/keys/{key}" \ -H "Authorization: Bearer $ALBERT_API_KEY" ``` Remplacez `{key}` par l'identifiant de la clef que vous souhaitez récupérer. Pour en savoir plus sur les endpoints `/v1/keys`, consultez l'API Reference [ici](https://guides.ia.numerique.gouv.fr/albert-api/api-reference/liste-des-endpoint/keys). {% endtab %} {% endtabs %} ## Révoquer une clef {% tabs %} {% tab title="Playground" icon="globe-pointer" %} Vous pouvez révoquer une clef sur la page *API Keys* du [Playground](https://albert.playground.gouv.fr/) en cliquant sur le bouton *Delete* de la clef que vous souhaitez révoquer.
**Attention, cette action est irréversible.** Une fois une clef révoquée, elle ne peut plus être utilisée. {% endtab %} {% tab title="API" icon="square-terminal" %} Vous pouvez révoquer une clef en appelant le endpoint DELETE `/v1/keys/{key}`. ``` curl -X DELETE "https://albert.api.etalab.gouv.fr/v1/keys/{key}" \ -H "Authorization: Bearer $ALBERT_API_KEY" ``` Remplacez `{key}` par l'identifiant de la clef que vous souhaitez révoquer et `$ALBERT_API_KEY` par une clef non expirée dans la commande ci-dessous. **Attention, cette action est irréversible.** Une fois une clef révoquée, elle ne peut plus être utilisée. Pour en savoir plus sur les endpoints `/v1/keys`, consultez l'API Reference [ici](https://guides.ia.numerique.gouv.fr/albert-api/api-reference/liste-des-endpoint/keys). {% endtab %} {% endtabs %} ### Limites de consommation Toutes vos clefs d'API partagent les mêmes limites de consommation. En effet, ces limites sont appliquées au niveau de votre utilisateur. Pour en savoir plus sur les limites de consommation, consultez la section [Quotas & limites](/albert-api/compte-and-usage/quotas). # Quotas & limites Chaque compte dispose de limites de consommation. Ces limites sont configurées par l'administration de la plateforme. Elles sont de 2 types : limites par token et limites par requête. Vous pouvez consulter les limites par token et par requête pour chaque modèle en cliquant [ici](https://ia.numerique.gouv.fr/outils-ia/albert-api/tarifs-et-limites/). ### Limites par token Dans Albert API, les limites par tokens sont exprimées en **tokens par minute (TPM) et par jour (TPD)**. Vous pouvez consulter les limites par token pour chaque modèle en cliquant [ici](https://ia.numerique.gouv.fr/outils-ia/albert-api/tarifs-et-limites/). #### Qu'est ce qu'un token ? Un token est une unité de mesure de la consommation des LLM. Un token correspond à un mot ou une partie de mot. Exemple : * "Albert" → 1 token * "centraliser" → 2 tokens ("centr" et "aliser") {% hint style="info" %} La ponctuation est comptabilisée comme un token ! {% endhint %} Le *tokenizer*, c'est-à-dire l'algorithme permettant de transformer le texte en tokens, est généralement celui du modèle utilisé. Sur Albert API, pour que toutes les requêtes soient comptabilisées dans les mêmes conditions, nous utilisons un tokenizer opensource, [*Tiktoken o200k\_base*](https://github.com/openai/tiktoken). Vous pouvez tester le tokenizer sur des textes sur [ce simulateur](https://tiktokenizer.vercel.app/?model=o200k_base). #### Comment sont comptabilisés les tokens ? Les tokens sont comptabilisés uniquements sur des endpoints suivants : `/v1/chat/completions`, `/v1/embeddings` et `/v1/rerank`. Ils sont comptabilisés différement selon les endpoints. * `/v1/chat/completions` Les tokens sont comptabilisés **uniquement sur les messages** de la requête, pas les tokens générés par le modèle. Voici un exemple de requête qui est comptabilisée comme 37 tokens: ```json { "model": "openweight-large", "messages": [ { "role": "system", "content": "Tu es un assistant de chat qui répond à des questions." → 12 tokens }, { "role": "user", "content": "Bonjour, comment allez-vous ?" → 6 tokens } { "role": "assistant", "content": "Je vais bien, merci pour votre question." → 9 tokens } { "role": "user", "content": "Quel est votre nom ?" → 5 tokens } { "role": "assistant", "content": "Je m'appelle Albert." → 5 token } ] } ``` * `/v1/embeddings` Les tokens sont comptabilisés **uniquement sur les inputs** de la requête. Voici un exemple de requête qui est comptabilisée comme 23 tokens: ```json { "model": "openweight-embeddings-large", "input": [ "Albert API est un outil de IA open source.", → 10 tokens "Il est développé par la communauté de l'IA open source." → 13 tokens ] } ``` * `/v1/rerank` Les tokens sont comptabilisés **uniquement sur le query et les documents** de la requête. Voici un exemple de requête qui est comptabilisée comme 33 tokens: ```json { "model": "openweight-rerank-large", "query": "Albert API est un outil de IA open source.", → 10 tokens "documents": [ "Albert API est un outil de IA open source.", → 10 tokens "Il est développé par la communauté de l'IA open source." → 13 tokens ] } ``` ### Limites par requête Dans Albert API, les limites par requêtes sont exprimées en **requêtes par minute (RPM) et par jour (RPD)**. Vous pouvez consulter les limites par requête pour chaque modèle en cliquant [ici](https://ia.numerique.gouv.fr/outils-ia/albert-api/tarifs-et-limites/). ### Qu'est ce qu'une requête ? Une requête est un appel à un endpoint d'Albert API. Les requêtes sont comptabilisées uniquement sur les endpoints qui appellent un modèle : * `/v1/chat/completions` * `/v1/embeddings` * `/v1/rerank` * `/v1/audio/transcriptions` * `/v1/ocr` ### Consulter sa consommation Il y a 2 façons de consulter sa consommation : * via le Playground Albert API sur la page [Usage](https://albert.playground.etalab.gouv.fr) * via l'API en appelant l'endpoint [GET /v1/me/usage](https://guides.ia.numerique.gouv.fr/albert-api/api-reference/liste-des-endpoint/me#get-v1-me-usage) ```bash curl -X GET "https://albert.playground.etalab.gouv.fr/v1/me/usage" \ -H "Authorization: Bearer $API_KEY" ``` ### Dépassement de limites Lorsque le trafic ou les tokens dépassent les plafonds configurés pour votre compte, l’API peut répondre **429 Too Many Requests** (détail dans le corps ou les en-têtes selon la version). Stratégie recommandée : **backoff exponentiel**, respect éventuel d’un en-tête **`Retry-After`**, et réduction du parallélisme. {% hint style="warning" %} ⚠️ À vérifier — Codes HTTP exacts (429 vs autre) et format du `detail` pour les dépassements sur l’instance Albert : consulter la page de l’endpoint **Me** : [page de l’endpoint Me](https://doc.incubateur.net/alliance/albert-api/api-reference/liste-des-endpoint/me) {% endhint %} ### Quotas “tarifs” (par famille de modèles) En complément de vos limites propres au compte (champ `limits` dans `GET /v1/me/info`), la page officielle **Tarifs et limites** fournit une vue indicative par type de modèle et par niveau d’accès (**expérimentation** vs **production**). [Tarifs et limites](https://ia.numerique.gouv.fr/outils-ia/albert-api/tarifs-et-limites/) | Famille de modèles (ex.) | Accès | RPM | RPD | TPM | TPD | | -------------------------------------------------- | --------------- | ---- | -------- | -------- | --------- | | `openai/gpt-oss-120b` (chat) | expérimentation | 10 | 1000 | 128 000 | 1 280 000 | | `openai/gpt-oss-120b` (chat) | production | 50 | 5000 | 246 000 | Illimité | | `mistralai/Mistral-Small-*` / `Ministral-*` (chat) | expérimentation | 50 | 1000 | 128 000 | 2 460 000 | | `mistralai/Mistral-Small-*` / `Ministral-*` (chat) | production | 100 | 50 000 | 246 000 | illimité | | `Qwen/Qwen3-Coder-*` (code) | expérimentation | 50 | 1000 | 128 000 | 2 460 000 | | `Qwen/Qwen3-Coder-*` (code) | production | 100 | 50 000 | 246 000 | illimité | | `deepseek-ai/DeepSeek-V4-Flash` (code) | expérimentation | 50 | illimité | 246 000 | illimité | | `deepseek-ai/DeepSeek-V4-Flash` (code) | production | 50 | illimité | 246 000 | illimité | | `openai/whisper-large-v3` (audio) | expérimentation | 50 | 1000 | illimité | illimité | | `openai/whisper-large-v3` (audio) | production | 100 | 5000 | illimité | illimité | | `BAAI/bge-m3` (embeddings) | expérimentation | 500 | 50 000 | illimité | illimité | | `BAAI/bge-m3` (embeddings) | production | 2000 | 200 000 | illimité | illimité | | `Qwen/Qwen3-VL-*` (embeddings) | expérimentation | 50 | 1000 | illimité | illimité | | `Qwen/Qwen3-VL-*` (embeddings) | production | 100 | 50 000 | illimité | illimité | | `BAAI/bge-reranker-v2-m3` (rerank) | expérimentation | 500 | 50 000 | illimité | illimité | | `BAAI/bge-reranker-v2-m3` (rerank) | production | 2000 | 200 000 | illimité | illimité | | `lightonocr-2-1b` (ocr) | expérimentation | 50 | 1000 | 128 000 | 2 460 000 | | `lightonocr-2-1b` (ocr) | production | 100 | 50 000 | 246 000 | illimité | {% hint style="warning" %} ⚠️ À vérifier — la page “tarifs” peut évoluer. Les compteurs `Limit` dans `GET /v1/me/info` restent la source de vérité opérationnelle. {% endhint %} ### Budget (`UserInfo.budget`) * Valeur **numérique** — enveloppe budgétaire restante ou autorisée selon les règles plateforme (coûts agrégés). * **`null`** — d’après la spec, **budget illimité** côté modèle de données (cela ne supprime pas d’éventuelles limites techniques `limits`). ### Qui configure les limites ? Les champs `limits`, `budget`, `priority` et droits associés sont **fixés par l’administration de la plateforme** (ou les mécanismes internes liés à votre compte organisationnel). Ils ne sont en général **pas modifiables** par simple appel public documenté ici. {% hint style="warning" %} ⚠️ À vérifier — Interprétation monétaire précise du `budget`, fenêtres temporelles des compteurs (`tpd`, `rpd`) et comportement lorsque plusieurs limites entrent en conflit : demander la fiche d’exploitation à votre référent ou consulter les engagements contractuels. {% endhint %} Pour suivre la consommation réelle : [Usage & facturation](/albert-api/compte-and-usage/usage). # Usage & facturation L’endpoint **`GET /v1/me/usage`** retourne l’historique de consommation du compte authentifié. ## Paramètres de requête * **`start_time`** — timestamp Unix **début** ; si absent, la spec indique un défaut à **30 jours avant** l’instant présent. * **`end_time`** — timestamp Unix **fin** ; si absent, défaut à **maintenant**. * **`endpoint`** — filtre optionnel sur un **sous-ensemble** d’endpoints :\ `/v1/audio/transcriptions`, `/v1/chat/completions`, `/v1/embeddings`, `/v1/ocr`, `/v1/rerank`, `/v1/search`. * **`offset`**, **`limit`** — pagination des enregistrements d’usage. ## Objet `Usage` (élément de liste) Chaque entrée peut inclure notamment : * **`model`**, **`key`**, **`endpoint`**, **`method`**, **`status`** — contexte de la requête ; * **`created`** — horodatage Unix (secondes) ; * **`usage`** — objet **`UsageDetail`** avec agrégats de jetons, coût, empreinte carbone et métriques. ## `UsageDetail` * **`prompt_tokens`**, **`completion_tokens`**, **`total_tokens`** — compteurs de jetons ; * **`cost`** — coût total attribué à l’appel (unité et politique internes à la plateforme) ; * **`carbon`** — objet **`CarbonFootprintUsage`** avec : * **`kWh`** — `min` / `max` ; * **`kgCO2eq`** (objet min/max d’équivalent **CO₂**, GWP). * **`metrics`** — champs comme **`latency`**, **`ttft`** (temps jusqu’au premier token) lorsque disponibles. {% hint style="info" %} Le volet **empreinte carbone** (kWh et kgCO₂eq avec fourchettes min/max) est une particularité utile pour les bilans environnementaux des services qui s’appuient sur Albert API. Côté moteur OpenGateLLM, les estimations peuvent s’appuyer sur des bibliothèques du type **EcoLogits** ; les valeurs retournées par l’API restent **indicatives** et dépendent des paramètres de modèle et d’hébergement configurés sur la plateforme. {% endhint %} ## Conteneur de réponse La réponse **`Usages`** renvoie un tableau `data` d’objets `Usage`. Pour le détail des champs optionnels, ouvrez les schémas `Usages`, `Usage` et `UsageDetail` dans la page de l’endpoint **Me** : [page de l’endpoint Me](https://doc.incubateur.net/alliance/albert-api/api-reference/liste-des-endpoint/me). Pour les plafonds appliqués à votre compte : [Quotas & limites](/albert-api/compte-and-usage/quotas). # Absence de rétention des données métier sur le chemin d'inférence L'inférence Albert API est une offre "zero data retention" : elle ne stocke aucune donnée métier. *Mise à jour : 2/9/2026* ### 1. Objet et périmètre Albert API est le point d'accès interministériel mutualisé à des modèles d'intelligence artificielle, opéré par la DINUM sur infrastructures Outscale (SecNumCloud, tenant DINUM) et Nubo (DGFIP). Le produit, présenté sous forme d'API, est formé de deux parties qui peuvent être utilisées indépendamment. D'une part, **l'inférence**, c'est-à-dire les appels aux *endpoints* de génération de texte, de complétion, d'*embeddings*, de code et de transcription audio, quel que soit le modèle appelé et quelle que soit l'infrastructure qui le porte. D'autre part, des **fonctions de RAG** (collections, dépôt de documents, *chunking*, base vectorielle, recherche documentaire). Ces fonctions reposent, par construction, sur la persistance des documents versés par l'administration utilisatrice : elles ne relèvent pas d'un régime de non-rétention et font l'objet d'une documentation distincte. Une administration qui n'utilise que les *endpoints* d'inférence n'active aucune de ces fonctions. **Le périmètre de la présente note est exclusivement l'inférence.** ### 2. Définition retenue Est qualifié de **donnée métier** tout contenu transmis par l'administration utilisatrice ou produit pour elle : texte des requêtes (*prompts*), texte des réponses générées (*complétions*), textes soumis à vectorisation, fichiers transmis en entrée. **Engagement :** sur le périmètre défini au point 1, aucune donnée métier n'est écrite sur un support de stockage durable, **à aucune fin** : ni supervision, ni suivi des usages, ni *monitoring* technique, ni filtrage de contenu (*guardrails*), ni sécurité, ni amélioration ou entraînement de modèles ou du service. La donnée métier n'existe qu'en mémoire des processus qui la traitent, pour la seule durée de traitement de la requête. Elle n'est ni journalisée, ni mise en cache persistant, ni indexée, ni tracée, ni exportée vers un tiers. ### 3. Ce qui est effectivement conservé : des métadonnées, sans contenu La non-rétention porte sur le contenu, non sur l'existence des appels. Le service conserve un jeu restreint de métadonnées, nécessaires à l'application des quotas, au dimensionnement de la capacité et au suivi de l'exploitation. La liste ci-dessous est exhaustive. | Métadonnée conservée | Finalité | Durée de conservation | | ------------------------------------------------- | ------------------------------------- | --------------------- | | Horodatage de la requête | Exploitation, capacité | 24 mois | | Identifiant du compte / de la clé d'API appelante | Quotas, suivi d'usage par entité | 24 mois | | Nom du modèle et *endpoint* appelé | Capacité, pilotage de l'offre | 24 mois | | Nombre de *tokens* en entrée et en sortie | Quotas, capacité, facturation interne | 24 mois | | Code de retour HTTP, latence, durée de génération | Supervision, qualité de service | 24 mois | | Adresse IP source | Sécurité, limitation de débit | 24 mois | Aucune de ces métadonnées ne permet, seule ou par recoupement, de reconstituer le contenu d'une requête ou d'une réponse. ### 4. Administration **Accès des administrateurs.** L'exploitation s'effectue via un accès administrateur nominatif et tracé, transitant par un bastion et un tunnel chiffré, depuis des postes d'administration dédiés dits *Securix*, durcis par la cellule cybersécurité de la DINUM en collaboration avec l'ANSSI. Ces postes sont indispensables pour accéder aux infrastructures de production et d'administration sur Nubo et Outscale : aucun accès n'est possible depuis un poste bureautique ordinaire. Cet accès porte sur les machines et les composants d'exploitation ; il n'ouvre sur aucun magasin contenant des données métier d'inférence, puisqu'il n'en existe aucun. **Absence de tiers.** Les modèles à poids ouverts sont hébergés et exécutés sur les infrastructures précitées. Aucun appel n'est émis vers un fournisseur de modèle externe : le contenu des requêtes ne quitte jamais le périmètre Outscale SecNumCloud / Nubo. ### 5. Conséquences opérationnelles Ce choix d'architecture est structurant et emporte des conséquences que l'administration utilisatrice doit intégrer : * **aucune restitution a posteriori** n'est possible — ni d'une conversation, ni d'un contenu produit : la DINUM ne peut pas fournir ce qu'elle ne conserve pas ; * **aucune analyse de contenu a posteriori** n'est possible en cas d'incident de sécurité ou de signalement d'usage abusif ; la maîtrise des usages, la modération et la journalisation applicative, si elles sont requises, relèvent de l'application appelante et de l'administration qui l'opère ; * **la DINUM intervient en qualité de sous-traitant au sens de l'article 28 du RGPD.** L'administration utilisatrice demeure responsable de traitement : elle définit les finalités et les données transmises. La DINUM n'accède à aucune donnée à caractère personnel contenue dans les requêtes, ne les conserve pas et n'en fait aucun usage propre ; * **aucune réutilisation** des contenus, en particulier à des fins d'entraînement, d'ajustement ou d'évaluation de modèles, n'est possible ni pratiquée. ### 6. Vérifiabilité Les affirmations de cette note sont vérifiables par l'administration utilisatrice. La DINUM s'engage à fournir sur demande: 1. **le code source de la passerelle**, publié et auditable en permanence : . 2. **les éléments du dossier de sécurité** relatifs à l'hébergement et à l'homologation : . 3. **un atelier technique** avec l'équipe Albert API, pour instruire les questions résiduelles d'une analyse d'impact relative à la protection des données. ### Annexe 1 : flux de données sur le chemin d'inférence pure ![image.png](https://docs.numerique.gouv.fr/media/39a3bba6-80ad-4760-a153-a81596784222/attachments/67db652b-d86b-4d4e-a520-cf46d66eb4d4.png) *Les flux en trait plein transportent de la donnée métier ; ils sont éphémères. Les flux en pointillés transportent exclusivement des métadonnées et sont les seuls à alimenter un stockage durable.* ### Annexe 2 : traitement du contenu, composant par composant | Composant | Rôle | Voit le contenu | Écrit le contenu | | --------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | *Reverse proxy* (nginx) | Terminaison TLS, routage | En transit | Non. Journalisation des corps de requête désactivée. Mise en tampon transitoire sur disque détruit à la fin de la requête | | API Albert (OpenGateLLM / FastAPI) | Authentification, quotas, routage vers les modèles | Oui, en mémoire | Non | | Base de données relationnelle (PostgreSQL) | Comptes, clés d'API, quotas, compteurs | Non | Non | | Cache technique (Redis) | Sessions, compteurs de limitation de débit | Non | Non | | Moteurs d'inférence (vLLM) | Exécution des modèles | Oui, en mémoire vive et mémoire GPU | Non. Journalisation des requêtes désactivée ; *KV-Cache* en mémoire GPU, non persisté, détruit à l'arrêt du processus (voir Annexe 3) | | Base vectorielle (Elasticsearch) | RAG uniquement | Non sollicitée sur le périmètre inférence | Sans objet | | Collecte et agrégation de journaux (Promtail, Loki) | Journaux applicatifs et système | Non. Les journaux collectés sont dépourvus de contenu métier | Non | | Métrologie (Prometheus, Grafana, Node Exporter) | Séries temporelles numériques | Non | Non | | Observabilité LLM (Langfuse) | Suivi des appels, explicitement configuré pour ignorer le contenu des requêtes | Non | Non | | Sondes de disponibilité (Gatus) | Tests synthétiques | Requêtes de test générées par le service, sans donnée d'utilisateur | Sans objet | | Restitution statistique (Metabase) | Tableaux de bord d'usage | Non. Agrégats de métadonnées uniquement | Non | ### Annexe 3 : Le cas particulier du *KV-Cache* \ **Mécanisme.** Pour générer un texte, un modèle calcule pour chaque *token* du contexte des représentations intermédiaires (clés et valeurs) qu'il doit conserver le temps de la génération, faute de quoi il les recalculerait à chaque *token* produit. vLLM réserve à cet effet, au démarrage du processus, un espace fixe de mémoire GPU découpé en blocs. Ces blocs contiennent des tenseurs numériques, non le texte lui-même. **Durée de rétention.** Les blocs alloués à une requête sont libérés dès la fin de celle-ci. Une optimisation standard, la mise en cache de préfixes (*prefix caching*), conserve toutefois dans l'espace GPU les blocs correspondant aux préfixes déjà calculés, afin de les réutiliser si une requête ultérieure présente **exactement** le même préfixe (cas typique : le *prompt* système d'une application, identique à chaque appel). Ces blocs sont évincés au fil de la charge selon une politique du moins récemment utilisé. Leur durée de vie n'est donc pas déterministe : elle est bornée par la pression sur la mémoire GPU et, en tout état de cause, par la durée de vie du processus. Un redémarrage du moteur détruit intégralement l'espace. **Propriétés de sécurité.** Ces blocs résident exclusivement en mémoire GPU. Ils ne sont jamais écrits sur disque, jamais sauvegardés, jamais répliqués, jamais exportés. Ils ne sont ni lisibles ni adressables depuis l'API : aucun appel ne permet d'en obtenir le contenu. Une réutilisation ne se produit que si le préfixe soumis est strictement identique, c'est-à-dire si l'appelant possède déjà le contenu concerné. # Foire aux questions (FAQ) Besoin d'aide ? On vous répond !
Pourquoi mon compte n'est pas autorisé ? Lors de votre connexion au [playground](https://albert.playground.etalab.gouv.fr/) d'Albert API via ProConnect, vous arrivez sur la page suivante vous indiquant que votre accès n'est pas autorisé. {% hint style="info" icon="circle-info" %} Si vous souhaitez vous connecter avec un autre compte **cliquez sur *****Logout pour réinitialiser la connexion**.* {% endhint %} **4 cas de figures vous permettent d'accéder à Albert API :**
1. **🇫🇷 Je suis une administration de l'État ou un organisme sous sa tutelle**\ \ Par principe, la condition d'accès à Albert API est d'appartenir une administration de l'État ou un organisme sous sa tutelle ([en savoir plus](#comment-savoir-si-je-suis-eligible-a-lacces-a-albert-api)).\ \ Si vous êtes dans ce cas, vous devez impérativement vous connectez avec votre adresse professionnelle. En effet, cette condition est évaluée directement par ProConnect, pas par Albert API.\ \ Si malgré l'utilisation de votre adresse professionnelle votre compte est toujours bloqué, il convient alors de réaliser une demande d'accès aux produits et services mis à disposition par la DINUM pour autoriser votre administration. Pour cela vous rendez-vous sur le [DataPass](https://datapass.api.gouv.fr/formulaires/produits_dinum/demande/nouveau) dédié.\ \ Veillez à fournir toutes les informations qui vous sembleraient utiles à porter à notre connaissance pour déterminer votre lien avec l'État.
2. **🏢 Je suis une entreprise privée souhaitant intégrer Albert API**\ \ Vous êtes une entreprise privée et vous souhaitez proposer Albert API comme API d'inférence de votre service pour vos clients administration publiques.\ \ ⚠️ Pour être éligible, vos clients doivent être des administrations de l'État ou des organismes sous sa tutelle ([en savoir plus](#comment-savoir-si-je-suis-eligible-a-lacces-a-albert-api)).\ \ Dans ce cas, nous vous mettons à disposez un accès "bac à sable" limité afin que vous puissiez intégrer au mieux Albert API dans votre service. Pour en faire la demande, merci de nous écrire à l'adresse suivante [albert.api@numerique.gouv.fr](mailto:albert.api@numerique.gouv.fr?subject=Demande%20entreprise%20d%27acc%C3%A8s%20%C3%A0%20Albert%20API).
3. **👤 Je suis une administration territoriale relevant d'une co-tutelle de l'État**\ \ Par principe, les administrations territoriales ne sont pas éligible à l'accès à Albert API. En effet, seules les administrations de l'État ou les organismes sous sa tutelle peuvent y prétendre.\ \ Toutefois, certaines administrations territoriales disposent d'une co-tutelle de l'État ([en savoir plus](#comment-savoir-si-je-releve-dune-administration-de-letat-ou-dun-organisme-sous-sa-tutelle)). Dans ce cas, vous devez impérativement vous connectez avec votre adresse professionnelle. En effet, cette condition est évaluée directement par ProConnect, pas par Albert API.\ \ Si malgré l'utilisation de votre adresse professionnelle votre compte est toujours bloqué, il convient alors de réaliser une demande d'accès aux produits et services mis à disposition par la DINUM pour autoriser votre administration. Pour cela vous rendez-vous sur le [DataPass](https://datapass.api.gouv.fr/formulaires/produits_dinum/demande/nouveau) dédié.\ \ Veillez à fournir toutes les informations qui vous sembleraient utiles à porter à notre connaissance pour déterminer votre lien avec l'État. 4. **🤝 Je suis association chargée d'une mission de service publique**\ \ Par principe, les associations ne sont pas éligible à l'accès à Albert API. En effet, seules les administrations de l'État ou les organismes sous sa tutelle peuvent y prétendre.\ \ Toutefois, certaines associations chargée d'une mission de service publique disposent d'une co-tutelle de l'État ([en savoir plus](#comment-savoir-si-je-releve-dune-administration-de-letat-ou-dun-organisme-sous-sa-tutelle)). Dans ce cas, vous devez impérativement vous connectez avec votre adresse professionnelle. En effet, cette condition est évaluée directement par ProConnect, pas par Albert API.\ \ Si malgré l'utilisation de votre adresse professionnelle votre compte est toujours bloqué, il convient alors de réaliser une demande d'accès aux produits et services mis à disposition par la DINUM pour autoriser votre administration. Pour cela vous rendez-vous sur le [DataPass](https://datapass.api.gouv.fr/formulaires/produits_dinum/demande/nouveau) dédié.\ \ Veillez à fournir toutes les informations qui vous sembleraient utiles à porter à notre connaissance pour déterminer votre lien avec l'État. {% hint style="info" icon="lightbulb" %} Nous vous recommandons d'utiliser une adresse mail de service pour gérer vos accès en production d'Albert API. {% endhint %} **Vous ne vous reconnaissez pas dans un de ces cas ?** Malheureusement vous n'êtes pas éligible à Albert API. Si vous pensez qu'il s'agit d'une erreur vous pouvez nous écrire à l'adresse suivante [albert.api@numerique.gouv.fr](mailto:albert.api@numerique.gouv.fr?subject=Demande%20non%20%C3%A9ligible%20d%27acc%C3%A8s%20%C3%A0%20Albert%20API%20).
Comment savoir si je relève d'une administration de l'État ou d'un organisme placé sous sa tutelle ? La DINUM met à disposition ses services, dont fait partie Albert API, aux administrations de l’État et aux organismes placés sous sa tutelle.\ \ Pour ce deuxième cas, la tutelle de l'État n'a pas l'obligation d'être exclusive. En effet, une co-tutelle suffit pour être éligible à Albert API. Cela concerne par exemple certaines administrations territoriales ou associations chargées d'une mission d'intérêt général.\ \ Ce lien avec l'État est déterminé dans les documents qui définissent vos activités (loi, décret, arrêté, convention constitutive, statuts, etc.). **En cas de difficultés rapprochez vous de votre service juridique.** Tous les organismes répondant à ce critère ne sont pas systématiquement référencé par ProConnect. Pour corriger cela, la DINUM met à votre disposition un [DataPass](https://datapass.api.gouv.fr/formulaires/produits_dinum/demande/nouveau) afin de réaliser **une demande d'accès aux produits et services mis à disposition par la DINUM.** Veillez à fournir toutes les informations qui vous sembleraient utiles à porter à notre connaissance pour déterminer votre lien avec l'État.
Pourquoi mon appel API est bloqué par la politique CORS ? Albert API ne renvoie pas l'en-tête `Access-Control-Allow-Origin` dans ses réponses car l'API n'est pas destinée à être appelée depuis un navigateur. Nous n'activons volontairement pas CORS sur cette API. L'API est destinée à être consommée par des applications serveur, où la clef d'authentification peut être conservée de manière sécurisée. Autoriser les appels depuis un navigateur encouragerait l'exposition de jetons d'API dans du code JavaScript, ce qui constitue une mauvaise pratique de sécurité. Les applications web doivent appeler cette API via leur propre backend, qui est responsable de protéger les identifiants d'accès.
Pourquoi l'API renvoi une erreur 503 « Model is too busy » ? Lorsque le modèle moteur est saturé, c'est-à-dire qu'il reçoit trop de requête, les endpoints concernés peuvent répondre une erreur **503** **« Model is too busy »**.\ \ Cette situation est temporaire. Pour prévenir ce problème en production nous vous recommandons de mettre en place une balance automatique de vos requête (fallback) vers un autre modèle. Pour vous aidez, Albert API met à disposition un endpoint `GET /health/models` pour surveiller l'état de chaque modèle (voir [API reference - Health](/albert-api/api-reference/liste-des-endpoint/health#get-health-models)).
Est-ce que je peux avoir une clef d'API sans expiration ? Non, il est impossible d'obtenir une clef d'API sans expiration pour des raisons de sécurité. Toutes les clefs d'API ont une date d'expiration de maximum 1 an à compter de la date de création. Vous pouvez configurer une clef avec une date d'expiration inférieure à 1 an lors de la création.
# Support Nous mettons à votre disposition différents canaux pour partager vos expériences, nous signaler vos problèmes ou encore apporter une contribution au projet.
Cover image

Tchap

Rejoignez la communauté Albert API.tchap.svghttps://tchap.gouv.fr/#/room/#albert:agent.dinum.tchap.gouv.fr

Email

Ecrivez-nous !at.svgmailto:albert.api@numerique.gouv.fr

YouCanBookMe

Prenez rendez-vous pour nous rencontrer.calendar-days.svghttps://albertapi.youcanbookme.com/

Github

Contribuez à Albert API.github.svghttps://github.com/etalab-ia/OpenGateLLM
## Ressources techniques
Cover image

API reference

L'API reference documente le comportement de chaque endpoint.book-open.svgListe des Endpoint

Statuts

Suivez le statut l'API en live.heart-pulse.svghttps://albert.status.etalab.gouv.fr/
## Signaler un problème Merci de nous signalez tout problème que vous rencontrez sur Tchap ou sur Github dans la section issue.
**Bonnes pratiques pour un signalement utile :** * fenêtre horaire et fuseau ; * `request_id` ou extraits de **logs** sans secrets (tracez un hash de jeton, pas la clé complète) ; * code HTTP, extrait JSON d’erreur (`detail`) ; * modèle et endpoint concernés ; * reproductibilité minimale (curl anonymisé). # Changelog Cette page résume l’évolution fonctionnelle et technique visible d'Albert API. ## Référence de version La **version d'Albert API** exposée sur `https://albert.api.etalab.gouv.fr/openapi.json` figure dans le champ `info.version` du document (par exemple `0.4.x` selon les déploiements). C’est la **source de vérité** pour les routes et schémas disponibles sur un environnement donné. *** ## Versions
0.6.0 (beta) **Date de déploiement : 31 août 2026** #### **🔐 Connexion au Playground via ProConnect** Dans un souci d'améliorer la sécurité d'Albert API, la connexion au Playground se fait désormais via ProConnect, le SSO de l'Etat.\ \ Vos comptes existants et vos clés d'API sont conservés : aucune action de migration n'est nécessaire.\ \ ⚠️ Connectez-vous avec l'adresse professionnelle exacte associée à votre compte actuel (celle de votre email de confirmation). Une autre adresse créera un nouveau compte, vide, sans vos clés. **Si votre email Albert API ne correspond pas à votre adresse ProConnect, merci de nous contacter pour faire le matching ().**\ \ Si l'accès vous est refusé, rendez-vous sur notre [FAQ](/albert-api/ressources/faq#pourquoi-mon-compte-nest-pas-autorise) pour connaître la démarche à suivre. #### 🎁 Phase de test pour Gemma 4 Un nouveau modèle vient s'ajouter au catalogue des modèles : `gemma-4-31-b-it`. Ce modèle est candidat au remplacement du modèle `openweight-medium` durant du phase de test allant jusqu'au 1er décembre 2026. Nous attendons vos retours sur ce nouveau modèle. Vous retrouvez toutes les spécifications techniques de ce modèle dans notre [documentation](/albert-api/modeles/available-models#gemma-4-31b-it). **Retrouvez le calendrier des migrations de modèle dans notre documentation** [**ici**](/albert-api/modeles/available-models#calendrier-des-migrations)**.**
0.5.0 (beta) **Date de déploiement : 27 juillet 2026** La version 0.5.0 d'Albert API introduit une phase d'expérimentation de nouveaux modèles ainsi que la suppression définitive de plusieurs fonctionnalités dépréciées depuis la version 0.4.1. #### 🎁 Phase de test de nouveaux modèles À compter du **25 juillet 2026**, nous lançons une phase de test de trois nouveaux modèles. Cette expérimentation se poursuivra jusqu'au **1er octobre 2026**, date à laquelle nous déciderons, en fonction de vos retours et de nos évaluations, de pérenniser tout ou partie de ces modèles. **Nous attendons avec impatience vos retours sur le canal de support !** * [LightOnOCR-2-1B](https://huggingface.co/lightonai/LightOnOCR-2-1B) (`openweight-ocr`) Ce modèle, accessible via l'endpoint `/v1/chat/completions`, est spécialisé dans l'OCR. Il permet d'extraire du texte à partir d'images, notamment de documents ou de pages de PDF numérisées, grâce à ses capacités multimodales. Une documentation détaillée sera publiée le **25 juillet**. * [DeepSeek-V4-Flash](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash) Ce modèle de **284 milliards de paramètres** est évalué comme successeur du modèle **Qwen3-Coder-30B-A3B-Instruct** pour les usages liés au développement logiciel. Si les résultats de la phase de test sont concluants, il remplacera le modèle actuellement proposé sous l'alias `openweight-code`. **⚠️ Nous ne recommandons pas d'utiliser ce modèle pour d'autres usages que le code.** * [Qwen3-VL-Embedding-8B](https://huggingface.co/Qwen/Qwen3-VL-Embedding-8B) Ce modèle d'embeddings multimodal, accessible via l'endpoint `/v1/embeddings`, vous permettra de représenter de manière vectorielle des textes, des images, des screenshots et des vidéos. Cela vous permettra de réaliser dans votre vector store du RAG avec différents formats d'entrée. Une documentation détaillée sera publiée le **25 juillet**. #### 🗑️ Suppression de fonctionnalités dépréciées Comme annoncé lors de la sortie de la version **0.4.1**, plusieurs fonctionnalités dépréciées seront définitivement supprimées avec la version **0.5.0**. Ces évolutions visent à simplifier et homogénéiser les contrats d'API. Nous vous invitons à vérifier les changements ci-dessous et à mettre à jour vos intégrations si vous êtes concernés. * L'argument `collection` de l'endpoint `POST /v1/documents` est supprimé au profit de `collection_id`. * L'endpoint `GET /v1/chunks/{document}/{chunk}` est remplacé par `GET /v1/documents/{document_id}/chunks/{chunk_id}`. * L'endpoint `GET /v1/chunks` est remplacé par `GET /v1/documents/{document_id}/chunks`. * L'endpoint `POST /v1/parse-beta` est supprimé. * L'argument `collections` de l'endpoint `POST /v1/search` est remplacé par `collection_ids`. * L'argument `search` de l'endpoint `POST /v1/chat/completions` est supprimé au profit de l'outil `search`, à utiliser via le champ `tools`. * L'argument `prompt` de l'endpoint `POST /v1/search` est remplacé par `query` et l'argument `collections` par `collections` * L'argument `collections` de l'endpoint `POST /v1/search` est remplacé supprimé par `collection_ids`. #### 📦 Fonctionnalité dépréciées * Le tool `search` de l'endpoint `POST /v1/chat/completions` est déprécié. La fonctionnalité est maintenue pour le moment mais ne fera plus l'objet d'améliorations, elle sera supprimée lors de la version 1.0.0 (Q4 2026). Nous souhaitons privilégier l'usage de la combinaison de l'usage de `/v1/search` et `/v1/chat/completion` pour un RAG maitrisé.
# Documentation utilisateurs ## L'Assistant, c'est quoi ? **L'Assistant** est une plateforme de la DINUM qui vous permet d'échanger avec des modèles d'intelligence artificielle dans un espace **sécurisé** en ligne, de créer des conversations et des projets avec vos documents, et vos instructions adaptées à vos métiers. Le service est disponible à l'adresse suivante : [https://assistant.numerique.gouv.fr](https://assistant.numerique.gouv.fr/) {% hint style="info" %} Vous pouvez utiliser l'Assistant sans coût et sans quotas d'utilisation {% endhint %} ## L'Assistant, pour quoi faire ? ### Avoir un outil d'intelligence artificielle maîtrisé et sécurisé * Hébergement souverain et sécurisé : les documents importés dans l'Assistant et le contenu des conversations sont stockés de façon **sécurisée** sur des infrastructures qualifiées SecNumCloud. Le traitement par des modèles d'IA est aussi réalisé dans cet environnement, sans envoi à des acteurs tiers. * Vous pouvez accéder à l'Assistant en ligne depuis n'importe quel navigateur, sans installation de logiciel. * Simplicité d'usage : une interface simple pour aider les agents à monter en compétence sur l'utilisation de l'intelligence artificielle sans complexité. ### Un outil généraliste pour permettre aux directions métiers de se concentrer sur leurs spécificités * Une brique essentielle du socle d'IA générative de la DINUM; * Un assistant généraliste qui permettra d'intégrer facilement des modules spécifiques aux métiers, aux ministères et à la granularité de l'administrations, de ses langages et de ses spécificités; * Le tout à moindre coût, car sans le besoin de re-développer une interface nouvelle, en s'intégrant directement à l'Assistant {% hint style="warning" icon="lightbulb-on" %} **L'Assistant n'est donc pas spécialisé pour l'administration ?** Pas encore ! Créé à la Direction Interministérielle du numérique, l'Assistant a pour objectif d'être d'abord un **outil généraliste** adapté à la **grande variété des métiers** de l'administration de l'état et de ses organismes de tutelle, ainsi qu'aux contraintes de **sécurité et de souveraineté.** Il est construit pour être modulaire, et pouvoir intégrer dès la fin 2026 des modules métiers. {% endhint %} ## L'Assistant, c'est pour moi ? {% hint style="success" %} L'Assistant s'adresse à **tous les agents des administrations de l'État et de leurs organismes de tutelle.** {% endhint %} Votre organisation n'est pas eligible ? L'Assistant est conçu comme un logiciel libre, le code source est disponible à l'adresse suivante : ## Qui opère l'Assistant ? L'Assistant est développé par l’équipe de **LaSuite**, au sein de la **Direction interministérielle du numérique (DINUM)**. Nous travaillons avec les administrations pour construire des services adaptés, open-source, sobres et souverains. *** ## Prochaines étapes Maintenant que vous savez utiliser les bases de l'Assistant IA, explorez : 1. [**Guide rapide**](/assistant-ia/pour-commencer/guide-rapide) - Les fonctionnalités essentielles en 10 minutes 2. [**Recherche web**](/assistant-ia/guides-pratiques/recherche-web) - Trouver des informations actualisées 3. [**Gestion des documents**](/assistant-ia/guides-pratiques/documents) - Analyser vos fichiers 4. [**Projets et bases documentaires**](/assistant-ia/pour-aller-plus-loin/automatisations-et-api#bases-documentaires-et-projets) - Organiser votre travail {% hint style="info" %} **Besoin d'aide ?** Consultez notre section [Troubleshooting](/assistant-ia/depannage/erreurs) ou [signalez un problème](/assistant-ia/depannage/report-issue). {% endhint %} # Bien démarrer ## Se connecter Rendez-vous sur le site: [https://assistant.numerique.gouv.fr](https://assistant.numerique.gouv.fr/) Afin de faciliter votre connexion à L'Assistant, nous utilisons **ProConnect** : ce moyen d'authentification simple et rapide vous permet de vous connecter à tous les outils de LaSuite à l'aide d'un compte unique, sécurisé. ## Découvrir l'interface Lors de votre première connexion à l'Assistant, vous découvrirez au centre de votre écran la barre de saisie suivante, qui vous permet de démarrer votre première conversation en toute simplicité.
C'est ici qu'apparaitront les messages de l'Assistant au fur et à mesure de vos conversations. Le second élément de l'interface est la barre lattérale de gauche, ou vous trouverez 3 sections : * **Les boutons d'action** : nouvelle conversation, recherche, et nouveau projet; * **Les projets** : vous trouverez ici les projets que vous avez configuré; * **Les conversations** : vous y trouverez toutes les conversations démarées à la volée sans être rattachées à un projet.
## Optimiser ses conversations Vous pouvez dans une conversation avec l'Assistant lui donner la possibilité d'aller **chercher sur internet** des informations pour **améliorer la pertinence** du résultat. Pour ce faire, cliquez sur le bouton "**Rechercher sur le web**" dans la barre de saisie. Elle apparaîtra surlignée en bleu comme dans l'image ci dessous. {% hint style="info" %} Vous pouvez également activer l'option "Recherche web intelligente" dans les **paramètres**, ou c'est L'Assistant qui décidera automatiquement de l'activation de la recherche web en fonction de votre recherche. {% endhint %}
Vous pouvez également déposer des documents, sur lesquels l'Assistant s'appuiera pour rédiger sa réponse, soit en effectuant un résumé, soit en faisant une recherche ciblée des paragraphes les plus semblables à votre question.
Pour déposer vos documents, vous pouvez cliquer sur le bouton "Joindre un fichier" qui ouvrira un sélectionneur de fichier, soit glisser-déposer vos documents directement dans l'interface.
{% hint style="warning" %} Une limite de 10 Mo et de 10 documents par message s'applique. {% endhint %} Enfin, exercez toujours un regard critique sur les productions de l'Assistant, et reposez-vous le plus possible sur vos sources et vos propres analyses pour comprendre les réponses de L'Assistant. ## Utiliser les projets Après quelques conversations, vous pouvez remarquer que vous utilisez régulièrement une même instruction ou un même corpus documentaire dans plusieurs conversations, où que vous devez répéter les instructions à chaque message. Grâce aux projets, vous pouvez créer un jeu d'instruction et un corpus documentaire persistents, facilement repérables grâce à une identité visuelle, constituée d'un logo et d'une couleur.
Après avoir créé le projet, vous êtes redirigé vers l'interface de "conversation dans un projet". Tous les messages envoyés par l'Assistant se baseront sur les **documents** et les **instructions** du projet. Au moment de commencer une conversation, vous pouvez facilement repérer si vous êtes dans un projet, car l'**identité visuelle** et **le nom du projet** s'affichent au dessus de la barre de saisie.
Vous pouvez retrouver les conversations en cours dans le projet en cliquant sur la flêche à gauche du nom du projet.
Enfin, pour modifier ou supprimer un projet, cliquez sur le menu composé de 3 points horizontaux sur la droite de la carte du projet.
## Rechercher une conversation Vous pouvez chercher une conversation grâce à l'option "**Rechercher**" dans la barre lattérale. Cette recherche porte pour l'instant sur le titre des conversations. Lors de la recherche, les conversations correspondant aux mots clefs saisis s'afficheront. Pour vous aider à mieux vous repérer, le temps écoulé depuis la dernière modification s'affiche, ainsi que le projet dans laquelle se situe la conversation si c'est le cas.
## Se retrouver dans l'interface ## Prochaines étapes Maintenant que vous maîtrisez les bases, explorez : 1. [**Gestion des documents**](/assistant-ia/guides-pratiques/documents) - Maîtriser l'analyse de fichiers 2. [**Recherche web**](/assistant-ia/guides-pratiques/recherche-web) - Approfondir la recherche d'informations 3. [**Troubleshooting**](/assistant-ia/depannage/erreurs) - Résoudre les problèmes courants *** {% hint style="success" icon="trophy" %} Vous avez maintenant les **bases nécessaires** pour utiliser efficacement l'Assistant IA. Plus vous l'utiliserez, plus vous découvrirez de fonctionnalités avancées. N'hésitez pas à **explorer, tester et faire des retours** pour améliorer l'outil. {% endhint %} {% hint style="info" %} **Besoin d'aide ?** Consultez notre [FAQ](/assistant-ia/depannage/faq) ou [signalez un problème](/assistant-ia/depannage/report-issue). {% endhint %} # Sécurité Comprendre la sécurité et la souveraineté de l'Assistant IA L'Assistant IA a été conçu pour vous offrir **le plus haut niveau de sécurité et de souveraineté** possible. Mais que signifie cela concrètement pour vous, en tant qu'agent de l'État ? ## 🛡️ La sécurité, comment ça marche ? La sécurité de l'Assistant IA repose sur plusieurs piliers : ### Protection de vos données * **Isolement complet** : Vos conversations et documents sont **strictement séparés** de ceux des autres utilisateurs. Personne d'autre ne peut y accéder. * **Authentification renforcée** : L'accès se fait exclusivement via **ProConnect**, avec vos identifiants professionnels. * **Infrastrucutre labélisée SecNumCloud** : conformément à la loi SREN, les serveurs qui hébergent l'Assistant répondent à des critères élevées en sécurité des systèmes d'information pour assurer une isolation physique du réseau en plus de la sécurité applicative. ### Qui peut accéder à vos données ? * **Vous seul** : Par défaut, vos conversations sont **privées** et accessibles uniquement par vous. * **Votre administration** : Peut accéder sur demande à des statistiques **anonymisées et aggrégées** pour comprendre l'usage du service. * **L'équipe technique** : Peut accéder aux logs techniques (sans le contenu de vos conversations) pour la maintenance. * **L'équipe produit DINUM** : **Uniquement si vous avez activé l'option « Autoriser l'analyse de conversation »** dans vos paramètres. Dans ce cas, ils peuvent lire vos conversations pour améliorer le service, mais **jamais** pour entraîner des modèles ou les partager avec des tiers. {% hint style="warning" %} **Important :** Pour une confidentialité maximale, désactivez l'option « Autoriser l'analyse de conversation » dans vos paramètres. Celle-ci est désactivée par défaut. {% endhint %} ## Ce que vous NE devez PAS faire Pour garantir la sécurité de tous, il est **strictement interdit** d'utiliser l'Assistant IA pour : ✖️ Traiter des **données classifiées** (Diffusion Restreinte, Secret, Très Secret) ✖️ Prendre des **décisions administratives individuelles** (l'IA ne remplace pas votre jugement) ✖️ Générer ou diffuser des **contenus illicites** ✖️ Contourner les **mesures de sécurité** {% hint style="danger" %} L'Assistant IA **n'est pas homologué** pour le traitement de données classifiées. En cas de doute sur la sensibilité d'une information, **ne la partagez pas** avec l'outil, et contactez votre référent protection des données ou votre hiérarchie {% endhint %} ## 📋 Ce que garantit la DINUM En tant qu'éditrice de l'Assistant IA, la DINUM s'engage à : ✅ Maintenir le service disponible dans des conditions raisonnables\ ✅ Assurer la sécurité et la confidentialité des données\ ✅ Respecter les obligations légales en vigueur (RGPD, loi SREN, etc.)\ ✅ Corriger les dysfonctionnements signalés\ ✅ Ne jamais partager vos données avec des tiers commerciaux\ ✅ Ne jamais utiliser vos données pour entraîner des modèles d'IA ## 🔍 Besoin de plus d'informations ? Pour aller plus loin, consultez : * [**Protection des données**](/assistant-ia/documentation-legale/data-protection) - Tous les détails sur le traitement de vos données * [**Mentions légales**](/assistant-ia/documentation-legale/legal) - Le cadre juridique complet * [**Signaler un incident**](https://formulaire.beta.numerique.gouv.fr/r/assistant) - En cas de problème de sécurité *** {% hint style="success" %} L'Assistant IA est conçu pour être **l'outil le plus sûr possible** pour les agents publics. Mais n'oubliez pas : **vous conservez la responsabilité** de l'usage que vous en faites. En cas de question, votre référent IA ou votre DPO (Délégué à la Protection des Données) est là pour vous accompagner. {% endhint %} # Gestion des documents Comment l'assistant analyse et utilise vos documents : contexte complet pour les petits fichiers, indexation RAG pour les longs documents, et ce que l'IA "voit" vraiment. L'assistant ne "lit" pas vos documents comme vous. Il les transforme en texte, puis les analyse selon deux modes distincts selon leur taille. Voici ce qui se passe concrètement. *** ## 📄 Documents courts : traitement en contexte complet **Si votre document fait moins d'une dizaine de pages de texte**, l'assistant l'intègre **entièrement** dans le contexte de la conversation. Cela signifie qu'il a accès à l'intégralité du contenu simultanément. Il peut alors : * **Analyser les liens** entre toutes les sections * **Repérer les contradictions** ou répétitions * **Extraire des informations** précise sans limite de zone * **Répondre à des questions** portant sur n'importe quelle partie du document {% hint style="info" %} **Exemple** : Un contrat de 8 pages sera entièrement "chargé" dans la mémoire de la conversation. Vous pouvez demander : *"Quels sont les articles concernant les pénalités de retard ?"* et l'assistant parcourra l'ensemble pour vous répondre. {% endhint %} *** ## 📚 Documents longs : indexation et recherche RAG **Au-delà d'une dizaine de pages**, ou dans le cadre d'un **projet**, vos documents sont **découpés en sections** (on parle de *chunks*) et stockés dans une base de recherche spécialisée. L'assistant dispose alors de **deux outils principaux** pour y accéder : ### 🔍 1. Le résumé Un résumé automatique du document est généré et stocké. Cela permet à l'assistant de comprendre **la thématique globale** avant même de plonger dans les détails. ### 🎯 2. La recherche RAG (Recherche Augmentée par Génération) Lorsque vous posez une question, l'assistant : 1. **Interprète votre demande** 2. **Recherche dans la base** les paragraphes les plus proches sémantiquement 3. **Sélectionne les extraits pertinents** 4. **Génère une réponse** basée sur ces extraits {% hint style="success" %} **Concrètement** : Si vous demandez *"Quelles sont les spécifications techniques du module X ?"*, l'assistant ne lira pas les 200 pages du manuel. Il identifiera les 3 paragraphes qui parlent de ce module et s'y référera pour répondre. {% endhint %} *** ## 👁️ Ce que l'assistant "voit" vraiment **Votre document est converti en texte brut.** L'assistant **ne voit pas** : * ❌ **La mise en page** (colonnes, encadrés, position des éléments) * ❌ **Les numéros de page** (les références type *"voir page 4"* sont inutiles) * ❌ **Les schémas, images ou graphiques** (sauf si leur légende ou texte alternatif est présent) * ❌ **Les annotations manuscrites** ou surlignages * ❌ **Les informations de format** (police, couleur, taille) **Il voit uniquement** : * ✅ **Le texte** extrait du document * ✅ **La structure hiérarchique** (titres, sous-titres, listes, tableaux) * ✅ **Les mots et leur agencement** dans les phrases et paragraphes ### ⚠️ Conséquence importante Pour que l'assistant **trouve l'information que vous cherchez**, celle-ci doit être **clairement identifiable par son contenu textuel**. | ❌ À éviter | ✅ À privilégier | | ------------------------------------ | -------------------------------------------------------- | | *"Le tableau en haut de la page 12"* | *"Le tableau comparant les performances trimestrielles"* | | *"Le paragraphe sous le schéma"* | *"Le paragraphe expliquant le processus de validation"* | | *"La note en bas de page"* | *"La note précisant les exceptions à la règle"* | **Pourquoi ?** Parce que l'assistant recherche des **mots-clés** et des **concepts**, pas des positions visuelles. *** ## 💡 Bonnes pratiques pour optimiser le traitement ### Pour les documents courts * **Structurez avec des titres clairs** : L'assistant s'appuie sur la hiérarchie du texte * **Soyez explicite** dans vos noms de sections ### Pour les documents longs * **Utilisez des mots-clés précis** dans vos questions : *"Dans le chapitre sur la conformité RGPD, quelles sont les obligations ?"* * **Évitez les références spatiales** : Préférez le contenu à la position * **Demandez des résumés ciblés** : *"Résume-moi la section sur les procédures d'urgence"* ### Dans tous les cas * **Privilégiez les formats texte** (PDF avec texte, DOCX, TXT) aux images ou scans * **Testez avec une question simple** pour confirmer que le document est bien indexé *** ## ❓ Questions fréquentes
Pourquoi l'assistant ne trouve pas une information que je vois dans mon document ? * L'information est peut-être dans une **image ou un schéma** sans texte alternatif * Le document a peut-être été **mal extrait** (PDF scanné, format corrompu) * Votre question utilise des **références visuelles** ("à droite", "en bas") incompréhensibles pour l'IA * L'information est dans un **tableau complexe** dont la structure n'a pas été préservée **Solution** : Reformulez votre question avec des mots-clés du contenu, ou vérifiez le format du document.
Comment savoir si mon document est en full context ou en RAG ? * **Full context** : Document de moins de 5 pages, discuté dans une conversation unique * **RAG** : Document de plus de 5 pages, ou ajouté à une base documentaire/projet Vous pouvez toujours demander à l'assistant : *"Comment as-tu accès à ce document ?"*
Mon document fait 4 pages mais l'assistant semble ne pas tout voir. Pourquoi ? La limite de "environ 5 pages" concerne le **nombre de pages de texte pur**. Si votre document contient beaucoup d'information très denses, la quantité de texte effective peut être supérieure à ce que vous attendez, ce qui réduit le contexte disponible.
# Recherche web Recherche web en temps réel avec Brave Search et résumé automatique des résultats pour des réponses rapides et précises. Votre assistant peut effectuer des **recherches web en temps réel** pour trouver des informations à jour, avec résumé automatique des résultats grâce à l'intégration avec Brave Search. {% hint style="success" %} **Recherche intelligente** : Votre assistant comprend votre intention de recherche et reformule les requêtes pour de meilleurs résultats. {% endhint %} ## Comment utiliser la recherche web ### Méthode 1 : En selectionnant l'outil dans la barre de saisie En cliquant sur le bouton "Rechercher sur le web" dans la barre de saisie, celle-ci apparaît surlignée en bleu. L'Assistant ira chercher des sources sur internet pour répondre à votre requête. ### Méthode 2 : Utiliser la recherche intelligente L'assistant peut **automatiquement** déclencher une recherche web si : * L'option "Recherche web intelligente" est activée dans les paramètres * Votre question porte sur des **actualités récentes** * Votre question nécessite des **informations à jour** Exemples : ``` Vous : "Quels sont les derniers résultats des élections 2025 ?" Vous : "Quel est le taux de change euro/dollar aujourd'hui ?" Vous : "Quelles sont les prévisions météo pour demain ?" ``` ## Bonnes pratiques ### Formuler de bonnes requêtes | ❌ À éviter | ✅ Recommandé | Pourquoi | | ------------ | ---------------------------------------------------------------- | ------------------------------------- | | "IA" | "Quelles sont les dernières avancées en IA générative en 2025 ?" | Plus spécifique = meilleurs résultats | | "météo" | "Quelle est la météo à Paris demain ?" | Précis = réponse ciblée | | "actualités" | "Quelles sont les actualités tech aujourd'hui ?" | Trop large = trop de résultats | ### Évaluer les résultats * ✅ **Vérifiez les sources** citées dans les résultats * ✅ **Croisez les informations** avec d'autres sources * ⚠️ **Méfiez-vous** des informations non vérifiées * ❌ **Ne partagez pas** d'informations sensibles trouvées en ligne ### Limites à connaître * ⚠️ **Accès limité** : Certains sites bloquent les robots de recherche * ⚠️ **Paywalls** : Les articles payants ne seront pas accessibles * ⚠️ **Actualité** : Les informations peuvent être obsolètes quelques heures après la recherche * ⚠️ **Biais** : Tous les moteurs de recherche ont des biais potentiels ### Bonnes pratiques : * ✅ Utilisez la recherche web pour des **informations publiques** uniquement * ✅ **Ne recherchez pas** d'informations personnelles ou sensibles * ✅ **Vérifiez** toujours les sources avant de partager des informations * ✅ **Respectez** les droits d'auteur et les politiques d'utilisation ## Résolution des problèmes
La recherche ne retourne aucun résultat * Vérifiez que votre question est claire et spécifique * Essayez de reformuler avec des mots-clés différents * Vérifiez que vous n'avez pas désactivé la recherche web * Essayez une recherche plus large * Contactez le support si le problème persiste
Les résultats sont obsolètes * La recherche web peut avoir une légère latence * Essayez d'ajouter "après:\[date]" à votre requête * Vérifiez directement sur les sites sources
Les résultats ne sont pas pertinents * Soyez plus spécifique dans votre requête * Ajoutez plus de contexte à votre question * Essayez de poser la question différemment
Je ne vois pas les liens vers les sources * Les liens sont affichés à la fin de chaque message * Cliquez sur "Voir la source" * Si vous ne voyez pas de source apparaître, il se peut que l'Assistant ait halluciné (voir [Hallucinations](/assistant-ia/pour-aller-plus-loin/hallucinations)) et n'ait pas réellement pu chercher sur internet.
## Ressources connexes {% content-ref url="/pages/byUl4AyFGA218bLAHiP1" %} [Gestion des documents](/assistant-ia/guides-pratiques/documents) {% endcontent-ref %} {% content-ref url="/pages/4taWnWUphdsejPlm7lYE" %} [Résumé automatique](/assistant-ia/guides-pratiques/resume) {% endcontent-ref %} # Résumé automatique Résumé intelligent de documents, de pages web et de conversations avec l'outil de résumé intégré. Votre assistant peut **résumer automatiquement** des documents, des pages web et même des conversations pour vous fournir les points clés de manière concise et efficace. {% hint style="success" %} **Gagnez du temps** : Obtenez l'essentiel de longs documents ou articles en quelques secondes. {% endhint %} ## Comment utiliser le résumé Glissez-déposez un document ou uploadez-le, puis demandez un résumé : ``` Vous : "Voici un rapport de 50 pages. Peux-tu me le résumer ?" [Glissez-déposez le document] Assistant : "Voici le résumé du rapport..." ``` ### Personnalisation du résumé Vous pouvez spécifier le format et la longueur : ``` Vous : "Résume ce document en 5 bullet points maximum" Vous : "Fais un résumé détaillé avec des sections claires" Vous : "Donne-moi juste les 3 points principaux" ``` ### Extraction d'informations spécifiques Demandez à l'assistant d'extraire des informations précises : ``` Vous : "Dans ce document, extrais toutes les dates importantes" Vous : "Résume seulement la section sur la sécurité" Vous : "Quels sont les 5 points d'action mentionnés ?" ``` ### Résumé de documents Avec l'outil **Summarize** : * ✅ Traitement de PDFs, Word, Markdown, etc. * ✅ Identification automatique des sections importantes * ✅ Conservation de la structure (titres, sous-titres) * ✅ Extraction des données clés (dates, noms, chiffres) ## Bonnes pratiques ### Pour de meilleurs résumés 1. **Soyez spécifique** sur ce que vous voulez résumer 2. **Précisez le format** souhaité (bullet points, paragraphe, etc.) 3. **Indiquez la longueur** si vous avez des préférences 4. **Demandez des points spécifiques** à inclure ou exclure 5. **Vérifiez les sources** citées dans le résumé ### Exemples de requêtes efficaces | ❌ Moins bon | ✅ Meilleur | Pourquoi | | ---------------------- | ---------------------------------------------------------- | ------------- | | "Résume" | "Résume ce document en 5 points clés" | Plus précis | | "Donne le résumé" | "Fais un résumé structuré avec introduction et conclusion" | Plus détaillé | | "Dis-moi ce qu'il y a" | "Quels sont les arguments principaux et les preuves ?" | Plus ciblé | ## Paramètres avancés Le résumé est déclenché par l'Assistant en précisant les contraintes que vous avez émises. Vous pouvez donc, directement depuis le message où vous demandez un résumé, donner des instructions spécifiques pour le résumé. ### Niveau de détail Contrôlez la granularité du résumé : ``` Vous : "Résume ce document avec un niveau de détail élevé" Vous : "Donne-moi un aperçu très général" ``` ### Focus thématique Demandez un résumé axé sur un thème spécifique : ``` Vous : "Résume ce rapport en te concentrant sur les aspects financiers" Vous : "Quels sont les points techniques mentionnés dans ce document ?" ``` ### Langue du résumé Demandez un résumé dans une langue spécifique : ``` Vous : "Résume ce document en anglais" Vous : "Fais un résumé en français de cet article" ``` ## Limites et conseils ### Ce que le résumé peut faire ✅ Comprendre le contenu principal\ ✅ Identifier les points clés \ ✅ Extraire des informations structurées \ ✅ Synthétiser des informations multiples \ ✅ Détecter les thèmes principaux ### Ce que le résumé ne peut pas faire ❌ Comprendre le contexte non écrit \ ❌ Interpréter des informations ambiguës \ ❌ Garantir l'exactitude à 100% \ ❌ Remplacer une lecture complète pour les décisions critiques \ ❌ Comprendre les nuances subjectives ### Conseils pour une utilisation optimale 1. **Pour les documents importants** : Lisez toujours le document complet après le résumé 2. **Pour les décisions critiques** : Vérifiez les informations dans la source originale 3. **Pour les informations sensibles** : Confirmez avec un expert humain 4. **Pour les documents techniques** : Demandez un résumé plus détaillé 5. **Pour les comparaisons** : Résumez plusieurs documents pour une vue d'ensemble ## Résolution des problèmes
Le résumé est trop court/vague * Demandez un résumé plus détaillé * Précisez le nombre de points souhaités * Demandez un résumé structuré * Essayez un autre modèle (Mistral Large donne des résumés plus complets)
Le résumé manque d'informations importantes * Demandez spécifiquement les informations manquantes * Vérifiez que le document a été correctement uploadé * Essayez de résumer des sections spécifiques du document * Demandez un résumé avec un focus particulier
Le résumé contient des informations incorrectes * Vérifiez l'exactitude avec la source originale * Donnez un retour négatif (👎) avec une explication * Demandez à l'assistant de vérifier une information spécifique * Signalez le problème à votre administrateur
Le résumé est trop long * Demandez un résumé plus court * Précisez un nombre maximum de points * Demandez uniquement les points principaux * Utilisez des bullet points pour plus de concision
## Ressources similaires {% content-ref url="/pages/byUl4AyFGA218bLAHiP1" %} [Gestion des documents](/assistant-ia/guides-pratiques/documents) {% endcontent-ref %} {% content-ref url="/pages/UdDR0PV74lycV0aL3IdN" %} [Recherche web](/assistant-ia/guides-pratiques/recherche-web) {% endcontent-ref %} # Comprendre les erreurs de l'Assistant Guide de dépannage pour résoudre les problèmes courants avec l'Assistant IA Cette section vous aide à résoudre les problèmes les plus courants rencontrés avec l'Assistant IA. **L'Assistant vous indiquera toujours l'erreur qu'il rencontre**, soit via un message d'erreur technique, soit par un message explicite comme : > *"Je n'arrive pas à accéder à internet, vérifiez que la configuration me l'autorise."* Pensez à **rafraîchir la page** (F5 ou Ctrl+R) pour vérifier s'il n'y a pas un **bandeau d'erreur** en haut de l'interface indiquant l'indisponibilité de certaines fonctionnalités. Ces dernières peuvent être configurées par l'équipe de l'Assistant ou mises à jour automatiquement lorsque des fonctionnalités cassées sont détectées. Si vous rencontrez un **vrai message d'erreur technique** (qui ne ressemble pas à une réponse normale de l'Assistant), vous pouvez réessayer dans une nouvelle conversation. La plupart de ces erreurs vous empêcherons de continuer dans cette conversation, car celle-ci est en message d'erreur. *** ## Problèmes de connexion ### Je n'arrive pas à me connecter **Symptômes :** * La page de connexion ne répond pas * Erreur après identification ProConnect * Message "Accès refusé" **Solutions :** 1. **Vérifiez votre connexion ProConnect** * Assurez-vous d'utiliser vos identifiants professionnels * Si vous avez oublié votre mot de passe, réinitialisez-le via [ProConnect](https://proconnect.gouv.fr/) 2. **Vérifiez votre éligibilité** * L'Assistant IA est accessible à tous les agents des **administrations de l'État et de leurs organismes de tutelle** * Si vous pensez avoir droit à l'accès mais que la connexion échoue, contactez votre référent IA ministériel 3. **Problèmes techniques** * Essayez un autre navigateur (Chrome, Firefox, Edge recommandés) * Vide le cache de votre navigateur * Désactivez les extensions qui pourraient bloquer la connexion 4. **Maintenance en cours** * Les maintenances sont annoncées dans l'interface par l'intermédiaire de bannières situées en haut de la partie centrale. Une page de statut vera bientôt le jour. {% hint style="info" %} Si le problème persiste, [signalez-le à l'équipe](/assistant-ia/depannage/report-issue). {% endhint %} ### Les réponses sont incomplètes ou coupées **Solutions :** 1. **Attendez quelques secondes** - La génération peut être lente selon la charge 2. **Actualisez la conversation** 3. **Reformulez votre demande** de manière plus concise 4. **Divisez les questions complexes** en plusieurs messages *** ## Problèmes avec les documents ### Je ne peux pas téléverser de documents **Symptômes :** * Bouton de téléversement grisé * Erreur lors du glisser-déposer * Message **"Type de fichier non supporté"** (affiché par l'Assistant) **Solutions :** 1. **Vérifiez le type de fichier** * Formats supportés : PDF, images (JPG, PNG), documents bureautiques (.md, .docx, .pptx, .xlsx) * Taille maximale : 10 Mo par fichier (variable selon la configuration) : un message d'erreur précisant la taille maximale s'affichera si le téléversement échoue. 2. **Vérifiez la disponibilité de la fonctionnalité** * Le téléversement de documents peut être temporairement désactivé pour maintenance * Un **bandeau d'erreur** peut apparaître en haut de page 3. **Essayez un autre navigateur** ### L'Assistant ne comprend pas mon document **Solutions :** 1. **Vérifiez la qualité du document** * Les PDF mal scannés ou les images de mauvaise qualité peuvent ne pas être lisibles * Essayez de fournir le texte directement 2. **Soyez précis dans vos questions** * Au lieu de "Qu'est-ce qu'il y a dans ce document ?", demandez "Quel est le montant total mentionné dans la section budget ?" 3. **Donnez du contexte** * "Ce document est un compte rendu de réunion. Peux-tu m'en faire un résumé ?" *** ## Problèmes avec la recherche web ### La recherche web ne fonctionne pas **Symptômes :** * Bouton de recherche web grisé * Pas de résultats de recherche * Erreur **"Impossible d'effectuer la recherche"** ou **"La recherche web est désactivée"** (affiché par l'Assistant) **Solutions :** 1. **Vérifiez que la recherche est activée** * Cliquez sur l'icône 🌐 dans la barre de message * Ou activez la "recherche intelligente" dans vos paramètres 2. **Vérifiez votre question** * La recherche fonctionne mieux avec des questions claires et précises * Évitez les questions trop vagues 3. **Problème temporaire** * Le service de recherche peut être temporairement indisponible * **Rafraîchissez la page** pour vérifier l'affichage d'un bandeau d'erreur * Réessayez plus tard *** ## Problèmes de performance ### L'application est lente **Solutions :** 1. **Vérifiez votre connexion internet** 2. **Fermez les onglets inutilisés** 3. **Utilisez un navigateur moderne** (Chrome, Firefox, Edge, Safari récent) 4. **Videz le cache** de votre navigateur ### Les conversations mettent du temps à charger **Solutions :** 1. **Utilisez la recherche** pour trouver des conversations spécifiques au lieu de tout parcourir *** ## Problèmes d'affichage ### L'interface ne s'affiche pas correctement **Solutions :** 1. **Actualisez la page** (F5 ou Ctrl+R) 2. **Videz le cache** du navigateur 3. **Essayez un autre navigateur** 4. **Vérifiez la résolution** de votre écran 5. **Désactivez le mode zoom** (Ctrl+0 pour réinitialiser) ### Les messages ne s'affichent pas correctement **Solutions :** 1. **Actualisez la conversation** 2. **Vérifiez que JavaScript est activé** dans votre navigateur 3. **Essayez de copier-coller** le message problématique *** ## Problèmes divers ### L'Assistant donne des réponses incorrectes **Solutions :** 1. **Vérifiez les faits** - L'Assistant peut faire des erreurs, toujours croiser les informations 2. **Reformulez votre question** de manière plus précise 3. **Fournissez plus de contexte** ou de documents de référence 4. **Activez la recherche web** pour des informations actualisées 5. **Signalez l'erreur** pour aider à améliorer le service **Rappel :** L'Assistant est un **outil d'aide**, pas une source de vérité absolue. Vous conservez la responsabilité finale de vérifier les informations. *** ## Besoin d'aide supplémentaire ? Si vous ne trouvez pas de solution à votre problème : 1. [**Consultez les questions fréquentes**](/assistant-ia/depannage/faq) 2. [**Signalez un problème**](/assistant-ia/depannage/report-issue) à l'équipe technique 3. **Contactez votre référent IA** ministériel 4. **Rejoignez le canal Tchap** de la communauté pour voir si d'autres utilisateurs ont déjà rencontré le même problème : [Lien vers le canal Tchap](https://tchap.gouv.fr/#/room/!eAHyPLdVHMxNhKAbaC:agent.dinum.tchap.gouv.fr?via=agent.dinum.tchap.gouv.fr\&via=agent.education.tchap.gouv.fr\&via=agent.justice.tchap.gouv.fr) {% hint style="warning" %} Le canal de la communauté à pour but de créer un lieu d'échange entre utilisateurs. Les demandes d'accès à l'Assistant par des personnes ne remplissant pas les conditions énoncées dans cette documentation seront supprimées. {% endhint %} # Questions fréquentes ## Accès et éligibilité ### Qui peut accéder à l'Assistant IA ? **Réponse :** L'Assistant IA est accessible à **tous les agents des administrations de l'État et de leurs organismes de tutelle**. Il suffit de se connecter via ProConnect avec vos identifiants professionnels. *Aucun code d'accès n'est nécessaire.* ### Comment accéder à l'Assistant IA ? 1. Rendez-vous sur [assistant.numerique.gouv.fr](https://assistant.numerique.gouv.fr) 2. Connectez-vous via **ProConnect** avec vos identifiants professionnels 3. Vous êtes prêt à utiliser l'Assistant ! ### Pourquoi n'ai-je pas accès alors que je suis agent public ? Plusieurs raisons possibles : * Votre administration n'a pas encore déployé l'accès (contactez votre référent IA) * Problème technique avec ProConnect (vérifiez vos identifiants) * Votre navigateur n'est pas compatible (essayez Chrome, Firefox ou Edge) Si le problème persiste, contactez votre référent IA ministériel. *** ## Fonctionnement ### Comment bien formuler mes questions ? Pour obtenir de meilleurs résultats : ✅ **À faire :** * Soyez **précis** : décrivez clairement le contexte et l'objectif * **Structurez** votre demande avec des phrases courtes * **Donnez des exemples** ou extrayez le texte pertinent * **Itérez** : affinez votre demande en fonction des réponses ❌ **À éviter :** * Questions trop vagues ("Parle-moi de l'administration") * Demandes trop complexes en un seul message * Attente de réponses sans vérifier les faits **Exemple de bonne formulation :** ``` Rôle : Tu es un expert en communication publique. Objectif : Reformule ce mail pour le rendre plus clair et professionnel. Contexte : [coller le texte ici] ``` ### Puis-je utiliser l'Assistant IA pour des tâches administratives ? **Oui, mais avec précaution :** * L'Assistant peut vous aider à **rédaction de projets de textes, synthèses, recherches d'information** * **Ne l'utilisez PAS** pour prendre des décisions administratives individuelles (actes unilatéraux visant des personnes nommément désignées) * Toujours **vérifier et valider** les informations générées ### Quels types de fichiers puis-je téléverser ? **Formats supportés :** * **Documents :** PDF, Markdown (.md), Word (.docx), PowerPoint (.pptx), Excel (.xlsx) * **Images :** JPG, PNG, WEBP * **Autres :** TXT, CSV (selon configuration) **Limites :** * Taille maximale : généralement 10 Mo par fichier (variable) * Nombre de fichiers : plusieurs peuvent être téléversés simultanément ### Combien de temps mes conversations sont-elles conservées ? Vos conversations sont conservées **tant que votre compte est actif**. Vous pouvez : * **Archiver** des conversations pour les cacher de la vue principale * **Supprimer** des conversations définitivement * **Exporter** vos échanges si nécessaire (fonctionnalité à venir) *** ## Sécurité et confidentialité ### Mes données sont-elles sécurisées ? **Oui, plusieurs niveaux de protection :** * **Hébergement souverain** : Infrastructure SecNumCloud en France * **Isolement** : Vos données sont strictement séparées de celles des autres utilisateurs * **Accès restreint** : Seuls vous et les administrateurs autorisés pouvez accéder à vos conversations ### Qui peut accéder à mes conversations ? **Par défaut :** * **Vous seul** avez accès à vos conversations * Les **administrateurs techniques** de la DINUM peuvent accéder aux données **En cas d'analyse activée :** * L'équipe produit peut consulter vos échanges **à des fins d'amélioration du service uniquement** * Les données ne sont **jamais** utilisées pour entraîner des modèles * Les données ne sont **jamais** partagées avec des tiers ### Mes données sont-elles utilisées pour entraîner des modèles ? **Non, absolument pas.** * Vos conversations **ne sont jamais** utilisées pour entraîner des modèles d'IA * Vos données **n'apparaîtront jamais** dans les réponses à d'autres utilisateurs * La DINUM n'entraîne pas de modèles, elle utilise des modèles existants du marché ### Puis-je utiliser l'Assistant avec des données sensibles ? **Oui, l'Assistant est homologué pour le traitement de données sensibles au sens de la loi SREN. Contactez votre hierarchie pour connaître le cadre d'usage spécifique à votre administration.** **À NE PAS faire :** * ❌ Données médicales * ❌ Données classifiées (Diffusion restreinte, Secret, Très Secret) * ❌ Données sensibles au sens de l'ANSSI **À faire :** * ✅ Anonymisez les données lorsque vous le pouvez * ✅ Consultez votre référent IA ou DPO en cas de doute * ✅ Préférez les données déjà publiques *** ## Modèles et fonctionnalités ### Quel modèle d'IA est utilisé ? **Modèle principal actuel :** Mistral Medium 3.5 D'autres modèles peuvent être utilisée lorsque l'Assistant connaît une forte charge, afin que votre expérience soit la plus pérenne possible : si les serveurs du modèle principal sont surchargé, vous basculez sur un autre modèle, qui répond aux mêmes exigences de sécurité et de souveraineté. De plus, si certaines fonctionalités sont dégradées du fait du changement de modèle, un bandeau d'erreur s'affichera en haut de la page de l'Assistant. ### Pourquoi les réponses varient-elles selon les modèles ? Chaque modèle a ses propres caractéristiques : * **Force** : Certains modèles sont meilleurs pour des tâches spécifiques * **Style** : Les réponses peuvent avoir des tonalités différentes * **Connaissances** : Les dates de coupure des données d'entraînement varient * **Capacités** : Certains modèles gèrent mieux les longs contextes ou les documents ### La recherche web est-elle toujours activée ? **Deux modes disponibles :** 1. **Recherche manuelle** : Vous cliquez sur l'icône 🌐 pour activer la recherche 2. **Recherche intelligente** : Activez cette option dans vos paramètres pour que l'Assistant décide automatiquement quand faire une recherche **À noter :** * La recherche utilise **Brave Search API** * Les requêtes sont conservées par Brave pendant **90 jours** (voir leur [déclaration de traitement](https://cdn.search.brave.com/search-api/web/v1/client/_app/immutable/assets/brave-search-api-dpa-2025-09-09.DRXCoye6.pdf)) * Les résultats sont résumés et intégrés dans la réponse *** ## Projets et organisation ### C'est quoi un projet ? Un **projet** est un espace qui regroupe plusieurs conversations avec : * Une **instruction commune** partagée par toutes les conversations du projet * Un **contexte documentaire spécifique** pour adapter le comportement de l'Assistant * Une **organisation simplifiée** de vos échanges par thème **Exemples d'utilisation :** * Un projet "Rédaction administrative" avec des instructions pour adopter un style formel * Un projet "Analyse juridique" avec un contexte sur les textes de référence * Un projet "Veille technologique" pour suivre l'actualité d'un domaine ### Comment créer un projet ? 1. Cliquez sur "Nouveau projet" dans la barre latérale 2. Donnez un nom à votre projet 3. Définissez l'instruction commune (optionnel mais recommandé) 4. Ajoutez éventuellement des documents de référence 5. Commencez une nouvelle conversation dans ce projet *** ## Techniques ### Quelle est la limite de contexte ? La taille maximale d'une conversation (vos messages + les réponses + les extraits de documents) est d'environ **100 000 mots** (soit environ 300-400 pages de texte). **Bonnes pratiques :** * Commencez une nouvelle conversation pour les longs échanges * Résumez régulièrement les points clés * Archivez les anciennes conversations ### Pourquoi ai-je une erreur de limite de contexte ? Cette erreur apparaît lorsque la conversation atteint la limite maximale. **Solutions :** 1. Commencez une **nouvelle conversation** 2. **Résumez** les points importants de l'ancienne conversation dans un nouveau message 3. **Divisez** votre travail en plusieurs conversations thématiques 4. **Archivez** les conversations terminées ### Puis-je exporter mes conversations ? La fonctionnalité d'export est **en développement**. En attendant, vous pouvez : * **Copier-coller** manuellement le contenu * **Prendre des captures d'écran** pour les échanges importants *** ## Support et communauté ### Où puis-je échanger avec d'autres utilisateurs ? Rejoignez la communauté sur **Tchap** : [Canal Assistant IA](https://tchap.gouv.fr/#/room/!eAHyPLdVHMxNhKAbaC:agent.dinum.tchap.gouv.fr) ### Qui contacter en cas de problème ? 1. **Votre référent IA** ministériel (pour les problèmes de cadre d'usage ou de formation) 2. **L'équipe DINUM** via les canaux officiels 3. [**Signaler un problème**](/assistant-ia/depannage/report-issue) pour les bugs techniques ### Comment signaler un bug ? Rendez vous sur la page Signaler un problème : {% content-ref url="/pages/ziVqPfmpjAj0KTQ9dOXZ" %} [Signaler un problème](/assistant-ia/depannage/report-issue) {% endcontent-ref %} *** ## Divers ### L'Assistant IA est-il meilleur que ChatGPT ? **Différences principales :** | Critère | Assistant IA | ChatGPT | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | **Souveraineté** | ✅ Hébergé en France (SecNumCloud) | ❌ Hébergé aux États-Unis | | **Confidentialité** | ✅ Données ne sortent pas de France | ❌ Données peuvent être stockées à l'étranger | | **Accès** | ✅ Réservé aux agents publics | ❌ Ouvert au grand public | | **Modèles** | Modèles ouverts et propriétaires d'environ 120 milliard de paramètres, limités par des logiques de coût et d'empreinte environnementales | Modèles propriétaires de plusieurs téras de paramètres (1000 milliards, soit 10 fois plus coûteux), avec des meilleurs performances | | **Sécurité** | ✅ Adapté aux contraintes de l'État | ❌ Non conçu pour les besoins publics | L'Assistant IA est **spécifiquement conçu** pour répondre aux besoins des agents publics dans un cadre **souverain et sécurisé**. ### Puis-je utiliser l'Assistant IA sur mobile ? **Oui**, l'application web est **disponible sur votre navigateur** et fonctionne sur : * Smartphones (iOS et Android) * Tablettes * Ordinateurs portables **Recommandations :** * Ajoutez un marque-page sur l'Assistant qui peut prendre la forme d'une icone sur mobile ou d'un raccourci sur ordinateur. *** ## Besoin d'aide supplémentaire ? Si vous ne trouvez pas de réponse à votre question : * [**Consultez le guide de dépannage**](/assistant-ia/depannage/erreurs) pour les problèmes techniques * [**Signalez un problème**](/assistant-ia/depannage/report-issue) à l'équipe * **Contactez votre référent IA** ministériel # Signaler un problème Signaler un problème technique ou un bug sur l'Assistant IA Rencontrez-vous un bug, une erreur ou un comportement inattendu ? Signalez-le nous pour que nous puissions investiguer et corriger le problème rapidement. ## Avant de signaler Vérifiez d'abord si votre problème est déjà documenté : 1. [**Consultez le guide de dépannage**](/assistant-ia/depannage/erreurs) - Solutions aux problèmes courants 2. [**Parcourez la FAQ**](/assistant-ia/depannage/faq) - Réponses aux questions fréquentes 3. **Essayez les solutions proposées** avant de signaler ## Comment signaler un problème Envoyez un email à : **** Nous centralisons toutes les remontées de problèmes et demandes de support. *** ## Informations à fournir Pour que nous puissions traiter votre signalement efficacement, **merci de fournir un maximum d'informations** : ### 📋 Informations obligatoires | Information | Exemple | Pourquoi c'est important | | --------------------------- | ------------------------------------------------------------------------------ | ------------------------------------- | | **Description du problème** | "L'Assistant ne répond pas quand je clique sur Envoyer" | Nous permet de comprendre le problème | | **Étapes pour reproduire** | 1. Ouvrir une nouvelle conversation 2. Écrire "Bonjour" 3. Cliquer sur Envoyer | Nous permet de reproduire et corriger | | **Comportement attendu** | "L'Assistant devrait répondre avec un message de salutation" | Savoir ce qui devrait se passer | | **Comportement réel** | "Rien ne se passe, pas de réponse" | Comprendre l'anomalie | ### 📊 Informations techniques utiles | Information | Comment l'obtenir | Exemple | | -------------------------- | -------------------- | ------------------------------------------------- | | **Navigateur** | Menu Aide > À propos | Chrome 125.0.6422.60 | | **Système d'exploitation** | Paramètres système | Windows 11, macOS Sonoma 14.4 | | **Appareil** | - | ordinateur portable, iPhone 15 | | **Date et heure** | - | 29/05/2026, 14:30 | | **URL de la page** | Barre d'adresse | | ### 📎 Pièces jointes utiles Vous pouvez joindre : * **Capture d'écran** du problème (avec l'URL visible si possible) * **Vidéo** montrant les étapes pour reproduire (max 2 min) * **Fichier** qui pose problème (si applicable) * **Logs** (pour les utilisateurs techniques) {% hint style="info" %} **Pour les captures d'écran :** N'incluez **pas** de données sensibles ou personnelles. Floutez les informations confidentielles avant l'envoi. {% endhint %} {% hint style="warning" %} **Problèmes urgents :** En cas de suspicion de **fuite de données** ou de **violation de sécurité**, contactez **immédiatement** votre référent IA ou l'équipe DINUM. {% endhint %} ## Conseils pour un signalement efficace ✅ **À faire :** * Soyez **précis** et **détaillé** * Fournissez des **étapes claires** pour reproduire * Joignez des **captures d'écran** ou **vidéos** * Mentionnez votre **navigateur** et **système d'exploitation** ❌ **À éviter :** * "L'Assistant ne marche pas" (trop vague) * "J'ai un problème" (sans détails) * Signaler des **problèmes déjà connus** (vérifiez le statut du service) Voir la page [Comprendre les erreurs de l'Assistant](/assistant-ia/depannage/erreurs) {% hint style="success" %} Merci de votre contribution ! Chaque signalement nous aide à améliorer l'Assistant IA pour tous les agents publics. {% endhint %} # Accéder à l'Assistant ### Qui est éligible à utiliser l'Assistant IA ? L'Assistant est un produit développé et opéré par la DINUM, à destination **des services de l'État et de ses organismes de tutelle.** Le périmètre de l'accès à l'Assistant est un périmètre au niveau des services et administrations et non des agents individuels : ainsi, il est essentiel de vérifier si votre service, et non votre statut individuel, tombe dans cette définition.
### Mon administration est-elle un **service de l'État ou de ses organismes de tutelle** ? L'unique manière d'être surs que votre administration relève bien de cette définition est de contacter votre **hiérarchie** ou votre **service juridique**. Il existe un nombre trop importants de cas particuliers pour que nous puissions les détailler.\ \ Nous devons nous même effectuer une analyse juridique afin de fournir des réponses détaillés. La seule manière d'accéder à cette analyse est en remplissant le [Datapass d'accès à L'Assistant](https://datapass.api.gouv.fr/formulaires/produits_dinum/demande/nouveau) #### Exemples d'administrations éligibles * Les services centraux des ministères * Les services déconcentrés des ministères * Les autoriés administratives ou publiques indépendantes * Les établissements publics nationaux ayant fonction d'administration centrale #### Exemples d'administrations non éligibles * Collectivités territoriales ### Je pense être dans un service éligible mais je n'ai pas accès, pourquoi ? L'authentification à l'Assistant ce fait grâce à ProConnect, qui nous fournit des informations sur votre service de rattachement. C'est grâce à cette information que nous faisons le tri. Si vous n'avez pas accès, c'est que votre service de rattachement n'est pas directement catégorisé comme éligible : conformément aux sections précédentes, vous pouvez, en accord avec votre hierarchie, entamer le processus de demande d'accès à L'Assistant sur la plateforme DataPass :
Nos équipes juridiques instruiront ensuite l'éligibilité de votre service. # Mentions légales Les présentes mentions légales s'appliquent à l'utilisation de l'**Assistant IA**, service développé et opéré par la Direction interministérielle du numérique (DINUM). ## Éditeur **Nom :** Direction interministérielle du numérique (DINUM) **Adresse :** ``` 20 avenue de Ségur 75007 Paris France ``` **Téléphone :** 01.71.21.01.70 (Accueil du Secrétariat général du gouvernement) **SIRET :** 12000101100010 (Secrétariat général du gouvernement) **SIREN :** 120 001 011 **Représentant légal :** Madame Stéphanie Schaer, Directrice interministérielle du numérique **Directrice de la publication :** Madame Stéphanie Schaer *** ## Hébergement **Fournisseur :** Outscale **Adresse :** ``` 1, rue Royale – 319 Bureaux de la Colline 92210 Saint-Cloud France ``` **Site web :** **Certification :** SecNumCloud (délivrée par l'ANSSI) **Infrastructure :** * Filiale de Dassault Systèmes * Niveau de sécurité le plus élevé pour les services cloud en France * Conformité aux exigences de souveraineté française et européenne *** ## Infrastructure et sécurité ### Sécurité des communications * **Chiffrement** : Toutes les communications sont protégées par TLS 1.3 * **Authentification** : Accès sécurisé via ProConnect (basé sur FranceConnect) ### Mesures de sécurité techniques * Chiffrement des données au repos (AES-256) * Journalisation des activités * Tests de sécurité réguliers * Audits externes ### Certifications * **SecNumCloud** : Certification de sécurité cloud délivrée par l'ANSSI * **ISO 27001** : Norme internationale de management de la sécurité de l'information (en cours) *** ## Conformité réglementaire ### Loi SREN (Sécurité et Résilience des Espaces Numériques) L'Assistant IA respecte les exigences de la [loi SREN](https://www.numerique.gouv.fr/publications/rn-num/loi-sren/) : ✅ **Souveraineté numérique** : Infrastructure et services sous contrôle français/européen ✅ **Résilience** : Architecture redondante et résistante ✅ **Protection des données** : Mesures adaptées au niveau de sensibilité Respect des exigences pour le traitement des informations classifiées : * **Diffusion Restreinte** : **Non autorisé** dans l'Assistant IA (sauf configuration spécifique) * **Secret** : **Interdit** * **Très Secret** : **Interdit** {% hint style="warning" %} **Important :** L'Assistant IA n'est **pas homologué** pour le traitement de données classifiées. Ne soumettez **jamais** de données sensibles au sens de l'ANSSI. {% endhint %} *** ## Service **Nom commercial :** Assistant IA **URL :** **Description :** Plateforme conversationnelle d'intelligence artificielle générative destinée aux agents des administrations de l'État et de leurs organismes de tutelle. *** ## Conditions d'utilisation ### Acceptation L'utilisation de l'Assistant IA implique l'acceptation pleine et entière des présentes mentions légales. ### Modifications La DINUM se réserve le droit de modifier à tout moment les présentes mentions légales. Les utilisateurs seront informés des modifications substantielles. ### Accès au service L'accès à l'Assistant IA est **gratuit** et réservé aux : * Agents des administrations de l'État * Agents des organismes sous tutelle de l'État * Partenaires et prestataires autorisés par leur administration de rattachement L'accès se fait via **ProConnect** avec des identifiants professionnels valides. ### Propriété intellectuelle #### Code source Le code source de l'Assistant IA est **open source** et disponible sous licence [MIT](https://github.com/suitenumerique/conversations/blob/main/LICENSE) sur : #### Contenus Sauf mention contraire, les contenus produits par la DINUM (documentation, guides, etc.) sont proposés sous [Licence Ouverte Etalab 2.0](https://www.etalab.gouv.fr/wp-content/uploads/2017/04/ETALAB-Licence-Ouverte-v2.0.pdf). **Vous êtes autorisé à :** * Reproduire, copier, modifier, extraire, transformer * Communiquer, diffuser, redistribuer, publier, transmettre, exploiter **Sous réserve de :** * Mentionner la source * Mentionner la date de dernière mise à jour * Ne pas induire en erreur des tiers quant aux informations #### Logos et marques Les logos et marques de l'État, de la DINUM, de LaSuite et de l'Assistant IA sont **protégés** et ne peuvent être utilisés sans autorisation préalable. #### Modèles d'IA Les modèles d'IA utilisés (Mistral, etc.) sont la propriété de leurs éditeurs respectifs. Leurs licences sont documentées sur : #### Contenus générés par les utilisateurs Les utilisateurs conservent **tous les droits** sur les contenus qu'ils créent ou soumettent via l'Assistant IA. **À noter :** La DINUM ne revendique **aucune propriété** sur les contenus générés par les utilisateurs. *** ## Protection des données Pour les informations détaillées sur le traitement des données personnelles, consultez notre page dédiée : [Protection des données](/assistant-ia/documentation-legale/data-protection) **Responsable du traitement :** Votre administration de rattachement **Délégué à la Protection des Données (DPO) :** * Pour votre administration : contactez votre DPO interne * Pour la DINUM : *** ## Responsabilités ### Responsabilités de la DINUM La DINUM s'engage à : * Maintenir le service disponible dans des conditions raisonnables * Assurer la sécurité et la confidentialité des données * Respecter les obligations légales en vigueur * Corriger les dysfonctionnements signalés **La DINUM ne garantit pas :** * L'exactitude absolue des contenus générés par l'IA * La disponibilité permanente du service (maintenances, incidents) * L'absence totale de bugs ou d'erreurs ### Responsabilités des utilisateurs Les utilisateurs s'engagent à : * Respecter les présentes mentions légales * Utiliser le service conformément à son objet * Ne pas soumettre de données interdites (sensibles, personnelles non anonymisées, etc.) * Respecter les lois et réglementations en vigueur * Ne pas tenter de contourner les mesures de sécurité **Les utilisateurs sont responsables :** * Des contenus qu'ils soumettent * De l'usage qu'ils font des réponses générées * Du respect des règles de leur administration ### Limitation de responsabilité La DINUM ne peut être tenue responsable : * Des dommages indirects (perte de données, préjudice commercial, etc.) * De l'utilisation frauduleuse du service par des tiers * Des conséquences de l'utilisation des contenus générés * Des interruptions de service *** ## Utilisation interdite Il est **strictement interdit** d'utiliser l'Assistant IA pour : ❌ Générer ou diffuser des contenus illicites (haine, discrimination, etc.) \ ❌ Enfreindre les lois et réglementations en vigueur \ ❌ Traiter des données classifiées (Diffusion restreinte, Secret, Très Secret) \ ❌ Prendre des décisions administratives individuelles \ ❌ Usurper l'identité d'autrui \ ❌ Effectuer des activités de piratage ou de test d'intrusion non autorisé \ ❌ Utiliser le service à des fins personnelles ou commerciales non autorisées \ ❌ Contourner les mesures de sécurité ou de limitation d'accès *** ## Accessibilité ### État de conformité L'Assistant IA (assistant.numerique.gouv.fr) **n'est pas encore pleinement conforme** au [RGAA 4.1](https://www.numerique.gouv.fr/publications/rgaa-accessibilite/). **Statut :** Partiellement accessible **Audit :** En cours **Date prévue de conformité :** À déterminer ### Déclaration d'accessibilité Une déclaration d'accessibilité complète sera publiée une fois l'audit terminé. **Contact accessibilité :** ### Mesures d'accessibilité Nous nous engageons à rendre le service accessible conformément à l'article 47 de la loi n° 2005-102 du 11 février 2005. **Actions en cours :** * Audit RGAA complet * Correction des non-conformités identifiées * Formation des équipes aux bonnes pratiques * Tests utilisateurs avec des personnes en situation de handicap *** ## Sécurité ### Certifications * **Hébergement SecNumCloud** : Certification de sécurité cloud délivrée par l'ANSSI ### Mesures de sécurité * Chiffrement de toutes les communications (TLS 1.3) * Chiffrement des données au repos (AES-256) * Authentification forte (ProConnect) * Journalisation des activités * Tests de sécurité réguliers * Audits externes Pour plus de détails : [Sécurité et souveraineté](/assistant-ia/guides-pratiques/securite-et-souverainete) *** ## Cookies ### Utilisation Ce site utilise un **cookie de session** pour : * Maintenir votre connexion authentifiée * Améliorer votre expérience utilisateur ### Mesure d'audience Nous utilisons **PostHog** pour mesurer l'audience et comprendre l'usage du service. **Données collectées :** * Pages consultées * Fonctionnalités utilisées * Temps passé * Appareil et navigateur (anonymisés) **Durée :** Données conservées 2 ans (anonymisées) **Opt-out :** Vous pouvez désactiver le suivi d'audience dans vos paramètres. ### Pourquoi pas de bannière de consentement ? Conformément à la loi, certains outils de mesure d'audience, correctement configurés pour respecter la vie privée, sont **exemptés d'autorisation préalable**. *** ## Contact **Email :** ### Adresse postale ``` Direction interministérielle du numérique (DINUM) 20 avenue de Ségur 75007 Paris France ``` *** ## Réutilisation des contenus ### Licence Sauf mention contraire, les contenus de ce site sont proposés sous [Licence Ouverte Etalab 2.0](https://www.etalab.gouv.fr/wp-content/uploads/2017/04/ETALAB-Licence-Ouverte-v2.0.pdf). ### Conditions Vous êtes libre de : * Reproduire, copier, modifier, extraire, transformer * Communiquer, diffuser, redistribuer, publier, transmettre, exploiter **Sous réserve de :** 1. **Mentionner** la source (ex: "Source : Assistant IA - DINUM") 2. **Mentionner** la date de dernière mise à jour 3. **Ne pas induire en erreur** des tiers quant aux informations 4. **Ne pas suggérer** que la DINUM ou l'État endosse votre utilisation ### Exceptions Les éléments suivants **ne sont pas** couverts par la Licence Ouverte : * Les logos et marques de l'État, de la DINUM, de LaSuite * Les contenus provenant de tiers (mentionnés comme tels) * Les données personnelles * Les contenus générés par les utilisateurs *** ## Liens vers des sites externes L'Assistant IA peut contenir des liens vers des sites externes. La DINUM : * Ne contrôle pas ces sites * N'est pas responsable de leur contenu * Ne peut garantir leur accessibilité ou leur conformité Les liens vers des sites externes sont fournis à titre d'information et ne constituent pas une approbation. *** ## Droit applicable Les présentes mentions légales sont régies par le **droit français**. En cas de litige, les tribunaux français seront **seuls compétents**. *** ## Divers ### Langue Les présentes mentions légales sont rédigées en français. En cas de traduction, la version française fait foi. ### Version **Version actuelle :** 2.0 **Date de dernière mise à jour :** 29 mai 2026 **Changelog :** * v2.0 (29/05/2026) : Adaptation pour l'accès généralisé, suppression de la logique des codes * v1.0 (22/10/2025) : Version initiale pour l'expérimentation *** {% hint style="info" %} Pour toute question ou demande de clarification concernant ces mentions légales, contactez-nous à : **** {% endhint %} # Protection des données Cette page explique comment vos données sont **collectées, traitées, protégées et stockées** dans le cadre de l'utilisation de l'Assistant IA, conformément au **Règlement Général sur la Protection des Données (RGPD)** et à la législation française. ## Qui est responsable de vos données ? ### Responsable du traitement **Votre administration de rattachement** est le **responsable du traitement** des données personnelles liées à votre utilisation de l'Assistant IA. **Pourquoi ?** * Votre administration décide qui a accès au service * Elle définit les règles d'utilisation internes * Elle est responsable du traitement des données de ses agents ### Sous-traitant La **Direction interministérielle du numérique (DINUM)** agit en tant que **sous-traitant** pour la mise à disposition technique du service. **Rôle de la DINUM :** * Hébergement et maintenance de la plateforme * Fourniture de l'infrastructure technique * Support et amélioration du service *** ## Quelles données sont collectées ? Nous collectons uniquement les données **nécessaires** au fonctionnement du service et à la réalisation de nos missions de service public. ### Données d'identification | Donnée | Source | Finalité | Base juridique | Durée | | ------------------- | ---------- | -------------------------------- | ------------------------------------------ | ------------------ | | Prénom | ProConnect | Identification, personnalisation | Mission d'intérêt public (Art. 6.1.e RGPD) | Suppression compte | | Nom | ProConnect | Identification, personnalisation | Mission d'intérêt public (Art. 6.1.e RGPD) | Suppression compte | | Email professionnel | ProConnect | Contact, gestion de compte | Mission d'intérêt public (Art. 6.1.e RGPD) | Suppression compte | | Organisation | ProConnect | Gestion des accès, statistiques | Mission d'intérêt public (Art. 6.1.e RGPD) | Suppression compte | ### Données de contenu | Donnée | Source | Finalité | Base juridique | Durée | | ---------------------------- | ------------------ | --------------------------------------------- | ------------------------------------------ | ------------------ | | Messages (conversations) | Saisie utilisateur | Fourniture du service IA | Mission d'intérêt public (Art. 6.1.e RGPD) | Suppression compte | | Documents téléversés | Upload utilisateur | Analyse par l'IA, génération de réponses | Mission d'intérêt public (Art. 6.1.e RGPD) | Suppression compte | | Historique des conversations | Système | Continuité du service, expérience utilisateur | Mission d'intérêt public (Art. 6.1.e RGPD) | Suppression compte | ### Données techniques | Donnée | Source | Finalité | Base juridique | Durée | | ------------------ | ---------- | ---------------------------- | --------------------------------------------- | ----- | | Adresse IP | Connexion | Sécurité, détection des abus | Obligation légale (Loi n°2004-575) | 1 an | | Logs de connexion | Système | Sécurité, maintenance, audit | Obligation légale (Art. 5 décret n°2021-1362) | 1 an | | Type de navigateur | Navigateur | Compatibilité, statistiques | Intérêt légitime (Art. 6.1.f RGPD) | 2 ans | | Appareil | Navigateur | Statistiques, amélioration | Intérêt légitime (Art. 6.1.f RGPD) | 2 ans | ### Données d'usage (si analyse activée) | Donnée | Source | Finalité | Base juridique | Durée | | ------------------------- | ------- | ----------------------------------------------- | ---------------------------------- | ------------------ | | Contenu des conversations | Système | Amélioration du service, évaluation des modèles | Consentement (Art. 6.1.a RGPD) | Suppression compte | | Fréquence d'utilisation | Système | Statistiques, optimisation | Intérêt légitime (Art. 6.1.f RGPD) | 2 ans | | Fonctionnalités utilisées | Système | Compréhension des besoins | Intérêt légitime (Art. 6.1.f RGPD) | 2 ans | *** ## Où vos données sont-elles stockées ? ### Localisation géographique **Toutes vos données sont stockées et traitées en France.** * **Hébergement :** Outscale (Saint-Cloud, France) * **Infrastructure :** SecNumCloud (certification ANSSI) * **Sauvegardes :** France (plusieurs sites) ### Pas de transfert hors UE **Aucune donnée ne quitte le territoire français.** * Pas de stockage aux États-Unis * Pas de traitement par des fournisseurs américains * Pas de transfert vers des pays tiers ### Exception : Mesure d'audience **PostHog** (outil de mesure d'audience) est hébergé en Allemagne. * **Données envoyées :** Statistiques d'usage **anonymisées** * **Pas de données personnelles** transmises * **Conformité RGPD** garantie * **Clauses contractuelles** de protection des données *** ## Protection et sécurité des données ### Isolement des données * **Multi-tenancy sécurisé** : Isolation complète entre utilisateurs * **Pas de partage** : Vos données ne sont **jamais** accessibles par d'autres utilisateurs * **Compartimentage** : Séparation logique entre les données ### Gestion des accès **Principes :** * **Moindre privilège** : Chaque utilisateur a uniquement les permissions nécessaires * **Authentification forte** : ProConnect (basé sur FranceConnect) *** ## Sous-traitants Nous faisons appel à des sous-traitants pour l'hébergement et la mesure d'audience. Avant de leur transmettre vos données, nous nous sommes assurés de la mise en œuvre de garanties adéquates et du respect de conditions strictes de confidentialité, d'usage et de protection des données. | Partenaire | Pays | Rôle | Garanties | | ---------------- | --------- | ---------------------- | ---------------------------------------- | | **Outscale** | France | Hébergement | SecNumCloud, clauses contractuelles | | **IndieHosters** | France | Administration cluster | Clauses de sous-traitance | | **PostHog** | Allemagne | Mesure d'audience | Clauses de sous-traitance, anonymisation | *** ## Sécurité des fonctionnalités ### Recherche web - option qui doit être activée par l'utilisateur **Fournisseur :** Brave Search API **Protection :** * Vos messages ne sont pas envoyés tels quels : le modèle formule une requête internet basée sur votre message * Pas de tracking utilisateur : les requêtes envoyées pendant vos conversations ne sont pas traçables par le fournisseur Brave * Les requêtes sont conservées par Brave pendant **90 jours** (voir leur [DPA](https://cdn.search.brave.com/search-api/web/v1/client/_app/immutable/assets/brave-search-api-dpa-2025-09-09.DRXCoye6.pdf)) **Alternative :** Vous pouvez à tout désactiver la recherche web automatique dans vos paramètres. Celle ci est désactivée par défaut. ### Téléversement de documents **Sécurité :** * **Scan antivirus** : Tous les documents sont scannés avant traitement * **Limite de taille** : 10 Mo par fichier (configurable) * **Types autorisés** : Formats sûrs uniquement (PDF, images, bureautique) * **Isolement** : Traitement dans un environnement sécurisé **Nettoyage :** * Documents temporaires supprimés après traitement * Pas de conservation au-delà de la durée de la conversation (sauf si explicitement sauvegardé) ### Historique des conversations **Protection :** * Accès restreint à l'utilisateur propriétaire * Possibilité de suppression à tout moment **Durée :** * Conservé tant que le compte est actif * Suppression possible à tout moment par l'utilisateur * (À venir) Suppression automatique au bout de 12 mois d'inactivité *** ## Option "Autoriser l'analyse de conversation" **Par défaut :** Désactivée **Si activée :** * L'équipe produit DINUM peut accéder à vos conversations * **Uniquement** à des fins d'amélioration et de support * Les données **ne sont jamais** utilisées pour entraîner des modèles * Les données **ne sont jamais** partagées avec des tiers **Si désactivée :** * Vos conversations restent **strictement privées** * Seuls vous et les administrateurs techniques peuvent y accéder en cas de problème. **Où modifier :** Paramètres > Autoriser l'analyse de conversation *** ## À quoi servent vos données ? ### Finalités principales 1. **Fourniture du service** * Permettre l'accès à l'Assistant IA * Générer des réponses aux questions * Maintenir l'historique des conversations * Analyser les documents téléversés 2. **Sécurité et protection** * Authentifier les utilisateurs * Détecter et prévenir les abus * Protéger contre les attaques * Garantir l'intégrité du service 3. **Amélioration du service** (si analyse activée) * Évaluer la pertinence des réponses * Identifier les besoins des utilisateurs * Optimiser les fonctionnalités * Orienter la feuille de route 4. **Statistiques et reporting** (anonymisées) * Comprendre l'usage global * Mesurer l'adoption * Identifier les tendances * Justifier les investissements *** ## Qui a accès à vos données ? ### Accès par défaut | Acteur | Accès | Justification | | -------------------------- | ------------------------- | ------------------------ | | **Vous** | Toutes vos données | Propriétaire des données | | **Votre administration** | Statistiques anonymisées | Pilotage du déploiement | | **Équipe technique DINUM** | Données techniques (logs) | Maintenance et support | ### Accès conditionnel | Acteur | Accès | Condition | Justification | | ------------------------ | ------------------------- | ---------------------------------------- | --------------------------- | | **Équipe produit DINUM** | Contenu des conversations | **Option "Autoriser l'analyse" activée** | Amélioration du service | | **Support DINUM** | Conversations spécifiques | **Signalement d'un problème** | Résolution des incidents | | **Auditeurs** | Données anonymisées | Audit de sécurité | Conformité et certification | ### Accès interdit ❌ **Jamais partagées avec :** * Des tiers commerciaux * Des fournisseurs de modèles d'IA (Mistral, etc.) * Des autorités étrangères * D'autres utilisateurs ❌ **Jamais utilisées pour :** * L'entraînement de modèles d'IA * Le marketing ou la publicité * La revente ou l'exploitation commerciale * Le profilage non autorisé *** ## Vos droits sur vos données Conformément au RGPD, vous disposez des droits suivants sur vos données personnelles : ### 1. Droit d'accès **De quoi s'agit-il ?** Savoir quelles données nous détenons sur vous. **Comment l'exercer ?** * Contacter votre administration de rattachement * Ou contacter le DPO de la DINUM : **Délai de réponse :** 1 mois ### 2. Droit de rectification **De quoi s'agit-il ?** Corriger des données inexactes ou incomplètes. **Comment l'exercer ?** * Modifier directement dans votre profil (pour certaines données) * Contacter votre administration **Délai de réponse :** 1 mois ### 3. Droit à l'effacement ("droit à l'oubli") **De quoi s'agit-il ?** Supprimer vos données. **Limites :** * ✅ Possible pour vos conversations et documents * ❌ Impossible si conservation légale obligatoire (logs de sécurité) **Comment l'exercer ?** * Supprimer manuellement vos conversations * Demander la suppression de votre compte ### 4. Droit à la portabilité **De quoi s'agit-il ?** Récupérer vos données dans un format structuré. **Données concernées :** * Vos conversations * Vos documents téléversés **Format :** JSON, PDF ou autre format ouvert **Statut :** Demande manuelle uniquement ### 5. Droit d'opposition **De quoi s'agit-il ?** Refuser le traitement de vos données. **Cas possibles :** * Désactiver l'analyse des conversations * Refuser la mesure d'audience * Opposer à un traitement spécifique **Comment l'exercer ?** * Dans vos paramètres (pour l'analyse) * Par demande écrite ### 6. Droit à la limitation **De quoi s'agit-il ?** Limiter temporairement le traitement. **Cas possibles :** * Contester l'exactitude des données * Exercer votre droit d'opposition ### 7. Droit de ne pas faire l'objet d'une décision automatisée **Application :** Conformément à ses modalités d'utilisation, l'Assistant IA n'est **pas utilisé** pour prendre des décisions administratives individuelles vous concernant. *** ## Comment exercer vos droits ? ### Étape 1 : Contacter votre administration **Méthode recommandée :** 1. Identifiez votre administration de rattachement 2. Contactez son **Délégué à la Protection des Données (DPO/DPD)** 3. Faites votre demande par écrit (email ou courrier) **Où trouver le contact DPO ?** * Liste publique : * Intranet de votre administration * Demander à votre hiérarchie ### Étape 2 : Utiliser les modèles de la CNIL La CNIL fournit des modèles de demandes : ### Étape 3 : Contacter la DINUM (si nécessaire) Si vous ne pouvez pas contacter votre administration : **Email :** **Courrier :** ``` Services du Premier ministre À l'attention du délégué à la protection des données (DPD) 56 rue de Varenne 75007 Paris ``` **La DINUM transmettra votre demande à votre administration de rattachement.** ## Ressources supplémentaires * [**Mentions légales**](/assistant-ia/documentation-legale/legal) - Cadre juridique complet * [**Sécurité et souveraineté**](/assistant-ia/guides-pratiques/securite-et-souverainete) - Mesures techniques * [**CNIL**](https://www.cnil.fr/) - Autorité de protection des données française * [**RGPD**](https://eur-lex.europa.eu/legal-content/FR/TXT/?uri=CELEX%3A32016R0679) - Texte officiel du règlement * [**Modèles de courrier CNIL**](https://www.cnil.fr/fr/modeles/courrier) - Pour exercer vos droits *** {% hint style="success" %} La protection de vos données est une **priorité absolue** pour la DINUM. Nous mettons tout en œuvre pour garantir la **confidentialité, la sécurité et la conformité** de vos données personnelles. En cas de question, n'hésitez pas à contacter votre DPO ou l'équipe de la DINUM. {% endhint %} # Modalités d'utilisation ## 1. Champ d’application Le présent document définit les modalités d’utilisation de l’**Assistant IA** (ci-après "l'Assistant IA", "l'Assistant" ou "l'application"), une interface conversationnelle d’intelligence artificielle conçue pour les administrations de l’État et les organismes sous sa tutelle. ## 2. Objet de la plateforme L’Assistant IA facilite l’utilisation de modèles de langage en fournissant une interface permettant de générer du contenu en réponse à des demandes des utilisateurs et utilisatrices. L’Assistant IA est développé et opéré par la **Direction interministérielle du numérique (DINUM)**. Toute utilisation de ce service doit respecter les présentes modalités d’utilisation. ## 3. Définitions | Terme | Définition | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Utilisateurs et utilisatrices** | Toute personne utilisant l’Assistant IA à des fins de génération de contenu par un modèle de langage, qu’elles soient des agents, des partenaires ou des prestataires des administrations de rattachement. | | **Administration de rattachement** | L’administration relevant du système d’information et de communication de l’État qui met à disposition l’Assistant IA à ses agents, partenaires ou prestataires. | | **Modèles de langage** | Des modèles génératifs qui, à partir de grands volumes de données textuelles, calculent des probabilités des enchaînements de jetons textuels en vue de la génération automatique de texte ou de code informatique. | | **Contenu** | Éléments textuels générés en fonction des requêtes des utilisateurs, de la configuration du modèle par l’équipe Assistant IA, des documents fournis par l’utilisateur, des données d’entraînement du modèle, et de l'historique de la conversation en cours. | | **Configuration du modèle** | Jeu d’instructions, défini dans le code source de l’Assistant IA, qui constitue le cadre d’échange perçu par le modèle. | ## 4. Mise à disposition du service L’Assistant IA est mis à disposition des utilisateurs et utilisatrices par leur **administration de rattachement**. L’utilisation de l’Assistant IA est soumise à l'utilisation d'un compte **ProConnect**. L’accès au service est **gratuit** et réservé aux agents des administrations de l'État et des organismes sous tutelle. ## 5. Fonctionnalités Les modèles accessibles via la plateforme sont un sous-ensemble des modèles déployés par le service **Albert API**. Pour les identifier, se référer à la page : Ces modèles sont susceptibles d’évolution en fonction des évaluations de performances et de coût par Albert API. ### Fonctionnalités disponibles L’utilisateur ou l’utilisatrice peut : * **Créer une nouvelle conversation** : démarrer un nouvel échange avec l’Assistant, sans lien avec les discussions précédentes * **Rechercher dans l’historique** : retrouver rapidement une conversation passée ou un sujet précis via la barre de recherche * **Consulter l’historique des échanges** : afficher et reprendre une conversation en cours * **Poser des questions ou soumettre des demandes** : rédiger un message librement dans la zone de saisie principale * **Joindre un fichier** : envoyer un document ou une image pour analyse (via icône trombone ou glisser-déposer) * **Faire une recherche web** : forcer le modèle à s'appuyer sur une recherche internet pour générer sa réponse * **Changer de langue** : sélectionner une autre langue d’affichage via le menu en haut à droite * **Gérer la session** : fermer sa session en toute sécurité via le bouton « Se déconnecter » * **Donner un retour** : partager un avis ou un commentaire via le bouton « Faire un retour » * **Accéder aux paramètres** : personnaliser les préférences d'utilisation des données via le menu paramètres {% hint style="info" %} Les fonctionnalités liées au téléversement de documents peuvent être temporairement limitées en fonction de l'état de développement. {% endhint %} ## 6. Engagements et responsabilités des utilisateurs et utilisatrices ### 6.1 Usages conformes L’Assistant IA est mis à disposition pour permettre aux utilisateurs d’utiliser des modèles de langage dans un environnement sécurisé, dans le cadre de l’accomplissement de leurs missions professionnelles. **L’utilisateur s’engage à :** * Être responsable des données ou contenus qu’il saisit dans l’Assistant IA * Veiller à ne saisir que des messages professionnels appropriés * Recourir à l’Assistant IA lorsque la valeur ajoutée à son travail est pertinente * Éviter un usage superficiel de la plateforme * Se rapprocher de son administration de rattachement pour prendre connaissance de la doctrine d’emploi de l’Assistant IA ### 6.2 Usages interdits L’utilisateur s’engage à ne pas saisir ni générer dans l’Assistant IA des contenus ou informations contraires aux dispositions légales et réglementaires en vigueur. **En particulier, il est interdit de :** ❌ Saisir des **données personnelles non nécessaires** à l'exécution de son travail\ ❌ Utiliser l’Assistant IA pour des **usages non professionnels**\ ❌ Utiliser l’Assistant IA afin de générer une **décision administrative individuelle**\ ❌ Saisir ou générer tout **contenu illicite** ou susceptible d’enfreindre les dispositions légales\ ❌ Fournir à l’interface des **instructions ou recommandations** en ce sens ## 7. Engagements et responsabilités de la DINUM ### 7.1 Sécurité du service La DINUM s’engage à sécuriser l'application en prenant toutes les mesures nécessaires pour garantir la **sécurité et la confidentialité** des informations fournies et générées. **À noter concernant la recherche web :**\ La fonctionnalité « Recherche sur internet » équivaut à une recherche sur un moteur de recherche pour améliorer la réponse. Le contenu précis de la recherche, généré par le modèle de langage, est stocké par le moteur de recherche (service externe). Avant toute fourniture d’informations et de documents, il revient à l'utilisateur d'utiliser les moyens qualifiés par son **autorité de sécurité des systèmes d'information**. ### 7.2 Limites d’utilisation Les sources des informations générées par la plateforme sont réputées fiables. Toutefois, **la DINUM ne garantit pas** que les contenus générés soient exempts de défauts, d’erreurs ou d’omissions. **Il appartient à l’utilisateur de :** * Vérifier l’exactitude des contenus générés * Conserver la décision finale dans l’exploitation des sorties de l’Assistant IA * Utiliser l’Assistant IA comme un **outil d’aide à la recherche et à la rédaction**, et non comme une source générant un produit final ### 7.3 Accès au service La DINUM s’engage à fournir les moyens nécessaires et raisonnables pour assurer un **accès continu** à l'application. **Limites techniques :** * Le nombre de requêtes ou leur fréquence peuvent être limités en fonction des ressources de calcul disponibles * La quantité d’information pouvant être envoyée en une fois est limitée * Les conversations les plus anciennes de l’historique peuvent être supprimées au profit des plus récentes **Maintenance et évolution :** La DINUM se réserve le droit de : * Faire évoluer, modifier ou suspendre le service **sans préavis** pour des raisons de maintenance ou tout autre motif jugé nécessaire * Suspendre ou supprimer un compte utilisateur ayant méconnu les présentes modalités d’utilisation ### 7.4 Open Source et Licences **Code source :** Le code source de la plateforme est libre et disponible sur [GitHub](https://github.com/suitenumerique/conversations) **Licences :** * Les contenus proposés par la DINUM sont sous **Licence Ouverte Etalab 2.0**, à l’exception des logos et représentations iconographiques * Les licences des modèles utilisés sont documentées sur les pages HuggingFace des modèles respectifs, référencées sur [Albert API](https://albert.sites.beta.gouv.fr/solutions/models/) ### 7.5 Évolution des modalités d’utilisation Les présentes modalités d’utilisation peuvent être modifiées ou complétées à tout moment, **sans préavis**, en fonction : * Des modifications apportées au service * De l’évolution de la législation * Ou pour tout autre motif jugé nécessaire Ces modifications s’imposent à l’utilisateur, qui doit se référer régulièrement à cette rubrique pour vérifier la version en vigueur. La DINUM s’efforce d’annoncer les modifications et mises à jour sur l’application. ## 8. Accessibilité La DINUM s'engage à rendre accessibles ses services numériques, conformément à l'**article 47 de la loi n° 2005-102 du 11 février 2005**. ### État de conformité [**assistant.numerique.gouv.fr**](https://assistant.numerique.gouv.fr/) n'est **pas encore en conformité** avec le RGAA 4.1. Le site n'a **pas encore été audité**. **Contact accessibilité :** ### Signalement Si vous rencontrez un défaut d’accessibilité vous empêchant d’accéder à un contenu ou à un service, vous pouvez : 1. **Signaler le problème** à 2. **Contacter le Défenseur des droits** via [ce formulaire](https://formulaire.defenseurdesdroits.fr/) 3. **Envoyer un courrier** (gratuit, sans affranchissement) : ``` Défenseur des droits Libre réponse 71120 75342 Paris CEDEX 07 ``` {% hint style="info" %} Pour toute question concernant ces modalités d’utilisation, contactez votre administration de rattachement ou l’équipe DINUM à : **** {% endhint %} # Capacités et limites Comprenez ce que l'assistant peut faire et les limites inhérentes à son fonctionnement basé sur le langage. L'assistant fonctionne comme un système intelligent basé sur le traitement du langage naturel. Il excelle dans l'analyse, l'explication et la génération de texte, mais fonctionne dans des contraintes fondamentales. ## Ce que l'assistant comprend L'assistant traite l'information **textuelle** : * Il lit et comprend le code * Il explique des concepts techniques * Il génère du texte, du code, ou de la documentation * Il répond à des questions basées sur les données disponibles ## Ce que l'assistant peut faire L'assistant a à sa disposition plusieurs outil. Il peut analyser les documents que vous avez téléverser de 3 manières différentes : * **Résumer** la totalité en suivant les instructions que vous fournissez (en 2 paragraphes, en espagnol...) * **Utiliser la totalité du document** pour vous répondre (si le document fait environ moins de 5 pages de texte) * Sélectionner les **quelques paragraphes** les **plus pertinents** pour s'en inspirer à la génération de votre réponse. {% content-ref url="/pages/byUl4AyFGA218bLAHiP1" %} [Gestion des documents](/assistant-ia/guides-pratiques/documents) {% endcontent-ref %} Il peut également déclencher une ou plusieurs recherches internet si les paramètres le permettent et que le modèle en rédige la demande. Nous déclenchons alors une recherche web, et le modèle se base sur les résultats de celle-ci pour générer votre réponse. {% content-ref url="/pages/UdDR0PV74lycV0aL3IdN" %} [Recherche web](/assistant-ia/guides-pratiques/recherche-web) {% endcontent-ref %} ## Ce que l'assistant ne peut pas faire L'assistant **ne peut pas** : * **Exécuter du code directement** : Il ne peut pas lancer de programmes, de scripts, ou d'outils sur votre machine. Lorsqu'il propose du code, c'est à vous de l'exécuter dans votre environnement. * **Accéder à des ressources externes** : Sans configuration explicite, il ne peut pas se connecter à des bases de données, des API externes, ou des services en ligne en dehors de son contexte autorisé. * **Modifier ou générer des fichiers** : Pour l'instant, l'Assistant ne fait que générer le texte que vous pouvez ensuite insérer dans des fichiers. * **Effectuer des actions physiques** : Il ne peut pas interagir avec le matériel, les périphériques, ou effectuer des opérations système. ## Limites techniques actuelles {% hint style="warning" %} **Capacité documentaire** : Il y a actuellement une limite de **10 documents de 10 Mo chacun par projet**. Cette limite est due au dimensionnement actuel du service et sera amenée à évoluer positivement très rapidement. {% endhint %} ## Pourquoi ces limites ? Ces restrictions existent par **conception de sécurité**, ainsi que d'avancée sur la feuille de route (voir section ci-dessous) : * **Isolation** : L'assistant fonctionne dans un environnement contrôlé qui l'empêche d'affecter directement votre système. * **Transparence** : Vous gardez toujours le contrôle sur ce qui est exécuté ou modifié. * **Prévisibilité** : Le comportement de l'assistant reste dans le domaine de la manipulation de texte et d'information, pas dans celui de l'exécution arbitraire. Quand l'assistant vous propose une solution impliquant du code, il vous guide **étape par étape** et c'est à vous de décider de l'exécuter dans votre environnement local. ## Évolution à venir À terme, l'assistant pourra **exécuter du code dans un environnement sécurisé et isolé** pour réaliser des analyses statistiques, générer des documents, ou effectuer des traitements de données. Ces fonctionnalités seront activées progressivement selon des protocoles de sécurité stricts. Consultez la [feuille de route](/assistant-ia/pour-aller-plus-loin/feuille-de-route) pour connaître les dates prévisionnelles de ces évolutions. {% content-ref url="/pages/XkRugRNJ2eGLFJVn7z23" %} [Feuille de route](/assistant-ia/pour-aller-plus-loin/feuille-de-route) {% endcontent-ref %} # Feuille de route Feuille de route des fonctionnalités de l'Assistant IA ### Fonctionnalités déjà livrées {% stepper %} {% step %} Prise en charge des pièces jointes (formats : pptx, docx, xlsx, pdf, png) {% endstep %} {% step %} Support de la recherche web {% endstep %} {% step %} RAG (Retrieval-Augmented Generation) et résumé de longs documents {% endstep %} {% step %} OCR (reconnaissance optique de caractères) et améliorations UX {% endstep %} {% step %} Projets avec bases documentaires {% endstep %} {% step %} **Mars 2026 :** * Projets avec système prompt * Recherche juridique améliorée {% endstep %} {% step %} **Avril 2026 :** * Homologation DINUM pour les données sensibles au sens de la loi SREN * Bases documentaires intégrées dans les projets {% endstep %} {% endstepper %} ### En développement {% stepper %} {% step %} **Aout - Septembre 2026 :** * **Connexion Docs / Fichiers :** Permettre à votre Assistant d'aller chercher des documents dans les autres produits de la Suite, et de générer des documents dans votre compte Docs. * **Connecteurs MCP** : Grâce à la technologie MCP, intégrer des outils développés par d'autres services, comme DataGouv ou l'ANSSI (Mes questions cyber) dans l'Assistant {% endstep %} {% step %} **Septembre - Octobre 2026** * Génération de documents simples téléchargeables (formats : txt, docx, md) * Intégration des compagnons (exemple : Assistant RH) {% endstep %} {% step %} **Novembre - Décembre 2026** * Analyse statistique rigoureuse et capacité d'exécution de code * Génération de documents avancés (formats : pptx, xlsx, pdf) {% endstep %} {% endstepper %} # Automatisations et API Automatisations et API Pour l'instant, l'assistant ne supporte pas les automatisations. Consultez la [feuille de route](/assistant-ia/pour-aller-plus-loin/feuille-de-route) pour connaître les intégrations futures. Pour un usage programmatique, le service [Albert API](https://ia.numerique.gouv.fr/outils-ia/albert-api/) est disponible. # Hallucinations {% hint style="info" %} En cours de construction {% endhint %} Cette page détaillera précisément ce qu'on appelle une hallucination dans le cadre des outils d'intelligence artificielle, comment les reconnaître et pourquoi il n'est pas possible de les éradiquer totalement de notre outil.