利用这些例子来自动化技能管理。 API将每个技能表示为 Skill 名为 skills/{catalog}.{schema}.{skill}的资源。 如需与代理人共同撰写并发布技能,请参见 “创建并分享技能”。 关于特权和治理,请参见 治理技能。 技能没有Terraform或声明式自动化捆绑包的资源。
先决条件
为 技能建立一个有控制的模式。
拥有 操作所需的权限。
安装并认证你计划使用的客户端。 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 snippet 假设一个认证过的工作区客户端;
w模块化 SDK snippet 假设一个认证过的 Unity Gateway 客户端,在cGo 和clientJavaScript 中都存在。
API 操作
Skills REST API 提供了这些操作。 每个项目也要求 USE CATALOG 父母 USE SCHEMA 承担责任。 请点击每个链接查看其字段、权限和回复。
| 运算 | 用例 | 所需的权限 |
|---|---|---|
| 创建 | 创建一个技能并配置其捆绑包存储。 |
CREATE VOLUME 关于架构的 |
| 上传 | 通过文件API上传 SKILL.md 及任何支持文件。 |
WRITE VOLUME 以及 READ VOLUME 关于技巧 |
| 完成 | 读取并验证 SKILL.md,然后设置技能包的名称和描述。 |
READ VOLUME 关于技能 |
| 列表 | 找到你能在图式中获得的技能。 |
READ VOLUME, READ METADATA或 MANAGE 技能 |
| Get | 读取技能的元数据和当前 etag状态。 |
READ VOLUME, READ METADATA或 MANAGE 技能 |
| Update | 更改技能的注释。 |
MANAGE 关于技能 |
| Delete | 移除一个技能及其包。 |
MANAGE 关于技能 |
技能的持有者将所有这些属性都保留在技能上。 参见技能授予。
创建技能
创建技能需要三个步骤:创建技能、上传其捆绑包,然后最终定稿。 在你确定技能之前,它的包名和描述都是空的。
第一步:创建技能
在一个方案中创建技能。
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为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 SDK
使用Databricks SDK为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' },
});
步骤2:上传捆绑包
通过文件API上传 SKILL.md,以及任何支持文件,上传到技能的存储路径 /Skills/<catalog>/<schema>/<skill>/。
SKILL.md 必须从 YAML 前件开始,该前置件设 name 和 description。 将此示例保存为 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一个令牌。 这个例子是在标准输入时将令牌传递给 , 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 不包含文件 API。 改用 Go 的 Files SDK 上传:
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 SDK
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模块化SDK不包含文件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}`);
}
步骤3:确定技能
最终阅读并验证 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 SDK
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
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 SDK
通过 Databricks SDK for Java 获得资助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 SDK
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 SDK
w.aiGateway().deleteSkill(new DeleteSkillRequest().setName("skills/main.default.my_skill"));
JS 模块化 SDK
await client.deleteSkill({ name: 'skills/main.default.my_skill' });