What is LlamaBoard and How Does It Work: The Complete Guide to LlamaFactory's Web UI

LlamaBoard is the interactive Gradio-based web interface for LlamaFactory that enables users to configure, launch, and monitor LLM fine-tuning jobs through a browser without writing Python code.

LlamaBoard serves as the graphical front-end for the LlamaFactory open-source project, providing a browser-based alternative to command-line training workflows. This web UI abstracts complex training configurations into intuitive forms and dashboards, allowing researchers and developers to execute SFT, LoRA, RLHF, and DPO training jobs while monitoring progress in real time.

LlamaBoard Architecture and Core Components

Entry Point and CLI Integration

The llamafactory-cli webui command serves as the primary entry point, defined in src/launcher.py. This CLI wrapper parses command-line arguments and invokes the launch() function from src/webui.py, initiating the Gradio server on port 7860 by default.

Web UI Server (src/webui.py)

The src/webui.py module constructs the Gradio interface using gr.Blocks(), organizing functionality into three primary tabs:

• Training: Configuration forms for model selection, dataset upload, LoRA/QLoRA parameters, and hyperparameters
• Inference: Model loading and chat interface for testing checkpoints
• Monitor: Real-time visualization of training metrics and system utilization

Training Engine Integration

When users initiate training, src/webui.py spawns a subprocess via subprocess.Popen to execute src/train.py. This process isolation prevents the Gradio event loop from blocking during GPU-intensive operations. The train.run() function handles the actual training logic, supporting SFT, LoRA, QLoRA, DeepSpeed, and FSDP configurations.

How LlamaBoard Works: Operational Workflow

Configuration and Launch Process

LlamaBoard translates UI form inputs into YAML-compatible configurations that mirror LlamaFactory's CLI arguments. When users click Start, the system:

1. Validates model paths, dataset formats, and hyperparameter ranges
2. Serializes configurations into temporary YAML files or command-line arguments
3. Invokes the training subprocess with GPU allocation and distributed training flags

Real-Time Monitoring and Logging

The src/llamafactory/extras/logging.py module implements a custom logging.Handler that bifurcates output streams:

• File logging: Writes structured logs to logs/llamaboard.log
• UI streaming: Emits formatted messages to the Gradio output component via websocket
• External trackers: Integrates with TensorBoard, Wandb, MLflow, and SwanLab through SummaryWriter events

Simultaneously, src/llamafactory/extras/plotting.py generates Matplotlib and Plotly visualizations for loss curves, learning rate schedules, and GPU utilization metrics that render in the Monitor tab.

Model Export and Checkpoint Management

Upon training completion, LlamaBoard exposes trained checkpoints through the Inference tab for immediate testing. The export functionality serializes LoRA adapters or merged full models into downloadable zip archives, leveraging the same serialization logic used in the CLI workflow.

Practical Usage Examples

Launching LlamaBoard from Command Line

Start the web interface with default settings:

llamafactory-cli webui

Specify custom host and port for remote access:

llamafactory-cli webui --host 0.0.0.0 --port 8000

Programmatic Launch in Python

Integrate LlamaBoard into custom applications:

from llamafactory.webui import launch

config = {
    "model_name_or_path": "meta-llama/Meta-Llama-3-8B",
    "train_dataset": "data/v1_sft_demo.jsonl",
    "lora_rank": 8,
    "monitor": "llamaboard"
}

launch(config=config, share=True)  # share=True creates public Gradio link

Running Training via Web Interface

1. Navigate to http://127.0.0.1:7860 after launching
2. Select the Training tab and configure:
   • Model: meta-llama/Meta-Llama-3-8B
   • Dataset: Upload JSONL file or select predefined dataset
   • Method: LoRA with rank 8
   • Hyperparameters: Learning rate 1e-4, 3 epochs
3. Click Start to initiate the subprocess
4. Switch to the Monitor tab to observe real-time loss curves and GPU utilization

Side-by-Side Monitoring with TensorBoard

While LlamaBoard runs, launch TensorBoard in a separate terminal:

tensorboard --logdir logs/tensorboard

Access TensorBoard at http://localhost:6006 to view the same training metrics that appear in LlamaBoard's Monitor tab.

Summary

• LlamaBoard is the official Gradio-based web interface for LlamaFactory, providing browser-based control over LLM fine-tuning workflows.
• The architecture separates concerns between the UI server (src/webui.py), CLI launcher (src/launcher.py), and training engine (src/train.py), using subprocess isolation to maintain UI responsiveness.
• Real-time monitoring relies on custom logging handlers in src/llamafactory/extras/logging.py and plotting utilities in src/llamafactory/extras/plotting.py, supporting both built-in visualizations and external trackers like TensorBoard and Wandb.
• Users can launch LlamaBoard via llamafactory-cli webui, programmatically through the Python API, or within Docker containers exposing port 7860.

Frequently Asked Questions

What is the difference between LlamaBoard and LlamaFactory?

LlamaFactory is the underlying Python framework and CLI tool for fine-tuning large language models, while LlamaBoard is the optional Gradio-based web interface built on top of it. LlamaBoard provides graphical forms and dashboards that generate the same YAML configurations and training commands used by the LlamaFactory CLI, making it accessible to users who prefer browser-based workflows over terminal commands.

Can I use LlamaBoard for distributed training with DeepSpeed or FSDP?

Yes. LlamaBoard supports distributed training configurations including DeepSpeed and FSDP (Fully Sharded Data Parallel). When configuring a training job in the web interface, you can select distributed training options and specify ZeRO stages or sharding strategies. The UI passes these parameters to src/train.py, which initializes the appropriate distributed backend before spawning the training subprocess.

How does LlamaBoard handle real-time log streaming without blocking the interface?

LlamaBoard uses subprocess isolation to prevent the Gradio event loop from freezing during GPU-intensive operations. When you click Start, src/webui.py spawns the training process via subprocess.Popen. A background thread polls the subprocess stdout/stderr, parsing specially formatted log lines (tagged with [LLAMABOARD]) to update the UI components. This architecture ensures the browser interface remains responsive while training progresses on the GPU.

Is it possible to run LlamaBoard in a Docker container?

Yes. LlamaBoard is fully containerized through the official Dockerfiles in the docker/ directory (such as docker/docker-cuda/Dockerfile). These images expose port 7860 by default and include all dependencies required to run the Gradio interface. You can launch the container with GPU support and access LlamaBoard through your browser at http://localhost:7860, making it suitable for cloud deployments and reproducible environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}