Funk-lab/stt/server/README.md

STT-server — orchestrateur AI (in-cluster)

API FastAPI déployée dans le cluster k8s (namespace ai). Reçoit les requêtes des clients STT et route l'inférence vers LiteLLM (s01) → Qwen3 (g01) / Claude.

API

Méthode	Route	Corps	Réponse
GET	/healthz	—	{status, version}
GET	/v1/models	—	{default, available[]}
GET	/v1/memory/health	—	diagnostic mémoire long-terme (embed/Qdrant/collection, erreurs exposées)
POST	/v1/ask	{text, model?, session_id?}	{reply, model}
POST	/v1/reset	{session_id}	{status}

model (optionnel) = alias LiteLLM ; défaut serveur si absent ; rejeté (400) si absent de STT_ALLOWED_MODELS. Le client choisit le modèle par requête (pas de switch global).

session_id (optionnel) active la mémoire court-terme : le serveur garde l'historique de la conversation (en mémoire, borné + TTL) et l'injecte dans l'appel LLM. /v1/reset l'efface. Sans session_id, chaque requête est sans état. (Deployment en 1 worker pour la cohérence de la mémoire process. Mémoire long-terme Qdrant = phase 5b.)

Configuration (variables d'env)

Var	Défaut	Rôle
STT_LITELLM_URL	http://192.168.10.1:4000/v1/chat/completions	endpoint LiteLLM (IP directe s01, cf. open-webui)
STT_LITELLM_KEY	lm-studio	clé LiteLLM (valeur exacte attendue)
STT_MODEL	hermes-default	modèle par défaut
STT_ALLOWED_MODELS	hermes-default,qwen3-8b,claude-sonnet-4-6,claude-opus-4-7	alias autorisés (demandables par le client)
STT_SYSTEM_PROMPT	prompt vocal FR concis	persona
STT_MAX_TOKENS / STT_TEMPERATURE	200 / 0.7	génération
STT_DISABLE_THINKING	true	ajoute /no_think au prompt (désactive le raisonnement Qwen3)
STT_MEMORY_LONGTERM	true	mémoire long-terme Qdrant (dégrade si injoignable)
STT_QDRANT_URL	http://192.168.10.1:6333	Qdrant (s01)
STT_EMBED_URL	http://192.168.10.20:1238/v1/embeddings	embeddings nomic-embed-text (gpu-01 :1238, dim 768)
STT_EMBED_MODEL	nomic-embed-text	alias du modèle d'embedding
STT_MEMORY_TOPK	3	nombre de souvenirs injectés

Caveat Qwen3 — mode « thinking »

Qwen3 est un modèle de raisonnement : par défaut il « réfléchit » avant de répondre. Avec un max_tokens faible (200), il dépense tout le budget dans reasoning_content → content vide ; sur certaines questions il réfléchit longtemps → timeout (502 upstream LiteLLM : ). brain.py ajoute donc le token de contrôle /no_think au prompt système (STT_DISABLE_THINKING=true, inoffensif pour les modèles non-Qwen) et, par sécurité, récupère reasoning_content si content est vide. Voir le caveat partagé dans admin/ia/llama_server.md.

Dev local

cd stt/server
pip install -e .
STT_LITELLM_URL=http://192.168.1.200:4000/v1/chat/completions stt-server   # :8000
curl -s localhost:8000/healthz
curl -s localhost:8000/v1/ask -H 'content-type: application/json' -d '{"text":"bonjour"}'

Déploiement

• Image construite/poussée par .github/workflows/build-stt-server.yml, taguée sha-<commit> ; sur main la CI bumpe le manifest avec ce tag → ArgoCD redéploie tout seul (déterministe).
• Manifests : k8s/apps/stt/ ; Application ArgoCD : k8s/apps-of-apps/apps/stt.yaml (depuis main).
• Accès LiteLLM (hors cluster) : IP directe 192.168.10.1:4000 (même pattern qu'open-webui).

Mémoire

• Court-terme (memory.py) : historique par session_id (en mémoire, borné + TTL).
• Long-terme (longterm.py) : collection Qdrant stt-memory (vecteurs des tours user, embeddings nomic-embed-text dim 768 via gpu-01 :1238), souvenirs pertinents injectés au prompt. Dégrade si Qdrant/embeddings down. Migration auto de la collection si la dimension d'embedding change (_ensure_collection détecte et recrée).

À venir

• Intégration des outils Hermes (« agir sur Funk ») via le gateway :8080 — nécessite de spécifier son API. Aujourd'hui : inférence/chat seulement (via LiteLLM).
• Mémoire distillée versionnée (faits/préférences) dans server/memory/.