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

Esta página descreve como migrar de uma instância de User-Managed Notebooks 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 pelo utilizador 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 blocos de notas geridos pelo utilizador 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 pelo utilizador 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 utilizador, pelo que, após a migração, pode continuar a usá-la. Se já não precisar da instância de blocos de notas geridos pelo utilizador, elimine-a para evitar cobranças adicionais relativas a essa instância.

Faturação

Se a sua instância de blocos de notas gerida pelo utilizador usar discos persistentes extremos, a migração gera custos para operações de E/S. Consulte "IOPS aprovisionados extremos" na secção de preços do Persistent Disk e do Hyperdisk de Preços dos discos.

Após a migração, a instância de blocos de notas geridos pelo utilizador continua a existir e a gerar cobranças como antes. Se já não precisar da instância de blocos de notas gerida pelo utilizador, 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 blocos de notas geridos pelo utilizador para uma instância do Vertex AI Workbench com especificações correspondentes. Quando uma especificação na instância dos blocos de notas geridos pelo utilizador 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 instância de notebooks geridos pelo utilizador, 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 pelo utilizador 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 Migrados
Rede Migrados
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 o script pós-arranque

As instâncias de blocos de notas geridas pelo utilizador 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 gerida pelo utilizador, tem de usar a Google Cloud CLI 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 blocos de notas geridos pelo utilizador para uma instância do Vertex AI Workbench, peça ao 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 pelo utilizador 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 blocos de notas geridos pelo utilizador para uma instância do Vertex AI Workbench:

    • notebooks.instances.create
    • notebooks.instances.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 pelo utilizador listando as suas 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 geridas pelo utilizador que ainda não foram migradas, use o método projects.locations.instances.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 instância de blocos de notas geridos pelo utilizador está localizada ou use - para listar instâncias de todas as regiões

    Execute o seguinte comando:

    Linux, macOS ou Cloud Shell

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

    Windows (PowerShell)

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

    Windows (cmd.exe)

    gcloud notebooks instances 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 instância de blocos de notas geridos pelo utilizador 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/instances?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/instances?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/instances?filter=migrated:false" | Select-Object -Expand Content

    Verifique se existem avisos ou erros na saída

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

    Os avisos são apresentados quando componentes específicos na configuração da instância dos notebooks geridos pelo utilizador não são migrados para a mesma especificação numa instância do Vertex AI Workbench. Por exemplo, se a instância de blocos de notas geridos pelo utilizador 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 de blocos de notas geridos pelo utilizador 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 InstanceMigrationEligibilitydocumentação.

    Migre através da ferramenta de migração

    Pode migrar a instância de blocos de notas gerida pelo utilizador 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 pelo utilizador.

      Aceda aos blocos de notas geridos pelo utilizador

    2. Clique no botão Migrar.

    3. Na página Migre blocos de notas geridos pelo utilizador para instâncias, no separador Pronto, selecione a instância que quer migrar.

    4. Clique em Migrar.

    5. Quando a migração estiver concluída, aceda à página Instâncias para ver a sua nova instância 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 instância de blocos de notas gerida pelo utilizador está localizada
    • INSTANCE_ID: o ID da instância de notebooks geridos pelo utilizador
    • 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 instances migrate RUNTIME_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

    Windows (PowerShell)

    gcloud notebooks instances migrate RUNTIME_ID `
    --project=PROJECT_ID `
    --location=LOCATION `
    --post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

    Windows (cmd.exe)

    gcloud notebooks instances migrate RUNTIME_ID ^
    --project=PROJECT_ID ^
    --location=LOCATION ^
    --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 instância de blocos de notas gerida pelo utilizador está localizada
    • INSTANCE_ID: o ID da instância de notebooks geridos pelo utilizador
    • 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/instances/INSTANCE_ID:migrate

    Corpo JSON do pedido: 

    {
  "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/instances/INSTANCE_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/instances/INSTANCE_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 dos blocos de notas geridos pelo utilizador. 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 blocos de notas geridos pelo utilizador.

    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 pelo utilizador, 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 de blocos de notas gerida pelo utilizador original 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 blocos de notas geridos pelo utilizador

    Se não precisar da instância de blocos de notas gerida pelo utilizador 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 pelo utilizador.

      Aceda aos blocos de notas geridos pelo utilizador

    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?