LLaMA-Factory (llama-factory)
Affinage de modèles de langage et de modèles de vision publics et privés (LLM et VLM : texte, images, vidéo) sur les GPU NVIDIA de l'hôte : SFT, LoRA, QLoRA (4 et 8 bits, bitsandbytes installé par la commande install_qlora), DPO, KTO, modèles de récompense et PPO. L'interface web LLaMA Board lance, suit et évalue les entraînements, le Manager exécute des configurations d'entraînement relues, et les modèles fusionnés sont exportés pour être servis par vLLM derrière LiteLLM. Hors ligne : les modèles de base, les jeux de données et les entraînements restent sur l'hôte.
Généré depuis catalog/services/llama-factory.yaml : ne pas modifier à la main.
Résumé
| Version | 0.9.5 |
| Usage | installer et configurer, configurer et connecter |
| Couche | fonctionnelle (catalogue IA) |
| Catégorie | Évaluation et exploitation des LLM |
| 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 | L'image embarque les bibliothèques d'exécution CUDA de PyTorch, sous la licence CUDA de NVIDIA comme l'image de vLLM, tandis que le pilote NVIDIA reste sur l'hôte (LEX-011) ; les poids affinés gardent la licence de leur modèle de base (LEX-012). QLoRA installe bitsandbytes (MIT), épinglé par version et sha256. |
| Composant de la plateforme | llama-factory |
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/hiyouga/llamafactory | 0.9.5 | Apache-2.0 | clé d'image llamafactory, utilisée par board, condensé sha256:c5e769e047a19f9322800c9881a6270557ef0e6682f0145b50b322f8724de6b6 |
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.
GPU : GPU NVIDIA donnés au composant comme périphériques CDI (nvidia.com/gpu) : board.
Prérequis
Hôte
- au moins 16384 Mo de mémoire (bloquant,
memory). - au moins 1 GPU NVIDIA avec 8000 Mo de mémoire (bloquant,
gpu). - le programme
podmaninstallé sur l'hôte (bloquant,podman). - au moins 102400 Mo libres pour
/var/lib/navin(avertissement,data_disk).
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/nvidia-smi, /usr/bin/podman.
Réseau et ports
| Composant | Nom du port | Port | Ouvert dans le pare-feu de l'hôte |
|---|---|---|---|
board | board | 7860/tcp | oui |
Services et connexions nécessaires
Ce service n'a aucune dépendance.
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 |
|---|---|---|---|
LLaMA Board (board) | maître | podman | 7860/tcp |
Hôte GPU unique (single) (par défaut)
Une interface qui entraîne sur les GPU d'un hôte (plusieurs GPU de l'hôte par torchrun).
Ce que le mode déploie :
| Composant | Placement |
|---|---|
board | min 1, max 1 |
Plusieurs hôtes d'entraînement (multi-host)
Une interface par hôte GPU, chacune entraînant sur les GPU de son propre hôte avec ses modèles, ses jeux de données et ses entraînements ; les entraînements d'équipes distinctes tournent côte à côte.
Ce que le mode déploie :
| Composant | Placement |
|---|---|
board | min 2, 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.
-
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.
-
Choisissez le service. À l'étape Service, sélectionnez LLaMA-Factory. La carte affiche la licence
Apache-2.0. -
Choisissez les hôtes et le mode. À l'étape Hôtes, cochez les hôtes, puis choisissez le Mode :
single(par défaut),multi-host. Chaque mode déploie les composants listés dans Méthodes et modes d'installation. -
Liaisons. Ce service n'a aucune dépendance : l'étape Liaisons n'a rien à lier.
-
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.
-
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.
-
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 | 7860 |
| Authentification | aucune |
| Contrôle de santé | / |
| Méthode d'authentification | Champs | Description |
|---|---|---|
none | - | LLaMA Board n'a pas d'authentification propre : la publier derrière la passerelle authentifiante de la plateforme. |
Documentation officielle : https://llamafactory.readthedocs.io/en/latest/getting_started/webui.html
Haute disponibilité
| Cluster | aucun (none) |
| Haute disponibilité | aucun (none) |
| Bascule | aucun (none) |
| Réplication | aucun (none) |
| Quorum | aucun (none) |
| Découverte | aucun (none) |
| Point d'entrée | par hôte (per-host) |
| Documentation officielle | https://llamafactory.readthedocs.io/en/latest/getting_started/webui.html |
| Références | https://github.com/hiyouga/LLaMA-Factory/tree/v0.9.5/docker/docker-cuda |
Topologie par mode
| Modes | Niveau le plus haut du catalogue | Répartition | Composant du quorum | Domaines de panne | Description |
|---|---|---|---|---|---|
single | autonome (standalone) | unique (single) | - | 1 | Un hôte d'entraînement, sans tolérance aux pannes. |
multi-host | autonome (standalone) | par hôte (per-host) | - | 2 | Hôtes d'entraînement indépendants, chacun atteint à sa propre adresse. |
Remarques
- Un entraînement est un traitement par lots : il s'arrête avec son hôte ou son interface et reprend depuis le dernier point de contrôle de son output_dir (resume_from_checkpoint). L'entraînement multi nœud (torchrun entre hôtes) n'est pas déployé par le catalogue : il demande le réseau de l'hôte pour NCCL.
Paramètres de configuration
Modèles et données
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|---|---|---|---|---|---|---|
Hors ligne (offline) | bool | true | - | non | non | oui | Ne jamais télécharger depuis l'interface (HF_HUB_OFFLINE, TRANSFORMERS_OFFLINE, HF_DATASETS_OFFLINE) : les modèles de base et les jeux de données doivent déjà être sur l'hôte. Obligatoire pour un hôte de production sans Internet. |
Miroir du dépôt de modèles (hf_endpoint) | string | (vide) | ^(|https?://[A-Za-z0-9.-]+(:[0-9]{1,5})?(/[A-Za-z0-9._~/-]*)?)$ | non | non | non | Miroir interne compatible Hugging Face utilisé par download_model (HF_ENDPOINT), vide pour huggingface.co. |
Jeton du dépôt (hf_token) | password | - | - | non | oui | non | Jeton des modèles à accès restreint ou privés du dépôt (HF_TOKEN), facultatif. |
Index des paquets Python (pip_index_url) | string | https://pypi.org/simple | ^https?://[A-Za-z0-9.-]+(:[0-9]{1,5})?(/[A-Za-z0-9._~/-]*)?$ | non | non | non | Index compatible PyPI (miroir interne) depuis lequel install_qlora télécharge la roue épinglée de bitsandbytes, vérifiée par son sha256 ; inutilisé quand la roue est copiée dans /var/lib/navin/llama-factory/wheels de l'hôte. |
Hôte GPU
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|---|---|---|---|---|---|---|
GPU (gpu_devices) | string | all | ^(all|[A-Za-z0-9-]+(,[A-Za-z0-9-]+)*)$ | non | non | oui | GPU donnés à l'interface et à ses entraînements : all, ou une liste d'index ou d'UUID séparés par des virgules (les GPU gardés pour vLLM restent à l'écart). |
Mémoire partagée (shm_size) | string | 16g | ^[0-9]+[mg]$ | non | non | oui | Taille de /dev/shm du conteneur, utilisée par les chargeurs de données et par NCCL entre les GPU de l'hôte. |
Réseau
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|---|---|---|---|---|---|---|
Port de l'interface (port) | port | 7860 | min 1024 | non | non | oui | Port de LLaMA Board (Gradio). L'interface n'a pas d'authentification propre : la publier derrière la passerelle authentifiante de la plateforme. |
TLS (tls_enabled) | bool | false | - | non | non | oui | Servir LLaMA Board en TLS avec le certificat que le Manager émet pour l'hôte depuis son autorité : l'interface est alors lancée par un court lanceur exécuté par le Python de l'image (launch de Gradio avec ssl_certfile et ssl_keyfile) au lieu de llamafactory-cli webui, avec la même interface. |
Niveau de journalisation (log_level) | enum | INFO | DEBUG, INFO, WARNING, ERROR | non | non | non | Verbosité de LLaMA-Factory (LLAMAFACTORY_VERBOSITY). |
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 |
|---|---|---|---|---|---|---|---|---|
board | http | board | 7860 (port) | - | tls_enabled | - | - | - |
Commandes
| Commande | Composant | Cible | Description |
|---|---|---|---|
Journaux de l'interface (logs) | board | hôte choisi | Dernières lignes du journal de l'interface et des entraînements qu'elle a lancés. |
Télécharger un modèle (download_model) | board | tous les hôtes | Télécharge les poids d'un modèle Hugging Face dans le cache de chaque hôte du service (depuis huggingface.co ou le miroir interne) ; l'interface le trouve ensuite hors ligne par son identifiant. |
Activer QLoRA (install_qlora) | board | tous les hôtes | Installe bitsandbytes 0.50.2 (MIT), nécessaire à QLoRA (quantification 4 et 8 bits du modèle de base pendant l'entraînement) et absent de l'image officielle, sur chaque hôte du service : la roue est vérifiée par son sha256 épinglé et va dans /var/lib/navin/llama-factory/python, monté en lecture seule dans l'interface. Elle vient du dossier wheels de l'hôte quand elle y a été copiée (hôte sans accès à un index), sinon de l'index des paquets Python du service. Sans redémarrage : les entraînements suivants la trouvent. |
Lancer un entraînement (train) | board | hôte choisi | Lance llamafactory-cli train en arrière-plan avec une configuration relue du dossier configs de l'hôte (/var/lib/navin/llama-factory/configs, /app/configs dans l'interface) ; sa sortie va dans un journal de /app/saves/navin-runs (commandes runs et run_log). Un redémarrage de l'interface arrête les entraînements en cours : ils reprennent depuis leur dernier point de contrôle. |
Exporter un modèle (export) | board | hôte choisi | Lance llamafactory-cli export en arrière-plan avec une configuration du dossier configs (fusion de l'adaptateur dans son modèle de base, export_dir sous /app/output) ; sa sortie va dans un journal de /app/saves/navin-runs. |
Publier dans vLLM (publish_to_vllm) | board | hôte choisi | Copie un modèle exporté (dossier de /app/output) dans les poids importés du vLLM installé sur le même hôte (/var/lib/navin/vllm/models/local/<nom>). Régler ensuite les paramètres de vLLM model_source sur local et model sur <nom>, puis appliquer : LiteLLM enregistre le modèle par sa liaison. Autre hôte : y copier d'abord le dossier. |
Publier dans Ollama (publish_to_ollama) | board | hôte choisi | Copie un modèle exporté (dossier de /app/output) dans le dossier d'import de l'Ollama installé sur le même hôte (/var/lib/navin/ollama/import/<nom>). Lancer ensuite la commande Ollama import_safetensors et ajouter le modèle à litellm_models. Autre hôte : y copier d'abord le dossier. |
Entraînements (runs) | board | hôte choisi | Journaux des entraînements et des exports lancés par le Manager, du plus récent au plus ancien, puis les journaux d'entraînement (trainer_log.jsonl) de l'interface et du Manager sous /app/saves et /app/output. |
Journal d'un entraînement (run_log) | board | hôte choisi | 200 dernières lignes d'un journal de /app/saves/navin-runs (nom donné par runs). |
Environnement (env) | board | hôte choisi | Versions de LLaMA-Factory, PyTorch, Transformers, CUDA et GPU vus par l'interface (llamafactory-cli env). |
État des GPU (gpu_status) | board | tous les hôtes | Utilisation, mémoire et température des GPU de chaque hôte (nvidia-smi). |
Paramètres des commandes
| Commande | Paramètre | Type | Défaut | Obligatoire | Description |
|---|---|---|---|---|---|
download_model | Dépôt (repo) | string | - | oui | Identifiant Hugging Face, par exemple Qwen/Qwen3-8B. |
download_model | Révision (revision) | string | main | non | Branche, étiquette ou commit des poids validés. |
train | Configuration (config) | string | - | oui | Nom du fichier de configuration YAML du dossier configs, par exemple qwen3-lora-sft.yaml. |
export | Configuration (config) | string | - | oui | Nom du fichier de configuration d'export YAML du dossier configs. |
publish_to_vllm | Dossier exporté (export) | string | - | oui | Nom du dossier export_dir sous /app/output. |
publish_to_vllm | Dossier du modèle (name) | string | - | oui | Nom du dossier sous les poids importés de vLLM. |
publish_to_ollama | Dossier exporté (export) | string | - | oui | Nom du dossier export_dir sous /app/output. |
publish_to_ollama | Dossier d'import (name) | string | - | oui | Nom du dossier sous le dossier d'import d'Ollama. |
run_log | Journal (name) | string | - | oui | Nom du fichier du journal, par exemple qwen3-lora-sft-20261102-093000-train.log. |
Contrôles de santé
Vivacité (par instance)
| Composant | Contrôle | Détails |
|---|---|---|
board | HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn if config.tls_enabled else (host.ip or '127.0.0.1') }}:{{ config.port }}/ | Attendu 200 ; 90 tentatives ; intervalle 5 s ; délai 5 s |
Disponibilité (contrôle du service)
| Contrôle | Détails |
|---|---|
HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn if config.tls_enabled else (host.ip or '127.0.0.1') }}:{{ config.port }}/ | Attendu 200 ; 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": 16384} | au moins 16384 Mo de mémoire | bloquant | tous les composants |
gpu | gpu {"min_count": 1, "min_memory_mb": 8000} | au moins 1 GPU NVIDIA avec 8000 Mo de mémoire | bloquant | tous les composants |
podman | binary {"name": "podman"} | le programme podman installé sur l'hôte | bloquant | tous les composants |
data_disk | disk_free_mb {"path": "/var/lib/navin", "min": 102400} | au moins 102400 Mo libres pour /var/lib/navin | avertissement | tous les composants |
port_free | port_free {"param": "port"} | port 7860 libre sur l'hôte | bloquant | tous les composants |
Désinstallation
Chemins supprimés quand les données sont purgées : {{ paths.data }}, {{ paths.log }}.
Liens rapides
- LLaMA Board :
{{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.port }}/
Documentation amont
- Site : https://llamafactory.readthedocs.io
- Sources : https://github.com/hiyouga/LLaMA-Factory
- Haute disponibilité : https://llamafactory.readthedocs.io/en/latest/getting_started/webui.html
- Haute disponibilité : https://github.com/hiyouga/LLaMA-Factory/tree/v0.9.5/docker/docker-cuda
- Authentification : https://llamafactory.readthedocs.io/en/latest/getting_started/webui.html