Pular para o conteúdo principal

Usar o Qiskit Code Assistant no modo local

Aprenda 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 status de versão prévia e está sujeito a alterações.
  • Se você tiver feedback ou quiser entrar em contato com a equipe de desenvolvedores, use o canal do Qiskit Slack Workspace ou os repositórios públicos do GitHub relacionados.

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 a extensão 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 do 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:

  • Instala o Ollama (se ainda não estiver instalado)
  • Baixa e configura o modelo Qiskit Code Assistant recomendado
  • Configura a extensão do VS Code para funcionar com a sua implantação local

Configuração da extensão do 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 Qiskit Code Assistant recomendado
  • Configurar a extensão do JupyterLab para funcionar com a 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

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 formato de arquivo GGUF 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çamentoTreinado na versão do Qiskit
 QiskitHumanEval-HardQiskitHumanEvalHumanEvalASDivMathQASciQMBPPIFEvalCrowsPairs (inglês)TruthfulQA (MC1 acc)  
mistral-small-3.2-24b-qiskit32.4547.0277.493.7749.6897.5064.0048.4467.0839.41Janeiro de 20262.2
qwen2.5-coder-14b-qiskit25.1749.0191.464.2153.9097.0077.6049.6465.1837.82Junho de 20252.0
granite-3.3-8b-qiskit14.5727.1562.800.4838.6693.3052.4059.7159.7539.05Junho de 20252.0
granite-3.2-8b-qiskit9.9324.5057.320.0941.4196.3051.8060.7966.7940.51Junho de 20252.0
granite-8b-qiskit-rc-0.1015.8938.4159.76———————Fevereiro de 20251.3
granite-8b-qiskit17.8844.3753.66———————Novembro de 20241.2

Observação: Todos os modelos listados na tabela de benchmark foram avaliados usando seus respectivos prompts de sistema, definidos em seus modelos do Hugging Face.

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 o seu ambiente local ou precisar de mais controle sobre o processo de instalação, expanda as seções abaixo.

Baixar pelo site do Hugging Face

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

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

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

  1. Instale a CLI do Hugging Face

  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

Há várias formas de implantar e interagir com o modelo Qiskit Code Assistant baixado. Este guia demonstra o uso do Ollama da seguinte forma: com o aplicativo Ollama por meio da integração com o Hugging Face Hub ou com um modelo local, ou com o pacote llama-cpp-python.

Usando o aplicativo Ollama​

O aplicativo Ollama oferece uma solução simples para executar 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 querem lidar com menos detalhes técnicos.

Instalar o Ollama​

  1. Baixe o aplicativo Ollama

  2. Instale o arquivo baixado

  3. Inicie o aplicativo Ollama instalado

    informação
    O aplicativo está sendo executado com sucesso 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 com o Hugging Face Hub​

A integração Ollama/Hugging Face Hub oferece uma forma 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 de template e params já estão incluídos para o modelo no Hugging Face Hub.

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

  2. Vá até 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, siga estas etapas para carregá-lo no seu aplicativo Ollama local.

  1. Crie um Modelfile com o seguinte conteúdo e certifique-se de atualizar <PATH-TO-GGUF-FILE> com o caminho real do seu 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:

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 extensões manualmente à implantação local

Use a extensão do VS Code e a extensão do JupyterLab para o Qiskit Code Assistant para enviar prompts ao modelo Qiskit Code Assistant implantado localmente. Depois de ter o aplicativo Ollama configurado com o modelo, você pode configurar as extensões para se conectarem ao serviço local.

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

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

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

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

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

Com a extensão do JupyterLab do Qiskit Code Assistant, 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 JupyterLab do Qiskit Code Assistant.
  2. No JupyterLab, vá para o Settings Editor e defina o campo Qiskit Code Assistant Service API como a URL da sua implantação local do Ollama (por exemplo, http://localhost:11434).

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