Multimodális munkafolyamat építése a Rivya API-val

Egy jó Rivya API-integráció nem csak egyetlen kérés egyetlen modellhez.

A legtöbb valódi termékfolyamat egy kisebb láncból áll: ki kell választani a megfelelő modellt, elő kell készíteni a bemenetet, szükség esetén referenciafájlokat kell feltölteni, el kell indítani a feladatot, figyelni kell az állapotot, kezelni kell a krediteket, és értesíteni kell a terméket, amikor az eredmény elkészült.

Ez a cikk a tervezési formát mutatja meg. A legrövidebb futtatható útvonalhoz használja a Rivya API gyorskezdés útmutatót, a pontos kérésmezőkhöz pedig az API-dokumentációt.

Az alábbi munkafolyamat a megvalósított Public API-szerződést írja le. Fejlesztés előtt ellenőrizze, hogy a Public API-hozzáférés engedélyezve van-e a telepítéshez és a fiókhoz, a kiválasztott modell API-képes-e, valamint az opcionális funkciók, például a webhookok, valóban elérhetők-e.

Kezdje a termékpillanattal

Mielőtt végpontokat választana, írja le egy mondatban a termékpillanatot.

Példák:

• Termékkép-vázlat létrehozása, amikor egy eladó beküldi a termékadatlap leírását.

• Rövid videókoncepció generálása, miután egy kampánymenedzser jóváhagyott egy állóképes irányt.

• Chatforduló küldése egy belső kutatási eszközben, majd a válasz streamelése vissza a felhasználónak.

• Referencia kép feltöltése, támogatott modellkérés elküldése, majd a felhasználó értesítése, amikor az eredmény elkészült.

Ez a mondat megakadályozza, hogy az integráció laza API-hívások gyűjteményévé váljon.

Térképezze fel a munkafolyamatot, mielőtt kódot ír

Használja ezt a táblázatot, mielőtt megnyitná a kérési sémát.

A munkafolyamatnak elég világosnak kell lennie ahhoz, hogy minden API-területnek legyen oka létezni.

1. lépés: Hozzon létre kulcsot az integrációhoz

Hozzon létre API-kulcsot ahhoz a konkrét alkalmazáshoz, környezethez vagy munkafolyamathoz, amely használni fogja.

Ne használjon egyetlen kulcsot mindenre. Ha a kulcsokat cél szerint nevezi el, később könnyebb lesz az ellenőrzés:

• production-image-workflow

• staging-video-tests

• internal-chat-assistant

• aláírt befejezési webhookok, ha ez a funkció engedélyezett

Olvassa el az API-hitelesítés dokumentációt, mielőtt eltárolja a kulcsot. A teljes titok csak egyszer jelenik meg, ezért a csapatának azonnal a megfelelő szerveroldali titoktárba kell mentenie.

2. lépés: Válasszon modelleket a nyilvános API-listából

Ne égesse be a modellt csak azért, mert egy kézi tesztben működött.

Az API modellek és a Modell API referencia alapján erősítse meg:

• a nyilvános modellazonosítót

• hogy elérhető-e az API-n keresztül

• a támogatott bemeneti módot

• a prompttal és paraméterekkel kapcsolatos elvárásokat

• hogy szükséges-e a Files API

• a kreditviselkedést és a készenléti megjegyzéseket

Itt sok integráció tisztábbá válik. Egy modell, amely kézi Studio-teszthez tökéletes, nem biztos, hogy a legjobb első modell egy automatizált termékfolyamathoz.

3. lépés: Döntse el, része-e a Files API az első verziónak

Ha a modell szöveges bemenetről is futtatható, tartsa az első verziót csak szövegesnek.

A Files API használatát csak akkor adja hozzá, amikor a munkafolyamatnak valóban szüksége van referenciamédiára.

Amikor szüksége van rá, határozza meg:

• milyen fájltípusokat fogad el a termék

• ki felel a fájltakarítási lépésért

• mi történik, ha a feltöltés sikertelen

• hogyan kerül a visszakapott fájladat a modellparaméterekbe

• ugyanazt a fájlt újra kell-e használni, vagy ismét fel kell tölteni

Így a törékeny fájlélmény nem bújik el egy tisztának tűnő generálás gomb mögött.

4. lépés: Küldjön be egy generálási feladatot

Kép-, videó- és hanggenerálásnál a szokásos minta:

1. készítse elő a modellazonosítót, a promptot és a támogatott paramétereket

2. adjon hozzá idempotenciakulcsot a biztonságos újrapróbálkozásokhoz

3. küldje be a kérést a generálási végponton

4. mentse el a nyilvános feladatazonosítót

5. kérdezze le az állapotot, amíg a feladat végállapotba nem ér

A kérés formájához használja a Generálás létrehozása, az eredménykezeléshez pedig a Generálási állapot dokumentációt.

A terméknek a queued, processing, succeeded és failed állapotokat felhasználó számára látható állapotként kell kezelnie. Ne kényszerítse a felhasználókat rendszer-részletek olvasására vagy arra, hogy találgassák, miért lassú egy feladat.

5. lépés: Chatmodellekhez használja a Chat API-t

A chatmodelleknek a Chat API útvonalat kell használniuk, nem a generálási végpontot.

Ez azért fontos, mert a chatmunka másképp viselkedik:

• a chatfordulók API-val létrehozott munkamenetekhez tartozhatnak

• a nem streamelt és az SSE streamelt válaszok eltérő felhasználói élményt adnak

• a képmellékletek a Files API-ból származó fájlazonosítókat használnak

• a kreditek elszámolása a chatfordulót követi, nem egy szokásos aszinkron médiafeladatot

Ha a termékének saját felületén belüli asszisztensi válaszra van szüksége, a Chat API lehet a megfelelő út. Ha a felhasználó még ötleteket fedez fel, a Rivya Chat vagy a Studio jobb választás lehet.

6. lépés: Kezdje lekérdezéssel, majd adjon hozzá webhookokat

Első verzióban a lekérdezés könnyebben átlátható.

Ha a webhookok engedélyezve vannak a telepítéshez, adja hozzá az API-webhookokat, amikor:

• a terméknek sok aszinkron feladata van

• a várakozó klienseknek nem kellene közvetlenül lekérdezniük

• az alsóbb rendszereknek aláírt befejezési eseményekre van szükségük

• az újrapróbálkozás és a duplikátumkezelés már meg van tervezve

A webhook-fogadóknak egyszerűnek és szigorúnak kell lenniük: ellenőrizzék az aláírást, fogadjanak duplikátumbiztos eseményeket, frissítsenek egyetlen termékrekordot, és csak azt naplózzák, amit biztonságos naplózni.

7. lépés: Tegye láthatóvá a krediteket a termékben

A Rivya API ugyanazokat a fiókkrediteket használja, mint a Studio.

Az integrációnak el kell döntenie, ebből mennyit mutat meg. Legalább a csapatnak tudnia kell:

• melyik fiókhoz tartozik az API-kulcs

• melyik munkafolyamat fogyaszthat krediteket

• mi történik, ha túl kevés a kredit

• hogyan magyarázzák el a sikertelen generálási állapotokat

• hová irányítsanak valakit kreditekkel és számlázással kapcsolatos kérdések esetén

A felhasználó felé látható pénztárcamodellhez használja az API kreditek, a Rivya kreditek és számlázás útmutató és a Hogyan gondolkodjon a Rivya kreditekről, csomagokról és előfizetésekről útmutatókat.

Egy kis első verzió

Egy jó első verzió szándékosan korlátozott.

Például:

1. egy API-kulcs

2. egy kiválasztott képmodell

3. még nincs fájlfeltöltés

4. egy generálási kérés

5. egy állapotlekérdezési útvonal

6. egy egyszerű eredmény-előnézet a termékben

7. egy világos kredithiba-üzenet

Ez a verzió bizonyítja a kapcsolatot, mielőtt további mozgó részeket adna hozzá.

Egy teljesebb verzió

Miután az első verzió működik, egy teljesebb munkafolyamat hozzáadhatja:

• Files API referenciaképekhez vagy videókhoz

• modellspecifikus paramétervezérlőket

• a termékrekordhoz kötött idempotenciát

• aláírt webhookokat a befejezéshez

• Chat API-t asszisztensi fordulókhoz

• szerveroldali eseménystreamet, ahol a chatnek élő kimenetre van szüksége

• adminisztrátori vagy ügyféltámogatási nézeteket a sikertelen feladatokhoz

Minden hozzáadásnak valós termékigényre kell válaszolnia. Ha csak nagyobbnak mutatja a demót, hagyja ki.

Gyakori integrációs hibák

Kerülje ezeket a mintákat:

• az összes API-funkció egyszerre történő bevezetését

• a kreditfelhasználás elrejtését a fióktulajdonos elől

• Studio-only feltételezések használatát API-folyamatban

• a fájlfeltöltések utólagos gondolatként kezelését

• generálási kérések idempotencia nélküli újrapróbálását

• Chat API használatát olyan feladatokhoz, amelyeknek aszinkron generálásnak kellene lenniük

• generálási végpontok használatát chatfordulókhoz

• teljes API-kulcsok, webhook-titkok vagy ideiglenes fájladatok naplózását

A legbiztonságosabb API-munkafolyamat egyértelmű a tulajdonlásban, az állapotban és a hibakezelésben.

Merre tovább

• Induljon a Developers oldalról a nyilvános API-központhoz.

• Használja a Rivya API gyorskezdés útmutatót az első kérés futtatásához.

• Modellazonosítók kiválasztása előtt használja az API modellek dokumentációt.

• A Files API használatát csak akkor vezesse be, ha a modellnek valóban referenciamédiára van szüksége.

• Chatfordulókhoz és streamelt chatválaszokhoz használja a Chat API útvonalat.

• Használja az API-webhookokat, ha a lekérdezés már nem elég, és a webhook-hozzáférés engedélyezett.

• Ha a munkafolyamatnak továbbra is emberi feltárásra van szüksége, automatizálás előtt olvassa el a Mikor használja a Rivya API-t Studio helyett cikket.