databricks-execution-compute

Databricks 执行与计算

在 Databricks 上运行代码。三种执行模式——根据工作负载选择。以下示例均使用 Databricks CLI；安装和身份验证请参阅 databricks-core 技能。

执行模式决策矩阵

方面	Databricks Connect ⭐	Serverless Job	Interactive Cluster
适用于	Spark 代码（ETL、数据生成）	大量计算（ML）	在多次工具调用间保留状态、Scala/R
启动时间	即时	冷启动约 25-50s	停止后约 5min
状态	在 Python 进程内	无	通过 context_id
语言	Python（PySpark）	Python、SQL	Python、Scala、SQL、R
依赖项	withDependencies()	配置 environments 的 CLI	在集群上安装

决策流程

主要决策点：如果你正在使用 Declarative Automation Bundles（DABs），请先按照 databricks-dabs 技能中的说明操作。简而言之，你可以使用 databricks bundle run 运行与作业、管道和其他资源关联的代码。可通过检查项目根目录中是否存在 databricks.yml 文件来识别。如果这些资源不存在，或者你没有使用 DABs，请继续阅读以下内容。

对于所有基于 Spark 的工作负载，优先使用 Databricks Connect，其次使用 serverless。

Spark-based code? → Databricks Connect (fastest)
  └─ Python 3.12 missing? → Install it + databricks-connect
  └─ Install fails? → Ask user (don't auto-switch modes)

Heavy/long-running (ML)? → Serverless Job (independent)
Need state across calls? → Interactive Cluster (list and ask which one to use)
Scala/R? → Interactive Cluster (list and ask which one to use)

如何运行代码

继续之前，请阅读所选模式的参考文件。

Databricks Connect（在本地运行，纯 Spark 代码时优先使用）→ 参考

from databricks.connect import DatabricksSession
...
spark = DatabricksSession.builder.profile("my-local-profile").serverless(True).getOrCreate()


python my_spark_script.py

Serverless Job → 参考

纯 CLI 流程：将本地文件上传为工作区笔记本，使用 databricks jobs submit 提交一次性运行（一次调用即可创建并运行，临时执行——不会在 Jobs UI 中留下条目，也不会重试），然后轮询并获取结果。本地文件必须是 Databricks 源代码笔记本——首行应为 # Databricks notebook source（Python）或 -- Databricks notebook source（SQL）。

1. 将本地文件上传为工作区笔记本。 TARGET_PATH 是位置参数；--file 是本地路径。

databricks workspace import /Workspace/Users/<user>/.ai_dev_kit/train --file /local/path/to/train.py --format SOURCE --language PYTHON --overwrite

2. 提交运行。 使用 --no-wait 可立即返回 {"run_id": N}；省略该参数则会阻塞，直到运行终止。安装 dependencies 必须使用 "client": "4"（"1" 会静默忽略这些依赖）。

databricks jobs submit --no-wait --json @submit.json

{
  "run_name": "train-run",
  "tasks": [{
    "task_key": "main",
    "notebook_task": {"notebook_path": "/Workspace/Users/<user>/.ai_dev_kit/train"},
    "environment_key": "ml_env"
  }],
  "environments": [{
    "environment_key": "ml_env",
    "spec": {"client": "4", "dependencies": ["scikit-learn==1.5.2", "mlflow==2.22.0"]}
  }]
}

3. 检查状态／等待完成。 生命周期：PENDING → RUNNING → TERMINATED（或 SKIPPED／INTERNAL_ERROR）。只有生命周期状态为 TERMINATED 后，才能读取 .state.result_state（SUCCESS／FAILED／CANCELED）。

databricks jobs get-run <RUN_ID> | jq '{state: .state.life_cycle_state, result: .state.result_state, duration_ms: .execution_duration, url: .run_page_url, task_run_id: .tasks[0].run_id}'

4. 获取输出／错误。 注意：get-run-output 接受的是任务的 run_id（.tasks[0].run_id），而不是提交时返回的父级 run_id。notebook_output.result 是传递给 dbutils.notebook.exit() 的字符串。

databricks jobs get-run-output <TASK_RUN_ID> | jq '{result: .notebook_output.result, error, error_trace}'

始终在笔记本中使用 dbutils.notebook.exit(<string>)——get-run-output 不会捕获 print() 的内容。对于 JSON 结果，使用 dbutils.notebook.exit(json.dumps({...}))，然后在客户端解析 .notebook_output.result。

交互式集群 → 参考

默认情况下避免使用——优先选择 Serverless Job。 只有在以下情况下才使用交互式集群：

• 已有正在运行且可用的经典集群，或
• 需要通过执行上下文，在多次调用之间进行实时、有状态的执行（例如调试），或
• 用户明确要求使用。

交互式集群启动缓慢（3-8 分钟），运行期间还会产生费用。不要在未明确要求时启动。

CLI 命令一览

所有计算生命周期和代码执行操作都通过 Databricks CLI 进行。主要命令：

操作	命令
将本地文件上传为工作区笔记本	databricks workspace import <WORKSPACE_PATH> --file <LOCAL> --format SOURCE --language PYTHON --overwrite
运行无服务器代码（上传 + 提交 + 等待）	databricks jobs submit --json @submit.json（参见上文的 Serverless Job 部分；异步运行时使用 --no-wait）
获取运行状态 / 等待	databricks jobs get-run <RUN_ID>（轮询 .state.life_cycle_state）
获取运行输出	databricks jobs get-run-output <TASK_RUN_ID>
列出集群	databricks clusters list --output json
获取集群详情	databricks clusters get <CLUSTER_ID>
启动 / 重启 / 终止集群	databricks clusters start/restart/delete <CLUSTER_ID>
永久删除集群	databricks clusters permanent-delete <CLUSTER_ID>
创建集群	databricks clusters create --json '{...}'（参见 3-interactive-cluster.md）
列出节点类型 / Spark 版本	databricks clusters list-node-types / databricks clusters spark-versions
在正在运行的集群上执行代码	databricks api post /api/1.2/contexts/create + databricks api post /api/1.2/commands/execute（参见 3-interactive-cluster.md）
SQL 仓库	databricks warehouses create/list/get/start/stop/edit/delete（参见下文的 SQL Warehouses）

SQL 仓库

所有需要 ID 的命令都使用位置参数（不使用 --id 标志）。使用 databricks warehouses list 查找 ID。

# Create a serverless SQL warehouse. min_num_clusters + max_num_clusters are REQUIRED
# (the server rejects the default 0). Keep the aidevkit_project tag for resource tracking.
databricks warehouses create --json '{
  "name": "my-warehouse",
  "cluster_size": "Small",
  "enable_serverless_compute": true,
  "auto_stop_mins": 10,
  "min_num_clusters": 1,
  "max_num_clusters": 1,
  "tags": {"custom_tags": [{"key": "aidevkit_project", "value": "ai-dev-kit"}]}
}'

# List / find — trim to id, name, state with jq
databricks warehouses list -o json | jq '.[] | {id, name, state, size: .cluster_size}'

# Find by name
databricks warehouses list -o json | jq '.[] | select(.name == "my-warehouse")'

# Get one warehouse's full config
databricks warehouses get <WAREHOUSE_ID>

# Start / stop (both are LROs; add --no-wait to return immediately)
databricks warehouses start <WAREHOUSE_ID>
databricks warehouses stop  <WAREHOUSE_ID>

# Resize / reconfigure — pass the FULL desired config (omitted fields revert to defaults,
# so always re-state min_num_clusters/max_num_clusters). Use --no-wait if the warehouse
# is STOPPED, otherwise edit blocks trying to reach RUNNING and errors out (the mutation
# itself still applies). When the warehouse is already RUNNING, --no-wait is optional.
databricks warehouses edit <WAREHOUSE_ID> --no-wait --json '{
  "name": "my-warehouse",
  "cluster_size": "Medium",
  "enable_serverless_compute": true,
  "auto_stop_mins": 15,
  "min_num_clusters": 1,
  "max_num_clusters": 1
}'

# Delete (irreversible)
databricks warehouses delete <WAREHOUSE_ID>

规格： 2X-Small、X-Small、Small、Medium、Large、X-Large、2X-Large、3X-Large、4X-Large。类型： 在 JSON 请求体中设置 "warehouse_type": "PRO"（默认值）或 "CLASSIC"。

相关技能

• databricks-synthetic-data-gen — 使用 Spark + Faker 生成数据
• databricks-jobs — 生产作业编排
• databricks-dbsql — SQL 仓库和 AI 函数