Pular para o conteúdo principal

Sampler com a API REST

Os passos neste tópico descrevem como executar e configurar cargas de trabalho com a API REST, e demonstram como invocá-las em qualquer programa de sua escolha.

nota

Esta documentação utiliza o módulo requests do Python para demonstrar a API REST do Qiskit Runtime. No entanto, este fluxo de trabalho pode ser executado usando qualquer linguagem ou framework que suporte trabalhar com APIs REST. Consulte a documentação de referência da API para detalhes.

1. Inicializar a conta​

Como o Sampler do Qiskit Runtime é um serviço gerenciado, primeiro você precisa inicializar sua conta. Você pode então selecionar o dispositivo que deseja usar para executar seus cálculos.

Encontre detalhes sobre como inicializar sua conta, ver os Backends disponíveis e trabalhar com tokens em Configurar para usar o IBM Quantum Platform com API REST.

2. Criar um circuito QASM​

Você precisa de pelo menos um circuito como entrada para a primitiva Sampler.

Defina um circuito quântico QASM:

qasm_string='''
OPENQASM 3;
include "stdgates.inc";
qreg q[2];
creg c[2];
x q[0];
cx q[0], q[1];
c[0] = measure q[0];
c[1] = measure q[1];
'''

Os trechos de código abaixo assumem que a qasm_string foi transpilada para uma nova string resulting_qasm.

3. Executar o circuito quântico usando a API Sampler V2​

nota

Os jobs abaixo usam as primitivas V2 do Qiskit Runtime. O SamplerV2 recebe um ou mais blocos unificados primitivos (PUBs) como entrada. Cada PUB é uma tupla que contém um circuito e os dados transmitidos para esse circuito, que podem ser múltiplos parâmetros, e retorna um resultado por PUB.

import requests

url = 'https://quantum.cloud.ibm.com/api/v1/jobs'
auth_id = "Bearer <YOUR_BEARER_TOKEN>"
crn = "<SERVICE-CRN>"
backend = "<BACKEND_NAME>"

headers = {
    'Content-Type': 'application/json',
    'Authorization':auth_id,
    'Service-CRN': crn
    }
job_input = {
    'program_id': 'sampler',
    "backend": backend,
    "params": {
        # primitive unified blocs (PUBs) containing one circuit each:
        "pubs": [[resulting_qasm],[resulting_qasm,None,500]] 
}}

response = requests.post(url, headers=headers, json=job_input)

if response.status_code == 200:
    job_id = response.json().get('id')
    print("Job created:",response.text)
else:
    print(f"Error: {response.status_code}")

4. Verificar o status do job e obter resultados​

Em seguida, passe o job_id para a API:

response_status_singlejob= requests.get(url+'/'+job_id, headers=headers)
response_status_singlejob.json().get('state')

Saída

>>> Job ID: 58223448-5100-4dec-a47a-942fb30edced
>>> Job Status: JobStatus.RUNNING

Obter resultados do job:

response_result= requests.get(url+'/'+job_id+'/results', headers=headers)

res_dict=response_result.json()

# Get results for the first PUB
counts=res_dict['results'][0]['data']['c']['samples']

print(counts[:20])

Saída

['0x3', '0x0', '0x2', '0x1', '0x0', '0x3', '0x0', '0x3', '0x1', '0x2', '0x2', '0x0', '0x2', '0x0', '0x3', '0x3', '0x2', '0x0', '0x1', '0x0']

5. Trabalhar com as opções do Qiskit Runtime​

As técnicas de mitigação de erros permitem que os usuários mitiguem erros de circuito modelando o ruído do dispositivo no momento da execução. Isso normalmente resulta em sobrecarga de pré-processamento quântico relacionada ao treinamento do modelo, e sobrecarga de pós-processamento clássico para mitigar erros nos resultados brutos usando o modelo gerado.

As técnicas de mitigação de erros integradas às primitivas são opções avançadas de resiliência. Para especificar essas opções, use a opção resilience_level ao enviar seu job. O Sampler V2 não suporta a especificação de níveis de resiliência. No entanto, você pode ativar ou desativar métodos individuais de mitigação/supressão de erros.

Os exemplos a seguir demonstram as opções padrão para desacoplamento dinâmico e twirling. Encontre mais opções e mais detalhes no tópico Técnicas de mitigação e supressão de erros.

Desacoplamento dinâmico​

import requests

url = 'https://quantum.cloud.ibm.com/api/v1/jobs'
auth_id = "Bearer <YOUR_BEARER_TOKEN>"
crn = "<SERVICE-CRN>"
backend = "<BACKEND_NAME>"

headers = {
    'Content-Type': 'application/json',
    'Authorization':auth_id,
    'Service-CRN': crn
    }
job_input = {
    'program_id': 'sampler',
    "backend": backend,
    "params": {
        # primitive unified blocs (PUBs) containing one circuit each:
        "pubs": [[resulting_qasm]], 
        "options": {
            "dynamical_decoupling": {
                "enable": True,
                "sequence_type": 'XpXm',
                "extra_slack_distribution": 'middle',
                "scheduling_method": 'alap',
            },
        },
    }
}

response = requests.post(url, headers=headers, json=job_input)

if response.status_code == 200:
    job_id = response.json().get('id')
    print("Job created:",response.text)
else:
    print(f"Error: {response.status_code}")

Twirling​

import requests

url = 'https://quantum.cloud.ibm.com/api/v1/jobs'
auth_id = "Bearer <YOUR_BEARER_TOKEN>"
crn = "<SERVICE-CRN>"
backend = "<BACKEND_NAME>"

headers = {
    'Content-Type': 'application/json',
    'Authorization':auth_id,
    'Service-CRN': crn
    }
job_input = {
    'program_id': 'sampler',
    "backend": backend,
    "params": {
        # primitive unified blocs (PUBs) containing one circuit each:
        "pubs": [[resulting_qasm]], 
        "options": {
            "twirling": {
                "enable_gates": True,
                "enable_measure": True,
                "num_randomizations": "auto",
                "shots_per_randomization": "auto",
                "strategy": "active-accum",
                },
        },
    }
}

response = requests.post(url, headers=headers, json=job_input)

if response.status_code == 200:
    job_id = response.json().get('id')
    print("Job created:",response.text)
else:
    print(f"Error: {response.status_code}")

Circuits parametrizados​

1. Inicializar a conta​

Como o Qiskit Runtime é um serviço gerenciado, primeiro você precisa inicializar sua conta. Você pode então selecionar o dispositivo que deseja usar para executar seus cálculos.

Encontre detalhes sobre como inicializar sua conta, ver os Backends disponíveis e invalidar tokens neste tópico.

2. Definir parâmetros​

import requests
import qiskit_ibm_runtime
from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit.transpiler import generate_preset_pass_manager
from qiskit.qasm3 import dumps
from qiskit import QuantumCircuit
from qiskit.circuit import Parameter
from qiskit import transpile

service = QiskitRuntimeService(channel='ibm_quantum')
backend = service.backend("<SPECIFY BACKEND>")

pm = generate_preset_pass_manager(backend=backend, optimization_level=1)

theta = Parameter('theta')
phi = Parameter('phi')
# In case we want to pass a dictionary:
parameter_values = {'theta': 1.57, 'phi': 3.14}

3. Criar um circuito quântico e adicionar gates parametrizados​

qc = QuantumCircuit(2)

# Add parameterized gates
qc.rx(theta, 0)
qc.ry(phi, 1)
qc.cx(0, 1)
qc.measure_all()

# Draw the original circuit
qc.draw('mpl')

# Get an ISA circuit
isa_circuit = pm.run(qc)

4. Gerar código QASM 3​

qasm_str = dumps(isa_circuit)
print("Generated QASM 3 code:")
print(qasm_str)

5. Executar o circuito quântico usando a API Sampler V2​

import requests

url = 'https://quantum.cloud.ibm.com/api/v1/jobs'
auth_id = "Bearer <YOUR_BEARER_TOKEN>"
crn = "<SERVICE-CRN>"
backend = "<BACKEND_NAME>"

headers = {
    'Content-Type': 'application/json',
    'Authorization':auth_id,
    'Service-CRN': crn
    }

job_input = {
    'program_id': 'sampler',
    "backend": backend,
    "params": {
        # Choose one option: direct parameter transfer or through a dictionary
        # # primitive unified blocs (PUBs) containing one circuit each:
        #"pubs": [[qasm_str,[1,2],500]], 

        # primitive unified blocs (PUBs) containing one circuit each:
        "pubs": [[qasm_str,parameter_values,500]], 
}}

response = requests.post(url, headers=headers, json=job_input)

if response.status_code == 200:
    job_id = response.json().get('id')
    print(f"Job created: {response.text}")
else:
    print(f"Error: {response.status_code}")
print(response.text)

6. Verificar o status do job e obter resultados​

Em seguida, passe o job_id para a API:

response_status_singlejob = requests.get(f"{url}/{job_id}", headers=headers)
response_status_singlejob.json().get('state')

Saída

{'status': 'Completed'}

Obter resultados do job:

response_result = requests.get(f"{url}/{job_id}/results", headers=headers)

res_dict=response_result.json()

# Get results for the first PUB
counts=res_dict['results'][0]['data']['c']['samples']

print(counts[:20])

Saída

['0x1', '0x2', '0x1', '0x2', '0x1', '0x2', '0x0', '0x2', '0x1', '0x1', '0x2', '0x2', '0x1', '0x1', '0x1', '0x1', '0x1', '0x1', '0x1', '0x1']

Próximos passos​

Recomendações
  • Há várias maneiras de executar cargas de trabalho, dependendo das suas necessidades: modo job, modo Session e modo em lote. Aprenda como trabalhar com o modo Session e o modo em lote no tópico de modos de execução. Note que usuários do Plano Aberto não podem enviar jobs de Session.
  • Aprenda como inicializar sua conta com a API REST.
  • Pratique com primitivas trabalhando na lição de função de custo no IBM Quantum Learning.
  • Aprenda como transpilar localmente na seção Transpilar.
Fonte: IBM Quantum docs — atualizado em 10 de jun. de 2026
Versão em inglês no doQumentation — atualizada em 10 de jun. de 2026
Esta tradução é baseada na versão em inglês de 27 de abr. de 2026
Problema com o site ou a tradução?Problema de conteúdo? Editar no IBM Quantum docs