Wiki source code of Guide d'installation de DigDash Agent

Last modified by Aurelie Bertrand on 2025/10/14 16:41

version	line-number	content
5.1	1	{{toc/}}
	2
	3	----
	4
6.1	5	(% class="wikigeneratedid" %)
	6	Ce document présente l’installation et la configuration de l’agent DigDash et de ses principaux composants.
	7
16.1	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).
17.1	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).
16.1	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
1.1	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
10.1	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.
1.1	22
6.1	23	== Création des logs ==
1.1	24
18.2	25	1. (((
	26	Créez un fichier log4j2_agent.properties dans /etc/digdash avec la configuration suivante :
1.1	27
10.1	28	{{code language="shell"}}
1.1	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
10.1	39	appender.rolling.fileName = /var/log/digdash/digdash_agent.log
	40	appender.rolling.filePattern = /var/log/digdash/digdash_agent-%i.log.gz
1.1	41	appender.rolling.layout.type=PatternLayout
10.1	42	appender.rolling.layout.pattern = %d %-5p [agent] [%t] (%F:%L) - %m%n
1.1	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}}
18.2	64	)))
1.1	65
18.1	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.
1.1	67
6.1	68	(% start="2" %)
18.2	69	1. (((
	70	Ajoutez la ligne suivante dans /etc/digdash/digdash.properties pour que DigDash puisse lire la configuration des logs :
1.1	71
2.2	72	{{code}}
	73	agent.ddlog4j.properties.file=/etc/digdash/log4j2_agent.properties
	74	{{/code}}
18.2	75	)))
1.1	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
18.2	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}}
1.1	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]]
18.2	84	1. (((
	85	Ajoutez votre clé API dans /etc/digdash/digdash.properties :
1.1	86
2.2	87	{{code}}
	88	agent.llm.apikey=<API_KEY>
	89	{{/code}}
18.2	90	)))
1.1	91
	92	== Configuration de l’application ==
	93
18.2	94	1. (((
	95	Configurez le serveur backend pour correspondre à votre environnement dans /etc/digdash/digdash.properties :
1.1	96
3.1	97	{{code}}
24.1	98	agent.digdashserver.baseurl=https://<digdash.url.externe>
	99	agent.digdashserver.domain=ddenterpriseapi
3.1	100	{{/code}}
1.1	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]]).
18.2	103	)))
1.1	104
25.1	105	== Déploiement ==
1.1	106
25.1	107	1. Déployez le serveur Tomcat.
18.2	108	1. (((
	109	Après le démarrage du serveur, exécutez la commande suivante pour vérifier que le serveur agent fonctionne :
1.1	110
	111	{{code language="shell"}}
25.1	112	curl http://localhost:8080/digdash_agent/actuator/health
1.1	113	{{/code}}
	114
	115	La réponse attendue est :
	116
3.1	117	{{code language="shell"}}
	118	{
	119	"status": "UP"
1.1	120	}
3.1	121	{{/code}}
18.2	122	)))
1.1	123
	124	(% start="2" %)
10.1	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.
1.1	126
	127	= Installation de ChromaDB =
	128
6.1	129	L’agent utilise ChromaDB, une base de données vectorielle, pour effectuer des recherches sémantiques sur les données des cubes DigDash.
1.1	130
	131	== Prérequis ==
	132
	133	* Serveur Linux
18.1	134	* Accès root au serveur
1.1	135
	136	== Installation ==
	137
18.2	138	1. (((
	139	Créez le dossier d’installation :
1.1	140
	141	{{code language="shell"}}
18.2	142	sudo mkdir /opt/chroma
1.1	143	sudo useradd -m -s /bin/bash chroma
18.2	144	sudo chown chroma:chroma /opt/chroma
1.1	145	{{/code}}
18.2	146	)))
	147	1. (((
	148	Accédez au dossier d'installation:
1.1	149
	150	{{code language="shell"}}
	151	sudo su - chroma
	152	cd /opt/chroma
	153	{{/code}}
18.2	154	)))
1.1	155
	156	(% start="3" %)
18.2	157	1. (((
25.2	158	Créez un fichier bash "install-chroma-cli.sh" via `nano install-chroma-cli.sh` en copiant-collant le script suivant:
1.1	159
	160	{{code language="shell"}}
18.1	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
1.1	198	{{/code}}
18.2	199	)))
1.1	200
18.2	201	(% start="4" %)
	202	1. (((
26.1	203	Exécutez le script "install-chroma-cli.sh" pour installer l’interface en ligne de commande Chroma (Chroma CLI) :
1.1	204
	205	{{code language="shell"}}
26.1	206	install-chroma-cli.sh
	207	{{/code}}
26.2	208	)))
	209	1. (((
	210	Créez le fichier de configuration de Chroma "config.yaml" :
26.1	211
26.2	212	{{code language="shell"}}
	213	#################
26.1	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"
18.1	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	####################
26.2	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" %)
18.1	246	1. (((
27.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. (((
18.1	255	Augmentez la limite « soft » et « hard » du nombre de fichiers ouverts à au moins 65 536.
18.2	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.
18.1	257	Vous pouvez vérifier les limites actuelles avec :
	258
	259	{{code}}
	260	ulimit -n # soft limit
	261	ulimit -Hn # hard limit
	262	{{/code}}
27.1	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}}
18.2	277	)))
27.1	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	)))
18.2	286	1. (((
27.1	287	Enfin, exécutez la commande suivante pour déployer le serveur :
18.1	288
18.2	289	{{code}}
	290	ANONYMIZED_TELEMETRY=False ./chroma run config.yaml >> chroma.log 2>&1 &
	291	{{/code}}
23.1	292	)))
18.1	293
19.1	294	(% class="wikigeneratedid" %)
20.1	295	Chroma est écrit en Rust, vous pouvez donc ajuster la verbosité des logs en définissant la variable d’environnement RUST_LOG=debug.
19.1	296
27.1	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
12.1	316	= Configuration des paramètres du serveur DigDash{{id name="Paramètres_serveur"/}} =
1.1	317
7.1	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]].
1.1	319
15.1	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.
1.1	321
1.2	322	\|=Paramètre \|=Description
15.1	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.
1.2	324	\|=URL de base du modèle de vectorisation\|(((
1.1	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/]].
1.2	326	)))
	327	\|=Clé API du modèle de vectorisation\|Vous pouvez réutiliser la clé API utilisée pour le LLM.
20.1	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]].
7.1	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.
1.3	331	\|=Forcer l'initialisation du stockage des vecteurs \|Cochez cette case pour effacer complètement la base pour l’environnement spécifié.
1.2	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]].
1.1	336
1.2	337	= Installation d’OpenWebUI (optionnelle) =
1.1	338
8.1	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
1.2	342	== Pré-requis ==
1.1	343
	344	* Serveur Linux (Ubuntu/Debian recommandé)
	345	* Python 3.11
21.1	346	* //pip// et //virtualenv//
1.1	347
	348	Installez les packages requis :
	349
2.1	350	{{code}}
	351	sudo apt update
1.1	352	sudo apt install -y python3 python3-venv python3-pip build-essential
2.1	353	{{/code}}
1.1	354
1.3	355	== Installation ==
1.1	356
27.2	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	)))
21.1	369	1. (((
28.1	370	Créez et activez un environnement virtuel dans ce dossier:
1.1	371
27.2	372	(((
1.3	373	{{code language="shell"}}
	374	python3 -m venv openwebui-venv
1.1	375	source openwebui-venv/bin/activate
1.3	376	{{/code}}
27.2	377	)))
28.2	378	)))
21.1	379	1. (((
	380	Mettez à jour pip pour éviter les problèmes de compatibilité :
1.1	381
28.1	382	(((
1.3	383	{{code}}
	384	pip install --upgrade pip
	385	{{/code}}
28.2	386	)))
	387	)))
1.1	388
29.1	389	(% start="5" %)
28.2	390	1. (((
29.1	391	Installez le package open-webui:
28.1	392
28.2	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
29.1	408	(% start="6" %)
28.2	409	1. (((
	410	(((
29.1	411	Déployez le serveur:
28.2	412
29.1	413	{{code}}
	414	nohup open-webui serve --port 5000 &
	415	{{/code}}
28.2	416
29.1	417	L’interface web devrait être disponible sur http:~/~/localhost:5000.
2.1	418	)))
28.1	419	)))
30.1	420
	421	= Ajouter un modèle LLM dans Openwebui =
	422
	423	1. Connectez-vous à http:~/~/localhost:5000 en tant qu'administrateur.
33.1	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.
30.1	428	1. Vous pouvez renseigner une API compatible OpenAI. Nous allons ajouter le modèle LLama 3.3 d'OVH:
32.1	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.
30.1	432	1. Cliquez sur le symbole "Rafraîchir". Un message devrait s'afficher validant la nouvelle connexion.
	433
31.1	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.
30.1	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.//
31.1	439	\\De même pour l'api d'OpenAI, //https:~/~/api.openai.com/v1/chat/completions// devient //https:~/~/api.openai.com/v1.//
	440	)))
30.1	441
31.1	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.

Wiki source code of Guide d'installation de DigDash Agent

Sommaire