Pular para o conteúdo principal

Inicialize sua conta do serviço Qiskit Runtime

Antes de usar o Qiskit Runtime, você precisa inicializar (instanciar) sua conta enviando (carregando) as credenciais. Essas credenciais podem ser enviadas manualmente toda vez que você inicializa o serviço Qiskit Runtime, ou você pode salvá-las para reutilização.

Notas

Antes de começar​

Certifique-se de que você concluiu estas etapas:

  1. Verifique se você é membro de uma conta IBM Cloud. Consulte Configurar sua conta IBM Cloud para obter instruções.
  2. Crie (ou tenha acesso a) pelo menos uma instância. Siga estas etapas para verificar:
    1. Faça login no IBM Quantum Platform.
    2. Verifique se a conta e a região corretas estão selecionadas no seletor de conta no cabeçalho.
    3. Se você tiver uma ou mais instâncias exibidas, esta etapa está concluída. Caso contrário, crie uma instância.
  3. Certifique-se de que está trabalhando em um ambiente Python ativo com o Qiskit SDK e o Qiskit Runtime instalados.
  4. Ative o ambiente virtual Python e execute o Python nesse ambiente.

Encontre suas credenciais de acesso​

  1. Encontre sua chave de API (também chamada de token de API). No painel, crie sua chave de API, depois copie-a para um local seguro para que você possa usá-la para autenticação. O token não ficará visível novamente. Observe que você pode usar uma única chave de API para se conectar a qualquer região.
  2. Opcional: Encontre a instância que você deseja usar na página Instâncias. Passe o mouse sobre o CRN, clique no ícone para copiá-lo e salve-o em um local seguro para que você possa usá-lo para identificar a instância.

Conecte o Qiskit à sua instância do serviço Qiskit Runtime​

nota

Estas instruções foram desenvolvidas para qiskit_ibm_runtime v0.42 ou posterior. Alguns recursos não estão disponíveis em versões anteriores do qiskit_ibm_runtime. Nesses casos, você deve sempre fornecer um valor para channel, token e instance, seja explicitamente ou por meio de uma conta salva.

O código básico para conectar o Qiskit à sua instância do serviço Qiskit Runtime é mostrado a seguir. No entanto, existem várias formas diferentes de personalizar as opções do QiskitRuntimeService, dependendo das suas necessidades. Essas opções são descritas nas seções a seguir.

from qiskit_ibm_runtime import QiskitRuntimeService

service = QiskitRuntimeService(channel=<channel>,
            token=<your-API_KEY>, # Use the 44-character API_KEY you created and saved from the IBM Quantum Platform Home dashboard
            instance=<instance_CRN>)
nota

O canal padrão é ibm_quantum_platform. Como este é quase sempre o canal adequado, ele não está incluído nos exemplos.

Caminho de início rápido: Especificar credenciais explicitamente​

A maneira mais rápida de colocar uma instância do QiskitRuntimeService em funcionamento é o método de instanciação direta: forneça explicitamente o token de API (chave) e o CRN (identificador de instância) toda vez que precisar inicializar o serviço Qiskit Runtime. Consulte Encontre suas credenciais de acesso se necessário.

from qiskit_ibm_runtime import QiskitRuntimeService

service = QiskitRuntimeService(token=<cloud_api_key>, # Use the 44-character API_KEY you created and saved from the IBM Quantum Platform Home dashboard
            instance=<instance_CRN>)

Esse caminho é confiável, mas pode ser tedioso se você precisar carregar os mesmos detalhes repetidamente. Para evitar carregar suas credenciais várias vezes, se você estiver trabalhando em um ambiente Python confiável (como em um laptop pessoal ou estação de trabalho), você pode usar credenciais de conta salvas, conforme descrito na seção a seguir.

Embora o parâmetro de entrada instance seja opcional, é recomendável que você sempre forneça essa informação, a menos que queira usar um único serviço para trabalhar com várias instâncias. Nessa situação, consulte a seção seleção automática de instância.

Caminho de início rápido: Especificar credenciais salvas​

Se você já salvou suas credenciais, use o código a seguir para aplicar suas credenciais padrão. Para instruções sobre como salvar credenciais, consulte Salvar suas credenciais de acesso.

from qiskit_ibm_runtime import QiskitRuntimeService

# run every time you need the service
service = QiskitRuntimeService()
...

Se você nomeou um ou mais conjuntos de credenciais — por exemplo, para acesso aberto e premium — use o código a seguir para usar um conjunto de credenciais nomeadas.

from qiskit_ibm_runtime import QiskitRuntimeService

# run every time you need the service
service = QiskitRuntimeService(name="<name_of_saved_credentials>")
...

Considerações ao carregar credenciais salvas​

  • Se você inicializar um serviço com token e name, o token é ignorado e os detalhes salvos da conta name são carregados.

    No exemplo a seguir, o serviço carrega os detalhes de account_A e não usa token_B:

    from qiskit_ibm_runtime import QiskitRuntimeService

    service = QiskitRuntimeService(token="token_B", name="account_A")

  • Se você fornecer um name e uma instance ao inicializar um serviço, o serviço tentará carregar a conta name e se conectar à instance especificada. Se houver algum conflito, um aviso será emitido.

    No exemplo a seguir, o serviço tenta carregar as credenciais de account_A e usar a instância CRN_B — mesmo que haja uma instância diferente especificada em account_A:

    from qiskit_ibm_runtime import QiskitRuntimeService

    service = QiskitRuntimeService(instance="CRN_B", name="account_A")

  • O serviço tenta carregar a conta padrão salva somente se você não fornecer um token ou name ao inicializar um serviço. No entanto, se uma instance for fornecida explicitamente, o serviço tentará se conectar a essa instância usando as credenciais padrão. Se houver algum conflito, um aviso será emitido.

    No exemplo a seguir, o serviço tenta carregar as credenciais padrão e usar a instância CRN_B — mesmo que haja uma instância diferente especificada na conta padrão:

    from qiskit_ibm_runtime import QiskitRuntimeService

    service = QiskitRuntimeService(instance="CRN_B")

  • Se você salvar vários conjuntos de credenciais, mas não especificar um ao inicializar o serviço e não houver uma conta padrão salva, aquela cujo nome vem por último em ordem alfabética será usada.

    No exemplo a seguir, o usuário salvou contas chamadas "my_premium" e "my_open", mas não marcou nenhuma como padrão. Em seguida, inicializou o serviço usando o código a seguir. Nesse caso, as credenciais "my_premium" são usadas:

    from qiskit_ibm_runtime import QiskitRuntimeService

    service = QiskitRuntimeService()

  • Se você estiver recebendo persistentemente o erro "401 Unauthorized", pode estar tentando usar um token de portador em vez da sua chave de API.

Selecionar a instância automaticamente​

Se você fornecer um token mas não fornecer um CRN de instância ao instanciar o serviço, o QiskitRuntimeService autentica na conta identificada pelo token e usa a seleção automática de instância para escolher a instância mais relevante para a tarefa solicitada. Se você tiver várias instâncias disponíveis em sua conta, o serviço escolhe automaticamente entre as instâncias disponíveis, dependendo do recurso solicitado e destas opções do QiskitRuntimeService (se definidas): plans_preference, region, tags.

  • plans_preference: Os tipos de planos de instância a priorizar. Por exemplo, se [open] for passado, somente instâncias do Plano Open estarão disponíveis. Os valores aceitos são open, premium, pay-as-you-go, flex e on-prem. Se plans_preference não for especificado, os planos gratuitos têm prioridade sobre os planos pagos.
  • region: A região da instância. Os valores aceitos são us-east e eu-de.
  • tags: As tags da instância. Aceita uma lista de strings com nomes de tags.
nota

Você pode configurar suas credenciais salvas para selecionar uma instância automaticamente.

A instância é encontrada e usada nesta ordem:

  1. Se sua conta tiver acesso a apenas uma instância, ela será selecionada por padrão.
  2. Se as credenciais salvas estiverem sendo usadas e uma instância foi especificada com as credenciais, essa instância é usada. Consulte Considerações ao carregar credenciais salvas.
  3. Se sua conta tiver várias instâncias que podem acessar o QPU solicitado, o sistema usa suas preferências de plano especificadas para escolher um plano e uma instância. Para o Qiskit Runtime v0.42 e posterior, os planos gratuitos têm prioridade por padrão.
  4. Se sua conta tiver acesso a várias instâncias, mas apenas uma puder acessar o QPU solicitado, a instância com acesso é selecionada. Se essa instância não estiver associada a um plano gratuito, um custo será gerado.

Exemplos​

Neste exemplo, o serviço pesquisa todas as instâncias disponíveis na conta para encontrar aquelas que podem acessar o Backend especificado:

service = QiskitRuntimeService(token=<your-API_KEY>)

Neste exemplo, o serviço pesquisa todas as instâncias disponíveis na conta na região da UE para encontrar aquelas que podem acessar o Backend especificado:

service = QiskitRuntimeService(token=<your-API_KEY>, region="eu-de")

Neste exemplo, o serviço pesquisa todas as instâncias disponíveis na conta que estão marcadas como services para encontrar aquelas que podem acessar o Backend especificado:

service = QiskitRuntimeService(token=<your-API_KEY>, tags=['services'])

Neste exemplo, o serviço pesquisa todas as instâncias premium e open disponíveis na conta para encontrar aquelas que podem acessar o Backend especificado. Se um Backend estiver em uma instância do Plano Premium e em uma do Plano Open, a instância do Plano Premium terá prioridade porque premium é especificado primeiro em plans_preference.

service = QiskitRuntimeService(token=<your-API_KEY>, plans_preference=['premium', 'open'])

Determinar qual instância foi escolhida​

A instância selecionada é retornada como um aviso. Além disso, você pode executar service.active_instance() para determinar a instância ativa.

Testes locais com o Qiskit Runtime​

A classe QiskitRuntimeService pode ser inicializada com channel=local para realizar simulação local. Nesse caso, a autenticação não é necessária e não é preciso fornecer valores para token ou instance. Portanto, não é recomendável salvar uma conta local. Em vez disso, você pode fazer a instanciação direta:

from qiskit_ibm_runtime import QiskitRuntimeService

# Initialize for local testing

service = QiskitRuntimeService(channel="local")

Próximos passos​

Recomendações