Last modified by Aurelie Bertrand on 2025/10/14 16:41
Show last authors
1 {{toc/}}
2
3 ----
4
5 (% class="wikigeneratedid" %)
6 Ce document présente l’installation et la configuration de l’agent DigDash et de ses principaux composants.
7
8 (% class="wikigeneratedid" %)
9 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).
10 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).
11 Ainsi, n'importe quel chatbot peut utiliser l'Agent.
12 OpenWebUI a été retenu ici comme exemple, car il s’agit d’un chatbot open source installable facilement.
13
14 = Installation du serveur Agent =
15
16 == Prérequis ==
17
18 * Un conteneur de servlets compatible Jakarta EE 9+, tel que Tomcat 10 ou Jetty 11
19 * Java 17
20
21 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.
22
23 == Création des logs ==
24
25 1. (((
26 Créez un fichier log4j2_agent.properties dans /etc/digdash avec la configuration suivante :
27
28 {{code language="shell"}}
29 ###################################
30 # Log4j2 Status
31 ###################################
32 status=error
33 name=PropertiesConfig
34 ###################################
35 # Rolling File Appender
36 ###################################
37 appender.rolling.type=RollingFile
38 appender.rolling.name=RollingFile
39 appender.rolling.fileName = /var/log/digdash/digdash_agent.log
40 appender.rolling.filePattern = /var/log/digdash/digdash_agent-%i.log.gz
41 appender.rolling.layout.type=PatternLayout
42 appender.rolling.layout.pattern = %d %-5p [agent] [%t] (%F:%L) - %m%n
43 appender.rolling.policies.type=Policies
44 appender.rolling.policies.size.type=SizeBasedTriggeringPolicy
45 appender.rolling.policies.size.size=200MB
46 # Rollover strategy
47 appender.rolling.strategy.type=DefaultRolloverStrategy
48 appender.rolling.strategy.max=15
49 ###################################
50 # Root Logger
51 ###################################
52 rootLogger.level=info
53 rootLogger.appenderRefs=rolling
54 rootLogger.appenderRef.rolling.ref=RollingFile
55 ###################################
56 # Application-specific Logger
57 ###################################
58 logger.app.name=com.digdash
59 logger.app.level=info
60 logger.app.additivity=false
61 logger.app.appenderRefs=rolling
62 logger.app.appenderRef.rolling.ref=RollingFile
63 {{/code}}
64 )))
65
66 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.
67
68 (% start="2" %)
69 1. (((
70 Ajoutez la ligne suivante dans /etc/digdash/digdash.properties pour que DigDash puisse lire la configuration des logs :
71
72 {{code}}
73 agent.ddlog4j.properties.file=/etc/digdash/log4j2_agent.properties
74 {{/code}}
75 )))
76
77 == Configuration LLM ==
78
79 L’application web prend en charge les modèles d’OVH Cloud. Il est recommandé d’utiliser le modèle "Llama-3.3 70b".
80 D’autres modèles sont disponibles dans le catalogue OVH : [[https:~~/~~/endpoints.ai.cloud.ovh.net/catalog>>url:https://endpoints.ai.cloud.ovh.net/catalog]].
81
82 1. Ajoutez l’URL de l’API LLM dans /etc/digdash/digdash.properties :{{code}}agent.llm.baseurl=https://llama-3-3-70b-instruct.endpoints.kepler.ai.cloud.ovh.net/api/openai_compat/v1{{/code}}
83 1. 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>>url:https://help.ovhcloud.com/csm/en-public-cloud-ai-endpoints-getting-started?id=kb_article_view&sysparm_article=KB0065403]]
84 1. (((
85 Ajoutez votre clé API dans /etc/digdash/digdash.properties :
86
87 {{code}}
88 agent.llm.apikey=<API_KEY>
89 {{/code}}
90 )))
91
92 == Configuration de l’application ==
93
94 1. (((
95 Configurez le serveur backend pour correspondre à votre environnement dans /etc/digdash/digdash.properties :
96
97 {{code}}
98 agent.digdashserver.baseurl=https://<digdash.url.externe>
99 agent.digdashserver.domain=ddenterpriseapi
100 {{/code}}
101
102 L’application web concaténera ces deux propriétés pour former l’URL complète du serveur backend (ex. : [[http:~~/~~/localhost:9080/ddenterpriseapi>>url:http://localhost:9080/ddenterpriseapi]]).
103 )))
104
105 == Déploiement ==
106
107 1. Déployez le serveur Tomcat.
108 1. (((
109 Après le démarrage du serveur, exécutez la commande suivante pour vérifier que le serveur agent fonctionne :
110
111 {{code language="shell"}}
112 curl http://localhost:8080/digdash_agent/actuator/health
113 {{/code}}
114
115 La réponse attendue est :
116
117 {{code language="shell"}}
118 {
119  "status": "UP"
120 }
121 {{/code}}
122 )))
123
124 (% start="2" %)
125 1. 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.
126
127 = Installation de ChromaDB =
128
129 L’agent utilise ChromaDB, une base de données vectorielle, pour effectuer des recherches sémantiques sur les données des cubes DigDash.
130
131 == Prérequis ==
132
133 * Serveur Linux
134 * Accès root au serveur
135
136 == Installation ==
137
138 1. (((
139 Créez le dossier d’installation :
140
141 {{code language="shell"}}
142 ​sudo mkdir /opt/chroma
143 sudo useradd -m -s /bin/bash chroma
144 sudo chown chroma:chroma /opt/chroma​
145 {{/code}}
146 )))
147 1. (((
148 Accédez au dossier d'installation:
149
150 {{code language="shell"}}
151 sudo su - chroma
152 cd /opt/chroma
153 {{/code}}
154 )))
155
156 (% start="3" %)
157 1. (((
158 Créez un fichier bash "install-chroma-cli.sh" via `nano install-chroma-cli.sh` en copiant-collant le script suivant:
159
160 {{code language="shell"}}
161 # ----------------------------------------------
162 # Chroma CLI Installer Script
163 # Usage:
164 # curl -sSL https://raw.githubusercontent.com/chroma-core/chroma/main/rust/cli/install/install.sh | bash
165 # ----------------------------------------------
166 REPO="chroma-core/chroma"
167 RELEASE="cli-1.1.10"
168
169 OS=$(uname -s)
170 ARCH=$(uname -m)
171 ASSET=""
172
173 case "$OS" in
174 Linux*)
175 ASSET="chroma-linux"
176 ;;
177 Darwin*)
178 if [ "$ARCH" = "arm64" ]; then
179 ASSET="chroma-macos-arm64"
180 else
181 ASSET="chroma-macos-intel"
182 fi
183 ;;
184 MINGW*|MSYS*|CYGWIN*)
185 ASSET="chroma-windows.exe"
186 ;;
187 *)
188 echo "Unsupported OS: $OS"
189 exit 1
190 ;;
191 esac
192
193 DOWNLOAD_URL="https://github.com/${REPO}/releases/download/${RELEASE}/${ASSET}"
194 echo "Downloading ${ASSET} from ${DOWNLOAD_URL}..."
195 curl -L "$DOWNLOAD_URL" -o chroma
196
197 chmod +x chroma
198 {{/code}}
199 )))
200
201 (% start="4" %)
202 1. (((
203 Exécutez le script "install-chroma-cli.sh" pour installer l’interface en ligne de commande Chroma (Chroma CLI) :
204
205 {{code language="shell"}}
206 install-chroma-cli.sh
207 {{/code}}
208 )))
209 1. (((
210 Créez le fichier de configuration de Chroma "config.yaml" :
211
212 {{code language="shell"}}
213 #################
214 # OpenTelemetry #
215 #################
216 open_telemetry:
217 service_name: "chroma"
218 endpoint: "http://127.0.0.1:4317"
219 filters:
220 - crate_name: "chroma_frontend"
221 filter_level: "trace"
222 ########################
223 # HTTP server settings #
224 ########################
225 port: 8000
226 listen_address: "127.0.0.1" # Accept only local requests
227 max_payload_size_bytes: 41943040
228 cors_allow_origins: ["*"]
229
230 ####################
231 # General settings #
232 ####################
233 persist_path: "/opt/chroma/data"
234 {{/code}}
235 )))
236
237 Notez que Chroma n'écrit pas de log dans la sortie standard si la configuration "Open Telemetry" n'est pas donnée.
238
239 Dans notre installation, nous ne comptons pas mettre en place un serveur Open Telemetry collectant des métriques.
240 Cela génère un log d'erreur toutes les minutes quand Chroma appelle le serveur car non disponible.
241
242 D'après la [[documentation OpenTelemetry>>https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#periodic-exporting-metricreader]], nous pouvons configurer la variable d'environnement OTEL_METRIC_EXPORT_INTERVAL pour déterminer la périodicité des appels d'export de métrique.
243 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>>https://github.com/open-telemetry/opentelemetry-rust/pull/3088]].
244
245 (% start="6" %)
246 1. (((
247 Désactivez la configuration OpenTelemetry en ajoutant la variable d'environnement OTEL_METRIC_EXPORT_INTERVAL suivante :
248
249 {{code language="shell"}}
250 echo -e "\n### Chroma Configuration\nexport OTEL_METRIC_EXPORT_INTERVAL=31556952000 #one year in milliseconds" >> ~/.bashrc
251 source ~/.bashrc
252 {{/code}}
253 )))
254 1. (((
255 Augmentez la limite « soft » et « hard » du nombre de fichiers ouverts à au moins 65 536.
256 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.
257 Vous pouvez vérifier les limites actuelles avec :
258
259 {{code}}
260 ulimit -n # soft limit
261 ulimit -Hn # hard limit
262 {{/code}}
263
264 Si la limite est trop basse, alors vous pouvez augmenter temporairement la limite pour votre session ssh avec
265
266 {{code language="shell"}}
267 sudo ulimit -Hn 65536
268 ulimit -n 65536
269 {{/code}}
270
271 ou appliquer de manière permanente les changements en modifiant les limites de securité du serveur `/etc/security/limits.conf`:
272
273 (((
274 {{code language="shell"}}
275 sudo nano /etc/security/limits.conf
276 {{/code}}
277 )))
278
279 Et en ajoutant les nouvelles limites de fichiers ouverts par processus pour l'utilisateur chroma:
280
281 {{code}}
282 chroma soft nofile 65535
283 chroma hard nofile 65535
284 {{/code}}
285 )))
286 1. (((
287 Enfin, exécutez la commande suivante pour déployer le serveur :
288
289 {{code}}
290 ANONYMIZED_TELEMETRY=False ./chroma run config.yaml >> chroma.log 2>&1 &
291 {{/code}}
292 )))
293
294 (% class="wikigeneratedid" %)
295 Chroma est écrit en Rust, vous pouvez donc ajuster la verbosité des logs en définissant la variable d’environnement RUST_LOG=debug.
296
297 (% start="9" %)
298 1. (((
299 Exécutez la commande suivante pour vérifier le bon déploiement du serveur:
300
301 (((
302 {{code language="shell"}}
303 curl http://locahost:8000/api/v2/heartbeat
304 {{/code}}
305 )))
306
307 La réponse devrait ressembler à:
308
309 (((
310 {{code language="json"}}
311 {"nanosecond heartbeat":1760109567965688154}
312 {{/code}}
313 )))
314 )))
315
316 = Configuration des paramètres du serveur DigDash{{id name="Paramètres_serveur"/}} =
317
318 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>>doc:Digdash.deployment.configuration.configuration_guide.AI.WebHome]]**.
319
320 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.
321
322 |=Paramètre |=Description
323 |=Fréquence en secondes de la vectorisation des cubes dans la base de vecteurs|Définit la fréquence d’exécution de l'ordonnanceur. Ajustez selon la fréquence de reconstruction des cubes. La valeur minimale est de 1 seconde.
324 |=URL de base du modèle de vectorisation|(((
325 L’Agent prend actuellement en charge uniquement les modèles d’OVH. Nous recommandons le modèle BGE-M3 : [[https:~~/~~/bge-m3.endpoints.kepler.ai.cloud.ovh.net>>url:https://bge-m3.endpoints.kepler.ai.cloud.ovh.net/]].
326 )))
327 |=Clé API du modèle de vectorisation|Vous pouvez réutiliser la clé API utilisée pour le LLM.
328 |=URL de base du stockage des vecteurs|Définissez l’URL de base vers la base de données ChromaDB : [[http:~~/~~/localhost:8000>>url:http://localhost:8000]].
329 |=Clé d'environnement spécifique (prod, test ou dev)|ChromaDB stocke les vectorisations des cubes dans différentes "collections". Ce paramètre préfixe toutes les collections ChromaDB avec la valeur spécifiée (ex. : prod, test, dev). Utilisez-le si vous souhaitez utiliser la même base ChromaDB pour différents environnements.
330 |=Délai d'expiration du stockage des vecteurs|Valeur par défaut : 30 secondes.  Après ce délai, la requête est réessayée plusieurs fois avant d’échouer.
331 |=Forcer l'initialisation du stockage des vecteurs    |Cochez cette case pour effacer complètement la base pour l’environnement spécifié.
332 |=Liste des rôles à vectoriser|Pour limiter l’Agent à certains rôles, listez les identifiants des rôles séparés par des virgules (par exemple : Retail_2d6e0f1e, R_D_7b55a031).
333 |=Liste des modèles à vectoriser|Pour limiter l’Agent à certains modèles, listez les identifiants des modèles de données séparés par des virgules (par exemple : 761a667955c84f834bb2950996f93e1fv, c99c1c9fadd5e4ceafc954c4fb7c1067).
334 |=Liste des hiérarchies à vectoriser|Ajoutez les identifiants des hiérarchies temporelles que l’Agent doit interpréter. L’Agent détectera les filtres temporels dans l’entrée utilisateur et trouvera la correspondance la plus proche parmi les membres des hiérarchies spécifiées.
335 Pour trouver les identifiants de vos hiérarchies temporelles, allez dans le gestionnaire de hiérarchies du Studio. Consultez la page [[Gestionnaire de hiérarchies>>doc:Digdash.user_guide.studio.managers.hierarchies.WebHome]].
336
337 = Installation d’OpenWebUI (optionnelle) =
338
339 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.
340 OpenWebUI a été retenu comme exemple, car il s’agit d’un chatbot open source installable facilement.
341
342 == Pré-requis ==
343
344 * Serveur Linux (Ubuntu/Debian recommandé)
345 * Python 3.11
346 * //pip// et //virtualenv//
347
348 Installez les packages requis :
349
350 {{code}}
351 sudo apt update
352 sudo apt install -y python3 python3-venv python3-pip build-essential
353 {{/code}}
354
355 == Installation ==
356
357 1. Créez l'utilisateur openwebui:(((
358 {{code}}
359 sudo useradd -m -s /bin/bash openwebui
360 {{/code}}
361 )))
362
363 (% start="2" %)
364 1. Dirigez-vous vers le dossier d'installation: (((
365 {{code}}
366 cd /home/openwebui
367 {{/code}}
368 )))
369 1. (((
370 Créez et activez un environnement virtuel dans ce dossier:
371
372 (((
373 {{code language="shell"}}
374 python3 -m venv openwebui-venv
375 source openwebui-venv/bin/activate
376 {{/code}}
377 )))
378 )))
379 1. (((
380 Mettez à jour pip pour éviter les problèmes de compatibilité :
381
382 (((
383 {{code}}
384 pip install --upgrade pip
385 {{/code}}
386 )))
387 )))
388
389 (% start="5" %)
390 1. (((
391 Installez le package open-webui:
392
393 (((
394 {{code}}
395 pip install open-webui
396 {{/code}}
397
398 Notez que le téléchargement peut durer plusieurs minutes.
399
400 (% class="box warningmessage" %)
401 (((
402 ⚠ Ne pas utiliser le package Python uv.
403 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.
404 )))
405 )))
406 )))
407
408 (% start="6" %)
409 1. (((
410 (((
411 Déployez le serveur:
412
413 {{code}}
414 nohup open-webui serve --port 5000 &
415 {{/code}}
416
417 L’interface web devrait être disponible sur http:~/~/localhost:5000.
418 )))
419 )))
420
421 = Ajouter un modèle LLM dans Openwebui =
422
423 1. Connectez-vous à http:~/~/localhost:5000 en tant qu'administrateur.
424 1. Cliquez sur votre nom d'utilisateur en bas en gauche, puis cliquez sur **Panneau d'adminstration**.
425 1. Cliquez ensuite sur l'onglet **Réglages** en haut de la page.
426 1. Enfin dans le menu, cliquez sur **Connexions**.
427 1. Cliquez sur le bouton **+** pour ajouter une nouvelle connexion.
428 1. Vous pouvez renseigner une API compatible OpenAI. Nous allons ajouter le modèle LLama 3.3 d'OVH:
429 1*. **Type de connexion**: Externe
430 1*. **URL**: [[https:~~/~~/llama-3-3-70b-instruct.endpoints.kepler.ai.cloud.ovh.net/api/openai_compat/v1>>https://llama-3-3-70b-instruct.endpoints.kepler.ai.cloud.ovh.net/api/openai_compat/v1]]
431 1*. **Clé**: La clé d'API du modèle. Vous pouvez réutiliser la clé OVH de l'agent DigDash.
432 1. Cliquez sur le symbole "Rafraîchir". Un message devrait s'afficher validant la nouvelle connexion.
433
434 (% class="box infomessage" %)
435 (((
436 ℹ En cas d'échec, assurez-vous que la clé d'API est bien correcte. En général, l'url attendue est la racine du web-service de completion de chat.
437 Par exemple, le webservice complet d'OVH //https:~/~/llama-3-3-70b-instruct.endpoints.kepler.ai.cloud.ovh.net/api/openai_compat/v1/chat/completions//
438 devient //https:~/~/llama-3-3-70b-instruct.endpoints.kepler.ai.cloud.ovh.net/api/openai_compat/v1.//
439 \\De même pour l'api d'OpenAI, //https:~/~/api.openai.com/v1/chat/completions// devient //https:~/~/api.openai.com/v1.//
440 )))
441
442 (% start="8" %)
443 1. Démarrez une nouvelle conversation. Vous devriez voir le modèle LLM dans la liste des modèles et pouvoir converser avec.