Important
這項功能位於 測試版 (Beta) 中。 帳號管理員可從帳號主控台 預覽 頁面管理此功能存取權。 請參閱 管理帳戶層級預覽。
利用這些範例來自動化技能管理。 API 將每個技能表示為 Skill 一個名為 skills/{catalog}.{schema}.{skill}的資源。 若要與經紀人共同撰寫並發表技能,請參閱 「創建與分享技能」。 關於特權與治理,請參見 治理技能。 技能沒有 Terraform 或 Declarative Automation Bundles 的資源。
先決條件
建立 一個有規範的技能架構。
擁有 你操作所需的權限。
安裝並驗證你打算使用的客戶端。 REST API 沒有版本限制;每個工具和 SDK 都有最低版本:
- Databricks CLI:v1.20.0 及以上版本
-
Python SDK:
databricks-sdk0.142.0 及以上版本 -
Go SDK:
databricks-sdk-gov0.184.0 及以上版本 -
Go Modular SDK:
github.com/databricks/sdk-go/aigatewayv0.1.0 及以上版本 -
Java SDK:
databricks-sdk-java0.157.0 及以上版本 -
JavaScript SDK:
@databricks/sdk-aigateway0.23.0 及以上版本
SDK snippets 假設一個已認證的工作區用戶端;
w模組化 SDK snippets 假設 Unity Gateway 用戶端已認證,無論是c在 Go 和 JavaScript 中client。
API 作業
Skills REST API 提供這些操作。 每個項目也都要求 USE CATALOG 父母 USE SCHEMA 負責。 請點擊每個連結查看欄位、權限與回應。
| Operation | 應用案例 | 所需的權限 |
|---|---|---|
| 創造 | 創建一個技能並配置其套件儲存。 |
CREATE VOLUME 在結構描述上 |
| Upload | 透過檔案 API 上傳 SKILL.md 及任何支援檔案。 |
WRITE VOLUME 以及 READ VOLUME 關於技巧 |
| 完成 | 讀取並驗證 SKILL.md,然後設定技能組合名稱和描述。 |
READ VOLUME 關於 Skill |
| 清單 | 找到你能在架構中使用技能。 |
READ VOLUME, READ METADATA或 MANAGE 在技能上 |
| 獲取 | 閱讀技能的元資料和目前 etag狀態。 |
READ VOLUME, READ METADATA或 MANAGE 在技能上 |
| Update | 更改技能的註解。 |
MANAGE 關於 Skill |
| Delete | 移除一個技能及其組合包。 |
MANAGE 關於 Skill |
技能擁有者會將這些技能全部保留在技能上。 請參閱技能授予。
創造一項技能
創建技能需要三個步驟:建立技能、上傳其組合包,然後完成。 在你確定技能之前,它的組合名稱和描述都是空白的。
步驟一:創建技能
在一個架構中創造技能。
comment 這是你唯一能設定的欄位。 Azure Databricks 衍生 name、 bundle_name, 。description
將main.default.my_skill 和 data-team 取代為您自己的值。
REST API
傳送 POST/api/2.1/unity-catalog/skills,並傳遞 parent 和 skill_id 作為查詢參數:
databricks api post \
"/api/2.1/unity-catalog/skills?parent=schemas/main.default&skill_id=my_skill" \
--json '{"comment": "Team-shared math helper skill"}'
CLI
傳遞父架構和技能名稱,並附註 --json:
databricks ai-gateway create-skill schemas/main.default my_skill \
--json '{"comment": "Team-shared math helper skill"}'
Python SDK
使用 Databricks SDK for Python 創建並管理一項技能:
from databricks.sdk import WorkspaceClient
from databricks.sdk.service import catalog as c
w = WorkspaceClient()
skill = w.ai_gateway.create_skill(
parent="schemas/main.default",
skill_id="my_skill",
skill=c.Skill(comment="Team-shared math helper skill"),
)
Go 軟體開發套件 (SDK)
使用 Databricks SDK for Go 創建並管理一項技能:
skill, err := w.AiGateway.CreateSkill(ctx, catalog.CreateSkillRequest{
Parent: "schemas/main.default",
SkillId: "my_skill",
Skill: catalog.Skill{Comment: "Team-shared math helper skill"},
})
Go Modular SDK
用 Go Modular SDK 創建並管理一項技能。 可選欄位是指標,因此範例中使用一行輔助工具 func ptr[T any](v T) *T { return &v }。
skill, err := c.CreateSkill(ctx, aigateway.CreateSkillRequest{
Parent: ptr("schemas/main.default"),
SkillId: ptr("my_skill"),
Skill: &aigateway.Skill{Comment: ptr("Team-shared math helper skill")},
})
Java 開發套件
使用 Databricks SDK for Java 創建並管理一項技能:
Skill skill =
w.aiGateway()
.createSkill(
new CreateSkillRequest()
.setParent("schemas/main.default")
.setSkillId("my_skill")
.setSkill(new Skill().setComment("Team-shared math helper skill")));
JS 模組化 SDK
使用 JavaScript SDK 建立並管理一項技能:
const created = await client.createSkill({
parent: 'schemas/main.default',
skillId: 'my_skill',
skill: { comment: 'Team-shared math helper skill' },
});
步驟二:上傳組合包
透過 Files API 將 ,以及 SKILL.md任何支援檔案上傳到技能的儲存路徑 /Skills/<catalog>/<schema>/<skill>/。
SKILL.md 必須從設定 name 和 description的 YAML 前置碼開始。 將此範例存為 SKILL.md:
---
name: my-skill
description: A team-shared skill that helps with basic math.
---
# My Skill
Step-by-step guidance the agent follows when this skill is loaded.
REST API
把 a PUT 傳送到 Files API。 設定為你的工作區 URL,例如 https://my-workspace.cloud.databricks.com,並DATABRICKS_TOKEN設定DATABRICKS_HOST為一個令牌。 這個範例是在標準輸入時將 token 傳遞到 , curl 因此它不會出現在程序清單中:
curl --request PUT --config - --data-binary @SKILL.md \
--header "Content-Type: application/octet-stream" \
"${DATABRICKS_HOST}/api/2.0/fs/files/Skills/main/default/my_skill/SKILL.md?overwrite=true" \
<<< "header = \"Authorization: Bearer ${DATABRICKS_TOKEN}\""
CLI
建立技能資料夾,然後將檔案複製到裡面:
databricks fs mkdir dbfs:/Skills/main/default/my_skill
databricks fs cp SKILL.md dbfs:/Skills/main/default/my_skill/SKILL.md --overwrite
Python SDK
with open("SKILL.md", "rb") as f:
w.files.upload("/Skills/main/default/my_skill/SKILL.md", f, overwrite=True)
Go 軟體開發套件 (SDK)
f, err := os.Open("SKILL.md")
if err != nil {
return err
}
defer f.Close()
err = w.Files.Upload(ctx, files.UploadRequest{
FilePath: "/Skills/main/default/my_skill/SKILL.md",
Contents: f,
Overwrite: true,
})
Go Modular SDK
Go Modular SDK 不包含 Files API。 改用 Files SDK for Go 上傳:
fc, err := files.NewClient(ctx)
if err != nil {
return err
}
f, err := os.Open("SKILL.md")
if err != nil {
return err
}
defer f.Close()
_, err = fc.Upload(ctx, "/Skills/main/default/my_skill/SKILL.md", f, files.WithOverwrite(true))
Java 開發套件
try (InputStream contents = Files.newInputStream(Paths.get("SKILL.md"))) {
w.files()
.upload(
new UploadRequest()
.setFilePath("/Skills/main/default/my_skill/SKILL.md")
.setOverwrite(true)
.setContents(contents));
}
JS 模組化 SDK
JavaScript Modular SDK 不包含 Files API,因此此範例直接呼叫 REST 端點。 它會讀取工作區的 URL,例如 https://my-workspace.cloud.databricks.com,以及來自 DATABRICKS_HOST 和 DATABRICKS_TOKEN 環境變數的權杖:
import { readFile } from 'node:fs/promises';
const response = await fetch(
`${process.env.DATABRICKS_HOST}/api/2.0/fs/files/Skills/main/default/my_skill/SKILL.md?overwrite=true`,
{
method: 'PUT',
headers: {
'Content-Type': 'application/octet-stream',
Authorization: `Bearer ${process.env.DATABRICKS_TOKEN}`,
},
body: await readFile('SKILL.md'),
},
);
if (!response.ok) {
throw new Error(`Upload failed: ${response.status} ${response.statusText}`);
}
步驟三:完成技能
最終閱讀並驗證 SKILL.md,然後設定技能 bundle_name 的 和 description 從前置內容。 如果你之後更改組合包,請再完成一次。
REST API
databricks api post "/api/2.1/unity-catalog/skills/main.default.my_skill/finalize" --json '{}'
CLI
databricks ai-gateway finalize-skill skills/main.default.my_skill
Python SDK
finalized = w.ai_gateway.finalize_skill(name="skills/main.default.my_skill")
print(finalized.bundle_name, finalized.description)
Go 軟體開發套件 (SDK)
finalized, err := w.AiGateway.FinalizeSkill(ctx, catalog.FinalizeSkillRequest{
Name: "skills/main.default.my_skill",
})
Go Modular SDK
finalized, err := c.FinalizeSkill(ctx, aigateway.FinalizeSkillRequest{
Name: ptr("skills/main.default.my_skill"),
})
Java 開發套件
Skill finalized =
w.aiGateway().finalizeSkill(new FinalizeSkillRequest().setName("skills/main.default.my_skill"));
JS 模組化 SDK
const finalized = await client.finalizeSkill({ name: 'skills/main.default.my_skill' });
找到一項技能
在結構中列出你能存取的技能,然後依資源名稱取得技能的元資料。
REST API
databricks api get "/api/2.1/unity-catalog/skills?parent=schemas/main.default"
databricks api get "/api/2.1/unity-catalog/skills/main.default.my_skill"
當列表回應包含 next_page_token時,將它傳遞給下一個請求。page_token 持續直到 next_page_token 空無一人或空。
CLI
databricks ai-gateway list-skills schemas/main.default
databricks ai-gateway get-skill skills/main.default.my_skill
Python SDK
for skill in w.ai_gateway.list_skills(parent="schemas/main.default"):
print(skill.name)
skill = w.ai_gateway.get_skill(name="skills/main.default.my_skill")
CLI 和 Python 迭代器會幫你處理分頁。
授予存取權
這些範例 READ VOLUME 授予技能,讓校長能閱讀技能並下載其組合包。 關於其他技能特權,請參見 「授予技能存取權」。
REST API
databricks api patch \
"/api/2.1/unity-catalog/permissions/skill/main.default.my_skill" \
--json '{
"changes": [
{ "principal": "data-team", "add": ["READ_VOLUME"] }
]
}'
CLI
Grant READ VOLUME 與 Databricks CLI:
databricks grants update skill main.default.my_skill \
--json '{"changes": [{"principal": "data-team", "add": ["READ_VOLUME"]}]}'
Python SDK
Grant READ VOLUME 使用 適用於 Python 的 Databricks SDK:
from databricks.sdk.service import catalog as c
w.grants.update(
securable_type="skill",
full_name="main.default.my_skill",
changes=[c.PermissionsChange(principal="data-team", add=[c.Privilege.READ_VOLUME])],
)
Go 軟體開發套件 (SDK)
_, err := w.Grants.Update(ctx, catalog.UpdatePermissions{
SecurableType: "skill",
FullName: "main.default.my_skill",
Changes: []catalog.PermissionsChange{{
Principal: "data-team",
Add: []catalog.Privilege{catalog.PrivilegeReadVolume},
}},
})
Java 開發套件
使用 適用於 Java 的 Databricks SDK 授予 READ VOLUME:
w.grants()
.update(
new UpdatePermissions()
.setSecurableType("skill")
.setFullName("main.default.my_skill")
.setChanges(
Arrays.asList(
new PermissionsChange()
.setPrincipal("data-team")
.setAdd(Arrays.asList(Privilege.READ_VOLUME)))));
更新技能
這些範例是更新技能評論,這是你唯一能更改的欄位。 這個技能的名稱不能更改。 要更改技能內容,請 上傳 新組合包並重新 完成 該技能。
有條件更新的話,先 取得技能 並隨更新傳達 etag 。 更新只有在技能自那次讀取後沒有改變時才算成功。 在將 URL etag 編碼到 REST 查詢字串時。
REST API
databricks api patch \
"/api/2.1/unity-catalog/skills/main.default.my_skill?update_mask=comment" \
--json '{"comment": "Updated: team-shared math helper"}'
CLI
databricks ai-gateway update-skill skills/main.default.my_skill comment \
--json '{"comment": "Updated: team-shared math helper"}'
Python SDK
from databricks.sdk.service import catalog as c
from databricks.sdk.common.types.fieldmask import FieldMask
updated = w.ai_gateway.update_skill(
name="skills/main.default.my_skill",
update_mask=FieldMask(["comment"]),
skill=c.Skill(comment="Updated: team-shared math helper"),
)
Go 軟體開發套件 (SDK)
updated, err := w.AiGateway.UpdateSkill(ctx, catalog.UpdateSkillRequest{
Name: "skills/main.default.my_skill",
UpdateMask: *fieldmask.New([]string{"comment"}),
Skill: catalog.Skill{Comment: "Updated: team-shared math helper"},
})
Go Modular SDK
mask, err := types.NewFieldMask[aigateway.Skill]("comment")
updated, err := c.UpdateSkill(ctx, aigateway.UpdateSkillRequest{
Skill: &aigateway.Skill{
Name: ptr("skills/main.default.my_skill"),
Comment: ptr("Updated: team-shared math helper"),
},
UpdateMask: mask,
})
Java 開發套件
Skill updated =
w.aiGateway()
.updateSkill(
new UpdateSkillRequest()
.setName("skills/main.default.my_skill")
.setUpdateMask(FieldMask.newBuilder().addPaths("comment").build())
.setSkill(new Skill().setComment("Updated: team-shared math helper")));
JS 模組化 SDK
import { skillFieldMask } from '@databricks/sdk-aigateway/v1';
const updated = await client.updateSkill({
skill: {
name: 'skills/main.default.my_skill',
comment: 'Updated: team-shared math helper',
},
updateMask: skillFieldMask('comment'),
});
刪除技能
刪除技能會移除該技能及其組合包。 客服人員無法再載入它。
你也可以傳遞技能的當前值 etag ,讓刪除條件是自上次讀取以來技能沒有改變。 在 REST 中將查詢字串 URL 編碼 etag 。
REST API
databricks api delete "/api/2.1/unity-catalog/skills/main.default.my_skill"
CLI
databricks ai-gateway delete-skill skills/main.default.my_skill
Python SDK
w.ai_gateway.delete_skill(name="skills/main.default.my_skill")
Go 軟體開發套件 (SDK)
err := w.AiGateway.DeleteSkill(ctx, catalog.DeleteSkillRequest{
Name: "skills/main.default.my_skill",
})
Go Modular SDK
err := c.DeleteSkill(ctx, aigateway.DeleteSkillRequest{
Name: ptr("skills/main.default.my_skill"),
})
Java 開發套件
w.aiGateway().deleteSkill(new DeleteSkillRequest().setName("skills/main.default.my_skill"));
JS 模組化 SDK
await client.deleteSkill({ name: 'skills/main.default.my_skill' });