Menyambungkan ke Databricks menggunakan terowongan SSH

Penting

Fitur ini ada di Beta.

Terowongan SSH yang disediakan oleh Databricks memungkinkan Anda mengakses ruang kerja dan menjalankan beban kerja secara interaktif pada komputasi Databricks dari IDEs menggunakan terowongan SSH. Mudah untuk menyiapkan, menghilangkan kebutuhan akan manajemen lingkungan, dan menjaga semua kode dan data tetap aman dalam ruang kerja Databricks Anda.

Persyaratan

Untuk menggunakan terowongan SSH untuk menyambungkan ke komputasi tanpa server atau klasik Databricks, Anda harus memiliki:

  • Databricks CLI versi 1.5.0 atau yang lebih baru diinstal pada komputer lokal Anda dan autentikasi dikonfigurasi. Lihat Menginstal atau memperbarui Databricks CLI.
  • Salah satu hal berikut ini:
    • versi Visual Studio Code: 1.110.0 (Universal) atau lebih tinggi dan ekstensi Remote - SSH (1.0.46+) terinstal.
    • Versi Kursor: 2.6.11 (Universal) atau lebih tinggi.

Untuk menyambungkan ke komputasi GPU tanpa server, fitur Runtime AI harus diaktifkan. Lihat Runtime AI.

Untuk terhubung ke komputasi klasik (khusus, pengguna tunggal):

Menyambungkan ke komputasi tanpa server

Untuk menyambungkan ke komputasi tanpa server, jalankan databricks ssh connect perintah dari terminal dalam IDE Anda. Tidak diperlukan langkah penyiapan terpisah.

Untuk informasi selengkapnya tentang perintah databricks ssh connect, lihat ssh kelompok perintah.

databricks ssh connect

--accelerator Gunakan opsi untuk menyambungkan ke Runtime AI:

databricks ssh connect --accelerator=GPU_1xA10

databricks ssh connect memberi Anda sesi interaktif pada satu simpul. Untuk pekerjaan pelatihan yang berjalan lama atau pelatihan terdistribusi multi-node, kirimkan workload dengan CLI air sebagai gantinya. Lihat AI Runtime CLI.

Setelah menyambungkan, selesaikan menyiapkan lingkungan pengembangan Anda. Lihat proyek terbuka.

Untuk menyambungkan ke komputasi tanpa server dan memulai sesi di Visual Studio Code atau Kursor, gunakan opsi .--ide CLI membuka jendela IDE yang menunjuk ke folder ruang kerja rumah.

databricks ssh connect --ide=vscode

Hubungkan ke komputasi klasik

Untuk menyambungkan ke komputasi klasik, pertama-tama siapkan koneksi SSH, lalu sambungkan menggunakan IDE Anda atau dari terminal.

Menyiapkan koneksi SSH

Nota

Menyiapkan koneksi SSH hanya diperlukan jika Anda tersambung ke komputasi klasik.

Pertama, siapkan terowongan SSH menggunakan perintah databricks ssh konfigurasi. Berikan nama untuk koneksi, misalnya ganti <connection-name> dengan my-connection:

databricks ssh setup --name <connection-name>

CLI meminta Anda untuk memilih kluster. Anda juga dapat menentukannya secara langsung dengan --cluster <cluster-id>:

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

Nota

Untuk pengguna IntelliJ, Databricks merekomendasikan untuk menambahkan --auto-start-cluster=false ke perintah penyiapan dan memulai kluster secara manual sebelum menyambungkan. Ini karena IDE JetBrains memulai semua kluster yang telah dikonfigurasi setiap kali diluncurkan, yang dapat mengakibatkan biaya komputasi tak terduga.

Menyambungkan menggunakan Visual Studio Code atau Kursor

  1. Untuk Visual Studio Code, instal ekstensi SSH Jarak Jauh. Kursor menyertakan ekstensi SSH jarak jauh secara default.

  2. Di menu utama IDE, klik Tampilkan>Palet Perintah. Pilih Remote-SSH: Pengaturan. Atau, pilih Preferensi: Buka Pengaturan Pengguna (JSON) untuk memodifikasi settings.json secara langsung.

  3. Di bawah Remote.SSH: Ekstensi Default (atau remote.SSH.defaultExtensions di settings.json), tambahkan ms-Python.Python dan ms-toolsai.jupyter.

    Jika Anda memodifikasi settings.json:

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

    Nota

    Secara opsional, tingkatkan nilai Remote.SSH: Connect Timeout (atau remote.SSH.connectTimeout in settings.json) untuk mengurangi kemungkinan kesalahan batas waktu lebih lanjut. Batas waktu default adalah 360.

  4. Di Palet Perintah, pilih Remote-SSH: Sambungkan ke Host.

  5. Dari menu drop-down, pilih koneksi yang Anda siapkan di langkah pertama. IDE melanjutkan untuk terhubung di jendela baru.

Menyambungkan menggunakan IDE IntelliJ

  1. Ikuti tutorial server jarak jauh untuk pengaturan.
  2. Pada layar koneksi baru, masukkan:
    • Nama pengguna:root
    • Host: <connection-name>

Menyambungkan menggunakan terminal

ssh <connection-name>

Membuka proyek

Secara bawaan, perintah databricks ssh connect akan terbuka di direktori sementara. Untuk mengakses file ruang kerja, navigasikan ke direktori ruang kerja Anda dari IDE atau terminal:

  • Di Visual Studio Code atau Kursor, dari Palet Perintah (Cmd/Ctrl+Shift+P) pilih Buka Folder dan navigasi ke /Workspace/Users/<your-username>.
  • Dari jendela terminal, ubah direktori Anda: cd /Workspace/Users/<your-username>.

Nota

File di /Workspace, /Volumes, dan /dbfs tetap ada saat kluster di-restart. File di /home, /root, dan jalur lokal lainnya bersifat sementara dan hilang saat memulai ulang.

Jalankan kode (Visual Studio Code atau Cursor)

Untuk menjalankan kode menggunakan terowongan SSH, lingkungan virtual Databricks harus disiapkan. Lingkungan ini mencakup semua pustaka DBR bawaan dan pustaka cakupan komputasi.

  1. Buka Palet Perintah (Cmd/Ctrl+Shift+P) dan pilih Python: Pilih Interpreter.

  2. Pilih pythonEnv-xxx lingkungan virtual dari daftar. Jika Anda menyiapkan dependensi Python dengan flag --base-environment, pilih nama lingkungan virtual yang lebih panjang dari daftar opsi yang tersedia. Jika lingkungan virtual tidak muncul:

    1. Jalankan echo $DATABRICKS_VIRTUAL_ENV dari terminal dalam IDE.

      Contoh output: /local_disk0/.ephemeral_nfs/envs/pythonEnv-xxx/bin/python

    2. Tempelkan output lengkap sebagai jalur penerjemah di Python: Pilih prompt Interpreter.

  3. Buka terminal baru dan lingkungan virtual harus diaktifkan secara otomatis.

  4. Untuk menjalankan notebook Jupyter, pastikan bahwa lingkungan virtual dipilih sebagai kernel. Klik Pilih Kernel di kanan atas buku catatan.

Jalankan dan men-debug berkas Python dan notebook .ipynb menggunakan ekstensi Python dan Jupyter standar.

Untuk menggunakan Spark dalam file Python pada komputasi tanpa server, inisialisasi sesi secara eksplisit:

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

Mengelola dependensi

Kelola dependensi menggunakan lingkungan dasar ruang kerja, pustaka kluster, skrip init, atau notebook, tergantung pada jenis dan persyaratan komputasi Anda.

Lingkungan dasar ruang kerja (direkomendasikan untuk serverless dan AI Runtime)

Nota

Fitur ini mengharuskan dukungan lingkungan dasar ruang kerja Tanpa Server dalam pratinjau Pekerjaan diaktifkan. Lihat Kelola Pratinjau Azure Databricks.

Gunakan lingkungan dasar ruang kerja dengan lingkungan tanpa server versi 4 atau di bawah ini untuk mengonfigurasi dependensi Python sebelumnya. Buat lingkungan dasar menggunakan UI workspace atau perintah databricks environments create-workspace-base-environment.

Tentukan lingkungan menggunakan --base-environment opsi saat menyambungkan:

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

Untuk informasi selengkapnya tentang format yang diterima, lihat databricks ssh connect.

Pustaka kluster (direkomendasikan untuk komputasi klasik)

Instal dependensi menggunakan UI ruang kerja di bawah Pustaka Komputasi>. Ini bertahan selama seluruh proses memulai ulang kluster dan tersedia di pythonEnv-xxx. Lihat Pustaka kluster.

Ketergantungan non-Python

Untuk mempertahankan dependensi non-Python, gunakan skrip init yang menginstal paket saat komputasi dimulai. Secara opsional, simpan paket dalam volume Katalog Unity dan referensikan dari skrip init. Lihat Apa itu skrip init?.

penyiapan notebook khusus Project

Untuk dependensi cakupan proyek, jalankan notebook dengan berisi perintah %pip install pada awal setiap sesi.

# 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 perintah mencakup pagar pembatas khusus Databricks dan menyebarluaskan dependensi ke simpul eksekutor Spark. Ini memungkinkan fungsi yang ditentukan pengguna (UDF) dengan dependensi kustom.

Untuk contoh selengkapnya, lihat Mengelola pustaka dengan %pip perintah.

Anda tidak perlu menjalankan kembali buku catatan jika sesi tersambung kembali dalam waktu 10 menit. Ini dapat dikonfigurasi menggunakan -shutdown-delay dalam konfigurasi SSH Anda.

Nota

Beberapa sesi SSH pada kluster yang sama berbagi satu lingkungan virtual.

Menggunakan Git

Nota

Fitur ini mengharuskan dukungan Git CLI untuk pratinjau folder Git diaktifkan. Lihat Kelola Pratinjau Azure Databricks.

Anda dapat menggunakan Git CLI di terowongan SSH dengan folder Git yang baru dibuat dan kredensial Git yang telah Anda konfigurasi di ruang kerja Databricks. Lihat Menggunakan perintah Git CLI.

Jika CLI meminta kredensial alih-alih mengambilnya secara otomatis, Anda harus menghubungkan penyedia Git Anda ke Databricks. Lihat Menyambungkan penyedia Git Anda ke Databricks.

Keterbatasan

Terowongan SSH yang disediakan oleh Databricks memiliki batasan berikut:

  • Kluster bersama tidak didukung.
  • Ekstensi Databricks untuk Visual Studio Code dan terowongan SSH belum kompatibel dan tidak boleh digunakan bersama-sama.
  • File yang diedit di luar /Workspace, /Volumes, dan /dbfs hilang saat menghidupkan ulang kluster.
  • Maksimum 10 koneksi SSH diizinkan per kluster.
  • Sesi yang tidak aktif dapat terputus setelah 1 jam.
  • Terowongan SSH tidak dapat diluncurkan dari lingkungan jarak jauh atau kontainer Docker lainnya.
  • Anda mungkin mengalami masalah performa atau koneksi saat tiga atau beberapa notebook Jupyter terbuka secara bersamaan. Batasan ini akan ditangani dalam rilis mendatang.

Perbedaan Notebook Databricks

Ada beberapa perbedaan dalam notebook saat menggunakan terowongan SSH:

  • File Python tidak menentukan databricks global apa pun (seperti spark atau dbutils). Anda harus mengimpornya secara eksplisit dengan from databricks.sdk.runtime import spark.
  • Untuk buku catatan ipynb, fitur-fitur ini tersedia:
    • Databricks globals: display, displayHTML, dbutils, table, sqludf, getArgument, sc, sqlContext, spark
    • %sql perintah magic untuk menjalankan sel SQL

Untuk bekerja dengan sumber Python "notebooks":

  • Cari jupyter.interactiveWindow.cellMarker.codeRegex dan atur ke:

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

  • Cari jupyter.interactiveWindow.cellMarker.default dan atur ke:

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

Troubleshooting

Bagian ini berisi informasi tentang mengatasi masalah umum.

Koneksi SSH gagal atau kehabisan waktu

  • Pastikan kluster sedang berjalan di antarmuka ruang kerja.
  • Periksa apakah port keluar 22 terbuka dan diizinkan di laptop, jaringan, dan VPN Anda.
  • Tingkatkan batas waktu SSH. Lihat Menyambungkan menggunakan Visual Studio Code atau Kursor.
  • Untuk kesalahan ketidakcocokan kunci, hapus ~/.databricks/ssh-tunnel-keys dan jalankan databricks ssh setupkembali .
  • Untuk kesalahan "identifikasi host jarak jauh telah berubah", periksa ~/.ssh/known_hosts file dan hapus entri yang terkait dengan kluster Anda.
  • Sesi SSH mungkin turun setelah 1 jam dan tidak lebih dari 10 koneksi SSH dapat dilakukan ke satu kluster. Lihat Batasan.

Perintah code tidak ditemukan

Jika Anda melihat Error: exec: "code": executable file not found in $PATH, buka Palet Perintah (Cmd/Ctrl+Shift+P), pilih Perintah Shell: Instal perintah 'kode' di PATH, dan mulai ulang SESI IDE atau terminal Anda.

Kesalahan autentikasi CLI

  • Konfirmasikan profil Databricks CLI Anda valid menggunakan databricks auth login.
  • Konfirmasikan bahwa Anda memiliki CAN MANAGE izin pada kluster.

Kode saya tidak berfungsi

File terhapus atau pengaturan lingkungan direset setelah kluster dimulai ulang

  • File di /Workspace, /Volumes, dan /dbfs mount bertahan selama klaster melakukan restart. File di /home, /root, dan jalur lokal lainnya bersifat sementara dan hilang saat memulai ulang.
  • Gunakan manajemen pustaka kluster untuk dependensi persisten. Mengotomatiskan instalasi ulang menggunakan skrip init jika diperlukan. Lihat Apa itu skrip init?.

Penyiapan SSH gagal pada Windows (WSL)

Jalankan databricks ssh setup langsung di Windows, bukan dalam WSL. Instans Windows Visual Studio Code tidak dapat menemukan konfigurasi SSH yang dibuat di sisi WSL.

FAQ

Apa perbedaan terowongan SSH dengan Databricks Connect?

Databricks Connect memungkinkan Anda menulis kode menggunakan API Spark dan menjalankannya dari jarak jauh pada komputasi Databricks alih-alih dalam sesi Spark lokal. Ekstensi Databricks Visual Studio Code menggunakan Databricks Connect untuk menyediakan debugging kode pengguna yang terintegrasi di Databricks.

Terowongan SSH memungkinkan Anda mengakses ruang kerja dari IDE Anda dan memindahkan seluruh lingkungan pengembangan Anda ke komputasi — Python, kernel, dan semua eksekusi berjalan di Databricks dengan akses penuh ke sumber daya komputasi.

Bagaimana kode dan data saya diamankan?

Semua kode berjalan dalam VPC cloud Databricks Anda. Tidak ada data atau kode yang meninggalkan lingkungan aman Anda. Lalu lintas SSH sepenuhnya dienkripsi.

Platform IDE apa yang didukung?

Visual Studio Code dan Kursor secara resmi didukung. IDE apa pun dengan kemampuan SSH kompatibel, tetapi hanya Visual Studio Code dan Kursor yang diuji.

Apakah semua fitur notebook Databricks tersedia dari IDE?

Beberapa fitur seperti display(), dbutils, dan %sql tersedia dengan batasan atau penyiapan manual. Lihat Perbedaan Notebook Databricks.

Apakah kluster saya akan dimulai secara otomatis saat saya tersambung menggunakan terowongan SSH?

Ya, tetapi jika diperlukan waktu lebih lama untuk memulai kluster daripada batas waktu koneksi, upaya koneksi akan gagal. Untuk mencegah hal ini, tingkatkan nilai Remote.SSH: Sambungkan Batas Waktu dari palet perintah (atau remote.SSH.connectTimeout di settings.json) untuk lebih mengurangi kemungkinan kesalahan waktu habis.

Bagaimana cara mengetahui apakah kluster saya berjalan?

Navigasi ke Komputasi di UI ruang kerja Databricks, dan periksa status kluster. Kluster harus menunjukkan Berjalan agar koneksi SSH berfungsi.

Bagaimana cara memutuskan sambungan sesi SSH/IDE saya?

Anda dapat memutuskan sesi dengan menutup jendela IDE Anda, menggunakan opsi Putuskan sambungan di IDE Anda, menutup terminal SSH Anda, atau menjalankan exit perintah di terminal.

Bagaimana cara menghentikan cluster dan menghindari tagihan saat saya tidak bekerja?

Untuk segera berhenti, hentikan kluster dari UI ruang kerja. Navigasi ke Komputasi di UI ruang kerja Databricks, temukan kluster Anda, dan klik Hentikan atau Hentikan.

Tetapkan kebijakan penghentian otomatis singkat pada kluster Anda dari antarmuka pengguna ruang kerja. Setelah Anda memutuskan sambungan, server SSH menunggu periode waktu tertentu shutdown-delay (bawaan: 10 menit), kemudian batas waktu tidak aktif kluster berlaku.

Bagaimana cara menangani dependensi persisten?

Dependensi yang diinstal selama sesi hilang setelah mulai ulang kluster. Gunakan penyimpanan persisten (/Workspace/Users/<your-username>) untuk persyaratan dan skrip penyiapan. Gunakan pustaka kluster atau skrip init untuk otomatisasi.

Metode autentikasi apa yang didukung?

Autentikasi menggunakan Databricks CLI dan file profil Anda ~/.databrickscfg . Kunci SSH ditangani oleh terowongan SSH.

Bisakah saya menyambungkan ke database atau layanan eksternal dari kluster?

Ya, selama jaringan klaster Anda memungkinkan koneksi keluar dan Anda memiliki pustaka yang diperlukan.

Dapatkah saya menggunakan ekstensi IDE tambahan?

Sebagian besar ekstensi berfungsi saat diinstal dalam sesi SSH jarak jauh Anda, tergantung pada IDE dan kluster Anda. Visual Studio Code secara default tidak menginstal ekstensi lokal pada host jarak jauh. Anda dapat menginstalnya secara manual dengan membuka panel ekstensi dan mengaktifkan ekstensi lokal Anda di host jarak jauh. Anda juga dapat mengonfigurasi Visual Studio Code untuk selalu menginstal ekstensi tertentu dari jarak jauh. Lihat Menyambungkan ke Databricks.

Ya, namun admin ruang kerja harus memasukkan URL Visual Studio Code dan marketplace ekstensi Cursor ke daftar yang diizinkan. Komputer lokal Anda juga harus memiliki kemampuan untuk mengakses internet.

  • Last updated on