• Installation du serveur Agent
  • Prérequis
  • Création des logs
  • Configuration LLM
  • Configuration de l’application
  • Déploiement
• Installation de ChromaDB
  • Prérequis
  • Installation
• Configuration des paramètres du serveur DigDash
• Installation d’OpenWebUI (optionnelle)
  • Pré-requis
  • Installation
• Ajouter un modèle LLM dans Openwebui

Ce document présente l’installation et la configuration de l’agent DigDash et de ses principaux composants.

L'Agent utilise un serveur MCP (Model Context Protocol) qui permet à Digdash de se connecter de manière standardisée à un modèle de langage (LLM).
MCP est un protocole standardisé pour connecter des applications aux modèles d’IA. Son rôle est de fournir au modèle un accès contrôlé et structuré à des ressources externes (dans notre cas, les données DigDash).
Ainsi, n'importe quel chatbot peut utiliser l'Agent.
OpenWebUI a été retenu ici comme exemple, car il s’agit d’un chatbot open source installable facilement. 

Installation du serveur Agent

Prérequis

• Un conteneur de servlets compatible Jakarta EE 9+, tel que Tomcat 10 ou Jetty 11
• Java 17

Décompressez l’archive d’installation de DigDash Tomcat 10 et placez le fichier /add-ons/agent/digdash_agent.war dans le dossier webapps de Tomcat.

Création des logs

1. Créez un fichier log4j2_agent.properties dans /etc/digdash avec la configuration suivante :

   ###################################
   # Log4j2 Status
   ###################################
   status=error
   name=PropertiesConfig
   ###################################
   # Rolling File Appender
   ###################################
   appender.rolling.type=RollingFile
   appender.rolling.name=RollingFile
   appender.rolling.fileName = /var/log/digdash/digdash_agent.log
   appender.rolling.filePattern = /var/log/digdash/digdash_agent-%i.log.gz
   appender.rolling.layout.type=PatternLayout
   appender.rolling.layout.pattern = %d %-5p [agent] [%t] (%F:%L) - %m%n
   appender.rolling.policies.type=Policies
   appender.rolling.policies.size.type=SizeBasedTriggeringPolicy
   appender.rolling.policies.size.size=200MB
   # Rollover strategy
   appender.rolling.strategy.type=DefaultRolloverStrategy
   appender.rolling.strategy.max=15
   ###################################
   # Root Logger
   ###################################
   rootLogger.level=info
   rootLogger.appenderRefs=rolling
   rootLogger.appenderRef.rolling.ref=RollingFile
   ###################################
   # Application-specific Logger
   ###################################
   logger.app.name=com.digdash
   logger.app.level=info
   logger.app.additivity=false
   logger.app.appenderRefs=rolling
   logger.app.appenderRef.rolling.ref=RollingFile

Cette configuration stocke les logs dans le fichier /var/log/digdash/digdash_agent.log et archive les anciens logs dans le dossier /var/log/digdash/. Vous pouvez ajuster la propriété logger.app.level pour modifier le niveau de verbosité des logs de l’application web.

2. Ajoutez la ligne suivante dans /etc/digdash/digdash.properties pour que DigDash puisse lire la configuration des logs :

   agent.ddlog4j.properties.file=/etc/digdash/log4j2_agent.properties

Configuration LLM

L’application web prend en charge les modèles d’OVH Cloud. Il est recommandé d’utiliser le modèle "Llama-3.3 70b".
D’autres modèles sont disponibles dans le catalogue OVH : https://endpoints.ai.cloud.ovh.net/catalog.

1. Ajoutez l’URL de l’API LLM dans /etc/digdash/digdash.properties :agent.llm.baseurl=https://llama-3-3-70b-instruct.endpoints.kepler.ai.cloud.ovh.net/api/openai_compat/v1
2. Générez une clé API depuis OVH Cloud en suivant ce guide : https://help.ovhcloud.com/csm/en-public-cloud-ai-endpoints-getting-started?id=kb_article_view&sysparm_article=KB0065403

3. Ajoutez votre clé API dans /etc/digdash/digdash.properties :

   agent.llm.apikey=<API_KEY>

Configuration de l’application

1. Configurez le serveur backend pour correspondre à votre environnement dans /etc/digdash/digdash.properties :

   agent.digdashserver.baseurl=https://<digdash.url.externe>
   agent.digdashserver.domain=ddenterpriseapi

   L’application web concaténera ces deux propriétés pour former l’URL complète du serveur backend (ex. : http://localhost:9080/ddenterpriseapi).

Déploiement

1. Déployez le serveur Tomcat.

2. Après le démarrage du serveur, exécutez la commande suivante pour vérifier que le serveur agent fonctionne :

   curl http://localhost:8080/digdash_agent/actuator/health

   La réponse attendue est :

   {
    "status": "UP"
   }

2. Vérifiez les journaux de démarrage dans /var/log/digdash/digdash_agent.log pour détecter tout avertissement ou erreur indiquant une configuration manquante.

Installation de ChromaDB

L’agent utilise ChromaDB, une base de données vectorielle, pour effectuer des recherches sémantiques sur les données des cubes DigDash.

Prérequis

• Serveur Linux
• Accès root au serveur

Installation

1. Créez le dossier d’installation :

   ​sudo mkdir /opt/chroma
   sudo useradd -m -s /bin/bash chroma
   sudo chown chroma:chroma /opt/chroma​

2. Accédez au dossier d'installation:

   sudo su - chroma
   cd /opt/chroma

3. Créez un fichier bash "install-chroma-cli.sh" via `nano install-chroma-cli.sh` en copiant-collant le script suivant:

   # ----------------------------------------------
   # Chroma CLI Installer Script
   # Usage:
   #   curl -sSL https://raw.githubusercontent.com/chroma-core/chroma/main/rust/cli/install/install.sh | bash
   # ----------------------------------------------
   REPO="chroma-core/chroma"
   RELEASE="cli-1.1.10"
   
   OS=$(uname -s)
   ARCH=$(uname -m)
   ASSET=""
   
   case "$OS" in
     Linux*)
      ASSET="chroma-linux"
       ;;
     Darwin*)
      if [ "$ARCH" = "arm64" ]; then
        ASSET="chroma-macos-arm64"
      else
        ASSET="chroma-macos-intel"
      fi
       ;;
     MINGW*|MSYS*|CYGWIN*)
      ASSET="chroma-windows.exe"
       ;;
     *)
      echo "Unsupported OS: $OS"
      exit 1
       ;;
   esac
   
   DOWNLOAD_URL="https://github.com/${REPO}/releases/download/${RELEASE}/${ASSET}"
   echo "Downloading ${ASSET} from ${DOWNLOAD_URL}..."
   curl -L "$DOWNLOAD_URL" -o chroma
   
   chmod +x chroma

4. Exécutez le script "install-chroma-cli.sh" pour installer l’interface en ligne de commande Chroma (Chroma CLI) :

   install-chroma-cli.sh

5. Créez le fichier de configuration de Chroma "config.yaml" :

   #################
   # OpenTelemetry #
   #################
   open_telemetry:
     service_name: "chroma"
     endpoint: "http://127.0.0.1:4317"
     filters:
       - crate_name: "chroma_frontend"
         filter_level: "trace"
   ########################
   # HTTP server settings #
   ########################
   port: 8000
   listen_address: "127.0.0.1" # Accept only local requests
   max_payload_size_bytes: 41943040
   cors_allow_origins: ["*"]
   
   ####################
   # General settings #
   ####################
   persist_path: "/opt/chroma/data"

Notez que Chroma n'écrit pas de log dans la sortie standard si la configuration "Open Telemetry" n'est pas donnée.

Dans notre installation, nous ne comptons pas mettre en place un serveur Open Telemetry collectant des métriques.  
Cela génère un log d'erreur toutes les minutes quand Chroma appelle le serveur car non disponible.

D'après la documentation OpenTelemetry, nous pouvons configurer la variable d'environnement OTEL_METRIC_EXPORT_INTERVAL pour déterminer la périodicité des appels d'export de métrique.
Ainsi, en donnant une valeur très élévée, le service sera "désactivé" en attendant le support de la variable OTEL_SDK_DISABLED dans l'implémentation rust d'OpenTelemetry.

6. Désactivez la configuration OpenTelemetry en ajoutant la variable d'environnement OTEL_METRIC_EXPORT_INTERVAL suivante :

   echo -e "\n### Chroma Configuration\nexport OTEL_METRIC_EXPORT_INTERVAL=31556952000 #one year in milliseconds" >> ~/.bashrc
   source ~/.bashrc

7. Augmentez la limite « soft » et « hard » du nombre de fichiers ouverts à au moins 65 536.
   Chroma doit pouvoir ouvrir de nombreux fichiers sous forte charge. Si ces limites sont trop basses, il pourrait ne pas réussir à ouvrir la base de données et l’application risquerait de ne plus fonctionner.
   Vous pouvez vérifier les limites actuelles avec :

   ulimit -n    # soft limit
   ulimit -Hn   # hard limit

   Si la limite est trop basse, alors vous pouvez augmenter temporairement la limite pour votre session ssh avec

   sudo ulimit -Hn 65536
   ulimit -n 65536

   ou appliquer de manière permanente les changements en modifiant les limites de securité du serveur `/etc/security/limits.conf`:

   sudo nano /etc/security/limits.conf

   Et en ajoutant les nouvelles limites de fichiers ouverts par processus pour l'utilisateur chroma:

   chroma soft nofile 65535
   chroma hard nofile 65535

8. Enfin, exécutez la commande suivante pour déployer le serveur :

   ANONYMIZED_TELEMETRY=False ./chroma run config.yaml >> chroma.log 2>&1 &

Chroma est écrit en Rust, vous pouvez donc ajuster la verbosité des logs en définissant la variable d’environnement RUST_LOG=debug.

9. Exécutez la commande suivante pour vérifier le bon déploiement du serveur:

   curl http://locahost:8000/api/v2/heartbeat

   La réponse devrait ressembler à:

   {"nanosecond heartbeat":1760109567965688154}

Configuration des paramètres du serveur DigDash

Pour configurer les paramètres du serveur DigDash, depuis le menu Configuration, allez sur la page Paramètres serveur > Paramètres supplémentaires > Intelligence Artificielle.

Dans la section Agent, cochez Activer la fonction Agent afin d'activer un ordonnanceur qui intègre périodiquement de nouveaux cubes et stocke les vectorisations dans la base Chroma. Une fois l'option activée, les paramètres suivants sont effectifs.

Installation d’OpenWebUI (optionnelle)

L'agent DigDash peut fonctionner avec n’importe quel chatbot compatible grâce au MCP (Model Context Protocol). Ce protocole permet aux modèles LLM d’utiliser des « outils » externes.
OpenWebUI a été retenu comme exemple, car il s’agit d’un chatbot open source installable facilement. 

Pré-requis

• Serveur Linux (Ubuntu/Debian recommandé)
• Python 3.11
• pip et virtualenv

Installez les packages requis :

Installation

1. Créez l'utilisateur openwebui:
   sudo useradd -m -s /bin/bash openwebui

2. Dirigez-vous vers le dossier d'installation: 
   cd /home/openwebui

3. Créez et activez un environnement virtuel dans ce dossier:

   python3 -m venv openwebui-venv
   source openwebui-venv/bin/activate

4. Mettez à jour pip pour éviter les problèmes de compatibilité :

   pip install --upgrade pip
   

5. Installez le package open-webui:

   pip install open-webui

   Notez que le téléchargement peut durer plusieurs minutes.

   ⚠ Ne pas utiliser le package Python uv.
   L’agent DigDash (fonction OpenWebUI) nécessite l’installation de bibliothèques Python supplémentaires à l’exécution, ce qui n’est pas compatible avec uv.

6. Déployez le serveur: 

   nohup open-webui serve --port 5000 &
   

    L’interface web devrait être disponible sur http://localhost:5000.

Ajouter un modèle LLM dans Openwebui

1. Connectez-vous à http://localhost:5000 en tant qu'administrateur.
2. Cliquez sur votre nom d'utilisateur en bas en gauche, puis cliquez sur Panneau d'adminstration.
3. Cliquez ensuite sur l'onglet Réglages en haut de la page.
4. Enfin dans le menu, cliquez sur Connexions.
5. Cliquez sur le bouton + pour ajouter une nouvelle connexion.
6. Vous pouvez renseigner une API compatible OpenAI. Nous allons ajouter le modèle LLama 3.3 d'OVH:
   • Type de connexion: Externe
   • URL: https://llama-3-3-70b-instruct.endpoints.kepler.ai.cloud.ovh.net/api/openai_compat/v1
   • Clé: La clé d'API du modèle. Vous pouvez réutiliser la clé OVH de l'agent DigDash.
7. Cliquez sur le symbole "Rafraîchir". Un message devrait s'afficher validant la nouvelle connexion.

8. Démarrez une nouvelle conversation. Vous devriez voir le modèle LLM dans la liste des modèles et pouvoir converser avec.