Pular para o conteúdo principal
Última atualização em

Desenvolvimento Remoto do Databricks

info

Beta

O desenvolvimento remoto está em versão beta.

Databricks Remote Development permite que você acesse seu workspace e execute cargas de trabalho interativamente no Databricks compute a partir de IDEs usando um túnel SSH. É fácil de configurar, elimina a necessidade de gerenciamento de ambiente e mantém todo o código e dados seguros dentro do seu workspace Databricks .

Requisitos​

Para usar o Remote Development para se conectar ao Databricks serverless ou ao compute clássico, é preciso ter:

  • CLI do Databricks versão 1.5.0 ou acima instalada em sua máquina local e autenticação configurada. Consulte Instalar ou atualizar a CLI do Databricks.
  • Qualquer um dos seguintes:
    • Versão do Visual Studio Code: 1.110.0 (Universal) ou superior e a extensão Remote - SSH (1.0.46+) instalada.
    • Versão do Cursor: 2.6.11 (Universal) ou acima.

Para se conectar ao compute de GPU serverless, o recurso AI Runtime deve ser habilitado. Consulte AI Runtime.

Para conectar-se ao compute clássico (dedicado, de usuário único):

  • O compute deve estar executando o Databricks Runtime 17.0 ou acima. Consulte Visão geral do compute dedicado.
  • Unity Catalog precisa estar ativado.
  • Caso exista uma política compute , ela não deve proibir a execução de tarefas.
  • Ao usar um contêiner personalizado, ele deve ter openssh-server instalado.

Conecte-se ao compute serverless​

Para se conectar ao compute serverless, execute o comando databricks ssh connect em um terminal dentro do seu IDE. Nenhuma etapa de configuração separada é necessária.

Para obter mais informações sobre o comando databricks ssh connect, consulte o grupo de comandossh.

Bash
databricks ssh connect

Use a opção --accelerator para conectar-se ao AI Runtime:

Bash
databricks ssh connect --accelerator=GPU_1xA10

Após conectar, finalize a configuração do seu ambiente de desenvolvimento. Ver projetos abertos.

Para conectar-se ao compute serverless e começar a sessão no Visual Studio Code ou Cursor, use a opção --ide. A CLI abre uma janela IDE apontando para a pasta inicial do workspace.

Bash
databricks ssh connect --ide=vscode

Conectar-se ao compute clássico​

Para se conectar ao compute clássico, primeiro configure a conexão SSH e, em seguida, conecte-se usando seu IDE ou a partir do terminal.

Configure a conexão SSH.​

nota

A configuração da conexão SSH é necessária apenas se estiver conectando ao compute clássico.

Primeiro, configure o túnel SSH usando o comando databricks ssh setup. Forneça um nome para a conexão, por exemplo, substitua <connection-name> por my-connection:

Bash
databricks ssh setup --name <connection-name>

A interface de linha de comando (CLI) solicita que você selecione um cluster. Você também pode especificar um diretamente com --cluster <cluster-id>:

Bash
databricks ssh setup --name <connection-name> --cluster <cluster-id>
nota

Para usuários do IntelliJ, a Databricks recomenda adicionar --auto-start-cluster=false ao comando de configuração e iniciar o cluster manualmente antes de conectar. Isso ocorre porque IDEs da JetBrains iniciam todos clusters configurados na inicialização, o que pode resultar em cobranças compute inesperadas.

Conecte-se usando o Visual Studio Code ou o cursor.​

  1. Para o Visual Studio Code, instale a extensão Remote SSH. O Cursor inclui uma extensão SSH remota por default.

  2. No menu principal da IDE, clique em Exibir > Paleta de comandos . Selecione SSH remoto: Configurações . Alternativamente, selecione Preferências: Abrir configurações do usuário (JSON) para modificar settings.json diretamente.

  3. Em Remote.SSH: extensões padrão (ou remote.SSH.defaultExtensions em settings.json), adicione ms-Python.Python e ms-toolsai.jupyter.

    Se você estiver modificando settings.json:

    JSON
    "remote.SSH.defaultExtensions": [
        "ms-Python.Python",
        "ms-toolsai.jupyter"
    ]
nota

Opcionalmente, aumente o valor de Remote.SSH: Connect Timeout (ou remote.SSH.connectTimeout em settings.json) para reduzir ainda mais a chance de erros de tempo limite. O tempo limite default é 360.

  1. Na paleta de comandos, selecione Remote-SSH: Conectar ao host .

  2. No menu suspenso, selecione a conexão que você configurou no primeiro passo. A IDE prossegue para se conectar em uma nova janela.

Conecte-se usando o IntelliJ IDEs​

  1. Siga o tutorial do servidor remoto para configurar tudo.
  2. Na tela de nova conexão, digite:
    • Nome de usuário : root
    • Hospedar : <connection-name>

Conecte-se usando o terminal​

Bash
ssh <connection-name>

Projetos abertos​

Por padrão, o comando databricks ssh connect é aberto em um diretório efêmero. Para acessar os arquivos do workspace, navegue até o seu diretório de workspace no IDE ou terminal:

  • No Visual Studio Code ou Cursor, na Paleta de Comandos ( Cmd/Ctrl+Shift+P ), selecione Abrir Pasta e navegue até /Workspace/Users/<your-username>.
  • Em uma janela de terminal, altere seu diretório: cd /Workspace/Users/<your-username>.
nota

Os arquivos em /Workspace, /Volumes e /dbfs persistem após reinicializações do cluster. Os arquivos em /home, /root e outros caminhos locais são efêmeros e perdidos ao reiniciar.

código de execução (Visual Studio Code ou Cursor)​

Para executar código usando o Desenvolvimento Remoto, o ambiente virtual do Databricks deve ser configurado. Este ambiente inclui todas as bibliotecas DBR integradas e bibliotecas com escopo de compute.

  1. Abra a Paleta de Comandos ( Cmd/Ctrl+Shift+P ) e selecione Python: Selecionar Interpretador .

  2. Selecione o ambiente virtual pythonEnv-xxx da lista. Se não aparecer:

    1. execução echo $DATABRICKS_VIRTUAL_ENV de um terminal dentro do IDE.

      Exemplo de saída: /local_disk0/.ephemeral_nfs/envs/pythonEnv-xxx/bin/python

    2. Cole a saída completa como o caminho do interpretador no prompt Python: Selecionar Interpretador.

  3. Abra um novo terminal e o ambiente virtual deverá ser ativado automaticamente.

  4. Para executar um Notebook Jupyter, certifique-se de que o ambiente virtual esteja selecionado como o kernel. Clique em Selecionar Kernel no canto superior direito do Notebook.

Execute e depure arquivos Python e Notebooks .ipynb usando as extensões padrão do Python e do Jupyter.

Para usar Spark em um arquivo Python em compute serverless, inicialize uma sessão explicitamente:

Python
from databricks.connect import DatabricksSession
spark = DatabricksSession.builder.serverless().profile("DEFAULT").getOrCreate()

Gerenciar dependências Python​

Gerenciar dependências Python globalmente no nível do cluster ou com escopo para projetos individuais usando Notebooks.

biblioteca de clusters (recomendada)​

Instale as dependências através da interface do usuário workspace em compute > biblioteca . Esses persistem após reinicializações do cluster e estão disponíveis em pythonEnv-xxx. Veja a biblioteca de clusters.

Configuração do Notebook específica do projeto​

Para dependências no escopo do projeto, execute um Notebook contendo o comando %pip install no início de cada sessão:

Python
# Install from pyproject.toml
%pip install .

# Install from a requirements file
%pip install -r requirements.txt

# Install a wheel from Volumes or Workspace
%pip install /Volumes/catalog/schema/volume/your_library.whl

%pip O comando inclui as proteções específicas Databrickse propaga as dependências para os nós executor Spark . Isso permite funções definidas pelo usuário (UDFs) com dependências personalizadas.

Para mais exemplos, veja gerenciar biblioteca com %pip comando.

Não é necessário executar o Notebook novamente se a sessão se reconectar em até 10 minutos. Isso pode ser configurado usando -shutdown-delay na sua configuração SSH.

nota

Várias sessões SSH no mesmo cluster compartilham um ambiente virtual.

Limitações​

O desenvolvimento remoto do Databricks apresenta as seguintes limitações:

  • Clusters compartilhados não são suportados.
  • A extensão Databricks para Visual Studio Code e o Desenvolvimento Remoto ainda não são compatíveis e não devem ser usados em conjunto.
  • Os arquivos editados fora de /Workspace, /Volumes e /dbfs são perdidos na reinicialização do cluster.
  • É permitido um máximo de 10 conexões SSH por cluster.
  • Sessões inativas podem cair após 1 hora.
  • O Desenvolvimento Remoto não pode ser usado de outros ambientes remotos ou contêineres Docker.
  • Pode-se encontrar problemas de desempenho ou conexão quando três ou mais Notebooks Jupyter estiverem abertos simultaneamente. Essa limitação será abordada em uma versão futura.

Diferenças entre NotebooksDatabricks​

Existem algumas diferenças no Notebook ao usar o Desenvolvimento Remoto:

  • Os arquivos Python não definem nenhuma variável global do Databricks (como spark ou dbutils). Você deve importá-los explicitamente com from databricks.sdk.runtime import spark.
  • Para notebooks ipynb , estes recursos estão disponíveis:
    • Valores globais do Databricks: display, displayHTML, dbutils, table, sql, udf, getArgument, sc, sqlContext, spark
    • %sql comando mágico para executar células SQL

Para trabalhar com o código-fonte Python “Notebook”:

  • Procure por jupyter.interactiveWindow.cellMarker.codeRegex e defina-o como:

    ^# COMMAND ----------|^# Databricks notebook source|^(#\\s*%%|#\\s*\<codecell\\>|#\\s*In\\[\\d*?\\]|#\\s*In\\[ \\])

  • Procure por jupyter.interactiveWindow.cellMarker.default e defina-o como:

    # COMMAND ----------

Solução de problemas​

Esta seção contém informações sobre como resolver problemas comuns.

A conexão SSH falha ou expira.​

  • Verifique se o cluster está em execução na interface do usuário workspace .
  • Verifique se a porta de saída 22 está aberta e permitida em seu laptop, rede e VPN.
  • Aumente o tempo limite do SSH. Consulte Conectar usando o Visual Studio Code ou o Cursor.
  • Para erros de incompatibilidade key , exclua ~/.databricks/ssh-tunnel-keys e reexecução databricks ssh setup.
  • Para erros de "identificação do host remoto alterada", verifique o arquivo ~/.ssh/known_hosts e exclua as entradas relacionadas ao seu cluster.
  • As sessões SSH podem ser encerradas após 1 hora e um máximo de 10 conexões SSH podem ser feitas a um único cluster. Consulte Limitações.

comandocode não encontrado​

Se você vir Error: exec: "code": executable file not found in $PATH, abra a Paleta de Comandos ( Cmd/Ctrl+Shift+P ), selecione Comando Shell: Instalar comando 'code' no PATH e reinicie sua sessão de IDE ou terminal.

erros de autenticação da CLI​

  • Confirme se o seu perfil do Databricks CLI é válido usando databricks auth login.
  • Confirme se você tem permissões CAN MANAGE no cluster.

Meu código não funciona.​

Os arquivos desaparecem ou o ambiente é redefinido após a reinicialização cluster .​

  • Os arquivos nos pontos de montagem /Workspace, /Volumes e /dbfs persistem mesmo após reinicializações do cluster. Os arquivos em /home, /root e outros caminhos locais são efêmeros e perdidos ao reiniciar.
  • Utilize o gerenciamento de bibliotecas cluster para dependências persistentes. Automatize reinstalações usando um script de inicialização, se necessário. Veja O que são scripts de inicialização?

A configuração SSH falha no Windows (WSL)​

Execute databricks ssh setup diretamente no Windows, não no WSL. A instância do Visual Studio Code para Windows não consegue encontrar as configurações SSH criadas no ambiente WSL.

Perguntas frequentes​

Qual a diferença entre o desenvolvimento remoto e o Databricks Connect?​

Databricks Connect permite que você escreva código usando APIs Spark e o execute remotamente no compute Databricks , em vez de na sessão local Spark . A extensão Databricks para Visual Studio Code utiliza o Databricks Connect para fornecer depuração integrada do código do usuário no Databricks.

O Desenvolvimento Remoto permite que você acesse o workspace do seu IDE e move todo o seu ambiente de desenvolvimento para o compute — Python, kernel e todas as execuções são executadas no Databricks com acesso total aos recursos de compute.

Como meu código e meus dados são protegidos?​

Toda a execução de código ocorre dentro da sua VPC cloud Databricks . Nenhum dado ou código sai do seu ambiente seguro. O tráfego SSH é totalmente criptografado.

Quais IDEs são suportadas?​

O Visual Studio Code e o Cursor são oficialmente suportados. Qualquer IDE com recursos SSH é compatível, mas apenas o VS Code e o Cursor foram testados.

Todos os recursos Databricks Notebook estão disponíveis no IDE?​

Alguns recursos como display(), dbutils e %sql estão disponíveis com limitações ou configuração manual. Veja as diferenças entre os notebooksDatabricks.

Meu cluster iniciará automaticamente quando eu me conectar usando o túnel SSH?​

Sim, mas se a inicialização do cluster demorar mais do que o tempo limite de conexão, a tentativa de conexão falhará. Para evitar isso, aumente o valor de Remote.SSH: Connect Timeout na paleta de comandos (ou remote.SSH.connectTimeout em settings.json) para reduzir ainda mais a chance de erros de tempo limite.

Como posso saber se meu cluster está em execução?​

Navegue até "Compution" na interface do usuário workspace Databricks e verifique o status do cluster. O cluster precisa mostrar "Em execução" para que a conexão SSH funcione.

Como faço para desconectar minha sessão SSH/IDE?​

Você pode desconectar uma sessão fechando a janela do seu IDE, usando a opção Desconectar no seu IDE, fechando o terminal SSH ou executando o comando exit no terminal.

Como faço para desligar o cluster e evitar cobranças quando não estou trabalhando?​

Para interromper imediatamente, encerre o cluster na interface do usuário workspace . Navegue até "Compution" na interface do usuário workspace Databricks , encontre seu cluster e clique em "Terminate " ou "Stop" .

Configure uma política de encerramento automático de curta duração no seu cluster a partir da interface do usuário workspace . Após a desconexão, o servidor SSH aguarda o período shutdown-delay (default: 10 minutos), então o tempo limite do parado do cluster é aplicado.

Como devo lidar com dependências persistentes?​

As dependências instaladas durante uma sessão são perdidas após a reinicialização do cluster. Use armazenamento persistente (/Workspace/Users/<your-username>) para requisitos e scripts de configuração. Utilize a biblioteca cluster ou o script de inicialização para automação.

Quais métodos de autenticação são suportados?​

A autenticação usa a CLI do Databricks e seu arquivo de perfis ~/.databrickscfg. As chaves SSH são gerenciadas pelo Databricks Remote Development.

Posso me conectar a bancos de dados ou serviços externos a partir do cluster?​

Sim, desde que a sua rede cluster permita conexões de saída e você tenha a biblioteca necessária.

Posso usar extensões adicionais da IDE?​

A maioria das extensões funciona quando instalada em sua sessão SSH remota, dependendo do seu IDE e cluster. Por default o Visual Studio Code não instala extensões locais em hosts remotos. Você pode instalá-las manualmente abrindo o painel de extensões e ativando suas extensões locais no host remoto. Você também pode configurar o Visual Studio Code para sempre instalar determinadas extensões remotamente. Consulte Conectar-se ao Databricks.

Sim, no entanto, os administradores do workspace devem permitir as URLs dos marketplaces de extensão do Visual Studio Code e Cursor. Sua máquina local também deve ter a capacidade de acessar a internet.

Nesta página