Fine-tuning de domaine

Le RAG donne à Cradle les faits (prix, spécifications, clauses). Le fine-tuning lui donne le style et les patterns de raisonnement d'un domaine étroit — juridique, médical, construction, comptabilité, etc. Les deux fonctionnalités fonctionnent ensemble.

Le pipeline d'entraînement utilise Python uniquement pour les étapes LoRA. Le runtime Cradle reste sans Python.

Ce que vous pouvez entraîner sur un MacBook Pro M3 Pro 18 Go

Avec 36 Go de RAM ou plus, vous pouvez utiliser Qwen2.5-7B avec rank 16.

Étape 1 — construire un dataset

Rassemblez les documents source dans un dossier :

~/corpus/legal/
├── snippets/
│   ├── contract-terms.md
│   └── court-practice.pdf
├── gost/
│   └── civil-code-sections.pdf
└── examples/
    └── faq-operator.md

Exécutez le constructeur de dataset :

pnpm build-dataset \
  --files ~/corpus/legal \
  --out "~/Library/Application Support/cradle/finetune-datasets/legal-v1" \
  --mode qa \
  --model "~/Library/Application Support/cradle/models/qwen3-8b-q4.gguf" \
  --qa-per-chunk 2 \
  --language ru

• --mode qa — synthétise des paires Q&R à partir de chaque chunk avec un modèle local. Lent mais produit un dataset d'instruction-tuning.
• --mode raw — rapide ; émet { "text": "<chunk>" } pour du continued pretraining.
• --model — chemin vers un GGUF chat téléchargé utilisé pour la synthèse Q&R. Qwen3 8B est recommandé.

Sortie :

legal-v1/
├── train.jsonl
├── valid.jsonl
└── meta.json

Inspectez 5–10 paires manuellement. Les questions doivent sonner naturellement et les réponses ne doivent pas contenir de nombres inventés. Si le synthétiseur hallucine, essayez un modèle plus grand ou --mode raw.

Étape 2 — installer MLX

Python n'est nécessaire qu'une fois sur la machine d'entraînement. Utilisez uv :

curl -LsSf https://astral.sh/uv/install.sh | sh

uv venv cradle-finetune --python 3.11
source cradle-finetune/bin/activate
uv pip install -r /path/to/cradle/tools/finetune/requirements.txt

python -c "import mlx_lm; print(mlx_lm.__version__)"
# attendez ≥ 0.31.0

Étape 3 — entraîner un LoRA

Copiez et modifiez la config exemple :

cp tools/finetune/lora_config.example.yaml ~/lora-legal.yaml
# modifiez : data, adapter_path, modèle de base

Lancez l'entraînement :

python -m mlx_lm.lora --config ~/lora-legal.yaml

Surveillez le log :

Iter 1:   Val loss 2.134, Val took 4.2s
Iter 10:  Train loss 1.987, It/sec 0.85, Tokens/sec 420
...
Iter 750: Train loss 1.234, Val loss 1.456
Saved final adapter weights to adapters-raw/legal-v1/adapters.safetensors

Checkpoints :

• La validation loss doit diminuer. Si elle stagne ou augmente, réduisez iters.
• Un It/sec de 0,5–2 sur un M3 Pro est normal. En dessous de 0,2 signifie que la RAM est tendue : réduisez batch_size ou activez grad_checkpoint.
• OOM en cours : réduisez num_layers de 16 à 8, ou rank de 16 à 8.

Étape 4 — exporter vers GGUF

Clonez et compilez llama.cpp pour les outils de conversion :

git clone https://github.com/ggml-org/llama.cpp ~/repos/llama.cpp
cd ~/repos/llama.cpp
cmake -B build && cmake --build build --config Release -j

Fusionnez le LoRA dans le modèle de base et quantifiez :

cd /path/to/cradle
BASE_MODEL=Qwen/Qwen2.5-3B-Instruct \
ADAPTER_PATH="~/Library/Application Support/cradle/adapters-raw/legal-v1" \
OUT_DIR=/tmp/legal-v1-gguf \
LLAMA_CPP=~/repos/llama.cpp \
QUANT=Q4_K_M \
./tools/finetune/export_gguf.sh

Résultat : /tmp/legal-v1-gguf/model-Q4_K_M.gguf (~1,9 Go pour une base 3B).

Étape 5 — importer dans Cradle

Option A — comme un nouveau modèle

1. Déplacez le GGUF dans le répertoire de modèles Cradle : ~/Library/Application Support/cradle/models/legal-v1.gguf.
2. Dans l'app de bureau : Modèles → Ajouter une URL personnalisée.
3. URL : file:///Users/aki/Library/Application%20Support/cradle/models/legal-v1.gguf
4. Rôle : general, contexte : 16384 (ou correspondant au modèle de base).
5. Dans Agents → Modifier, assignez ce modèle à l'agent concerné.

Option B — adaptateur runtime (expérimental)

Si vous avez un adaptateur GGUF séparé :

1. Adaptateurs → Importer un adaptateur dans Cradle.
2. Sélectionnez le modèle de base par catalogId.
3. Scale : 1,0.

Puis assignez l'adaptateur dans Agents → Modifier → Domain adapter. Le modèle de base reste le même.

⚠️ Vérifié uniquement avec node-llama-cpp v3.4, qui supporte LoRA via createContext({ lora: ... }). MLX-LM n'exporte pas directement d'adaptateurs GGUF, donc l'option A est recommandée jusqu'à ce que vous ayez besoin de plusieurs adaptateurs indépendants.

Dépannage

• OOM à l'itération 1 — modèle de base trop grand. Sur 18 Go max : 3B avec rank 16, ou 7B avec rank 8 + grad checkpoint.
• La validation loss ne baisse pas — trop peu d'exemples (moins de 100) ou mauvais format. Vérifiez que chaque ligne de train.jsonl est un JSON valide avec un champ messages.
• Le GGUF fusionné fait 16 Go — la quantification a été sautée. Vérifiez que llama-quantize a bien tourné et que OUT_DIR contient model-Q4_K_M.gguf.
• L'agent répond toujours comme le modèle de base — le scale de l'adaptateur est trop bas ; essayez 1,5, ou augmentez iters.

Prochaines étapes

Associez l'adaptateur fine-tuné avec le RAG : l'adaptateur définit le langage du domaine, le RAG fournit les faits actuels.