Funk-lab/admin/ia/litellm.md

LiteLLM — Proxy LLM unifié (storage-01)

LiteLLM tourne en service systemd sur storage-01 (127.0.0.1:4000). Il route les requêtes OpenAI-compatibles vers le bon backend selon le modèle demandé.

---

Flux

Hermes / ask-agent / Open WebUI / n8n
        │
        ▼  http://127.0.0.1:4000/v1  (Authorization: Bearer lm-studio)
   LiteLLM Proxy
        ├── hermes-default       →  qwen3-8b            →  llama-server gpu-01 :1234  (GPU)
        ├── qwen3-8b             →  llama-server gpu-01 :1234  (GPU, gratuit)
        ├── qwen3-1.7b-system    →  llama-server gpu-01 :1236  (CPU 14 threads, gratuit)
        ├── qwen3-1.7b-monitor   →  llama-server gpu-01 :1237  (CPU 14 threads, gratuit)
        ├── claude-sonnet-4-6    →  api.anthropic.com           (cloud, payant)
        └── claude-opus-4-7      →  api.anthropic.com           (cloud, payant)

---

Service systemd

# Depuis storage-01
sudo systemctl status litellm
sudo systemctl restart litellm
sudo journalctl -u litellm -f
sudo journalctl -u litellm -n 50

---

Modèles disponibles

Nom dans l'API	Backend	Coût
hermes-default	qwen3-8b sur gpu-01 :1234 (GPU)	Gratuit
qwen3-8b	llama-server gpu-01 :1234 (ROCm 7.x)	Gratuit
qwen3-1.7b-system	llama-server gpu-01 :1236 (CPU, 14 threads)	Gratuit
qwen3-1.7b-monitor	llama-server gpu-01 :1237 (CPU, 14 threads)	Gratuit
claude-sonnet-4-6	Anthropic API	~$3/$15 par million tokens in/out
claude-opus-4-7	Anthropic API	Plus cher, meilleur raisonnement

qwen3-1.7b-system et qwen3-1.7b-monitor sont utilisés par ask-agent system et ask-agent monitor — voir hermes.md.

⚠️ Qwen3 = modèle « thinking » : il raisonne avant de répondre. Avec un max_tokens faible, il peut renvoyer un content vide (budget épuisé en reasoning_content) ou dépasser le timeout (réflexion longue). Ajouter /no_think au prompt système pour le désactiver (STT le fait via STT_DISABLE_THINKING). Voir admin/ia/llama_server.md.

---

Switch rapide avec hermes-switch

Script déployé sur storage-01 :

sudo hermes-switch status    # voir le modèle actuel de hermes-default
sudo hermes-switch qwen      # Qwen3-8B local GPU (gratuit, ~60 tok/s)
sudo hermes-switch claude    # Claude Sonnet 4.6 (payant, ~1-2$ par session debug)

Le script modifie /etc/litellm/config.yaml et redémarre litellm automatiquement. Source : roles/litellm/files/hermes-switch.

Coût Claude

Session type	Tokens input	Coût estimé
Debug simple (5 échanges)	~80k	~$0.24
Debug complexe (10 échanges)	~375k	~$1.12
Utilisation courante	—	Utiliser Qwen

---

Validation API

# Depuis storage-01 — master_key = lm-studio
curl http://127.0.0.1:4000/v1/models \
  -H "Authorization: Bearer lm-studio" | python3 -m json.tool

# Test inférence Qwen (local)
curl http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer lm-studio" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3-8b", "messages": [{"role": "user", "content": "Dis bonjour"}], "max_tokens": 30}'

# Test inférence Claude
curl http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer lm-studio" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "messages": [{"role": "user", "content": "Dis bonjour"}], "max_tokens": 30}'

---

Configuration

Fichier : /etc/litellm/config.yaml (géré par Ansible, propriété litellm:litellm, mode 0640)

La clé API Anthropic est injectée via ANTHROPIC_API_KEY dans l'unit systemd — elle vient du vault Ansible (vault_anthropic_api_key). Jamais en clair dans config.yaml.

master_key : lm-studio — doit correspondre à LM_API_KEY dans le .env Hermes.

---

⚠️ Gap IaC — modèles CPU absents du template Ansible

ansible/roles/litellm/templates/config.yaml.j2 n'inclut que 4 modèles : hermes-default, qwen3-8b, claude-sonnet-4-6, claude-opus-4-7.

Les entrées qwen3-1.7b-system (:1236) et qwen3-1.7b-monitor (:1237) ont été ajoutées manuellement dans /etc/litellm/config.yaml sur storage-01.

Un make apply-storage sur un hôte vierge ne déploierait PAS les routes CPU nécessaires à ask-agent system et ask-agent monitor.

Axe d'amélioration : ajouter les 2 entrées CPU dans config.yaml.j2 avec des variables dans defaults/main.yml (litellm_cpu_system_url, litellm_cpu_monitor_url).

---

Ajouter un modèle

1. Modifier roles/litellm/templates/config.yaml.j2 :

   - model_name: claude-haiku-4-5
     litellm_params:
       model: anthropic/claude-haiku-4-5-20251001
       api_key: os.environ/ANTHROPIC_API_KEY
   

2. Redéployer :

   ansible-playbook -i inventory.yml playbooks/storage-01.yml --tags litellm
   

---

Points d'attention

Sujet	Détail
Accès réseau	127.0.0.1 uniquement — pour exposer au cluster, changer litellm_host: 0.0.0.0 + ouvrir firewall
master_key	lm-studio — doit correspondre exactement à LM_API_KEY dans le .env Hermes
Clé Anthropic	ANTHROPIC_API_KEY dans l'env systemd — vault Ansible
Coût Claude	Surveiller la consommation sur console.anthropic.com
404 /api/v1/models	Hermes appelle /api/v1/models à l'init (retourne 404) — normal, ne bloque pas
hermes-switch status	Utilise grep -A3 — si le bloc hermes-default a une structure différente, ajuster