DOCSEARCHbyAlgolia
Submit Docs

UrbanGPT Documentation

repository·main·Indexed 19 days ago

https://github.com/hkuds/urbangpt

UrbanGPT is a spatio-temporal large language model implemented in PyTorch, designed for urban tasks by integrating spatio-temporal dependency encoding with instruction-tuning. It supports zero-shot generalization in urban data science and is based on Vicuna-7B-v1.5-16k. The repository includes tools for instruction tuning, evaluation, metric calculation, and deployment via a fastchat Nginx Gateway.

Tokens
4.3K
Snippets
12
Records
17
Agent score
65%

What's inside UrbanGPT

  1. Overview of UrbanGPT

    main
    UrbanGPT is a spatio-temporal large language model (LLM) implemented in PyTorch. It integrates a spatio-temporal dependency encoder with the instruction-tuning paradigm, allowing LLMs to understand complex inter-dependencies across time and space. This architecture is designed to improve prediction accuracy and generalization, particularly in zero-shot scenarios for various downstream urban tasks.

  2. Understand the purpose of the Nginx Gateway

    main

    The Nginx gateway acts as a protective layer for Gradio servers, providing several key functions:

    • Security: Acts as a firewall and reduces the attack surface by requiring only a single public port to be exposed.
    • Traffic Management: Facilitates load balancing across multiple Gradio servers and allows for dynamic mounting/unmounting of servers.
    • Resource Control: Offers additional security features like total connection limits.

  3. Prepare checkpoints and data for training UrbanGPT

    main

    Before training, you must prepare three components:

    1. Vicuna Base Model: Download Vicuna weights (v1.5 or v1.5-16k with 7B parameters). You may need to update the config.json for the v1.5-16k model.
    2. Spatio-temporal Encoder: Use the pre-trained weights located at ./checkpoints/st_encoder/pretrain_stencoder.pth.
    3. Spatio-temporal Train Data: Download the NYC taxi, bike, and crime data from the provided HuggingFace dataset and place it in ./UrbanGPT/ST_data_urbangpt/train_data.

  4. Deploy the fastchat Nginx Gateway

    main

    To deploy the gateway, follow these steps:

    1. Copy the provided nginx.conf to /etc/nginx/nginx.conf (requires sudo permissions).
    2. Configure Gradio Port: In the configuration file, locate server localhost:7860 and replace 7860 with the actual port where your Gradio web server is deployed.
    3. Configure Upstream Servers: Modify the upstream websocket block to define the Gradio servers that will sit behind the gateway.
    4. Reload Nginx: Apply the changes using the update commands.
    sudo nginx -t
sudo systemctl reload nginx

  5. Access UrbanGPT models and datasets on Hugging Face

    main

    The project provides pre-trained checkpoints and datasets via Hugging Face. Use these links to download the specific components needed for your tasks:

    • Model Checkpoints: Vicuna-7B-v1.5-16k tuned on instruction data.
    • Instruction Datasets: Portions of the instruction dataset released for evaluation.
    • Original Datasets: The original datasets used during the UrbanGPT training process.
    | 🤗 Huggingface Address | 🎯 Description |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| [https://huggingface.co/bjdwh/UrbanGPT](https://huggingface.co/bjdwh/UrbanGPT/tree/main) | It's the checkpoint of our UrbanGPT based on Vicuna-7B-v1.5-16k tuned on instruction data [train-data](https://huggingface.co/datasets/bjdwh/ST_data_urbangpt/tree/main/train_data) |
| [https://huggingface.co/datasets/bjdwh/ST_data_urbangpt](https://huggingface.co/datasets/bjdwh/ST_data_urbangpt) | We released a portion of the instruction dataset for evaluation. |
| [https://huggingface.co/datasets/bjdwh/UrbanGPT_ori_stdata](https://huggingface.co/datasets/bjdwh/UrbanGPT_ori_stdata) | We released the original dataset used in UrbanGPT. |

  6. Update the Nginx Gateway configuration

    main

    Whenever you modify /etc/nginx/nginx.conf, you must validate the syntax and reload the service to apply changes. Use these commands in order:

    1. Test configuration: sudo nginx -t (verifies the config file is valid).
    2. Reload service: sudo systemctl reload nginx (restarts the service to load the new config without dropping connections).
    3. Check status: sudo systemctl status nginx (verifies the service is active (running)).
    sudo nginx -t
sudo systemctl reload nginx
sudo systemctl status nginx

  7. Generate instructions with instruction_generate.py

    main

    Use instruction_generate.py to create specific instruction datasets for training or testing.

    Available arguments:

    • -dataset_name: The dataset to use. Options include NYC_multi (for training), and NYC_taxi, NYC_bike, NYC_crime1, NYC_crime2, or CHI_taxi (for testing).
    • -for_zeroshot: Set to True for zero-shot prediction tasks.
    • -for_supervised: Set to True for supervised prediction tasks.
    • -for_ablation: Set to True for ablation studies.

    Note: Only one of for_zeroshot, for_supervised, or for_ablation can be set to True at a time.

    # Create instruction data for training
python instruction_generate.py -dataset_name NYC_multi

# Create instruction data for NYC_taxi testing in zero-shot setting
python instruction_generate.py -dataset_name NYC_taxi -for_zeroshot True

  8. Install Nginx for the fastchat Gateway

    main

    The Nginx gateway requires Nginx to be installed on your host machine. Use the following commands based on your Linux distribution:

    Debian-based (e.g., Ubuntu):

    sudo apt update
sudo apt install nginx

    Red Hat-based (e.g., CentOS, Fedora):

    sudo yum install epel-release
sudo yum install nginx
    sudo apt update
sudo apt install nginx

  9. Evaluate UrbanGPT

    main

    Evaluation is conducted using urbangpt/eval/run_urbangpt.py. You can use either your own trained model or the released checkpoints.

    Required arguments:

    • --model-name: Path to the model checkpoint.
    • --prompting_file: Path to the prompting JSON file.
    • --st_data_path: Path to the spatio-temporal .pkl data.
    • --output_res_path: Directory to save results.
    • --start_id / --end_id: Range of IDs to evaluate.
    • --num_gpus: Number of GPUs to use.
    # Example evaluation command
output_model=./checkpoints/tw2t_multi_reg-cla-gird
datapath=./ST_data_urbangpt/NYC_taxi_cross-region/NYC_taxi.json
st_data_path=./ST_data_urbangpt/NYC_taxi_cross-region/NYC_taxi_pkl.pkl
res_path=./result_test/cross-region/NYC_taxi
start_id=0
end_id=51920
num_gpus=8

python ./urbangpt/eval/run_urbangpt.py --model-name ${output_model}  --prompting_file ${datapath} --st_data_path ${st_data_path} --output_res_path ${res_path} --start_id ${start_id} --end_id ${end_id} --num_gpus ${num_gpus}

  10. Explore Machine Learning with Embeddings in the Playground

    main

    The playground/test_embedding directory contains scripts to demonstrate various machine learning tasks using embeddings. You can use these scripts to:

    • Evaluate text similarity: See test_sentence_similarity.py.
    • Build a classifier: See test_classification.py.
    • Perform semantic search: See test_semantic_search.py.

    Prerequisites

    1. Dataset: Download the Amazon Fine Food Reviews dataset from Kaggle.
    2. OpenAI API Key: Required for comparisons against OpenAI models.

    Running the Classification Test

    To run the classification benchmark, which compares vicuna-7b, text-similarity-ada-001, and text-embedding-ada-002 and reports accuracy, execute:

    cd playground/test_embedding
python3 test_classification.py

  11. Install the UrbanGPT environment

    main

    To set up the UrbanGPT environment, create a Conda environment with Python 3.9.13 and install the required dependencies. Note that there is a known version compatibility issue between flash-attn and transformers; ensure you use the versions specified below or check the flash-attn GitHub for compatible releases.

    Follow these steps:

    1. Create and activate the Conda environment.
    2. Install Torch with CUDA 11.7.
    3. Install fschat to support the Vicuna base model.
    4. Install torch_geometric and related PyG packages.
    5. Install core libraries: deepspeed, ray, einops, wandb, flash-attn, and transformers.
    conda create -n urbangpt python=3.9.13
conda activate urbangpt

# Torch with CUDA 11.7
pip install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2

# To support vicuna base model
pip3 install "fschat[model_worker,webui]"

# To install pyg and pyg-relevant packages
pip install torch_geometric
pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.0.1+cu117.html

# Install required libraries
pip install deepspeed
pip install ray
pip install einops
pip install wandb
pip install flash-attn==2.3.5
pip install transformers==4.34.0

# Alternatively, use the requirements file
pip install -r requirements.txt