Configurer l’Assistant IA en self-hosted sur Grist : Guide pratique pour débutants

Grist est un outil puissant pour les petites entreprises, les administrations ou les associations qui gèrent des données sans complications inutiles. L’un de ses atouts est l’intégration d’un Assistant IA, qui aide à générer des formules, expliquer du code ou transformer des données directement dans vos documents. Si vous auto-hébergez Grist – par exemple sur un serveur Docker pour contrôler vos données – vous pouvez configurer cet Assistant avec des services externes comme OpenAI ou OpenRouter, ou même des modèles locaux comme Llama. Cela garde tout chez vous, sans dépendre du cloud public.

Ce guide s’adresse aux débutants : pas de jargon technique excessif, juste les étapes claires. Nous couvrons la version legacy (pour l’édition Community) et la version actuelle (pour l’édition Enterprise). Avant de commencer, assurez-vous que votre installation Grist est opérationnelle. Si ce n’est pas le cas, consultez la documentation self-hosted de base.

Pourquoi configurer l’Assistant IA en self-hosted ?

Dans une PME ou une association, l’IA peut simplifier la gestion : imaginez générer une formule pour trier des budgets en quelques clics, sans être expert en code. En self-hosted, vous évitez les coûts récurrents des API cloud et protégez les données sensibles, comme des listes de membres ou des rapports financiers. L’Assistant utilise des endpoints d’IA compatibles avec l’API chat completions (un standard ouvert), ce qui le rend flexible.

Les deux versions fonctionnent sur le même principe : définir des variables d’environnement dans votre configuration Docker ou serveur. La legacy est plus simple, limitée aux formules ; la nouvelle gère des interactions plus avancées, comme des appels d’outils structurés.

Prérequis généraux

Installation Grist self-hosted : Utilisez Docker ou Docker Compose. Si vous n’avez pas encore installé Grist, téléchargez l’image officielle depuis le dépôt GitHub de Grist et lancez-la avec un docker run basique.
Accès à un terminal : Pour éditer les fichiers de configuration (comme docker-compose.yml).
Compte chez un fournisseur IA : Gratuit pour tester, mais prévoyez un budget pour l’usage (environ 0,01 € par requête pour des modèles basiques).
Édition Grist : Community pour legacy, Enterprise pour la nouvelle (via licence ou build custom).
Variables d’environnement : Vous les définirez dans votre fichier de config Docker. Redémarrez le conteneur après chaque changement.

Pas besoin de compétences en programmation ; copiez-collez suffit.

Configuration de la version legacy (AI Formula Assistant)

Cette version est idéale pour débuter : elle aide surtout à créer des formules Python dans Grist. Elle est disponible dans l’édition Community, gratuite pour self-hosted.

Étape 1 : Choisir un fournisseur d’IA

Commencez par OpenAI, le plus simple.

Créez un compte sur platform.openai.com.
Générez une clé API : Allez dans "API Keys", cliquez "Create new secret key", copiez-la (elle ressemble à sk-proj-...).

Pour OpenRouter (qui agrège plusieurs modèles, y compris gratuits) :

Inscrivez-vous sur openrouter.ai.
Générez une clé API dans les paramètres.

Pour un modèle local comme Llama :

Installez un serveur local compatible, comme Ollama (gratuit, open-source). Téléchargez-le sur ollama.com, lancez ollama run llama3 pour tester. L’endpoint sera http://localhost:11434/v1/chat/completions.

Étape 2 : Définir les variables d’environnement

Ouvrez votre fichier docker-compose.yml (ou équivalent) et ajoutez une section environment sous le service Grist. Exemple pour OpenAI :

services:
  grist:
    image: gristlabs/grist
    environment:
      - ASSISTANT_CHAT_COMPLETION_ENDPOINT=https://api.openai.com/v1/chat/completions
      - ASSISTANT_API_KEY=sk-votre-cle-openai-ici
      - ASSISTANT_MODEL=gpt-4o-mini  # Modèle économique et rapide

Pour OpenRouter :

      - ASSISTANT_CHAT_COMPLETION_ENDPOINT=https://openrouter.ai/api/v1/chat/completions
      - ASSISTANT_API_KEY=sk-or-votre-cle-openrouter-ici
      - ASSISTANT_MODEL=openai/gpt-4o-mini  # Ou un autre comme anthropic/claude-3-haiku

Pour Llama local (via Ollama sur le même hôte) :

      - ASSISTANT_CHAT_COMPLETION_ENDPOINT=http://host.docker.internal:11434/v1/chat/completions
      - ASSISTANT_API_KEY=  # Pas besoin si local
      - ASSISTANT_MODEL=llama3  # Nom du modèle Ollama

Note : host.docker.internal pointe vers l’hôte depuis Docker ; ajustez si votre setup diffère.

Étape 3 : Redémarrer et tester

Lancez docker-compose up -d pour appliquer les changements.
Ouvrez Grist dans votre navigateur, créez un document vide.
Dans une cellule de formule, tapez / ou cliquez sur l’icône IA (si visible). Demandez : "Génère une formule pour sommer les ventes par mois."
L’Assistant devrait répondre avec du code Python prêt à coller.

Si rien ne se passe, vérifiez les logs Docker (docker logs grist) pour des erreurs comme "Invalid API key".

Configuration de la version nouvelle (Assistant)

Disponible dans l’édition Enterprise, cette version étend l’IA à des explications de code, transformations de données et interactions plus riches. Elle supporte les "tool calls" pour des réponses structurées, utile pour des workflows automatisés en admin ou associatif.

Étape 1 : Vérifier l’édition Enterprise

Assurez-vous d’avoir activé l’Enterprise : Ajoutez GRIST_EDITION=enterprise dans vos variables d’environnement, ou compilez depuis source avec la licence.

Étape 2 : Variables d’environnement avancées

Utilisez les mêmes bases que la legacy, mais avec des options supplémentaires pour plus de contrôle.

Exemple pour OpenAI :

environment:
  - ASSISTANT_CHAT_COMPLETION_ENDPOINT=https://api.openai.com/v1/chat/completions
  - ASSISTANT_API_KEY=sk-votre-cle-openai-ici
  - ASSISTANT_MODEL=gpt-4o-2024-08-06  # Modèle par défaut, récent et performant
  - ASSISTANT_LONGER_CONTEXT_MODEL=gpt-4o  # Pour les requêtes longues
  - ASSISTANT_MAX_TOOL_CALLS=5  # Limite les appels pour éviter les coûts

Pour OpenRouter :

  - ASSISTANT_CHAT_COMPLETION_ENDPOINT=https://openrouter.ai/api/v1/chat/completions
  - ASSISTANT_API_KEY=sk-or-votre-cle-ici
  - ASSISTANT_MODEL=anthropic/claude-3-5-sonnet-20240620  # Modèle avancé pour analyses complexes

Pour Llama local :

  - ASSISTANT_CHAT_COMPLETION_ENDPOINT=http://host.docker.internal:11434/v1/chat/completions
  - ASSISTANT_MODEL=llama3:8b  # Version 8B pour équilibre vitesse/précision
  - ASSISTANT_MAX_TOOL_CALLS=3  # Moins pour les modèles locaux lents

Les modèles locaux comme Llama nécessitent un serveur compatible (Ollama ou vLLM). Testez l’endpoint avec curl : curl http://localhost:11434/v1/chat/completions -H "Content-Type: application/json" -d '{"model": "llama3", "messages": [{"role": "user", "content": "Hello"}]}'. Si ça répond, c’est bon.

Étape 3 : Redémarrage et test avancé

Redémarrez avec docker-compose restart.
Dans Grist, accédez à l’Assistant via le menu latéral ou un widget dédié.
Testez : "Explique cette formule : =sum(Tasks lookup 'Status' = 'Done')." Ou "Transforme cette colonne de dates en jours restants."
Pour les tool calls : Demandez une tâche structurée, comme "Crée un rapport JSON des dépenses." L’IA renverra du code formaté.

Vérifiez les logs pour des erreurs de contexte (trop long) ; ajustez ASSISTANT_LONGER_CONTEXT_MODEL.

Différences entre les versions

Aspect	Legacy (Community)	Nouvelle (Enterprise)
Fonctionnalités	Formules basiques	Formules + explications, transformations, tool calls
Modèles supportés	OpenAI, OpenRouter basiques	+ Modèles avec structured output (ex. GPT-4o)
Variables clés	Endpoint, Key, Model	+ Longer Context, Max Tool Calls
Usage idéal	Débutants, PME simples	Administrations avec audits complexes
Coût	Bas (modèles mini)	Plus élevé pour tool calls

La legacy est plus légère ; passez à la nouvelle si vous gérez des données sensibles nécessitant des réponses précises.

Conseils pour les PME, administrations et associations

Économies : Utilisez des modèles gratuits comme Llama pour les tests. OpenRouter offre des crédits initiaux.
Sécurité : En self-hosted, vos données ne quittent pas votre serveur. Évitez les clés API en dur ; utilisez des secrets Docker.
Intégration quotidienne : Dans une asso, configurez pour générer des rapports de bénévoles. En admin, pour des tableaux de bord automatisés.
Limites : L’IA n’est pas infaillible ; validez toujours les formules générées. Coûts : Surveillez via les dashboards des fournisseurs.

Dépannage courant

Erreur "Endpoint not reachable" : Vérifiez l’URL et le réseau (pare-feu pour local).
"Invalid model" : Confirmez le nom exact sur le site du fournisseur.
Pas d’IA visible : Assurez l’édition correcte et redémarrez pleinement.
Coûts inattendus : Définissez ASSISTANT_MAX_TOOL_CALLS=1 pour limiter.

Pour plus, consultez les docs officielles. Cette config prend 15 minutes ; testez sur un doc vide. Si bloqué, le forum Grist aide vite.

Configurer l’Assistant IA en self-hosted sur Grist