label-anything-sam

Traditional Chinese version: README.zh-TW.md

Why this repository exists

As of 2026-04, the upstream Label Studio ML backend does not provide a maintained SAM3 integration path for production deployment. This repository provides a practical, deployment-focused stack:

• Core services: Label Studio + PostgreSQL + Redis + MinIO + Nginx + Cloudflare Tunnel
• Optional GPU overlays: SAM3 image/video backends and SAM2.1 image/video backends
• Security-first defaults for S3 access, token usage, and network exposure

Note

Version guidance:

• main and release v1.1.4 include all SAM3 fixes and enhancements: native point embeddings (image + video), mask selection modes (adaptive/top1/topk/threshold/all), runtime threshold and selection-mode UI overrides, bidirectional video tracking, multi-object track merging, and dual text-prompt fields (pure vs mixed-use).
• If you prefer native PostgreSQL mode (no Supabase), use release v1.0.4 (hotfix line based on pre-Supabase baseline).
• You can get each line in any of these ways:
  1. Git checkout (recommended for local dev)
  2. Download Source code (zip) from the corresponding Release
  3. Switch Branch/Tag in GitHub UI

git fetch --tags
git checkout tags/v1.1.4 -b local-main-v1.1.4
# or
git checkout tags/v1.0.4 -b local-v1-native-pg

In v1.0.4, Label Studio data is stored in native PostgreSQL (pg-db) and does not require .env.supabase or make supabase-up.

Quick Start

git clone https://github.com/felimet/label-anything-sam
cd label-anything-sam

# 1) Core stack
cp .env.example .env
# Supabase standalone is required for default Label Studio DB path in this branch
cp .env.supabase.example .env.supabase
# Fill all <PLACEHOLDER> values
# LABEL_STUDIO_USER_TOKEN must be <= 40 chars (use: openssl rand -hex 20)
# IMPORTANT: keep POSTGRES_PASSWORD in .env and .env.supabase the same

make supabase-up
make up
make init-minio

# 2) Optional ML backends (GPU)
cp .env.ml.example .env.ml
# Set LABEL_STUDIO_API_KEY (Legacy Token) and HF_TOKEN

make ml-up

# 3) Optional RedisInsight (Redis GUI)
cp .env.tools.example .env.tools
make tools-up

# 4) Supabase management command aliases
# (already started in step 1 for default DB route)
# make supabase-up / make supabase-down / make supabase-logs

# 5) Optional SAM3 Agent (LLM-assisted mask selection for SAM3 backend)
cp .env.sam3_agent.example .env.sam3_agent
# Set SAM3_AGENT_ENABLED=true and configure LLM endpoint (URL / KEY / MODEL)
# All supported providers (vLLM, Ollama, OpenAI, Gemini, Groq, etc.) are documented
# in .env.sam3_agent.example. The LLM MUST support vision (multimodal) input.

make up-sam3-agent
# To apply LLM config changes without rebuilding: make restart-sam3-agent

Overlay minimal example for Label Studio integration (NOT part of this branch runtime flow):

# Example pairing only:
# docker-compose.supabase.sample.yml + .env.supabase.sample.template
cp .env.supabase.sample.template .env.supabase.sample
make supabase-sample-up SUPABASE_SAMPLE_ENV=.env.supabase.sample

Optional Cloudflare Tunnel admin routes are configured in Cloudflare UI (not via env vars), for example:

supabase-studio.example.com -> http://supabase-studio:3000
supabase-meta.example.com   -> http://supabase-meta:8080
redisinsight.example.com    -> http://redisinsight:5540

If SUPABASE_META_CONTAINER_PORT is changed, update the supabase-meta target port in Cloudflare accordingly.

See docs/cloudflare-tunnel.md for the complete mapping table and CF Access requirements.

Open:

• Label Studio: http://localhost:18090
• MinIO Console: http://localhost:19001
• MinIO Full Admin UI: http://localhost:19002

Verify stack health:

make health

Direct Compose (Without Make)

If you prefer typing docker compose -f ... up directly, keep two safeguards enabled:

1. Interpolation safeguard: always provide a fixed project name plus explicit env files.
2. Runtime safeguard: keep service-level env_file (for ML backends) and required vars (${VAR:?}) in compose files.

PowerShell session defaults (recommended):

$env:COMPOSE_PROJECT_NAME = "label-anything-sam"

Standalone Supabase (default branch runtime):

docker compose --project-name label-anything-sam \
	--env-file .env --env-file .env.supabase \
	-f docker-compose.supabase.yml up -d

Supabase sample mode:

docker compose --project-name label-anything-sam \
	--env-file .env --env-file .env.supabase.sample \
	-f docker-compose.yml -f docker-compose.override.yml -f docker-compose.supabase.sample.yml up -d

ML overlays:

docker compose --project-name label-anything-sam \
	--env-file .env \
	-f docker-compose.yml -f docker-compose.override.yml -f docker-compose.ml.yml up -d

Optional one-liner fallback (--env-file omitted):

$env:COMPOSE_ENV_FILES = ".env,.env.supabase"
docker compose -f docker-compose.supabase.yml config -q

COMPOSE_ENV_FILES is only used when CLI --env-file is not provided.

Critical Notes Before You Continue

• Use Legacy Token for ML backends, not Personal Access Token.
• Use MINIO_LS_ACCESS_ID / MINIO_LS_SECRET_KEY for Label Studio S3 storage, never root credentials.
• Rotate MinIO service-account credentials immediately after first deployment.
• If changing .env, recreate containers (down + up) instead of only restart.

Environment Profiles

To avoid one oversized env file, variables are split by scope:

• .env.example → .env: Core runtime stack (required)
• .env.ml.example → .env.ml: SAM3/SAM2.1 backends (optional)
• .env.tools.example → .env.tools: Local dev tools such as RedisInsight (optional)
• .env.supabase.example → .env.supabase: Supabase standalone management stack (required)
• .env.supabase.sample.template → .env.supabase.sample: Supabase minimal example mode (documentation/demo only)

Supabase mode boundaries:

• Runtime mode (this branch): docker-compose.supabase.yml + .env.supabase
• Example mode only: docker-compose.supabase.sample.yml + .env.supabase.sample

.env.example is the single complete core template.

Start Here By Role

Role	Start Here	Cookbook	Deep Dive
End User / Project Admin	docs/README.md	docs/cookbook/user-cookbook.md	docs/user-guide.md
Developer	docs/README.md	docs/cookbook/developer-cookbook.md	docs/CONTRIBUTING.md
Operator / SRE	docs/README.md	docs/cookbook/ops-cookbook.md	docs/RUNBOOK.md

Documentation Map

• docs/README.md: Documentation hub and reading paths
• docs/user-guide.md: User workflows and admin operations
• docs/configuration.md: Single source of truth for environment variables
• docs/architecture.md: Topology, data flow, and security design
• docs/cloudflare-tunnel.md: Public exposure, tunnel, and WAF setup
• docs/sam3-backend.md: SAM3 backend behavior and constraints
• docs/sam21-backend.md: SAM2.1 backend behavior and constraints
• docs/RUNBOOK.md: Operations, incident response, backup and restore
• docs/CONTRIBUTING.md: Development workflow and contribution policy

Make Targets (Short List)

• make up / down / restart / logs / ps: Core stack lifecycle
• make ml-up / ml-down: Core stack with ML overlays
• make tools-up / tools-down / tools-logs: RedisInsight local GUI overlay
• make supabase-up / supabase-down / supabase-logs: Supabase management (standalone stack, default)
• make supabase-standalone-up / supabase-standalone-down / supabase-standalone-logs: Explicit standalone aliases
• make supabase-sample-up / supabase-sample-down / supabase-sample-logs: Supabase minimal example mode (studio + meta)
• make build-sam3-image / build-sam3-video / build-sam21-image / build-sam21-video: Build ML images
• make test-sam3-image / test-sam3-video / test-sam21-image / test-sam21-video: Run ML backend tests
• make init-minio: One-time bucket and service-account initialization
• make health: End-to-end health checks

Batch Annotation

Run SAM3 or SAM2.1 inference on an entire Label Studio project in one command — from the CLI or from a browser-based Web UI (no terminal required).

# CLI: annotate all tasks in project 1 with SAM3
python scripts/batch_annotate.py --project-id 1 --backend sam3 \
    --text-prompt "cow, grass, fence"
# or
make batch-annotate PROJECT_ID=1

# Web UI: open http://<your-server>:8085 in a browser
make batch-server

See docs/batch-annotation.md for full CLI reference, SAM3 vs SAM2.1 comparison, concurrency settings, and Web UI deployment.

Label Studio Annotation UI (SAM3-image)

License

Apache-2.0 © 2026 Jia-Ming Zhou