RubyLLM : une couche Ruby unique au-dessus de dix-sept fournisseurs de modèles

Le problème résolu : un seul vocabulaire pour dix-sept fournisseurs

Chaque fournisseur de modèles possède ses propres noms de champs, ses propres formats de messages, sa propre manière de déclarer des outils. Dans une application Rails, cette diversité se traduit par du code de plomberie : un client par fournisseur, des conversions de payloads, des tests qui divergent. RubyLLM prend le parti inverse. Le README annonce dix-sept fournisseurs intégrés, plus la possibilité de brancher directement un endpoint compatible OpenAI. La même méthode `ask` sert pour OpenAI, xAI, Anthropic, Google, AWS et des modèles locaux. Le public visé est donc précis : une équipe qui écrit du Ruby ou du Rails, qui veut tester plusieurs modèles sans réécrire sa couche d'appel, et qui préfère lire des objets Ruby plutôt que du JSON brut. Le README mentionne un usage en production chez Chat with Work, ce qui indique au moins un déploiement réel, sans donner de volumétrie ni de métriques.

Ce que fait réellement la bibliothèque entre votre code et l'API

L'API publique est une façade : `RubyLLM.chat`, `RubyLLM.paint`, `RubyLLM.embed`, `RubyLLM.transcribe`, `RubyLLM.speak`, `RubyLLM.ocr`, `RubyLLM.moderate`, `RubyLLM.rerank`, `RubyLLM.animate`, `RubyLLM.upload`. Derrière, le README décrit une répartition des responsabilités : le gem tient le registre des modèles, les appels d'outils, le registre d'usage et les batches. Le registre de modèles est le point central. C'est lui qui détermine quels paramètres sont acceptés, quels types de fichiers un modèle sait ingérer, et quels fournisseurs sont joignables. Deux conséquences pratiques. D'abord, une fonctionnalité absente du registre ne sera pas disponible, même si le fournisseur l'expose. Ensuite, la qualité de votre expérience dépend du rythme de mise à jour de ce registre, pas seulement de votre code. Le suivi des coûts suit le même chemin : `chat.tokens` et `chat.cost` s'appuient sur un registre d'usage par tentative, ce qui suppose que les tarifs connus du gem correspondent à ceux facturés par le fournisseur. Le README ne détaille pas la fréquence de mise à jour de ces tarifs.

Chats, outils et agents : trois niveaux d'abstraction

Le premier niveau est le chat. `chat = RubyLLM.chat` puis `chat.ask "What's the best way to learn Ruby?"`. Le streaming se fait par bloc : `chat.ask "Tell me a story about Ruby" do |chunk| print chunk.content end`. Le deuxième niveau est l'outil. Une classe hérite de `RubyLLM::Tool`, déclare `description` et implémente `execute` avec des arguments nommés. Le README donne un exemple météo qui appelle l'API open-meteo via Faraday et renvoie le JSON analysé. L'outil s'attache ensuite à une conversation avec `chat.with_tools(Weather)`. Le troisième niveau est l'agent : une classe hérite de `RubyLLM::Agent`, fixe `model` et `instructions`, et déclare ses outils avec `tools Weather`. Un agent s'instancie et s'interroge comme un chat. Cette gradation est cohérente : on commence par une question, on ajoute des outils quand le modèle doit agir, on encapsule quand la configuration doit être réutilisée. Deux mécanismes méritent l'attention. `requires_approval` suspend une exécution jusqu'à validation humaine, ce qui déplace la responsabilité de l'appel d'outil vers l'application. Et la boucle agentique peut être pilotée à la main avec `ask_later`, `step` et `complete?`, au lieu d'être entièrement déléguée au gem.

Rails : persistance, pièces jointes et streaming Hotwire

L'intégration Rails est présentée comme un mode d'emploi à part entière : l'API fonctionne sur vos propres enregistrements `Chat` et `Message`, avec les pièces jointes Active Storage, le streaming Hotwire et les jobs en arrière-plan. C'est le point qui distingue RubyLLM d'un simple client HTTP. Vous conservez votre schéma de données, vos migrations, vos validations ; le gem s'y branche au lieu d'imposer ses tables. Le README mentionne aussi des générateurs, sans en donner la liste ni les options. Trois éléments restent à vérifier de votre côté : la forme exacte des associations attendues, la manière dont les messages sont sérialisés en base, et le comportement des appels d'outils lorsque la conversation est rechargée depuis la base plutôt que gardée en mémoire. Le README ne tranche pas ces questions. Les gabarits de prompt ERB vivent dans `app/prompts` et se rendent avec `RubyLLM.render_prompt`, ce qui place les instructions dans le cycle de déploiement Rails habituel.

Mise en route : ce que le README donne, et ce qu'il laisse à votre charge

L'installation passe par le gem `ruby_llm`, et le README renvoie à la page Getting Started pour l'installation et la configuration des fournisseurs. Les exemples de code sont explicitement étiquetés comme utilisant la version 2.0.0.rc2. C'est une information de version, pas un détail : la documentation publiée correspond à une release candidate. La configuration des fournisseurs n'est pas détaillée dans le matériel fourni. On sait qu'il faut configurer les fournisseurs que l'on veut essayer, sans connaître les noms de clés ni le fichier d'initialisation attendu. Les points d'entrée visibles dans les exemples sont en revanche explicites : `RubyLLM.chat(model: "gemini-3.7-flash")` pour choisir un modèle, `with: "ruby_conf.jpg"` ou `with: ["diagram.png", "report.pdf", "notes.txt"]` pour joindre des fichiers, `with_schema` pour la sortie structurée, `with_caching` et `cache_until_here` pour le cache de prompt, `with_fallbacks` pour les modèles de secours, `cancel` pour interrompre une exécution, `with_server_tools` pour la recherche web, l'exécution de code et les connecteurs MCP. La sortie structurée s'appuie sur un schéma Schematist, une dépendance externe au gem lui-même, et le résultat se lit avec `response.parsed`. Un point à noter : les noms de modèles des exemples (gpt-5.6-luna, gemini-3.7-flash, rerank-v3.5) ne sont pas des modèles que je peux confirmer comme disponibles. Traitez-les comme des identifiants illustratifs et vérifiez le registre avant de les reprendre.

Ce que le dépôt ne montre pas

Le matériel fourni s'arrête à la documentation. Aucun benchmark, aucune latence, aucun coût mesuré, aucune volumétrie. Le README affirme que le gem est utilisé en production chez Chat with Work, mais ne fournit aucun chiffre. Il annonce dix-sept fournisseurs sans les énumérer nommément dans la description ; les topics du dépôt suggèrent une couverture large, mais un topic n'est pas une garantie de support. Un point de friction possible : la branche 2.0.0 est en release candidate au moment de la dernière publication, avec deux RC successives et une version stable antérieure en 1.16.0. Cela signifie que la documentation principale décrit une API dont la stabilité n'est pas encore acquise. Autre limite structurelle : la bibliothèque dépend d'un registre de modèles maintenu côté gem. Si un fournisseur change son API ou publie un nouveau modèle, votre code n'a rien à modifier, mais vous attendez une mise à jour du gem. Ce n'est pas un défaut en soi, c'est un transfert de responsabilité qu'il faut accepter. Enfin, la licence MIT accompagne le gem, ce qui autorise l'usage commercial et la modification, mais n'offre aucune garantie de la part des auteurs. Rien dans le matériel ne mentionne de support commercial, de SLA ou d'engagement de maintenance. Pour un projet dont la feuille de route dépend de fournisseurs tiers, c'est une donnée à intégrer.

Face à quoi d'autre : client HTTP direct ou SDK officiel

L'alternative la plus directe est d'écrire sa propre couche au-dessus des SDK officiels ou de simples appels HTTP. La différence n'est pas dans la possibilité, elle est dans le périmètre. Un client maison vous laisse choisir exactement les champs envoyés, gérer les erreurs comme vous l'entendez et ne dépendre d'aucun intermédiaire. En échange, vous réimplémentez la conversion des messages, le suivi des appels d'outils, la comptabilité des tokens et le support de chaque nouveau fournisseur. RubyLLM prend ces tâches à sa charge et vous impose son registre de modèles ainsi que son rythme de publication. Le choix se joue donc sur un axe simple : combien de fournisseurs comptez-vous interroger, et à quelle vitesse votre équipe peut-elle absorber la maintenance de cette plomberie. Pour un seul fournisseur et un seul cas d'usage, la couche maison reste défendable. Dès que vous voulez comparer deux modèles, ajouter des embeddings, du reranking et de la transcription, la surface à maintenir change d'ordre de grandeur.

Conclusion éditoriale

RubyLLM convient aux équipes Ruby et Rails qui veulent un seul vocabulaire pour plusieurs fournisseurs, avec persistance Active Record et pièces jointes Active Storage. Il convient mal à qui cherche une fonctionnalité absente du registre de modèles, ou refuse de dépendre d'un gem publié en release candidate pour la branche 2.0.0. À vérifier avant toute adoption : la version publiée sur rubygems.org et sa stabilité, le contenu du registre de modèles pour les modèles que vous visez, les clés de configuration attendues par chaque fournisseur, et le comportement de la boucle d'outils sur votre schéma de données.

Sources officielles

1. crmne/ruby_llm on GitHub
2. License: MIT
3. Project website
4. README
5. Releases