Opis API workflow

Ta strona opisuje klasy i metody używane w przykładach:

• Wprowadzenie do workflow
• Pierwsze zadanie workflow
• Zadania wielokrotnego użytku
• Usługi HTTP
• Gotowe workflow

Image

Image.from_registry(name, repository_secret="")

Argument	Domyślnie	Znaczenie
name	Wymagany	Nazwa, tag albo digest obrazu kontenera.
repository_secret	""	Nazwa sekretu CGC/Kubernetes z danymi dostępu do prywatnego obrazu.

Zwraca definicję Image. Nie tworzy zasobu CGC.

ShellCommand

ShellCommand(executable, arguments=(), prelude="")

Argument	Domyślnie	Znaczenie
executable	Wymagany	Lista lub krotka z nazwą programu i jego argumentami, np. ("python", "-m", "my_service").
arguments	()	Lista lub krotka niepustych argumentów. Element może zawierać opcję i jej wartość, np. "--port 8000".
prelude	""	Polecenia wykonywane przed głównym procesem, np. instalacja pakietów przez pip install.

Metoda render() sprawdza program i argumenty, zabezpiecza je przed niezamierzoną interpretacją przez powłokę i zwraca gotowe polecenie. Treść prelude jest wykonywana bezpośrednio przez powłokę, więc umieszczaj tam tylko zaufane polecenia. Funkcja app.inference() z entity="custom" może zwracać obiekt ShellCommand. Funkcje jobów zwracają polecenie jako tekst.

Każdy element arguments jest dzielony na opcję i wartość: "--label hello world" daje opcję --label i wartość hello world. Argumenty, które mają pozostać w całości, np. kod dla python -c, umieszczaj w executable.

ServicePort

ServicePort(name, port, ingress=False)

Argument	Domyślnie	Znaczenie
name	Wymagany	Niepusta nazwa portu CGC.
port	Wymagany	Unikalny port kontenera z zakresu od 1 do 65535.
ingress	False	Określa, czy CGC ma utworzyć publiczny ingress dla tego dodatkowego portu.

Obiekty ServicePort przekazuje się przez app.inference(additional_ports=[...]). Nazwy i numery muszą być unikalne wśród wszystkich portów zasobu, łącznie z portem głównym.

Przed sprawdzeniem duplikatów SDK usuwa spacje z początku i końca nazwy oraz zamienia wielkie litery na małe. Nazwa może mieć do 32 znaków: liter, cyfr i łączników. Numer portu musi być liczbą całkowitą, a ingress wartością logiczną.

Volume

Volume.from_name(
    name,
    mount_path="",
    size=None,
    storage_class=None,
    create_if_missing=False,
)

Argument	Domyślnie	Znaczenie
name	Wymagany	Nazwa wolumenu CGC.
mount_path	""	Ścieżka montowania wolumenu w kontenerze.
size	None	Pojemność w GB, gdy wolumen ma zostać utworzony.
storage_class	None	Klasa pamięci masowej. None oznacza użycie klasy domyślnej ustawionej w środowisku.
create_if_missing	False	Informacja w definicji o zamiarze utworzenia brakującego wolumenu; sama nie tworzy wolumenu.

Metoda	Znaczenie
create(size=None, storage_class=None)	Tworzy wolumen. Argumenty metody nadpisują wartości zapisane w definicji.
ensure()	Używa gotowego wolumenu albo tworzy go, jeśli go brakuje.
ready()	Zwraca informację, czy wolumen jest gotowy.
delete(force=False)	Usuwa wolumen i jego pliki.

Wywołaj ensure(), a następnie zaczekaj, aż ready() zwróci True, zanim uruchomisz job. Samo create_if_missing=True nie tworzy wolumenu. Wiele wolumenów można podłączyć tylko bez wskazywania własnych ścieżek montowania. Własne mount_path jest obsługiwane przy podłączeniu jednego wolumenu.

App

App(name, image=None, volumes=None, environment=None)

Argument	Domyślnie	Znaczenie
name	Wymagany	Nazwa workflow i domyślny prefiks nazw zasobów.
image	None	Domyślny Image używany przez kroki workflow.
volumes	None	Domyślna lista definicji Volume.
environment	None	Domyślne zmienne środowiskowe jako słownik, w którym nazwy i wartości są tekstem.

App przechowuje wspólną konfigurację. Nie tworzy zasobu.

app.function() i app.job()

Oba dekoratory służą do definiowania zadań, które kończą się po wykonaniu polecenia.

@app.function(
    image=None,
    name=None,
    cpu=1,
    memory=2,
    gpu=0,
    gpu_type="",
    volumes=None,
    environment=None,
    arguments=None,
    ttl_seconds_after_finished=3600,
    shm_size=0,
)

Argument	Domyślnie	Znaczenie
image	Obraz z App	Obraz używany przez ten job.
name	Nazwy App i funkcji	Podstawa nazwy joba, do której SDK dodaje unikalną końcówkę.
cpu	1	Rdzenie CPU zarezerwowane dla joba.
memory	2	Pamięć w GB.
gpu	0	Liczba GPU.
gpu_type	""	Identyfikator GPU CGC.
volumes	Wolumeny z App	Wolumeny podłączone do joba.
environment	{}	Zmienne środowiskowe dodawane do zmiennych z App.
arguments	[]	Dodatkowe argumenty kontenera.
ttl_seconds_after_finished	3600	Czas w sekundach od zakończenia joba do jego usunięcia. None wyłącza automatyczne usuwanie.
shm_size	0	Rozmiar pamięci współdzielonej w GB.

Funkcja z tym dekoratorem musi zwrócić niepuste polecenie powłoki jako tekst.

submit()

run = task.submit(*function_args, wait=False, **function_kwargs)

Przekazuje wartości do udekorowanej funkcji, tworzy job i zwraca JobRun.

for_each()

runs = task.for_each(*iterables, wait=False, kwargs=None)

Łączy elementy z tych samych pozycji w przekazanych kolekcjach przez zip(*iterables) i tworzy job dla każdej takiej grupy. kwargs zawiera argumenty nazwane przekazywane do każdego wywołania funkcji.

submit(wait=True) czeka na zakończenie i zwraca JobRun, ale nie zgłasza wyjątku dla Failed ani Timeout. Sprawdź status przed dalszą pracą.

JobRun

Metoda	Domyślne argumenty	Wartość zwrotna
status()	Brak	Aktualny stan joba, NotFound albo Unknown.
wait()	poll_seconds=5, timeout_seconds=600	Succeeded, Failed albo Timeout.
logs()	timestamps=False	Odpowiedź z logami joba.
delete()	Brak	Odpowiedź na żądanie usunięcia joba.

app.resource()

app.resource(
    image=None,
    name=None,
    startup_command=None,
    cpu=1,
    memory=2,
    gpu=0,
    gpu_type="",
    volumes=None,
    environment=None,
    repository_secret="",
    # Opcje przekazywane wyłącznie po nazwie:
    arguments=None,
    entity="custom",
    shm_size=0,
    node_port_enabled=False,
)

Argument	Domyślnie	Znaczenie
image	Obraz z App	Obraz kontenera.
name	<app-name>-resource	Dokładna nazwa zasobu CGC.
startup_command	None	Polecenie uruchamiane w kontenerze. Jeśli dla entity="custom" nie podasz polecenia ani argumentów, SDK użyje sleep infinity.
arguments	[]	Argumenty przetwarzane przez istniejący backend. Nie można ich łączyć ze startup_command.
entity	"custom"	Własny obraz albo nazwa szablonu zasobu dostępnego w bieżącym środowisku CGC.
cpu	1	Rdzenie CPU.
memory	2	Pamięć w GB.
gpu	0	Liczba GPU.
gpu_type	""	Identyfikator GPU CGC.
volumes	Wolumeny z App	Podłączone wolumeny.
environment	{}	Zmienne środowiskowe dodawane do zmiennych z App.
repository_secret	Sekret z definicji obrazu	Nazwa sekretu z danymi dostępu do prywatnego rejestru obrazów. Zastępuje wartość z definicji obrazu.
shm_size	0	Rozmiar pamięci współdzielonej w GB.
node_port_enabled	False	Udostępnia usługę przez port na węzłach klastra (NodePort).

Zwraca ResourceDefinition, który udostępnia create(), ready() i delete().

Zasób z entity="custom" wymaga wskazania obrazu. Dla zasobu opartego na szablonie nie podawaj własnego obrazu ani startup_command. Argumenty szablonu przekaż przez arguments.

arguments, entity, shm_size i node_port_enabled przekazuje się do app.resource() wyłącznie po nazwie.

app.inference()

@app.inference(
    image=None,
    name=None,
    port=8000,
    port_name="web",
    cpu=1,
    memory=2,
    gpu=0,
    gpu_type="",
    volumes=None,
    environment=None,
    repository_secret="",
    shm_size=0,
    node_port_enabled=False,
    ingress=True,
    # Opcje przekazywane wyłącznie po nazwie:
    entity="custom",
    additional_ports=None,
)

Argument	Domyślnie	Znaczenie
image	Obraz z App	Obraz kontenera.
name	Nazwy App i funkcji	Nazwa zasobu CGC.
entity	"custom"	Własny obraz albo szablon zasobu dostępny w bieżącym środowisku CGC.
port	8000	Port używany przez serwer HTTP.
port_name	"web"	Nazwa portu używana przy konfiguracji dostępu przez ingress.
additional_ports	[]	Dodatkowe obiekty ServicePort konfigurowane po osiągnięciu przez zasób stanu Running.
cpu	1	Rdzenie CPU.
memory	2	Pamięć w GB.
gpu	0	Liczba GPU.
gpu_type	""	Identyfikator GPU CGC.
volumes	Wolumeny z App	Podłączone wolumeny.
environment	{}	Zmienne środowiskowe dodawane do zmiennych z App.
repository_secret	Sekret z definicji obrazu	Nazwa sekretu z danymi dostępu do prywatnego rejestru obrazów. Zastępuje wartość z definicji obrazu.
shm_size	0	Rozmiar pamięci współdzielonej w GB.
node_port_enabled	False	Udostępnia usługę przez port na węzłach klastra (NodePort).
ingress	True	Udostępnia usługę pod publicznym adresem przez ingress.

Dla entity="custom" funkcja może zwrócić polecenie powłoki jako niepusty tekst, obiekt ShellCommand albo listę lub krotkę argumentów dla programu startowego obrazu (entrypointu). Dla szablonu zwraca listę lub krotkę argumentów; nie podawaj w deklaracji własnego obrazu ani polecenia powłoki. entity i additional_ports w app.inference() przekazuje się wyłącznie po nazwie.

Ograniczenia list argumentów

Listy przetwarza backend: "--port 8000" jest dzielone na opcję i wartość. Elementy z więcej niż jedną spacją są odrzucane, a powtarzające się klucze mogą być nadpisywane. Dla złożonych poleceń użyj ShellCommand.

deploy()

endpoint = service.deploy(
    *function_args,
    wait=False,
    reuse_existing=False,
    resource_timeout_seconds=600,
    poll_seconds=5,
    **function_kwargs,
)

Tworzy zasób i jego porty, a następnie zwraca DeployedEndpoint. Dodatkowe porty wymuszają oczekiwanie na stan Running nawet przy wait=False, ponieważ backend może dodać je dopiero do dostępnego zasobu. W razie błędu konfiguracji portów utworzony zasób pozostaje, aby można było go sprawdzić i samodzielnie usunąć.

Jeśli sprawdzanie gotowości zakończy się błędem lub przekroczy czas oczekiwania, SDK przerywa dodawanie portów i pozostawia zasób. Nie usuwa portów dodanych wcześniej. Wyjątek zawiera nazwę zasobu oraz dostępne pola code, reason i details.

Przy reuse_existing=False istniejący zasób o tej samej nazwie powoduje błąd. Wartość True pozwala go ponownie użyć i dodać brakujące porty, ale nie aktualizuje obrazu, polecenia, środowiska ani istniejących portów.

DeployedEndpoint

Właściwość albo metoda	Domyślne argumenty	Wartość zwrotna
url	Brak	Publiczny adres głównego portu. Zgłasza SDKException, gdy główny port ma ingress=False.
exists()	Brak	Informacja, czy lista zasobów zawiera pod, którego etykieta app-name wskazuje nazwę tego zasobu.
refresh_url()	Brak	Odświeżony publiczny adres głównego portu.
status()	Brak	Running albo Pending.
wait()	poll_seconds=5, timeout_seconds=600	Running albo Timeout.
wait_http()	path="", status_code=200, poll_seconds=5, timeout_seconds=300, request_timeout=10	Pomyślna odpowiedź HTTP albo SDKException.
post_json()	path, payload, headers=None, timeout=30	Zdekodowany JSON albo tekst odpowiedzi.
logs()	timestamps=False	Odpowiedź z logami zasobu.
delete()	Brak	Odpowiedź na żądanie usunięcia zasobu.

Jeśli główny port ma ingress=False, nie używaj url, wait_http() ani post_json(). Porty wewnętrzne są dostępne z zadań w tej samej przestrzeni nazw Kubernetes. Obiekt DeployedEndpoint udostępnia adres tylko głównego portu.

Przy port_name="http" adres zwykle prowadzi do ścieżki /; inne nazwy dodają zwykle prefiks /<port_name>. Korzystaj z adresu zwróconego przez SDK i zadbaj, aby aplikacja obsługiwała trasy z tym prefiksem. Wynik Running z metody wait() nie potwierdza jeszcze gotowości HTTP.

RTDetrWorkflow

Import klasy:

from cgc.sdk.recipes.rtdetr import RTDetrConfig, RTDetrWorkflow

RTDetrWorkflow(name, image, volume=None, config=None, inference_name=None)

Argument	Domyślnie	Znaczenie
name	Wymagany	Nazwa workflow i domyślna nazwa usługi modelu.
image	Wymagany	Obraz używany przez RT-DETR.
volume	None	Wolumen wymagany do przechowywania zbiorów danych i trenowania modelu. Nie jest potrzebny przy korzystaniu z gotowego modelu.
config	RTDetrConfig()	Konfiguracja modelu i zasobów.
inference_name	Nazwa workflow	Osobna nazwa usługi modelu.

RTDetrConfig używa tych samych pól konfiguracyjnych co wspólny workflow Ultralytics. Najważniejsze pola to model_name, inference_cpu, inference_memory, inference_gpu, inference_gpu_type, inference_port i inference_port_name.

RoboflowDataset

Import klas do obsługi zbiorów danych:

from cgc.sdk.recipes.datasets import RoboflowDataset, VolumeDataset

RoboflowDataset(
    workspace_id,
    project_id,
    version,
    format="yolov11",
    api_key="",
    target_class="",
)

Argument	Domyślnie	Znaczenie
workspace_id	Wymagany	Identyfikator obszaru roboczego w Roboflow.
project_id	Wymagany	Identyfikator projektu Roboflow.
version	Wymagany	Numer wersji zbioru danych.
format	yolov11	Format eksportu Roboflow.
api_key	""	Klucz API Roboflow używany przez job pobierający dane.
target_class	""	Opcjonalne metadane klasy docelowej.

Przekaż go do YoloWorkflow.download() albo RTDetrWorkflow.download(), a następnie wywołaj submit() na zwróconej definicji joba. Zobacz Zbiory danych.

VolumeDataset

VolumeDataset(name, path, data_yaml="data.yaml", target_class="")

Argument	Domyślnie	Znaczenie
name	Wymagany	Nazwa zbioru danych używana w kodzie.
path	Wymagany	Katalog zbioru danych na wolumenie workflow.
data_yaml	data.yaml	Plik konfiguracji zbioru danych dla Ultralytics.
target_class	""	Opcjonalne metadane klasy docelowej.

Workflow sprawdza plik konfiguracji zbioru na wolumenie zamiast pobierać dane.

YoloWorkflow

Import klasy:

from cgc.sdk.recipes.yolo import YoloConfig, YoloWorkflow

YoloWorkflow(name, image, volume=None, config=None, inference_name=None)

Używa tego samego konstruktora i wspólnych pól konfiguracyjnych Ultralytics co RTDetrWorkflow. YoloConfig domyślnie ustawia model_name na yolo11n.pt.

Ważne metody:

Metoda	Znaczenie
download(dataset)	Zwraca definicję joba pobierającego zbiór danych lub sprawdzającego jego konfigurację.
train(dataset, model_id=None)	Zwraca definicję joba trenującego model YOLO.
deploy_inference(dataset, model_id=None, wait=False, reuse_existing=False)	Uruchamia usługę z modelem wytrenowanym w workflow.
deploy_pretrained_inference(wait=False, gpu=None, gpu_type=None, reuse_existing=False)	Uruchamia usługę z gotowym modelem, bez potrzeby podłączania wolumenu.

Zobacz Wykrywanie obiektów z YOLO.