LLMTSCS

Official code for article "LLMLight: Large Language Models as Traffic Signal Control Agents".

Generate Convert Improve

Install / Use

/learn @usail-hkust/LLMTSCS

About this skill

Quality Score

0/100

README

LLMLight: Large Language Models as Traffic Signal Control Agents

Stars

</p> <p align="center">

</p>

🎉 News

[x] 🚀🔥 [2024.11] 🎯🎯📢📢 Exciting News! We are thrilled to announce that our 🌟LLMLight🌟 has been accepted by KDD'2025! 🎉🎉🎉 Thanks to all the team members 🤗
[x] 🚀🔥 [2024.11] 🎯🎯📢📢 Exciting Update! We’re thrilled to announce that our LightGPT family has expanded with four new members now available on HuggingFace. These models include fine-tuned backbones based on Qwen2 and Llama3. Check them out!
[x] 🚀🔥 [2025.04] 🎯🎯📢📢 Delighted to receive the Special Award and Golden Medal of the International Exhibition Inventions of Geneva 2025, congratulations to the LLMLight team! 🤗
[x] 🚀🔥 [2025.08] 🎯🎯📢📢 Delighted to receive the Audience Appreciation Award from KDD'2025, congratulations to the LLMLight team! 🤗

1 Introduction

Official code for article "LLMLight: Large Language Models as Traffic Signal Control Agents".

Traffic Signal Control (TSC) is a crucial component in urban traffic management, aiming to optimize road network efficiency and reduce congestion. Traditional methods in TSC, primarily based on transportation engineering and reinforcement learning (RL), often exhibit limitations in generalization across varied traffic scenarios and lack interpretability. This paper presents LLMLight, a novel framework employing Large Language Models (LLMs) as decision-making agents for TSC. Specifically, the framework begins by instructing the LLM with a knowledgeable prompt detailing real-time traffic conditions. Leveraging the advanced generalization capabilities of LLMs, LLMLight engages a reasoning and decision-making process akin to human intuition for effective traffic control. Moreover, we build LightGPT, a specialized backbone LLM tailored for TSC tasks. By learning nuanced traffic patterns and control strategies, LightGPT enhances the LLMLight framework cost-effectively. Extensive experiments on nine real-world and synthetic datasets showcase the remarkable effectiveness, generalization ability, and interpretability of LLMLight against nine transportation-based and RL-based baselines.

The code structure is based on Efficient_XLight.

workflow

Watch Our Demo Video Here:

https://github.com/usail-hkust/LLMTSCS/assets/62106026/90567f61-5d58-4dac-8c8e-836a421f3ff9

2 Requirements

python>=3.9,tensorflow-cpu==2.8.0, cityflow, pandas==1.5.0, numpy==1.26.2, wandb, transformers==4.45.0, peft==0.7.1, accelerate==0.27.2, datasets==2.16.1, fire, vllm==0.6.2

cityflow needs a Linux environment, and we run the code on Ubuntu.

3 Usage

Parameters are well-prepared, and you can run the code directly.

For example, to run Advanced-MPLight:

python run_advanced_mplight.py --dataset hangzhou \
                               --traffic_file anon_4_4_hangzhou_real.json \
                               --proj_name TSCS

To run GPT-3.5/GPT-4 with LLMLight, you need to set your key in ./models/chatgpt.py:

headers = {
    "Content-Type": "application/json",
    "Authorization": "YOUR_KEY_HERE"
}

Then, run LLMLight by:

python run_chatgpt.py --prompt Commonsense \
                      --dataset hangzhou \
                      --traffic_file anon_4_4_hangzhou_real.json \
                      --gpt_version gpt-4 \
                      --proj_name TSCS

You can either choose Commonsense or Wait Time Forecast as the prompt argument.

To run with open-sourced LLMs (or LightGPT) and LLMLight:

# with default methods of Transformers
python run_open_LLM.py --llm_model LLM_MODEL_NAME_ONLY_FOR_LOG \
                       --llm_path LLM_PATH \
                       --dataset hangzhou \
                       --traffic_file anon_4_4_hangzhou_real.json \
                       --proj_name TSCS
                       
# or with VLLM (much faster but will cost more GPU memory)
python run_open_LLM_with_vllm.py --llm_model LLM_MODEL_NAME_ONLY_FOR_LOG \
                                 --llm_path LLM_PATH \
                                 --dataset hangzhou \
                                 --traffic_file anon_4_4_hangzhou_real.json \
                                 --proj_name TSCS

4 Baselines

Heuristic Methods:
- FixedTime, Maxpressure, EfficientMaxPressure
DNN-RL:
- PressLight, MPLight, CoLight, AttendLight, EfficientMPLight, EfficientPressLight, Efficient-Colight
Adv-DNN-RL:
- Advanced-MaxPressure, Advanced-MPLight, Advanced-Colight
LLMLight+LLM:
- gpt-3.5-turbo-0613, gpt-4-0613, llama-2-13b-chat-hf, llama-2-70b-chat-hf
LLMLight+LightGPT:
- The model trained on Jinan 1 is available at https://huggingface.co/collections/usail-hkust/llmlight-lightgpt-673ac5a619cbbe309165b56d

5 LightGPT Training

Step 1: Imitation Fine-tuning

python ./finetune/run_imitation_finetune.py --base_model MODEL_PATH \
                                            --data_path DATA_PATH \
                                            --output_dir OUTPUT_DIR
                                            
python ./finetune/merge_lora.py --adapter_model_name="OUTPUT_DIR" \
                                --base_model_name="MODEL_PATH" \
                                --output_name="MERGED_MODEL_PATH"

We merge the adapter with the base model by running merge_lora.py.

Step 2: Policy Refinement Data Collection

You first need to train Advanced-CoLight by running:

python run_advanced_colight.py --dataset hangzhou \
                               --traffic_file anon_4_4_hangzhou_real.json \
                               --proj_name TSCS

The RL model weights will be automatically saved in a checkpoint folder in ./model. You need to copy it and put it under the ./model_weights/AdvancedColight/{traffic_file}/" folder.

Then, collect the data by running:

python ./finetune/run_policy_refinement_data_collection.py --llm_model MODEL_NAME_ONLY_FOR_LOG \
                                                           --llm_path MODEL_PATH \
                                                           --dataset hangzhou \
                                                           --traffic_file anon_4_4_hangzhou_real.json

The fine-tuning data will be ready at ./data/cgpr/cgpr_{traffic_file}.json.

Step 3: Critic-guided Policy Refinement

python ./finetune/run_policy_refinement.py --llm_model MODEL_NAME_ONLY_FOR_LOG \
                                           --llm_path MODEL_PATH \
                                           --llm_output_dir OUTPUT_DIR \
                                           --dataset hangzhou \
                                           --traffic_file anon_4_4_hangzhou_real.json \
                                           --proj_name LightGPTFineTuning
                                           
python ./finetune/merge_lora.py --adapter_model_name="OUTPUT_DIR_{traffic_file}" \
                                --base_model_name="MODEL_PATH" \
                                --output_name="MERGED_MODEL_PATH"

Similarly, we merge the adapter with the base model by running merge_lora.py.

6 Code structure

models: contains all the models used in our article.
utils: contains all the methods to simulate and train the models.
frontend: contains visual replay files of different agents.
errors: contains error logs of ChatGPT agents.
{LLM_MODEL}_logs: contains dialog log files of a LLM.
prompts: contains base prompts of ChatGPT agents.
finetune: contains codes for LightGPT training.

7 Datasets

<table> <tr> <td> <b> Road networks </b> </td> <td> <b> Intersections </b> </td> <td> <b> Road network arg </b> </td> <td> <b> Traffic files </b> </td> </tr> <tr>  <th rowspan="4"> Jinan </th> <th rowspan="4"> 3 X 4 </th> <th rowspan="4"> jinan </th> <td> anon_3_4_jinan_real </td> </tr> <tr> <td> anon_3_4_jinan_real_2000 </td> </tr> <tr> <td> anon_3_4_jinan_real_2500 </td> </tr> <tr> <td> anon_3_4_jinan_synthetic_24000_60mi

Related Skills

node-connect

352.2k

Diagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps

frontend-design

111.1k

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

openai-whisper-api

352.2k

Transcribe audio via OpenAI Audio Transcriptions API (Whisper).

qqbot-media

352.2k

QQBot 富媒体收发能力。使用 <qqmedia> 标签，系统根据文件扩展名自动识别类型（图片/语音/视频/文件）。