Utiliser Qiskit Code Assistant en mode local

Apprends à installer, configurer et utiliser les modèles Qiskit Code Assistant sur ta machine locale.

Remarques

• Qiskit Code Assistant est en version préliminaire et peut être sujet à des modifications.
• Pour tout retour ou pour contacter l'équipe de développement, utilise le canal Qiskit Slack Workspace ou les dépôts GitHub publics associés.

Démarrage rapide (recommandé)

La façon la plus simple de commencer avec Qiskit Code Assistant en mode local est d'utiliser les scripts de configuration automatique pour l'extension VS Code ou JupyterLab. Ces scripts installent automatiquement Ollama pour exécuter les LLM, téléchargent le modèle recommandé et configurent l'extension pour toi.

Configuration de l'extension VS Code

Lance la commande suivante dans ton terminal :

bash <(curl -fsSL https://raw.githubusercontent.com/Qiskit/qiskit-code-assistant-vscode/main/setup_local.sh)

Ce script effectue les étapes suivantes :

• Installe Ollama (si ce n'est pas déjà fait)
• Télécharge et configure le modèle Qiskit Code Assistant recommandé
• Configure l'extension VS Code pour qu'elle fonctionne avec ton déploiement local

Configuration de l'extension JupyterLab

Lance la commande suivante dans ton terminal :

bash <(curl -fsSL https://raw.githubusercontent.com/Qiskit/qiskit-code-assistant-jupyterlab/main/setup_local.sh)

Ce script va :

• Installer Ollama (si ce n'est pas déjà fait)
• Télécharger et configurer le modèle Qiskit Code Assistant recommandé
• Configurer l'extension JupyterLab pour qu'elle fonctionne avec ton déploiement local

Modèles disponibles

Modèles actuels

Voici les derniers modèles recommandés pour une utilisation avec Qiskit Code Assistant :

1. Qiskit/mistral-small-3.2-24b-qiskit - Publié en octobre 2025
2. qiskit/qwen2.5-coder-14b-qiskit - Publié en juin 2025
3. qiskit/granite-3.3-8b-qiskit - Publié en juin 2025
4. qiskit/granite-3.2-8b-qiskit - Publié en juin 2025

Modèles GGUF (recommandés pour les environnements personnels/ordinateurs portables)

Les modèles au format GGUF sont optimisés pour une utilisation locale et nécessitent moins de ressources de calcul :

1. mistral-small-3.2-24b-qiskit-GGUF – Publié en octobre 2025 Entraîné avec des données Qiskit jusqu'à la version 2.1

2. qiskit/qwen2.5-coder-14b-qiskit-GGUF – Publié en juin 2025 Entraîné avec des données Qiskit jusqu'à la version 2.0

3. qiskit/granite-3.3-8b-qiskit-GGUF – Publié en juin 2025 Entraîné avec des données Qiskit jusqu'à la version 2.0

4. qiskit/granite-3.2-8b-qiskit-GGUF – Publié en juin 2025 Entraîné avec des données Qiskit jusqu'à la version 2.0

Les modèles open source Qiskit Code Assistant sont disponibles au format safetensors ou GGUF et peuvent être téléchargés depuis Hugging Face comme expliqué ci-dessous.

Versions de Qiskit utilisées pour l'entraînement

Modèle						Métriques de benchmark					Date de publication	Entraîné sur la version Qiskit
	QiskitHumanEval-Hard	QiskitHumanEval	HumanEval	ASDiv	MathQA	SciQ	MBPP	IFEval	CrowsPairs (English)	TruthfulQA (MC1 acc)
mistral-small-3.2-24b-qiskit	32.45	47.02	77.49	3.77	49.68	97.50	64.00	48.44	67.08	39.41	janvier 2026	2.2
qwen2.5-coder-14b-qiskit	25.17	49.01	91.46	4.21	53.90	97.00	77.60	49.64	65.18	37.82	juin 2025	2.0
granite-3.3-8b-qiskit	14.57	27.15	62.80	0.48	38.66	93.30	52.40	59.71	59.75	39.05	juin 2025	2.0
granite-3.2-8b-qiskit	9.93	24.50	57.32	0.09	41.41	96.30	51.80	60.79	66.79	40.51	juin 2025	2.0
granite-8b-qiskit-rc-0.10	15.89	38.41	59.76	—	—	—	—	—	—	—	février 2025	1.3
granite-8b-qiskit	17.88	44.37	53.66	—	—	—	—	—	—	—	novembre 2024	1.2

Remarque : tous les modèles listés dans le tableau de benchmark ont été évalués avec leur invite système respective, définie dans leur modèle Hugging Face.

Modèles dépréciés

Ces modèles ne sont plus activement maintenus mais restent disponibles :

1. qiskit/granite-8b-qiskit-rc-0.10 - Publié en février 2025 (déprécié)
2. qiskit/granite-8b-qiskit - Publié en novembre 2024 (déprécié)

Configuration avancée

Si tu préfères configurer manuellement ton installation locale ou que tu as besoin de plus de contrôle sur le processus d'installation, développe les sections ci-dessous.

Télécharger depuis le site web Hugging Face

Suis ces étapes pour télécharger n'importe quel modèle lié à Qiskit Code Assistant depuis le site web Hugging Face :

1. Accède à la page du modèle Qiskit souhaité sur Hugging Face.
2. Va dans l'onglet Files and Versions et télécharge les fichiers de modèle safetensors ou GGUF.

Télécharger via l'interface en ligne de commande Hugging Face

Pour télécharger l'un des modèles Qiskit Code Assistant disponibles à l'aide de l'interface CLI Hugging Face, suis ces étapes :

1. Installe l'interface CLI Hugging Face

2. Connecte-toi à ton compte Hugging Face

   huggingface-cli login

3. Télécharge le modèle de ton choix depuis la liste précédente

   huggingface-cli download <HF REPO NAME> <MODEL PATH> --local-dir <LOCAL PATH>

Déployer manuellement les modèles Qiskit Code Assistant en local via Ollama

Il existe plusieurs façons de déployer et d'interagir avec le modèle Qiskit Code Assistant téléchargé. Ce guide illustre l'utilisation d'Ollama de la manière suivante : soit avec l'application Ollama en utilisant l'intégration Hugging Face Hub ou un modèle local, soit avec le paquet llama-cpp-python.

Utiliser l'application Ollama

L'application Ollama offre une solution simple pour exécuter des LLM localement. Elle est facile à prendre en main, avec une interface CLI qui rend l'ensemble du processus — configuration, gestion des modèles et interaction — assez direct. Elle est idéale pour une expérimentation rapide et pour les utilisateurs qui souhaitent gérer le moins de détails techniques possible.

Installer Ollama

1. Télécharge l'application Ollama

2. Installe le fichier téléchargé

3. Lance l'application Ollama installée

   info

   L'application fonctionne correctement lorsque l'icône Ollama apparaît dans la barre de menu du bureau. Tu peux également vérifier que le service est en cours d'exécution en accédant à http://localhost:11434/.

4. Essaie Ollama dans ton terminal et commence à exécuter des modèles. Par exemple :

   ollama run hf.co/Qiskit/Qwen2.5-Coder-14B-Qiskit

Configurer Ollama avec l'intégration Hugging Face Hub

L'intégration Ollama/Hugging Face Hub permet d'interagir avec des modèles hébergés sur Hugging Face Hub sans avoir besoin de créer un nouveau modelfile ni de télécharger manuellement les fichiers GGUF ou safetensors. Les fichiers template et params par défaut sont déjà inclus pour le modèle sur Hugging Face Hub.

1. Assure-toi que l'application Ollama est en cours d'exécution.

2. Accède à la page du modèle souhaité et copie l'URL. Par exemple, https://huggingface.co/Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF.

3. Depuis ton terminal, exécute la commande :

   ollama run hf.co/Qiskit/Qwen2.5-Coder-14B-Qiskit

Tu peux utiliser le modèle hf.co/Qiskit/Qwen2.5-Coder-14B-Qiskit ou l'un des autres modèles GGUF officiels actuellement recommandés : hf.co/Qiskit/mistral-small-3.2-24b-qiskit-GGUF ou hf.co/Qiskit/granite-3.3-8b-qiskit-GGUF.

Configurer Ollama avec un modèle GGUF Qiskit Code Assistant téléchargé manuellement

Si tu as téléchargé manuellement un modèle GGUF tel que https://huggingface.co/Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF et que tu souhaites expérimenter avec différents templates et paramètres, tu peux suivre ces étapes pour le charger dans ton application Ollama locale.

1. Crée un fichier Modelfile avec le contenu suivant, en veillant à remplacer <PATH-TO-GGUF-FILE> par le chemin réel de ton modèle téléchargé.

   FROM <PATH-TO-GGUF-FILE>
   TEMPLATE """{{ if .System }}
   System:
   {{ .System }}
   
   {{ end }}{{ if .Prompt }}Question:
   {{ .Prompt }}
   
   {{ end }}Answer:
   ```python{{ .Response }}
   """
   
   PARAMETER stop "Question:"
   PARAMETER stop "Answer:"
   PARAMETER stop "System:"
   PARAMETER stop "```"
   
   PARAMETER temperature 0
   PARAMETER top_k 1

2. Exécute la commande suivante pour créer une instance de modèle personnalisée basée sur le Modelfile.

   ollama create Qwen2.5-Coder-14B-Qiskit -f ./path-to-model-file

   remarque

   Ce processus peut prendre un certain temps pour qu'Ollama lise le fichier de modèle, initialise l'instance du modèle et la configure selon les spécifications fournies.

Exécuter le modèle Qiskit Code Assistant téléchargé manuellement dans Ollama

Une fois le modèle Qwen2.5-Coder-14B-Qiskit configuré dans Ollama, exécute la commande suivante pour lancer le modèle et interagir avec lui dans le terminal (en mode chat).

ollama run Qwen2.5-Coder-14B-Qiskit

Quelques commandes utiles :

• ollama list - Lister les modèles sur ton ordinateur
• ollama rm Qwen2.5-Coder-14B-Qiskit - Supprimer le modèle
• ollama show Qwen2.5-Coder-14B-Qiskit - Afficher les informations du modèle
• ollama stop Qwen2.5-Coder-14B-Qiskit - Arrêter un modèle en cours d'exécution
• ollama ps - Lister les modèles actuellement chargés

Déployer manuellement les modèles Qiskit Code Assistant en local via le paquet llama-cpp-python

Une alternative à l'application Ollama est le paquet llama-cpp-python, qui est une liaison Python pour llama.cpp. Il te donne plus de contrôle et de flexibilité pour exécuter le modèle GGUF localement, et est idéal pour les utilisateurs souhaitant intégrer le modèle local dans leurs flux de travail et applications Python.

1. Installe llama-cpp-python
2. Interagis avec le modèle depuis ton application en utilisant llama_cpp. Par exemple :

from llama_cpp import Llama

model_path = <PATH-TO-GGUF-FILE>

model = Llama(
        model_path,
        seed=17,
        n_ctx=10000,
        n_gpu_layers=37, # to offload in gpu, but put 0 if all in cpu
    )

input = 'Generate a quantum circuit with 2 qubits'
raw_pred = model(input)["choices"][0]["text"]

Tu peux également ajouter des paramètres de génération de texte au modèle pour personnaliser l'inférence :

generation_kwargs = {
        "max_tokens": 512,
        "echo": False, # Echo the prompt in the output
        "top_k": 1
    }

raw_pred = model(input, **generation_kwargs)["choices"][0]["text"]

Déployer manuellement les modèles Qiskit Code Assistant en local via llama.cpp

Utiliser la bibliothèque llama.cpp

Une autre alternative est d'utiliser llama.cpp, une bibliothèque open-source pour effectuer l'inférence de LLM sur un CPU avec une configuration minimale. Elle fournit un contrôle de bas niveau sur l'exécution du modèle et s'exécute généralement depuis la ligne de commande, en pointant vers un fichier de modèle GGUF local.

Il existe plusieurs façons d'installer llama.cpp sur ta machine :

• Installe llama.cpp en utilisant brew, nix ou winget
• Exécute avec Docker : Consulte la documentation Docker de l'équipe llama.cpp
• Télécharge les binaires pré-compilés depuis la page des versions
• Compile depuis les sources en clonant ce dépôt

Une fois installé, tu peux utiliser llama.cpp pour interagir avec les modèles GGUF en mode conversation comme suit :

# Use a local model file
llama-cli -m my_model.gguf -cnv

# Or download and run a model directly from Hugging Face
llama-cli -hf Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF -cnv

Tu peux également lancer un serveur API compatible OpenAI pour le modèle de la manière suivante :

llama-server -hf Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF

Paramètres avancés

Avec le programme llama-cli, tu peux contrôler la génération du modèle en utilisant des options en ligne de commande. Par exemple, tu peux fournir une invite « système » initiale en utilisant le drapeau -p/--prompt. En mode conversation (-cnv), cette invite initiale agit comme le message système. Sinon, tu peux simplement ajouter toute instruction souhaitée au début de ton texte d'invite. Tu peux également ajuster les paramètres d'échantillonnage - par exemple : la température (--temp), top-k (--top-k), top-p (--top-p), la pénalité de répétition (--repeat-penalty) et la graine à utiliser (--seed). Voici un exemple d'invocation utilisant ces options :

llama-cli -hf Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF \
  -p "You are a friendly assistant." -cnv \
  --temp 0.7 \
  --top-k 50 \
  --top-p 0.95 \
  --repeat-penalty 1.1 \
  --seed 42

Pour assurer le bon fonctionnement de nos modèles Qiskit, nous recommandons d'utiliser l'invite système fournie dans nos dépôts HF GGUF : invite système pour mistral-small-3.2-24b-qiskit-GGUF, Qwen2.5-Coder-14B-Qiskit-GGUF, granite-3.3-8b-qiskit-GGUF et granite-3.2-8b-qiskit-GGUF.

Connecter manuellement les extensions au déploiement local

Utilise l'extension VS Code et l'extension JupyterLab pour Qiskit Code Assistant afin d'interroger le modèle Qiskit Code Assistant déployé localement. Une fois l'application Ollama configurée avec le modèle, tu peux configurer les extensions pour qu'elles se connectent au service local.

Se connecter avec l'extension VS Code Qiskit Code Assistant

Avec l'extension VS Code Qiskit Code Assistant, tu peux interagir avec le modèle et effectuer la complétion de code pendant que tu écris. Cela convient parfaitement aux utilisateurs qui cherchent de l'aide pour écrire du code Qiskit dans leurs applications Python.

1. Installe l'extension VS Code Qiskit Code Assistant.
2. Dans VS Code, accède aux Paramètres utilisateur et définis Qiskit Code Assistant: Url sur l'URL de ton déploiement Ollama local (par exemple, http://localhost:11434).
3. Recharge VS Code en allant dans Affichage > Palette de commandes... et en sélectionnant Developer: Reload Window.

Le modèle Qiskit Code Assistant configuré dans Ollama devrait apparaître dans la barre d'état et est alors prêt à être utilisé.

Se connecter avec l'extension JupyterLab Qiskit Code Assistant

Avec l'extension JupyterLab Qiskit Code Assistant, tu peux interagir avec le modèle et effectuer la complétion de code directement dans ton Jupyter Notebook. Les utilisateurs qui travaillent principalement avec des Jupyter Notebooks peuvent tirer parti de cette extension pour améliorer leur expérience d'écriture de code Qiskit.

1. Installe l'extension JupyterLab Qiskit Code Assistant.
2. Dans JupyterLab, accède à l'Éditeur de paramètres et définis Qiskit Code Assistant Service API sur l'URL de ton déploiement Ollama local (par exemple, http://localhost:11434).

Le modèle Qiskit Code Assistant configuré dans Ollama devrait apparaître dans la barre d'état et est alors prêt à être utilisé.