Vai al contenuto principale

Usare Qiskit Code Assistant in modalità locale

Scopri come installare, configurare e usare uno qualsiasi dei modelli di Qiskit Code Assistant sul tuo computer locale.

Note
  • Qiskit Code Assistant è in stato di anteprima e potrebbe subire modifiche.
  • Per inviare feedback o contattare il team di sviluppo, usa il canale Qiskit Slack Workspace o i repository GitHub pubblici correlati.

Il modo più semplice per iniziare a usare Qiskit Code Assistant in modalità locale è ricorrere agli script di configurazione automatica per l'estensione VS Code o JupyterLab. Questi script installano automaticamente Ollama per eseguire i modelli LLM, scaricano il modello consigliato e configurano l'estensione per te.

Configurazione dell'estensione VS Code​

Esegui il comando seguente nel tuo terminale:

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

Questo script esegue i passaggi seguenti:

  • Installa Ollama (se non è già installato)
  • Scarica e configura il modello Qiskit Code Assistant consigliato
  • Configura l'estensione VS Code per funzionare con la tua installazione locale

Configurazione dell'estensione JupyterLab​

Esegui il comando seguente nel tuo terminale:

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

Questo script:

  • Installa Ollama (se non è già installato)
  • Scarica e configura il modello Qiskit Code Assistant consigliato
  • Configura l'estensione JupyterLab per funzionare con la tua installazione locale

Modelli disponibili​

Modelli attuali​

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

  1. Qiskit/mistral-small-3.2-24b-qiskit - Rilasciato a ottobre 2025
  2. qiskit/qwen2.5-coder-14b-qiskit - Rilasciato a giugno 2025
  3. qiskit/granite-3.3-8b-qiskit - Rilasciato a giugno 2025
  4. qiskit/granite-3.2-8b-qiskit - Rilasciato a giugno 2025

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

  1. mistral-small-3.2-24b-qiskit-GGUF – Rilasciato a ottobre 2025 Addestrato con dati Qiskit fino alla versione 2.1

  2. qiskit/qwen2.5-coder-14b-qiskit-GGUF – Rilasciato a giugno 2025 Addestrato con dati Qiskit fino alla versione 2.0

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

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

I modelli open source di Qiskit Code Assistant sono disponibili nei formati safetensors o GGUF e possono essere scaricati da Hugging Face come illustrato di seguito.

Versioni di Qiskit usate per l'addestramento​

Modello     Metriche di benchmark    Data di rilascioAddestrato sulla versione Qiskit
 QiskitHumanEval-HardQiskitHumanEvalHumanEvalASDivMathQASciQMBPPIFEvalCrowsPairs (inglese)TruthfulQA (MC1 acc)  
mistral-small-3.2-24b-qiskit32.4547.0277.493.7749.6897.5064.0048.4467.0839.41gennaio 20262.2
qwen2.5-coder-14b-qiskit25.1749.0191.464.2153.9097.0077.6049.6465.1837.82giugno 20252.0
granite-3.3-8b-qiskit14.5727.1562.800.4838.6693.3052.4059.7159.7539.05giugno 20252.0
granite-3.2-8b-qiskit9.9324.5057.320.0941.4196.3051.8060.7966.7940.51giugno 20252.0
granite-8b-qiskit-rc-0.1015.8938.4159.76———————febbraio 20251.3
granite-8b-qiskit17.8844.3753.66———————novembre 20241.2

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

Modelli deprecati​

Questi modelli non sono più mantenuti attivamente, ma rimangono disponibili:

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

Configurazione avanzata​

Se preferisci configurare manualmente la tua installazione locale o hai bisogno di un maggiore controllo sul processo di installazione, espandi le sezioni seguenti.

Scarica dal sito web di Hugging Face

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

  1. Naviga alla pagina del modello Qiskit desiderato su Hugging Face.
  2. Vai alla scheda Files and Versions e scarica i file del modello in formato safetensors o GGUF.
Scarica tramite la CLI di Hugging Face

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

  1. Installa la CLI di Hugging Face

  2. Accedi al tuo account Hugging Face

    huggingface-cli login

  3. Scarica il modello che preferisci dall'elenco precedente

    huggingface-cli download <HF REPO NAME> <MODEL PATH> --local-dir <LOCAL PATH>
Distribuzione manuale dei modelli Qiskit Code Assistant in locale tramite Ollama

Esistono più modi per distribuire e interagire con il modello Qiskit Code Assistant scaricato. Questa guida mostra come usare Ollama: sia con l'applicazione Ollama tramite l'integrazione con Hugging Face Hub o un modello locale, sia con il pacchetto llama-cpp-python.

Usare l'applicazione Ollama​

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

Installare Ollama​

  1. Scarica l'applicazione Ollama

  2. Installa il file scaricato

  3. 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 visitando http://localhost:11434/.

  4. Prova Ollama nel tuo terminale e inizia a eseguire modelli. Ad esempio:

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

Configurare Ollama tramite l'integrazione con Hugging Face Hub​

L'integrazione Ollama/Hugging Face Hub consente di 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.

  1. Assicurati che l'applicazione Ollama sia in esecuzione.

  2. Vai alla pagina del modello desiderato e copia l'URL. Ad esempio, https://huggingface.co/Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF.

  3. Dal tuo 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 qualsiasi 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.

Configurare 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 nella tua applicazione Ollama locale.

  1. Crea un Modelfile inserendo il contenuto seguente 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

  2. Run the following command to create a custom model instance based on the Modelfile.

    ollama create Qwen2.5-Coder-14B-Qiskit -f ./path-to-model-file
    nota
    This process may take some time for Ollama to read the model file, initialize the model instance, and configure it according to the specifications provided.

Run the Qiskit Code Assistant model manually downloaded in Ollama​

After the Qwen2.5-Coder-14B-Qiskit model has been set up in Ollama, run the following command to launch the model and interact with it in the terminal (in chat mode).

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

Some useful commands:

  • ollama list - List models on your computer
  • ollama rm Qwen2.5-Coder-14B-Qiskit - Delete the model
  • ollama show Qwen2.5-Coder-14B-Qiskit - Show model information
  • ollama stop Qwen2.5-Coder-14B-Qiskit - Stop a model that is currently running
  • ollama ps - List which models are currently loaded
Manually deploy the Qiskit Code Assistant models in local through the llama-cpp-python package

An alternative to the Ollama application is the llama-cpp-python package, which is a Python binding for llama.cpp. It gives you more control and flexibility to run the GGUF model locally, and is ideal for users who wish to integrate the local model in their workflows and Python applications.

  1. Install llama-cpp-python
  2. Interact with the model from within your application using llama_cpp. For example:
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"]

You can also add text generation parameters to the model to customize the inference:

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"]
Manually deploy the Qiskit Code Assistant models in local through llama.cpp

Use the llama.cpp library​

Another alternative is to use llama.cpp, an open-source library for performing LLM inference on a CPU with minimal setup. It provides low-level control over the model execution and is typically run from the command line, pointing to a local GGUF model file.

There are several ways to install llama.cpp on your machine:

Once installed, you can use llama.cpp to interact with GGUF models in conversation mode as follows:

# 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

You can also launch an OpenAI-compatible API server for the model in the following way:

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

Advanced parameters​

With the llama-cli program, you can control the model generation using command-line options. For example, you can provide an initial “system” prompt using the -p/--prompt flag. In conversation mode (-cnv), this initial prompt acts as the system message. Otherwise, you can simply prepend any desired instruction to your prompt text. You can also adjust sampling parameters - for instance: temperature (--temp), top-k (--top-k), top-p (--top-p), repetition penalty (--repeat-penalty), and the seed to use (--seed). The following is an example invocation using these 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

Per garantire il corretto funzionamento dei nostri modelli Qiskit, consigliamo di usare 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.

Collegare manualmente le estensioni alla distribuzione locale

Usa l'estensione VS Code e l'estensione JupyterLab per Qiskit Code Assistant per inviare prompt al modello Qiskit Code Assistant distribuito localmente. Una volta che hai configurato l'applicazione Ollama con il modello, puoi configurare le estensioni per connettersi al servizio locale.

Collegare l'estensione VS Code di Qiskit Code Assistant​

Con l'estensione VS Code di Qiskit Code Assistant, puoi interagire con il modello ed eseguire il completamento del codice mentre scrivi. È particolarmente utile per gli utenti che cercano assistenza nella scrittura di codice Qiskit per le loro applicazioni Python.

  1. Installa l'estensione VS Code di Qiskit Code Assistant.
  2. In VS Code, vai alle Impostazioni utente e imposta Qiskit Code Assistant: Url sull'URL della tua distribuzione Ollama locale (ad esempio, http://localhost:11434).
  3. Ricarica VS Code andando su Visualizza > Riquadro comandi... e selezionando Sviluppatore: Ricarica finestra.

Il modello Qiskit Code Assistant configurato in Ollama dovrebbe apparire nella barra di stato ed è quindi pronto all'uso.

Collegare l'estensione JupyterLab di Qiskit Code Assistant​

Con l'estensione JupyterLab di Qiskit Code Assistant, puoi interagire con il modello ed eseguire il completamento del codice direttamente nel tuo Jupyter Notebook. Gli utenti che lavorano prevalentemente con Jupyter Notebook possono sfruttare questa estensione per migliorare ulteriormente la propria esperienza nella scrittura di codice Qiskit.

  1. Installa l'estensione JupyterLab di Qiskit Code Assistant.
  2. In JupyterLab, vai all'Editor delle impostazioni e imposta Qiskit Code Assistant Service API sull'URL della tua distribuzione Ollama locale (ad esempio, http://localhost:11434).

Il modello Qiskit Code Assistant configurato in Ollama dovrebbe apparire nella barra di stato ed è quindi pronto all'uso.