Ligue-se aos Databricks usando um túnel SSH

Importante

Este recurso está em versão Beta.

O custo e o preço das funcionalidades na Beta estão sujeitos a alterações.

O túnel Azure Databricks SSH (Secure Shell) liga o Visual Studio Code, Cursor ou o seu terminal ao workspace do Azure Databricks e ao Azure Databricks serverless compute, AI Runtime ou classic compute. Usa-o para editar ficheiros de espaço de trabalho e executar ou depurar scripts e notebooks em Python, com o teu ambiente Python e execução de código na máquina de computação remota. Liga-te diretamente à computação serverless, ou configura uma ligação SSH reutilizável a um cluster clássico dedicado.

Requerimentos

Inicia a ligação SSH a partir da tua máquina local. O túnel não pode ser lançado a partir de outro ambiente remoto ou de um contentor Docker.

Para se ligar à computação serverless ou clássica, deve ter:

  • Databricks CLI versão 1.5.0 ou superior instalada na sua máquina local e autenticação configurada. Verifique a sua versão instalada com databricks --version. Consulte Instalar ou atualizar a CLI do Databricks.
  • Um dos seguintes:
    • Visual Studio Code versão 1.110.0 (Universal) ou superior e a extensão Remote - SSH (1.0.46+) instalada.
    • Cursor versão 2.6.11 (Universal) ou superior.

Para se ligar à computação serverless, o encaminhamento de portas para computação serverless deve estar ativado. Veja o Gerir encaminhamento de portas para computação serverless.

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

Requisitos adicionais para computação clássica

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

Escolha uma ligação SSH

Utilize o método de ligação para o seu tipo de processamento:

Computação Método de ligação Requisitos de configuração
Computação sem servidor databricks ssh connect Não há um passo separado de configuração do SSH.
Adicionar --ide vscode ou --ide cursor para lançar um IDE.
Ambiente de Execução de IA databricks ssh connect --accelerator <accelerator> Não há um passo separado de configuração do SSH.
Adicionar --ide vscode ou --ide cursor para lançar um IDE.
Para aceleradores suportados, veja --accelerator.
Computação clássica dedicada e de utilizador único Execute databricks ssh setup --name <connection-name> no seu terminal.
Depois inicia a sessão SSH a partir do IDE ou executa ssh <connection-name>.		 Selecione um cluster dedicado de utilizador único que cumpra os requisitos clássicos de computação.
Clusters partilhados não são suportados.

Para uma comparação com o Databricks Connect e outras opções de desenvolvimento, consulte Connect a partir do seu IDE.

Conectar-se à computação sem servidor

Ao cumprires os requisitos acima, executa databricks ssh connect a partir do teu terminal ou IDE.

O --ide valor seleciona o editor a lançar, independentemente do editor ou terminal de onde execute o comando.

Código do Visual Studio

databricks ssh connect --ide vscode

A CLI abre uma janela do Visual Studio Code ligada ao ambiente de computação remoto.

Cursor

databricks ssh connect --ide cursor

A CLI abre uma janela Cursor ligada à computação remota.

Terminal

databricks ssh connect

O CLI inicia uma sessão interativa de SSH.

Para opções de comandos, incluindo ligações nomeadas e perfis de autenticação, veja databricks ssh connect.

Depois de estabeleceres ligação, abre o teu projeto da área de trabalho e seleciona o ambiente Python. Se a ligação falhar, veja Resolução de problemas de ligações de túnel SSH.

Liga-te à computação de GPU serverless com AI Runtime

Com o AI Runtime ativado, adicione --accelerator para usar computação com GPU:

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 databricks air em vez disso. Veja Utilizar a CLI do Databricks com runtime de IA.

Liga-se à computação clássica

Para uma ligação reutilizável a um cluster dedicado clássico, configura um nome de host SSH e depois seleciona esse host no teu IDE ou liga-te a partir de um terminal.

Configurar a ligação SSH

Observação

Configurar a ligação SSH só é necessário se estiveres a ligar à computação clássica.

Executa databricks ssh setup na tua máquina local. Substitua <connection-name> por um nome para esta ligação, como my-connection:

databricks ssh setup --name <connection-name>

A CLI pede-te para selecionar um cluster e adiciona uma entrada de host à tua configuração SSH. Também podes selecionar um cluster diretamente. Substitua <cluster-id> pelo ID do seu cluster dedicado:

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

Para configurar quanto tempo o túnel SSH espera após o último cliente se desconectar, adicione --shutdown-delay ao comando de configuração. O padrão é 10 minutos. Por exemplo, para definir um atraso de 30 minutos para conexões através desta entrada de anfitrião SSH:

databricks ssh setup --name <connection-name> --cluster <cluster-id> --shutdown-delay 30m

Observação

Para utilizadores de IntelliJ, o Databricks recomenda adicionar --auto-start-cluster=false ao comando de configuração e iniciar o cluster manualmente antes de ligar. Isto deve-se ao facto de os IDEs do JetBrain iniciarem todos os clusters configurados no lançamento, o que pode resultar em cargas de computação inesperadas.

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>

Ligue-se à computação clássica a partir de um terminal

Utilize o nome da ligação que configurou com databricks ssh setup:

ssh <connection-name>

Para uma ligação direta sem entrada de host SSH reutilizável, também pode usar a CLI. Substitua <cluster-id> pelo seu ID dedicado do cluster:

databricks ssh connect --cluster <cluster-id>

Ver databricks ssh connect.

Abrir projetos do espaço de trabalho através de SSH

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>.

Observação

Ficheiros em /Workspace, /Volumes, e /dbfs persistem através dos reinicios do cluster. Ficheiros em /home, /root, e outros caminhos locais são efémeros e perdem-se ao reiniciar.

Execute Python e notebooks na sessão SSH

Selecione o ambiente Python fornecido pela sua sessão SSH antes de executar o código. Para computação clássica, este ambiente inclui as bibliotecas de Runtime Databricks incorporadas e as bibliotecas associadas à computação.

  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()

Gerir dependências para sessões SSH

Escolha a gestão de dependências para o seu tipo de processamento:

Para pacotes não Python, veja Dependências não Python.

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

Observação

Esta funcionalidade requer que a pré-visualização do suporte ao ambiente de base do espaço de trabalho sem servidor no Jobs esteja ativada. Ver Gerir as pré-visualizações de Azure Databricks.

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. O túnel SSH não suporta --base-environment com a versão 5 ou superior do ambiente serverless. 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

A --base-environment opção aceita um nome de visualização, um caminho YAML de espaço de trabalho ou um ID de recurso. Não podes combiná-lo com --cluster. Ver 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 notebook de configuração se voltares a ligar antes de o túnel SSH desligar. Por defeito, o túnel desliga-se 10 minutos depois de o último cliente se desligar. Para alterar este atraso, use --shutdown-delay com o comando para o seu método de ligação:

  • Para uma ligação de computação clássica reutilizável, defina o atraso com databricks ssh setup. A entrada do host SSH gerada aplica-se o atraso quando liga a partir do seu IDE ou executa ssh <connection-name>.
  • Para uma ligação CLI direta, defina o tempo de espera com databricks ssh connect.

Observação

Múltiplas sessões SSH no mesmo cluster partilham um ambiente virtual.

Usar o Git numa sessão SSH

Importante

Este recurso está no Public Preview. Os administradores do espaço de trabalho podem controlar o acesso ao suporte Git CLI para pastas Git a partir da página de Pré-visualizações . Ver Gerir as pré-visualizações de Azure Databricks.

Podes usar a CLI Git no túnel SSH com pastas Git recém-criadas e as credenciais Git que configuraste no espaço de trabalho do Azure Databricks. Veja Utilizar comandos Git CLI.

Se a CLI pedir credenciais em vez de as detetar automaticamente, deve ligar o seu fornecedor Git ao Azure Databricks. Veja Ligar o seu fornecedor Git ao Databricks.

Mantenha processos desanexados a funcionar

Por defeito, quando o túnel SSH é desligado, ele para todos os processos que a sessão iniciou, incluindo os processos que desanexou da sessão com tmux, setsid ou nohup. Antes de os parar, o túnel regista um aviso com os IDs de processo deles na saída da execução do trabalho do túnel. databricks ssh connect imprime o ID da execução do trabalho quando o databricks ssh connect inicia o túnel.

Para manter a tarefa destacada a correr depois de desligar, use a opção --keep-detached-processes. Defina a opção na conexão que inicia o túnel, antes de começar o trabalho que quer manter. Ver Ligações a um túnel existente.

  • Computação serverless ou clássica: Passa a bandeira para databricks ssh connect.
  • Computação clássica com um host SSH configurado: Passe a flag para databricks ssh setup. A entrada do host SSH gerada é aplicada sempre que se liga. As ligações serverless não requerem configuração, por isso esta opção aplica-se apenas à computação clássica.

O exemplo seguinte mantém processos em segundo plano a correr em computação serverless:

databricks ssh connect --keep-detached-processes

O exemplo seguinte mantém processos desanexados a correr num cluster dedicado:

databricks ssh connect --cluster 0123-456789-abcdefgh --keep-detached-processes

Quando usa esta flag e o último cliente se desliga, o túnel comporta-se da seguinte forma:

  • Após esse --shutdown-delay período, o túnel verifica processos desanexados. Enquanto alguns estão a funcionar, o túnel continua a funcionar em vez de se desligar.
  • Processos desanexados mantêm o seu acesso a /Workspace e /Volumes.
  • Após a saída do último processo desanexado, o túnel encerra-se e a execução da tarefa termina.

Enquanto o túnel continua a correr, pode reconectar-se ao mesmo compute e voltar a ligar a trabalhos desanexados, por exemplo com tmux attach. Em computação serverless, reconecta-te com o mesmo nome de ligação. Se omitires --name, a CLI deriva o nome da ligação do teu workspace e das opções --accelerator e --base-environment, por isso, mudar qualquer uma dessas opções inicia uma ligação separada.

Ligações a um túnel existente

O modo do túnel é fixo quando é iniciado, e as ligações posteriores tratam-no da seguinte forma:

  • Se ligares com a flag a um túnel que começou sem ela, a CLI inicia um novo túnel. Os processos que desanexaste no túnel existente não são mantidos, e continuam a parar quando esse túnel desliga. Num cluster dedicado, o novo túnel interrompe imediatamente o túnel existente, o que termina as suas sessões abertas e os seus processos desanexados.
  • Se ligares sem a flag a um túnel que começou com ela, a CLI reutiliza esse túnel, e o túnel continua a funcionar enquanto os processos desanexados permanecem. Isto aplica-se também a ligações de outras entradas de anfitrião SSH ou sessões do IDE para o mesmo recurso de computação.

Custos e vida útil máxima

Tenha em mente o seguinte:

  • Enquanto o túnel continua a funcionar, a computação continua a funcionar e incorre em custos. Um cluster clássico não termina automaticamente. Uma sessão ociosa tmux conta como um processo destacado em execução, por isso feche-a quando já não precisar dela.
  • A execução do trabalho ainda para quando atinge o tempo máximo de vida definido por --server-timeout, mesmo que processos destacados estejam em execução. Este tempo de vida conta a partir do início da execução da tarefa, não a partir do momento em que o último cliente se desconecta. Depois de a execução da tarefa terminar, os processos desanexados perdem o acesso a /Workspace e /Volumes. Na computação serverless, os processos desanexados param. Na computação clássica, podem continuar a funcionar sem esse acesso até o cluster terminar. Para manter a saída de trabalho desanexado de longa duração, guarde-a com o Azure Databricks SDK ou a API REST em vez de escrever em caminhos /Workspace ou /Volumes. Consulte Trabalhar com arquivos em volumes do Catálogo Unity.
  • Para trabalhos de longa duração, use jobs ou bundles em vez disso.

Executar agentes de codificação numa sessão SSH

Podes executar Claude Code e Codex em sessões SSH sem qualquer instalação ou configuração. Os agentes enviam pedidos de modelo através do Unity Gateway no seu espaço de trabalho e autenticam-se com as credenciais da sua sessão SSH.

Requisitos para agentes de codificação

  • Databricks CLI versão 1.23.0 ou superior na sua máquina local.

  • Unity Gateway ativado para o teu espaço de trabalho, com acesso aos modelos que queres usar. Consulta os pré-requisitos do guia de introdução rápida do agente de programação.

  • Acesso HTTPS de saída da instância de computação para os seguintes hosts. A primeira execução transfere as ferramentas do agente deles:

    • github.com e nodejs.org
    • PyPI: pypi.org e files.pythonhosted.org
    • npm registry: registry.npmjs.org

    Se a imagem de computação já incluir uv ou npm, o launcher ignora o download.

Lançar um agente de codificação

  1. Liga-te à tua capacidade de computação. Consulte Escolher uma ligação SSH para as diferentes formas de ligação.

  2. No terminal da sessão SSH, execute o agente:

    claude

    ou

    codex

    Quaisquer argumentos que adicionar são entregues ao agente sem alterações.

Para executar um agente sem abrir uma sessão interativa, passe o comando do agente após --. O shell remoto interpreta o comando, por isso envolva todo o comando em aspas simples para manter intactos os argumentos entre aspas. Por exemplo, para executar o Claude Code em modo não interativo:

databricks ssh connect -- 'claude -p "Summarize the notebooks in my workspace home folder"'

Os comandos passados após -- iniciam no teu diretório pessoal no computador, não na pasta inicial do teu espaço de trabalho.

Na primeira vez que executas um agente no compute, o launcher descarrega e instala automaticamente as ferramentas do agente.

Restrições dos agentes de codificação

  • As ferramentas do agente, o histórico de conversas e as definições do agente estão armazenadas no teu diretório pessoal no ambiente de computação. Na computação serverless, este diretório desaparece quando a computação é desligada. Num cluster dedicado, persiste em sessões SSH até o cluster reiniciar ou terminar. Para guardar o seu trabalho, armazene ficheiros em /Workspace ou /Volumes. Veja Ficheiros desaparecem ou o ambiente é reposto após o reinício do cluster.
  • Se tu próprio instalares claude ou codex no computador, essa instalação tem prioridade e não está configurada para o Unity Gateway.

Limitações dos túneis SSH

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

  • Clusters partilhados não são suportados.
  • 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.

Comportamento do Notebook em sessões SSH

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 ----------

Resolução de problemas para ligações de túnel SSH

Comece pelo sintoma que corresponde à falha:

Symptom Primeira verificação
A ligação SSH falha ou expira. Verifica o acesso HTTPS e WebSocket do workspace. Para computação clássica, verifica também o estado do cluster e o timeout do IDE. Veja A ligação SSH falha ou expira.
O CLI informa que não consegue encontrar code. Instale o comando shell do Visual Studio Code no seu ambiente local PATH. codecomando não encontrado.
A autenticação na CLI falha. Verifique o perfil CLI e, para a computação clássica, as permissões do cluster. Veja erros de autenticação da CLI.
O CLI indica invalid_grant com Refresh token is invalid. Iniciar sessão novamente no espaço de trabalho usando o mesmo perfil de CLI e depois tentar a ligação novamente. Veja O token de atualização é inválido.
O código Python ou os notebooks falham após estabelecer ligação. Verifique o interpretador selecionado ou kernel do notebook. Veja o código Python ou os notebooks falham na sessão SSH.
Os ficheiros desaparecem após um reinício do cluster. Verifica se os ficheiros foram armazenados num caminho local efémero. Veja Ficheiros desaparecem ou o ambiente é reposto após o reinício do cluster.
claude ou codex falha ao iniciar. Verifica se o Unity Gateway está ativado e se o teu token e permissões permitem o acesso. Veja Agente de codificação falha ao iniciar.

A ligação SSH falha ou atinge o tempo limite

  • Para classic compute, verifique se o cluster está a correr na interface do workspace.
  • Verifique se a sua rede, VPN e firewall permitem tráfego HTTPS e WebSocket para o domínio do seu espaço de trabalho. O túnel SSH não usa a porta 22. Encaminha todo o tráfego através do mesmo endpoint HTTPS utilizado por outros comandos da CLI do Databricks. Consulte Configurar regras de firewall de nomes de domínio.
  • Se um proxy ou firewall inspecionar o tráfego TLS, verifique se permite o pedido de atualização do WebSocket. Um intermediário que bloqueia ou remove a atualização faz com que a ligação falhe ou expire. Pede ao teu administrador de rede para permitir atualizações do WebSocket para o domínio do teu espaço de trabalho, ou para contornar a inspeção TLS desse domínio.
  • Se te ligares através de um proxy HTTP corporativo, define a HTTPS_PROXY variável de ambiente ou NO_PROXY para contornar o proxy do teu domínio de workspace. O túnel SSH utiliza a mesma configuração de proxy que outros comandos CLI do Databricks. Veja configuração do servidor proxy.
  • Verifique se a sua máquina local tem acesso HTTPS a github.com e release-assets.githubusercontent.com.
  • 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. Veja limitações dos túneis SSH.

code comando 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

  • Inicia sessão no teu espaço de trabalho usando databricks auth login.
  • Para computação clássica, confirma se tens CAN ATTACH TO permissão no cluster, ou CAN RESTART se o cluster não está a funcionar.

O token de atualização é inválido

Se databricks ssh connect falhar com error getting token, invalid_grant, e Refresh token is invalid, o servidor de autorização rejeitou o token de atualização OAuth guardado pela CLI. Inicie sessão novamente para obter uma nova sessão:

  1. Identifique o perfil de configuração do espaço de trabalho a que pretende ligar-se:

    databricks auth profiles --skip-validate

  2. Iniciar sessão novamente com esse perfil. Substitua <workspace-url> pelo URL do espaço de trabalho, sem o /oidc/v1/token caminho, e <profile-name> pelo nome de perfil correspondente:

    databricks auth login --host <workspace-url> --profile <profile-name>

    Conclua o processo de início de sessão no seu navegador.

  3. Tente novamente a ligação com o mesmo perfil:

    databricks ssh connect --ide vscode --profile <profile-name>

    Usa --ide cursor para Cursor, ou omite --ide para uma sessão terminal.

Se o erro persistir, verifica se o comando falhado tem como alvo o mesmo espaço de trabalho e perfil em que acabaste de iniciar sessão. Ver autenticação OAuth utilizador-para-máquina (U2M).

Código Python ou notebooks falham na sessão SSH

Ficheiros desaparecem ou o ambiente é reposto 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?.

O agente de codificação falha ao iniciar

Quando executas claude ou codex, o launcher verifica se consegues aceder ao Unity Gateway antes de ele descarregar as ferramentas do agente. Se não tiveres acesso ao Unity Gateway, os agentes incorporados não conseguem executar. Associe a mensagem de erro à causa:

  • O Unity Gateway não está ativado neste espaço de trabalho: Peça ao administrador do seu espaço de trabalho para ativar o Unity Gateway. Consulte Pré-requisitos.
  • O acesso ao serviço de modelos não pôde ser verificado: Verifique se cumpre os pré-requisitos do Unity Gateway, ou peça ao administrador do seu espaço de trabalho acesso aos modelos.
  • Um passo de instalação falha, por exemplo ✗ Installing Node.js seguido de failed to download: Verifique se a instância de computação consegue alcançar github.com, nodejs.org, pypi.org, files.pythonhosted.org e registry.npmjs.org através de HTTPS. Consulte Requisitos para agentes de programação.

Se claude não for encontrada ou codex não for encontrado, verifique se a sua CLI local do Databricks é a versão 1.23.0 ou superior e depois volte a ligar. Consulte Requisitos para agentes de codificação.

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

A computação serverless requer configuração de SSH?

No. Após instalar e autenticar a CLI Databricks, utilize databricks ssh connect para computação serverless. O databricks ssh setup comando configura entradas de host SSH reutilizáveis para computação dedicada clássica.

O túnel SSH do Databricks requer a porta 22?

No. O túnel SSH transporta tráfego via HTTPS para o domínio do seu espaço de trabalho e requer suporte WebSocket. A sua rede, VPN, firewall e proxy têm de permitir esse tráfego. Veja A ligação SSH falha ou expira.

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 a infraestrutura de computação. Python, o kernel e a execução do código correm no Azure Databricks com acesso aos recursos de computação.

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

O tráfego SSH é encriptado de ponta a ponta, e o código corre na computação do Azure Databricks a que te ligas. A autenticação utiliza a CLI Databricks e o seu perfil de espaço de trabalho configurado. Veja Que métodos de autenticação são suportados?.

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.

Posso usar agentes de codificação numa sessão SSH?

Yes. Numa sessão SSH em computação serverless ou num cluster dedicado, execute claude ou codex. Os agentes usam o Unity Gateway sem qualquer configuração adicional. Veja Como executar agentes de codificação numa sessão SSH.

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. Veja o comportamento do Notebook nas sessões SSH.

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 se desligar, o túnel SSH espera pelo shutdown-delay período (padrão: 10 minutos), depois aplica-se o timeout de inatividade do cluster. Se usares --keep-detached-processes, o cluster não termina automaticamente enquanto processos destacados estão a correr. Isto também se aplica a ligações sem a bandeira que reutilizam um túnel iniciado com ela. Ver Ligações a um túnel existente.

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.

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.

  • Última atualização a