Перейти до основного вмісту

Використання Qiskit Code Assistant у локальному режимі

Дізнайся, як встановити, налаштувати та використовувати будь-яку з моделей Qiskit Code Assistant на своїй локальній машині.

Примітки
  • Qiskit Code Assistant перебуває у статусі попереднього випуску і може змінюватися.
  • Якщо ти маєш відгуки або хочеш зв'язатися з командою розробників, скористайся каналом Qiskit Slack Workspace або відповідними публічними репозиторіями GitHub.

Найпростіший спосіб розпочати роботу з Qiskit Code Assistant у локальному режимі — скористатися скриптами автоматичного налаштування для розширення VS Code або JupyterLab. Ці скрипти автоматично встановлять Ollama для запуску LLM, завантажать рекомендовану модель і налаштують розширення за тебе.

Налаштування розширення VS Code​

Виконай таку команду в терміналі:

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

Цей скрипт виконує такі кроки:

  • Встановлює Ollama (якщо ще не встановлено)
  • Завантажує та налаштовує рекомендовану модель Qiskit Code Assistant
  • Налаштовує розширення VS Code для роботи з локальним розгортанням

Налаштування розширення JupyterLab​

Виконай таку команду в терміналі:

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

Цей скрипт виконає таке:

  • Встановить Ollama (якщо ще не встановлено)
  • Завантажить та налаштує рекомендовану модель Qiskit Code Assistant
  • Налаштує розширення JupyterLab для роботи з локальним розгортанням

Доступні моделі​

Поточні моделі​

Це останні рекомендовані моделі для використання з Qiskit Code Assistant:

  1. Qiskit/mistral-small-3.2-24b-qiskit - Випущено у жовтні 2025 року
  2. qiskit/qwen2.5-coder-14b-qiskit - Випущено у червні 2025 року
  3. qiskit/granite-3.3-8b-qiskit - Випущено у червні 2025 року
  4. qiskit/granite-3.2-8b-qiskit - Випущено у червні 2025 року

Моделі у форматі GGUF оптимізовані для локального використання і вимагають менше обчислювальних ресурсів:

  1. mistral-small-3.2-24b-qiskit-GGUF – Випущено у жовтні 2025 року Навчено на даних Qiskit до версії 2.1

  2. qiskit/qwen2.5-coder-14b-qiskit-GGUF – Випущено у червні 2025 року Навчено на даних Qiskit до версії 2.0

  3. qiskit/granite-3.3-8b-qiskit-GGUF – Випущено у червні 2025 року Навчено на даних Qiskit до версії 2.0

  4. qiskit/granite-3.2-8b-qiskit-GGUF – Випущено у червні 2025 року Навчено на даних Qiskit до версії 2.0

Моделі Qiskit Code Assistant з відкритим кодом доступні у форматі safetensors або GGUF і можуть бути завантажені з Hugging Face, як описано нижче.

Версії Qiskit, використані для навчання​

Модель     Метрики бенчмарку    Дата випускуНавчено на версії Qiskit
 QiskitHumanEval-HardQiskitHumanEvalHumanEvalASDivMathQASciQMBPPIFEvalCrowsPairs (English)TruthfulQA (MC1 acc)  
mistral-small-3.2-24b-qiskit32.4547.0277.493.7749.6897.5064.0048.4467.0839.41Січень 20262.2
qwen2.5-coder-14b-qiskit25.1749.0191.464.2153.9097.0077.6049.6465.1837.82Червень 20252.0
granite-3.3-8b-qiskit14.5727.1562.800.4838.6693.3052.4059.7159.7539.05Червень 20252.0
granite-3.2-8b-qiskit9.9324.5057.320.0941.4196.3051.8060.7966.7940.51Червень 20252.0
granite-8b-qiskit-rc-0.1015.8938.4159.76———————Лютий 20251.3
granite-8b-qiskit17.8844.3753.66———————Листопад 20241.2

Примітка: Усі моделі, перелічені в таблиці бенчмарків, були оцінені з використанням відповідного системного промпту, визначеного в їхній моделі на Hugging Face.

Застарілі моделі​

Ці моделі більше не підтримуються активно, але залишаються доступними:

  1. qiskit/granite-8b-qiskit-rc-0.10 - Випущено у лютому 2025 року (застаріло)
  2. qiskit/granite-8b-qiskit - Випущено у листопаді 2024 року (застаріло)

Розширене налаштування​

Якщо ти надаєш перевагу ручному налаштуванню або потребуєш більшого контролю над процесом встановлення, розгорни розділи нижче.

Завантаження з веб-сайту Hugging Face

Дотримуйся цих кроків, щоб завантажити будь-яку модель, пов'язану з Qiskit Code Assistant, з веб-сайту Hugging Face:

  1. Перейди на сторінку потрібної моделі Qiskit на Hugging Face.
  2. Перейди на вкладку Files and Versions і завантаж файли моделі у форматі safetensors або GGUF.
Завантаження за допомогою Hugging Face CLI

Щоб завантажити будь-яку з доступних моделей Qiskit Code Assistant за допомогою Hugging Face CLI, дотримуйся таких кроків:

  1. Встанови Hugging Face CLI

  2. Увійди у свій обліковий запис Hugging Face

    huggingface-cli login

  3. Завантаж бажану модель із попереднього списку

    huggingface-cli download <HF REPO NAME> <MODEL PATH> --local-dir <LOCAL PATH>
Ручне розгортання моделей Qiskit Code Assistant локально через Ollama

Існує кілька способів розгорнути завантажену модель Qiskit Code Assistant і взаємодіяти з нею. У цьому посібнику демонструється використання Ollama наступним чином: або через застосунок Ollama з використанням інтеграції Hugging Face Hub чи локальної моделі, або через пакет llama-cpp-python.

Використання застосунку Ollama​

Застосунок Ollama надає просте рішення для локального запуску LLM. Він простий у використанні, з CLI, що робить весь процес налаштування, управління моделями та взаємодію досить зрозумілими. Ідеально підходить для швидкого експериментування та для користувачів, які хочуть мінімуму технічних деталей.

Встановлення Ollama​

  1. Завантаж застосунок Ollama

  2. Встанови завантажений файл

  3. Запусти встановлений застосунок Ollama

    інформація
    Застосунок працює успішно, коли значок Ollama з'являється в рядку меню робочого стола. Ти також можеш перевірити, чи запущено сервіс, перейшовши за адресою http://localhost:11434/.

  4. Спробуй Ollama у терміналі та запусти моделі. Наприклад:

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

Налаштування Ollama через інтеграцію Hugging Face Hub​

Інтеграція Ollama/Hugging Face Hub надає спосіб взаємодії з моделями, розміщеними на Hugging Face Hub, без необхідності створювати новий modelfile або вручну завантажувати файли GGUF чи safetensors. Стандартні файли template і params вже включені для моделі на Hugging Face Hub.

  1. Переконайся, що застосунок Ollama запущено.

  2. Перейди на сторінку потрібної моделі та скопіюй URL. Наприклад, https://huggingface.co/Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF.

  3. У терміналі виконай команду:

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

Ти можеш використовувати модель hf.co/Qiskit/Qwen2.5-Coder-14B-Qiskit або будь-яку з інших поточних рекомендованих офіційних моделей GGUF: hf.co/Qiskit/mistral-small-3.2-24b-qiskit-GGUF або hf.co/Qiskit/granite-3.3-8b-qiskit-GGUF.

Налаштування Ollama з вручну завантаженою GGUF-моделлю Qiskit Code Assistant​

Якщо ти вручну завантажив(-ла) GGUF-модель, наприклад https://huggingface.co/Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF, і хочеш експериментувати з різними шаблонами та параметрами, дотримуйся цих кроків, щоб завантажити її у свій локальний застосунок Ollama.

  1. Створи Modelfile, ввівши такий вміст, і обов'язково заміни <PATH-TO-GGUF-FILE> на фактичний шлях до завантаженої моделі.

    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
    примітка
    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

Щоб забезпечити правильну роботу наших моделей Qiskit, рекомендуємо використовувати системний промпт, наданий у наших репозиторіях HF GGUF: системний промпт для mistral-small-3.2-24b-qiskit-GGUF, Qwen2.5-Coder-14B-Qiskit-GGUF, granite-3.3-8b-qiskit-GGUF і granite-3.2-8b-qiskit-GGUF.

Ручне підключення розширень до локального розгортання

Використовуй розширення VS Code і JupyterLab для Qiskit Code Assistant, щоб взаємодіяти з локально розгорнутою моделлю Qiskit Code Assistant. Після того як ти налаштував(-ла) застосунок Ollama з моделлю, ти можеш налаштувати розширення для підключення до локального сервісу.

Підключення через розширення Qiskit Code Assistant для VS Code​

За допомогою розширення Qiskit Code Assistant для VS Code ти можеш взаємодіяти з моделлю та виконувати доповнення коду під час написання. Це добре підходить для користувачів, яким потрібна допомога у написанні коду Qiskit для Python-застосунків.

  1. Встанови розширення Qiskit Code Assistant для VS Code.
  2. У VS Code перейди до User Settings і встав URL свого локального розгортання Ollama у поле Qiskit Code Assistant: Url (наприклад, http://localhost:11434).
  3. Перезавантаж VS Code, перейшовши до View > Command Palette... і вибравши Developer: Reload Window.

Модель Qiskit Code Assistant, налаштована в Ollama, має з'явитися в рядку стану та буде готова до використання.

Підключення через розширення Qiskit Code Assistant для JupyterLab​

За допомогою розширення Qiskit Code Assistant для JupyterLab ти можеш взаємодіяти з моделлю та виконувати доповнення коду безпосередньо в Jupyter Notebook. Користувачі, які переважно працюють з Jupyter Notebooks, можуть скористатися цим розширенням для покращення свого досвіду написання коду Qiskit.

  1. Встанови розширення Qiskit Code Assistant для JupyterLab.
  2. У JupyterLab перейди до Settings Editor і встав URL свого локального розгортання Ollama у поле Qiskit Code Assistant Service API (наприклад, http://localhost:11434).

Модель Qiskit Code Assistant, налаштована в Ollama, має з'явитися в рядку стану та буде готова до використання.