albert-api
Skill29 starsChanged 28 days agoMITView on GitHub
Albert API — API d'inférence et d'IA générative interministérielle de l'État (OpenGateLLM, hébergement SecNumCloud). Compatible OpenAI : chat completions et embeddings. Plus rerank, transcription audio, OCR de PDF et d'images, et un pipeline RAG souverain complet (collections, documents, recherche sémantique/ hybride/lexicale). À utiliser pour appeler Albert, intégrer un LLM souverain dans un produit ou un script de l'administration, faire du RAG sur corpus interne, transcrire de l'audio ou extraire du texte de PDF/images via Albert, ou gérer ses clés et quotas Albert. Déclencheurs : Albert, Albert API, OpenGateLLM, LLM de l'État, IA générative souveraine, base_url Albert.
- Reads credentials
In this repository12 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- anssi-guidesSkill
- datagouv-apisSkill
- presentation-docsSkill
- rag-indexSkill
- rag-parseSkill
- rag-searchSkill
- lasuite-ui-kitSkill
- react-dsfrSkill
- rgaaSkill
- securite-developpementSkill
- usage-ia-agents-etatSkill
The file
Files
Albert API — Référence consolidée
API d'inférence de l'État français, opérée par le département IAE de la DINUM (commun numérique OpenGateLLM). Partiellement compatible OpenAI : pour chat/completions et embeddings, réutiliser le SDK openai (ou tout client OpenAI) en changeant simplement base_url et la clé. Les autres surfaces — rerank, RAG, audio, OCR — n'existent pas dans le SDK OpenAI et s'appellent en HTTP direct.
Base URL : https://albert.api.etalab.gouv.fr
Spec OpenAPI (fait foi) : https://albert.api.etalab.gouv.fr/openapi.json
Doc humaine : https://doc.incubateur.net/alliance/albert-api
Comment utiliser cette skill
- Consommation d'abord. L'usage courant = appeler les modèles (chat, embeddings) et le RAG. Les écritures (créer collection, uploader documents, gérer des clés) ne se font que sur intention explicite de l'utilisateur.
- Compatibilité OpenAI, mais partielle. Pointer un client OpenAI sur
https://albert.api.etalab.gouv.fr/v1évite de réécrire du code pourchat/completionsetembeddings, dont les schémas de requête/réponse suivent OpenAI (Albert ajoute des paramètres :search,search_args). Le SDK s'arrête là :rerank,audio/transcriptions,ocret le RAG n'ont aucune méthode côté SDK — ne jamais générer declient.rerank(...),client.ocr(...)ouclient.search(...), ces appels échouent avant même de partir. Les faire en HTTP direct (requests,httpx,curl). - Ne jamais logger ni afficher le token. Le Bearer token est un secret. Ne pas l'écho dans les réponses, les logs, les exemples copiés. Le lire depuis une variable d'environnement (
ALBERT_API_KEY). - L'OpenAPI fait autorité. En cas de divergence entre ce fichier et la spec récupérée en live, suivre la spec. Son champ
info.versionchange sans préavis (v0.4.7, puislatest, puis0.6.0post1à ce jour) : c'est le contenu qui fait foi, pas un semver —bin/check_drift.pydétecte les écarts d'endpoints et d'enums. - Ne pas inventer d'ID de modèle, et ne jamais coder un alias. Lister les modèles via
GET /v1/modelset utiliser le champid, jamais une valeur du tableaualiases(cf. § Modèles).
Authentification & accès
- Header :
Authorization: Bearer <token>sur tous les endpoints/v1/*. - Public : réservé aux agents de la fonction publique. Demande d'accès en ligne (voir la doc humaine). L'accès distingue un mode expérimentation (quotas réduits) d'un mode production (sur dossier).
- Connaître ses droits :
GET /v1/merenvoie l'identité, les quotas et limites du compte.GET /v1/usagerenvoie la consommation. - Gérer ses clés :
GET/POST /v1/keys,DELETE /v1/keys/{key_id}. Créer une clé dédiée par usage/produit plutôt que réutiliser la clé personnelle.
⚠️ Créer une clé : piège vérifié en live (2026-10-16) sur la route canonique
POST /v1/keys.
POST /v1/keys(corps{"name": "...", "expires": <ts>}) renvoie 201 avec une réponse dont le champ exploitable porte le nomvalue(champs renvoyés :created,expires,id,name,object,user_id,value). La spec 0.8.0 (KeyResponse) déclare ce champvaluecorrectement — contrairement au constat du 08/09 où elle annonçaittoken/key. Lireresp["token"]lève toujours unKeyError: c'estresp["value"]qu'il faut utiliser.- Le champ
valued'un élément du listingGET /v1/keysest masqué : tout appel avec renvoie401 {"detail":"Invalid API key."}(vérifié surGET /v1/models, code HTTP 200 avec la clé fraîchement créée, 401 avec celle du listing). La valeur exploitable n'existe qu'à la création — pas récupérable ensuite. La perdre = clé orpheline, à supprimer et recréer.Corollaire : pas de renommage possible.
/v1/keys/{key_id}n'expose quegetetdelete, il n'y a pas dePATCH(confirmé dans la spec 0.8.0) — renommer = créer + réinstaller la nouvelle valeur partout + supprimer l'ancienne.Diagnostiquer une clé suspecte avec
GET /v1/modelsouGET /v1/me: pour une clé invalide ("invalid-test-key", test 2026-10-16) les deux renvoient 401 — pas de distinction/v1/modelsvs/v1/meà exploiter ; un403signe alors un quota/compte plutôt qu'une clé invalide.
- Erreurs :
401= token absent/invalide ;403= droits ou quota insuffisants ;404= ressource/ID inexistant ;429= rate limit. Sur 401/403, distinguer token manquant de quota dépassé avant de réessayer.
Choisir un endpoint (intention → surface)
| Objectif | Endpoint |
| Générer du texte, chat, RAG-in-one-call, tool calling | POST /v1/chat/completions |
| Vectoriser du texte (embeddings) | POST /v1/embeddings |
| Reclasser des documents par pertinence | POST /v1/rerank |
| Transcrire de l'audio | POST /v1/audio/transcriptions |
| Extraire le texte d'un PDF/image (OCR) | POST /v1/ocr |
| Indexer un corpus puis chercher dedans (RAG) | /v1/collections → /v1/documents → POST /v1/search |
| Lister les modèles et leurs types | GET /v1/models |
| Quotas, usage, clés | /v1/me, /v1/usage, /v1/keys |
| Santé du service | GET /health, GET /health/models |
Modèles
Lister en live : GET /v1/models (champ data[]). GET /v1/models/{model} pour le détail d'un modèle.
id ou alias ? Toujours l'id
Chaque entrée du catalogue expose deux façons de désigner le modèle, et elles n'ont pas le même statut. La spec OpenAPI les décrit ainsi :
| Champ | Description dans la spec | Statut |
id | « The model identifier, which can be referenced in the API endpoints » | Identifiant contractuel, c'est celui à coder |
aliases | « Aliases of the model. It will be used to identify the model by users » | Commodité d'affichage, non contractuelle |
⚠️ Coder un alias est un bug différé. Les alias ont déjà churné sans préavis : en juillet 2026,
deepseek-ai/DeepSeek-V4-Flasha été re-versionné endeepseek-ai/DeepSeek-V4-Flash-0731etQwen/Qwen3.6-27Ba disparu du catalogue. Toutes les intégrations qui les avaient codés en dur sont tombées en404 {"detail":"Model not found."}. Lesidcanoniques, eux, n'ont pas bougé.
Les id canoniques sont en minuscules avec des tirets (deepseek-v4-flash), alors que les alias reprennent souvent la nomenclature HuggingFace (deepseek-ai/DeepSeek-V4-Flash-0731). Certains modèles portent aussi un alias de rôle stable (openweight-code, openweight-small…), pratique mais réservé aux modèles ouverts : les modèles propriétaires n'en ont pas, donc ce schéma ne peut pas servir de politique uniforme.
# Le bon réflexe : récupérer les id, filtrés par type
curl -s https://albert.api.etalab.gouv.fr/v1/models \
-H "Authorization: Bearer $ALBERT_API_KEY" \
| jq -r '.data[] | select(.type=="text-generation") | .id'Instantané du catalogue
Relevé le 2026-08-26, revérifié le 2026-09-03 (conforme au catalogue live), à revérifier via GET /v1/models : le catalogue évolue et cette table sera périmée.
type | Usage | id canoniques |
text-generation | Chat / complétion | deepseek-v4-flash, mistral-medium-2508, qwen3-coder-30b-A3b-instruct, openai/gpt-oss-120b |
image-text-to-text | Vision (image + texte) | mistral-medium-3-5-128b, gemma-4-31b-it, mistral-small-3-2-24b-instruct-2506, ministral-3-8b-instruct-2512, lightonocr-2-1b |
text-embeddings-inference | Embeddings | bge-m3, qwen3-vl-embedding-8b, mistral-embed-2312 |
text-classification | Rerank | bge-reranker-v2-m3 |
automatic-speech-recognition | Transcription audio | whisper-large-v3 |
image-to-text | OCR | mistral-ocr-2512 |
Vérifier qu'un modèle répond avant de s'appuyer dessus
GET /health/models (authentifié) renvoie un statut par modèle :
curl -s https://albert.api.etalab.gouv.fr/health/models \
-H "Authorization: Bearer $ALBERT_API_KEY" | jq '.data[] | select(.status!="green")'Un modèle présent dans GET /v1/models mais red dans /health/models répond 502 Bad Gateway, pas 404. Distinguer les deux évite de chercher une erreur de nommage là où il n'y a qu'une panne amont : 404 = identifiant inconnu (vérifier l'id), 502 = modèle indisponible (attendre ou basculer).
Endpoints
Inférence — compatibles OpenAI
| Méthode | Chemin | Notes |
| POST | /v1/chat/completions | messages*, model* ; options : temperature, top_p, max_completion_tokens, stream, stop, n, seed, response_format, tools, tool_choice. Spécifique Albert : search: true + search_args pour activer le RAG dans l'appel. |
| POST | /v1/embeddings | input* (string ou array), model* ; dimensions, encoding_format (float|base64). |
| GET | /v1/models · /v1/models/{model} | Catalogue des modèles. |
Reranking — HTTP direct (hors SDK OpenAI)
| Méthode | Chemin | Corps |
| POST | /v1/rerank | query*, documents* (array de strings), model*, top_n. Renvoie results : une liste de {index, relevance_score} triée par pertinence — des indices dans documents, pas les textes ; c'est à l'appelant de re-mapper. |
Le SDK openai n'expose pas de ressource rerank : cet endpoint s'appelle en HTTP direct (cf. § Exemples).
Audio & documents
| Méthode | Chemin | Corps | Notes |
| POST | /v1/audio/transcriptions | multipart : file*, model* ; language, prompt, response_format (json|text|verbose_json|diarized_json|srt|vtt), temperature | diarized_json = transcription avec séparation des locuteurs. |
| POST | /v1/ocr | json : document* (objet, pas une URL nue : {"type":"document_url","document_url":"…"} pour un PDF, ou {"type":"image_url","image_url":"…"} pour une image), model, pages, image_limit, include_image_base64 | OCR d'un PDF/image accessible par URL. |
RAG — collections, documents, recherche
| Méthode | Chemin | Corps / notes |
| GET/POST | /v1/collections | POST : name*, description, visibility (private|public). |
| GET/PATCH/DELETE | /v1/collections/{collection_id} | Lire / modifier / supprimer une collection. |
| GET/POST | /v1/documents | POST multipart : file (le fichier à indexer ; ou name pour un document sans fichier), collection_id (collection cible) ; chunking paramétrable (chunk_size, chunk_overlap, separators, preset_separators, disable_chunking). |
| GET/DELETE | /v1/documents/{document_id} | Métadonnées / suppression d'un document. |
| GET/POST | /v1/documents/{document_id}/chunks | Lister / ajouter des chunks. |
| GET/DELETE | /v1/documents/{document_id}/chunks/{chunk_id} | Lire / supprimer un chunk. |
| POST | /v1/search | query, collection_ids, document_ids, method (hybrid|semantic|lexical), limit, score_threshold, metadata_filters. Renvoie les chunks les plus pertinents. |
Compte & supervision
| Méthode | Chemin |
| GET/PATCH | /v1/me |
| GET | /v1/usage |
| GET/POST | /v1/keys |
| GET/DELETE | /v1/keys/{key_id} |
| GET/PATCH · GET · DELETE | /v1/me/info · /v1/me/usage · /v1/me/keys · /v1/me/keys/{key_id} — dépréciées, à ne plus utiliser |
| GET | /health · /health/models · /metrics |
Workflow RAG (la valeur cœur d'Albert)
Deux approches :
A. RAG explicite (contrôle total) :
- Créer une collection —
POST /v1/collections. - Uploader les documents dedans —
POST /v1/documents(chunking automatique). - Chercher les passages pertinents —
POST /v1/search(method: hybridpar défaut conseillé). - Injecter les chunks récupérés dans le
messagesd'unPOST /v1/chat/completions.
B. RAG intégré (une seule requête) : passer search: true + search_args (collections, méthode, limite) directement à POST /v1/chat/completions — Albert fait la recherche et la génération en un appel.
Exemples
Lire
ALBERT_API_KEYdepuis l'environnement ; ne jamais coller le token en clair. Vérifier lesidde modèle viaGET /v1/models(le champid, pas un alias).
Chat (SDK OpenAI)
from openai import OpenAI
import os
client = OpenAI(
base_url="https://albert.api.etalab.gouv.fr/v1",
api_key=os.environ["ALBERT_API_KEY"],
)
resp = client.chat.completions.create(
model="mistral-medium-2508", # un id de type text-generation (cf. GET /v1/models)
messages=[{"role": "user", "content": "Explique le RGPD en une phrase."}],
temperature=0.2,
)
print(resp.choices[0].message.content)Lister les modèles / chat (curl)
curl -s https://albert.api.etalab.gouv.fr/v1/models \
-H "Authorization: Bearer $ALBERT_API_KEY" | jq '.data[] | {id, type, aliases}'
curl -s https://albert.api.etalab.gouv.fr/v1/chat/completions \
-H "Authorization: Bearer $ALBERT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"mistral-medium-2508","messages":[{"role":"user","content":"Bonjour"}]}'Embeddings
emb = client.embeddings.create(model="bge-m3", input=["texte à vectoriser"])
vector = emb.data[0].embeddingReranking (requests — pas de méthode SDK)
import os, requests
docs = ["texte du chunk 1", "texte du chunk 2", "texte du chunk 3"]
r = requests.post(
"https://albert.api.etalab.gouv.fr/v1/rerank",
headers={"Authorization": f"Bearer {os.environ['ALBERT_API_KEY']}"},
json={
"model": "bge-reranker-v2-m3", # un id de type text-classification
"query": "Quelles sont les obligations de publication ?",
"documents": docs,
"top_n": 2,
},
).json()
# `results` contient des index dans `docs`, pas les textes : re-mapper soi-même
top = [(docs[x["index"]], x["relevance_score"]) for x in r["results"]]Transcription audio
curl -s https://albert.api.etalab.gouv.fr/v1/audio/transcriptions \
-H "Authorization: Bearer $ALBERT_API_KEY" \
-F "file=@reunion.mp3" \
-F "model=whisper-large-v3" \
-F "response_format=text"RAG explicite (requests)
import os, requests
BASE = "https://albert.api.etalab.gouv.fr/v1"
H = {"Authorization": f"Bearer {os.environ['ALBERT_API_KEY']}"}
# 1) collection
col = requests.post(f"{BASE}/collections", headers=H,
json={"name": "ma-doc", "visibility": "private"}).json()
# 2) document
with open("guide.pdf", "rb") as f:
requests.post(f"{BASE}/documents", headers=H,
data={"collection_id": col["id"]},
files={"file": f})
# 3) recherche
hits = requests.post(f"{BASE}/search", headers=H, json={
"query": "Quelles sont les obligations de publication ?",
"collection_ids": [col["id"]],
"method": "hybrid",
"limit": 5,
}).json()
# 4) injecter les chunks dans un chat completion (cf. exemple chat)Albert en ligne de commande (CLI)
Albert n'a pas de CLI dédiée — et n'en a pas besoin pour l'usage courant : étant compatible OpenAI, n'importe quel client CLI OpenAI fonctionne en pointant la base URL sur Albert et la clé sur ALBERT_API_KEY. Deux options éprouvées :
llm (Simon Willison) — recommandé pour le terminal
Enregistrer Albert comme modèle OpenAI-compatible dans ~/.config/io.datasette.llm/extra-openai-models.yaml :
- model_id: albert-mistral
model_name: mistral-medium-2508 # un id renvoyé par GET /v1/models
api_base: https://albert.api.etalab.gouv.fr/v1
api_key_name: albertPuis :
llm keys set albert # colle le token (stocké hors du shell, jamais en clair dans l'historique)
llm -m albert-mistral "Résume le RGPD en une phrase."
cat rapport.txt | llm -m albert-mistral "Fais-en une synthèse en 3 points."CLI openai officielle
export OPENAI_BASE_URL="https://albert.api.etalab.gouv.fr/v1"
export OPENAI_API_KEY="$ALBERT_API_KEY" # déjà exporté côté env, pas en dur
openai api models.list
openai api chat.completions.create -m mistral-medium-2508 -g user "Bonjour"Pour les capacités propres à Albert (RAG, OCR, gestion des collections/clés), il n'y a pas de sous-commande CLI standard : utiliser
curl(cf. exemples ci-dessus) ou le SDK. Ne jamais passer le token en argument de commande (visible danspset l'historique) : le lire depuis l'environnement ou un gestionnaire de clés (llm keys).
Garanties & doctrine
- Hébergement SecNumCloud (Outscale) : qualification ANSSI.
- Pas de rétention des conversations, pas d'envoi de données sur Internet ouvert.
- Adapté aux usages avec données internes de l'administration, dans le respect du cadre RGPD applicable.
Maintenance de cette skill
La source d'autorité est l'OpenAPI live (/openapi.json). Pour vérifier que cette skill n'a pas dérivé de la spec :
python3 bin/check_drift.py # compare la spec live au snapshot committé
python3 bin/check_drift.py --update # régénère le snapshot après mise à jour de SKILL.mdLe script (sans dépendance) compare version, endpoints et enums au fichier openapi.snapshot.json. En cas d'écart il sort en code 1 et liste les différences — signal qu'il faut relire et corriger ce fichier. À lancer périodiquement ou avant toute revue ; idéalement adossé à une GitHub Action qui ouvre une issue quand la version d'Albert bouge.
Références
- Doc Albert API : https://doc.incubateur.net/alliance/albert-api
- OpenAPI (autoritatif) : https://albert.api.etalab.gouv.fr/openapi.json
- OpenGateLLM (commun numérique sous-jacent) : notebooks et tutoriels RAG/OCR.
- Assistant IA (interface chat grand public adossée à Albert) : https://assistant.numerique.gouv.fr/
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

