Home

Awesome

Note on the top: the project is unmaintained.

Transformer-based dialog models work better and we recommend using them instead of RNN-based CakeChat. See, for example https://github.com/microsoft/DialoGPT

CakeChat: Emotional Generative Dialog System

CakeChat is a backend for chatbots that are able to express emotions via conversations.

CakeChat representation

CakeChat is built on Keras and Tensorflow.

The code is flexible and allows to condition model's responses by an arbitrary categorical variable. For example, you can train your own persona-based neural conversational model<sup>[1]</sup> or create an emotional chatting machine<sup>[2]</sup>.

Main requirements

Table of contents

  1. Network architecture and features
  2. Quick start
  3. Setup for training and testing
    1. Docker
      1. CPU-only setup
      2. GPU-enabled setup
    2. Manual setup
  4. Getting the pre-trained model
  5. Training data
  6. Training the model
    1. Fine-tuning the pre-trained model on your data
    2. Training the model from scratch
    3. Distributed train
    4. Validation metrics calculation
    5. Testing the trained model
  7. Running CakeChat server
    1. Local HTTP-server
      1. HTTP-server API description
    2. Gunicorn HTTP-server
    3. Telegram bot
  8. Repository overview
    1. Important tools
    2. Important configuration settings
  9. Example use cases
  10. References
  11. Credits & Support
  12. License

Network architecture and features

Network architecture

Model:

Word embedding layer:

Decoding

Metrics:

Quick start

In case you are familiar with Docker here is the easiest way to run a pre-trained CakeChat model as a server. You may need to run the following commands with sudo.

CPU version:

docker pull lukalabs/cakechat:latest && \

docker run --name cakechat-server -p 127.0.0.1:8080:8080 -it lukalabs/cakechat:latest bash -c "python bin/cakechat_server.py"

GPU version:

docker pull lukalabs/cakechat-gpu:latest && \

nvidia-docker run --name cakechat-gpu-server -p 127.0.0.1:8080:8080 -it lukalabs/cakechat-gpu:latest bash -c "CUDA_VISIBLE_DEVICES=0 python bin/cakechat_server.py"

That's it! Now test your CakeChat server by running the following command on your host machine:

python tools/test_api.py -f localhost -p 8080 -c "hi!" -c "hi, how are you?" -c "good!" -e "joy"

The response dict may look like this:

{'response': "I'm fine!"}

Setup for training and testing

Docker

Docker is the easiest way to set up the environment and install all the dependencies for training and testing.

CPU-only setup

Note: We strongly recommend using GPU-enabled environment for training CakeChat model. Inference can be made both on GPUs and CPUs.

  1. Install Docker.

  2. Pull a CPU-only docker image from dockerhub:

docker pull lukalabs/cakechat:latest
  1. Run a docker container in the CPU-only environment:
docker run --name <YOUR_CONTAINER_NAME> -it lukalabs/cakechat:latest

GPU-enabled setup

  1. Install nvidia-docker for the GPU support.

  2. Pull GPU-enabled docker image from dockerhub:

docker pull lukalabs/cakechat-gpu:latest
  1. Run a docker container in the GPU-enabled environment:
nvidia-docker run --name <YOUR_CONTAINER_NAME> -it cakechat-gpu:latest

That's it! Now you can train your model and chat with it. See the corresponding section below for further instructions.

Manual setup

If you don't want to deal with docker, you can install all the requirements manually:

pip install -r requirements.txt -r requirements-local.txt

NB:

We recommend installing the requirements inside a virtualenv to prevent messing with your system packages.

Getting the pre-trained model

You can download our pre-trained model weights by running python tools/fetch.py.

The params of the pre-trained model are the following:

Training data

The model was trained on a preprocessed Twitter corpus with ~50 million dialogs (11Gb of text data). To clean up the corpus, we removed

We used our emotions classifier to label each utterance with one of the following 5 emotions: "neutral", "joy", "anger", "sadness", "fear", and used these labels during training. To mark-up your own corpus with emotions you can use, for example, DeepMoji tool.

Unfortunately, due to Twitter's privacy policy, we are not allowed to provide our dataset. You can train a dialog model on any text conversational dataset available to you, a great overview of existing conversational datasets can be found here: https://breakend.github.io/DialogDatasets/

The training data should be a txt file, where each line is a valid json object, representing a list of dialog utterances. Refer to our dummy train dataset to see the necessary file structure. Replace this dummy corpus with your data before training.

Training the model

There are two options:

  1. training from scratch
  2. fine-tuning the provided trained model

The first approach is less restrictive: you can use any training data you want and set any config params of the model. However, you should be aware that you'll need enough train data (~50Mb at least), one or more GPUs and enough patience (days) to get good model's responses.

The second approach is limited by the choice of config params of the pre-trained model – see cakechat/config.py for the complete list. If the default params are suitable for your task, fine-tuning should be a good option.

Fine-tuning the pre-trained model on your data

  1. Fetch the pre-trained model from Amazon S3 by running python tools/fetch.py.

  2. Put your training text corpus to data/corpora_processed/train_processed_dialogs.txt. Make sure that your dataset is large enough, otherwise your model risks to overfit the data and the results will be poor.

  3. Run python tools/train.py.

    1. The script will look for the pre-trained model weights in results/nn_models, the full path is inferred from the set of config params.
    2. If you want to initialize the model weights from a custom file, you can specify the path to the file via -i argument, for example, python tools/train.py -i results/nn_models/my_saved_weights/model.current.
    3. Don't forget to set CUDA_VISIBLE_DEVICES=<GPU_ID> environment variable (with <GPU_ID> as in output of nvidia-smi command) if you want to use GPU. For example, CUDA_VISIBLE_DEVICES=0 python tools/train.py will run the train process on the 0-th GPU.
    4. Use parameter -s to train the model on a subset of the first N samples of your training data to speed up preprocessing for debugging. For example, run python tools/train.py -s 1000 to train on the first 1000 samples.

Weights of the trained model are saved to results/nn_models/.

Training the model from scratch

  1. Put your training text corpus to data/corpora_processed/train_processed_dialogs.txt.

  2. Set up training parameters in cakechat/config.py. See configuration settings description for more details.

  3. Consider running PYTHONHASHSEED=42 python tools/prepare_index_files.py to build the index files with tokens and conditions from the training corpus. Make sure to set PYTHONHASHSEED environment variable, otherwise you may get different index files for different launches of the script. Warning: this script overwrites the original tokens index files data/tokens_index/t_idx_processed_dialogs.json and data/conditions_index/c_idx_processed_dialogs.json. You should only run this script in case your corpus is large enough to contain all the words that you want your model to understand. Otherwise, consider fine-tuning the pre-trained model as described above. If you messed up with index files and want to get the default versions, delete your copies and run python tools/fetch.py anew.

  4. Consider running python tools/train_w2v.py to build w2v embedding from the training corpus. Warning: this script overwrites the original w2v weights that are stored in data/w2v_models. You should only run this script in case your corpus is large enough to contain all the words that you want your model to understand. Otherwise, consider fine-tuning the pre-trained model as described above. If you messed up with w2v files and want to get the default version, delete your file copy and run python tools/fetch.py anew.

  5. Run python tools/train.py.

    1. Don't forget to set CUDA_VISIBLE_DEVICES=<GPU_ID> environment variable (with <GPU_ID> as in output of nvidia-smi command) if you want to use GPU. For example CUDA_VISIBLE_DEVICES=0 python tools/train.py will run the train process on the 0-th GPU.
    2. Use parameter -s to train the model on a subset of the first N samples of your training data to speed up preprocessing for debugging. For example, run python tools/train.py -s 1000 to train on the first 1000 samples.

  6. You can also set IS_DEV=1 to enable the "development mode". It uses a reduced number of model parameters (decreased hidden layer dimensions, input and output sizes of token sequences, etc.) and performs verbose logging. Refer to the bottom lines of cakechat/config.py for the complete list of dev params.

Weights of the trained model are saved to results/nn_models/.

Distributed train

GPU-enabled docker container supports distributed train on multiple GPUs using horovod.

For example, run python tools/distributed_train.py -g 0 1 to start training on 0 and 1 GPUs.

Validation metrics calculation

During training the following datasets are used for validations metrics calculation:

The metrics are stored to cakechat/results/tensorboard and can be visualized using Tensorboard. If you run a docker container from the provided CPU or GPU-enabled docker image, tensorboard server should start automatically and serve on http://localhost:6006. Open this link in your browser to see the training graphs.

If you installed the requirements manually, start tensorboard server first by running the following command from your cakechat root directory:

mkdir -p results/tensorboard && tensorboard --logdir=results/tensorboard 2>results/tensorboard/err.log &

After that proceed to http://localhost:6006.

Testing the trained model

You can run the following tools to evaluate your trained model on test data(dummy example, replace with your data):

Running CakeChat server

Local HTTP-server

Run a server that processes HTTP-requests with given input messages and returns response messages from the model:

python bin/cakechat_server.py

Specify CUDA_VISIBLE_DEVICES=<GPU_ID> environment variable to run the server on a certain GPU.

Don't forget to run python tools/fetch.py prior to starting the server if you want to use our pre-trained model.

To make sure everything works fine, test the model on the following conversation

– Hi, Eddie, what's up?
– Not much, what about you?
– Fine, thanks. Are you going to the movies tomorrow?

by running the command:

python tools/test_api.py -f 127.0.0.1 -p 8080 \
    -c "Hi, Eddie, what's up?" \
    -c "Not much, what about you?" \
    -c "Fine, thanks. Are you going to the movies tomorrow?"

You should get a meaningful answer, for example:

{'response': "Of course!"}

HTTP-server API description

/cakechat_api/v1/actions/get_response

JSON parameters are:

ParameterTypeDescription
contextlist of stringsList of previous messages from the dialogue history (max. 3 is used)
emotionstring, one of enumOne of {'neutral', 'anger', 'joy', 'fear', 'sadness'}. An emotion to condition the response on. Optional param, if not specified, 'neutral' is used
Request
POST /cakechat_api/v1/actions/get_response
data: {
 'context': ['Hello', 'Hi!', 'How are you?'],
 'emotion': 'joy'
}
Response OK
200 OK
{
  'response': 'I\'m fine!'
}

Gunicorn HTTP-server

We recommend using Gunicorn for serving the API of your model at production scale.

  1. Install gunicorn: pip install gunicorn

  2. Run a server that processes HTTP-queries with input messages and returns response messages of the model:

cd bin && gunicorn cakechat_server:app -w 1 -b 127.0.0.1:8080 --timeout 2000

Telegram bot

You can run your CakeChat model as a Telegram bot:

  1. Create a telegram bot to get bot's token.
  2. Run python tools/telegram_bot.py --token <YOUR_BOT_TOKEN> and chat with it on Telegram.

Repository overview

Important tools

Important configuration settings

All the configuration parameters for the network architecture, training, predicting and logging steps are defined in cakechat/config.py. Some inference parameters used in an HTTP-server are defined in cakechat/api/config.py.

Example use cases

By providing additional condition labels within dataset entries, you can build the following models:

To make use of these extra conditions, please refer to the section Training the model. Just set the "condition" field in the training set to one of the following: persona ID, emotion or topic label, update the index files and start the training.

References

Credits & Support

CakeChat is developed and maintained by the Replika team:

Nicolas Ivanov, Michael Khalman, Nikita Smetanin, Artem Rodichev and Denis Fedorenko.

Demo by Oleg Akbarov, Alexander Kuznetsov and Vladimir Chernosvitov.

All issues and feature requests can be tracked here – GitHub Issues.

License

© 2019 Luka, Inc. Licensed under the Apache License, Version 2.0. See LICENSE file for more details.