Skills API i odniesienie do SDK

Important

Ta funkcja jest dostępna w wersji beta. Administratorzy kont mogą zarządzać dostępem do tej funkcji na stronie podglądów konsoli konta. Zobacz Zarządzanie podglądami na poziomie konta.

Wykorzystaj te przykłady, aby zautomatyzować zarządzanie umiejętnościami. API reprezentuje każdą umiejętność jako zasób Skill o nazwie skills/{catalog}.{schema}.{skill}. Aby napisać i opublikować umiejętność z agentem, zobacz Stwórz i udostępniaj umiejętności. W przypadku przywilejów i zarządzania zobacz Umiejętności Zarządzania. Umiejętności nie mają zasobów z Terraform ani Declarative Automation Bundles.

Warunki wstępne

Operacje interfejsu API

Skills REST API zapewnia te operacje. Każdy z nich również wymaga USE CATALOG i zależy od USE SCHEMA rodzica. Kliknij każdy link, aby poznać pola, uprawnienia i odpowiedzi.

Operation Przypadek użycia Wymagane uprawnienia
Utwórz Stwórz umiejętność i udostępnij jej magazyn pakietów. CREATE VOLUME w schemacie
Prześlij Prześlij SKILL.md i wszystkie pliki wspierające przez API Files. WRITE VOLUME oraz READ VOLUME na umiejętność
Finalize Przeczytaj i zweryfikowaj SKILL.md, a następnie ustaw nazwę pakietu i opis umiejętności. READ VOLUME o umiejętności
Lista Znajdź umiejętności, do których możesz mieć dostęp w schemacie. READ VOLUME, READ METADATA, czyli MANAGE na umiejętność
Pobierz Przeczytaj metadane umiejętności i jej aktualne etag. READ VOLUME, READ METADATA, czyli MANAGE na umiejętność
Update Zmień komentarz do umiejętności. MANAGE o umiejętności
Delete Usuń umiejętność i jej pakiet. MANAGE o umiejętności

Właściciel umiejętności posiada wszystkie te cechy na tej umiejętności. Zobacz Grant Access to Skills.

Tworzenie umiejętności

Stworzenie umiejętności wymaga trzech kroków: stworzenia umiejętności, przesłania jej pakietu, a następnie jej finalizacji. Dopóki nie sfinalizujesz umiejętności, jej nazwa i opis pakietu są puste.

Krok 1: Stwórz umiejętność

Stwórz tę umiejętność w schemiacie. comment to jedyne pole, które możesz ustawić. Azure Databricks derives name, bundle_name, and description.

Zastąp main.default.my_skill i data-team własnymi wartościami.

interfejs API REST

Wyślij do POST/api/2.1/unity-catalog/skills, przekazując parent i skill_id jako parametry zapytania:

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

Przekaż schemat nadrzędny i nazwę umiejętności, a komentarz dodaj:--json

databricks ai-gateway create-skill schemas/main.default my_skill \
  --json '{"comment": "Team-shared math helper skill"}'

Zestaw SDK dla języka Python

Stwórz i zarządzaj umiejętnością za pomocą Databricks SDK dla Pythona:

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"),
)

Zestaw SDK dla języka Go

Stwórz i zarządzaj umiejętnością za pomocą 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

Stwórz i zarządzaj umiejętnością za pomocą Go Modular SDK. Pola opcjonalne są wskaźnikami, więc przykład używa jednolinijowej funkcji pomocniczej, 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

Stwórz i zarządzaj umiejętnością za pomocą Databricks SDK dla Javy:

Skill skill =
    w.aiGateway()
        .createSkill(
            new CreateSkillRequest()
                .setParent("schemas/main.default")
                .setSkillId("my_skill")
                .setSkill(new Skill().setComment("Team-shared math helper skill")));

JS Modular SDK

Stwórz i zarządzaj umiejętnością za pomocą SDK JavaScript:

const created = await client.createSkill({
  parent: 'schemas/main.default',
  skillId: 'my_skill',
  skill: { comment: 'Team-shared math helper skill' },
});

Krok 2: Przeładowaj pakiet

Prześlij SKILL.md, oraz wszystkie pliki pomocnicze na ścieżkę /Skills/<catalog>/<schema>/<skill>/przechowywania umiejętności, , przez API Files. SKILL.md musi zacząć od frontmaterii YAML, która ustawia name i description. Zapisz ten przykład jako :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.

interfejs API REST

Wyślij a PUT do API Plików. Ustaw DATABRICKS_HOST na adres URL twojego workspace, na przykład https://my-workspace.cloud.databricks.com, oraz DATABRICKS_TOKEN na token. Ten przykład przekazuje token na curl standardowe wejście, aby nie pojawiał się na liście procesów:

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

Utwórz folder umiejętności, a następnie skopiuj plik do niego:

databricks fs mkdir dbfs:/Skills/main/default/my_skill
databricks fs cp SKILL.md dbfs:/Skills/main/default/my_skill/SKILL.md --overwrite

Zestaw SDK dla języka Python

with open("SKILL.md", "rb") as f:
    w.files.upload("/Skills/main/default/my_skill/SKILL.md", f, overwrite=True)

Zestaw SDK dla języka Go

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

Modułowe SDK Go nie zawiera API plików. Zamiast tego przesyłaj pliki SDK dla 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 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 Modular SDK

JavaScript Modular SDK nie zawiera API plików, więc ten przykład wywołuje bezpośrednio endpoint REST. Odczytuje URL przestrzeni roboczej, takie jak https://my-workspace.cloud.databricks.com, oraz token z DATABRICKS_HOST zmiennych środowiskowych i DATABRICKS_TOKEN środowiskowych:

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}`);
}

Krok 3: Dopracuj umiejętność

Finalizing czyta i waliduje SKILL.md, następnie ustawia umiejętności bundle_name i description z jej przedniej strony. Jeśli później zmienisz pakiet, sfinalizuj ponownie.

interfejs API REST

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

Zestaw SDK dla języka Python

finalized = w.ai_gateway.finalize_skill(name="skills/main.default.my_skill")
print(finalized.bundle_name, finalized.description)

Zestaw SDK dla języka Go

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 Modular SDK

const finalized = await client.finalizeSkill({ name: 'skills/main.default.my_skill' });

Znajdź umiejętność

Wypisz umiejętności, do których masz dostęp, w schemacie, a następnie uzyskaj metadane umiejętności według nazwy zasobu.

interfejs API REST

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"

Gdy odpowiedź na liście zawiera next_page_token, przekażmy ją jako page_token w następnym żądaniu. Kontynuuj, aż next_page_token będzie nieobecności lub pusta.

CLI

databricks ai-gateway list-skills schemas/main.default

databricks ai-gateway get-skill skills/main.default.my_skill

Zestaw SDK dla języka Python

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")

Iterator CLI i Python obsługują paginację za ciebie.

Przyznaj dostęp

Te przykłady dają READ VOLUME możliwość przeczytania umiejętności i pobrania jej pakietu. O pozostałych przywilejach umiejętności zobacz: Udziel dostępu do umiejętności.

interfejs API REST

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 z databricks CLI:

databricks grants update skill main.default.my_skill \
  --json '{"changes": [{"principal": "data-team", "add": ["READ_VOLUME"]}]}'

Zestaw SDK dla języka Python

Nadawanie READ VOLUME za pomocą pakietu Databricks SDK dla języka Python:

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])],
)

Zestaw SDK dla języka Go

Przyznaj READ VOLUME za pomocą Databricks SDK for Go:

_, 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

Grant READ VOLUME za pomocą pakietu Databricks SDK dla języka Java:

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)))));

Aktualizuj umiejętność

Te przykłady aktualizują komentarz do umiejętności, jedyne pole, które możesz zmienić. Nazwy umiejętności nie da się zmienić. Aby zmienić zawartość umiejętności, wgraj nowy pakiet i ponownie ją sfinalizuj .

Dla aktualizacji warunkowej najpierw zdobądź umiejętność i zdaj ją etag wraz z aktualizacją. Aktualizacja udaje się tylko wtedy, gdy umiejętność nie zmieniła się od tamtego czytania. URL koduje go etag przy dodawaniu go do ciągu zapytania REST.

interfejs API REST

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"}'

Zestaw SDK dla języka Python

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"),
)

Zestaw SDK dla języka Go

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

Usuń umiejętność

Usunięcie umiejętności usuwa ją i jej pakiet. Agenci nie mogą już go ładować.

Możesz też przekazać aktualność etag umiejętności, aby usunięcie było uzależnione od tego, że nie zmieniła się od ostatniego odczytu. Łańcuchy zapytań w REST kodują etag przez URL.

interfejs API REST

databricks api delete "/api/2.1/unity-catalog/skills/main.default.my_skill"

CLI

databricks ai-gateway delete-skill skills/main.default.my_skill

Zestaw SDK dla języka Python

w.ai_gateway.delete_skill(name="skills/main.default.my_skill")

Zestaw SDK dla języka Go

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 Modular SDK

await client.deleteSkill({ name: 'skills/main.default.my_skill' });

Dodatkowe zasoby

  • Ostatnia aktualizacja o