# zgc-llm-safety/trafficllm architecture

> Architecture diagram of the GitHub repository zgc-llm-safety/trafficllm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zgc-llm-safety/trafficllm
- Repository: https://github.com/zgc-llm-safety/trafficllm

## Overview

##### Project Type and Purpose
- TrafficLLM is an open‐source framework for adapting large-language models (ChatGLM2, GLM4, LLaMA2) to network traffic analysis tasks (detection & generation).
- Core features: traffic-domain tokenization, dual-stage tuning (instruction + traffic data), and extensible parameter-efficient fine-tuning (EA-PEFT).

##### Main Components
A. Data Layer
- Raw Traffic Datasets (PCAP files)
- Instruction Datasets (JSON of human instructions)
B. Preprocessing Layer
- preprocess_dataset.py, flow_data_preprocess.py, packet_data_preprocess.py
- Output: structured JSON datasets for tuning & testing
C. Tokenization Layer
- traffic_tokenizer.py
- Extends base‐model tokenizer to handle traffic segments & special tokens
D. Dual-Stage Tuning Pipeline
1. Stage 1 (Instruction Tuning)
- Script: dual-stage-tuning/trafficllm_stage1.sh & main.py
- Learns LLM to understand natural-language traffic tasks
2. Stage 2 (Task-Specific Traffic Tuning)
- Script: dual-stage-tuning/trafficllm_stage2.sh & trainer_seq2seq.py
- Teaches model to map traffic patterns to labels or generate pcap payloads
E. EA-PEFT Extension Module
- EA-PEFT/ea-peft.py
- Dynamically updates or registers new task adapters with low overhead
- Produces separate PEFT checkpoints per traffic task
F. Model Store
- Base models: models/chatglm2/chatglm2-6b/, Adapt2GLM4/...
- PEFT checkpoints: stored under models/chatglm2/peft/<task>/checkpoint-*/
G. Evaluation Component
- evaluation.py
- Consumes base + PEFT models plus test JSON & label files to compute metrics
H. Inference & Serving Layer
- inference.py (CLI mode)
- trafficllm_server.py (Streamlit web server)
- config.json: registers model_path, peft_set, task mapping, preprompts

##### Relationships & Data Flow
- Raw Data → Preprocessing → Processed JSON
- Processed JSON → Tokenizer → Tokenized Input
- Tokenized Input + Base Model → Stage 1 Tuning → Instruction PEFT Adapter
- Stage 1 Model → Stage 2 Tuning (per-task) → Task-Specific PEFT Adapters
- All PEFT Adapters registered via config.json
- Inference Module loads Base Model + selected PEFT Adapter → Serves predictions
- Evaluation Module loads same model combinations → Computes detection/generation metrics
- EA-PEFT Module may extend/update PEFT Adapters by feeding in new traffic data

##### Architectural Patterns & Design Principles
- Pipeline Pattern: clear linear flow from raw data to deployment
- Modularization: each layer (preprocess, tokenize, tune, serve) is independent
- Plugin/Adapter Pattern: PEFT adapters encapsulate task-specific behavior
- Configuration-driven: config.json drives model & adapter selection at runtime
- Reusability & Extensibility: add new tasks by adding new PEFT checkpoints and updating config.json

##### Putting It All Together
- Leftmost column: Data Layer (Raw Traffic, Instructions)
- Next column: Preprocessing → Tokenization
- Center column: Dual-Stage Tuning (Stage 1 and Stage 2) plus EA-PEFT extension
- Below/alongside: Model Store (base + PEFT checkpoints)
- Rightmost column: Inference & Serving + Evaluation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RawPCAP["Raw PCAP Files"]:::data
        InstrJSON["Instruction JSON"]:::data
        Config["config.json"]:::config
    end

    %% Preprocessing Layer
    subgraph "Preprocessing Layer"
        direction TB
        PP1["preprocess_dataset.py"]:::process
        PP2["flow_data_preprocess.py"]:::process
        PP3["packet_data_preprocess.py"]:::process
        PP4["preprocess_utils.py"]:::process
        PP5["specfic_dataset_utils.py"]:::process
        ProcJSON["Processed JSON Datasets"]:::data
    end

    %% Tokenization Layer
    subgraph "Tokenization Layer"
        direction TB
        Tokenizer["traffic_tokenizer.py"]:::process
        Tokenized["Tokenized Input"]:::data
    end

    %% Dual-Stage Tuning
    subgraph "Dual-Stage Tuning Pipeline"
        direction TB
        subgraph "Stage 1: Instruction Tuning"
            direction TB
            S1Script["trafficllm_stage1.sh"]:::process
            S1Main["main.py"]:::process
            S1Args["arguments.py"]:::process
            S1Train["trainer.py"]:::process
            InstrAdapter["Instruction PEFT Adapter"]:::model
        end
        subgraph "Stage 2: Task-Specific Tuning"
            direction TB
            S2Script["trafficllm_stage2.sh"]:::process
            S2TrainSeq["trainer_seq2seq.py"]:::process
            TaskAdapter["Task-Specific PEFT Adapter"]:::model
        end
    end

    %% EA-PEFT Extension
    EA["ea-peft.py"]:::process

    %% Model Store
    subgraph "Model Store"
        direction TB
        BaseModels["Base Models"]:::model
        PEFTStore["PEFT Checkpoints"]:::model
    end

    %% Serving & Evaluation
    subgraph "Serving & Evaluation"
        direction TB
        InferenceCLI["inference.py"]:::service
        InferenceWeb["trafficllm_server.py"]:::service
        InferenceWebTxt["trafficllm_server_text.py"]:::service
        Eval["evaluation.py"]:::service
    end

    %% Relationships
    RawPCAP -->|feeds| PP1
    InstrJSON -->|feeds| PP1
    PP1 -->|generates| ProcJSON
    ProcJSON -->|feeds| Tokenizer
    Tokenizer -->|produces| Tokenized
    Tokenized -->|uses| S1Script
    Tokenized -->|uses| S1Main
    S1Train -->|trains| InstrAdapter
    InstrAdapter -->|seed model| S2Script
    Tokenized -->|feeds| S2Script
    S2TrainSeq -->|trains| TaskAdapter
    InstrAdapter -->|registered via| Config
    TaskAdapter -->|registered via| Config
    S1Train --> EA
    EA -->|updates| TaskAdapter
    BaseModels -->|load for| S1Train
    BaseModels -->|load for| S2TrainSeq
    InstrAdapter -->|stored in| PEFTStore
    TaskAdapter -->|stored in| PEFTStore
    Config -->|drives| InferenceCLI
    Config -->|drives| InferenceWeb
    BaseModels -->|loaded by| InferenceCLI
    PEFTStore -->|loaded by| InferenceCLI
    BaseModels -->|loaded by| InferenceWeb
    PEFTStore -->|loaded by| InferenceWeb
    InferenceCLI -->|evaluates| Eval
    InferenceWeb -->|evaluates| Eval

    %% Click Events
    click PP1 "https://github.com/zgc-llm-safety/trafficllm/blob/master/preprocess/preprocess_dataset.py"
    click PP2 "https://github.com/zgc-llm-safety/trafficllm/blob/master/preprocess/flow_data_preprocess.py"
    click PP3 "https://github.com/zgc-llm-safety/trafficllm/blob/master/preprocess/packet_data_preprocess.py"
    click PP4 "https://github.com/zgc-llm-safety/trafficllm/blob/master/preprocess/preprocess_utils.py"
    click PP5 "https://github.com/zgc-llm-safety/trafficllm/blob/master/preprocess/specfic_dataset_utils.py"
    click Tokenizer "https://github.com/zgc-llm-safety/trafficllm/blob/master/tokenization/traffic_tokenizer.py"
    click S1Script "https://github.com/zgc-llm-safety/trafficllm/blob/master/dual-stage-tuning/trafficllm_stage1.sh"
    click S1Main "https://github.com/zgc-llm-safety/trafficllm/blob/master/dual-stage-tuning/main.py"
    click S1Args "https://github.com/zgc-llm-safety/trafficllm/blob/master/dual-stage-tuning/arguments.py"
    click S1Train "https://github.com/zgc-llm-safety/trafficllm/blob/master/dual-stage-tuning/trainer.py"
    click S2Script "https://github.com/zgc-llm-safety/trafficllm/blob/master/dual-stage-tuning/trafficllm_stage2.sh"
    click S2TrainSeq "https://github.com/zgc-llm-safety/trafficllm/blob/master/dual-stage-tuning/trainer_seq2seq.py"
    click EA "https://github.com/zgc-llm-safety/trafficllm/blob/master/EA-PEFT/ea-peft.py"
    click InferenceCLI "https://github.com/zgc-llm-safety/trafficllm/blob/master/inference.py"
    click InferenceWeb "https://github.com/zgc-llm-safety/trafficllm/blob/master/trafficllm_server.py"
    click InferenceWebTxt "https://github.com/zgc-llm-safety/trafficllm/blob/master/trafficllm_server_text.py"
    click Eval "https://github.com/zgc-llm-safety/trafficllm/blob/master/evaluation.py"
    click Config "https://github.com/zgc-llm-safety/trafficllm/blob/master/config.json"

    %% Styles
    classDef data fill:#D0E8FF,stroke:#004A7C,color:#004A7C
    classDef process fill:#DFFFE0,stroke:#2E7D32,color:#2E7D32
    classDef model fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C
    classDef service fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef config fill:#FFF3E0,stroke:#BF360C,color:#BF360C
```
