Vision API Polski
Przegląd Rozwiązania
API Vision jest przeznaczone do zapewnienia kompleksowego rozwiązania dla zadań związanych z widzeniem komputerowym. Łączy ono przetwarzanie wstępne, inferencję, postprocessing i serwowanie w jednym żądaniu do endpointu. Wykorzystuje Triton jako źródło inferencji, w połączeniu z operacjami przetwarzania obrazu i wideo przyspieszonymi dzięki GPU . Do serwowania strumieni używa przyspieszonych przez GPU Serwerów Gstreamer.
Kluczowe funkcje:
- Plik obrazu jako wejście, detekcja, przetworzony plik obrazu jako wyjście
- Plik wideo jako wejście, detekcja, przetworzony plik wideo jako wyjście
- Strumień jako wejście, detekcja, przetworzony strumień RTSP jako wyjście
Jak uruchomić
Ponieważ Triton jest źródłem inferencji, najpierw musisz upewnić się, że jest on skonfigurowany i włączony Triton.
Na ten moment Vision API akceptuje tylko standardowe wyjście modelu detekcji - [x1, x2, y1, y2, score, class_1, class_2 ..], jeżeli z jakiegoś powodu twój model ma inny output, API do nie przyjmie.
API Vision jest dostępne jako zasób obliczeniowy i wymaga różnych zasobów w zależności od wybranych operacji przetwarzania i rozdzielczości źródła. Aplikacja zawsze wymaga GPU, które obsługuje operacje przetwarzania obrazu. Najlepszym wyborem będzie A5000. Na początek zalecamy 1,5 rdzenia CPU i 1,5 GB RAM na każde wideo/strumień, który będziesz przetwarzać. Te wartości mogą wzrosnąć, gdy dodasz operacje lub użyjesz źródeł o wyższej rozdzielczości.
Aby uruchomić instancję, użyj następującej komendy:
cgc compute create --name vision-api -c 8 -m 12 -g 1 -gt A5000 vision-api
Po inicjalizacji możesz uzyskać dostęp do Swagger, aby zobaczyć wszystkie endpointy pod adresem:
https://vision-api.<namespace>.cgc-waw-01.comtegra.cloud/docs
Jak używać
Każdy endpoint będzie wymagał od Ciebie przekazania tokenu aplikacji jako źródła autoryzacji. Jest to ten sam token aplikacji, który możesz zobaczyć przy użyciu:
cgc compute list -d
Jak napisano w Kluczowych funkcjach, istnieją 3 sposoby korzystania z Vision API w zależności od pożądanego wejścia i wyjścia. Pierwsze 2, w których możesz uzyskać plik jako wyjście, będą miały podobny sposób użycia.
Najpierw prześlij plik na
/image/upload
lub /video/upload
i otrzymasz uuid, który reprezentuje źródło. Następnie możesz go uwzględnić w żądaniu do
image/to-image
lub video/to-video
.
Zwróć uwagę na treść żądania:
{
"source_file_uuid": "98ada9eb-daf6-4ee4-b4be-9fab7abdf619",
"tritonServer": {
"triton_url": "triton",
"infer_model_name": "yolov8n",
"version": "1"
},
"inference": {
"confidence_threshold": 0.25,
"iou_threshold": 0.45
},
"postprocess": {
"bbox": {
"apply": true,
"rectangle_color": "default",
"text_color": "default",
"rectangle_thickness": 2,
"text_size": 0.5,
"text_thickness": 2,
"include_text": false
},
"blur": {
"apply": false,
"blur_intensity": [99, 99]
},
"pose": {
"apply": true,
"keypoints": {
"apply": true,
"keypoint_color": [0, 165, 255],
"line_color": [255, 165, 0],
"radius": 5,
"line_thickness": 2
},
"pose_classifier": {
"apply": true,
"slope_threshold": 40,
"fall_detector": {
"apply": false,
"alert_threshold": 2
}
}
}
},
"output_format": "jpg"
}
Tutaj możesz wpisać otrzymane uuid i zmienić wszystko, co chcesz w inferencji i postprocessingu. Po wypełnieniu treści żądania, wyślij je i poczekaj. Gdy przetwarzanie się zakończy, otrzymasz plik zawierający przetworzony obraz lub wideo.
Trzeci endpoint, który zwraca strumień RTSP, będzie wymagał podobnego żądania, ale natychmiast zwróci adres URL strumienia. Możesz go przechwycić, korzystając z tego adresu URL. Domyślnie strumień RTSP będzie dostępny tylko w Twojej przestrzeni nazw. Jeśli chcesz go zobaczyć na zewnętrznych maszynach, przejdź do sekcji Szczegółowe informacje.
Gdy nie potrzebujesz już strumienia, możesz go usunąć, przekazując stream_id do /stream/delete-stream.
Dostępny jest również endpoint informacyjny info/get-models, który pobiera modele dostępne na Triton z informacjami o nich.
Jeśli wolisz używać API nie przez Swagger, możesz wysyłać żądania w taki sposób:
curl -X 'POST' \
'https://<appname>.<namespace>.cgc-waw-01.comtegra.cloud/video/to-stream' \
-H 'accept: application/json' \
-H 'app-token: 8d23ae613a4e46119f4d52cb25e8b551' \
-H 'Content-Type: application/json' \
-d '{
"source_file_uuid": "ac839d89-14c7-4116-b5d8-30c34c714971",
"tritonServer": {
"triton_url": "triton",
...
}
Wstawiając token aplikacji w nagłówku i parametry w body.
Szczegółowe informacje
Opcjonalne parametry aplikacji
Dodatkowe opcjonalne parametry, które możesz przekazać do polecenia create w CLI:
MAX_STREAMS
- maksymalna liczba strumieni, które mogą działać jednocześnie, domyślnie jest to liczba rdzeni CPU / 2.BUFFER_SIZE
- rozmiar buforów sieciowych używanych przez aplikację. Najlepiej ustawić go na rozmiar nie większy niż Twoje MTU. Domyślnie 9000.GST_SERVERS
- liczba serwerów Gstreamer. Domyślnie jest to MAX_STREAMS / 5. Jeśli Twoje źródło ma wyższą lub niższą rozdzielczość, możesz eksperymentować z tym parametrem, aby uzyskać optymalne zużycie zasobów.
Parametry żądania
Treść żądania ma kilka sekcji, zaczynając od sekcji Triton, gdzie musimy określić hosta Triton. W przypadku CGC, Triton postawiony w tym samym namespace będzie dostępny pod nazwą kontenera, na przykład: triton. Dodatkowo wybieramy model, którego chcemy użyć, jego wersję oraz triton_request_concurrency, który jest dostępny wyłącznie dla endpointu wideo i wskazuje, ile klientów będzie jednocześnie zapytaniać Triton. Jest to przykład parametru, który wpływa zarówno na czas wykonania zapytania, jak i zużycie zasobów, co należy wziąć pod uwagę.
Sekcja inferencji dotyczy typowych tematów dla inferencji modelu:
- confidence threshold
- intersection over union threshold
Sekcja postprocessingu dotyczy wszystkiego, co dzieje się po uzyskaniu wyników inferencji. Możemy wybrać nakładanie ramek w miejscach, gdzie model wykrył obiekty, rozmywanie tych obszarów lub użycie filtra Kalmana do poprawy ciągłości detekcji.
Konfiguracja Trackera
Oprócz opcji postprocessingu, takich jak nakładanie ramek, rozmazywanie obszarów lub używanie filtrów Kalmana, użytkownicy mogą modyfikować parametry trackera, aby zoptymalizować precyzję detekcji i poprawić funkcjonalność różnych funkcji, takich jak klasyfikacja pozycji, zliczanie obiektów oraz filtracja Kalmanem dla zapewnienia ciągłości detekcji. Eksperymentując z tymi parametrami, użytkownicy mogą dostosować swoje aplikacje, aby uzyskać lepszą dokładność i niezawodność.
Dostępne parametry do dostosowania:
Parametr | Domyślna wartość | Opis | Uwagi |
---|---|---|---|
track_activation_threshold | 0.25 | Próg pewności detekcji dla aktywacji śledzenia. | Zwiększenie tej wartości poprawia dokładność i stabilność, ale może pomijać prawidłowe detekcje. Zmniejszenie zwiększa kompletność, ale ryzykuje wprowadzenie szumu i niestabilności. |
lost_track_buffer | 30 | Liczba klatek buforowanych po utracie śledzenia. | Zwiększenie tej wartości zmniejsza fragmentację śledzenia lub znikanie z powodu krótkich przerw w detekcji. |
minimum_matching_threshold | 0.8 | Próg dopasowania śledzeń z detekcjami. | Zwiększenie tej wartości poprawia dokładność, ale ryzykuje fragmentacją. Zmniejszenie poprawia kompletność, ale zwiększa ryzyko fałszywych pozytywów. |
frame_rate | "auto" | Liczba klatek na sekundę wideo. Jeśli ustawiona na "auto," liczba klatek na sekundę jest automatycznie wyodrębniana ze źródła. | Ustaw stałą liczbę klatek, jeśli liczba klatek na sekundę źródła jest zmienna lub nieznana. |
minimum_consecutive_frames | 1 | Liczba kolejnych klatek, które obiekt musi być śledzony, zanim zostanie uznany za prawidłowy. | Zwiększenie tej wartości zapobiega tworzeniu przypadkowych śledzeń z fałszywej lub podwójnej detekcji, ale ryzykuje pomijanie krótszych śledzeń. |
Część informacji o parametrach została pobrana z oficjalnej dokumentacji biblioteki Supervision.
Estymacja Pozy
Estymację pozy można skonfigurować przez ustawienie pose
na true podczas używania modeli "Pose".
Sekcja estymacji pozy zawiera następujący zestaw parametrów:
Parametr | Domyślna wartość | Opis | Uwagi |
---|---|---|---|
pose.apply | false | Włącza lub wyłącza funkcję estymacji pozycji. | Ustaw na true , aby aktywować estymację pozycji. Wymagane podczas korzystania z modeli "Pose Estimation". |
keypoints.apply | true | Włącza lub wyłącza rysowanie punktów reprezentujących stawy ciała. | Punkty kluczowe reprezentują wykryte stawy. |
keypoints.keypoint_color | [0, 165, 255] | Ustawia kolor BGR dla punktów kluczowych. | [0, 165, 255] dla żółtego. |
keypoints.line_color | [255, 165, 0] | Ustawia kolor BGR dla linii łączących punkty kluczowe. | [255, 165, 0] dla niebieskiego. |
keypoints.radius | 5 | Określa promień punktów kluczowych w pikselach. | Większe wartości zwiększają widoczność punktów kluczowych na klatce obrazu. |
keypoints.line_thickness | 2 | Określa grubość linii łączących punkty kluczowe w pikselach. | Grubsze linie poprawiają widoczność przy wyższych rozdzielczościach klatek obrazu. |
pose_classifier.apply | false | Włącza lub wyłącza klasyfikację pozycji. | Dostępne pozycje: Standing (stojąca) lub Laying (leżąca). |
pose_classifier.slope_threshold | 40 | Ustawia kąt nachylenia do klasyfikacji pozycji jako leżącej. | Dostosuj wartość, aby precyzyjnie dostroić dokładność klasyfikacji pozycji. |
fall_detector.apply | false | Włącza lub wyłącza funkcję wykrywania upadków. | Alerty wykrywania upadków mogą być przydatne w aplikacjach o krytycznym znaczeniu dla bezpieczeństwa. |
fall_detector.alert_threshold | 2 | Określa próg czasowy (w sekundach) dla uruchomienia alertu upadku. | Niższe wartości zwiększają czułość wykrywania upadków; dostosuj w zależności od wymagań. Domyślnie alert o upadku zostanie wywołany, jeśli osoba leży przez dwie sekundy. |
Podczas korzystania z modeli do estymacji pozycji, należy ustawić parametr pose
na true, aby zapewnić prawidłowe działanie.
Obecnie funkcja estymacji pozy obsługuje tylko modele YOLO-pose z 17 punktami kluczowymi w formacie COCO.
Liczenie Obiektów
Funkcja Liczenia Obiektów (object_counter) umożliwia zliczanie określonych klas obiektów, które poruszają się przez linię podziału w klatce wideo. Jest to szczególnie przydatne w scenariuszach takich jak monitorowanie ruchu drogowego, liczenie ludzi lub przedmiotów oraz analiza wzorców ruchu.
Poniższe parametry są dostępne do konfiguracji funkcji Liczenia Obiektów:
Parametr | Domyślna wartość | Opis | Uwagi |
---|---|---|---|
apply | true | Włącza lub wyłącza funkcję liczenia obiektów. | Ustaw true , aby aktywować funkcję liczenia obiektów. |
line_type | "axis" | Określa typ linii używanej do liczenia obiektów. Wybierz "axis" dla linii poziomej/pionowej lub "custom" dla linii zdefiniowanej ręcznie. | Jeśli wybierzesz "axis" , musisz określić oś (axis ), na której linia będzie rysowana. Jeśli wybierzesz "custom" , określ parametry line_start i line_end . |
axis | "x" | Określa oś, na której rysowana jest linia dzieląca. Używane tylko, gdy line_type="axis" . | Wybierz "x" dla linii pionowej lub "y" dla linii poziomej. |
position | "1/2" | Określa pozycję linii dzielącej na wybranej osi. Używane tylko, gdy line_type="axis" . | Akceptuje liczbę całkowitą (pozycję w pikselach) lub ułamek jako ciąg znaków (np. "1/2" dla środka klatki). |
line_start | [null, null] | Definiuje punkt początkowy linii niestandardowej. Używane tylko, gdy line_type="custom" . | Podaj współrzędne punktu początkowego linii w formacie [x, y] . Dowiedz się więcej... |
line_end | [null, null] | Definiuje punkt końcowy linii niestandardowej. Używane tylko, gdy line_type="custom" . | Podaj współrzędne punktu końcowego linii w formacie [x, y] . Dowiedz się więcej... |
class_id_map | {"person": 0} | Mapuje nazwy klas obiektów na odpowiadające im identyfikatory klas. | Co najmniej jedna klasa musi zostać określona. Jeśli nie jesteś pewien identyfikatorów klas, skorzystaj z aplikacji Netron. |
draw_counts | true | Wyświetla liczbę obiektów po obu stronach linii dzielącej. | Pokazuje, ile obiektów z każdej klasy przekroczyło linię w obu kierunkach. |
draw_dividing_line | true | Rysuje linię dzielącą na klatce wideo. | Przydatne do wizualnego wskazania, gdzie obiekty są liczone. |
line_color | [255, 255, 255] | Ustawia kolor linii dzielącej w formacie BGR. | [255, 255, 255] oznacza białą linię. |
line_thickness | 2 | Określa grubość linii dzielącej. | Dostosuj w zależności od rozdzielczości klatki wideo, aby linia była bardziej widoczna. |
Jak określić współrzędne dla parametrów line_start
i line_end
Podczas definiowania punktu początkowego i końcowego linii niestandardowej należy podać współrzędne w formacie [x, y]
. Współrzędne te reprezentują pozycje w siatce klatki wideo lub obrazu. Przykład działania:
- Lewy górny róg: Lewy górny róg klatki to punkt
(0, 0)
. - Oś pozioma (X): Współrzędna
x
zwiększa się w miarę przesuwania się w prawo wzdłuż klatki, co odpowiada szerokości klatki. - Oś pionowa (Y): Współrzędna
y
zwiększa się w miarę przesuwania się w dół klatki, co odpowiada wysokości klatki.
Na przykład:
line_start
: Określa punkt początkowy linii. Na przykład[0, 1080]
umieści początek w lewym dolnym rogu klatki o rozdzielczości 1920x1080.line_end
: Określa punkt końcowy linii. Na przykład[1920, 0]
umieści koniec w prawym górnym rogu klatki o rozdzielczości 1920x1080.
Każda opcja ma swoje podopcje, które modyfikują ich zachowanie. Ponownie, ważne jest, aby pamiętać, że im więcej postprocessingu dodamy, tym dłużej potrwa zapytanie i tym więcej zasobów zostanie zużytych. Wszystkie opcje poza ramkami są domyślnie wyłączone. W przypadku kolorów domyślna opcja - "default" oznacza, że każda wykryta klasa będzie miała przypisany inny losowy kolor. Jeśli chcesz użyć określonego koloru, możesz podać go w formie tablicy RGB - np.: [255, 0, 0], wtedy KAŻDA klasa będzie miała ten kolor. Może to być przydatne, gdy masz tylko jedną lub kilka klas.
Na koniec mamy format wyjścia. Obecnie zaimplementowany jest tylko jeden format, więc domyślne ustawienie nie powinno być zmieniane.
Strumienie RTSP
RTSP używa TCP do transportu, ale CGC nie zapewnia opcji otwarcia portu TCP z poziomu CLI. Jeśli chcesz zobaczyć strumień na zewnętrznych maszynach, będziesz musiał ręcznie dodać porty TCP.
Every Gstreamer server uses separate TCP port. First one serves on 9001 and every another on the next one, so 9002, 9003, ... . You will need to add TCP port for every one of them. Każdy z serwerów Gstreamera używa oddzielnego portu. 1 serwuje strumienie na porcie 9001, a reszta na kolejnych - 9002. 9003 .... Będziesz musiał otworzyć port TCP dla każdego z nich.
Błędy i rozwiązywanie problemów
Ta sekcja zawiera informacje o tym, gdzie zwracane są błędy podczas przetwarzania i jak je interpretować. Zrozumienie komunikatów o błędach i ich przyczyn pozwoli szybko rozwiązać problemy i zapewnić płynne działanie systemu.
Lokalizacja błędów
Większość błędów będzie widoczna w Responses > Server Response. Szczegółowe informacje o błędach można znaleźć w części Response Body odpowiedzi serwera.
Na przykład błąd dotyczący nieistniejącego pliku wideo (który może wystąpić, gdy parametr source_file_uuid
jest nieprawidłowy) będzie wyglądał następująco:
Błędy w parametrach
W przypadku problemów z dostarczonymi parametrami w odpowiedzi znajdą się szczegółowe komunikaty o tym, co poszło nie tak. Poniżej znajduje się przykład takiego błędu:
{
"detail": [
{
"type": "value_error",
"loc": [
"body",
"postprocess",
"pose",
"pose_classifier",
"slope_threshold"
],
"msg": "Value error, Slope threshold must be between 0 and 90 degrees",
"input": 150,
"ctx": {
"error": {}
},
"url": "https://errors.pydantic.dev/2.10/v/value_error"
}
]
}
W tym przykładzie:
- Opis błędu: Parametr
slope_threshold
został podany z nieprawidłową wartością (150
). - Przyczyna: Prawidłowy zakres wartości dla
slope_threshold
to od 0 do 90 stopni. - Rozwiązanie: Zaktualizuj wartość
slope_threshold
, aby mieściła się w dopuszczalnym zakresie.
Odpowiedź z błędem zawiera:
- Typ: Wskazuje typ błędu, np.
value_error
. - Lokalizacja (
loc
): Pokazuje, gdzie w hierarchii parametrów wystąpił błąd. - Wiadomość (
msg
): Zawiera dokładny opis błędu. - Wprowadzone dane (
input
): Wyświetla podaną nieprawidłową wartość. - URL: Link do dokumentacji z dodatkowymi szczegółami dotyczącymi typu błędu.
Błąd modelu do estymacji pozycji
Jeśli pojawi się następujący błąd:
RuntimeError encountered during pose estimation: shape '[1, 17, 3]' is invalid for input of size 0. Are you sure you are using a pose estimation model?
Oznacza to, że funkcja estymacji pozycji została włączona, ale używany model nie obsługuje estymacji pozycji.
Rozwiązanie:
- Zmień model na taki, który obsługuje estymację pozycji (zobacz jak skonfigurować).
- Alternatywnie wyłącz funkcję
pose
, ustawiając parametrapply
nafalse
w sekcji parametrów dotyczącej pozycji.
Punkt końcowy stream/to-stream
zawsze zwraca adres URL dla strumienia wyjściowego. Jeśli zwrócony adres URL nie działa, logi można sprawdzić za pomocą następującego polecenia:
cgc logs <vision-api-compute-resource-name>
Na przykład dla powyższej konfiguracji polecenie wyglądałoby następująco:
cgc logs vision-api
To polecenie zapewni szczegółowe logi zasobów obliczeniowych Vision API, pomagając w diagnozowaniu i rozwiązywaniu problemów związanych ze strumieniem wyjściowym.
Ze względu na wieloprocesową naturę endpointu /stream błędy mogą pojawić się w CGC z opóźnieniem.