UrbanGPT：时空大型语言模型

论文《UrbanGPT：时空大型语言模型》的PyTorch实现

李中航、夏良昊、唐嘉宾、徐勇、石磊、夏龙、尹大伟、黄超* (*通讯作者)

本仓库包含UrbanGPT的代码、数据和模型权重。

🎉 新闻

🚀🔥 [2024.05] 🎯🎯📢📢 激动人心的消息！我们非常高兴地宣布，我们的🌟UrbanGPT🌟已被KDD'2024录用！🎉🎉🎉 感谢所有团队成员🤗

🎯🎯📢📢 我们在🤗Hugging Face上上传了UrbanGPT使用的模型和数据。我们强烈建议参考下表了解更多详情：

🤗 Hugging Face地址	🎯 描述
https://huggingface.co/bjdwh/UrbanGPT	这是我们基于Vicuna-7B-v1.5-16k的UrbanGPT检查点，经过train-data指令数据的微调
https://huggingface.co/datasets/bjdwh/ST_data_urbangpt	我们发布了部分用于评估的指令数据集。
https://huggingface.co/datasets/bjdwh/UrbanGPT_ori_stdata	我们发布了UrbanGPT使用的原始数据集。

[2023.02.23] 🚀🚀 发布UrbanGPT的代码。
[2023.02.29] 添加视频。
[2023.03.05] 发布完整论文。
[2023.03.11] 上传UrbanGPT的新检查点。
[2023.06.07] 发布指令生成代码和UrbanGPT使用的原始数据集。

👉 待办事项

发布基线代码。
...

简介

在这项工作中，我们提出了一个时空大型语言模型，它能够在广泛的下游城市任务中展现出卓越的泛化能力。为实现这一目标，我们提出了UrbanGPT，它无缝集成了时空依赖编码器和指令微调范式。这种集成使得大型语言模型（LLMs）能够理解时间和空间之间复杂的相互依赖关系，从而在数据稀缺的情况下促进更全面和准确的预测。广泛的实验结果突显了为时空学习构建LLMs的潜力，特别是在零样本场景中。提出的UrbanGPT的详细框架。

演示视频

https://github.com/HKUDS/UrbanGPT/assets/90381931/9cd094b4-8fa3-486f-890d-631a08b19b4a

入门指南

<a href='#Code Structure'>1. 代码结构</a>
<a href='#Environment'>2. 环境 </a>
<a href='#Training UrbanGPT'>3. 训练UrbanGPT </a>
- <a href='#Prepare Pre-trained Checkpoint'>3.1. 准备预训练检查点</a>
- <a href='#Instruction Tuning'>3.2. 指令微调</a>
<a href='#Evaluating UrbanGPT'>4. 评估UrbanGPT</a>
- <a href='#Preparing Checkpoints and Data'>4.1. 准备检查点和数据</a>
- <a href='#Running Evaluation'>4.2. 运行评估</a>
- <a href='#Evaluation Metric Calculation'>4.3. 评估指标计算</a>
<a href='#Instructions Generation'>5. 指令生成 </a>

1. 代码结构 <a href='#all_catelogue'>[返回顶部]</a>

.
|   README.md
|   urbangpt_eval.sh
|   urbangpt_train.sh
|   
+---checkpoints
|   \---st_encoder
|           pretrain_stencoder.pth
|           
+---playground
|   |   inspect_conv.py
|   |   
|   +---test_embedding
|   |       README.md
|   |       test_classification.py
|   |       test_semantic_search.py
|   |       test_sentence_similarity.py
|   |       
|   \---test_openai_api
|           anthropic_api.py
|           openai_api.py
|           
+---tests
|       test_openai_curl.sh
|       test_openai_langchain.py
|       test_openai_sdk.py
|       
\---urbangpt
    |   constants.py
    |   conversation.py
    |   utils.py
    |   __init__.py
    |   
    +---eval
    |   |   run_urbangpt.py                     # 评估
    |   |   run_vicuna.py
    |   |   
    |   \---script
    |           run_model_qa.yaml
    |           
    +---model
    |   |   apply_delta.py
    |   |   apply_lora.py
    |   |   builder.py
    |   |   compression.py
    |   |   convert_fp16.py
    |   |   make_delta.py
    |   |   model_adapter.py
    |   |   model_registry.py
    |   |   monkey_patch_non_inplace.py
    |   |   STLlama.py                          # 模型
    |   |   utils.py
    |   |   __init__.py
    |   |   
    |   \---st_layers
    |           args.py
    |           ST_Encoder.conf
    |           ST_Encoder.py                   # ST-编码器
    |           __init__.py
    |           
    +---protocol
    |       openai_api_protocol.py
    |       
    +---serve
    |   |   api_provider.py
    |   |   bard_worker.py
    |   |   cacheflow_worker.py
    |   |   cli.py
    |   |   controller.py
    |   |   controller_graph.py
    |   |   gradio_block_arena_anony.py
    |   |   gradio_block_arena_named.py
    |   |   gradio_css.py
    |   |   gradio_patch.py
    |   |   gradio_web_server.py
    |   |   gradio_web_server_graph.py
    |   |   gradio_web_server_multi.py
    |   |   huggingface_api.py
    |   |   inference.py
    |   |   model_worker.py
    |   |   model_worker_graph.py
    |   |   openai_api_server.py
    |   |   register_worker.py
    |   |   test_message.py
    |   |   test_throughput.py
    |   |   __init__.py
    |   |   
    |   +---examples
    |   |       extreme_ironing.jpg
    |   |       waterview.jpg
    |   |       
    |   +---gateway
    |   |       nginx.conf
    |   |       README.md
    |   |       
    |   \---monitor
    |           basic_stats.py
    |           clean_battle_data.py
    |           elo_analysis.py
    |           hf_space_leaderboard_app.py
    |           monitor.py
    |           
    \---train
            llama2_flash_attn_monkey_patch.py
            llama_flash_attn_monkey_patch.py
            stchat_trainer.py
            train_lora.py
            train_mem.py
            train_st.py                         # 训练

<环境/>

2.环境 <a href='#all_catelogue'>[返回顶部]</a>

请先克隆仓库并安装所需环境，可以通过运行以下命令完成：

[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

3. 训练UrbanGPT <a href='#all_catelogue'>[返回顶部]</a>

3.1. 准备预训练检查点 <a href='#all_catelogue'>[返回顶部]</a>

UrabnGPT基于以下优秀的现有模型进行训练。请按照说明准备检查点。

Vicuna: 准备我们的基础模型Vicuna，这是一个经过指令微调的聊天机器人，也是我们实现中的基础模型。请在这里下载其权重。我们通常使用v1.5和v1.5-16k版本的7B参数模型。您应该更新vicuna的'config.json'，例如，v1.5-16k中的'config.json'可以在config.json中找到。
时空编码器: 我们使用一个简单的基于TCNs的时空编码器来编码时空依赖关系。st_encoder的权重是通过典型的多步时空预测任务预训练的。
时空训练数据: 我们使用的预训练数据包括纽约市的出租车、自行车和犯罪数据，包括时空统计数据、记录的时间戳以及关于区域兴趣点(POIs)的信息。这些数据组织在train_data中。请下载并将其放在./UrbanGPT/ST_data_urbangpt/train_data目录下。

3.2. 指令微调 <a href='#all_catelogue'>[返回顶部]</a>

开始微调: 完成上述步骤后，您可以通过填写urbangpt_train.sh中的空白来开始指令微调。以下是一个示例：

[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

4. 评估UrbanGPT <a href='#all_catelogue'>[返回顶部]</a>

#### 4.1. 准备检查点和数据 <a href='#all_catelogue'>[返回顶部]</a>

检查点： 您可以尝试使用自己的模型或我们发布的检查点来评估UrbanGPT。
数据： 我们为NYC-taxi数据集划分了测试集，并制作了用于评估的指令数据。请参考evaluating。

4.2. 运行评估 <a href='#all_catelogue'>[返回顶部]</a>

您可以通过填写urbangpt_eval.sh中的空白处来开始第二阶段的调优。以下是一个示例：

# 在以下路径中填写评估相关内容！
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}

4.3. 评估指标计算 <a href='#all_catelogue'>[返回顶部]</a>

您可以使用result_test.py来计算预测结果的性能指标。

5. 指令生成 <a href='#all_catelogue'>[返回顶部]</a>

您可以使用instruction_generate.py中的代码生成您需要的特定指令。例如：

-dataset_name: 选择数据集。# NYC_multi（用于训练）    NYC_taxi NYC_bike NYC_crime1 NYC_crime2 CHI_taxi（用于测试）
# 以下选项只能有一个设置为True
-for_zeroshot: 是否用于零样本预测。
-for_supervised: 是否用于监督预测。
-for_ablation: 是否用于消融研究。

# 创建用于训练的指令数据
python instruction_generate.py -dataset_name NYC_multi

# 创建NYC_taxi数据集的指令数据，以便在UrbanGPT的零样本设置下进行测试
python instruction_generate.py -dataset_name NYC_taxi -for_zeroshot True

引用

如果您在研究或应用中发现UrbanGPT有用，请引用：

@misc{li2024urbangpt,
      title={UrbanGPT: Spatio-Temporal Large Language Models}, 
      author={Zhonghang Li and Lianghao Xia and Jiabin Tang and Yong Xu and Lei Shi and Long Xia and Dawei Yin and Chao Huang},
      year={2024},
      eprint={2403.00813},
      archivePrefix={arXiv},
      primaryClass={cs.CL}
}