Table of Contents

🇬🇧 English version

Exécuter Orkeon sur des modèles locaux

Voir aussi : Trois façons d'exécuter Orkeon · les modèles de settings examples/appsettings/ · Fournisseurs LLM · Retour à l'index

Chaque exemple et chaque crew Orkeon peut tourner sur un modèle installé sur votre machine — sans clé API, sans cloud. Trois approches, du zéro-install au tout-embarqué :

Option Où tourne le modèle Idéal pour
Docker Model Runner (DMR) sur l'hôte, port 12434 utilisateurs Docker Desktop — les settings par défaut des conteneurs pointent déjà dessus
Ollama sur l'hôte, port 11434 installations Ollama existantes
Embarqué (--target local-llm) dans l'image ghcr.io/orkeon/orkeon zéro configuration hôte, démos hors-ligne

L'image conteneur ghcr.io/orkeon/orkeon utilise l'option 1 par défaut : ses settings embarqués ciblent host.docker.internal:12434 avec le modèle ai/granite-4.0-h-tiny. Des alternatives prêtes à l'emploi vivent dans /etc/orkeon/profiles et se sélectionnent avec -e ORKEON_LLM_PROFILE=<nom> :

Profil Cible
host-dmr Docker Model Runner sur l'hôte — le défaut embarqué
host-ollama Ollama sur l'hôte (http://host.docker.internal:11434)
openai OpenAI cloud, modèle gpt-4o-mini (à surcharger avec -e ORKEON_Llm__Model=...) — à coupler avec -e ORKEON_Llm__ApiKey=sk-...
local le modèle embarqué (images de l'option 3 uniquement)

orkeon-example settings, dans le conteneur, montre quels settings s'appliquent et pourquoi.

Aucun nom de provider n'apparaît dans ces fichiers : Orkeon choisit le provider d'après l'URL de base. Une URL contenant /engines/ désigne Docker Model Runner, piloté par le dialecte OpenAI (OpenAILlmProvider) ; le port 11434 va au provider Ollama natif (OllamaLlmProvider) ; toute autre adresse est un serveur compatible OpenAI. Un autre serveur de ce type s'écrit avec son chemin /v1 et, s'il ne vérifie aucune clé, "ApiKey": "not-needed" — une adresse sans chemin est lue comme un serveur compatible OpenAI à sa racine, avec un avis qui demande son chemin. Voir la résolution du provider.

Hors conteneur, orkeon init --provider docker-model-runner (ou --provider ollama) écrit les mêmes settings avec localhost à la place de host.docker.internal (http://localhost:12434/engines/llama.cpp/v1, http://localhost:11434), et examples/appsettings/appsettings.docker-model-runner.local.json.example est le modèle pour les runners d'exemples.

Option 1 — Docker Model Runner (recommandé avec Docker Desktop)

# 1. Télécharger un modèle du catalogue Docker (une fois, sur l'HÔTE) :
docker model pull ai/granite-4.0-h-tiny

# 2. Vérifier qu'il est complètement téléchargé — un pull interrompu ne laisse RIEN :
docker model list

# 3. Lancer les exemples — les settings par défaut fonctionnent tels quels :
docker run -it --rm -e ORKEON_ENTRYPOINT=shell -v "$PWD/out:/output" \
  ghcr.io/orkeon/orkeon
# puis dans le shell :
orkeon-example run 1

Pièges :

  • Tags du catalogue : docker model pull résout dans le catalogue Docker Hub ai/. Un tag absent du catalogue échoue avec 404 Not Found: Model not found — p. ex. ai/gemma4 existe, un ai/gemma4:128K inventé non. Vérifiez sur https://hub.docker.com/u/ai ou avec docker model list.
  • Pulls interrompus : un docker model pull annulé ne laisse rien, et docker model configure sur un modèle absent échoue silencieusement. Confirmez toujours avec docker model list avant de configurer.
  • Identifiants de modèles : DMR annonce les modèles sous leur identifiant complet (docker.io/ai/granite-4.0-h-tiny:latest). Les settings Orkeon peuvent utiliser la forme courte (ai/granite-4.0-h-tiny) — le préflight du conteneur matche par sous-chaîne et le serveur accepte les deux.
  • Grammaire : les profils DMR posent "Llm": { "Grammar": true }, si bien qu'un livrable structured_output atteint le moteur llama.cpp sous forme de grammar GBNF. Un fichier de réglages à vous pointé sur DMR (ou llama-server) la pose aussi ; sans elle la grammaire est abandonnée avec un avertissement qui nomme la clé.

Changer de modèle

# lancer n'importe quel modèle téléchargé sans toucher aux fichiers de settings :
docker run -it --rm -e ORKEON_ENTRYPOINT=shell \
  -e ORKEON_Llm__Model=gemma4 \
  ghcr.io/orkeon/orkeon

Les variables d'environnement ORKEON_Llm__* écrasent tous les fichiers de settings (ce sont des overrides de configuration .NET), donc -e ORKEON_Llm__Model=… se combine avec n'importe quel profil. docker model list sur l'hôte montre les noms utilisables.

Fenêtres de contexte plus grandes

DMR sert chaque modèle avec sa taille de contexte par défaut. L'augmenter (p. ex. à 128K pour gemma4) est une configuration runtime par modèle — mais l'outillage autour est trompeusement muet : suivez la procédure ci-dessous et vérifiez toujours avec configure show, jamais avec docker model list ni inspect (tous deux ne montrent que les métadonnées de packaging ; la colonne CONTEXT reste vide même quand la config runtime est appliquée, et configure lui-même n'affiche rien, succès comme échec).

Étape 1 — tenter la configuration directe :

docker model configure --context-size 131072 gemma4
docker model configure show gemma4

Si configure show affiche le réglage, c'est terminé :

[
  {
    "Backend": "llama.cpp",
    "Model": "docker.io/ai/gemma4:latest",
    "Mode": "completion",
    "Config": { "context-size": 131072 }
  }
]

Étape 2 — si configure show n'affiche rien (ou échoue) : passer par docker model tag. Le tag duplique instantanément un modèle installé (sans re-téléchargement) et fournit une référence à laquelle la configuration s'accroche de façon fiable. Déroulé complet avec gemma4 :

# 1. le modèle doit être ENTIÈREMENT téléchargé — un pull interrompu ne laisse
#    rien, et configure/tag sont silencieux ou échouent sur un modèle absent
docker model list                     # gemma4 doit apparaître avec sa taille

# 2. le dupliquer sous un alias dédié grand-contexte
docker model tag gemma4 gemma4:128K
#    -> Model "gemma4" tagged successfully with "gemma4:128K"

# 3. configurer l'alias
docker model configure --context-size 131072 gemma4:128K

# 4. VÉRIFIER — la seule commande qui montre la config runtime
docker model configure show gemma4:128K
#    -> "Config": { "context-size": 131072 }

Puis lancez vos crews avec le nom du modèle :

docker run -it --rm -e ORKEON_ENTRYPOINT=shell \
  -e ORKEON_Llm__Model=gemma4 \
  -v "$PWD/out:/output" ghcr.io/orkeon/orkeon

Note : configure show rapporte la configuration sur la référence canonique (docker.io/ai/gemma4:latest) — elle est indexée par l'ID du modèle, que les deux tags partagent, donc le réglage s'applique à tous les tags du même modèle ; -e ORKEON_Llm__Model=gemma4 en bénéficie.

Étape 3 — vérité terrain (optionnelle mais définitive) : demander à llama.cpp lui-même. Déclenchez une première requête (chargement à la demande), puis lisez le n_ctx servi :

curl -s -X POST http://host.docker.internal:12434/engines/llama.cpp/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gemma4","messages":[{"role":"user","content":"hi"}],"max_tokens":1}' > /dev/null
curl -s http://host.docker.internal:12434/engines/llama.cpp/v1/models | grep -o '"n_ctx[^,]*'

(depuis un conteneur ; sur l'hôte utilisez localhost:12434.)

Si votre version de Docker Desktop n'a pas ces commandes du tout, passez par l'UI Desktop (Models → modèle → réglages) ou par la variante embarquée avec --build-arg LOCAL_MODEL_CTX=131072 (option 3 ci-dessous), où la taille de contexte est entièrement sous votre contrôle.

Deux notions à ne pas confondre :

  • La taille de contexte est une propriété côté serveur (ce que le modèle peut lire) ; un cache KV à 128K coûte plusieurs Go de RAM en plus sur l'hôte.
  • Llm:MaxTokens dans les settings Orkeon plafonne uniquement la réponse — indépendant de la taille de contexte. Chaque profil local livré par Orkeon le fixe à 4096, ce qui est aussi la valeur de repli d'une valeur non fixée sur Docker Model Runner (aucun plafond documenté pour un modèle local) ; sur Ollama, une valeur non fixée n'envoie aucun num_predict, et le modèle écrit jusqu'à son contexte (voir les plafonds de sortie).

Concurrence : gardez MaxConcurrentRequests à 1

Un serveur d'inférence local sature la machine avec une seule requête ; deux agents en parallèle doublent la mémoire du cache KV et font thrasher le CPU/GPU au lieu d'accélérer quoi que ce soit. Tous les profils locaux livrés par Orkeon épinglent donc le rate limiter :

"RateLimiting": { "MaxConcurrentRequests": 1 }

Les cinq clés de la section, avec leurs défauts, sont dans la référence de configuration. Si vous écrivez votre propre fichier de settings, conservez ce bloc — absent ou à 0, la concurrence est ILLIMITÉE (le limiteur ne s'active que pour les valeurs > 0), et les crews parallèles ou consensuels ouvriront joyeusement une connexion par agent. Ne l'augmentez que pour les fournisseurs cloud (les templates cloud livrés utilisent 2-16).

Option 2 — Ollama sur l'hôte

ollama pull llama3.2          # sur l'hôte
docker run -it --rm -e ORKEON_ENTRYPOINT=shell \
  -e ORKEON_LLM_PROFILE=host-ollama \
  ghcr.io/orkeon/orkeon

Le profil host-ollama cible http://host.docker.internal:11434 (le port 11434 route vers le provider Ollama natif d'Orkeon). Changez de modèle avec -e ORKEON_Llm__Model=<nom> si vous avez téléchargé autre chose.

Sur un moteur Linux nu (sans Docker Desktop), host.docker.internal n'existe pas — ajoutez --add-host=host.docker.internal:host-gateway au docker run.

Option 3 — Embarquer le modèle dans l'image

Construisez une variante qui ne demande aucun serveur côté hôte : le llama-server de llama.cpp et un GGUF sont embarqués et servis dans le conteneur avec la même forme d'URL que DMR — zéro changement de settings. Les recettes vivent au stage local-llm de Dockerfile.runners. Il est linux/amd64 seulement (le llama.cpp embarqué est un build x64) : sur une machine arm64, ajoutez --platform linux/amd64 au docker build, et il tourne sous émulation.

# Granite 4.0 h-tiny (Apache 2.0, ~4,2 Go de poids → image ~6 Go)
docker build -f Dockerfile.runners --target local-llm \
  --build-arg LOCAL_MODEL_URL=https://huggingface.co/ibm-granite/granite-4.0-h-tiny-GGUF/resolve/main/granite-4.0-h-tiny-Q4_K_M.gguf \
  -t orkeon:granite .

# Gemma 4 E4B avec un contexte 128K (licence Gemma — gardez l'image locale)
docker build -f Dockerfile.runners --target local-llm \
  --build-arg LOCAL_MODEL_URL=https://huggingface.co/unsloth/gemma-4-E4B-it-qat-GGUF/resolve/main/gemma-4-E4B-it-qat-UD-Q4_K_XL.gguf \
  --build-arg LOCAL_MODEL_NAME=ai/gemma4 \
  --build-arg LOCAL_MODEL_CTX=131072 \
  -t orkeon:gemma4 .

docker run -it --rm -m 8g -e ORKEON_ENTRYPOINT=shell orkeon:granite

Le serveur écoute sur 127.0.0.1:12434 avec le préfixe /engines/llama.cpp ; le profil local, matérialisé au build, devient les settings embarqués par défaut. Au démarrage, l'entrypoint le lance et attend le chargement du modèle (30 à 90 s).

Argument de build Défaut Rôle
LOCAL_MODEL_URL — (obligatoire) le GGUF à télécharger au build
LOCAL_MODEL_NAME ai/granite-4.0-h-tiny l'identifiant de modèle qu'annoncent les settings et le serveur
LOCAL_MODEL_SHA256 vide somme de contrôle facultative du GGUF, vérifiée au build (recommandée pour des builds reproductibles)
LOCAL_MODEL_CTX 8192 la taille de contexte par défaut, bakée dans l'image
LLAMA_CPP_BUILD b9972 la release llama.cpp dont le llama-server est embarqué
  • Surchargez la taille de contexte au run avec -e ORKEON_LOCAL_LLM_CTX=….
  • -e ORKEON_LOCAL_LLM=0 démarre le conteneur sans le serveur embarqué.
  • Inférence CPU : comptez ~5-15 tokens/s ; donnez de la mémoire au conteneur (-m 8g, plus à grand contexte — sur WSL2, augmentez .wslconfig).
  • Ces variantes sont à construire soi-même par conception : aucun tag pré-construit n'est publié, les obligations de licence des poids (notamment Gemma) restent de votre côté.

Dépannage

Symptôme Cause Correctif
docker model pull …: 404 Not Found tag absent du catalogue ai/ vérifier le catalogue / docker model list ; ai/gemma4 existe, pas les tags inventés
orkeon-example: cannot reach the LLM endpoint pas de serveur sur l'hôte / moteur Linux démarrer DMR ou Ollama ; sur Linux ajouter --add-host=host.docker.internal:host-gateway
endpoint … is up, but it does not serve the configured model modèle non téléchargé (ou nom différent) le message imprime le docker model pull exact et les modèles réellement servis
LLM API Error (NotFound): model not found en plein crew préflight sauté (ORKEON_SKIP_PREFLIGHT=1 ou orkeon run direct) mêmes correctifs que ci-dessus
docker model configure semble ne rien faire configure est toujours silencieux ; le modèle peut être absent, ou votre version de Desktop peut ignorer le flag docker model list d'abord ; puis vérifier avec le n_ctx servi (voir plus haut) — pas avec la colonne CONTEXT
le crew « réussit » mais invente un contenu sans rapport avec les documents fournis le data/ de l'exemple n'était pas monté utiliser orkeon-example run (le monte automatiquement) plutôt qu'un orkeon run nu
Access denied … Mounts granting Write: /output le modèle a écrit hors de /output ce message lui permet de se corriger à l'itération suivante ; seul /output est inscriptible
très lent / OOM à 128K de contexte mémoire du cache KV réduire le contexte, ou augmenter la mémoire conteneur/VM