技能 API 和 SDK 参考

Important

此功能在 Beta 版中。 帐户管理员可以从帐户控制台 预览 页管理对此功能的访问权限。 请参阅 “管理帐户级预览”。

利用这些例子来自动化技能管理。 API将每个技能表示为 Skill 名为 skills/{catalog}.{schema}.{skill}的资源。 如需与代理人共同撰写并发布技能,请参见 “创建并分享技能”。 关于特权和治理,请参见 治理技能。 技能没有Terraform或声明式自动化捆绑包的资源。

先决条件

  • 为 技能建立一个有控制的模式。

  • 拥有 操作所需的权限。

  • 安装并认证你计划使用的客户端。 REST API 没有版本要求;每个工具和 SDK 都有最低版本:

    • Databricks CLI:v1.20.0及以上版本
    • Python SDK: databricks-sdk 0.142.0及以上版本
    • Go SDK: databricks-sdk-go v0.184.0及以上版本
    • Go Modular SDK: github.com/databricks/sdk-go/aigateway v0.1.0及以上版本
    • Java SDK: databricks-sdk-java 0.157.0及以上版本
    • JavaScript SDK: @databricks/sdk-aigateway 0.23.0及以上版本

    SDK snippet 假设一个认证过的工作区客户端; w模块化 SDK snippet 假设一个认证过的 Unity Gateway 客户端,在 c Go 和 client JavaScript 中都存在。

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

使用 READ VOLUME 授予:

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)

Grant 与READ VOLUME:

_, 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' });

其他资源