This repository includes code for the ConvXAI paper accepted in CSCW 2023 Demo:
Bibtex for citations:
@article{shen2023convxai,
title={ConvXAI: Delivering Heterogeneous AI Explanations via Conversations to Support Human-AI Scientific Writing},
author={Shen, Hua and Huang, Chieh-Yang and Wu, Tongshuang and Huang, Ting-Hao'Kenneth'},
journal={arXiv preprint arXiv:2305.09770},
year={2023}
}
Create a convxai
virtual environment, activate the environment, and install the libraries for ConvXAI as below.
$conda create --name convxai python=3.7
$conda activate convxai
$pip install -r requirements.txt
$conda install -c conda-forge git-lfs # to support github large file upload
$conda install -c conda-forge jsonnet # to support allennlp package
ConvXAI system is built upon MongoDB database. Please install MongoDB on your node and ensure you have the database access to connect and manage the data.
Then refer to the Config Files Setup section to set up mongodb_config.yml
.
Set up the configs files of ConvXAI under path convxai/configs
:
- mongodb_config.yml: You can either deploy both server and client in the same machine setting
mongo_host: localhost
, or you can deply them on two machines and set your client machine's IP address as mongo_host, e.g.,mongo_host: "157.230.188.155""
.
mongo_host: localhost
mongo_db_name: convxai
Set up the path for both scientific writing models and the pre-trained checkpoints of conversational XAI models.
Scientific writing models: ConvXAI involves a SciBERT-based writing structure model (i.e., diversity model) and a GPT-based writing style model (i.e., quality model).
The diversity model and quality model are both accessible from the Huggingface Hub and will be downloaded with below script.
scientific_writing:
diversity_model_dir: "huashen218/convxai-diversity-model"
quality_model_dir: "huashen218/convxai-quality-model"
Conversational XAI models: Please specify the path_of_convxai/
in the checkpoints_root_dir
shown below.
For instance, a user clone the convxai repo under /home/huashen/workspace/projects/
path, then the path_of_convxai
is /home/hqs5468/hua/workspace/projects/convxai
.
conversational_xai:
intent_model: "path_of_convxai/checkpoints/xai_models/xai_user_intent_model/intent-deberta-v3-xsmall"
checkpoints_root_dir: "path_of_convxai/checkpoints/xai_models/"
xai_example_dir:
xai_emample_embeddings_dir:
ACL: "xai_example_embeddings/diversity_model_ACL_embeddings.h5"
CHI: "xai_example_embeddings/diversity_model_CHI_embeddings.h5"
ICLR: "xai_example_embeddings/diversity_model_ICLR_embeddings.h5"
xai_emample_texts_dir:
ACL: "xai_example_embeddings/diversity_model_ACL_texts.h5"
CHI: "xai_example_embeddings/diversity_model_CHI_texts.h5"
ICLR: "xai_example_embeddings/diversity_model_ICLR_texts.h5"
xai_writing_aspect_prediction_dir: "/xai_writing_aspect_prediction"
xai_counterfactual_dir: "xai_writing_aspect_prediction/"
- service_config.yml: You can keep this file unchanged unless you want to change the
relative paths
or theclass names
inside ofservice_config.yml
.
You can skip this step if you are going to use the default datasets and models of ConvXAI system, because ConvXAI repository is self-contained. It includes:
- CIA dataset: collects paper abstracts from 2018-2022 in CHI, ICLR and ACL conferences. CIA dataset is for finetuning GPT-based model to generate scientific style quality scores. Data path is:
data/CIA
. - XAI models: contains pretrained checkpoints supporting conversational XAI modules to generate AI comments and explanations on-the-fly. Particularly, the
checkpoints/
include:xai_writing_aspect_prediction/
: enables xai_models to generate AI comments related to the submitted paper's apsect label distribution.xai_example_embeddings/
: saves embeddings from CIA datasets to enable xai_models to generate example-based explanations. The method is NN_DOT method described in this paper.xai_counterfactual_explainer_models/
: contains MiCE counterfactual model pre-trained on our writing structure model.
You can also train your own writing and XAI models from scratch. Please refer to the ConvXAI Tutorial for details.
You can deploy the ConvXAI server (i.e., deep learning server for writing and XAI models) and client (i.e., UI web service) either on the same node OR on two different nodes.
Then please run server and client on two different terminals as described below.
One terminal runs the server with: $bash path_of_convxai/convxai/runners/main_server.sh
.
Please specify the path_of_convxai/
inside the main_server.sh shown below.
You can also change --port
if needed.
#!/usr/bin/env bash
set -x;
set -e;
export PYTHONPATH=path_of_convxai/
RUN_SERVICE_DIR="path_of_convxai/convxai";
CUDA_VISIBLE_DEVICES=0 python $RUN_SERVICE_DIR/services/run_server/run.py \
--config-path $RUN_SERVICE_DIR/configs/service_config.yml \
--port 10020;
The other terminal runs the client with: $bash path_of_convxai/convxai/runners/main_client.sh
. Please specify the path_of_convxai/
similarly.
#!/usr/bin/env bash
set -x;
set -e;
export PYTHONPATH=path_of_convxai/
RUN_SERVICE_DIR="/path_of_convxai/convxai/services/web_service";
python $RUN_SERVICE_DIR/web_server.py
Then check the client terminal output, such as - * Running on http://157.230.188.155:8080/ (Press CTRL+C to quit)
, to open the browser link to interact with ConvXAI user interface.
Have fun chatting with ConvXAI robot for improving your paper writing!