Zbuduj multimodalny proces z Rivya API

Dobra integracja Rivya API to coś więcej niż pojedyncze żądanie wysłane do jednego modelu.

Większość rzeczywistych procesów produktowych tworzy krótki łańcuch: wybór modelu, przygotowanie danych wejściowych, ewentualne przesłanie plików referencyjnych, utworzenie zadania, śledzenie statusu, rozliczenie punktów i powiadomienie produktu o gotowym wyniku.

Ten artykuł pokazuje sposób planowania. Najkrótszą działającą ścieżkę znajdziesz w Szybkim starcie Rivya API, a dokładne pola żądań w dokumentacji API.

Poniższy proces opisuje wdrożony kontrakt Public API. Przed rozpoczęciem prac potwierdź, że dostęp do Public API jest włączony dla wdrożenia i konta, wybrany model obsługuje API, a opcjonalne funkcje, takie jak webhooki, są rzeczywiście dostępne.

Zacznij od konkretnego momentu w produkcie

Przed wyborem punktów końcowych opisz w jednym zdaniu moment, w którym produkt ma użyć API.

Przykłady:

• Utwórz szkic obrazu produktu, gdy sprzedawca prześle opis oferty.

• Wygeneruj koncepcję krótkiego filmu, gdy kierownik kampanii zatwierdzi kierunek nieruchomego obrazu.

• Wyślij turę czatu z wewnętrznego narzędzia badawczego i przekaż odpowiedź użytkownikowi w strumieniu.

• Prześlij obraz referencyjny, utwórz żądanie obsługiwanego modelu i powiadom użytkownika, gdy wynik będzie gotowy.

Takie zdanie zapobiega przekształceniu integracji w przypadkowy zbiór wywołań API.

Rozpisz proces przed napisaniem kodu

Skorzystaj z tej tabeli przed otwarciem schematu żądania.

Proces powinien być na tyle jasny, aby każdy użyty obszar API miał konkretny cel.

Krok 1: utwórz klucz dla integracji

Utwórz klucz API dla konkretnej aplikacji, środowiska lub procesu, który będzie z niego korzystać.

Nie używaj jednego klucza do wszystkiego. Nazwy wskazujące przeznaczenie ułatwią późniejszy przegląd:

• production-image-workflow

• staging-video-tests

• internal-chat-assistant

• podpisane webhooki ukończenia, jeśli ta funkcja jest włączona

Przeczytaj Uwierzytelnianie API, zanim zapiszesz klucz. Pełna wartość tajna jest wyświetlana tylko raz, dlatego zespół powinien od razu umieścić ją w odpowiednim magazynie sekretów po stronie serwera.

Krok 2: wybierz modele z publicznej listy API

Nie wpisuj modelu na stałe tylko dlatego, że zadziałał w teście ręcznym.

Użyj Modele API i Referencja modeli API, aby potwierdzić:

• publiczny identyfikator modelu

• czy jest dostępny przez API

• obsługiwany rodzaj danych wejściowych

• wymagania dotyczące polecenia i parametrów

• czy Files API jest wymagane

• zasady dotyczące punktów i informacje o gotowości

Na tym etapie wiele integracji staje się prostszych. Model idealny do ręcznego testu w Studio nie musi być najlepszym pierwszym modelem dla zautomatyzowanego procesu produktowego.

Krok 3: Zdecyduj, Czy Files API Jest Częścią Pierwszej Wersji

Jeśli model może działać na podstawie tekstu, nie dodawaj innych danych wejściowych do pierwszej wersji.

Dodaj Files API tylko wtedy, gdy proces rzeczywiście wymaga mediów referencyjnych.

Gdy tak jest, zdefiniuj:

• jakie rodzaje plików przyjmuje produkt

• kto odpowiada za etap porządkowania plików

• co dzieje się po nieudanym przesłaniu

• jak zwrócone dane pliku trafiają do parametrów modelu

• czy ten sam plik ma być używany ponownie, czy ponownie przesyłany

Dzięki temu niewygodna obsługa plików nie zostanie ukryta za estetycznym przyciskiem generowania.

Krok 4: utwórz jedno zadanie generowania

Typowy proces generowania obrazu, wideo lub audio wygląda tak:

1. przygotuj identyfikator modelu, polecenie i obsługiwane parametry

2. dodaj klucz idempotencji do bezpiecznych ponowień

3. wyślij żądanie przez punkt końcowy generowania

4. zapisz publiczny identyfikator zadania

5. odpytuj status, aż zadanie osiągnie stan końcowy

Kształt żądania opisuje Utwórz generowanie, a obsługę wyniku Status generowania.

Produkt powinien przedstawiać queued, processing, succeeded i failed jako zrozumiałe stany. Użytkownik nie powinien odczytywać szczegółów systemowych ani zgadywać, dlaczego zadanie trwa długo.

Krok 5: użyj Chat API dla modeli czatu

Modele czatu powinny korzystać z Chat API, a nie z punktu końcowego generowania.

To ma znaczenie, bo chat work ma inne behavior:

• tury czatu mogą należeć do sesji utworzonych przez API

• odpowiedzi bez strumienia i przesyłane przez SSE wymagają innej obsługi użytkownika

• załączniki obrazów korzystają z identyfikatorów plików z Files API

• rozliczenie punktów dotyczy tury czatu, a nie zwykłego asynchronicznego zadania medialnego

Jeśli produkt potrzebuje odpowiedzi asystenta we własnym interfejsie, Chat API może być właściwym wyborem. Gdy użytkownik nadal bada pomysły, lepiej może sprawdzić się Rivya Chat lub Studio.

Krok 6: zacznij od odpytywania, później dodaj webhooki

W pierwszej wersji regularne odpytywanie jest łatwiejsze do zrozumienia.

Jeśli webhooki są włączone w danym wdrożeniu, dodaj Webhooki API, gdy:

• produkt obsługuje wiele zadań asynchronicznych

• oczekujący klienci nie powinni samodzielnie odpytywać statusu

• dalsze systemy potrzebują podpisanych zdarzeń ukończenia

• obsługa ponowień i duplikatów jest już zaprojektowana

Odbiorniki webhooków powinny być proste i ścisłe: weryfikuj podpis, bezpiecznie obsługuj duplikaty, aktualizuj jeden rekord produktu i zapisuj wyłącznie bezpieczne dane.

Krok 7: pokaż punkty w produkcie

Rivya API korzysta z tych samych punktów konta co Studio.

Twoja integration powinna zdecydować, ile z tego pokazać. Minimum, jakie zespół powinien znać:

• do którego konta należy klucz API

• który proces może zużywać punkty

• co dzieje się, gdy punktów jest zbyt mało

• jak wyjaśniane są nieudane zadania generowania

• dokąd skierować pytania o punkty i rozliczenia

Zasady portfela widoczne dla użytkownika opisują Kredyty API, Przewodnik po punktach i rozliczeniach Rivya oraz Jak rozumieć punkty, pakiety i plany Rivya.

Mała pierwsza wersja

Dobra pierwsza wersja jest celowo ograniczona.

Na przykład:

1. jeden klucz API

2. jeden wybrany model obrazu

3. bez przesyłania plików

4. jedno żądanie generowania

5. jedna ścieżka odpytywania statusu

6. jeden prosty podgląd wyniku w produkcie

7. jeden jasny komunikat błędu dotyczący kredytów

Taka pierwsza wersja potwierdza działanie połączenia przed dodaniem kolejnych elementów.

Bardziej Kompletna Wersja

Gdy pierwsza wersja działa, pełniejszy proces może obejmować:

• Files API dla obrazów lub filmów referencyjnych

• kontrolki parametrów specyficzne dla modelu

• idempotencję powiązaną z rekordem produktu

• podpisane webhooki ukończenia

• Chat API dla tur asystenta

• strumień zdarzeń po stronie serwera, gdy czat wymaga wyniku na żywo

• widoki administracyjne lub pomocy dla nieudanych zadań

Każdy dodatek powinien odpowiadać na rzeczywistą potrzebę produktu. Jeśli jedynie powiększa demonstrację, pozostaw go poza zakresem.

Częste błędy integracji

Unikaj następujących wzorców:

• zaczynanie od wszystkich funkcji API naraz

• ukrywanie zużycia punktów przed właścicielem konta

• przenoszenie do API założeń właściwych tylko dla Studio

• traktowanie przesyłania plików jako dodatku na końcu

• ponawianie żądań generacji bez idempotencji

• używanie Chat API do zadań, które powinny być asynchronicznym generowaniem

• używanie punktów końcowych generowania do tur czatu

• zapisywanie pełnych kluczy API, sekretów webhooków lub danych plików tymczasowych

Najbezpieczniejszy proces API jasno określa własność, stany i obsługę błędów.

Dokąd Przejść Dalej

• Zacznij od Developers, aby otworzyć publiczne centrum API.

• Użyj Szybkiego startu Rivya API, aby wysłać pierwsze żądanie.

• Użyj Modeli API przed wyborem identyfikatorów modeli.

• Użyj Files API tylko wtedy, gdy model rzeczywiście potrzebuje mediów referencyjnych.

• Użyj Chat API do tur czatu i odpowiedzi przesyłanych strumieniowo.

• Użyj Webhooków API, gdy odpytywanie już nie wystarcza i dostęp do webhooków jest włączony.

• Jeśli proces nadal wymaga ręcznego poszukiwania kierunku, przeczytaj Kiedy używać Rivya API zamiast Studio, zanim go zautomatyzujesz.