Ligue-se aos Databricks usando um túnel SSH

O túnel SSH fornecido pelo Databricks permite-lhe aceder ao seu espaço de trabalho e executar cargas de trabalho de forma interativa nos recursos de computação do Databricks a partir de IDEs através de um túnel SSH. É simples de configurar, elimina a necessidade de gestão do ambiente e mantém todo o código e dados seguros dentro do seu espaço de trabalho Databricks.

Requerimentos

Para usar o túnel SSH para estabelecer ligação aos recursos de computação Databricks serverless ou clássicos, deve ter:

• Databricks CLI versão 1.5.0 ou superior instalada na sua máquina local e autenticação configurada. Consulte Instalar ou atualizar a CLI do Databricks.
• 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 superior.

Para estabelecer ligação à computação GPU sem servidor, a funcionalidade AI Runtime tem de estar ativada. Ver Runtime de IA.

Para se ligar à computação clássica (dedicada, de utilizador único):

• O recurso de computação tem de estar a executar o Databricks Runtime 17.0 ou superior. Consulte Visão geral de computação dedicada.
• O Unity Catalog tem de estar ativado.
• Se existir uma política de computação, não deve proibir a execução de tarefas.
• Ao usar o Databricks Container Services para computação dedicada, a sua imagem Docker deve ter openssh-server sido instalada.

Conectar-se à computação sem servidor

Para te ligares à computação serverless, executa o databricks ssh connect comando a partir de um terminal dentro do teu IDE. Não é necessário um passo separado de configuração.

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

databricks ssh connect

Utilize a opção --accelerator para ligar-se ao AI Runtime:

databricks ssh connect --accelerator=GPU_1xA10

databricks ssh connect proporciona-te uma sessão interativa num único nó. Para tarefas de treino de longa duração ou treino distribuído por vários nós, submeta a carga de trabalho com a CLI air. Ver AI Runtime CLI.

Depois de ligar, termine de configurar o seu ambiente de desenvolvimento. Ver Projetos abertos.

Para estabelecer ligação à computação sem servidor e iniciar a sessão no Visual Studio Code ou no Cursor, use a opção --ide. A CLI abre uma janela do IDE que aponta para a pasta do espaço de trabalho principal.

databricks ssh connect --ide=vscode

Liga-se à computação clássica

Para te ligares à computação clássica, primeiro configura a ligação SSH e depois liga-te usando o teu IDE ou a partir do terminal.

Configurar a ligação SSH

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

databricks ssh setup --name <connection-name>

A CLI pede-te para selecionar um cluster. Também pode especificar um diretamente com:--cluster <cluster-id>

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

Liga-te usando Visual Studio Code ou Cursor

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

2. No menu principal do IDE, clique em Ver>Paleta de Comandos. Selecione Remote-SSH: Definições. Alternativamente, selecione Preferências: Abrir Definições de Utilizador (JSON) para modificar settings.json diretamente.

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

   Se está a modificar settings.json:

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

   Observação

   Opcionalmente, aumente o valor do Remote.SSH: Tempo de Espera de Conexão (ou remote.SSH.connectTimeout em settings.json) para reduzir ainda mais a probabilidade de erros de timeout. O timeout padrão é 360.

4. Na Paleta de Comandos, selecione Remote-SSH: Ligar ao Anfitrião.

5. No menu pendente, selecione a ligação que configurou no primeiro passo. O IDE procede a ligar-se numa nova janela.

Liga-te usando IDEs IntelliJ

1. Segue o tutorial do servidor remoto para te configurares.
2. No novo ecrã de ligação, introduz:
   • Nome de utilizador: root
   • Anfitrião: <connection-name>

Liga-te usando terminal

ssh <connection-name>

Projetos abertos

Por defeito, o databricks ssh connect comando abre-se num diretório efémero. Para aceder aos ficheiros do espaço de trabalho, navegue até ao diretório do espaço de trabalho a partir do IDE ou terminal:

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

Executar código (Visual Studio Code ou Cursor)

Para executar código usando o túnel SSH, é necessário configurar o ambiente virtual Databricks. Este ambiente inclui todas as bibliotecas DBR integradas e bibliotecas compute-scoped.

1. Abra a paleta de comandos (cmd/ctrl+Shift+P) e selecione Python: Select Interpreter.

2. Selecione o pythonEnv-xxx ambiente virtual da lista. Se configurares dependências em Python usando a --base-environment flag, seleciona o nome mais longo do ambiente virtual da lista de opções. Se o ambiente virtual não aparecer:

   1. Executa echo $DATABRICKS_VIRTUAL_ENV a partir de um terminal dentro do IDE.

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

   2. Cole o resultado completo como caminho para o interpretador no prompt Python: Select Interpreter.

3. Abre um novo terminal e o ambiente virtual deverá ativar-se automaticamente.

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

Execute e depure ficheiros e .ipynb cadernos Python usando as extensões padrão de Python e Jupyter.

Para usar o Spark num ficheiro Python em computação serverless, inicialize uma sessão explicitamente:

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

Gerenciar dependências

Gerir dependências utilizando um ambiente de base do espaço de trabalho, bibliotecas do cluster, scripts de inicialização ou notebooks, consoante o tipo de computação e os requisitos.

Ambientes base de workspace (recomendados para serverless e tempo de execução com IA)

Utilize um ambiente de base do espaço de trabalho com um ambiente serverless de versão 4 ou inferior para pré-configurar as dependências do Python. Crie um ambiente de base utilizando a interface do espaço de trabalho ou o comando do Databricks CLI databricks environments create-workspace-base-environment.

Especifique o ambiente usando a --base-environment opção ao ligar:

databricks ssh connect --base-environment my-workspace-env

Para mais informações sobre formatos aceites, consulte databricks ssh connect.

Bibliotecas de cluster (recomendadas para computação clássica)

Instale dependências usando a interface do workspace em Bibliotecas de Computação>. Estas persistem mesmo após reinícios do cluster e estão disponíveis em pythonEnv-xxx. Veja Bibliotecas em cluster.

Dependências não-Python

Para persistir dependências que não sejam Python, use um script init que instale os pacotes quando o cálculo começa. Opcionalmente, armazena os pacotes num volume do Unity Catalog e referencia-os a partir do script init. Consulte O que são scripts init?.

Configuração específica do notebook do projeto

Para dependências com âmbito de projeto, execute um caderno contendo %pip install comandos no início de cada sessão:

# 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 os comandos incluem guardrails específicos do Databricks e propagam dependências para nós executores do Spark. Isto permite funções definidas pelo utilizador (UDFs) com dependências personalizadas.

Para mais exemplos, veja Gerir bibliotecas com %pip comandos.

Não precisas de voltar a executar o caderno se a sessão se reconectar dentro de 10 minutos. Isto é configurável usando -shutdown-delay na sua configuração SSH.

Utilizar o Git

Pode usar a CLI Git num túnel SSH com pastas Git recém-criadas e as credenciais Git que configurou no espaço de trabalho Databricks.

Para que isto funcione como esperado, um administrador da área de trabalho tem de ativar a pré-visualização Utilizar comandos da CLI do Git (Beta) na página Pré-visualizações. Ver Gerir as pré-visualizações de Azure Databricks. Se a CLI pedir credenciais em vez de as utilizar automaticamente, deve ligar o seu fornecedor de Git ao Databricks; caso contrário, a funcionalidade da CLI do Git não está ativada no seu espaço de trabalho e deve contactar o seu administrador.

Limitações

O túnel SSH fornecido pela Databricks tem as seguintes limitações:

• Clusters partilhados não são suportados.
• A extensão Databricks para Visual Studio Code e o túnel SSH ainda não são compatíveis e não devem ser usados em conjunto.
• Ficheiros editados fora de /Workspace, /Volumes e /dbfs são perdidos ao reiniciar o cluster.
• É permitido um máximo de 10 ligações SSH por cluster.
• As sessões inativas podem ser terminadas após 1 hora.
• O túnel SSH não pode ser lançado a partir de outros ambientes remotos ou contentores Docker.
• Pode ter problemas de desempenho ou ligação quando três ou mais notebooks Jupyter estão abertos simultaneamente. Esta limitação será abordada numa versão futura.

Diferenças entre Databricks e Cadernos

Existem algumas diferenças nos notebooks ao usar o túnel SSH:

• Os ficheiros Python não definem os globais do Databricks (como spark ou dbutils). Deve importá-los explicitamente com from databricks.sdk.runtime import spark.
• Para cadernos ipynb, estas funcionalidades estão disponíveis:
  • Databricks globais: display, displayHTML, dbutils, table, sql, udf, getArgument, sc, sqlContext, spark
  • %sql comando mágico para executar células SQL

Para trabalhar com "notebooks" de fonte em Python:

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

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

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

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

Solução de problemas

Esta secção contém informações sobre como resolver questões comuns.

Ligação SSH falha ou expira

• Verifica se o cluster está a correr na interface do workspace.
• Verifica se a porta de saída 22 está aberta e permitida no teu portátil, rede e VPN.
• Aumenta o tempo de espera do SSH. Veja Conectar-se com Visual Studio Code ou Cursor.
• Para erros de descorrespondência de chaves, apague ~/.databricks/ssh-tunnel-keys e volte a executar databricks ssh setup.
• Para erros de "a identificação remota do host foi alterada", verifique o ficheiro ~/.ssh/known_hosts e apague as entradas relacionadas com o cluster.
• As sessões SSH podem ser interrompidas após 1 hora e não podem ser feitas mais de 10 ligações SSH a um único cluster. Consulte Limitações.

Comando code não encontrado

Se vires Error: exec: "code": executable file not found in $PATH, abre a Command Palette (Cmd/Ctrl+Shift+P), seleciona Shell Command: Install 'code' command in PATH e reinicia o teu IDE ou sessão de terminal.

Erros de autenticação CLI

• Confirme que o seu perfil de CLI Databricks é válido usando databricks auth login.
• Confirma que tens CAN MANAGE permissões no cluster.

O meu código não funciona

• Certifique-se de que configurou o ambiente virtual Databricks, veja Executar código (Visual Studio Code ou Cursor)
• Os cadernos IPYNB e *.py Databricks têm acesso às variáveis globais do Databricks, mas os ficheiros Python *.py não têm. Ver diferenças nos Databricks Notebooks.

Ficheiros desaparecem ou o ambiente reinicia após o reinício do cluster

• Ficheiros em pontos de montagem /Workspace, /Volumes e /dbfs persistem durante os reinícios do cluster. Ficheiros em /home, /root, e outros caminhos locais são efémeros e perdem-se ao reiniciar.
• Use a gestão de bibliotecas de cluster para dependências persistentes. Automatiza reinstalações usando scripts de init se necessário. Consulte O que são scripts init?.

Configuração do SSH falha no Windows (WSL)

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

FAQ

Como é que o túnel SSH é diferente do Databricks Connect?

O Databricks Connect permite-lhe escrever código usando APIs do Spark e executá-lo remotamente no processamento do Databricks em vez de na sessão local do Spark. A extensão Databricks Visual Studio Code utiliza o Databricks Connect para fornecer depuração integrada do código de utilizador no Databricks.

O túnel SSH permite-lhe aceder ao espaço de trabalho a partir do seu IDE e move todo o seu ambiente de desenvolvimento para o computador — Python, kernel, e toda a execução corre em Databricks com acesso total aos recursos de computação.

Como é que o meu código e dados estão protegidos?

Todo o código corre dentro da tua VPC cloud Databricks. Nenhum dado ou código sai do seu ambiente seguro. O tráfego SSH está totalmente encriptado.

Que IDEs são suportados?

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

Todas as funcionalidades dos notebooks Databricks estão disponíveis no IDE?

Algumas funcionalidades como display(), dbutils, e %sql estão disponíveis com limitações ou configuração manual. Ver diferenças nos Databricks Notebooks.

O meu cluster arranca automaticamente quando me ligo usando o túnel SSH?

Sim, mas se demorar mais a iniciar o cluster do que o tempo limite da ligação, a tentativa de ligação falha. Para evitar isto, aumente o valor do Remote.SSH: Conecte Timeout da paleta de comandos (ou remote.SSH.connectTimeout em settings.json) para reduzir ainda mais a possibilidade de erros de timeout.

Como sei se o meu cluster está a funcionar?

Navega até Computar na interface do espaço de trabalho Databricks e verifica o estado do cluster. O cluster tem de mostrar Em Execução para que a conexão SSH funcione.

Como posso desligar a minha sessão de SSH/IDE?

Podes desligar uma sessão fechando a janela do IDE, usando a opção Desligar no teu IDE, fechando o terminal SSH ou executando o exit comando no terminal.

Como posso parar o cluster e evitar cobranças quando não estou a trabalhar?

Para parar imediatamente, termine o cluster a partir da interface de utilizador do workspace. Navegue até Computar na interface de trabalho do Databricks, encontre o seu cluster e clique em Terminar ou Parar.

Defina uma política curta de auto-terminação no seu cluster a partir da interface do espaço de trabalho. Depois de desligar, o servidor SSH espera pelo período shutdown-delay (padrão: 10 minutos), depois, aplica-se o tempo limite de inatividade do cluster.

Como devo lidar com dependências persistentes?

As dependências instaladas durante uma sessão são perdidas após o reinício do cluster. Use armazenamento persistente (/Workspace/Users/<your-username>) para requisitos e scripts de configuração. Use bibliotecas de cluster ou scripts de init para automação.

Que métodos de autenticação são suportados?

A autenticação utiliza a CLI Databricks e o ficheiro dos seus ~/.databrickscfg perfis. As chaves SSH são tratadas pelo túnel SSH.

Posso ligar-me a bases de dados ou serviços externos a partir do cluster?

Sim, desde que a tua rede de cluster permita ligações de saída e tenhas as bibliotecas necessárias.

Posso usar extensões adicionais do IDE?

A maioria das extensões funciona quando instalada dentro da tua sessão remota de SSH, dependendo do teu IDE e cluster. O Visual Studio Code, por defeito, não instala extensões locais em hosts remotos. Pode instalá-las manualmente abrindo o painel de extensões e ativando as extensões locais no host remoto. Também podes configurar o Visual Studio Code para instalar sempre certas extensões remotamente. Ver Conectar ao Databricks.

O túnel SSH suporta Private Link?

Sim, no entanto, os administradores de workspace devem permitir listar URLs dos marketplaces de extensões Visual Studio Code e Cursor. A sua máquina local também deve ter a capacidade de aceder à internet.