Qiskit Code Assistant

Os LLMs do Qiskit Code Assistant têm 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. 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 e outros modelos de código aberto, que incorporam os recursos e funcionalidades mais recentes da IBM®.

Notas

Quer ir direto para as instruções de instalação? Acesse a seção Instalar o Qiskit Code Assistant.
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.

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.

Instalar o Qiskit Code Assistant

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

Baixar do site do Hugging Face

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

Navegue até a página do modelo Qiskit desejado no Hugging Face.
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:

Instale o Hugging Face CLI
Faça login na sua conta do Hugging Face
```
huggingface-cli login
```

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

Baixe a aplicação Ollama
Instale o arquivo baixado
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/.
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.

Certifique-se de que a aplicação Ollama está em execução.
Acesse a página do modelo desejado e copie a URL. Por exemplo, https://huggingface.co/Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF.

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.

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

Execute o seguinte comando para criar uma instância de modelo personalizada com base no Modelfile.
```
ollama create Qwen2.5-Coder-14B-Qiskit -f ./path-to-model-file
```
nota
Este processo pode levar algum tempo para o Ollama ler o arquivo do modelo, inicializar a instância do modelo e configurá-la de acordo com as especificações fornecidas.

Executar o modelo do Qiskit Code Assistant baixado manualmente no Ollama

Após configurar o modelo Qwen2.5-Coder-14B-Qiskit no Ollama, execute o seguinte comando para iniciar o modelo e interagir com ele no terminal (em modo de chat).

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

Alguns comandos úteis:

ollama list - Listar os modelos no seu computador
ollama rm Qwen2.5-Coder-14B-Qiskit - Excluir o modelo
ollama show Qwen2.5-Coder-14B-Qiskit - Exibir informações do modelo
ollama stop Qwen2.5-Coder-14B-Qiskit - Parar um modelo que está em execução
ollama ps - Listar quais modelos estão carregados no momento

Implantar manualmente os modelos do Qiskit Code Assistant localmente através do pacote llama-cpp-python

Uma alternativa à aplicação Ollama é o pacote llama-cpp-python, que é um binding Python para o llama.cpp. Ele oferece mais controle e flexibilidade para executar o modelo GGUF localmente, e é ideal para usuários que desejam integrar o modelo local em seus fluxos de trabalho e aplicações Python.

Instale o llama-cpp-python
Interaja com o modelo dentro da sua aplicação usando llama_cpp. Por exemplo:

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

Você também pode adicionar parâmetros de geração de texto ao modelo para personalizar a inferência:

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

Implantar manualmente os modelos do Qiskit Code Assistant localmente através do llama.cpp

Usar a biblioteca `llama.cpp`

Outra alternativa é usar o llama.cpp, uma biblioteca de código aberto para realizar inferência de LLM em uma CPU com configuração mínima. Ela fornece controle de baixo nível sobre a execução do modelo e normalmente é executada pela linha de comando, apontando para um arquivo de modelo GGUF local.

Existem várias maneiras de instalar o llama.cpp na sua máquina:

Instalar o llama.cpp usando brew, nix ou winget
Executar com Docker: Consulte a documentação Docker da equipe do llama.cpp
Baixar binários pré-compilados na página de releases
Compilar a partir do código-fonte clonando este repositório

Após instalado, você pode usar o llama.cpp para interagir com modelos GGUF em modo de conversação da seguinte forma:

# 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

Você também pode iniciar um servidor de API compatível com OpenAI para o modelo da seguinte forma:

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

Parâmetros avançados

Com o programa llama-cli, você pode controlar a geração do modelo usando opções de linha de comando. Por exemplo, você pode fornecer um prompt inicial de “sistema” usando o flag -p/--prompt. No modo de conversação (-cnv), este prompt inicial atua como a mensagem do sistema. Caso contrário, você pode simplesmente adicionar qualquer instrução desejada ao início do seu texto de prompt. Você também pode ajustar os parâmetros de amostragem - por exemplo: temperatura (--temp), top-k (--top-k), top-p (--top-p), penalidade de repetição (--repeat-penalty) e a semente a ser usada (--seed). A seguir está um exemplo de invocação usando essas opções:

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 adequado dos nossos modelos Qiskit, recomendamos usar o prompt do sistema fornecido nos nossos repositórios HF GGUF: prompt do 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 o Continue (VS Code)

Continue (VS Code)

1. Instalar a extensão

Abra o VS Code, vá para Extensões (Cmd+Shift+X), pesquise Continue e instale.

2. Abrir a configuração

Clique no ícone do Continue na barra lateral, depois clique no ícone de engrenagem, ou abra a paleta de comandos (Cmd+Shift+P) e execute Continue: Open Config File.

Isso abre ~/.continue/config.yaml (ou config.json em versões mais antigas).

3. Configurar o modelo

Adicione o seguinte ao config.yaml:

models:
  - name: Qiskit Code Assistant
    provider: ollama
    model: mistral-small-3.2-24b-qiskit
    apiBase: http://localhost:11434

Isso disponibiliza o modelo Qiskit no painel de chat (conversas na barra lateral, perguntas e respostas inline) e para comandos de edição inline.

4. Testar

Chat: Abra o painel do Continue na barra lateral e faça uma pergunta (por exemplo, “How do I create a parameterized circuit in Qiskit?”)
Edição inline: Selecione um bloco de código, pressione Cmd+I (Mac) ou Ctrl+I (Linux/Windows)

Conectar manualmente o Jupyter AI (JupyterLab)

Jupyter AI (JupyterLab)

Nota: Estas instruções abrangem o Jupyter AI v2.x.

1. Instalar o Jupyter AI e o provedor Ollama

pip install “jupyter-ai<3” langchain-ollama

O ”jupyter-ai<3” garante que você obtenha a v2.x. O pacote langchain-ollama é necessário para que o Jupyter AI detecte o Ollama como provedor. Sem ele, o Ollama não aparecerá no painel de configurações.

Em seguida, reinicie o JupyterLab.

2. Configurar o modelo de chat

Abra o JupyterLab e clique no ícone de chat na barra lateral esquerda. No painel de configurações:

Em Language model, selecione Ollama como provedor.
Insira mistral-small-3.2-24b-qiskit como nome do modelo.
Nenhuma chave de API é necessária para o Ollama (deixe o campo vazio).
Clique na seta de voltar para começar a conversar.

3. Usar o comando mágico `%%ai`

O comando mágico %%ai permite consultar o modelo diretamente nas células do notebook.

%load_ext jupyter_ai_magics

Em seguida, em uma célula:

%%ai ollama:mistral-small-3.2-24b-qiskit
Write a function that implements Grover's algorithm using Qiskit

4. Host Ollama personalizado (opcional)

Por padrão, o Jupyter AI se conecta a http://127.0.0.1:11434. Se o seu servidor Ollama estiver em um endereço ou porta diferente:

Na interface de chat: Defina o campo “Base API URL” no painel de configurações da IA.

Conectar manualmente o OpenCode (Terminal)

OpenCode (Terminal)

1. Instalar o OpenCode

curl -fsSL https://opencode.ai/install | bash

2. Configurar o modelo Qiskit

Crie um arquivo opencode.json na raiz do seu projeto (ou ~/.config/opencode/opencode.json para uma configuração global):

{
  “$schema”: “https://opencode.ai/config.json”,
  “provider”: {
    “ollama”: {
      “npm”: “@ai-sdk/openai-compatible”,
      “name”: “Ollama (local)”,
      “options”: {
        “baseURL”: “http://localhost:11434/v1”
      },
      “models”: {
        “mistral-small-3.2-24b-qiskit”: {
          “name”: “Qiskit Code Assistant”
        }
      }
    }
  }
}

3. Selecionar o modelo

Inicie o OpenCode no diretório do seu projeto:

opencode

Dentro da TUI, execute o comando /models e selecione Qiskit Code Assistant da lista.

4. Testar

Faça uma pergunta diretamente no chat, por exemplo: “Define a Bell circuit and run it using QiskitRuntimeService”

Modelos disponíveis

Modelos atuais

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

Qiskit/mistral-small-3.2-24b-qiskit - Lançado em outubro de 2025
Qiskit/Qwen2.5-Coder-14B-Qiskit - Lançado em junho de 2025
qiskit/granite-3.3-8b-qiskit - Lançado em junho de 2025
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:

mistral-small-3.2-24b-qiskit-GGUF – Lançado em outubro de 2025
Treinado com dados do Qiskit até a versão 2.1
Qiskit/Qwen2.5-Coder-14B-Qiskit-GGUF – Lançado em junho de 2025
Treinado com dados do Qiskit até a versão 2.0
qiskit/granite-3.3-8b-qiskit-GGUF – Lançado em junho de 2025
Treinado com dados do Qiskit até a versão 2.0
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 nos formatos safetensors ou GGUF file format e podem ser baixados do Hugging Face conforme explicado abaixo.

Versões do Qiskit usadas para treinamento

Modelo						Métricas de Benchmark					Data de lançamento	Treinado na versão do Qiskit
	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	Janeiro de 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	Junho de 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	Junho de 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	Junho de 2025	2.0
granite-8b-qiskit-rc-0.10	15.89	38.41	59.76	—	—	—	—	—	—	—	Fevereiro de 2025	1.3
granite-8b-qiskit	17.88	44.37	53.66	—	—	—	—	—	—	—	Novembro de 2024	1.2

Nota: Todos os modelos listados na tabela de benchmarks foram avaliados usando seus respectivos prompts do sistema, definidos em seu modelo do Hugging Face.

Modelos descontinuados

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

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

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 estas citações recomendadas:

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

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

Os benchmarks Qiskit HumanEval e Qiskit HumanEval Hard​

Instalar o Qiskit Code Assistant​

Usando a aplicação Ollama​

Instalar o Ollama​

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

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

Executar o modelo do Qiskit Code Assistant baixado manualmente no Ollama​

Usar a biblioteca llama.cpp​

Parâmetros avançados​

Continue (VS Code)​

1. Instalar a extensão​

2. Abrir a configuração​

3. Configurar o modelo​

4. Testar​

Jupyter AI (JupyterLab)​

1. Instalar o Jupyter AI e o provedor Ollama​

2. Configurar o modelo de chat​

3. Usar o comando mágico %%ai​

4. Host Ollama personalizado (opcional)​

OpenCode (Terminal)​

1. Instalar o OpenCode​

2. Configurar o modelo Qiskit​

3. Selecionar o modelo​

4. Testar​

Modelos disponíveis​

Modelos atuais​

Modelos GGUF (recomendados para ambientes pessoais/laptops)​

Versões do Qiskit usadas para treinamento​

Modelos descontinuados​

Mais informações e citações​

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

Os benchmarks Qiskit HumanEval e Qiskit HumanEval Hard

Instalar o Qiskit Code Assistant

Usando a aplicação Ollama

Instalar o Ollama

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

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

Executar o modelo do Qiskit Code Assistant baixado manualmente no Ollama

Usar a biblioteca `llama.cpp`

Parâmetros avançados

Continue (VS Code)

1. Instalar a extensão

2. Abrir a configuração

3. Configurar o modelo

4. Testar

Jupyter AI (JupyterLab)

1. Instalar o Jupyter AI e o provedor Ollama

2. Configurar o modelo de chat

3. Usar o comando mágico `%%ai`

4. Host Ollama personalizado (opcional)

OpenCode (Terminal)

1. Instalar o OpenCode

2. Configurar o modelo Qiskit

3. Selecionar o modelo

4. Testar

Modelos disponíveis

Modelos atuais

Modelos GGUF (recomendados para ambientes pessoais/laptops)

Versões do Qiskit usadas para treinamento

Modelos descontinuados

Mais informações e citações