Installation Tock

La page architecture présente l’architecture fonctionnelle et technique Tock, le rôle des différents composants ainsi que les différents modes de déploiement.

Ce chapitre présente les différentes options d’installation de Tock. En particulier, il s’agit d’évoquer le cas d’une installation en production ainsi que partager quelques retours d’expérience sur les performances, la résilience, la capacité de Tock à monter en charge, les déploiementsde type Cloud, la supervision, etc.

Si vous cherchez seulement à tester Tock avec des données non sensibles, vous pouvez préférer utiliser la plateforme de démonstration Tock.

Installation avec Docker

Le dépôt tock-docker fournit une implémentation complète de Tock pour les technologies Docker et Docker Compose. Tock est composé par défaut de plusieurs conteneurs/images Docker et d’une base de donnée MongoDB.

Pour en savoir plus sur l’installation de Tock avec Docker, voir les instructions du dépôt tock-docker.

Le guide déployer Tock avec Docker dans la section Découvrir Tock donne un exemple de déploiement d’une plateforme complète en quelques minutes avec une empreinte minimale en utilisant Docker et Docker Compose. Cependant, cette méthode n’est pas envisageable pour un déploiement pérenne comme une plateforme de production.

Si vous souhaitez utiliser Docker Compose en production, merci de lire cet article et de revoir la configuration, qui est uniquement donnée dans le projet tock-docker à titre d’exemple. En particulier, la configuration des instances MongoDB doit être revue attentivement.

Installation sans Docker

Il est tout à fait possible d’installer Tock sans utiliser Docker. En analysant les descripteurs fournis dans tock-docker (ie. les fichiers pom.xml, les Dockerfile et docker-compose.yml) on peut facilement concevoir une installation sans Docker.

Hormis la base de données MongoDB, tous les autres composants peuvent démarrer comme des applications Java/JVM classiques, par exemple :

• directement en ligne de commande
• au sein d’un serveur d’applications Java
• depuis un outil de développement intégré (IDE)
• etc.

Pour en savoir plus sur les paramètres de lancement des différents composants Tock, vous pouvez vous inspirer des commandes présentes dans les descripteurs de tock-docker ou encore des configurations fournies pour IntelliJ
(voir ci-dessous).

Ligne de commande

Une technique consiste à rassembler les différentes dépendances et archives JAR dans un dossier puis démarrer le composant ou l’application avec une commande Java classique.

Pour exemple, le descripteur du composant tock-docker-nlp-api (voir pom.xml) avec la commande suivante :

java $JAVA_ARGS -Dfile.encoding=UTF-8 -cp '/maven/*' ai.tock.nlp.api.StartNlpServiceKt

JAR exécutable

Ce n’est pas la technique que nous recommandons, mais il est possible d’exécuter un JAR unique contenant toutes les dépendances (parfois appelé “fat JAR”). Voici comment procéder pour créer un tel JAR, en reprenant l’exemple du composant Tock NLP-API.

Dans le POM du composant (nlp/api/service/pom.xml), ajoutez la déclaration suivante :

    <build>
        <plugins>
            <plugin>
                <artifactId>maven-assembly-plugin</artifactId>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>single</goal>
                        </goals>
                        <configuration>
                            <archive>
                                <manifest>
                                    <mainClass>ai.tock.nlp.api.StartNlpServiceKt</mainClass>
                                </manifest>
                            </archive>
                            <descriptors>
                                <descriptor>src/main/assembly/jar-with-dependencies.xml</descriptor>
                            </descriptors>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

Créez également un descripteur d’archive nlp/api/service/src/main/assembly/jar-with-dependencies.xml avec le contenu suivant :

<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.0.0 http://maven.apache.org/xsd/assembly-2.0.0.xsd">
    <id>jar-with-dependencies</id>
    <formats>
        <format>jar</format>
    </formats>
    <includeBaseDirectory>false</includeBaseDirectory>
    <dependencySets>
        <dependencySet>
            <outputDirectory>/</outputDirectory>
            <useProjectArtifact>true</useProjectArtifact>
            <unpack>true</unpack>
            <scope>runtime</scope>
        </dependencySet>
    </dependencySets>
    <containerDescriptorHandlers>
        <containerDescriptorHandler>
            <!-- Merge service implementations from dependencies -->
            <handlerName>metaInf-services</handlerName>
        </containerDescriptorHandler>
    </containerDescriptorHandlers>
</assembly>

Pour finir, construisez l’archive “jar-with-dependencies” avec mvn package.

Dans un IDE

Pour le développement, il est possible d’exécuter les différents composants Tock (NLU, Studio, bot…) depuis un IDE comme IntelliJ, Eclipse ou Visual Studio Code par exemple.

Outre les images Docker, des configurations pour IntelliJ sont fournies avec les sources de Tock :

• Configuration Services Tock Studio complets (Bot + NLP) / BotAdmin
• Configuration Services Tock Studio (NLP uniquement) / Admin
• Configuration Service NLP / NlpService
• Configuration Service d’entités / Duckling
• Configuration Service construction des modèles NLP / BuildWorker
• Configuration Service de compilation des scripts / KotlinCompilerServer

Enfin pour lancer les interfaces utilisateur (Tock Studio), les commandes sont décrites dans le lien suivant :

• Instructions Interface Tock Studio complète (Bot + NLP)

Base de données MongoDB

Architecture replica set

La base MongoDB doit être configurée en replica set, car Tock tire parti des change streams.

Cela implique qu’au minimum 3 noeuds doivent être déployés, ce qui améliore la résilience.

Différents scénarios sont possibles pour la base de données :

• Installer les noeuds MongoDB sur un ou plusieurs serveurs (méthode classique)
• Instancier les noeuds MongoDB avec Docker (pour des tests ou le développement en local)
• Utiliser un service cloud MongoDB en SaaS (Software-as-a-Service), par exemple MongoDB Atlas disponible sur AWS, Azure et GCP

Un tutoriel d’installation en replica set est disponible sur le site de MongoDB.

Conservation des données

Tock conserve en base différents types de données et applique des TTL (Time To Live), afin que certaines expirent et soient purgées automatiquement après un certain temps.

En pratique, les variables d’environnement et l’application des TTL ont lieu à l’initialisation des composant DAO (Data Access Object), au démarrage de Tock.

Les TTL de Tock possèdent une valeur par défaut et sont configurables au moyen de variables d’environnement. Certaines concernent un composant Tock en particulier, d’autres doivent être définies sur plusieurs composants.

Tock pouvant être utilisé comme plateforme conversationnelle complète ou uniquement la partie NLU/NLP, on indique les variables spécifiques au conversationnel (notées Bot) ou utilisables sur tous les types de plateformes (notées *).

Selon le mode de déploiement utilisé, ces variables d’environnement peuvent être ajoutées soit directement en ligne de commande, soit dans un descripteur type docker-compose.yml, dockerrun.aws.json ou autre (exemple ci-dessous).

Il est possible de supprimer automatiquement les phrases non validées (Inbox) pour certaines intentions uniquement, grâce à tock_nlp_classified_sentences_index_ttl_intent_names :

• docker-compose.yml

version: "3"
services:
  admin_web:
    image: tock/bot_admin:$TAG
    environment:
      - tock_nlp_classified_sentences_index_ttl_days=10
      - tock_nlp_classified_sentences_index_ttl_intent_names=greetings,unknown

• dockerrun.aws.json

{
  "AWSEBDockerrunVersion": 2,
  "containerDefinitions": [
    {
      "name": "admin_web",
      "image": "tock/bot_admin:${TAG}",
      "environment": [
        {
          "name": "tock_nlp_classified_sentences_index_ttl_days",
          "value": "10"
        },
        {
          "name": "tock_nlp_classified_sentences_index_ttl_intent_names",
          "value": "greetings,unknown"
        }
      ]
    }
  ]
}

Dans cet exemple, seules les phrases détectées comme intentions greetings ou unknown (mais non validées) seront supprimées au bout de 10 jours ; les autres phrases ne seront pas supprimées.

Seules les phrases validées par un utilisateur dans Tock Studio, intégrant le modèle NLP du bot, n’expirent jamais par défaut (même s’il reste possible de les supprimer du modèle via la vue Search > Status: Included in model) : il est donc important de ne pas valider des phrases comportant des données personnelles par exemple.

La conservation des données, le chiffrement et l’anonymisation sont essentiels à la protection des données, en particulier si elles sont personnelles. Pour en savoir plus, voir la section Sécurité > Données.

Composants applicatifs

Selon les composants applicatifs de Tock, obligatoires ou facultatifs, certains doivent être mono-instance et d’autres peuvent être déployés en plusieurs instances (voir la section haute disponibilité pour en savoir plus).

Pour plus de commodité, les composants ci-dessous sont nommé comme les images Docker fournies avec Tock, bien que l’utilisation de Docker ne soit pas obligatoire pour installer Tock.

Exposition réseau

Par défaut, les composants ou conteneurs de la plateforme Tock ne doivent pas être exposés à l’extérieur du VPN ou VPC. Seul le bot lui-même doit être accessible des partenaires et canaux externes auxquels on veut s’intégrer, pour le fonctionnement des WebHooks.

Bien sûr, l’implémentation du bot lui-même n’est pas fournie avec Tock (chacun implémente ses fonctionnalités propres pour son besoin).

Proxies HTTP

Les propriétés système Java https.proxyHost, http.proxyHost et http.nonProxyHosts sont la méthode recommandée pour configurer un proxy.

Packaging du bot

Un exemple de bot en mode Tock Bot intégré est disponible dans docker-compose-bot-open-data.yml.

Des exemples et indications pour packager des bots en mode Tock Bot API (WebHooks, WebSockets) seront bientôt disponibles.

Configurations minimales

L’architecture Tock est composée de plusieurs composants qui peuvent être déployés ensemble sur un même serveur, ou répartis sur plusieurs machines/instances.

Le paramètre principal à surveiller est la mémoire vive disponible.

Construction des modèles

Plus vos modèles sont importants, plus il est nécessaire d’augmenter la mémoire pour reconstruire les modèles (composant tock/build_worker).

Pour donner un ordre de grandeur, un modèle de 50000 phrases avec plusieurs intentions, comportant une vingtaine d’entités, nécessitera de provisionner environ 8 Go de RAM pour le composant tock/build_worker.

Cependant, des modèles importants mais contenant peu d’entités fonctionnent facilement avec seulement 1 Go de RAM.

Mémoire JVM & Docker

Pour garantir que les conteneurs/instances Docker ne dépassent pas la mémoire disponible, il est recommandé de limiter la mémoire des JVMs en suivant l’exemple suivant :

JAVA_ARGS=-Xmx1g -XX:MaxMetaspaceSize=256m

Optimisation machines

Il est possible d’optimiser déploiements et infrastructures en prenant en compte différents éléments comme :

• les besoins des composants respectifs en ressources machines : CPU, mémoire, disque
• l’intérêt d’avoir une ou plusieurs instances de chaque composant suivant son rôle
• les contraintes/objectifs de résilience et haute disponibilité
• les modèles de coûts, notamment chez les fournisseurs de clouds publics

Exemples

A titre indicatif, voici quelques exemples de configurations actuellement en production. Il s’agit des composants “applicatifs” de l’architecture Tock sans la base de donnée MongoDB.

Les types d’instances EC2 sont donnés à titre indicatif. Tock n’a pas de dépendance à AWS.
Pour en savoir plus voir la documentation AWS.

Modèles de taille limitée

Modèles de taille importante

Questions fréquentes

Mettre à disposition l’interface d’administration dans un sous-repertoire

Par défaut l’interface d’administration est servie à la racine (Exemple : https://[domain host]) Si vous souhaitez la rendre disponible sur un chemin relatif (https://[domain host]/tock), utilisez dans la configuration de l’image docker tock/bot_admin la variable d’environnement botadminverticle_base_href.

Par exemple : botadminverticle_base_href=tock

Pour tock/nlp_admin, il faut utiliser la propriété adminverticle_base_href.

Voir aussi…

Pour une utilisation de Tock en production, nous vous recommandons de parcourir également les pages suivantes :

• Sécurité
• Supervision
• Cloud
• Haute disponibilité