Geniusia_v2/geniusia2/QWEN3_VL_USAGE.md

Utilisation de Qwen3-VL dans le Système

Vue d'ensemble

Qwen3-VL:8b est un modèle vision-langage utilisé via Ollama pour le raisonnement visuel et la prise de décision intelligente.

Architecture

┌─────────────────┐
│  Screenshots    │
│  + Détections   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  LLM Manager    │ ← Interface Python
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│     Ollama      │ ← Serveur local (localhost:11434)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Qwen3-VL:8b    │ ← Modèle vision-langage
└─────────────────┘

Configuration

Dans config.py :

"llm": "qwen3-vl:8b",
"ollama": {
    "host": "localhost:11434",
    "timeout": 30
}

Trois Usages Principaux

1. Raisonnement sur les Détections

Quand ? Après que OWL-v2/DINO/YOLO ont détecté plusieurs éléments UI

Pourquoi ? Pour choisir intelligemment le bon élément parmi plusieurs candidats

Comment ?

# Dans orchestrator.py, ligne 525
llm_result = self.llm.reason_about_detections(
    detections_data,  # Liste des éléments détectés
    context,          # Fenêtre active, historique
    intent            # Intention de l'utilisateur
)

Exemple concret :

Situation : 3 boutons détectés sur l'écran
- Bouton "Annuler" (confiance: 0.92)
- Bouton "Enregistrer" (confiance: 0.88)
- Bouton "Fermer" (confiance: 0.85)

Intention utilisateur : "Sauvegarder le document"

Qwen3-VL analyse les screenshots + le contexte et répond :
{
    "element_index": 1,
    "confidence": 0.95,
    "reasoning": "Le bouton 'Enregistrer' correspond à l'intention de sauvegarder"
}

Entrées envoyées à Qwen3-VL :

• Images : Screenshots des ROI (régions d'intérêt) de chaque élément détecté, encodés en base64
• Prompt : Description textuelle avec l'intention et le contexte
• Format : Demande une réponse JSON structurée

Sortie attendue :

{
    "element_index": 1,
    "confidence": 0.95,
    "reasoning": "Explication du choix"
}

2. Génération avec Vision

Quand ? Pour analyser des screenshots et générer des descriptions

Pourquoi ? Pour comprendre ce qui se passe dans l'interface

Comment ?

response = llm_manager.generate_with_vision(
    prompt="Décris cette interface utilisateur",
    images=[screenshot]
)

Exemple :

Input : Screenshot d'une fenêtre + prompt "Que vois-tu ?"

Qwen3-VL répond :
"Je vois une fenêtre de traitement de texte avec une barre d'outils en haut 
contenant des boutons pour enregistrer, imprimer et formater le texte. 
Le document actuel semble être vide."

3. Score de Pertinence d'Action

Quand ? Pour évaluer si une action proposée est pertinente

Pourquoi ? Pour éviter d'exécuter des actions incorrectes

Comment ?

score = llm_manager.score_action_relevance(
    action={"action_type": "click", "target_element": "button"},
    intent="Fermer la fenêtre"
)
# Retourne : 0.85 (très pertinent)

Flux de Données Complet

Exemple : Détection d'un pattern de 3 clics

1. Utilisateur clique 3 fois sur un bouton
   ↓
2. EventCapture détecte le pattern répétitif
   ↓
3. Orchestrator récupère les 3 screenshots
   ↓
4. VisionAnalysis crée les signatures visuelles
   ↓
5. OWL-v2/DINO/YOLO détectent les éléments UI
   ↓
6. LLMManager envoie à Qwen3-VL :
   - Screenshots des éléments (base64)
   - Contexte : "Fenêtre Firefox, 3 clics répétés"
   - Intention : "Rafraîchir la page"
   ↓
7. Qwen3-VL analyse et répond :
   {
     "element_index": 0,
     "confidence": 0.92,
     "reasoning": "C'est le bouton de rafraîchissement"
   }
   ↓
8. Orchestrator crée une tâche apprise
   ↓
9. Prochaine fois, le système peut rejouer automatiquement

Format des Images Envoyées

Les images sont converties en base64 PNG :

def _image_to_base64(self, image: np.ndarray) -> str:
    # 1. Convertir numpy array en PIL Image
    pil_image = Image.fromarray(image.astype(np.uint8))
    
    # 2. Encoder en PNG
    buffered = BytesIO()
    pil_image.save(buffered, format="PNG")
    
    # 3. Convertir en base64
    img_str = base64.b64encode(buffered.getvalue()).decode()
    
    return img_str

Fallback Automatique

Si Qwen3-VL n'est pas disponible (Ollama arrêté, modèle non téléchargé), le système utilise un fallback :

def _fallback_to_vision_only(self, detections):
    # Sélectionne simplement l'élément avec la confiance la plus élevée
    best_detection = max(detections, key=lambda d: d['confidence'])
    return {
        "selected_element": best_detection,
        "confidence": best_detection['confidence'],
        "reasoning": "Sélection basée sur la confiance vision (fallback)"
    }

Vérifier que Qwen3-VL fonctionne

# 1. Vérifier qu'Ollama est lancé
curl http://localhost:11434/api/tags

# 2. Lister les modèles disponibles
ollama list

# 3. Si qwen3-vl:8b n'est pas là, le télécharger
ollama pull qwen3-vl:8b

# 4. Tester le modèle
ollama run qwen3-vl:8b "Bonjour"

Logs et Debugging

Le LLMManager log toutes ses actions :

self.logger.log_action({
    "action": "llm_reasoning",
    "intent": intent,
    "num_detections": len(detections),
    "selected_index": result.get("element_index"),
    "confidence": result.get("confidence")
})

Cherche dans data/logs/ pour voir l'historique des décisions de Qwen3-VL.

Performance

• Latence : ~1-2 secondes par requête (dépend du GPU)
• Mémoire : ~8 GB VRAM pour le modèle 8b
• Précision : Excellente pour le raisonnement visuel UI

Différence avec les Modèles de Détection

Modèle	Rôle	Sortie
OWL-v2/DINO/YOLO	Détection d'objets	Bounding boxes + labels
Qwen3-VL	Raisonnement	Décision intelligente + explication

Exemple :

• OWL-v2 dit : "J'ai trouvé 3 boutons"
• Qwen3-VL dit : "Le bouton du milieu est le bon car il correspond à l'intention de sauvegarder"

Résumé

Qwen3-VL est le cerveau du système qui :

1. ✅ Comprend le contexte visuel
2. ✅ Raisonne sur les intentions
3. ✅ Prend des décisions intelligentes
4. ✅ Explique ses choix

Les modèles de détection (OWL-v2, DINO, YOLO) sont les yeux qui trouvent les éléments, mais Qwen3-VL est le cerveau qui décide quoi faire avec.