Qiskit Code Assistant im lokalen Modus verwenden

Lerne, wie du eines der Qiskit Code Assistant-Modelle auf deinem lokalen Rechner installierst, konfigurierst und verwendest.

Hinweise

• Qiskit Code Assistant befindet sich im Preview-Release-Status und kann sich ändern.
• Wenn du Feedback geben oder das Entwicklerteam kontaktieren möchtest, nutze den Qiskit Slack Workspace-Kanal oder die zugehörigen öffentlichen GitHub-Repositories.

Schnellstart (empfohlen)

Der einfachste Weg, mit Qiskit Code Assistant im lokalen Modus zu beginnen, sind die automatisierten Setup-Skripte für die VS Code- oder JupyterLab-Erweiterung. Diese Skripte installieren automatisch Ollama, um die LLMs auszuführen, laden das empfohlene Modell herunter und konfigurieren die Erweiterung für dich.

Setup der VS Code-Erweiterung

Führe den folgenden Befehl in deinem Terminal aus:

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

Dieses Skript führt die folgenden Schritte aus:

• Ollama installieren (falls noch nicht vorhanden)
• Das empfohlene Qiskit Code Assistant-Modell herunterladen und konfigurieren
• Die VS Code-Erweiterung für deine lokale Bereitstellung einrichten

Setup der JupyterLab-Erweiterung

Führe den folgenden Befehl in deinem Terminal aus:

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

Dieses Skript führt folgende Schritte aus:

• Ollama installieren (falls noch nicht vorhanden)
• Das empfohlene Qiskit Code Assistant-Modell herunterladen und konfigurieren
• Die JupyterLab-Erweiterung für deine lokale Bereitstellung einrichten

Verfügbare Modelle

Aktuelle Modelle

Dies sind die neuesten empfohlenen Modelle für die Verwendung mit Qiskit Code Assistant:

1. Qiskit/mistral-small-3.2-24b-qiskit – Veröffentlicht Oktober 2025
2. qiskit/qwen2.5-coder-14b-qiskit – Veröffentlicht Juni 2025
3. qiskit/granite-3.3-8b-qiskit – Veröffentlicht Juni 2025
4. qiskit/granite-3.2-8b-qiskit – Veröffentlicht Juni 2025

GGUF-Modelle (empfohlen für persönliche Umgebungen/Laptops)

GGUF-Format-Modelle sind für den lokalen Einsatz optimiert und benötigen weniger Rechenressourcen:

1. mistral-small-3.2-24b-qiskit-GGUF – Veröffentlicht Oktober 2025 Trainiert mit Qiskit-Daten bis Version 2.1

2. qiskit/qwen2.5-coder-14b-qiskit-GGUF – Veröffentlicht Juni 2025 Trainiert mit Qiskit-Daten bis Version 2.0

3. qiskit/granite-3.3-8b-qiskit-GGUF – Veröffentlicht Juni 2025 Trainiert mit Qiskit-Daten bis Version 2.0

4. qiskit/granite-3.2-8b-qiskit-GGUF – Veröffentlicht Juni 2025 Trainiert mit Qiskit-Daten bis Version 2.0

Die Open-Source-Qiskit Code Assistant-Modelle sind im safetensors- oder GGUF-Dateiformat verfügbar und können wie nachfolgend beschrieben von Hugging Face heruntergeladen werden.

Für das Training verwendete Qiskit-Versionen

Modell						Benchmark-Metriken					Veröffentlichungsdatum	Trainiert auf Qiskit-Version
	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	Januar 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	Juni 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	Juni 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	Juni 2025	2.0
granite-8b-qiskit-rc-0.10	15.89	38.41	59.76	—	—	—	—	—	—	—	Februar 2025	1.3
granite-8b-qiskit	17.88	44.37	53.66	—	—	—	—	—	—	—	November 2024	1.2

Hinweis: Alle in der Benchmark-Tabelle aufgeführten Modelle wurden mit ihrem jeweiligen System-Prompt ausgewertet, der im zugehörigen Hugging Face-Modell definiert ist.

Veraltete Modelle

Diese Modelle werden nicht mehr aktiv gepflegt, sind aber weiterhin verfügbar:

1. qiskit/granite-8b-qiskit-rc-0.10 – Veröffentlicht Februar 2025 (veraltet)
2. qiskit/granite-8b-qiskit – Veröffentlicht November 2024 (veraltet)

Erweitertes Setup

Wenn du deine lokale Umgebung lieber manuell konfigurieren oder mehr Kontrolle über den Installationsprozess haben möchtest, klappe die folgenden Abschnitte auf.

Von der Hugging Face-Website herunterladen

Folge diesen Schritten, um ein beliebiges Qiskit Code Assistant-Modell von der Hugging Face-Website herunterzuladen:

1. Rufe die gewünschte Qiskit-Modellseite auf Hugging Face auf.
2. Gehe zum Tab Files and Versions und lade die safetensors- oder GGUF-Modelldateien herunter.

Mit der Hugging Face CLI herunterladen

Um eines der verfügbaren Qiskit Code Assistant-Modelle mit der Hugging Face CLI herunterzuladen, folge diesen Schritten:

1. Installiere die Hugging Face CLI

2. Melde dich bei deinem Hugging Face-Konto an

   huggingface-cli login

3. Lade das gewünschte Modell aus der vorherigen Liste herunter

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

Qiskit Code Assistant-Modelle lokal manuell über Ollama bereitstellen

Es gibt mehrere Möglichkeiten, das heruntergeladene Qiskit Code Assistant-Modell bereitzustellen und damit zu interagieren. Diese Anleitung zeigt die Verwendung von Ollama: entweder mit der Ollama-Anwendung über die Hugging Face Hub-Integration oder ein lokales Modell, oder mit dem llama-cpp-python-Paket.

Die Ollama-Anwendung verwenden

Die Ollama-Anwendung bietet eine einfache Möglichkeit, LLMs lokal auszuführen. Die Bedienung ist unkompliziert – dank einer CLI, die den gesamten Setup-Prozess, die Modellverwaltung und die Interaktion übersichtlich gestaltet. Sie eignet sich ideal für schnelle Experimente und für Nutzer, die sich weniger mit technischen Details befassen möchten.

Ollama installieren

1. Lade die Ollama-Anwendung herunter

2. Installiere die heruntergeladene Datei

3. Starte die installierte Ollama-Anwendung

   info

   Die Anwendung läuft erfolgreich, wenn das Ollama-Symbol in der Desktop-Menüleiste erscheint. Du kannst auch überprüfen, ob der Dienst läuft, indem du http://localhost:11434/ aufrufst.

4. Teste Ollama in deinem Terminal und starte Modelle. Zum Beispiel:

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

Ollama mit der Hugging Face Hub-Integration einrichten

Die Ollama/Hugging Face Hub-Integration ermöglicht die Interaktion mit auf dem Hugging Face Hub gehosteten Modellen, ohne eine neue Modelfile erstellen oder die GGUF- oder safetensors-Dateien manuell herunterladen zu müssen. Die Standard-template- und params-Dateien sind für das Modell im Hugging Face Hub bereits enthalten.

1. Stelle sicher, dass die Ollama-Anwendung läuft.

2. Rufe die gewünschte Modellseite auf und kopiere die URL. Zum Beispiel: https://huggingface.co/Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF.

3. Führe in deinem Terminal den folgenden Befehl aus:

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

Du kannst das Modell hf.co/Qiskit/Qwen2.5-Coder-14B-Qiskit oder eines der anderen aktuell empfohlenen offiziellen GGUF-Modelle hf.co/Qiskit/mistral-small-3.2-24b-qiskit-GGUF oder hf.co/Qiskit/granite-3.3-8b-qiskit-GGUF verwenden.

Ollama mit einem manuell heruntergeladenen Qiskit Code Assistant-GGUF-Modell einrichten

Wenn du ein GGUF-Modell wie https://huggingface.co/Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF manuell heruntergeladen hast und mit verschiedenen Templates und Parametern experimentieren möchtest, kannst du diese Schritte befolgen, um es in deine lokale Ollama-Anwendung zu laden.

1. Erstelle eine Modelfile mit folgendem Inhalt und ersetze <PATH-TO-GGUF-FILE> durch den tatsächlichen Pfad deines heruntergeladenen Modells.

   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

   hinweis

   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:

• Install llama.cpp using brew, nix, or winget
• Run with Docker: See out the Docker documentation by llama.cpp team
• Download pre-built binaries from the releases page
• Build from source by cloning this repository

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

Um die korrekte Funktionalität unserer Qiskit-Modelle sicherzustellen, empfehlen wir, den in unseren HF GGUF-Repositories bereitgestellten System-Prompt zu verwenden: System-Prompt für mistral-small-3.2-24b-qiskit-GGUF, Qwen2.5-Coder-14B-Qiskit-GGUF, granite-3.3-8b-qiskit-GGUF und granite-3.2-8b-qiskit-GGUF.

Erweiterungen manuell mit der lokalen Bereitstellung verbinden

Verwende die VS Code-Erweiterung und die JupyterLab-Erweiterung für den Qiskit Code Assistant, um das lokal bereitgestellte Qiskit Code Assistant-Modell anzusprechen. Sobald du die Ollama-Anwendung mit dem Modell eingerichtet hast, kannst du die Erweiterungen so konfigurieren, dass sie sich mit dem lokalen Dienst verbinden.

Mit der Qiskit Code Assistant VS Code-Erweiterung verbinden

Mit der Qiskit Code Assistant VS Code-Erweiterung kannst du mit dem Modell interagieren und während des Schreibens deines Codes Code-Vervollständigungen erhalten. Das eignet sich gut für Nutzer, die beim Schreiben von Qiskit-Code in ihren Python-Anwendungen Unterstützung suchen.

1. Installiere die Qiskit Code Assistant VS Code-Erweiterung.
2. Gehe in VS Code zu den Benutzereinstellungen und setze Qiskit Code Assistant: Url auf die URL deiner lokalen Ollama-Bereitstellung (zum Beispiel http://localhost:11434).
3. Lade VS Code neu, indem du zu Ansicht > Befehlspalette... gehst und Entwickler: Fenster neu laden auswählst.

Das in Ollama konfigurierte Qiskit Code Assistant-Modell sollte in der Statusleiste erscheinen und ist dann einsatzbereit.

Mit der Qiskit Code Assistant JupyterLab-Erweiterung verbinden

Mit der Qiskit Code Assistant JupyterLab-Erweiterung kannst du mit dem Modell interagieren und Code-Vervollständigungen direkt in deinem Jupyter Notebook erhalten. Nutzer, die hauptsächlich mit Jupyter Notebooks arbeiten, können diese Erweiterung nutzen, um ihr Erlebnis beim Schreiben von Qiskit-Code weiter zu verbessern.

1. Installiere die Qiskit Code Assistant JupyterLab-Erweiterung.
2. Gehe in JupyterLab zum Einstellungs-Editor und setze Qiskit Code Assistant Service API auf die URL deiner lokalen Ollama-Bereitstellung (zum Beispiel http://localhost:11434).

Das in Ollama konfigurierte Qiskit Code Assistant-Modell sollte in der Statusleiste erscheinen und ist dann einsatzbereit.