Funk-lab/ansible/roles/llama_server/README.md

llama_server

Compile llama.cpp (backend HIP/ROCm) et déploie le service llama-server GPU (:1234) sur gpu-01. Sert aussi les embeddings du RAG.

Ce que fait le rôle

• Clone + build llama.cpp (cmake HIP, gfx1030) — build seulement si le binaire est absent
• Service systemd llama-server : modèle GGUF depuis /mnt/models (NFS), :1234
• Embeddings activés (--embeddings, pooling mean)
• Ouvre le port dans le firewall, désactive l'ancien service lm-studio
• Instance dédiée embeddings (optionnelle, llama_embed_enabled) : service systemd llama-embed servant un modèle d'embedding spécialisé (ex. nomic-embed-text) sur :1238, GPU. Télécharge le GGUF depuis llama_embed_model_url si absent. Partage le binaire et le GPU avec :1234 (modèle ~300 Mo VRAM).
• Heartbeat embed (optionnel, llama_embed_heartbeat_enabled, défaut true) : service systemd llama-embed-heartbeat qui envoie un petit embed à :1238 toutes les llama_embed_heartbeat_interval s → garde le slot d'embedding chaud. Sans ça, la 1ʳᵉ requête après une pause part à froid (5-8 s) et dépasse le timeout du STT-server (4 s) → recall mémoire vide et RAG documentaire raté (docs=0, cf. admin/ia/stt.md). Pendant du llm-heartbeat (rôle litellm) côté chat. Logs : journalctl -u llama-embed-heartbeat.

Heartbeat embed — variables

Variable	Défaut
llama_embed_heartbeat_enabled	true (si llama_embed_enabled)
llama_embed_heartbeat_interval	20 (s entre deux pings)
llama_embed_heartbeat_timeout	15 (s max par ping)

• Watchdog (optionnel, llama_watchdog_enabled, défaut true) : service systemd llama-watchdog qui sonde une vraie génération sur :1234 toutes les llama_watchdog_interval s. Sur llama_watchdog_failures échecs consécutifs → systemctl restart llama-server en local (tourne en root, pas de SSH). Répare automatiquement le wedge ROCm où /health reste vert mais l'inférence est morte (cf. admin/incidents-llm-gpu.md). Logs : journalctl -u llama-watchdog.

Watchdog — variables

Variable	Défaut
llama_watchdog_enabled	true
llama_watchdog_port	{{ llama_server_port }} (1234)
llama_watchdog_model	{{ llama_model_alias }} (qwen3-8b)
llama_watchdog_interval	20 (s entre deux sondes)
llama_watchdog_timeout	15 (s max par sonde)
llama_watchdog_failures	3 (échecs consécutifs avant restart)

Complémentaire au llm-heartbeat du rôle litellm : le heartbeat empêche la péremption par inactivité de la connexion LiteLLM↔llama-server ; le watchdog répare le figeage du llama-server lui-même. Le watchdog gère le 503 "Loading model" post-restart (rechargement VRAM) sans le compter comme échec.

Variables principales

Variable	Défaut	Surcharge gpu-01
llama_server_port	1234	—
llama_model_path	""	/mnt/models/bartowski/Qwen3-8B-GGUF/Qwen3-8B-Q4_K_M.gguf
llama_model_alias	""	qwen3-8b
llama_ctx_size	32768	32768
llama_n_gpu_layers	99	—
hsa_override_gfx_version	10.3.0	—
llama_embed_enabled	false	true
llama_embed_port	1238	—
llama_embed_model_path	""	/mnt/models/nomic-ai/nomic-embed-text-v1.5.f16.gguf
llama_embed_model_url	""	URL HuggingFace du GGUF nomic
llama_embed_model_alias	nomic-embed-text	—

⚠️ Gap IaC — instances CPU hors Ansible

Le rôle ne gère que l'instance GPU (llama-server.service). Les services suivants existent sur gpu-01 mais ont été créés à la main (non reproductibles par make apply-gpu) :

Service	Port	Modèle	Usage
llama-server-system.service	1236	Qwen3-1.7B CPU	profil system
llama-server-monitor.service	1237	Qwen3-1.7B CPU	profil monitor
llama-server-dev.service	—	(non documenté, présent dans /etc/systemd/system)	?

À faire : templatiser ces instances dans le rôle (liste d'instances avec port/modèle/threads) pour qu'une réinstallation de gpu-01 restaure les 3 serveurs.

Caveats

• Rebuild forcé : supprimer le binaire (/opt/llama.cpp/build/bin/llama-server) puis relancer le rôle
• Le modèle vient du NFS — voir caveat du rôle nfs_client