aidea-server : le backend Go qui unifie les LLM et la génération d'images derrière une API compatible OpenAI

Deux API pour deux publics distincts

Le dépôt sépare nettement les points d'entrée. Le répertoire api porte une API compatible OpenAI : d'après le tableau de structure du README, les endpoints qui s'y trouvent peuvent être consommés directement par n'importe quel logiciel tiers qui parle le protocole OpenAI. Le répertoire server, lui, regroupe les endpoints destinés au client AIdea. Cette séparation est le choix de conception le plus lisible du projet. Elle signifie qu'un outil existant, configuré pour pointer vers une URL OpenAI, peut viser cette instance sans adaptation, tandis que les fonctions propres à l'application (les personas numériques, par exemple) restent sur une surface distincte.

Le revers apparaît vite : deux surfaces à maintenir, deux jeux de tests, et une compatibilité OpenAI qui doit être préservée à chaque évolution du protocole amont. Le README ne précise pas jusqu'où va cette compatibilité (streaming, function calling, formats de réponse d'erreur). C'est un point à vérifier dans le code avant de bâtir dessus.

Comment les modèles de chat sont normalisés

Le mécanisme central se trouve sous pkg/ai/chat. Le README le décrit sans ambiguïté : il s'agit d'une interface abstraite de modèle de conversation, et tous les modèles de chat y sont encapsulés pour être compatibles avec le protocole OpenAI Chat Stream. Autrement dit, chaque fournisseur branché (GPT, Qwen, ERNIE et les autres annoncés dans la description du dépôt) est traduit vers un format de flux unique. C'est cette couche qui rend l'API compatible OpenAI possible : le serveur ne réécrit pas sa logique métier par fournisseur, il convertit à la frontière.

Cette approche a un coût classique. Un wrapper qui normalise vers un protocole commun tend à exposer l'intersection des capacités, pas l'union. Les paramètres propres à un fournisseur, ou les modalités qu'un seul propose, demandent soit une extension du format normalisé, soit un chemin dédié. Le README ne dit pas comment le projet tranche ce dilemme, et il ne liste pas non plus les fournisseurs effectivement présents dans pkg/ai/chat à la date du dernier push. La description mentionne GPT, 通义千问 et 文心一言 ; le reste doit se lire dans l'arborescence.

Le socle : Glacier, Eloquent et une pile d'infrastructure

Le projet ne repose pas sur des bibliothèques Go très répandues. Il utilise deux frameworks maison : Glacier, un framework applicatif modulaire avec injection de dépendances bâti sur le conteneur go-ioc, et Eloquent, un ORM inspiré de Laravel et généré par code, avec support de MySQL notamment. Le README justifie Glacier par un besoin de propagation des dépendances et de modularisation.

Ce choix a une conséquence pratique directe : la documentation externe sur ces deux briques est rare, et la lecture du code devient le principal moyen d'apprentissage. Autour d'elles, le dépôt empile des paquets identifiés dans le tableau : pkg/redis, pkg/token pour les JWT, pkg/rate pour la limitation de débit, pkg/proxy pour un proxy SOCKS5, pkg/uploader adossé au stockage Qiniu, pkg/sms comme abstraction unifiée des fournisseurs SMS, pkg/aliyun pour les SMS et le contrôle de contenu, pkg/tencent pour la reconnaissance vocale et les SMS, pkg/youdao pour la traduction, pkg/dingding pour les notifications. Le paquet pkg/voice, synthèse vocale via Qiniu, est signalé comme actuellement désactivé. Cette densité donne une idée du périmètre réel : ce n'est pas un proxy de modèles, c'est un backend d'application complet avec facturation, paiement et notifications.

Traitement asynchrone, facturation et paiements

internal/queue définit la file de tâches et internal/queue/consumer ses consommateurs : d'après le README, toutes les tâches traitées de façon asynchrone sont déclarées à cet endroit. C'est le chemin emprunté par les opérations longues, dont la génération d'images. internal/coins porte la tarification et les politiques de facturation, avec un fichier d'exemple coins-table.yaml à la racine. internal/payment implémente les paiements en ligne, Alipay et Apple étant cités.

La présence de ces trois blocs dans le même dépôt indique un produit commercial, pas une brique d'infrastructure neutre. La note de version 202404071800 mentionne d'ailleurs Stripe, l'arrêt de certaines sorties et les canaux de modèles. Pour une équipe qui veut seulement un routeur multi-fournisseurs, cette couche est du poids mort à comprendre et à configurer. Pour une équipe qui construit une application grand public, elle représente un travail déjà fait, mais dont les règles métier sont enfouies dans le code plutôt que documentées.

Mise en route : configuration et déploiement

Le README renvoie à docs/deploy.md pour l'auto-hébergement, et à docs/deploy-vip.md pour un déploiement assisté. Il existe par ailleurs un dépôt séparé, aidea-docker, dédié au déploiement conteneurisé. Le dépôt fournit trois fichiers d'exemple à la racine : config.yaml pour la configuration applicative, coins-table.yaml pour la grille tarifaire, et nginx.conf pour la configuration Nginx. Un fichier systemd.service sert d'exemple d'unité systemd. Le point d'entrée du programme est cmd.

Les migrations de base de données sont en SQL, dans le répertoire migrate. Concrètement, la séquence que le matériel permet de décrire est : renseigner config.yaml, appliquer les fichiers de migrate, compiler le binaire depuis cmd, puis placer Nginx et systemd devant. Le README ne détaille ni les clés de configuration attendues dans config.yaml, ni l'ordre exact des migrations, ni les variables d'environnement. Ces informations sont dans docs/deploy.md, que je n'ai pas. Prévoyez donc de lire ce fichier avant d'estimer la charge d'installation.

Le passif documentaire assumé par le projet

Le README contient un avertissement rare et utile : les commentaires de code et la documentation technique sont actuellement limités et seront complétés avec le temps. Il ajoute deux avertissements de nommage qui évitent des contresens coûteux. D'abord, Room, Advisory Group et Digital Persona désignent la même chose dans le code, la nomenclature ayant évolué par révisions successives. Ensuite, la v1 de Creation Island n'a rien à voir avec la v2 : la v1 servait les versions de l'app jusqu'à 1.0.1, et depuis 1.0.2 elle n'est plus utilisée.

Ces notes sont précieuses parce qu'elles signalent un dépôt où le vocabulaire du code ne correspond plus au vocabulaire produit. Un nouveau contributeur qui grep Room trouvera du code lié aux personas numériques. Ce n'est pas un défaut de conception, c'est une dette de nommage, et elle est explicitement reconnue. Notez aussi que le README ne fournit aucune information de licence, et que le champ correspondant est inconnu dans les métadonnées du dépôt. Sans fichier de licence identifiable, on ne peut pas décrire les droits de réutilisation, de modification ou de redistribution. C'est un point bloquant pour un usage en entreprise, et je ne peux que constater l'absence, pas l'interpréter.

Quand ce n'est pas le bon outil

Si votre besoin se limite à router des requêtes vers plusieurs fournisseurs de modèles avec une API compatible OpenAI, aidea-server apporte beaucoup plus que nécessaire : paiements, SMS, stockage Qiniu, traduction Youdao, bots DingTalk, contrôle de contenu Aliyun. Chacun de ces blocs est une dépendance à configurer et une surface à auditer. Un projet comme LiteLLM, qui se présente comme un proxy multi-fournisseurs exposant une API compatible OpenAI, adopte une approche différente : la compatibilité est le produit lui-même, pas une couche ajoutée à un backend d'application. La différence n'est pas la qualité, c'est le périmètre. LiteLLM ne vous donne ni facturation par jetons ni personas numériques ; aidea-server ne vous donne pas un composant minimal que vous pouvez isoler sans lire l'ensemble du dépôt.

Un second cas de mauvaise adéquation : si votre équipe n'écrit pas Go. Les deux frameworks structurants étant maison, l'aide disponible en ligne est limitée, et le README indique lui-même que la documentation technique est en retard. Une équipe Python ou TypeScript devra apprendre Glacier et Eloquent en plus du domaine.

Coût de maintenance et angle mort de licence

Le rythme des versions publiées est irrégulier : 202401311800, puis 202402201630, puis 202404071800. Le dernier push enregistré sur la branche main est daté du 18 mars 2026, ce qui indique une activité plus récente que la dernière version étiquetée, sans que le matériel permette de dire ce qui a été poussé entre les deux. Le dépôt n'est pas archivé.

Deux conséquences pour la maintenance. La première : les notes de version sont rédigées en chinois et mêlent correctifs, nouvelles fonctionnalités et changements d'infrastructure (Stripe, canaux de modèles, arrêt de certaines sorties). Suivre les ruptures demande de lire ces notes, pas seulement les tags. La seconde : la dépendance à deux frameworks maison signifie que les mises à jour de Go, de MySQL ou de Redis peuvent interagir avec du code que peu de gens connaissent en dehors du mainteneur. Sur la licence, je ne peux rien affirmer : le champ est inconnu et le README n'en mentionne aucune. Vérifiez la présence d'un fichier LICENSE à la racine avant tout usage autre qu'exploration locale.

Conclusion éditoriale

aidea-server convient à une équipe qui veut un backend Go déjà structuré autour de plusieurs fournisseurs de modèles et d'une API compatible OpenAI, et qui accepte de lire le code faute de documentation. Il ne convient pas à qui cherche un projet clé en main avec une licence explicite et des commentaires abondants. Avant de vous engager, vérifiez trois choses dans le dépôt : le fichier de licence, le contenu de docs/deploy.md, et la liste des fournisseurs réellement implémentés sous pkg/ai/chat.

Sources officielles

1. Issues
2. mylxsw/aidea-server on GitHub
3. Project website
4. README
5. Releases