Qiskit Code Assistant

O Qiskit Code Assistant tem como objetivo tornar a computação quântica mais acessível a novos usuários do Qiskit e melhorar a experiência de programação para os usuários atuais. Trata-se de um assistente de código com IA generativa baseado no watsonx. Ele é treinado com milhões de tokens de texto do SDK do Qiskit, anos de exemplos de código Qiskit e funcionalidades do IBM Quantum®. O Qiskit Code Assistant pode ajudar no seu fluxo de desenvolvimento quântico oferecendo sugestões geradas por LLM com base nos modelos IBM Granite, que incorporam os recursos e funcionalidades mais recentes da IBM®.

Notas

• Este é um recurso experimental disponível para usuários do IBM Quantum Premium Plan registrados na nova IBM Quantum Platform.
• O Qiskit Code Assistant está em versão de pré-lançamento e está sujeito a alterações.
• Se você tiver feedback ou quiser entrar em contato com a equipe de desenvolvimento, use o canal do Qiskit Slack Workspace ou os repositórios públicos relacionados no GitHub.

Funcionalidades

As seguintes funcionalidades estão incluídas nas extensões para o Visual Studio Code (VS Code) e editores compatíveis, bem como para o JupyterLab:

• Acelera a geração de código Qiskit utilizando IA generativa baseada em modelos especializados na geração de código Qiskit.
• Permite prompts abstratos e específicos para gerar recomendações.
• Apresenta sugestões que você pode revisar, aceitar ou rejeitar.
• Suporta arquivos de código Python e notebooks Jupyter.
• Inclui mecanismos de proteção para evitar responder a perguntas que representem risco potencial para os usuários, como discursos de ódio.

Para instruções sobre como integrar o Qiskit Code Assistant diretamente ao seu ambiente de desenvolvimento, siga as instruções no tópico correspondente:

• JupyterLab
• VS Code

O Large Language Model (LLM) por trás do Qiskit Code Assistant

Para fornecer sugestões de código, o Qiskit Code Assistant utiliza um Large Language Model (LLM). Neste caso, o Qiskit Code Assistant atualmente depende do modelo mistral-small-3.2-24b-qiskit, construído com base no modelo Mistral-Small-3.2-24B-Qiskit. O modelo mistral-small-3.2-24b-qiskit aprimora as capacidades de geração de código para Qiskit do modelo Mistral-Small-3.2-24B-Instruct-2506 por meio de pré-treinamento estendido e ajuste fino em dados Qiskit de alta qualidade, bem como em commits Python e conversas. Para mais informações sobre a família de modelos Mistral AI, consulte a documentação do Mistral AI. Para mais detalhes sobre os modelos .*-qiskit, consulte Qiskit Code Assistant: Training LLMs for generating Quantum Computing Code.

Nossos LLMs especializados para Qiskit também estão disponíveis como modelos de código aberto. Confira todos os modelos disponíveis em https://huggingface.co/Qiskit.

Os benchmarks Qiskit HumanEval e Qiskit HumanEval Hard

Para testar o mistral-small-3.2-24b-qiskit e outros modelos, colaboramos com Qiskit Advocates e especialistas para criar os benchmarks baseados em execução chamados Qiskit HumanEval (QHE) e Qiskit HumanEval Hard (QHE Hard), e os executamos nos modelos. Esses benchmarks são semelhantes ao HumanEval, incluindo vários problemas de código desafiadores para resolver, todos baseados nas bibliotecas oficiais do Qiskit.

Os benchmarks são compostos por aproximadamente 150 testes, cada um formado por uma definição de função, seguida de uma docstring que detalha a tarefa que o modelo deve resolver. Cada exemplo também inclui uma solução canônica de referência, bem como testes unitários, para avaliar a correção das soluções geradas. Existem três níveis de dificuldade para os testes: básico, intermediário e difícil. O benchmark Qiskit HumanEval Hard é uma variação do Qiskit HumanEval, mas remove informações relacionadas às importações de código, de modo que o LLM precisa descobrir os imports corretos de métodos ou classes. Essa mudança torna o conjunto de dados muito mais desafiador para os LLMs, de acordo com nossos testes e resultados iniciais.

Os conjuntos de dados para o Qiskit HumanEval e o Qiskit HumanEval Hard estão disponíveis nestes endereços: Qiskit HumanEval e Qiskit HumanEval. Você pode contribuir para o desenvolvimento desses benchmarks no repositório GitHub.

Mais informações e citações

Para saber mais sobre o Qiskit Code Assistant, o Qiskit HumanEval ou os benchmarks Qiskit HumanEval Hard, e citá-los em suas publicações científicas, consulte as citações recomendadas abaixo:

@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},
}

Use o Qiskit Code Assistant no modo local

Saiba como instalar, configurar e usar qualquer um dos modelos do Qiskit Code Assistant na sua máquina local.

Notas

• O Qiskit Code Assistant está em versão de pré-lançamento e está sujeito a alterações.
• Se você tiver feedback ou quiser entrar em contato com a equipe de desenvolvimento, use o canal do Qiskit Slack Workspace ou os repositórios públicos relacionados no GitHub.

Início rápido (recomendado)

A maneira mais fácil de começar a usar o Qiskit Code Assistant no modo local é utilizar os scripts de configuração automatizada para as extensões do VS Code ou do JupyterLab. Esses scripts instalam automaticamente o Ollama para executar os LLMs, baixam o modelo recomendado e configuram a extensão para você.

Configuração da extensão para VS Code

Execute o seguinte comando no seu terminal:

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

Este script realiza as seguintes etapas:

• Instalar o Ollama (se ainda não estiver instalado)
• Baixar e configurar o modelo recomendado do Qiskit Code Assistant
• Configurar a extensão do VS Code para funcionar com sua implantação local

Configuração da extensão para JupyterLab

Execute o seguinte comando no seu terminal:

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

Este script irá:

• Instalar o Ollama (se ainda não estiver instalado)
• Baixar e configurar o modelo recomendado do Qiskit Code Assistant
• Configurar a extensão do JupyterLab para funcionar com sua implantação local

Modelos disponíveis

Modelos atuais

Estes são os modelos mais recentes recomendados para uso com o Qiskit Code Assistant:

1. Qiskit/mistral-small-3.2-24b-qiskit - Lançado em outubro de 2025
2. qiskit/qwen2.5-coder-14b-qiskit - Lançado em junho de 2025
3. qiskit/granite-3.3-8b-qiskit - Lançado em junho de 2025
4. qiskit/granite-3.2-8b-qiskit - Lançado em junho de 2025

Modelos GGUF (recomendados para ambientes pessoais/laptops)

Os modelos no formato GGUF são otimizados para uso local e exigem menos recursos computacionais:

1. mistral-small-3.2-24b-qiskit-GGUF – Lançado em outubro de 2025
   Treinado com dados do Qiskit até a versão 2.1

2. qiskit/qwen2.5-coder-14b-qiskit-GGUF – Lançado em junho de 2025
   Treinado com dados do Qiskit até a versão 2.0

3. qiskit/granite-3.3-8b-qiskit-GGUF – Lançado em junho de 2025
   Treinado com dados do Qiskit até a versão 2.0

4. qiskit/granite-3.2-8b-qiskit-GGUF – Lançado em junho de 2025
   Treinado com dados do Qiskit até a versão 2.0

Os modelos de código aberto do Qiskit Code Assistant estão disponíveis em safetensors ou GGUF file format e podem ser baixados do Hugging Face conforme explicado abaixo.

Versões do Qiskit usadas no treinamento

Model						Benchmark Metrics					Release date	Trained on 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	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

Note: All models listed in the benchmark table were evaluated using their respective system prompt, defined in their Hugging Face model.

Modelos descontinuados

Estes modelos não são mais mantidos ativamente, mas continuam disponíveis:

1. qiskit/granite-8b-qiskit-rc-0.10 - Lançado em fevereiro de 2025 (descontinuado)
2. qiskit/granite-8b-qiskit - Lançado em novembro de 2024 (descontinuado)

Configuração avançada

Se você preferir configurar manualmente sua instalação local ou precisar de mais controle sobre o processo de instalação, expanda as seções abaixo.

Baixar do site do Hugging Face

Siga estas etapas para baixar qualquer modelo relacionado ao Qiskit Code Assistant do site do Hugging Face:

1. Navegue até a página do modelo Qiskit desejado no Hugging Face.
2. Acesse a aba Files and Versions e baixe os arquivos do modelo em formato safetensors ou GGUF.

Baixar usando o Hugging Face CLI

Para baixar qualquer um dos modelos disponíveis do Qiskit Code Assistant usando o Hugging Face CLI, siga estas etapas:

1. Instale o Hugging Face CLI

2. Faça login na sua conta do Hugging Face

   huggingface-cli login

3. Baixe o modelo de sua preferência da lista anterior

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

Implantar manualmente os modelos do Qiskit Code Assistant localmente via Ollama

Existem várias maneiras de implantar e interagir com o modelo do Qiskit Code Assistant baixado. Este guia demonstra o uso do Ollama da seguinte forma: com a aplicação Ollama usando a integração do Hugging Face Hub ou o modelo local, ou com o pacote llama-cpp-python.

Usando a aplicação Ollama

A aplicação Ollama oferece uma solução simples para executar os LLMs localmente. É fácil de usar, com uma CLI que torna todo o processo de configuração, gerenciamento de modelos e interação bastante direto. É ideal para experimentação rápida e para usuários que desejam lidar com menos detalhes técnicos.

Instalar o Ollama

1. Baixe a aplicação Ollama

2. Instale o arquivo baixado

3. Inicie a aplicação Ollama instalada

   informação

   A aplicação está funcionando corretamente quando o ícone do Ollama aparece na barra de menus da área de trabalho. Você também pode verificar se o serviço está em execução acessando http://localhost:11434/.

4. Experimente o Ollama no seu terminal e comece a executar modelos. Por exemplo:

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

Configurar o Ollama usando a integração do Hugging Face Hub

A integração Ollama/Hugging Face Hub fornece uma maneira de interagir com modelos hospedados no Hugging Face Hub sem precisar criar um novo modelfile nem baixar manualmente os arquivos GGUF ou safetensors. Os arquivos padrão template e params já estão incluídos para o modelo no Hugging Face Hub.

1. Certifique-se de que a aplicação Ollama está em execução.

2. Acesse a página do modelo desejado e copie a URL. Por exemplo, https://huggingface.co/Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF.

3. No seu terminal, execute o comando:

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

Você pode usar o modelo hf.co/Qiskit/Qwen2.5-Coder-14B-Qiskit ou qualquer um dos outros modelos GGUF oficiais recomendados atualmente: hf.co/Qiskit/mistral-small-3.2-24b-qiskit-GGUF ou hf.co/Qiskit/granite-3.3-8b-qiskit-GGUF.

Configurar o Ollama com um modelo GGUF do Qiskit Code Assistant baixado manualmente

Se você baixou manualmente um modelo GGUF, como https://huggingface.co/Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF, e deseja experimentar diferentes templates e parâmetros, você pode seguir estas etapas para carregá-lo na sua aplicação Ollama local.

1. Crie um Modelfile inserindo o seguinte conteúdo e certifique-se de atualizar <PATH-TO-GGUF-FILE> para o caminho real do modelo baixado.

   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:

• 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

Para garantir o funcionamento correto dos nossos modelos Qiskit, recomendamos usar o prompt de sistema fornecido nos nossos repositórios HF GGUF: prompt de sistema para 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.

Conectar manualmente extensões à implantação local

Use a extensão para VS Code e a extensão para JupyterLab do Qiskit Code Assistant para interagir com o modelo do Qiskit Code Assistant implantado localmente. Depois de ter a aplicação Ollama configurada com o modelo, você pode configurar as extensões para se conectar ao serviço local.

Conectar com a extensão do Qiskit Code Assistant para VS Code

Com a extensão do Qiskit Code Assistant para VS Code, você pode interagir com o modelo e realizar completação de código enquanto escreve seu código. Isso pode ser útil para usuários que buscam assistência na escrita de código Qiskit para suas aplicações Python.

1. Instale a extensão do Qiskit Code Assistant para VS Code.
2. No VS Code, acesse as Configurações do Usuário e defina a URL do Qiskit Code Assistant como a URL da sua implantação local do Ollama (por exemplo, http://localhost:11434).
3. Recarregue o VS Code acessando Exibir > Paleta de Comandos... e selecionando Developer: Reload Window.

O modelo do Qiskit Code Assistant configurado no Ollama deverá aparecer na barra de status e estará pronto para uso.

Conectar com a extensão do Qiskit Code Assistant para JupyterLab

Com a extensão do Qiskit Code Assistant para JupyterLab, você pode interagir com o modelo e realizar completação de código diretamente no seu Jupyter Notebook. Usuários que trabalham predominantemente com Jupyter Notebooks podem aproveitar esta extensão para aprimorar ainda mais sua experiência ao escrever código Qiskit.

1. Instale a extensão do Qiskit Code Assistant para JupyterLab.
2. No JupyterLab, acesse o Editor de Configurações e defina a API de Serviço do Qiskit Code Assistant como a URL da sua implantação local do Ollama (por exemplo, http://localhost:11434).

O modelo do Qiskit Code Assistant configurado no Ollama deverá aparecer na barra de status e estará pronto para uso.

Próximos passos

Recomendações

• Instale e use as extensões oficiais para o JupyterLab ou o VS Code.
• Veja exemplos de uso do Qiskit Code Assistant para circuits, configuração de supressão de erros e transpilação com pass managers.