Llama-swap

Installation

Debian

# apt update && apt upgrade
# apt install -y nodejs npm golang-go
# cd /opt
# git clone https://github.com/mostlygeek/llama-swap.git
# cd llama-swap
# make clean all

• On crée le service SystemD :

# vi /etc/systemd/system/llama-swap.service

[Unit]
Description=llama-swap
After=network.target

[Service]
Type=simple
ExecStart=/opt/llama-swap/build/llama-swap-linux-amd64 --config /etc/llama-swap/config.yaml --listen 0.0.0.0:8080
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable --now llama-swap

Configuration

• Si nécessaire, on crée le dossier :

 # mkdir /etc/llama-swap

• On édite le fichier de configuration :

# vi /etc/llama-swap/config.yaml

• Exemple de configuration de base :

apiKeys:
  - "CLE_API_1"
  - "CLE_API_2"

logLevel: info

healthCheckTimeout: 500

globalTTL: 0

unloadTimeout: 10

logToStdout: both

Les options globales se placent au début du fichier, avant la section models:.

Groupes de modèles

Llama-swap peut gérer plusieurs modèles derrière une seule instance et un seul port d'accès.

Les modèles restent définis normalement sous la section :

models:
  "Gemma4-31B":
    name: "Gemma4-31B"
    cmd: |
      ...

  "Gemma4-26B":
    name: "Gemma4-26B"
    cmd: |
      ...

  "Aux":
    name: "Petit modèle auxiliaire"
    cmd: |
      ...

La partie de routage est séparée de la définition des modèles.

Les clients continuent à utiliser la même URL, par exemple :

https://serveur.example/v1

Le modèle demandé est sélectionné avec le champ :

{
  "model": "Gemma4-31B"
}

Llama-swap démarre alors le backend correspondant et lui attribue un port interne via ${PORT}.

Plusieurs modèles peuvent être actifs simultanément si la configuration de routage l'autorise.

Groupes

Le mode group permet de répartir les modèles dans plusieurs groupes.

Par exemple, un groupe contenant les gros modèles principaux :

routing:
  router:
    use: group
    settings:
      groups:
        main:
          swap: true
          exclusive: false
          members:
            - Gemma4-31B
            - Gemma4-26B
            - Qwen3.8-27B

Avec :

swap: true

un seul modèle de ce groupe est conservé à la fois.

Ainsi, si Gemma4-31B est chargé et qu'une requête demande Gemma4-26B, llama-swap peut décharger le premier puis charger le second.

Il est possible de créer un second groupe pour les modèles auxiliaires :

routing:
  router:
    use: group
    settings:
      groups:
        main:
          swap: true
          exclusive: false
          members:
            - Gemma4-31B
            - Gemma4-26B

        auxiliary:
          swap: true
          exclusive: false
          members:
            - Qwen3-1.7B
            - Qwen3-4B

On obtient alors deux groupes indépendants :

Groupe principal :
  Gemma4-31B
  OU
  Gemma4-26B

Groupe auxiliaire :
  Qwen3-1.7B
  OU
  Qwen3-4B

Si les groupes ne sont pas exclusifs entre eux, une combinaison telle que :

Gemma4-31B + Qwen3-1.7B

peut rester chargée simultanément.

Cela est utile pour un agent utilisant :

• un gros modèle principal ;
• un petit modèle pour la génération de titres ;
• un petit modèle pour certaines tâches auxiliaires.

Exemple :

État initial :
Gemma4-31B + Qwen3-1.7B

Nouvelle requête :
Gemma4-26B

Résultat :
Gemma4-31B est déchargé
Gemma4-26B est chargé
Qwen3-1.7B reste chargé

Le mode groupes est adapté lorsque l'organisation souhaitée peut être représentée simplement sous forme de plusieurs ensembles indépendants.

Matrix

Le mode matrix permet un contrôle plus précis des combinaisons de modèles autorisées.

Contrairement aux groupes, on ne décrit plus seulement des familles de modèles : on décrit directement quelles combinaisons peuvent coexister.

Le routeur est activé avec :

routing:
  router:
    use: matrix

Une matrice peut par exemple autoriser :

Gemma4-31B + Aux
OU
Gemma4-26B + Aux
OU
Vision + Aux

tout en interdisant :

Gemma4-31B + Gemma4-26B
Gemma4-31B + Vision
Gemma4-26B + Vision

Exemple :

routing:
  router:
    use: matrix
    settings:
      matrix:
        vars:
          g31: Gemma4-31B
          g26: Gemma4-26B
          aux: Qwen3-1.7B
          vis: Qwen3-VL-4B

        sets:
          main31: "g31 & aux"
          main26: "g26 & aux"
          vision: "vis & aux"

Les variables permettent d'utiliser des noms courts dans les expressions :

vars:
  g31: Gemma4-31B
  aux: Qwen3-1.7B

Puis les combinaisons sont décrites dans sets :

sets:
  main31: "g31 & aux"

Le symbole & indique que les deux modèles peuvent faire partie de la même combinaison autorisée.

Le symbole | permet d'exprimer une alternative.

Par exemple :

sets:
  normal: "(g31 | g26) & aux"

Cela représente :

Gemma4-31B OU Gemma4-26B
+
Aux

Le modèle auxiliaire peut donc rester chargé pendant que llama-swap remplace le modèle principal.

Coût d'éviction

Matrix permet également d'attribuer un coût à l'éviction d'un modèle.

Exemple :

evict_costs:
  g31: 20
  g26: 20
  aux: 1

Un modèle long à charger peut recevoir un coût élevé.

Un petit modèle rapide à recharger peut recevoir un coût faible.

Lorsque plusieurs solutions sont possibles, llama-swap peut ainsi privilégier celle qui évite de décharger les modèles les plus coûteux.

Exemple :

Gemma4-31B : coûteux à recharger
Aux         : rapide à recharger

On peut donc attribuer :

evict_costs:
  g31: 20
  aux: 1

Exemple pratique

Supposons les modèles suivants :

models:
  "Gemma4-31B":
    cmd: |
      ...

  "Gemma4-26B":
    cmd: |
      ...

  "Aux":
    cmd: |
      ...

  "CrispASR":
    cmd: |
      ...

On souhaite :

• permettre un gros LLM avec le modèle auxiliaire ;
• remplacer librement le gros LLM ;
• ne pas charger deux gros LLM simultanément ;
• empêcher CrispASR de fonctionner en même temps qu'un gros modèle si la VRAM est insuffisante.

Conceptuellement :

Autorisé :

Gemma4-31B + Aux
Gemma4-26B + Aux
CrispASR + Aux

Interdit :

Gemma4-31B + Gemma4-26B
Gemma4-31B + CrispASR
Gemma4-26B + CrispASR

Dans ce cas, Matrix est généralement plus adapté que de simples groupes.

Groupes ou Matrix ?

Le mode group est généralement suffisant lorsque les modèles peuvent être organisés simplement en plusieurs familles indépendantes.

Exemple :

1 gros LLM parmi plusieurs
+
1 petit modèle auxiliaire parmi plusieurs

Le mode matrix est préférable lorsque les règles deviennent plus complexes.

Exemple :

Gemma31 peut coexister avec Aux
Gemma26 peut coexister avec Aux
CrispASR peut coexister avec Aux
mais aucun gros modèle ne peut coexister avec CrispASR

Matrix permet alors d'exprimer directement les contraintes de RAM, de VRAM et d'utilisation des GPU.

Il n'est pas nécessaire de lancer plusieurs instances de llama-swap : une seule instance peut gérer plusieurs modèles actifs simultanément, tous accessibles via le même port externe.

Exemples de modèles

Qwen3.8-27B-GGUF Context 144384 Kvarn6/Kvarn6 (2x 12 Go de VRAM) Spécialiste codeur lent

...
models:
  "Qwen3.8-27B":
    name: "Qwen3.8-27B"
    capabilities:
      in:
        - text
        - image
      out:
        - text
      tools: true
      context: 144384

    cmd: |
      /opt/beellama.cpp/build/bin/llama-server
      -m /opt/models/Qwen3.8-27B/UD-Q4_K_XL/Qwen3.8-27B-UD-Q4_K_XL.gguf
      --mmproj /opt/models/Qwen3.8-27B/UD-Q4_K_XL/mmproj-BF16.gguf
      --no-mmproj-offload
      --image-min-tokens 1024
      -ngl 999
      -sm tensor
      -ts 1/1
      -t 4
      -tb 4
      -b 1024
      -ub 1024
      -c 144384
      -np 1
      -fa on
      --load-mode none
      -ctk kvarn6
      -ctv kvarn6
      --kv-tail-tokens 1024
      --spec-type ngram-mod,draft-mtp
      --spec-ngram-mod-n-match 24
      --spec-ngram-mod-n-min 12
      --spec-ngram-mod-n-max 48
      --spec-draft-n-max 3
      --spec-draft-n-min 0
      --spec-draft-p-min 0.75
      --reasoning on
      --reasoning-preserve
      --jinja
      --chat-template-file /opt/models/Qwen-Fixed-Chat-Templates/chat_template.jinja
      --chat-template-kwargs '{"preserve_thinking": true}'
      --reasoning-format deepseek
      --reasoning-budget 16192
      --reasoning-budget-message "D'accord, assez réfléchi, plus d'attente. Passons à l'action."
      --slot-save-path /kv_cache/
      --temp 1.0
      --top-k 20
      --top-p 0.95
      --min-p 0.0
      --presence-penalty 0.0
      --repeat-penalty 1.0
      --host 127.0.0.1
      --port ${PORT}

gemma-4-31B-it-qat-GGUF Context 32768 pour traduction (2x 12 Go de VRAM) Spécialiste traduction

...
models:
  "traducteur":
    name: "Gemma4-31B-QAT"
    capabilities:
      in:
        - text
      out:
        - text
      tools: true
      context: 32768

    cmd: |
      env LLAMA_GRAPH_REUSE_DISABLE=1 /opt/llama.cpp/build/bin/llama-server
      -m /opt/models/gemma-4-31B-it-qat/UD-Q4_K_XL/gemma-4-31B-it-qat-UD-Q4_K_XL.gguf
      --host 127.0.0.1
      --port ${PORT}
      -ngl 999
      -sm tensor
      --tensor-split 1,1
      -c 32768
      -ctk q8_0
      -ctv q8_0
      -np 1
      -b 1024
      -ub 1024
      -fa on
      --jinja
      --reasoning off
      --spec-type ngram-mod,draft-mtp
      --spec-ngram-mod-n-match 24
      --spec-ngram-mod-n-min 12
      --spec-ngram-mod-n-max 48
      --spec-draft-model /opt/models/gemma-4-31B-it-qat/UD-Q4_K_XL/MTP/mtp-gemma-4-31B-it-Q8_0.gguf
      --spec-draft-n-max 4
      --spec-draft-n-min 0
      --spec-draft-p-min 0.75
      --slot-save-path /kv_cache/
      --temp 1.0
      --top-p 0.95
      --top-k 64
      --min-p 0.0
      --presence-penalty 0.0
      --repeat-penalty 1.0

gemma-4-26B-A4B-it-qat-GGUF (2x 12 Go VRAM) Généraliste rapide

# hf download unsloth/gemma-4-26B-A4B-it-qat-GGUF --include "*UD-Q4_K_XL*.gguf" --include "*mtp*Q8_0*.gguf" --include "*mmproj-BF16*.gguf" --local-dir /opt/models/gemma-4-26B-A4B-it-qat/UD-Q4_K_XL

...
models:
  "Gemma4-26B":
    name: "Gemma4-26B-A4B-QAT"
    capabilities:
      in:
        - text
        - image
      out:
        - text
      tools: true
      context: 212992

    cmd: |
      env LLAMA_GRAPH_REUSE_DISABLE=1 /opt/llama.cpp/build/bin/llama-server
      -m /opt/models/gemma-4-26B-A4B-it-qat/UD-Q4_K_XL/gemma-4-26B-A4B-it-qat-UD-Q4_K_XL.gguf
      --host 127.0.0.1
      --port ${PORT}
      -ngl 999
      -sm tensor
      --tensor-split 1,1
      -c 212992
      -ctk q8_0
      -ctv q8_0
      -np 1
      -b 1024
      -ub 1024
      -fa on
      --jinja
      --reasoning on
      --slot-save-path /kv_cache/
      --temp 1.0
      --top-p 0.95
      --top-k 64
      --min-p 0.0
      --presence-penalty 0.0
      --repeat-penalty 1.0
      --spec-type ngram-mod,draft-mtp
      --spec-draft-model /opt/models/gemma-4-26B-A4B-it-qat/UD-Q4_K_XL/MTP/mtp-gemma-4-26B-A4B-it-Q8_0.gguf
      --spec-draft-n-max 4
      --spec-draft-n-min 0
      --spec-draft-p-min 0.75
      --spec-ngram-mod-n-match 24
      --spec-ngram-mod-n-min 12
      --spec-ngram-mod-n-max 48
      --mmproj /opt/models/gemma-4-26B-A4B-it-qat/UD-Q4_K_XL/mmproj-BF16.gguf
      --no-mmproj-offload

gemma-4-31B-it-GGUF (2x 12 Go VRAM) UD-IQ3_XXS Généraliste dense

L'utilisation d'une quantification en dessous de 4 bits (et d'un KV cache quantifié sur un Gemma-4 non-QAT) est déconseillée. Usage expérimental uniquement.

# hf download unsloth/gemma-4-31B-it-GGUF --include "*UD-IQ3_XXS*.gguf" --include "*mtp-gemma-4-31B-it-Q8_0*.gguf" --include "*mmproj-BF16*.gguf" --local-dir /opt/models/gemma-4-31B-it-GGUF/UD-IQ3_XXS

...
models:
  "Gemma4-31B":
    name: "gemma-4-31B-it"
    capabilities:
      in:
        - text
        - image
      out:
        - text
      tools: true
      context: 110592

    cmd: |
      env LLAMA_GRAPH_REUSE_DISABLE=1 /opt/llama.cpp/build/bin/llama-server
      -m /opt/models/gemma-4-31B-it-GGUF/UD-IQ3_XXS/gemma-4-31B-it-UD-IQ3_XXS.gguf
      --host 127.0.0.1
      --port ${PORT}
      -ngl 999
      -sm tensor
      --tensor-split 1,1
      -c 110592
      -ctk q8_0
      -ctv q8_0
      -np 1
      -b 1024
      -ub 1024
      -fa on
      --jinja
      --reasoning on
      --slot-save-path /kv_cache/
      --temp 1.0
      --top-p 0.95
      --top-k 64
      --min-p 0.0
      --presence-penalty 0.0
      --repeat-penalty 1.0
      --spec-type ngram-mod,draft-mtp
      --spec-draft-model /opt/models/gemma-4-31B-it-GGUF/UD-IQ3_XXS/MTP/mtp-gemma-4-31B-it-Q8_0.gguf
      --spec-draft-n-max 4
      --spec-draft-n-min 0
      --spec-draft-p-min 0.75
      --spec-ngram-mod-n-match 24
      --spec-ngram-mod-n-min 12
      --spec-ngram-mod-n-max 48
      --mmproj /opt/models/gemma-4-31B-it-GGUF/UD-IQ3_XXS/mmproj-BF16.gguf
      --no-mmproj-offload

Ling-3.0-tiny-GGUF (2x 12 Go VRAM) Petit model MOE

# hf download bartowski/Ling-3.0-tiny-GGUF --include "*Q6_K_L*.gguf" --local-dir /opt/models/Ling-3.0-tiny-GGUF/Q6_K_L

...
models:
  "Ling3-tiny":
    name: "Ling-3.0-tiny"
    capabilities:
      in:
        - text
      out:
        - text
      tools: true
      context: 262144

    cmd: |
      /opt/llama.cpp/build/bin/llama-server
      -m /opt/models/Ling-3.0-tiny-GGUF/Q6_K_L/Ling-3.0-tiny-Q6_K_L.gguf
      --host 127.0.0.1
      --port ${PORT}
      -ngl 999
      -sm layer
      --tensor-split 1,1
      -c 262144
      -ctk q8_0
      -ctv q8_0
      -np 1
      -b 1024
      -ub 1024
      -fa on
      --jinja
      --slot-save-path /kv_cache/
      --temp 1.0
      --top-p 0.95
      --top-k 20
      --min-p 0.0
      --presence-penalty 0.0
      --repeat-penalty 1.0

Muse-Glimmer-30B-GGUF (2x 12 Go VRAM) Généraliste dense rapide

# hf download unsloth/Muse-Glimmer-30B-GGUF --include "*UD-Q4_K_XL*.gguf" --include "*mmproj-Muse-Glimmer-30B-Q8_0*.gguf" --include "*dflash-kquant*.gguf" --local-dir /opt/models/Muse-Glimmer-30B-GGUF/UD-Q4_K_XL

...
models:
  "Muse-Glimmer":
    name: "Muse-Glimmer-30B"
    capabilities:
      in:
        - text
        - image
      out:
        - text
      tools: true
      context: 131072

    cmd: |
      /opt/llama.cpp/build/bin/llama-server
      -m /opt/models/Muse-Glimmer-30B-GGUF/UD-Q4_K_XL/Muse-Glimmer-30B-UD-Q4_K_XL.gguf
      --spec-type draft-dflash,ngram-mod
      --spec-draft-model /opt/models/Muse-Glimmer-30B-GGUF/UD-Q4_K_XL/dflash-kquant.gguf
      --spec-draft-ngl all 
      --spec-draft-n-max 15
      --override-kv muse-glimmer.context_length=int:131072,dflash.context_length=int:131072
      --spec-ngram-mod-n-match 24
      --spec-ngram-mod-n-min 12
      --spec-ngram-mod-n-max 48
      --host 127.0.0.1
      --port ${PORT}
      -ngl 999
      -sm layer
      --tensor-split 1,1
      -c 131072
      -ctk q8_0
      -ctv q8_0
      -np 1
      -b 2048
      -ub 512
      -fa on
      --jinja
      --slot-save-path /kv_cache/
      --temp 1.0
      --top-p 0.95
      --top-k 64
      --min-p 0.0
      --presence-penalty 0.0
      --repeat-penalty 1.0
      --mmproj /opt/models/Muse-Glimmer-30B-GGUF/UD-Q4_K_XL/mmproj-Muse-Glimmer-30B-Q8_0.gguf
      --no-mmproj-offload