agentleFS
etalab-iaetalab-ia/skills/skills/albert-api/SKILL.md

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

The file

Files
SKILL.md

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 pour chat/completions et embeddings, 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, ocr et le RAG n'ont aucune méthode côté SDK — ne jamais générer de client.rerank(...), client.ocr(...) ou client.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.version change sans préavis (v0.4.7, puis latest, puis 0.6.0post1 à ce jour) : c'est le contenu qui fait foi, pas un semver — bin/check_drift.py dé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/models et utiliser le champ id, jamais une valeur du tableau aliases (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/me renvoie l'identité, les quotas et limites du compte. GET /v1/usage renvoie 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.

  1. POST /v1/keys (corps {"name": "...", "expires": <ts>}) renvoie 201 avec une réponse dont le champ exploitable porte le nom value (champs renvoyés : created, expires, id, name, object, user_id, value). La spec 0.8.0 (KeyResponse) déclare ce champ value correctement — contrairement au constat du 08/09 où elle annonçait token/key. Lire resp["token"] lève toujours un KeyError : c'est resp["value"] qu'il faut utiliser.
  2. Le champ value d'un élément du listing GET /v1/keys est masqué : tout appel avec renvoie 401 {"detail":"Invalid API key."} (vérifié sur GET /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 que get et delete, il n'y a pas de PATCH (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/models ou GET /v1/me : pour une clé invalide ("invalid-test-key", test 2026-10-16) les deux renvoient 401 — pas de distinction /v1/models vs /v1/me à exploiter ; un 403 signe 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)

ObjectifEndpoint
Générer du texte, chat, RAG-in-one-call, tool callingPOST /v1/chat/completions
Vectoriser du texte (embeddings)POST /v1/embeddings
Reclasser des documents par pertinencePOST /v1/rerank
Transcrire de l'audioPOST /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 typesGET /v1/models
Quotas, usage, clés/v1/me, /v1/usage, /v1/keys
Santé du serviceGET /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 :

ChampDescription dans la specStatut
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-Flash a été re-versionné en deepseek-ai/DeepSeek-V4-Flash-0731 et Qwen/Qwen3.6-27B a disparu du catalogue. Toutes les intégrations qui les avaient codés en dur sont tombées en 404 {"detail":"Model not found."}. Les id canoniques, 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.

typeUsageid canoniques
text-generationChat / complétiondeepseek-v4-flash, mistral-medium-2508, qwen3-coder-30b-A3b-instruct, openai/gpt-oss-120b
image-text-to-textVision (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-inferenceEmbeddingsbge-m3, qwen3-vl-embedding-8b, mistral-embed-2312
text-classificationRerankbge-reranker-v2-m3
automatic-speech-recognitionTranscription audiowhisper-large-v3
image-to-textOCRmistral-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éthodeCheminNotes
POST/v1/chat/completionsmessages*, 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/embeddingsinput* (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éthodeCheminCorps
POST/v1/rerankquery*, 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éthodeCheminCorpsNotes
POST/v1/audio/transcriptionsmultipart : file*, model* ; language, prompt, response_format (json|text|verbose_json|diarized_json|srt|vtt), temperaturediarized_json = transcription avec séparation des locuteurs.
POST/v1/ocrjson : 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_base64OCR d'un PDF/image accessible par URL.

RAG — collections, documents, recherche

MéthodeCheminCorps / notes
GET/POST/v1/collectionsPOST : name*, description, visibility (private|public).
GET/PATCH/DELETE/v1/collections/{collection_id}Lire / modifier / supprimer une collection.
GET/POST/v1/documentsPOST 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}/chunksLister / ajouter des chunks.
GET/DELETE/v1/documents/{document_id}/chunks/{chunk_id}Lire / supprimer un chunk.
POST/v1/searchquery, collection_ids, document_ids, method (hybrid|semantic|lexical), limit, score_threshold, metadata_filters. Renvoie les chunks les plus pertinents.

Compte & supervision

MéthodeChemin
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) :

  1. Créer une collection — POST /v1/collections.
  2. Uploader les documents dedans — POST /v1/documents (chunking automatique).
  3. Chercher les passages pertinents — POST /v1/search (method: hybrid par défaut conseillé).
  4. Injecter les chunks récupérés dans le messages d'un POST /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_KEY depuis l'environnement ; ne jamais coller le token en clair. Vérifier les id de modèle via GET /v1/models (le champ id, 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].embedding

Reranking (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: albert

Puis :

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 dans ps et 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.md

Le 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.