Label Studio (label-studio)

Labellisation de textes, d'images, de sons, de vidéos et de séries temporelles, validation humaine des sorties des modèles, comparaison de deux réponses (préférences) et préparation des jeux de données qui servent à affiner et à évaluer les modèles de langage et de vision (LLM et VLM : SFT, DPO). Les projets, les utilisateurs et les annotations sont dans la base PostgreSQL de la plateforme, les médias téléversés dans un compartiment S3 (SeaweedFS de la plateforme par défaut).

Généré depuis catalog/services/label-studio.yaml : ne pas modifier à la main.

Résumé

Version	1.23.2
Usage	installer et configurer, configurer et connecter
Couche	fonctionnelle (catalogue IA)
Catégorie	Plateformes de données
Méthodes d'installation	podman
Connexion externe	non
Réservé au bac à sable	non

Licence

Identifiant SPDX	Apache-2.0
Politique de licence	licence socle (MIT ou Apache-2.0)
Exception de licence	-
Remarque de licence	Label Studio Community Edition uniquement : les éditions Label Studio Enterprise et Starter Cloud de HumanSignal (rôles, espaces de travail, SSO, circuits de relecture) sont commerciales et ne sont ni installées ni configurées.
Composant de la plateforme	label-studio

Paquets et artefacts

Un paquet que publie le projet du service (son image, son archive binaire, son paquet Python ou système) porte la licence du service ; un paquet tiers porte la licence écrite sur sa ligne, lue dans les métadonnées officielles du projet amont.

Type	Paquet	Version	Licence	Détails
image de conteneur	docker.io/heartexlabs/label-studio	1.23.2	Apache-2.0	clé d'image label-studio, utilisée par app, nginx, condensé sha256:afcc516a22775a39d0d66f4c2ddc95d01be3e3d3862b21fcf4f9de34b4ad4e12

Les images sont épinglées par étiquette dans le descripteur, et par condensé (digest) quand le descripteur en déclare un (le bundle hors ligne refuse alors une image téléchargée qui ne le porte pas) ; le condensé est enregistré dans le miroir du Manager à l'import du bundle hors ligne, et chaque téléchargement ou chargement est vérifié par rapport à lui.

Systèmes et architectures pris en charge

Méthode	Systèmes d'exploitation	Architectures
podman	famille RHEL (dnf), famille Debian (apt), Arch Linux (pacman)	x86_64, aarch64 (non restreintes par le descripteur)

Systèmes hôtes certifiés : RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). Le contrôle préalable des hôtes accepte ces systèmes (une autre version d'une famille connue donne un avertissement, une version en fin de vie est refusée) et les architectures x86_64 et aarch64.

Prérequis

Hôte

• au moins 4096 Mo de mémoire (avertissement, memory).
• le programme podman installé sur l'hôte (bloquant, podman).

Programmes que les commandes et les contrôles du service lancent sur l'hôte, hors des racines gérées : les ajouter à allowed_commands de l'agent (voir Sécurité de l'agent Navin), sinon l'agent les refuse avec command_not_allowed : /usr/bin/curl.

Réseau et ports

Composant	Nom du port	Port	Ouvert dans le pare-feu de l'hôte
app	app	8091/tcp (mode standalone)	non
app	app	8091/tcp (mode replicated)	oui
nginx	web	8090/tcp	oui

Services et connexions nécessaires

• database : postgresql.
• s3 : seaweedfs.

Détail et résolution : voir Dépendances.

Méthodes et modes d'installation

Méthode	Défaut	Ce que la méthode utilise
podman	oui	les images de conteneur du descripteur, exécutées par Podman sous systemd

Composants

Composant	Type	Méthodes d'installation	Ports
Application (app)	maître	podman	8091/tcp (mode standalone), 8091/tcp (mode replicated)
Interface (nginx)	maître	podman	8090/tcp

• nginx ne tourne que sur un hôte qui porte aussi app (mode standalone).

Serveur unique (standalone) (par défaut)

Une application et une interface sur le même hôte, reliées sur le réseau du service.

Ce que le mode déploie :

Composant	Placement
app	min 1, max 1
nginx	min 1, max 1

Répliqué (replicated)

Plusieurs applications sans état qui partagent la base, le compartiment S3 et la clé secrète ; chaque interface répartit sur toutes les applications et le répartiteur de charge répartit les utilisateurs sur les interfaces.

Ce que le mode déploie :

Composant	Placement
app	min 2, recommandé 2
nginx	min 1, recommandé 2

Installer ce service

L'assistant d'installation du Navin Manager planifie, valide et exécute l'installation ; il faut la permission services:install sur le cluster.

1. Ouvrez l'assistant. Dans Clusters, choisissez l'action de ligne Installer des services du cluster cible. L'assistant s'ouvre sur sa première étape, Service.

2. Choisissez le service. À l'étape Service, sélectionnez Label Studio. La carte affiche la licence Apache-2.0 et les dépendances dont l'installation a besoin.

3. Choisissez les hôtes et le mode. À l'étape Hôtes, cochez les hôtes, puis choisissez le Mode : standalone (par défaut), replicated. Chaque mode déploie les composants listés dans Méthodes et modes d'installation. Avec plusieurs composants, placez chacun sur ses hôtes dans Répartition des composants (Proposer un placement propose un placement qui respecte les cardinalités).

4. Liez les dépendances. À l'étape Liaisons, choisissez pour chaque dépendance (database, s3) Installer avec la plateforme ou Utiliser une connexion existante ; une dépendance facultative peut rester sur Aucune liaison.

5. Configurez. À l'étape Configuration, relisez les paramètres (voir Paramètres de configuration). Les mots de passe laissés vides avec une valeur générée par défaut sont générés et scellés par le Manager.

6. Relisez et installez. À l'étape Installation, le Manager valide le plan et affiche l'ordre d'installation ; quand il indique « Le plan est valide. Prêt pour l'installation. », choisissez Installer. Un mode hautement disponible n'est installé que si ses contrôles HA réussissent.

7. Vérifiez. L'opération se termine quand les contrôles de santé de chaque instance réussissent (voir Contrôles de santé) ; le service apparaît alors en marche dans Services.

Connecter un service existant

Schémas	https, http
Port par défaut	8080
Authentification	obligatoire
Contrôle de santé	/health/

Méthode d'authentification	Champs	Description
personal_access_token	password	Jeton d'accès personnel d'un utilisateur de Label Studio (Account & Settings), saisi comme mot de passe : le Manager l'échange sur /api/token/refresh/ contre un jeton d'accès court envoyé en Authorization: Bearer.
legacy_token	api_key	Jeton historique d'un utilisateur, envoyé en Authorization: Token ; les jetons historiques doivent être activés pour l'organisation (Organization, Settings, Access Token Settings).

Documentation officielle : https://labelstud.io/guide/access_tokens

Haute disponibilité

Cluster	réplicas (replication)
Haute disponibilité	externe (external)
Bascule	répartiteur (load-balancer)
Réplication	stockage partagé (shared-store)
Quorum	aucun (none)
Découverte	aucun (none)
Point d'entrée	répartiteur (load-balancer)
Documentation officielle	https://labelstud.io/guide/persistent_storage
Références	https://labelstud.io/guide/storedata, https://labelstud.io/guide/install_k8s, https://labelstud.io/guide/security

Prérequis

Prérequis	Doit être hautement disponible	Modes	Description
database	oui	modes de niveau ha ou cluster	PostgreSQL hautement disponible portant les projets, les annotations et les utilisateurs.
s3	oui	modes de niveau ha ou cluster	Stockage S3 hautement disponible (SeaweedFS en mode distribué) partagé par toutes les applications.

Topologie par mode

Modes	Niveau le plus haut du catalogue	Répartition	Composant du quorum	Domaines de panne	Description
standalone	autonome (standalone)	unique (single)	-	1	Une application et une interface, sans tolérance aux pannes.
replicated	ha (ha)	actif-actif (active-active)	-	2	Applications et interfaces sans état sur des hôtes distincts derrière le répartiteur (HAProxy et keepalived).

Remarques

• Toutes les répliques partagent la clé secrète de l'installation (les sessions sont des cookies signés), la base et le compartiment S3 : n'importe quelle réplique sert n'importe quel utilisateur. Les migrations d'une nouvelle version s'exécutent au démarrage de chaque application sous un verrou de la base (locked_migrate), les répliques peuvent donc démarrer ensemble.
• L'édition Community n'a pas de rôles : chaque membre de l'organisation voit tous les projets. L'accès se contrôle par le lien d'invitation, le réglage d'inscription et la passerelle authentifiante de la plateforme.

Paramètres de configuration

Réseau

Paramètre	Type	Défaut	Valeurs permises	Obligatoire	Secret	Redémarrage	Description
Port de l'interface (port)	port	8090	min 1024	non	non	oui	Port du composant nginx : interface web, API REST et médias (1024 ou plus : nginx tourne sous un utilisateur non root).
Port de l'application (app_port)	port	8091	min 1024	non	non	oui	Port uwsgi du composant app, atteint par nginx uniquement : sur le réseau du service en mode autonome, depuis les autres hôtes du cluster en mode répliqué.
Adresse publique (public_url)	string	(vide)	^(|https?://[A-Za-z0-9.-]+(:[0-9]{1,5})?)$	non	non	oui	Adresse qu'ouvrent les utilisateurs, par exemple https://label-studio.bank.internal derrière la passerelle (LABEL_STUDIO_HOST et CSRF_TRUSTED_ORIGINS) ; en https les cookies sont sécurisés uniquement. Vide : liens relatifs à l'hôte demandé.
TLS (tls_enabled)	bool	false	-	non	non	oui	Servir l'interface, l'API REST et les médias en HTTPS sur le port de l'interface avec un certificat de l'autorité du Manager (nginx de l'image, TLS 1.2 et 1.3, HSTS) ; sans adresse publique, les cookies sont alors sécurisés uniquement et les adresses https des interfaces sont les origines de confiance. Le port uwsgi des applications reste en HTTP : le uwsgi de l'image est compilé sans OpenSSL.

Application

Paramètre	Type	Défaut	Valeurs permises	Obligatoire	Secret	Redémarrage	Description
Processus de travail (workers)	int	4	min 1, max 32	non	non	oui	Processus de travail uwsgi de chaque réplique app. (recommandé clamp(floor(host.cpu_count / 2), 2, 16))
Téléversement maximal (max_upload_mb)	int	200	min 1, max 10240	non	non	oui	Plus grand corps de requête en Mo, pour nginx (client_max_body_size) et l'application (DATA_UPLOAD_MAX_MEMORY_SIZE).
Niveau de journalisation (log_level)	enum	WARNING	DEBUG, INFO, WARNING, ERROR	non	non	non	Verbosité du journal de l'application (LOG_LEVEL), écrit en JSON dans le journal.

Sécurité

Paramètre	Type	Défaut	Valeurs permises	Obligatoire	Secret	Redémarrage	Description
Compte administrateur (admin_email)	string	admin@navin.internal	^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+$	non	non	non	Adresse électronique du premier compte, créé au premier démarrage (LABEL_STUDIO_USERNAME) ; son mot de passe se change ensuite dans l'interface.
Mot de passe administrateur (admin_password)	password	généré	-	non	oui	non	Mot de passe du premier compte (LABEL_STUDIO_PASSWORD), généré à chaque installation et conservé dans le coffre du Manager.
Clé secrète (secret_key)	password	généré	-	non	oui	oui	SECRET_KEY de Django partagée par toutes les répliques : elle signe les cookies de session et les jetons d'accès (la changer déconnecte tous les utilisateurs et révoque les jetons d'accès personnels).
Inscription libre (allow_signup)	bool	false	-	non	non	non	Permettre à quiconque atteint l'interface de créer un compte. Désactivée (LABEL_STUDIO_DISABLE_SIGNUP_WITHOUT_LINK=true) : seul le lien d'invitation de l'organisation inscrit un utilisateur.
Autorités de confiance (trusted_ca_pem)	text	(vide)	(-----BEGIN CERTIFICATE-----\r?\n[A-Za-z0-9+/=\r\n]+-----END CERTIFICATE-----\s*)*	non	non	oui	Certificats PEM des autorités internes qui signent les certificats de la base (sslmode verify-ca ou verify-full) et d'un stockage S3 en https. L'application leur fait confiance en plus des autorités publiques de l'image ; le relais des médias de l'interface leur fait confiance à la place des autorités publiques. Vide : autorités publiques uniquement.
Backends ML internes (allow_local_ml_backends)	bool	false	-	non	non	oui	Permettre aux projets de connecter des backends d'apprentissage automatique (pré-annotation, apprentissage actif) à des adresses privées du réseau interne (ML_BLOCK_LOCAL_IP=false). Désactivé : Label Studio refuse un backend ML qui se résout en une adresse privée ou de bouclage. La protection contre la falsification de requêtes côté serveur des imports par URL, des webhooks et des points d'accès S3 saisis dans un projet reste active.

Dépendances

Pour chaque dépendance active, le Manager prend la première solution parmi : la liaison choisie dans l'assistant ; un service de la même installation qui la fournit ; un service déjà installé dans le cluster ; la seule connexion du type attendu. Sinon, une dépendance facultative reste non liée, et une dépendance obligatoire est ajoutée à l'installation dans son mode par défaut (la colonne ci-dessous nomme le service du catalogue ajouté).

Liaison	Fournie par	Type de connexion	Point d'accès	Facultative	Quand rien n'est lié	Description
database	postgresql	postgresql	sql	non	postgresql est ajouté à l'installation	Base des projets, des tâches, des annotations, des utilisateurs et des organisations.
s3	seaweedfs	s3	s3	non	seaweedfs est ajouté à l'installation	Compartiment des médias téléversés et des exports (stockage persistant partagé par toutes les répliques).

Points d'accès

Point d'accès	Schéma	Composant	Port	Chemin	Paramètre TLS	Paramètres de liaison	Secrets de liaison	Commande de provisionnement
web	http	nginx	8090 (port)	-	tls_enabled	-	-	-

Fichiers de configuration client

Fichiers rendus pour le téléchargement de la configuration client :

• label-studio.env (client.env.j2)

Commandes

Commande	Composant	Cible	Description
Journaux de l'application (logs)	app	hôte choisi	Dernières lignes du journal de l'application (migrations, requêtes en erreur).
Journaux de l'interface (interface_logs)	nginx	hôte choisi	Dernières lignes du journal de nginx (accès en JSON).
Disponibilité (readiness)	app	tous les hôtes	Vérifie que chaque application répond (base atteinte, migrations appliquées).
Versions (version)	app	hôte choisi	Versions de Label Studio, de son interface et de son éditeur telles que l'application en cours d'exécution les donne (GET /api/version/).

Contrôles de santé

Vivacité (par instance)

Composant	Contrôle	Détails
app	HTTP http://127.0.0.1:{{ config.app_port }}/health/	Attendu 200 ; Attendu UP ; 120 tentatives ; intervalle 5 s ; délai 5 s
nginx	HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.ip or '127.0.0.1' }}:{{ config.port }}/nginx_health	Attendu 200 ; 60 tentatives ; intervalle 2 s ; délai 5 s

Disponibilité (contrôle du service)

Contrôle	Détails
HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.ip or '127.0.0.1' }}:{{ config.port }}/health/	Attendu 200 ; Attendu UP ; 10 tentatives ; intervalle 3 s ; délai 10 s

Contrôles préalables

Contrôle	Type	Signification	Sévérité	Composants
memory	memory_mb {"min": 4096}	au moins 4096 Mo de mémoire	avertissement	app
podman	binary {"name": "podman"}	le programme podman installé sur l'hôte	bloquant	tous les composants
port_free	port_free {"param": "port"}	port 8090 libre sur l'hôte	bloquant	nginx
app_port_free	port_free {"param": "app_port"}	port 8091 libre sur l'hôte	bloquant	app

Désinstallation

Chemins supprimés quand les données sont purgées : {{ paths.data }}, {{ paths.log }}.

Liens rapides

• Label Studio : {{ (config.public_url ~ '/') if config.public_url else (('https' if config.tls_enabled else 'http') ~ '://' ~ host.fqdn ~ ':' ~ config.port ~ '/') }}

Documentation amont

• Site : https://labelstud.io
• Sources : https://github.com/HumanSignal/label-studio
• Haute disponibilité : https://labelstud.io/guide/persistent_storage
• Haute disponibilité : https://labelstud.io/guide/storedata
• Haute disponibilité : https://labelstud.io/guide/install_k8s
• Haute disponibilité : https://labelstud.io/guide/security
• Authentification : https://labelstud.io/guide/access_tokens