# Label Studio ML Annotation

> Label Studio for data labeling with ML backend.

- Category: AI & Machine Learning
- Difficulty: intermediate
- Components: label-studio, postgresql, ml-backend
- Tags: labeling, annotation, ml, data
- Source: https://docker.recipes/ai-ml/label-studio-ml

## Overview

Label Studio is an open-source data labeling platform developed by HumanSignal that enables teams to annotate various data types including text, images, audio, video, and time series data. Originally created to address the bottleneck of high-quality data preparation in machine learning workflows, Label Studio has evolved into a comprehensive annotation platform that supports over 30 data types and integrates with popular ML frameworks. It provides a flexible interface for creating custom labeling configurations and supports collaborative annotation workflows with quality control features.

This deployment consists of three interconnected services: the main Label Studio application server, a PostgreSQL database for persistent data storage, and a dedicated ML backend service for automated pre-annotations. The Label Studio service runs the core web application and API, while the PostgreSQL database stores project configurations, user data, annotations, and metadata. The ML backend service operates independently to provide machine learning-powered suggestions and active learning capabilities, connecting to the main Label Studio instance via HTTP API calls.

This configuration is ideal for data science teams, AI researchers, and organizations looking to implement production-grade data labeling workflows with machine learning acceleration. The combination of Label Studio's versatile annotation interface with an integrated ML backend creates a powerful active learning environment where models can pre-annotate data and continuously improve based on human feedback, significantly reducing manual labeling effort while maintaining annotation quality.

## Features

- Multi-format data annotation supporting text, images, audio, video, and time series with customizable labeling interfaces
- PostgreSQL-backed persistent storage for annotations, projects, and user management with ACID compliance
- Integrated ML backend service providing automated pre-annotations and active learning capabilities
- Export functionality to popular ML formats including COCO, YOLO, Pascal VOC, CONLL, and JSON
- Web-based collaborative annotation interface with user roles, task assignment, and quality control
- RESTful API for programmatic access to projects, tasks, and annotations
- Custom labeling configuration templates using XML-based markup for domain-specific workflows
- Real-time model training integration with the ability to retrain models based on new annotations

## Use cases

- Computer vision projects requiring object detection, image segmentation, or classification annotations with YOLO/COCO export
- Natural language processing tasks including named entity recognition, sentiment analysis, and text classification
- Active learning workflows where ML models iteratively improve by suggesting labels for human verification
- Multi-annotator projects requiring consensus building and inter-annotator agreement measurement
- Audio and video content labeling for speech recognition, sound classification, or video analysis projects
- Research environments where custom annotation schemas need to be rapidly prototyped and deployed
- Production ML pipelines requiring continuous data labeling and model retraining cycles

## Prerequisites

- Docker and Docker Compose installed with minimum 2GB RAM available for the three-service stack
- Port 8080 available for Label Studio web interface and port 9090 for ML backend API
- Database password configured in environment variables for PostgreSQL authentication
- Basic understanding of data annotation workflows and machine learning model integration concepts
- Familiarity with Label Studio's XML-based labeling configuration syntax for custom interfaces
- Knowledge of target export formats (COCO, YOLO, etc.) if integrating with specific ML frameworks

## docker-compose.yml

```yaml
services:
  label-studio:
    image: heartexlabs/label-studio:latest
    container_name: label-studio
    restart: unless-stopped
    ports:
      - "${LS_PORT:-8080}:8080"
    environment:
      - DJANGO_DB=default
      - POSTGRE_HOST=label-studio-db
      - POSTGRE_NAME=labelstudio
      - POSTGRE_USER=labelstudio
      - POSTGRE_PASSWORD=${DB_PASSWORD}
    volumes:
      - ls_data:/label-studio/data
    depends_on:
      - label-studio-db

  label-studio-db:
    image: postgres:15-alpine
    container_name: label-studio-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=labelstudio
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=labelstudio
    volumes:
      - ls_db_data:/var/lib/postgresql/data

  ml-backend:
    image: heartexlabs/label-studio-ml-backend:latest
    container_name: ls-ml-backend
    restart: unless-stopped
    ports:
      - "${ML_PORT:-9090}:9090"
    environment:
      - LABEL_STUDIO_URL=http://label-studio:8080
    volumes:
      - ml_models:/models

volumes:
  ls_data:
  ls_db_data:
  ml_models:
```

## .env

```bash
# Label Studio
LS_PORT=8080
DB_PASSWORD=labelstudio_password
ML_PORT=9090
```

## Usage notes

- Docs: https://labelstud.io/guide/
- Label Studio at http://localhost:8080 - create account on first access
- ML backend at http://localhost:9090 for pre-annotations
- Configure ML backend in Project Settings > Machine Learning
- Export to COCO, YOLO, Pascal VOC, CONLL, JSON formats
- Active learning: ML backend suggests labels, humans verify

## Troubleshooting

- Label Studio shows database connection errors: Verify DB_PASSWORD environment variable is set and label-studio-db container is running
- ML backend not appearing in Project Settings: Check that ml-backend container is accessible on port 9090 and LABEL_STUDIO_URL is correctly configured
- Annotations not persisting after container restart: Ensure ls_data and ls_db_data volumes are properly mounted and have write permissions
- ML backend models not loading or training: Verify ml_models volume has sufficient disk space and the ML backend has network access to Label Studio API
- Web interface returns 500 errors on startup: Check label-studio container logs for Django database migration issues and ensure PostgreSQL is fully initialized
- Export functions failing with format errors: Validate that annotation schema matches the requirements of target export format (COCO, YOLO, etc.)

