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 - Lista os modelos no seu computador
ollama rm Qwen2.5-Coder-14B-Qiskit - Exclui o modelo
ollama show Qwen2.5-Coder-14B-Qiskit - Mostra informações do modelo
ollama stop Qwen2.5-Coder-14B-Qiskit - Para um modelo que está sendo executado no momento
ollama ps - Lista 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 workflows e aplicações Python.

Instale o llama-cpp-python
Interaja com o modelo de 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 via llama.cpp

Use 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. Ele fornece controle de baixo nível sobre a execução do modelo e normalmente é executado a partir da linha de comando, apontando para um arquivo de modelo GGUF local.

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

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

Uma vez instalado, você pode usar o llama.cpp para interagir com modelos GGUF no modo de conversação da seguinte forma:

# Use a local model file \{#use-a-local-model-file}
llama-cli -m my_model.gguf -cnv

# Or download and run a model directly from Hugging Face \{#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 a flag -p/--prompt. No modo de conversação (-cnv), esse prompt inicial atua como a mensagem do sistema. Caso contrário, você pode simplesmente adicionar qualquer instrução desejada no início do texto do seu prompt. Você também pode ajustar 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 de sistema fornecido em nossos repositórios GGUF do HF: 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 o Continue (VS Code)

Continue (VS Code)

1. Instale a extensão

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

2. Abra 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 o ~/.continue/config.yaml (ou config.json em versões mais antigas).

3. Configure 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 torna o modelo Qiskit disponível no painel de chat (conversas na barra lateral, perguntas e respostas em linha) e para comandos de edição em linha.

4. Test it

Chat: Abra o painel do Continue na barra lateral e faça uma pergunta (por exemplo, "Como eu crio um circuito parametrizado no Qiskit?")
Edição em linha: 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 cobrem o Jupyter AI v2.x.

1. Instale o Jupyter AI e o provedor Ollama

pip install "jupyter-ai<3" langchain-ollama

A fixaçã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. Configure 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 o provedor.
Digite mistral-small-3.2-24b-qiskit como o 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. Use 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 for executado em um endereço ou porta diferente:

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

Conectar manualmente o OpenCode (Terminal)

OpenCode (Terminal)

1. Instale o OpenCode

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

2. Configure 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. Selecione o modelo

Inicie o OpenCode no diretório do seu projeto:

opencode

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

4. Test it

Faça uma pergunta diretamente no chat, por exemplo: "Defina um circuito de Bell e execute-o usando 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)

Modelos no formato GGUF são otimizados para uso local e requerem 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 Qiskit Code Assistant de código aberto estão disponíveis em safetensors ou formato de arquivo GGUF e podem ser baixados do Hugging Face conforme explicado abaixo.

Versões do Qiskit usadas para o treinamento

Modelo						Métricas de Benchmark					Data de lançamento	Versão do Qiskit usada no treinamento
	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 benchmark foram avaliados usando seu respectivo prompt de sistema, definido em seu modelo do Hugging Face.

Modelos descontinuados

Esses 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, os benchmarks Qiskit HumanEval ou 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​

Use a biblioteca llama.cpp​

Parâmetros avançados​

Continue (VS Code)​

1. Instale a extensão​

2. Abra a configuração​

3. Configure o modelo​

4. Test it​

Jupyter AI (JupyterLab)​

1. Instale o Jupyter AI e o provedor Ollama​

2. Configure o modelo de chat​

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

4. Host Ollama personalizado (opcional)​

OpenCode (Terminal)​

1. Instale o OpenCode​

2. Configure o modelo Qiskit​

3. Selecione o modelo​

4. Test it​

Modelos disponíveis​

Modelos atuais​

Modelos GGUF (recomendados para ambientes pessoais/laptops)​

Versões do Qiskit usadas para o 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

Use a biblioteca `llama.cpp`

Parâmetros avançados

Continue (VS Code)

1. Instale a extensão

2. Abra a configuração

3. Configure o modelo

4. Test it

Jupyter AI (JupyterLab)

1. Instale o Jupyter AI e o provedor Ollama

2. Configure o modelo de chat

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

4. Host Ollama personalizado (opcional)

OpenCode (Terminal)

1. Instale o OpenCode

2. Configure o modelo Qiskit

3. Selecione o modelo

4. Test it

Modelos disponíveis

Modelos atuais

Modelos GGUF (recomendados para ambientes pessoais/laptops)

Versões do Qiskit usadas para o treinamento

Modelos descontinuados

Mais informações e citações