Qiskit Code Assistant

Gli LLM di Qiskit Code Assistant mirano a rendere il quantum computing più accessibile ai nuovi utenti di Qiskit e a migliorare l'esperienza di programmazione per gli utenti già attivi. Sono stati addestrati utilizzando milioni di token di testo dal Qiskit SDK, anni di esempi di codice Qiskit e le funzionalità di IBM Quantum®. Qiskit Code Assistant può supportare il tuo flusso di lavoro per lo sviluppo quantistico offrendo suggerimenti generati da LLM basati sui modelli IBM Granite e altri modelli open source, che incorporano le funzionalità e le caratteristiche più recenti di IBM®.

Note

Vuoi passare direttamente alle istruzioni di installazione? Vai alla sezione Installa Qiskit Code Assistant.
Per inviare feedback o contattare il team di sviluppo, usa il canale Qiskit Slack Workspace o i repository pubblici GitHub correlati.

Il Large Language Model (LLM) alla base di Qiskit Code Assistant

Per fornire suggerimenti di codice, Qiskit Code Assistant utilizza un Large Language Model (LLM). In questo caso, Qiskit Code Assistant si basa attualmente sul modello mistral-small-3.2-24b-qiskit, costruito sul modello Mistral-Small-3.2-24B-Qiskit. Il modello mistral-small-3.2-24b-qiskit migliora le capacità di generazione del codice per Qiskit del modello Mistral-Small-3.2-24B-Instruct-2506 attraverso un pre-addestramento esteso e il fine-tuning su dati Qiskit di alta qualità, nonché commit Python e chat. Per ulteriori informazioni sulla famiglia di modelli Mistral AI, consulta la documentazione di Mistral AI. Per maggiori dettagli sui modelli .*-qiskit, vedi Qiskit Code Assistant: Training LLMs for generating Quantum Computing Code.

I nostri LLM specializzati per Qiskit sono disponibili anche come modelli open source. Consulta tutti i modelli disponibili su https://huggingface.co/Qiskit.

I benchmark Qiskit HumanEval e Qiskit HumanEval Hard

Per testare il modello mistral-small-3.2-24b-qiskit e altri modelli, abbiamo collaborato con i Qiskit Advocates ed esperti del settore per creare i benchmark basati sull'esecuzione chiamati Qiskit HumanEval (QHE) e Qiskit HumanEval Hard (QHE Hard), ed eseguirli sui modelli. Questi benchmark sono simili a HumanEval e includono molteplici problemi di codice impegnativi da risolvere, tutti basati sulle librerie ufficiali di Qiskit.

I benchmark sono composti da circa 150 test, ognuno dei quali è composto da una definizione di funzione seguita da una docstring che dettaglia il compito che il modello deve risolvere. Ogni esempio include anche una soluzione canonica di riferimento e unit test per valutare la correttezza delle soluzioni generate. Esistono tre livelli di difficoltà per i test: base, intermedio e difficile. Il benchmark Qiskit HumanEval Hard è una variante del Qiskit HumanEval, ma rimuove le informazioni relative agli import del codice, quindi l'LLM deve determinare autonomamente i giusti import di metodi o classi. Questa modifica rende il dataset molto più impegnativo per gli LLM, secondo i nostri test e i risultati iniziali.

I dataset per Qiskit HumanEval e Qiskit HumanEval Hard sono disponibili sui seguenti siti: Qiskit HumanEval e Qiskit HumanEval. Puoi contribuire allo sviluppo di questi benchmark nel repository GitHub.

Installa Qiskit Code Assistant

Scopri come installare, configurare e usare uno qualsiasi dei modelli di Qiskit Code Assistant sulla tua macchina locale.

Scarica dal sito di Hugging Face

Segui questi passaggi per scaricare qualsiasi modello correlato a Qiskit Code Assistant dal sito di Hugging Face:

Vai alla pagina del modello Qiskit desiderato su Hugging Face.
Vai alla scheda Files and Versions e scarica i file del modello in formato safetensors o GGUF.

Scarica usando la CLI di Hugging Face

Per scaricare uno qualsiasi dei modelli Qiskit Code Assistant disponibili usando la CLI di Hugging Face, segui questi passaggi:

Installa la CLI di Hugging Face
Accedi al tuo account Hugging Face
```
huggingface-cli login
```

Scarica il modello che preferisci dall'elenco precedente

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

Distribuisci manualmente i modelli Qiskit Code Assistant in locale tramite Ollama

Esistono diversi modi per distribuire e interagire con il modello Qiskit Code Assistant scaricato. Questa guida illustra l'uso di Ollama: tramite l'applicazione Ollama usando l'integrazione con Hugging Face Hub o il modello locale, oppure con il pacchetto llama-cpp-python.

Usare l'applicazione Ollama

L'applicazione Ollama offre una soluzione semplice per eseguire gli LLM in locale. È facile da usare, con una CLI che rende l'intero processo di configurazione, la gestione dei modelli e l'interazione piuttosto semplici. È ideale per sperimentazioni rapide e per gli utenti che vogliono gestire meno dettagli tecnici.

Installa Ollama

Scarica l'applicazione Ollama
Installa il file scaricato
Avvia l'applicazione Ollama installata

info
L'applicazione è in esecuzione correttamente quando l'icona di Ollama appare nella barra dei menu del desktop. Puoi anche verificare che il servizio sia in esecuzione andando su http://localhost:11434/.
Prova Ollama nel terminale e inizia a eseguire i modelli. Per esempio:
```
ollama run hf.co/Qiskit/Qwen2.5-Coder-14B-Qiskit
```

Configura Ollama usando l'integrazione con Hugging Face Hub

L'integrazione Ollama/Hugging Face Hub offre un modo per interagire con i modelli ospitati su Hugging Face Hub senza dover creare un nuovo modelfile né scaricare manualmente i file GGUF o safetensors. I file template e params predefiniti sono già inclusi per il modello su Hugging Face Hub.

Assicurati che l'applicazione Ollama sia in esecuzione.
Vai alla pagina del modello desiderato e copia l'URL. Per esempio, https://huggingface.co/Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF.

Dal terminale, esegui il comando:

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

Puoi usare il modello hf.co/Qiskit/Qwen2.5-Coder-14B-Qiskit o uno degli altri modelli GGUF ufficiali attualmente consigliati hf.co/Qiskit/mistral-small-3.2-24b-qiskit-GGUF o hf.co/Qiskit/granite-3.3-8b-qiskit-GGUF.

Configura Ollama con un modello GGUF di Qiskit Code Assistant scaricato manualmente

Se hai scaricato manualmente un modello GGUF come https://huggingface.co/Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF e vuoi sperimentare con template e parametri diversi, puoi seguire questi passaggi per caricarlo nell'applicazione Ollama locale.

Crea un Modelfile inserendo il seguente contenuto e assicurati di aggiornare <PATH-TO-GGUF-FILE> con il percorso effettivo del modello scaricato.

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

Esegui il seguente comando per creare un'istanza del modello personalizzata basata sul Modelfile.
```
ollama create Qwen2.5-Coder-14B-Qiskit -f ./path-to-model-file
```
nota
Questo processo potrebbe richiedere del tempo affinché Ollama legga il file del modello, inizializzi l'istanza del modello e la configuri in base alle specifiche fornite.

Esegui il modello Qiskit Code Assistant scaricato manualmente in Ollama

Dopo che il modello Qwen2.5-Coder-14B-Qiskit è stato configurato in Ollama, esegui il seguente comando per avviare il modello e interagire con esso nel terminale (in modalità chat).

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

Alcuni comandi utili:

ollama list - Elenca i modelli sul tuo computer
ollama rm Qwen2.5-Coder-14B-Qiskit - Elimina il modello
ollama show Qwen2.5-Coder-14B-Qiskit - Mostra le informazioni del modello
ollama stop Qwen2.5-Coder-14B-Qiskit - Interrompi un modello attualmente in esecuzione
ollama ps - Elenca i modelli attualmente caricati

Distribuisci manualmente i modelli Qiskit Code Assistant in locale tramite il pacchetto llama-cpp-python

Un'alternativa all'applicazione Ollama è il pacchetto llama-cpp-python, che è un binding Python per llama.cpp. Ti offre più controllo e flessibilità per eseguire il modello GGUF localmente, ed è ideale per gli utenti che desiderano integrare il modello locale nei propri workflow e nelle proprie applicazioni Python.

Installa llama-cpp-python
Interagisci con il modello dall'interno della tua applicazione utilizzando llama_cpp. Ad esempio:

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"]

Puoi anche aggiungere parametri di generazione del testo al modello per personalizzare l'inferenza:

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"]

Distribuisci manualmente i modelli Qiskit Code Assistant in locale tramite llama.cpp

Utilizza la libreria `llama.cpp`

Un'altra alternativa è utilizzare llama.cpp, una libreria open-source per eseguire l'inferenza LLM su una CPU con configurazione minima. Fornisce un controllo di basso livello sull'esecuzione del modello ed è tipicamente eseguita dalla riga di comando, puntando a un file modello GGUF locale.

Ci sono diversi modi per installare llama.cpp sulla tua macchina:

Installa llama.cpp usando brew, nix, o winget
Esegui con Docker: Consulta la documentazione Docker del team llama.cpp
Scarica binari precompilati dalla pagina delle release
Compila dal sorgente clonando questo repository

Una volta installato, puoi utilizzare llama.cpp per interagire con i modelli GGUF in modalità conversazione come segue:

# Use a local model file \{#use-a-local-model-file}
llama-cli -m my_model.gguf -cnv

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

Puoi anche avviare un server API compatibile con OpenAI per il modello nel seguente modo:

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

Parametri avanzati

Con il programma llama-cli, puoi controllare la generazione del modello utilizzando opzioni della riga di comando. Ad esempio, puoi fornire un prompt di "sistema" iniziale utilizzando il flag -p/--prompt. In modalità conversazione (-cnv), questo prompt iniziale funge da messaggio di sistema. Altrimenti, puoi semplicemente anteporre qualsiasi istruzione desiderata al testo del tuo prompt. Puoi anche regolare i parametri di campionamento - ad esempio: temperatura (--temp), top-k (--top-k), top-p (--top-p), penalità di ripetizione (--repeat-penalty), e il seed da utilizzare (--seed). Di seguito è riportato un esempio di invocazione che utilizza queste opzioni:

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

Per garantire il corretto funzionamento dei nostri modelli Qiskit, consigliamo di utilizzare il prompt di sistema fornito nei nostri repository HF GGUF: prompt di sistema per mistral-small-3.2-24b-qiskit-GGUF, Qwen2.5-Coder-14B-Qiskit-GGUF, granite-3.3-8b-qiskit-GGUF, e granite-3.2-8b-qiskit-GGUF.

Connetti manualmente Continue (VS Code)

Continue (VS Code)

1. Installa l'estensione

Apri VS Code, vai su Extensions (Cmd+Shift+X), cerca Continue, installalo.

2. Apri la configurazione

Clicca sull'icona Continue nella barra laterale, poi clicca sull'icona a forma di ingranaggio, oppure apri la command palette (Cmd+Shift+P) ed esegui Continue: Open Config File.

Questo apre ~/.continue/config.yaml (o config.json nelle versioni precedenti).

3. Configura il modello

Aggiungi quanto segue a config.yaml:

models:
  - name: Qiskit Code Assistant
    provider: ollama
    model: mistral-small-3.2-24b-qiskit
    apiBase: http://localhost:11434

Questo rende il modello Qiskit disponibile nel pannello di chat (conversazioni nella barra laterale, Q&A in linea) e per i comandi di modifica in linea.

4. Test it

Chat: Apri il pannello Continue nella barra laterale e fai una domanda (ad es., "Come creo un circuito parametrizzato in Qiskit?")
Modifica in linea: Seleziona un blocco di codice, premi Cmd+I (Mac) o Ctrl+I (Linux/Windows)

Connetti manualmente Jupyter AI (JupyterLab)

Jupyter AI (JupyterLab)

Nota: Queste istruzioni riguardano Jupyter AI v2.x.

1. Installa Jupyter AI e il provider Ollama

pip install "jupyter-ai<3" langchain-ollama

Il pin "jupyter-ai<3" garantisce di ottenere la v2.x. Il pacchetto langchain-ollama è necessario affinché Jupyter AI rilevi Ollama come provider. Senza di esso, Ollama non apparirà nel pannello delle impostazioni.

Quindi riavvia JupyterLab.

2. Configura il modello di chat

Apri JupyterLab e clicca sull'icona chat nella barra laterale sinistra. Nel pannello delle impostazioni:

Sotto Language model, seleziona Ollama come provider.
Inserisci mistral-small-3.2-24b-qiskit come nome del modello.
Non è necessaria alcuna chiave API per Ollama (lascia il campo vuoto).
Clicca sulla freccia indietro per iniziare a chattare.

3. Usa il comando magico `%%ai`

Il comando magico %%ai ti permette di interrogare il modello direttamente nelle celle del notebook.

%load_ext jupyter_ai_magics

Poi in una cella:

%%ai ollama:mistral-small-3.2-24b-qiskit
Write a function that implements Grover's algorithm using Qiskit

4. Host Ollama personalizzato (opzionale)

Per impostazione predefinita, Jupyter AI si connette a http://127.0.0.1:11434. Se il tuo server Ollama è in esecuzione su un indirizzo o una porta diversi:

Nell'interfaccia della chat: Imposta il campo "Base API URL" nel pannello delle impostazioni AI.

Connetti manualmente OpenCode (Terminale)

OpenCode (Terminale)

1. Installa OpenCode

curl -fsSL https://opencode.ai/install | bash

2. Configura il modello Qiskit

Crea un file opencode.json nella radice del tuo progetto (o ~/.config/opencode/opencode.json per una configurazione globale):

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "mistral-small-3.2-24b-qiskit": {
          "name": "Qiskit Code Assistant"
        }
      }
    }
  }
}

3. Seleziona il modello

Avvia OpenCode nella directory del tuo progetto:

opencode

All'interno della TUI, esegui il comando /models e seleziona Qiskit Code Assistant dall'elenco.

4. Test it

Fai una domanda direttamente nella chat, ad esempio: "Definisci un circuito di Bell ed eseguilo usando QiskitRuntimeService"

Modelli disponibili

Modelli attuali

Questi sono i modelli più recenti consigliati per l'uso con Qiskit Code Assistant:

Qiskit/mistral-small-3.2-24b-qiskit - Rilasciato ottobre 2025
Qiskit/Qwen2.5-Coder-14B-Qiskit - Rilasciato giugno 2025
qiskit/granite-3.3-8b-qiskit - Rilasciato giugno 2025
qiskit/granite-3.2-8b-qiskit - Rilasciato giugno 2025

Modelli GGUF (consigliati per ambienti personali/laptop)

I modelli in formato GGUF sono ottimizzati per l'uso locale e richiedono meno risorse computazionali:

mistral-small-3.2-24b-qiskit-GGUF – Rilasciato ottobre 2025

Addestrato con dati Qiskit fino alla versione 2.1
Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF – Rilasciato giugno 2025

Addestrato con dati Qiskit fino alla versione 2.0
qiskit/granite-3.3-8b-qiskit-GGUF – Rilasciato giugno 2025

Addestrato con dati Qiskit fino alla versione 2.0
qiskit/granite-3.2-8b-qiskit-GGUF – Rilasciato giugno 2025

Addestrato con dati Qiskit fino alla versione 2.0

I modelli Open Source di Qiskit Code Assistant sono disponibili in formato safetensors o GGUF file format e possono essere scaricati da Hugging Face come spiegato di seguito.

Versioni di Qiskit usate per l'addestramento

Modello						Metriche di benchmark					Data di rilascio	Versione di Qiskit su cui è stato addestrato
	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	January 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	June 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	June 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	June 2025	2.0
granite-8b-qiskit-rc-0.10	15.89	38.41	59.76	—	—	—	—	—	—	—	February 2025	1.3
granite-8b-qiskit	17.88	44.37	53.66	—	—	—	—	—	—	—	November 2024	1.2

Nota: tutti i modelli elencati nella tabella dei benchmark sono stati valutati usando il rispettivo prompt di sistema, definito nel loro modello su Hugging Face.

Modelli deprecati

Questi modelli non sono più mantenuti attivamente ma restano disponibili:

qiskit/granite-8b-qiskit-rc-0.10 - Rilasciato febbraio 2025 (deprecato)
qiskit/granite-8b-qiskit - Rilasciato novembre 2024 (deprecato)

Ulteriori informazioni e citazioni

Per saperne di più su Qiskit Code Assistant, i benchmark Qiskit HumanEval o Qiskit HumanEval Hard, e per citarli nelle tue pubblicazioni scientifiche, consulta queste citazioni consigliate:

@misc{2405.19495,
Author = {Nicolas Dupuis and Luca Buratti and Sanjay Vishwakarma and Aitana Viudes Forrat and David Kremer and Ismael Faro and Ruchir Puri and Juan Cruz-Benito},
Title = {Qiskit Code Assistant: Training LLMs for generating Quantum Computing Code},
Year = {2024},
Eprint = {arXiv:2405.19495},
}

@misc{2406.14712,
Author = {Sanjay Vishwakarma and Francis Harkins and Siddharth Golecha and Vishal Sharathchandra Bajpe and Nicolas Dupuis and Luca Buratti and David Kremer and Ismael Faro and Ruchir Puri and Juan Cruz-Benito},
Title = {Qiskit HumanEval: An Evaluation Benchmark For Quantum Code Generative Models},
Year = {2024},
Eprint = {arXiv:2406.14712},
}

@misc{2508.20907,
Author = {Nicolas Dupuis and Adarsh Tiwari and Youssef Mroueh and David Kremer and Ismael Faro and Juan Cruz-Benito},
Title = {Quantum Verifiable Rewards for Post-Training Qiskit Code Assistant},
Year = {2025},
Eprint = {arXiv:2508.20907},
}

Il Large Language Model (LLM) alla base di Qiskit Code Assistant​

I benchmark Qiskit HumanEval e Qiskit HumanEval Hard​

Installa Qiskit Code Assistant​

Usare l'applicazione Ollama​

Installa Ollama​

Configura Ollama usando l'integrazione con Hugging Face Hub​

Configura Ollama con un modello GGUF di Qiskit Code Assistant scaricato manualmente​

Esegui il modello Qiskit Code Assistant scaricato manualmente in Ollama​

Utilizza la libreria llama.cpp​

Parametri avanzati​

Continue (VS Code)​

1. Installa l'estensione​

2. Apri la configurazione​

3. Configura il modello​

4. Test it​

Jupyter AI (JupyterLab)​

1. Installa Jupyter AI e il provider Ollama​

2. Configura il modello di chat​

3. Usa il comando magico %%ai​

4. Host Ollama personalizzato (opzionale)​

OpenCode (Terminale)​

1. Installa OpenCode​

2. Configura il modello Qiskit​

3. Seleziona il modello​

4. Test it​

Modelli disponibili​

Modelli attuali​

Modelli GGUF (consigliati per ambienti personali/laptop)​

Versioni di Qiskit usate per l'addestramento​

Modelli deprecati​

Ulteriori informazioni e citazioni​

Il Large Language Model (LLM) alla base di Qiskit Code Assistant

I benchmark Qiskit HumanEval e Qiskit HumanEval Hard

Installa Qiskit Code Assistant

Usare l'applicazione Ollama

Installa Ollama

Configura Ollama usando l'integrazione con Hugging Face Hub

Configura Ollama con un modello GGUF di Qiskit Code Assistant scaricato manualmente

Esegui il modello Qiskit Code Assistant scaricato manualmente in Ollama

Utilizza la libreria `llama.cpp`

Parametri avanzati

Continue (VS Code)

1. Installa l'estensione

2. Apri la configurazione

3. Configura il modello

4. Test it

Jupyter AI (JupyterLab)

1. Installa Jupyter AI e il provider Ollama

2. Configura il modello di chat

3. Usa il comando magico `%%ai`

4. Host Ollama personalizzato (opzionale)

OpenCode (Terminale)

1. Installa OpenCode

2. Configura il modello Qiskit

3. Seleziona il modello

4. Test it

Modelli disponibili

Modelli attuali

Modelli GGUF (consigliati per ambienti personali/laptop)

Versioni di Qiskit usate per l'addestramento

Modelli deprecati

Ulteriori informazioni e citazioni