# Sources de modèles et backends supportés

Comment les modèles entrent dans un package JackAILocal, selon le backend
d'exécution. Les modèles sont préchargés au moment du build (factory ou
builder) — jamais téléchargés à l'usage chez le client.

## Vue d'ensemble

| Source | Backend cible | Format | Outil de préchargement |
|---|---|---|---|
| Registre Ollama (`registry.ollama.ai`) | Ollama | blobs Ollama | `ollama pull` orchestré par les builders (`Pull-OllamaModels`) |
| Hugging Face (`huggingface.co`) | llama.cpp | GGUF | `factory/powershell/Install-GGUFModels.ps1` + `manifest/gguf-downloads.json` |
| Hugging Face (`huggingface.co`) | vLLM | safetensors (repo HF complet) | `huggingface-cli download` vers `models/hf/` (appliance Linux) |
| NVIDIA `build.nvidia.com` / NGC | NIM (conteneur) | conteneur NIM + moteur TRT-LLM | `docker pull nvcr.io/nim/...` (appliance GPU NVIDIA seulement) |

## 1. Ollama (canal par défaut)

Le catalogue (`config/model-catalog.json`) référence des modèles Ollama
(`qwen3.5:*`, `gemma4:12b`, `qwen3-vl:*`). Les builders Windows/macOS
démarrent un Ollama de build sur un port dédié, font `ollama pull` selon le
manifest, et le store résultant (`models/ollama/`) part sur la clé. C'est le
chemin recommandé pour USB/SSD/installateur.

## 2. Hugging Face — GGUF pour llama.cpp

Pour un modèle absent du registre Ollama ou pour le fallback llama.cpp :
décrire les fichiers dans `manifest/gguf-downloads.json` (URL `resolve/main`
de huggingface.co + SHA-256), puis exécuter `Install-GGUFModels.ps1`. Les
fichiers atterrissent dans `models/gguf/` et le serveur llama.cpp les sert en
API compatible OpenAI.

`config/model-alias-map.json` fait la correspondance entre IDs Hugging Face
et références Ollama quand les deux existent.

## 3. Hugging Face — repos complets pour vLLM (appliance Linux GPU)

vLLM consomme les repos HF en safetensors. Sur l'appliance :

```bash
pip install vllm huggingface_hub
huggingface-cli download Qwen/Qwen3.5-9B-Instruct --local-dir /opt/JackAILocal/models/hf/qwen3.5-9b
backends/vllm/linux/start-vllm.sh /opt/JackAILocal/models/hf/qwen3.5-9b   # API OpenAI sur 127.0.0.1:8000
```

Le runtime jackailocald le consomme via la config `[backends.llamacpp]`
(toute API compatible OpenAI). Réservé aux machines Linux avec GPU dédié.

## 4. NVIDIA build.nvidia.com — NIM (appliance GPU NVIDIA)

Les modèles de `build.nvidia.com/models` se déploient localement sous forme
de microservices NIM (conteneurs NGC, moteurs TensorRT-LLM optimisés).
Exigences : GPU NVIDIA récent, Docker + NVIDIA Container Toolkit, clé API
NGC (gratuite) **au moment du build seulement** — l'exécution est locale.

Voir `deploy/appliance/nim-compose.example.yml`. Étapes :

```bash
docker login nvcr.io          # $oauthtoken / clé NGC
docker compose -f nim-compose.example.yml pull    # au build, avec Internet
docker compose -f nim-compose.example.yml up -d   # chez le client, hors ligne
```

Le NIM expose une API compatible OpenAI sur le port configuré; pointer
`[backends.llamacpp].url` dessus. Attention aux licences propres à chaque
modèle NIM (NVIDIA AI Enterprise pour certains) — vérifier la fiche du modèle
sur build.nvidia.com avant de l'intégrer à une offre commerciale.

## Règles

- Aucun téléchargement de modèle au lancement chez le client (offline-first).
- Chaque modèle ajouté doit passer par `config/model-catalog.json` (limite
  `hackathon_max_params_b` appliquée par l'agent de config).
- Chaque modèle ajouté doit avoir sa licence vérifiée et inscrite dans
  `licenses/THIRD_PARTY_NOTICES.md` (voir la mise en garde voix Piper).
- L'agent d'analyse de configuration est **Gemma 4 12B** (`gemma4:12b`),
  localement via Ollama ou `google/gemma-4-12B-it` via l'endpoint distant.