Saltar al contenido principal

Usar Qiskit Code Assistant en modo local

Aprende a instalar, configurar y usar cualquiera de los modelos de Qiskit Code Assistant en tu máquina local.

Notas
  • Qiskit Code Assistant está en estado de versión preliminar y puede cambiar.
  • Si tienes comentarios o quieres contactar al equipo de desarrollo, usa el canal del espacio de trabajo de Qiskit en Slack o los repositorios públicos de GitHub relacionados.

La forma más sencilla de comenzar con Qiskit Code Assistant en modo local es usar los scripts de configuración automatizada para la extensión de VS Code o de JupyterLab. Estos scripts instalarán automáticamente Ollama para ejecutar los LLMs, descargarán el modelo recomendado y configurarán la extensión por ti.

Configuración de la extensión de VS Code​

Ejecuta el siguiente comando en tu terminal:

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

Este script realiza los siguientes pasos:

  • Instalar Ollama (si no está instalado aún)
  • Descargar y configurar el modelo de Qiskit Code Assistant recomendado
  • Configurar la extensión de VS Code para que funcione con tu despliegue local

Configuración de la extensión de JupyterLab​

Ejecuta el siguiente comando en tu terminal:

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

Este script:

  • Instalará Ollama (si no está instalado aún)
  • Descargará y configurará el modelo de Qiskit Code Assistant recomendado
  • Configurará la extensión de JupyterLab para que funcione con tu despliegue local

Modelos disponibles​

Modelos actuales​

Estos son los últimos modelos recomendados para usar con Qiskit Code Assistant:

  1. Qiskit/mistral-small-3.2-24b-qiskit - Publicado en octubre de 2025
  2. qiskit/qwen2.5-coder-14b-qiskit - Publicado en junio de 2025
  3. qiskit/granite-3.3-8b-qiskit - Publicado en junio de 2025
  4. qiskit/granite-3.2-8b-qiskit - Publicado en junio de 2025

Los modelos en formato GGUF están optimizados para uso local y requieren menos recursos computacionales:

  1. mistral-small-3.2-24b-qiskit-GGUF – Publicado en octubre de 2025 Entrenado con datos de Qiskit hasta la versión 2.1

  2. qiskit/qwen2.5-coder-14b-qiskit-GGUF – Publicado en junio de 2025 Entrenado con datos de Qiskit hasta la versión 2.0

  3. qiskit/granite-3.3-8b-qiskit-GGUF – Publicado en junio de 2025 Entrenado con datos de Qiskit hasta la versión 2.0

  4. qiskit/granite-3.2-8b-qiskit-GGUF – Publicado en junio de 2025 Entrenado con datos de Qiskit hasta la versión 2.0

Los modelos de código abierto de Qiskit Code Assistant están disponibles en formato safetensors o GGUF y se pueden descargar desde Hugging Face tal como se explica a continuación.

Versiones de Qiskit usadas para el entrenamiento​

Modelo     Métricas de referencia    Fecha de publicaciónEntrenado en la versión de Qiskit
 QiskitHumanEval-HardQiskitHumanEvalHumanEvalASDivMathQASciQMBPPIFEvalCrowsPairs (inglés)TruthfulQA (MC1 acc)  
mistral-small-3.2-24b-qiskit32.4547.0277.493.7749.6897.5064.0048.4467.0839.41enero de 20262.2
qwen2.5-coder-14b-qiskit25.1749.0191.464.2153.9097.0077.6049.6465.1837.82junio de 20252.0
granite-3.3-8b-qiskit14.5727.1562.800.4838.6693.3052.4059.7159.7539.05junio de 20252.0
granite-3.2-8b-qiskit9.9324.5057.320.0941.4196.3051.8060.7966.7940.51junio de 20252.0
granite-8b-qiskit-rc-0.1015.8938.4159.76———————febrero de 20251.3
granite-8b-qiskit17.8844.3753.66———————noviembre de 20241.2

Nota: Todos los modelos listados en la tabla de referencia fueron evaluados usando su system prompt correspondiente, definido en su modelo de Hugging Face.

Modelos obsoletos​

Estos modelos ya no se mantienen activamente pero siguen estando disponibles:

  1. qiskit/granite-8b-qiskit-rc-0.10 - Publicado en febrero de 2025 (obsoleto)
  2. qiskit/granite-8b-qiskit - Publicado en noviembre de 2024 (obsoleto)

Configuración avanzada​

Si prefieres configurar tu entorno local de forma manual o necesitas más control sobre el proceso de instalación, expande las secciones a continuación.

Descargar desde el sitio web de Hugging Face

Sigue estos pasos para descargar cualquier modelo relacionado con Qiskit Code Assistant desde el sitio web de Hugging Face:

  1. Navega a la página del modelo de Qiskit deseado en Hugging Face.
  2. Ve a la pestaña Files and Versions y descarga los archivos del modelo en formato safetensors o GGUF.
Descargar usando la CLI de Hugging Face

Para descargar cualquiera de los modelos de Qiskit Code Assistant disponibles usando la CLI de Hugging Face, sigue estos pasos:

  1. Instala la CLI de Hugging Face

  2. Inicia sesión en tu cuenta de Hugging Face

    huggingface-cli login

  3. Descarga el modelo que prefieras de la lista anterior

    huggingface-cli download <HF REPO NAME> <MODEL PATH> --local-dir <LOCAL PATH>
Desplegar manualmente los modelos de Qiskit Code Assistant en local a través de Ollama

Hay múltiples formas de desplegar e interactuar con el modelo de Qiskit Code Assistant descargado. Esta guía demuestra el uso de Ollama de las siguientes maneras: ya sea con la aplicación Ollama usando la integración con Hugging Face Hub o un modelo local, o con el paquete llama-cpp-python.

Usar la aplicación Ollama​

La aplicación Ollama proporciona una solución sencilla para ejecutar LLMs de forma local. Es fácil de usar, con una CLI que simplifica bastante todo el proceso de configuración, la gestión de modelos y la interacción. Es ideal para experimentar rápidamente y para usuarios que quieren manejar menos detalles técnicos.

Instalar Ollama​

  1. Descarga la aplicación Ollama

  2. Instala el archivo descargado

  3. Inicia la aplicación Ollama instalada

    información
    La aplicación se está ejecutando correctamente cuando el ícono de Ollama aparece en la barra de menú del escritorio. También puedes verificar que el servicio está en funcionamiento accediendo a http://localhost:11434/.

  4. Prueba Ollama en tu terminal y comienza a ejecutar modelos. Por ejemplo:

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

Configurar Ollama usando la integración con Hugging Face Hub​

La integración Ollama/Hugging Face Hub proporciona una forma de interactuar con modelos alojados en Hugging Face Hub sin necesidad de crear un nuevo modelfile ni descargar manualmente los archivos GGUF o safetensors. Los archivos template y params predeterminados ya están incluidos para el modelo en Hugging Face Hub.

  1. Asegúrate de que la aplicación Ollama esté en ejecución.

  2. Ve a la página del modelo deseado y copia la URL. Por ejemplo, https://huggingface.co/Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF.

  3. Desde tu terminal, ejecuta el comando:

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

Puedes usar el modelo hf.co/Qiskit/Qwen2.5-Coder-14B-Qiskit o cualquiera de los otros modelos GGUF oficiales recomendados actualmente: hf.co/Qiskit/mistral-small-3.2-24b-qiskit-GGUF o hf.co/Qiskit/granite-3.3-8b-qiskit-GGUF.

Configurar Ollama con un modelo GGUF de Qiskit Code Assistant descargado manualmente​

Si descargaste manualmente un modelo GGUF como https://huggingface.co/Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF y quieres experimentar con diferentes plantillas y parámetros, puedes seguir estos pasos para cargarlo en tu aplicación local de Ollama.

  1. Crea un Modelfile con el siguiente contenido y asegúrate de actualizar <PATH-TO-GGUF-FILE> con la ruta real de tu modelo descargado.

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

También puede agregar parámetros de generación de texto al modelo para personalizar la inferencia:

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"]
Desplegar manualmente los modelos de Qiskit Code Assistant en local mediante llama.cpp

Usar la biblioteca llama.cpp​

Otra alternativa es usar llama.cpp, una biblioteca de código abierto para realizar inferencia de LLM en una CPU con una configuración mínima. Proporciona control de bajo nivel sobre la ejecución del modelo y se ejecuta típicamente desde la línea de comandos, apuntando a un archivo de modelo GGUF local.

Hay varias formas de instalar llama.cpp en su máquina:

Una vez instalado, puede usar llama.cpp para interactuar con modelos GGUF en modo conversación de la siguiente manera:

# 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

También puede lanzar un servidor de API compatible con OpenAI para el modelo de la siguiente manera:

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

Parámetros avanzados​

Con el programa llama-cli, puede controlar la generación del modelo usando opciones de línea de comandos. Por ejemplo, puede proporcionar un prompt inicial de “sistema” usando la bandera -p/--prompt. En modo conversación (-cnv), este prompt inicial actúa como el mensaje del sistema. De lo contrario, puede simplemente anteponer cualquier instrucción deseada al texto de su prompt. También puede ajustar los parámetros de muestreo — por ejemplo: temperatura (--temp), top-k (--top-k), top-p (--top-p), penalización de repetición (--repeat-penalty) y la semilla a usar (--seed). El siguiente es un ejemplo de invocación usando estas opciones:

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

Para garantizar el funcionamiento correcto de nuestros modelos de Qiskit, recomendamos usar el system prompt proporcionado en nuestros repositorios HF GGUF: system prompt para mistral-small-3.2-24b-qiskit-GGUF, Qwen2.5-Coder-14B-Qiskit-GGUF, granite-3.3-8b-qiskit-GGUF y granite-3.2-8b-qiskit-GGUF.

Conectar manualmente las extensiones al despliegue local

Usa la extensión de VS Code y la extensión de JupyterLab para Qiskit Code Assistant para interactuar con el modelo de Qiskit Code Assistant desplegado localmente. Una vez que tengas la aplicación Ollama configurada con el modelo, puedes configurar las extensiones para que se conecten al servicio local.

Conectar con la extensión de VS Code de Qiskit Code Assistant​

Con la extensión de VS Code de Qiskit Code Assistant, puedes interactuar con el modelo y realizar completado de código mientras escribes tu código. Esto puede resultar muy útil para usuarios que buscan asistencia para escribir código Qiskit en sus aplicaciones Python.

  1. Instala la extensión de VS Code de Qiskit Code Assistant.
  2. En VS Code, ve a Configuración de usuario y establece Qiskit Code Assistant: Url como la URL de tu despliegue local de Ollama (por ejemplo, http://localhost:11434).
  3. Recarga VS Code yendo a Ver > Paleta de comandos... y seleccionando Desarrollador: Recargar ventana.

El modelo de Qiskit Code Assistant configurado en Ollama debería aparecer en la barra de estado y ya estará listo para usar.

Conectar con la extensión de JupyterLab de Qiskit Code Assistant​

Con la extensión de JupyterLab de Qiskit Code Assistant, puedes interactuar con el modelo y realizar completado de código directamente en tu Jupyter Notebook. Los usuarios que trabajan principalmente con Jupyter Notebooks pueden aprovechar esta extensión para mejorar aún más su experiencia escribiendo código Qiskit.

  1. Instala la extensión de JupyterLab de Qiskit Code Assistant.
  2. En JupyterLab, ve al Editor de configuración y establece la API del servicio de Qiskit Code Assistant como la URL de tu despliegue local de Ollama (por ejemplo, http://localhost:11434).

El modelo de Qiskit Code Assistant configurado en Ollama debería aparecer en la barra de estado y ya estará listo para usar.