Passerelle LLM API auto-hébergée : architecture et opérations

Une passerelle API LLM auto-hébergée est un logiciel que vous exécutez dans votre propre réseau ou compte cloud. Elle accepte les requêtes compatibles OpenAI, authentifie les appelants, route le trafic vers un ou plusieurs fournisseurs de modèles en amont et enregistre l'usage pour l'exploitation et le contrôle des coûts. Contrairement à un simple reverse proxy, elle constitue un plan de contrôle : clés, alias de modèles, identifiants de canaux, quotas et historique des requêtes se trouvent au plus près du chemin de requête. Cet article explique quand l'auto-hébergement se justifie, quelle architecture attendre d'une passerelle Go comme celle de ce dépôt et comment l'exploiter sans transformer l'accès aux modèles en boîte noire sans responsable.

Si vous hésitez encore entre un simple relais et un plan de contrôle, lisez d'abord proxy LLM ou passerelle IA. Cette page suppose que vous voulez déjà assumer les responsabilités d'une passerelle et que vous avez besoin d'une base déployable.

Quand l'auto-hébergement est le bon défaut

Auto-hébergez une passerelle si au moins deux de ces conditions sont remplies :

• les clés API des fournisseurs ne doivent pas être distribuées à chaque environnement applicatif
• plusieurs produits ou équipes partagent l'accès aux modèles avec des budgets différents
• vous avez besoin de journaux par requête dans votre propre périmètre de conservation
• les règles de cheminement des données ou d'achat favorisent une infrastructure que vous exploitez
• vous voulez un routage multi-fournisseurs sans réécrire les clients
• les contraintes d'une passerelle SaaS — résidence des données, sortie réseau, contrôle des changements — ne conviennent pas

L'auto-hébergement est un mauvais choix par défaut lorsqu'un seul prototype utilise une clé, un modèle et n'a aucune exigence d'audit. Dans ce cas, appelez directement le fournisseur ou utilisez un proxy léger jusqu'à l'apparition de besoins de plan de contrôle.

Architecture de référence

Clients (apps, agents, eval jobs)
        |
        |  HTTPS + Bearer gateway key
        v
 Self-hosted AI gateway
   - OpenAI-compatible API (/v1/chat/completions, /v1/responses, ...)
   - Admin API for users, tokens, channels
   - Usage logs, dashboard, pricing context
        |
        +--> Channel: OpenAI
        +--> Channel: Anthropic / Claude (native Messages adaptation)
        +--> Channel: Gemini
        +--> Channel: Azure / Bedrock / others
        |
        v
 Your datastore (SQLite / MySQL / PostgreSQL)
 optional Redis for cache and rate limiting

Les clients continuent d'utiliser le SDK OpenAI ou des requêtes HTTP brutes. La diversité des services en amont relève de la configuration, pas d'un nouveau SDK par fournisseur. C'est la même proposition de valeur qu'une passerelle API compatible OpenAI, avec l'exigence supplémentaire que vous assumez la disponibilité et les sauvegardes.

Ce qu'inclut typiquement une passerelle en forme de ce dépôt

Ce projet est une passerelle Go auto-hébergeable et un système de gestion des actifs IA. Les capacités visibles dans le dépôt qui comptent pour la planification sont les suivantes :

• endpoints de relais compatibles OpenAI pour le chat et les surfaces associées
• configuration de canaux multi-fournisseurs
• gestion des utilisateurs et des tokens pour un accès à portée limitée
• journaux d'usage et tableaux de bord d'exploitation
• interface d'administration web intégrée au service
• SQLite pour les déploiements simples ; MySQL ou PostgreSQL pour une production multi-utilisateurs durable
• chemins de déploiement Docker utilisant l'image publiée calciumion/new-api

N'inventez pas de certifications de conformité ni de garanties de niveau de service non déclarées. Validez précisément les fonctionnalités nécessaires dans l'interface et l'API de la version en cours d'exécution avant de les promettre aux parties prenantes.

Chemin Docker minimal vérifié

Le dépôt fournit un véritable fichier docker-compose.yml qui exécute la passerelle avec PostgreSQL et Redis. C'est le point de départ recommandé pour une préproduction multi-utilisateurs. Chemin rapide indiqué dans le README du projet :

docker pull calciumion/new-api:latest
# from a checkout that includes docker-compose.yml
docker compose up -d
# gateway listens on http://localhost:3000 by default

Structure du service principal, abrégée à partir du fichier Compose du dépôt ; conservez le fichier complet pour les services Redis/Postgres, les contrôles de santé et les commentaires :

services:
  new-api:
    image: calciumion/new-api:latest
    container_name: new-api
    restart: always
    command: --log-dir /app/logs
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
      - ./logs:/app/logs
    environment:
      # Change passwords before any shared or production use.
      - SQL_DSN=postgresql://root:123456@postgres:5432/new-api
      - REDIS_CONN_STRING=redis://:123456@redis:6379
      - TZ=Asia/Shanghai
      - ERROR_LOG_ENABLED=true
      - BATCH_UPDATE_ENABLED=true
      - NODE_NAME=new-api-node-1
    depends_on:
      - redis
      - postgres

Ces notes d'exploitation maintiennent l'exemple réaliste :

• Les mots de passe Compose par défaut (123456) servent uniquement au démarrage local. Remplacez-les avant tout environnement partagé.
• Dans les environnements réglementés, préférez un digest d'image épinglé au tag flottant :latest utilisé dans la documentation.
• Pour une expérience SQLite sur un seul nœud, le README documente aussi l'exécution du conteneur avec un volume /data monté et sans SQL_DSN. Considérez-la comme une option à faible empreinte, pas comme une production à plusieurs processus d'écriture.
• Terminez TLS à l'entrée — nginx, Caddy, équilibreur de charge cloud ou Traefik. N'exposez pas les chemins de l'interface d'administration à Internet sans contrôle d'accès supplémentaire.
• Après la première connexion, placez les clés API des fournisseurs dans la configuration des canaux ou dans un gestionnaire de secrets, jamais dans git.

Si vous ne pouvez pas utiliser Docker Compose tel quel — registre isolé ou orchestration personnalisée — considérez cet extrait comme une base vérifiée à transposer, pas comme un pseudo-code facultatif. Le nom de l'image, le port, le volume et les variables SQL_DSN ci-dessus correspondent à la documentation de déploiement publiée dans ce dépôt.

Checklist de configuration de la première semaine

1. Identité et clés

• créez des administrateurs avec une authentification forte
• émettez un token par service avec la portée de modèles minimale
• séparez les clés de préproduction et de production
• documentez le responsable de la rotation

2. Canaux

Dans la configuration des canaux de l'interface d'administration :

• créez un canal par périmètre d'identifiants en amont
• indiquez explicitement les URL de base pour Azure ou les endpoints régionaux
• exécutez un contrôle de santé ou un test manuel après chaque changement d'identifiants
• ne partagez jamais une clé amont unique et sans restriction entre des locataires non fiables

3. Catalogue et contexte de prix

• publiez des alias de modèles stables (claude-sonnet, gemini-flash, gpt-...) dont dépendent les applications
• associez les alias aux identifiants amont actuels, par exemple aux modèles de classe Claude Sonnet 5 / Opus 4.8 et Gemini 3.5 Flash indiqués par les fournisseurs au moment de la bascule
• révisez le contexte tarifaire lorsque les alias par défaut changent

4. Observabilité

• activez les journaux d'usage pour les routes facturables
• confirmez les durées de conservation et les chemins d'export
• alertez sur le taux d'erreur et la vitesse de dépense, pas seulement sur le CPU

5. Sauvegardes

• automatisez les sauvegardes de base de données — exports PostgreSQL/MySQL ou instantanés de volume
• testez une restauration sur un hôte vierge avant le premier incident réel
• conservez les clés de chiffrement des sauvegardes hors du conteneur de la passerelle

Modèle de sécurité pour un plan de contrôle auto-hébergé

Menaces à prendre en compte

• clés de passerelle volées pouvant épuiser le budget fournisseur
• exposition de l'interface d'administration sur Internet
• journaux de prompts et d'outils contenant des secrets clients
• URL de base de canal propices au SSRF si les opérateurs peuvent pointer les canaux vers des endpoints internes de métadonnées
• fixation de session entre plusieurs nœuds si SESSION_SECRET conserve sa valeur par défaut dans un cluster

Mesures réellement utiles

• TLS en périphérie et accès d'administration privé — VPN, SSO ou listes d'adresses IP autorisées
• une clé unique par application et des listes de modèles autorisés pour les clés de traitement par lots
• secrets fournisseurs uniquement sur la passerelle
• quotas sur toute clé pouvant déclencher des outils ou de longs contextes
• règles de masquage pour les exports de journaux d'usage
• SESSION_SECRET défini pour les déploiements multi-nœuds — consultez les commentaires Compose dans le dépôt

Consultez le Top 10 OWASP pour les applications LLM lorsque des agents peuvent appeler automatiquement des outils. L'auto-hébergement ne supprime pas le risque d'autonomie excessive ; il déplace seulement l'endroit où vous appliquez les contrôles.

Politique de routage comme configuration

Écrivez la politique de routage sous forme de configuration :

1. alias de modèle par défaut pour chaque produit
2. alias de secours pour les erreurs transitoires en amont
3. alias épinglé pour les flux réglementés ou sensibles aux évaluations
4. refus explicite des modèles auxquels une clé ne doit jamais accéder

Associez le routage à une stratégie de bascule pour API LLM afin de ne pas relancer naïvement les échecs en cours de flux. Pour les agents à outils, gardez des schémas portables comme dans les appels d'outils portables entre fournisseurs.

Capacité, bases de données et Redis

Empreinte	Base	Notes
Solo / petite équipe	SQLite	Simple, monter un volume persistant
Production multi-équipe	MySQL ≥ 5.7.8 ou PostgreSQL ≥ 9.6	Meilleure concurrence et outillage ops
Chemins chauds rate-limit/cache	Redis optionnel	Utiliser quand les limites process-local ne suffisent pas

Dimensionnez le CPU et la mémoire en fonction des flux simultanés, pas de l'utilisation de l'interface d'administration au repos. Les réponses diffusées en continu maintiennent les connexions ouvertes ; les tests de charge doivent inclure du trafic de type SSE si vos clients utilisent le streaming.

Mises à niveau et gestion du changement

1. Lisez les notes de version pour les changements liés aux canaux et à la facturation.
2. Déployez en préproduction avec une configuration de canaux proche de la production.
3. Exécutez des tests curl pour /v1/chat/completions et toute utilisation de /v1/responses.
4. Vérifiez l'enregistrement des journaux et le comportement du portefeuille et des quotas avec une clé canari.
5. Déployez en conservant une image précédente connue pour pouvoir revenir en arrière.
6. Après la mise à niveau, revérifiez les alias de modèles par rapport aux renommages en amont.

Ne combinez jamais migrations de base de données, rotation des identifiants fournisseurs et changements de politique de routage dans la même fenêtre sans surveillance.

Tests de fumée après chaque déploiement

curl -sS https://gateway.example.com/v1/models \
  -H "Authorization: Bearer $GATEWAY_API_KEY" | head

curl -sS https://gateway.example.com/v1/chat/completions \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "ping"}],
    "max_tokens": 16
  }'

Ajoutez un alias Claude — par exemple claude-sonnet vers l'identifiant Claude actuel — et un alias Gemini — gemini-flash vers gemini-3.5-flash ou son successeur — si ces canaux sont concernés. Confirmez la présence d'entrées dans les journaux d'usage avant de déclarer le déploiement opérationnel.

Contrôle des coûts sans abandonner l'auto-hébergement

Auto-hébergé ne signifie pas illimité. Configurez :

• des quotas par clé et par groupe
• des listes de modèles autorisés qui bloquent les modèles phares pour les clés de traitement par lots
• des alertes sur la vitesse de dépense à partir des exports de journaux ou des contrôles du tableau de bord
• des tâches d'évaluation utilisant par défaut des modèles moins coûteux

Revoyez les informations publiques de tarification lorsque les alias par défaut changent. Une passerelle auto-hébergée incapable de répondre aux questions de coût devient une responsabilité partagée.

Quand choisir plutôt un hébergement managé

Restez en mode managé ou hybride lorsque :

• vous n'avez pas la capacité d'astreinte nécessaire pour une dépendance de niveau 0
• vous ne pouvez pas respecter les obligations de sauvegarde et de restauration
• les achats préfèrent un plan de contrôle exploité par un fournisseur
• votre équipe n'a besoin que d'un relais de secret vers un seul fournisseur

Dans les deux cas, vous pouvez conserver des clients applicatifs compatibles OpenAI. Le mode d'hébergement ne doit pas imposer une réécriture des clients.

Sources officielles et du projet

• Section de déploiement du README du projet (docker pull calciumion/new-api:latest, docker-compose.yml)
• OWASP Top 10 for LLM Applications
• Référence de l'API OpenAI
• Documentation Docker

Dernière vérification : 2026-07-15. Validez les tags d'image, les variables d'environnement et les chemins de l'interface par rapport à la version réellement déployée.

Questions fréquentes

Une passerelle LLM auto-hébergée est-elle la même chose que d'héberger les modèles soi-même ?

Non. La plupart des passerelles auto-hébergées appellent encore des API de fournisseurs hébergées. Vous hébergez le plan de contrôle — authentification, routage et journaux — pas nécessairement les poids. L'auto-hébergement de modèles à poids ouverts nécessite une pile GPU supplémentaire.

Puis-je commencer sur SQLite et passer à PostgreSQL plus tard ?

Oui, pour de nombreux déploiements, mais planifiez la migration au lieu de découvrir une contention de verrous pendant un incident. Utilisez SQLite pour les petites installations et migrez lorsque les écritures simultanées et les outils de sauvegarde l'exigent.

Quelle est la configuration sécurisée minimale viable ?

TLS en périphérie, accès d'administration privé, clés uniques par application, secrets fournisseurs uniquement sur la passerelle, journaux d'usage activés et quotas pour toute clé pouvant déclencher des outils ou de longs contextes.

Comment éviter de devenir le point de défaillance unique ?

Exécutez au moins deux instances de l'application derrière un équilibreur de charge lorsque la disponibilité compte, utilisez une base de données externe, testez les restaurations et documentez la bascule des canaux. La passerelle doit réduire le rayon d'impact des interruptions fournisseurs, pas en créer un pire.

Quel endpoint les nouveaux clients doivent-ils utiliser ?

Préférez la racine /v1 compatible OpenAI de la passerelle avec /v1/chat/completions pour une large compatibilité client. Adoptez /v1/responses uniquement lorsque votre produit dépend volontairement de cette surface et que votre version de passerelle prend en charge les flux nécessaires.

Bascule en préproduction

Déployez une passerelle de préproduction avec le fichier Compose du dépôt — ou l'image et le SQL_DSN équivalents —, émettez une clé à portée limitée pour un seul service non critique, puis vérifiez les chat completions, les journaux d'usage et la restauration des sauvegardes avant d'intégrer un second fournisseur ou du trafic de production. Une fois le premier canari validé, utilisez la configuration des canaux, le catalogue de modèles et l'historique d'usage comme boucle d'exploitation quotidienne.