Migre de blocos de notas geridos para instâncias do Vertex AI Workbench

Esta página descreve como migrar de uma instância de notebooks geridos para uma instância do Vertex AI Workbench. Pode migrar através da ferramenta de migração do Vertex AI Workbench ou migrar manualmente os dados e os ficheiros da sua instância.

Vista geral da ferramenta de migração

O Vertex AI Workbench oferece uma ferramenta de migração para migrar de uma instância de blocos de notas geridos para uma instância do Vertex AI Workbench.

A ferramenta de migração cria uma instância do Vertex AI Workbench com uma configuração semelhante à instância dos Managed Notebooks que quer migrar. Por exemplo, a ferramenta de migração cria uma instância com o mesmo ou um tipo de máquina, configuração de rede, definições de encerramento por inatividade e outras especificações semelhantes. Em seguida, os ficheiros no disco de dados da instância de blocos de notas geridos são copiados para a instância do Vertex AI Workbench.

O Vertex AI Workbench não elimina nem altera a sua instância de notebooks geridos, pelo que pode continuar a usá-la após a migração. Se já não precisar da instância de blocos de notas geridos, elimine-a para evitar cobranças adicionais relativas a essa instância.

Faturação

Se a sua instância de blocos de notas geridos usar discos persistentes extremos, a migração gera custos para operações de E/S. Consulte "IOPS aprovisionados extremos" na secção Preços do disco persistente e do Hyperdisk de Preços do disco.

Após a migração, a instância dos blocos de notas geridos continua a existir e a gerar cobranças como antes. Se já não precisar da instância dos blocos de notas geridos, elimine-a para evitar cobranças adicionais relativas a essa instância.

Comportamentos predefinidos da ferramenta de migração

A ferramenta de migração do Vertex AI Workbench tenta migrar a sua instância de notebooks geridos para uma instância do Vertex AI Workbench com especificações correspondentes. Quando uma especificação na sua instância de blocos de notas geridos não está disponível nas instâncias do Vertex AI Workbench, o Vertex AI Workbench usa uma especificação predefinida quando possível. Quando a ferramenta de migração não consegue migrar uma especificação da sua instância de blocos de notas geridos, não migra a instância.

A tabela seguinte apresenta alguns dos principais comportamentos de migração predefinidos da ferramenta de migração.

Categoria Especificação dos notebooks geridos Resultado da migração
SO Qualquer versão do Ubuntu Debian 11
Qualquer versão do Debian Debian 11
Framework Qualquer versão do CUDA CUDA 11.3
Qualquer versão do Python Python 3.10
Qualquer versão do PyTorch PyTorch 1.13
Qualquer versão do TensorFlow TensorFlow 2.11
Qualquer versão R Não migrado; consulte o artigo Adicione um ambiente conda
Qualquer versão local do PySpark Não migrado; consulte o artigo Adicione um ambiente conda
Qualquer versão do XGBoost Não migrado; consulte o artigo Adicione um ambiente conda
Qualquer versão do Python do Kaggle Não migrado; consulte o artigo Adicione um ambiente conda
Qualquer versão do Jax Não migrado; consulte o artigo Adicione um ambiente conda
Qualquer versão do Apache Beam Não migrado; consulte o artigo Adicione um ambiente conda
Tipo de máquina Um tipo de máquina suportado Tipo de máquina idêntico
Um tipo de máquina não suportado e2-standard-4
Aceleradores Aceleradores suportados Aceleradores idênticos
Aceleradores não suportados A migração não inclui aceleradores
Definição Encerramento por inatividade Migrados
Eliminar para o lixo Migrados
nbconvert Migrados
Transferência de ficheiros Migrados
Acesso ao terminal Migrados
Outro Autorizações da gestão de identidade e de acesso Migrada, embora possam ser necessárias novas autorizações para usar a instância do Vertex AI Workbench
Modo de acesso Migradas; as instâncias que usam o modo de acesso do JupyterLab de utilizador único têm de especificar a opção serviceAccount
Rede Migrado; as instâncias que usam uma nuvem virtual privada gerida pela Google têm de especificar as opções network e subnet
Script de pós-arranque Quando usa a Google Cloud consola, a instância é migrada sem o script de pós-arranque. Para migrar a instância com o script de pós-arranque, use a Google Cloud CLI ou a API REST para especificar a opção PostStartupScriptOption
Dataproc Hub Não migrado; tem de migrar manualmente

Especificar opções

As secções seguintes descrevem os casos em que é necessário especificar uma opção para migrar a instância de blocos de notas geridos para uma instância do Vertex AI Workbench.

Instâncias que usam o modo de acesso de utilizador único

As instâncias de blocos de notas geridas que usam o modo de acesso de utilizador único têm de ser migradas para uma instância com a opção serviceAccount especificada. A instância do Vertex AI Workbench para a qual migra restringe o acesso ao JupyterLab ao utilizador único, mas usa uma conta de serviço para interagir com Google Cloud serviços e APIs.

Instâncias que usam uma VPC gerida pela Google

As instâncias de blocos de notas geridas que usam uma VPC gerida pela Google têm de ser migradas para uma instância com as opções network e subnet especificadas. A opção de usar uma VPC gerida pela Google não é suportada nas instâncias do Vertex AI Workbench, pelo que tem de especificar uma rede diferente.

Instâncias que usam um script pós-arranque

As instâncias de blocos de notas geridas que usam um script de pós-arranque têm de ser migradas para uma instância com a opção PostStartupScriptOption especificada. Use esta opção para indicar se quer ignorar ou executar novamente o script de pós-inicialização na nova instância do Vertex AI Workbench.

A especificação da opção PostStartupScriptOption não é suportada na consola Google Cloud . Para especificar a opção PostStartupScriptOption quando migrar a instância de blocos de notas geridos, tem de usar a CLI do Google Cloud ou a API REST.

Antes de começar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Notebooks API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Notebooks API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.

    Funções necessárias

    Para receber as autorizações de que precisa para migrar uma instância de notebooks geridos para uma instância do Vertex AI Workbench, peça ao seu administrador para lhe conceder a função de IAM Notebooks Runner (roles/notebooks.runner) no projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

    Esta função predefinida contém as autorizações necessárias para migrar uma instância de notebooks geridos para uma instância do Vertex AI Workbench. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

    Autorizações necessárias

    São necessárias as seguintes autorizações para migrar uma instância de notebooks geridos para uma instância do Vertex AI Workbench:

    • notebooks.runtimes.create
    • notebooks.runtimes.get

    Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

    Verificação pré-migração

    Antes de migrar, verifique a elegibilidade para migração da instância de blocos de notas geridos listando as instâncias e verificando o resultado quanto a avisos ou erros de migração.

    Apresente uma lista das suas instâncias

    Para listar as instâncias de blocos de notas geridos que ainda não foram migradas, use o método projects.locations.runtimes.list com o filtro migrated:false. Pode listá-los através da CLI gcloud ou da API REST:

    gcloud

    Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

    • PROJECT_ID: o ID do seu projeto
    • LOCATION: a região onde a sua instância de blocos de notas geridos está localizada ou use - para listar instâncias de todas as regiões

    Execute o seguinte comando:

    Linux, macOS ou Cloud Shell

    gcloud notebooks runtimes list --project=PROJECT_ID \
    --location=LOCATION --filter=migrated:false --format=default

    Windows (PowerShell)

    gcloud notebooks runtimes list --project=PROJECT_ID `
    --location=LOCATION --filter=migrated:false --format=default

    Windows (cmd.exe)

    gcloud notebooks runtimes list --project=PROJECT_ID ^
    --location=LOCATION --filter=migrated:false --format=default

    REST

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • PROJECT_ID: o ID do seu projeto
    • LOCATION: a região onde a sua instância de blocos de notas geridos está localizada ou use - para listar instâncias de todas as regiões

    Método HTTP e URL: 

    GET https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes?filter=migrated:false

    Para enviar o seu pedido, escolha uma destas opções:

    curl

    Execute o seguinte comando: 

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes?filter=migrated:false"

    PowerShell

    Execute o seguinte comando: 

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes?filter=migrated:false" | Select-Object -Expand Content

    Verifique se existem avisos ou erros no resultado

    Se forem detetados avisos ou erros de migração, o resultado do método projects.locations.runtimes.list inclui estas informações.

    Os avisos são apresentados quando componentes específicos na configuração da instância dos notebooks geridos não são migrados para a mesma especificação numa instância do Vertex AI Workbench. Por exemplo, se a sua instância de blocos de notas geridos usar um acelerador não suportado, é apresentado um aviso no resultado. Neste caso, a instância é migrada sem aceleradores. Pode anexar aceleradores após a migração. Reveja os avisos no resultado, considere os comportamentos predefinidos da ferramenta de migração e avalie se a ferramenta de migração é aceitável para a sua migração.

    Um ou mais erros no resultado significa que não pode migrar a instância dos blocos de notas geridos através da ferramenta de migração. Tem de migrar a instância manualmente.

    Para mais informações sobre avisos e erros de migração, consulte os avisos e os erros na RuntimeMigrationEligibilitydocumentação.

    Migre através da ferramenta de migração

    Pode migrar a instância de blocos de notas geridos através da Google Cloud consola, da CLI gcloud ou da API REST.

    Consola

    1. Na Google Cloud consola, aceda à página Blocos de notas geridos.

      Aceda a notebooks geridos

    2. Clique no botão Migrar. É aberta a página Migrar blocos de notas geridos para instâncias.

    3. Para migrar instâncias que não precisam de opções especificadas, clique no separador Pronto, selecione as instâncias que quer migrar e, de seguida, clique em Migrar.

    4. Para migrar instâncias que precisam de opções especificadas, clique no separador Requer entrada, selecione as instâncias que quer migrar e, de seguida, clique em Migrar.

      1. Na caixa de diálogo Forneça informações para a migração, especifique uma rede e uma conta de serviço a usar para as novas instâncias do Vertex AI Workbench que selecionou.

      2. Clique em Enviar.

    5. Após a conclusão das migrações, aceda à página Instâncias para ver as novas instâncias do Vertex AI Workbench.

      Aceda a Instâncias

    gcloud

    Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

    • PROJECT_ID: o ID do seu projeto
    • LOCATION: a região onde a sua instância de blocos de notas geridos está localizada
    • RUNTIME_ID: o ID da instância dos blocos de notas geridos
    • NETWORK: a rede para a qual quer migrar a instância
    • SUBNET: a sub-rede para a qual quer migrar a instância
    • SUBNET_REGION: a região da sub-rede
    • SERVICE_ACCOUNT: opcional: o endereço de email da conta de serviço que quer usar
    • POST_STARTUP_SCRIPT_OPTION: opcional: uma das opções de script de pós-inicialização

    Execute o seguinte comando:

    Linux, macOS ou Cloud Shell

    gcloud notebooks runtimes migrate RUNTIME_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --network=NETWORK \
    --subnet=SUBNET \
    --subnet-region=SUBNET_REGION \
    --service-account=SERVICE_ACCOUNT \
    --post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

    Windows (PowerShell)

    gcloud notebooks runtimes migrate RUNTIME_ID `
    --project=PROJECT_ID `
    --location=LOCATION `
    --network=NETWORK `
    --subnet=SUBNET `
    --subnet-region=SUBNET_REGION `
    --service-account=SERVICE_ACCOUNT `
    --post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

    Windows (cmd.exe)

    gcloud notebooks runtimes migrate RUNTIME_ID ^
    --project=PROJECT_ID ^
    --location=LOCATION ^
    --network=NETWORK ^
    --subnet=SUBNET ^
    --subnet-region=SUBNET_REGION ^
    --service-account=SERVICE_ACCOUNT ^
    --post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

    REST

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • PROJECT_ID: o ID do seu projeto
    • LOCATION: a região onde a sua instância de blocos de notas geridos está localizada
    • RUNTIME_ID: o ID da instância dos blocos de notas geridos
    • NETWORK: a rede para a qual quer migrar a instância
    • SUBNET: a sub-rede para a qual quer migrar a instância
    • SERVICE_ACCOUNT: opcional: o endereço de email da conta de serviço que quer usar
    • POST_STARTUP_SCRIPT_OPTION: opcional: uma das opções de script de pós-inicialização

    Método HTTP e URL: 

    POST https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes/RUNTIME_ID:migrate

    Corpo JSON do pedido: 

    {
  "network": NETWORK,
  "subnet": SUBNET,
  "serviceAccount": SERVICE_ACCOUNT_EMAIL_ADDRESS,
  "postStartupScriptOption": (POST_STARTUP_SCRIPT_OPTION)
}

    Para enviar o seu pedido, escolha uma destas opções:

    curl

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

    curl -X POST \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
         "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes/RUNTIME_ID:migrate"

    PowerShell

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/runtimes/RUNTIME_ID:migrate" | Select-Object -Expand Content

    Migre manualmente

    Para migrar manualmente a sua instância para uma instância do Vertex AI Workbench, considere usar os seguintes métodos:

    • Use o Cloud Storage e o terminal: copie os seus dados e ficheiros para o Cloud Storage e, em seguida, para outra instância através do terminal.

    • Use o GitHub: copie os seus dados e ficheiros para um repositório do GitHub usando a extensão Git para o JupyterLab.

    Este guia descreve como migrar dados e ficheiros através do Cloud Storage e do terminal.

    Requisitos

    Tem de ter acesso ao terminal da instância de blocos de notas geridos. O acesso ao terminal é definido manualmente quando cria uma instância. Não é possível alterar a definição de acesso ao terminal após a criação da instância.

    Migre manualmente através do Cloud Storage e do terminal

    Para migrar dados e ficheiros para uma nova instância do Vertex AI Workbench através do Cloud Storage e do terminal, faça o seguinte.

    1. Crie um contentor do Cloud Storage no mesmo projeto onde se encontra a instância dos notebooks geridos.

    2. Nesse mesmo projeto, crie uma instância do Vertex AI Workbench para migrar os seus dados. Quando cria esta instância:

      • Ative o acesso ao terminal.
      • Especifique o tipo de máquina, a rede e outras caraterísticas para corresponder ao que precisa.

    3. Na interface do JupyterLab da instância de blocos de notas geridos, selecione Ficheiro > Novo > Terminal para abrir uma janela de terminal.

    4. Use a CLI gcloud para copiar os dados do utilizador para um contentor do Cloud Storage. O comando de exemplo seguinte copia todos os ficheiros do diretório /home/jupyter/ da sua instância para um diretório num contentor do Cloud Storage.

      gcloud storage cp /home/jupyter/* gs://BUCKET_NAMEPATH --recursive

      Substitua o seguinte:

      • BUCKET_NAME: o nome do seu contentor do Cloud Storage
      • PATH: o caminho para o diretório onde quer copiar os seus ficheiros, por exemplo: /copy/jupyter/

    5. Na interface do JupyterLab da nova instância do Vertex AI Workbench, selecione Ficheiro > Novo > Terminal para abrir uma janela de terminal.

    6. Use a CLI gcloud para copiar os seus dados para a nova instância. O comando de exemplo seguinte copia todos os ficheiros de um diretório do Cloud Storage para o diretório /home/jupyter/ da nova instância.

      gcloud storage cp gs://BUCKET_NAMEPATH* /home/jupyter/ --recursive

    Confirme a migração

    Após a migração, a instância original dos blocos de notas geridos continua a funcionar como antes. Confirme se a migração foi bem-sucedida antes de eliminar a instância original.

    Elimine a instância de notebooks geridos

    Se não precisar da instância de blocos de notas geridos a partir da qual fez a migração, elimine-a para evitar cobranças adicionais relativas a essa instância.

    1. Na Google Cloud consola, aceda à página Blocos de notas geridos.

      Aceda a notebooks geridos

    2. Selecione a instância que quer eliminar.

    3. Clique em  Eliminar. (Consoante o tamanho da janela, o botão Eliminar pode estar no menu de opções .)

    4. Para confirmar, clique em Eliminar.

    Resolver problemas

    Para encontrar métodos de diagnóstico e resolução de problemas de migração, consulte o artigo Resolução de problemas do Vertex AI Workbench.

    O que se segue?