Important
PIERRE est actuellement en version 0.27.x
(consulter les releases) avec une qualité de base de connaissances estimée à 10 %
. Par ailleurs, la documentation ci-dessous est en cours de rédaction. En cas de difficultés, créer une issue
ou envoyer un email à [email protected].
PIERRE ne connait pas les spécificités des bailleurs (ex : taille des parcs, coordonnées des agences, procédures internes, etc.). Ces éléments peuvent néanmoins lui être « enseignés en deux clics ».
PIERRE est une intelligence artificielle (IA) open source, plurilingue et multicanale au service du mouvement HLM, de ses candidats, locataires et collaborateurs.
Plus concrètement, PIERRE c'est à la fois :
-
Un chatbot (ou mieux : un resolution bot) open source — disponible sur le Web (démonstration) et par SMS — qui répond 24/7/365 à 100 % des questions de « premier niveau » des locataires et demandeurs HLM, et épaule au quotidien les collaborateurs des bailleurs sociaux (processus, données patrimoniales, aide à la rédaction, etc.).
-
Une base de connaissances en open data (consultation), utilisable indépendamment du chatbot et indispensable à la mise en oeuvre de toutes approches « Retrieval Augmented Generation » (RAG) via un LLM.
→ Télécharger une présentation de PIERRE (PDF · 2,7 Mo)
- Contribuer à PIERRE
- Fonctionnement + architecture de PIERRE
- Comment déployer PIERRE ?
- Modifier et paramétrer PIERRE (self-hosting)
- Administrer PIERRE avec une interface graphique
- License
Pour contribuer au code-source, créer une issue
dans GitHub et suivre les us et coutumes des projets open source. Les releases
de PIERRE sont consultables ici.
Lorsque l'on comprend comment fonctionne PIERRE, on comprend le rôle de la base de connaissances : elle est le coeur de l'intelligence de PIERRE et n'est — ni plus ni moins — que des fichiers-textes transformés. Par exemple, ce fichier contient tout ce que sait PIERRE sur les enquêtes-locataires.
Ce document peut être incomplet ou imprécis, et c'est tout l'enjeu que de l'améliorer, car c'est ce document qu'utilise PIERRE pour répondre aux questions sur ces sujets.
« Améliorer la base de connaissances », ce n'est donc que cela : (1) améliorer le contenu des fichiers-textes existants et (2) créer des fichiers-textes sur les thématiques manquantes.
La base de connaissances — en co-construction avec les bailleurs — couvre plusieurs thématiques :
global
: les connaissances génériques qui s'appliquent uniformément sur tout le territoire (ex : comment gérer un trouble du voisinage ? qu'est-ce que les charges locatives ?).local
: les connaissances spécifiques à un territoire donné (ex : les associations d'hébergement d'urgence dans l'Ain, les structures d'aide dans le cadre de violences conjugales dans l'Eure).org
: les connaissances relatives à un organisme HLM en particulier (ex : qu'est-ce que Grand Dijon Habitat et quelles sont les coordonnées du service-client et des agences ?).wikipedia
: des connaissances importées de Wikipédia (ex : l'histoire du logement social).
- Consulter la base de connaissances
- Et si vous identifiez un manque, une imprécision ou une erreur :
Option A : Adresser un email à [email protected]
Option B : Créer uneissue
sur GitHub (pour les connaisseurs)
Au fur et à mesure de l'amélioration de la base de connaissances, la pertinence de PIERRE s'améliorera automatiquement et profitera à l'ensemble du mouvement HLM.
- Un utilisateur pose une question à PIERRE via le web ou par SMS.
- Une première passe de LLM/IA augmente la requête initiale.
- Une deuxième passe de LLM/IA s'assure de la validité et sécurité de la requête initiale (ex : impossible d'insulter PIERRE ou d'adresser une question sans lien avec le logement).
- La requête validée et augmentée est transformée par un LLM/IA en vecteurs de valeurs numériques qui sont utilisés pour interroger les bases de connaissances de PIERRE.
- Les résultats retournés sont rerankés par un LLM/IA pour ne conserver que les plus pertinents.
- Une dernière passe de LLM/IA génère une réponse sur la base des résultats retournés, réordonnancés puis rerankés des bases de connaissances.
- La réponse est retournée quelques secondes plus tard à l'utilisateur via le web ou par SMS.
- La conversation se poursuit jusqu'à satisfaction de l'utilisateur (goto 1).
Note
On comprend ici aisément le rôle des bases de connaissances : elles sont le coeur de l'intelligence de PIERRE ou de toute IA mettant en oeuvre une approche « Retrieval Augmented Generation » (RAG) via un LLM. Ces bases de connaissances sont améliorables et personnalisables ; et c'est simplissime !
PIERRE utilise — à ce jour — plusieurs (passes de) LLM dans cet ordre successif :
-
Un modèle de génération de
textes
qui transforme la requête de l'utilisateur en une « requête augmentée » (en utilisant des techniques de type HyDE ou Stepback). -
Un modèle de génération d'
embeddings
qui transforme la « requête augmentée » en vecteurs de valeurs numériques qui sont ensuite utilisés pour rechercher les éléments de réponse les plus pertinents dans les bases de connaissances. PIERRE utilisebge-m3
, un modèle open source de la Beijing Academy of Artificial Intelligence (BAAI). -
À nouveau, un modèle de génération de
textes
configuré enreranker
qui classifie les résulats retournés par les bases de connaissances pour ne conserver que les éléments les plus pertinents en regard de la question posée par l'utilisateur. -
Un modèle de génération de
textes
qui génére les réponses textuelles aux utilisateurs en utilisant les éléments issus de (3).
Lorsque l'on auto-héberge PIERRE — et sur le principe du « Bring Your Own LLM Key/Model » (BYOK) — il est possible de choisir le modèle utilisé (Mistral, Anthropic, Cohere, OpenAI...) pour (1), (3) et (4) et ce, en modifiant le fichier de configuation (cf. infra).
Note
PIERRE propose à ce jour deux modalités d'interaction : Text-to-Text
via le Web (démonstration) ou par SMS, et Voice-to-Text
sur smartphone. À court terme, PIERRE va également investiguer une interaction Voice-to-Voice
.
En réponse au nouveau plan de numérotation mis en place par l'ARCEP en 2023 (avec l'introduction des numéros commerciaux 09 3x xx xx xx) et pour proposer aux entreprises une solution universelle pour converser avec leurs clients, les opérateurs téléphoniques français ont lançé en 2023 (déploiement opérationnel en octobre 2024) une nouvelle offre de SMS conversationnel à destination des entreprises (dite Time2chat
) qui (i) permet de s'affranchir des plateformes propriétaires (WhatsApp, Telegram, Messenger, etc.) utilisées au maximum par 50 % de la population française et (ii) une instantanéité et délivrabilité exceptionnelles (100 % des téléphones disposent nativement du SMS).
Principales caratéristiques de Time2chat
(en savoir plus via l'ARCEP ou via Orange) :
- Une conversation est une série de SMS entre une entreprise et un utilisateur.
- Elle dure maximum 24h et le nombre de SMS échangés durant cette période est illimité.
- Elle peut être initiée par l'entreprise ou l’utilisateur.
- Language:
Typescript
/Javascript
- Framework:
Hono
(withBun
runtime) - Local inference:
Ollama
- Database + Vectorstore:
SQLite3
(extended withsqlite-vec
) - Deployment:
Kamal
(withDocker
) - LLM: « Bring Your Own LLM Key/Model » (BYOK)
- GPU (optionnel):
Hugging Face
(via Inference Endpoints) - SMS:
CM
(via Time2Chat)
Déployer PIERRE sur un serveur génére des coûts :
- La location d'un serveur doté d'un
GPU
(meilleur rapport qualité/prix:GEX44
d'Hetzner) : €200 par mois - L'usage d'un LLM pour générer du texte : $0,40 (in) et $1,60 (out) / MTokens (
gpt-4.1-mini
) - (Optionnellement) La location d'un
GPU
musclé pour vectoriser vos connaissances : €10 par mois - (Optionnellement) Les conversations SMS :
– Location d'un numéro de téléphone : €10 par mois
– Envoi de SMS : €0.09 par conversation (= SMS illimités par fenêtre de 24h)
Avantages :
- Ne jamais avoir à se soucier de serveurs et d'API.
- Bénéficier 24/7/365 de la dernière version.
Adresser un email à [email protected].
Les instructions ci-après sont pour Windows
+WSL
(sous-système Windows pour Linux).
- Installer
WSL
et vérifier sa bonne installation (instructions). - Installer
Ollama
(≥0.6.5
) et vérifier sa bonne installation (instructions), puis saisir dans votre terminalollama pull bge-m3
pour télécharger le modèlebge-m3
. - Installer
Bun
(≥1.2.10
) et vérifier sa bonne installation (instructions). - Installer
SQlite3
et vérifier sa bonne installation (instructions). - Forker/cloner le présent dépôt.
- Lancer
bun install
dans votre terminal pour installer les dépendances. - Renommer le fichier
.env.example
en.env.production
et compléter le. - Ouvrir deux shell et exécuter dans le premier
ollama serve
etbun dev
dans le second. - Et voilà : PIERRE est accessible à http://localhost:3000 et répond à vos questions !
Note
La vitesse d'inférence peut être faible si votre processeur est peu puissant.
Pour déployer PIERRE sur un serveur, il est indispensable d'être parvenu à le faire fonctionner en local.
- Installer
Docker Desktop
et le lancer (instructions).Docker
gérera la conteneurisation. - Lancer
gem install kamal
pour installerKamal
(≥2.6.0
) qui gérera le déploiement (instructions). - Disposer d'un compte
GitHub
et générer une clef.GitHub
sera le registre de conteneurs lors du déploiement. - Disposer d'un VPS avec
GPU
(par exempleGEX44
d'Hetzner) et être en capacité de s'y connecter viassh
(avec une clef ou mot de passe). - Finaliser les modifications du fichier
.env.production
que vous avez créé précédemment. - Saississez dans votre terminal
bun --env-file=.env.production run kamal setup
. - Saississez dans votre terminal
bun --env-file=.env.production run kamal server exec "docker exec ollama ollama pull bge-m3"
. - Et voilà, PIERRE est accessible à l'adresse URL de votre serveur (il faut parfois attendre une dizaine de minutes afin que les certificats SSL soient générés).
- Étapes suivantes (optionnelles et décrites ci-dessous) :
– Créer une seconde instance (de tests) de PIERRE sur le même serveur
– Personnaliser PIERRE
– Faire fonctionner PIERRE par SMS
– Afficher PIERRE sur votre site internet ou extranet-locataire
[!NOTE] > TODO: Détailler la procédure permettant l'usage du
GPU
parDocker/Ollama
: se connecter viassh
au serveur,curl -fsSL https://ollama.com/install.sh | sh
, puis suivre les recommandations disponibles ici.
PIERRE — et notamment sa base de connaissances — évolue régulièrement et suit la convention semver
. Pour le mettre à jour :
- Saisir
bun pierre:version
pour connaitre la dernière version disponible. - Consulter les releases pour connaitre les modifications et éventuels breaking changes.
- Mettre à jour votre fork/clone.
- Saisir
bun pierre:config
pour vous assurer queconfig.ts
est correctement paramétré. - Saisir
bun --env-file=.env.production run kamal deploy
dans votre terminal (ou le raccourcibun prod:deploy
).
Pour tester en conditions réelles les mises à jour et nouveautés de PIERRE, le plus simple est de déployer une seconde instance de PIERRE sur votre serveur de production.
- Dupliquer
.env.production
en.env.staging
et modifier le (a priori uniquement leSERVICE
etHOST
). - Lancer
bun --env-file=.env.staging run kamal setup
pour déployer la première fois. - Lancer
bun --env-file=.env.staging run kamal deploy
pour redéployer (ou le raccourcibun staging:deploy
).
Note
Dans les instructions ci-dessous, nous considérons un bailleur social fictif nommé Pierre Habitat
dont le site institutionnel est accessible à pierre-habitat.fr
et qui a déployé sa propre version de PIERRE à l'adresse/IP 180.81.82.83
.
- Dans le répertoire
./assets
, supprimer les répertoiresdemo_client
,demo_team
ettesting_purpose_1
,testing_purpose_2
, puis dupliquer le dossierdefault
et le nommerpierre-habitat
. Les consignes suivantes s'appliquent à ce nouveau répertoire. - Supprimer les sous-répertoires
/dist
,/files
,/scripts
,/tailwind
. - Créer une icône
system.svg
et remplacer la précédente. Cette icône est celle qui apparait dans l'interface du chatbot (au dessus de « Bonjour 👋 »). - Générer les icônes qui permettront d'ajouter votre chatbot sur l'écran d'accueil des smartphones de vos utilisateurs et remplacer celles dans le dossier
icons
(les icônes Windows ne sont pas nécessaires). Conservez la structure du répertoire et le nommage des fichiers (automatique). - Modifier
config.ts
:
–id
avecpierre-habitat
–greeting
qui est le message d'accueil de votre chatbot
–examples
qui sont les exemples proposés après votre message d'accueil
–disclaimer
qui est le message s'affichant après chaque réponse générée (ex : Une IA peut se tromper, vérifier les informations.). - Modifier dans
manifest.json
:
–short_name
par le nom souhaité de votre chatbot
–start_url
parhttps://180.81.82.83/?config=pierre-habitat
- Et voilà, votre chabot personnalisé est disponible à http://localhost:3000/?config=pierre-habitat
Tip
Pour vous assurer que config.ts
est correctement paramétré, notamment lors des montées de version qui peuvent en modifier la structure, lancer bun pierre:config
.
Si vous avez à ce stade personnalisé visuellement votre chatbot (cf. supra), et bien qu'il affiche des icônes et les salutations de votre organisme, il ne se présente PAS encore comme le chatbot de votre organisme (essayez en lui demandant qui il est !).
Pour modifier cela, modifier dans le fichier config.ts
:
persona
qui définit l'identité et le rôle du chatbotaudience
qui définit le contexte dans lequel le chabot doit considérer son interlocuteurguidelines
qui définit la façon dont le chatbot répond aux questions
Note
Pour faciliter la lecture et manipulation du fichier config.ts
dans VSCode, ou plus généralement activer le word wrap : utilisez le raccourci Alt
+ z
(Windows) ou ⌥
+ z
(Mac).
Important
Il est très fortement recommandé de disposer d'une version fonctionnelle de PIERRE en local avant de changer le modèle de langage (LLM) et ce, pour être en mesure d'effectuer des tests. En effet, modifier le modèle de langage peut avoir quelques effets sur la qualité et vitesse des réponses de PIERRE.
Pour modifier les modèles, il suffit de :
- Modifier
models
dans votre fichierconfig.ts
par la valeur souhaitée. Il est fortement recommandé d'utiliser un modèle peu cher pour lereranker
qui est consommateur de tokens (ex :gpt-4o-mini-2024-07-18
d'OpenAI ou équivalent). - Renseigner la clef d'API correspondante dans les variables d'environnement (
.env.production
).
PIERRE permet – à ce stade – l'usage des principaux modèles de langage, à savoir : Anthropic
, Cohere
, Google
, Meta
, Mistral
, et OpenAI
.
Pour accélérer l'inférence, c'est-à-dire la vitesse des réponses, il est possible de faire appel à des fournisseurs tels que Cerebras
, Groq
ou encore TogetherAI
.
Important
Pour installer PIERRE sur votre site internet, il est indispensable de disposer d'une version fonctionnelle de PIERRE installée sur un VPS.
<script crossorigin="anonymous" src="http://180.81.82.83/assets/default/dist/js/widget.js"></script>
<p
id="pierre-ia"
data-url="http://180.81.82.83"
data-configuration="pierre-habitat"
style="
right: 20px;
bottom: 20px;
color: #000;
font-size: 30px;
font-weight: bold;
padding: 2px 12px;
background-color: #fff;
border-radius: 8px;
border: 4px solid black;
box-shadow: 2px 2px 6px #00000080;"
>
iA?
</p>
avec :
iA?
: le nom d'affichage du bouton (libre à vous de le modifier)style
: le style CSS du bouton (libre à vous de le modifier)180.81.82.83
dans l'URL du script le domaine/IP du serveur où le script est accessibledata-url
: le domaine/IP (sans slash de fin) du serveur où PIERRE est accessibledata-configuration
: le nom de domaine de votre organisme qui est également le nom du répertoire que vous avez créé plus tôt dans./assets
(cf. supra) oudefault
pour la version par défaut.
<iframe
id="pierre"
title="PIERRE - l'IA de Mouvement HLM"
style="..."
width="450"
height="620"
src="http://180.81.82.83/?config=pierre-habitat"
>
</iframe>
avec :
style
: le style CSS de l'iframe (libre à vous de le modifier)src
: l'URL d'accès à PIERRE (libre à vous de modifierconfig
)
- Obtenir un numéro de téléphone compatible
- Paramétrer votre webhook
- Modifier
phone
dans votre fichierconfig.ts
avec votre numéro de téléphone
TODO/À FINALISER
Si vous hébergez PIERRE :
- Rendez-vous à l'adresse https://180.81.82.83/a (à remplacer par votre domaine/IP).
- Saisissez (la première fois)
[email protected]
et le mot de passe contenu dans la variable d'environnementAUTH_PASSWORD
. - Vous pouvez désormais créer autant d'utilisateurs que nécessaire (n'oubliez pas de transmettre les mots de passe !) qui pourront modifier les utilisateurs ou l'encyclopédie, consulter les conversations ou les statistiques...
PIERRE dispose — en fait — de deux bases de connaissances :
-
Une base (dite
communautaire
) qui correspond aux connaissances partagées universellement au sein du mouvemement HLM (ex : comment déposer une demande de logement social, qu'est-ce que le SLS, les associations d'hébergement d'urgence dans le Vaucluse, etc.). -
Une base (dite
propriétaire
) qui correspond aux connaissances créées par un organisme HLM hébergeant sa propre version de PIERRE et qu'il ne souhaite pas partager aveccommunautaire
ou qu'il souhaite faire apprendre en pleine autonomie à PIERRE (ex : des procédures internes).
Comment faire apprendre des connaissances à PIERRE ?
- Se connecter à https://180.81.82.83/a, puis cliquer sur
Encyclopédie
. - Télécharger
_metadata.xlsx
, le compléter scrupuleusement et le ré-uploader avec les fichiers associés. Seuls les.docx
(Word),.xlsx
(Excel) et.md
(Markdown) sont acceptés. - Indispensable : Configurer
config.ts
de manière à permettre l'utilisation des connaissancesproprietary
et le protéger s'il utilise des donnéesprivées
/private
. - C'est tout. Toutes les nuits aux alentours de 4h du matin, la base de connaissances sera automatiquement reconstruite.
[IMPORTANT] Comment réduire la durée de reconstruction de votre base de connaissances ?
La reconstruction de votre base de connaissances peut être très longue (plusieurs heures) selon la quantité de données à traiter (= transformer vos données en vecteurs de valeurs numériques).
Pour savoir si cette durée est acceptable (PIERRE n'a en effet plus connaissance de vos données durant le processus), il convient à ce stade d'essayer de générer votre base de connaissances en local tout en consultant les logs. Si la durée de reconstruction n'est pas acceptable, il est nécessaire de disposer d'un GPU
d'appoint pour cette opération.
Note
PIERRE mettra prochainement en place un moyen simple de savoir si votre base de connaissances nécessite l'usage d'un GPU
.
- Option 1 : Adresser un email à [email protected] pour obtenir directement et simplement un
endpoint
ettoken
à renseigner dansenv.production
- Option 2 : Louer pendant 5-15 minutes chaque jour un
GPU
(env. €10/mois). Pour se faire :- Créer un compte
Hugging Face
(🇫🇷) et ajouter un moyen de paiement - Créer un
endpoint
d'inférencebge-m3
en suivant ce lien :- Endpoint name: à votre convenance et sans importance
- Hardware configuration:
Nvidia A10G
(ou équivalent) localisé au plus proche (Irlande) - Security Level:
Protected
(il vous faudra créer un token) - Autoscaling: vous assurer qu'il affiche
scale-to-zero after 15 min
- Cliquer sur
Create endpoint
.
- Créer un
token
pour pouvoir utiliser leendpoint
:- Se rendre sur https://huggingface.co/settings/tokens et
Create new token
- Token name: à votre convenance
- Cocher
Make calls to your Inference Endpoints
- Cliquer sur
Create token
- Se rendre sur https://huggingface.co/settings/tokens et
- Renseigner
HUGGINGFACE_ENDPOINT
etHUGGINGFACE_TOKEN
dans.env.production
ou.env.staging
avec les valeurs correspondantes.
- Créer un compte
Le code-source du présent dépôt est sous license GNU Affero General Public License Version 3. La base de connaissances (dossier /knowledge
) est sous license Creative Commons BY-NC-SA 4.0.
Copyright (c) 2024-aujourd'hui, Charles-Henri Arnould/BECKREL ([email protected]) et les contributeurs.