Back to Details

databricks-ml-training

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ML Training on Databricks

在Databricks上进行机器学习训练

FIRST: Use the parent 
databricks-core
skill for CLI basics, authentication, and profile selection.
Train with MLflow → register to Unity Catalog → consume the same artifact as either a batch Spark UDF over Delta or (when low-latency is required) a real-time serving endpoint.
Always train on Databricks (serverless job or notebook), never in the local Python process the agent is running in. Local training has no access to the silver tables, no MLflow tracking server, no UC registry path, and dies if the chat session drops — submit 
databricks jobs submit --no-wait
(see "Train + deploy as a serverless job" below). Only fall back to local execution if the user explicitly asks for it.
If you need to deploy a real time model serving endpoint after the model is registered (creating endpoints, traffic config, version-swapping, querying, Foundation Model API endpoints), see databricks-model-serving.
ConsumptionWhenHow
Batch UDFDashboards, daily/hourly scores, predictions read by Genie/Dashboards or an app (often synced to a Lakebase table)
mlflow.pyfunc.spark_udf(...)
→ 
INSERT INTO gold_predictions
. If the model was logged with 
fe.log_model(training_set=...)
, use 
fe.score_batch()
instead — see the Feature Engineering section below.
Real-time endpointScore on a user action (fraud at authorization, rec at page load) — sub-100ms
mlflow.deployments.get_deploy_client()
(classical) / 
agents.deploy()
(agents). Endpoint lifecycle: see databricks-model-serving.
注意事项：请先使用父技能
databricks-core
掌握CLI基础操作、身份验证和配置文件选择。
通过MLflow训练模型 → 注册到Unity Catalog → 将同一工件用作Delta上的批量Spark UDF，或在需要低延迟时用作实时服务端点。
务必在Databricks上训练模型（无服务器作业或笔记本），切勿在代理运行的本地Python进程中训练。本地训练无法访问银表、没有MLflow跟踪服务器、没有UC注册路径，且聊天会话中断时训练会终止——请提交
databricks jobs submit --no-wait
（见下文“以无服务器作业形式训练并部署”）。仅当用户明确要求时，才考虑本地执行。
如果需要在模型注册后部署实时模型服务端点（创建端点、流量配置、版本切换、查询、基础模型API端点），请查看databricks-model-serving。
消费方式使用场景实现方式
批量UDF仪表板、每日/每小时评分、供Genie/仪表板或应用读取的预测结果（通常同步到Lakebase表）
mlflow.pyfunc.spark_udf(...)
→ 
INSERT INTO gold_predictions
。如果模型是通过
fe.log_model(training_set=...)
记录的，请改用
fe.score_batch()
——详见下文特征工程（特征存储与Feature Views）部分。
实时端点用户操作时进行评分（授权时的欺诈检测、页面加载时的推荐）——延迟低于100毫秒
mlflow.deployments.get_deploy_client()
（传统机器学习）/ 
agents.deploy()
（代理）。端点生命周期：请查看databricks-model-serving。

Default Canonical flow

标准流程

silver_<features>  +  silver_<labels>
        ▼
   notebook (as a serverless job):
   ├── train with mlflow.autolog (XGBoost / sklearn / etc.)
   ├── mlflow.register_model → UC: {catalog}.{schema}.{model}
   ├── set_registered_model_alias(name, "prod", version)
   └── spark_udf(@prod) over latest features → MERGE into gold_predictions
        ▼
gold_<entity>_predictions   ◄── dashboards, apps, Genie read this
Feature-store-backed models diverge here. If training used 
fe.log_model(training_set=...)
, replace 
spark_udf(@prod)
with 
fe.score_batch(model_uri, df=<keys_only>)
— it auto-joins features via the model's registered feature lineage. See the Feature Engineering section below.
One notebook, one artifact. Re-running = retraining. Gold is where truth lives — read paths never call the model directly. Keep label-window logic (
failure occurred within 7 days
) in the notebook during dev; once stable, promote to a silver materialized view in SDP.
silver_<features>  +  silver_<labels>
        ▼
   笔记本（作为无服务器作业）：
   ├── 使用mlflow.autolog训练（XGBoost / sklearn / 等）
   ├── mlflow.register_model → UC: {catalog}.{schema}.{model}
   ├── set_registered_model_alias(name, "prod", version)
   └── 在最新特征上运行spark_udf(@prod) → MERGE到gold_predictions
        ▼
gold_<entity>_predictions   ◄── 仪表板、应用、Genie读取该表
基于特征存储的模型流程有所不同。如果训练使用了
fe.log_model(training_set=...)
，请将
spark_udf(@prod)
替换为
fe.score_batch(model_uri, df=<keys_only>)
——它会通过模型注册的特征谱系自动关联特征。详见下文特征工程（特征存储与Feature Views）部分。
一个笔记本对应一个工件。重新运行即重新训练。Gold表是结果的唯一可信来源——读取路径从不直接调用模型。开发阶段将标签窗口逻辑（如“7天内发生故障”）放在笔记本中；稳定后，将其升级为SDP中的银物化视图。

Train and register (the 90% case)

训练与注册（90%的通用场景）

mlflow.autolog()
captures params, metrics, code, and the model artifact for every run; 
registered_model_name=...
auto-registers the best run to UC (auto-incremented version). Wrap training with Optuna so each trial is a child run and the best one is what gets registered.
Always 
mlflow.set_registry_uri("databricks-uc")
 — without it, models land in the deprecated workspace registry. The experiment's parent folder must exist — 
set_experiment
does NOT auto-create it (fails with 
NOT_FOUND: Parent directory does not exist
). Pre-create it once with 
databricks workspace mkdirs
before the job runs.
bash
undefined
mlflow.autolog()
会捕获每次运行的参数、指标、代码和模型工件；
registered_model_name=...
会自动将最佳运行结果注册到UC（版本自动递增）。用Optuna包裹训练过程，这样每个试验都是子运行，最终注册的是最佳试验结果。
务必先执行
mlflow.set_registry_uri("databricks-uc")
——否则模型会存入已弃用的工作区注册表。实验的父文件夹必须预先存在——
set_experiment
不会自动创建文件夹（会报错
NOT_FOUND: Parent directory does not exist
）。请在作业运行前，通过
databricks workspace mkdirs
预先创建一次。
bash
undefined

Once per project — create the parent folder for the MLflow experiment.

每个项目执行一次——为MLflow实验创建父文件夹。

databricks workspace mkdirs /Users/me@example.com/turbine_project

Use the Databricks notebook source format (`# Databricks notebook source` header, `# COMMAND ----------` separators, `# MAGIC %md`/`%sql` magics for markdown/SQL cells):

```python
databricks workspace mkdirs /Users/me@example.com/turbine_project

使用Databricks笔记本源格式（包含`# Databricks notebook source`头部、`# COMMAND ----------`分隔符、用于Markdown/SQL单元格的`# MAGIC %md`/`%sql`魔法命令）：

```python

Databricks notebook source

Databricks notebook source

MAGIC %md

MAGIC %md

MAGIC # Turbine failure prediction

MAGIC # 涡轮机故障预测

MAGIC

MAGIC

MAGIC Train an XGBoost classifier on engineered turbine telemetry features.

MAGIC 基于涡轮机遥测特征训练XGBoost分类器。

MAGIC ## Data exploration

MAGIC ## 数据探索

COMMAND ----------

COMMAND ----------

(basic data exploration — class balance, schema sanity, etc.)

—

COMMAND ----------

—

MAGIC %md

—

MAGIC ## Training the model

—

COMMAND ----------

—
import mlflow, mlflow.xgboost, optuna from mlflow.tracking import MlflowClient from xgboost import XGBClassifier from sklearn.metrics import roc_auc_score
mlflow.set_registry_uri("databricks-uc") mlflow.set_experiment("/Users/me@example.com/turbine_project/mlflow_experiment")
CATALOG, SCHEMA, NAME = "ai_demo_gen", "wind_farm", "turbine_failure" FULL_NAME = f"{CATALOG}.{SCHEMA}.{NAME}"
#（基础数据探索——类别平衡、架构合理性等）

Autolog WITHOUT registered_model_name — otherwise every Optuna trial registers a new UC

COMMAND ----------

version, and a max-by-version pick lands on the last trial to finish, not the best one.

MAGIC %md

—

MAGIC ## 模型训练

—

COMMAND ----------

mlflow.xgboost.autolog(log_input_examples=True)
import mlflow, mlflow.xgboost, optuna from mlflow.tracking import MlflowClient from xgboost import XGBClassifier from sklearn.metrics import roc_auc_score
mlflow.set_registry_uri("databricks-uc") mlflow.set_experiment("/Users/me@example.com/turbine_project/mlflow_experiment")
CATALOG, SCHEMA, NAME = "ai_demo_gen", "wind_farm", "turbine_failure" FULL_NAME = f"{CATALOG}.{SCHEMA}.{NAME}"

For imbalanced labels: stratify the split, set scale_pos_weight = neg/pos.

自动记录时不要设置registered_model_name——否则每个Optuna试验都会注册一个新的UC版本，最终按版本最大值选择的会是最后完成的试验，而非最佳试验。

def objective(trial): params = { "n_estimators": trial.suggest_int("n_estimators", 100, 400), "max_depth": trial.suggest_int("max_depth", 3, 10), "learning_rate": trial.suggest_float("learning_rate", 0.01, 0.3, log=True), } with mlflow.start_run(nested=True): m = XGBClassifier(**params).fit(X_train, y_train) return roc_auc_score(y_test, m.predict_proba(X_test)[:, 1])
with mlflow.start_run(run_name="hpo") as parent: study = optuna.create_study(direction="maximize") study.optimize(objective, n_trials=20)
mlflow.xgboost.autolog(log_input_examples=True)

COMMAND ----------

针对不平衡标签：分层拆分数据集，设置scale_pos_weight = 负样本数/正样本数。

MAGIC %md

—

MAGIC ## Retrain best params and register

—

COMMAND ----------

—

Retrain on the winning trial's params explicitly, then register that single model.

—
with mlflow.start_run(run_name="best"): best = XGBClassifier(**study.best_params).fit(X_train, y_train) mlflow.log_metric("val_auc", study.best_value) info = mlflow.xgboost.log_model(best, name="model", registered_model_name=FULL_NAME)
def objective(trial): params = { "n_estimators": trial.suggest_int("n_estimators", 100, 400), "max_depth": trial.suggest_int("max_depth", 3, 10), "learning_rate": trial.suggest_float("learning_rate", 0.01, 0.3, log=True), } with mlflow.start_run(nested=True): m = XGBClassifier(**params).fit(X_train, y_train) return roc_auc_score(y_test, m.predict_proba(X_test)[:, 1])
with mlflow.start_run(run_name="hpo") as parent: study = optuna.create_study(direction="maximize") study.optimize(objective, n_trials=20)

Stages are deprecated — UC uses movable aliases. Repoint @prod at the version we just registered.

COMMAND ----------

—

MAGIC %md

—

MAGIC ## 使用最佳参数重新训练并注册

—

COMMAND ----------

—

根据最优试验的参数显式重新训练，然后注册该单一模型。

client = MlflowClient(registry_uri="databricks-uc") client.set_registered_model_alias(FULL_NAME, "prod", info.registered_model_version)

**Framework autolog**: `mlflow.{sklearn,xgboost,lightgbm,pytorch,tensorflow,spark}.autolog()`.

**Aliases, not stages**: UC dropped `Staging`/`Production`. Use movable `@prod`/`@challenger`; load with `models:/{full_name}@prod`. Promoting a new version is one `set_registered_model_alias` call.

---
with mlflow.start_run(run_name="best"): best = XGBClassifier(**study.best_params).fit(X_train, y_train) mlflow.log_metric("val_auc", study.best_value) info = mlflow.xgboost.log_model(best, name="model", registered_model_name=FULL_NAME)

Consume: batch scoring over Delta

Stage已被弃用——UC使用可移动别名。将@prod指向我们刚注册的版本。

The cheap, default path for models NOT backed by feature tables. Load the registered model as a Spark UDF and score a Delta table; write predictions to a gold table that downstream consumers read. For feature-store-backed models (logged with 
fe.log_model(training_set=...)
), skip 
spark_udf
entirely and use 
fe.score_batch()
— see the Feature Engineering section.
python
undefined
client = MlflowClient(registry_uri="databricks-uc") client.set_registered_model_alias(FULL_NAME, "prod", info.registered_model_version)

**框架自动记录**：`mlflow.{sklearn,xgboost,lightgbm,pytorch,tensorflow,spark}.autolog()`。

**使用别名而非Stage**：UC已弃用`Staging`/`Production`。使用可移动的`@prod`/`@challenger`别名；通过`models:/{full_name}@prod`加载模型。只需调用一次`set_registered_model_alias`即可升级新版本。

---

COMMAND ----------

消费：基于Delta的批量评分

MAGIC %md

—

MAGIC ## Score and save to a gold predictions table

—

COMMAND ----------

—
import mlflow from pyspark.sql import functions as F
这是非特征表支持模型的低成本默认路径。将注册模型加载为Spark UDF，对Delta表进行评分；将预测结果写入Gold表供下游消费者读取。对于特征存储支持的模型（通过
fe.log_model(training_set=...)
记录），请完全跳过
spark_udf
，改用
fe.score_batch()
——详见下文特征工程（特征存储与Feature Views）部分。
python
undefined

env_manager rules:

COMMAND ----------

"local" → same runtime as training (same notebook/job). Fastest, default in dev/demo.

MAGIC %md

"virtualenv"→ different runtime than training; rebuilds the model's env.

MAGIC ## 评分并保存到Gold预测表

"uv" → same as virtualenv but faster (MLflow ≥ 2.22).

COMMAND ----------

predict = mlflow.pyfunc.spark_udf( spark, model_uri=f"models:/{FULL_NAME}@prod", env_manager="local", )
features = spark.table(f"{CATALOG}.{SCHEMA}.silver_turbine_features_latest") feature_cols = [c for c in features.columns if c != "turbine_id"] # exclude the join key scored = features.withColumn("risk_score", predict(*[features[c] for c in feature_cols]))
import mlflow from pyspark.sql import functions as F

Overwrite-per-run pattern for "latest score per entity":

env_manager规则：

—

"local" → 与训练使用相同的运行时（同一笔记本/作业）。速度最快，是开发/演示的默认选项。

—

"virtualenv"→ 与训练使用不同的运行时；会重新构建模型的环境。

—

"uv" → 与virtualenv功能相同，但速度更快（要求MLflow ≥ 2.22）。

scored.select("turbine_id", "risk_score", F.current_timestamp().alias("scored_at"))
.write.mode("overwrite").saveAsTable(f"{CATALOG}.{SCHEMA}.gold_turbine_predictions")

For incremental scoring with history, MERGE into the predictions table instead of overwrite.

---
predict = mlflow.pyfunc.spark_udf( spark, model_uri=f"models:/{FULL_NAME}@prod", env_manager="local", )
features = spark.table(f"{CATALOG}.{SCHEMA}.silver_turbine_features_latest") feature_cols = [c for c in features.columns if c != "turbine_id"] # 排除连接键 scored = features.withColumn("risk_score", predict(*[features[c] for c in feature_cols]))

Real-time serving (when required)

针对“每个实体的最新评分”使用每次运行覆盖模式：

After registering a model to UC, deploy it behind a Model Serving endpoint. The dev-side call is 
mlflow.deployments.get_deploy_client("databricks").create_endpoint(...)
for classical ML or 
agents.deploy(...)
for 
ResponsesAgent
s. First deploy is ~5 min for classical ML.
For endpoint create / update / version-swap, traffic config, AI Gateway, querying, the 
state.ready
+ 
state.config_update
two-field readiness check, and Foundation Model API endpoints, see databricks-model-serving.
scored.select("turbine_id", "risk_score", F.current_timestamp().alias("scored_at"))
.write.mode("overwrite").saveAsTable(f"{CATALOG}.{SCHEMA}.gold_turbine_predictions")

如果需要增量评分并保留历史记录，请使用MERGE到预测表，而非覆盖。

---

Train + deploy as a serverless job

实时服务（必要时使用）

Training notebooks run a few minutes (Optuna + UC register; endpoint warmup adds 5–15 min if you also deploy). Submit as a serverless one-time run so the CLI doesn't block. The notebook ends with 
dbutils.notebook.exit(json.dumps({...}))
so the structured result (
model_version
, 
val_auc
, 
endpoint_name
) reaches 
.notebook_output.result
.
bash
undefined
将模型注册到UC后，在Model Serving端点后部署模型。开发端调用方式为：传统机器学习使用
mlflow.deployments.get_deploy_client("databricks").create_endpoint(...)
，
ResponsesAgent
使用
agents.deploy(...)
。首次部署传统机器学习模型约需5分钟。
关于端点创建/更新/版本切换、流量配置、AI网关、查询、
state.ready
+ 
state.config_update
双字段就绪检查以及基础模型API端点，请查看**databricks-model-serving**。

1. Upload the training notebook

以无服务器作业形式训练并部署

databricks workspace import /Workspace/Users/me@example.com/turbine_project/train
--file ./train_notebook.py --format SOURCE --language PYTHON --overwrite
训练笔记本运行时间通常为几分钟（Optuna + UC注册；如果同时部署端点，预热需额外5–15分钟）。请提交为无服务器一次性运行，这样CLI不会阻塞。笔记本需以
dbutils.notebook.exit(json.dumps({...}))
结尾，以便结构化结果（
model_version
、
val_auc
、
endpoint_name
）能传递到
.notebook_output.result
。
bash
undefined

2. Submit as serverless one-time run (returns {"run_id": N} immediately with --no-wait)

1. 上传训练笔记本

RUN_ID=$(databricks jobs submit --no-wait --json '{ "run_name": "turbine-train-and-deploy", "tasks": [{ "task_key": "train", "notebook_task": {"notebook_path": "/Workspace/Users/me@example.com/turbine_project/train"}, "environment_key": "ml_env" }], "environments": [{ "environment_key": "ml_env", "spec": { "client": "4", "dependencies": ["mlflow==3.1.0", "xgboost==2.1.3", "optuna==4.1.0", "scikit-learn==1.5.2"] } }] }' | jq -r .run_id)
databricks workspace import /Workspace/Users/me@example.com/turbine_project/train
--file ./train_notebook.py --format SOURCE --language PYTHON --overwrite

3. Poll until a terminal life_cycle_state.

2. 提交为无服务器一次性运行（添加--no-wait会立即返回{"run_id": N}）

for _ in $(seq 60); do STATE=$(databricks jobs get-run "$RUN_ID" | jq -r '.state.life_cycle_state // "UNKNOWN"') echo "$(date +%H:%M:%S) $STATE" [[ "$STATE" =~ ^(TERMINATED|SKIPPED|INTERNAL_ERROR)$ ]] && break sleep 30 done [[ "$STATE" =~ ^(TERMINATED|SKIPPED|INTERNAL_ERROR)$ ]] || { databricks jobs cancel-run "$RUN_ID"; exit 1; }
RUN_ID=$(databricks jobs submit --no-wait --json '{ "run_name": "turbine-train-and-deploy", "tasks": [{ "task_key": "train", "notebook_task": {"notebook_path": "/Workspace/Users/me@example.com/turbine_project/train"}, "environment_key": "ml_env" }], "environments": [{ "environment_key": "ml_env", "spec": { "client": "4", "dependencies": ["mlflow==3.1.0", "xgboost==2.1.3", "optuna==4.1.0", "scikit-learn==1.5.2"] } }] }' | jq -r .run_id)

life_cycle_state TERMINATED only means "the run ended" — check result_state.

3. 轮询直到进入终端生命周期状态。

RESULT=$(databricks jobs get-run "$RUN_ID" | jq -r '.state.result_state // "UNKNOWN"') echo "result_state=$RESULT" [[ "$RESULT" == "SUCCESS" ]] || { echo "Run did not succeed"; exit 1; }
for _ in $(seq 60); do STATE=$(databricks jobs get-run "$RUN_ID" | jq -r '.state.life_cycle_state // "UNKNOWN"') echo "$(date +%H:%M:%S) $STATE" [[ "$STATE" =~ ^(TERMINATED|SKIPPED|INTERNAL_ERROR)$ ]] && break sleep 30 done [[ "$STATE" =~ ^(TERMINATED|SKIPPED|INTERNAL_ERROR)$ ]] || { databricks jobs cancel-run "$RUN_ID"; exit 1; }

4. Pull structured output via the TASK run_id (NOT the submit run_id).

life_cycle_state为TERMINATED仅表示“运行已结束”——需检查result_state。

TASK_RUN_ID=$(databricks jobs get-run "$RUN_ID" | jq -r '.tasks[0].run_id') databricks jobs get-run-output "$TASK_RUN_ID" | jq '.notebook_output.result'
RESULT=$(databricks jobs get-run "$RUN_ID" | jq -r '.state.result_state // "UNKNOWN"') echo "result_state=$RESULT" [[ "$RESULT" == "SUCCESS" ]] || { echo "运行未成功"; exit 1; }

→ '{"model_version":"3","val_auc":0.91,"rows_scored":124,"endpoint":"turbine-risk-endpoint"}'

4. 通过任务运行ID（而非提交运行ID）获取结构化输出。


Common `jobs submit` traps to be aware of: `environments[].spec.client: "4"` is required on serverless notebook tasks; use the TASK run_id (`tasks[0].run_id`) — NOT the submit run_id — for `get-run-output`; `print()` is unreliable on serverless one-time runs (use `dbutils.notebook.exit(json.dumps(...))`); `jobs submit` rejects `tags`. For the broader `databricks-jobs` skill, see **[databricks-jobs](../databricks-jobs/SKILL.md)**.

---
TASK_RUN_ID=$(databricks jobs get-run "$RUN_ID" | jq -r '.tasks[0].run_id') databricks jobs get-run-output "$TASK_RUN_ID" | jq '.notebook_output.result'

Custom pyfunc

→ '{"model_version":"3","val_auc":0.91,"rows_scored":124,"endpoint":"turbine-risk-endpoint"}'

When sklearn/XGBoost autolog isn't enough — custom preprocessing, multiple sub-models, external API calls, ensemble logic. See references/custom-pyfunc.md for a full worked example. Two non-obvious things:
  • python_model="path/to/file.py"
     (file path, not class instance) + 
    mlflow.models.set_model(MyModel())
    at the end of that file. This is the "Models from Code" pattern — the file is logged verbatim, no pickling of the class.
  • mlflow.models.predict(model_uri=..., input_data=..., env_manager="uv")
     before deploying. Catches missing deps before the endpoint does.

需要注意的`jobs submit`常见陷阱：无服务器笔记本任务必须设置`environments[].spec.client: "4"`；获取输出需使用任务运行ID（`tasks[0].run_id`）——而非提交运行ID；无服务器一次性运行中`print()`不可靠（请使用`dbutils.notebook.exit(json.dumps(...))`）；`jobs submit`不支持`tags`。如需了解更全面的`databricks-jobs`技能，请查看**[databricks-jobs](../databricks-jobs/SKILL.md)**。

---

Custom GenAI agents

自定义PyFunc

Hand-rolled 
ResponsesAgent
(LangGraph + UC Function tools + Vector Search retrieval) — see references/genai-agents.md.
Prefer no-code authoring via databricks-agent-bricks (Knowledge Assistants, Supervisor Agents) unless the user explicitly needs a custom LangGraph agent.
当sklearn/XGBoost自动记录无法满足需求时（如自定义预处理、多个子模型、外部API调用、集成逻辑），请查看**references/custom-pyfunc.md**获取完整示例。有两个容易忽略的要点：
  • python_model="path/to/file.py"
    （文件路径，而非类实例）+ 在该文件末尾添加
    mlflow.models.set_model(MyModel())
    。这是“代码生成模型”模式——文件会被原样记录，不会对类进行序列化。
  • 部署前执行
    mlflow.models.predict(model_uri=..., input_data=..., env_manager="uv")
    。可以在端点部署前捕获缺失的依赖项。

Feature Engineering: Feature Store & Feature Views

自定义生成式AI代理

When to reach for Feature Engineering (either flavor) instead of a plain Delta table: when the same feature must be computed identically at training and serving time (no training/serving skew), the feature is time-dependent and needs point-in-time joins against labels (no future leakage), the feature needs to be served with <10ms latency via an online store, or the feature is shared across models with lineage tracked in UC. If none apply, a plain UC table is enough — the sections below can be skipped.
Default: don't use Feature Engineering unless one of the reasons above clearly applies or the user explicitly asked for it. It adds build time and complexity (an extra Delta table layer for 
FeatureLookup
; a materialization pipeline for Feature Views). If you're unsure, use plain UC tables and add Feature Engineering later when a concrete need surfaces.
Two flavors, one train/score path (
create_training_set
→ 
fe.log_model
→ 
fe.score_batch
):
  • FeatureLookup
    API     — you own the feature tables (compute, write, refresh); bind them to a training set via 
    FeatureLookup
    + 
    FeatureEngineeringClient
    . Reach for it when the features already exist as Delta tables or you want direct control over how they are computed. See references/feature-store.md.
  • Feature Views (declarative, Public Preview, 
    databricks-feature-engineering>=0.16.0
    ) — Databricks owns compute, materialization (Delta offline + Lakebase online), and refresh from a spec you declare (
    create_feature
    over 
    DeltaTableSource
    ; 
    RollingWindow
    /
    SlidingWindow
    /
    TumblingWindow
    ; 
    create_stream
    for Kafka features). Reach for it when the feature is a formula you want Databricks to keep fresh. See references/feature-views.md.
手动构建的
ResponsesAgent
（LangGraph + UC Function工具 + 向量搜索检索）——请查看**references/genai-agents.md**。
除非用户明确需要自定义LangGraph代理，否则优先通过databricks-agent-bricks进行无代码创作（知识助手、监督代理）。

Gotchas (the ones that cost time)

特征工程：特征存储与Feature Views

TrapFix
Model lands in workspace registry, not UC
mlflow.set_registry_uri("databricks-uc")
before logging
Endpoint returns PERMISSION_DENIED at first queryPass 
resources=[...]
to 
log_model
(covers UC functions, VS indexes, other endpoints, Lakebase) — see references/genai-agents.md#resources-that-need-passthrough-auth for the full list
Used 
transition_model_version_stage
Stages are deprecated in UC. Use 
client.set_registered_model_alias(name, "prod", version)
spark_udf
rebuilds a virtualenv on every call		Pass 
env_manager="local"
when training+scoring share a runtime
pip_requirements
mismatch crashes endpoint at load		Pin exact versions; or pull live with 
f"mlflow=={get_distribution('mlflow').version}"
agents.deploy()
produced a weirdly-named endpoint		Pass 
endpoint_name=...
explicitly. Auto-derived name is 
agents_<catalog>-<schema>-<model>
Endpoint-lifecycle gotchas (readiness two-state, version-swap, Serving-UI SP filter) live in databricks-model-serving.
何时选择特征工程（任一形式）而非普通Delta表：当同一特征必须在训练和服务时计算方式完全一致（避免训练/服务偏差）、特征与时间相关且需要与标签进行时间点连接（避免未来数据泄露）、特征需要通过在线存储以低于10毫秒的延迟提供服务，或者特征在多个模型间共享且需要在UC中跟踪谱系。如果以上情况都不适用，普通UC表即可——可跳过以下部分。
默认原则：除非明确符合上述任一原因，或用户明确要求，否则不要使用特征工程。它会增加构建时间和复杂度（
FeatureLookup
需要额外的Delta表层；Feature Views需要物化管道）。如果不确定，请先使用普通UC表，当出现具体需求时再添加特征工程。
两种形式共享同一训练/评分路径（
create_training_set
→ 
fe.log_model
→ 
fe.score_batch
）：
  • FeatureLookup
    API     —— 由您负责特征表的计算、写入和刷新；通过
    FeatureLookup
    + 
    FeatureEngineeringClient
    将其绑定到训练集。当特征已作为Delta表存在，或您希望直接控制特征计算方式时使用。请查看**references/feature-store.md**。
  • Feature Views（声明式，公开预览版，要求
    databricks-feature-engineering>=0.16.0
    ）—— 由Databricks负责计算、物化（Delta离线 + Lakebase在线）以及根据您声明的规范进行刷新（基于
    DeltaTableSource
    的
    create_feature
    ；
    RollingWindow
    /
    SlidingWindow
    /
    TumblingWindow
    ；基于Kafka特征的
    create_stream
    ）。当特征是您希望Databricks自动保持更新的公式时使用。请查看**references/feature-views.md**。

Reference files

常见陷阱（耗时问题）

FileContents
references/custom-pyfunc.mdSingle end-to-end custom pyfunc example: artifacts, signature, code_paths, log → register → deploy → query.
references/genai-agents.mdCustom LangGraph 
ResponsesAgent
with UC Function + Vector Search tools. 
create_text_output_item
gotcha and the 
resources=[...]
passthrough-auth list. For no-code agents prefer databricks-agent-bricks.
references/feature-store.mdFeature Engineering in Unity Catalog (standard 
FeatureLookup
API): 
FeatureEngineeringClient
, 
create_table
with 
timeseries_column
, 
FeatureLookup
with point-in-time joins, 
fe.log_model
with lineage, 
fe.score_batch
(replaces 
spark_udf
for FE models), and Lakebase online store via 
publish_table
. Requires 
databricks-feature-engineering>=0.16.0
.
references/feature-views.mdFeature Views (declarative Feature Engineering, Public Preview): 
create_feature
over 
DeltaTableSource
, 
RollingWindow
/
SlidingWindow
/
TumblingWindow
aggregations, 
materialize_features
(offline + online), streaming features off Kafka via 
create_stream
, point-in-time training sets, and the Feature Serving Endpoint. Requires 
databricks-feature-engineering>=0.16.0
.
陷阱解决方法
模型存入工作区注册表而非UC记录模型前先执行
mlflow.set_registry_uri("databricks-uc")
端点首次查询返回PERMISSION_DENIED调用
log_model
时传入
resources=[...]
（涵盖UC函数、向量搜索索引、其他端点、Lakebase）——完整列表请查看references/genai-agents.md#resources-that-need-passthrough-auth
使用了
transition_model_version_stage
UC已弃用Stage。请使用
client.set_registered_model_alias(name, "prod", version)
spark_udf
每次调用都会重建虚拟环境		当训练和评分共享同一运行时时，传入
env_manager="local"
pip_requirements
不匹配导致端点加载崩溃		固定精确版本；或通过
f"mlflow=={get_distribution('mlflow').version}"
动态获取当前版本
agents.deploy()
生成的端点名称不符合预期		显式传入
endpoint_name=...
。自动生成的名称格式为
agents_<catalog>-<schema>-<model>
端点生命周期相关陷阱（就绪双状态检查、版本切换、服务UI SP筛选）请查看databricks-model-serving。

Related skills

参考文件

  • databricks-model-serving — serving-endpoint lifecycle (create, query, update-config, version-swap, AI Gateway, Foundation Model API endpoints).
  • databricks-agent-bricks — no-code Knowledge Assistants and Supervisor Agents. Prefer this over hand-rolling agents.
  • databricks-mlflow-evaluation — evaluate model/agent quality before promoting 
    @prod
    .
  • databricks-vector-search — vector indexes used as retrieval tools in agents.
  • databricks-jobs — async deploy pattern (
    --no-wait
    , TASK run_id trap).
  • databricks-unity-catalog — UC governs the registered model: permissions, lineage, audit.
文件内容
references/custom-pyfunc.md完整的自定义PyFunc端到端示例：工件、签名、代码路径、记录→注册→部署→查询。
references/genai-agents.md带有UC Function + 向量搜索工具的自定义LangGraph 
ResponsesAgent
。包含
create_text_output_item
陷阱和
resources=[...]
传递身份验证列表。无代码代理优先选择databricks-agent-bricks。
references/feature-store.mdUnity Catalog中的特征工程（标准
FeatureLookup
API）：
FeatureEngineeringClient
、带
timeseries_column
的
create_table
、带时间点连接的
FeatureLookup
、带谱系的
fe.log_model
、
fe.score_batch
（替代FE模型的
spark_udf
）、以及通过
publish_table
实现的Lakebase在线存储。要求
databricks-feature-engineering>=0.16.0
。
references/feature-views.mdFeature Views（声明式特征工程，公开预览版）：基于
DeltaTableSource
的
create_feature
、
RollingWindow
/
SlidingWindow
/
TumblingWindow
聚合、
materialize_features
（离线 + 在线）、基于Kafka的流特征
create_stream
、时间点训练集以及特征服务端点。要求
databricks-feature-engineering>=0.16.0
。
—

相关技能

—
  • databricks-model-serving —— 服务端点生命周期（创建、查询、更新配置、版本切换、AI网关、基础模型API端点）。
  • databricks-agent-bricks —— 无代码知识助手和监督代理。优先选择该技能而非手动构建代理。
  • databricks-mlflow-evaluation —— 升级到
    @prod
    前评估模型/代理质量。
  • databricks-vector-search —— 代理中用作检索工具的向量索引。
  • databricks-jobs —— 异步部署模式（
    --no-wait
    、任务运行ID陷阱）。
  • databricks-unity-catalog —— UC管理注册模型：权限、谱系、审计。