Bina Aliran Kerja Multimodal dengan Rivya API

Integrasi Rivya API yang baik bukan sekadar satu request kepada satu model.

Kebanyakan aliran kerja produk sebenar mempunyai rantaian ringkas: pilih model yang betul, sediakan masukan, muat naik fail rujukan apabila perlu, hantar tugas, pantau status, kendalikan kredit dan maklumkan produk apabila hasil sudah sedia.

Artikel ini menunjukkan bentuk perancangan. Gunakan Rivya API Quickstart untuk laluan boleh jalan yang paling ringkas, dan gunakan dokumen API untuk medan request yang tepat.

Aliran kerja di bawah menerangkan kontrak API Awam yang telah dilaksanakan. Sebelum mula membina, pastikan akses API Awam diaktifkan untuk persekitaran pelaksanaan dan akaun anda, model yang dipilih sudah bersedia untuk API, serta ciri pilihan seperti webhook benar-benar tersedia.

Mulakan dengan Detik Produk

Sebelum memilih endpoint, terangkan detik produk dalam satu ayat.

Contoh:

• Cipta draf imej produk apabila penjual menghantar taklimat listing.

• Jana konsep video pendek selepas pengurus kempen meluluskan arah imej pegun.

• Hantar satu giliran chat dalam tool penyelidikan dalaman dan strim respons kembali kepada pengguna.

• Muat naik imej rujukan, hantar permintaan model yang disokong, dan maklumkan pengguna apabila hasil sudah sedia.

Ayat itu menghalang integrasi daripada menjadi himpunan longgar API call.

Petakan Aliran Kerja Sebelum Menulis Kod

Gunakan jadual ini sebelum membuka skema request.

Aliran kerja harus cukup jelas supaya setiap kawasan API mempunyai sebab untuk wujud.

Langkah 1: Cipta Kunci untuk Integrasi

Cipta kunci API untuk aplikasi, persekitaran atau aliran kerja khusus yang akan menggunakannya.

Elakkan menggunakan satu kunci untuk semuanya. Menamakan kunci mengikut tujuan memudahkan semakan kemudian:

• production-image-workflow

• staging-video-tests

• internal-chat-assistant

• webhook-smoke-test

Baca Pengesahan API sebelum menyimpan kunci. Rahsia penuh hanya dipaparkan sekali, jadi pasukan anda perlu segera menyimpannya dalam stor rahsia sisi pelayan yang betul.

Langkah 2: Pilih Model daripada Senarai API Awam

Jangan hard-code model hanya kerana ia berfungsi dalam ujian manual.

Gunakan Model API dan Rujukan API Model untuk mengesahkan:

• ID model awam

• sama ada ia tersedia melalui API

• mod masukan yang disokong

• jangkaan gesaan dan parameter

• sama ada API Fail diperlukan

• kelakuan kredit dan nota kesediaan

Di sinilah banyak integrasi menjadi lebih bersih. Model yang sempurna untuk ujian Studio manual mungkin bukan model pertama yang betul untuk aliran produk automatik.

Langkah 3: Tentukan Sama Ada API Fail Sebahagian daripada Versi Pertama

Jika model boleh berjalan daripada masukan teks, kekalkan versi pertama sebagai teks sahaja.

Tambah API Fail hanya apabila aliran kerja benar-benar memerlukan media rujukan.

Apabila ia diperlukan, tentukan:

• jenis fail yang diterima produk

• siapa memiliki langkah pembersihan fail

• apa yang berlaku apabila muat naik gagal

• bagaimana data fail yang dikembalikan dihantar ke parameter model

• sama ada fail yang sama patut digunakan semula atau dimuat naik lagi

Ini menghalang pengalaman fail yang rapuh daripada tersembunyi di sebalik butang generate yang kelihatan bersih.

Langkah 4: Hantar Satu Tugas Penjanaan

Untuk penjanaan imej, video dan audio, corak biasa ialah:

1. sediakan ID model, gesaan dan parameter yang disokong

2. tambah kunci idempotensi untuk percubaan semula yang selamat

3. hantar melalui endpoint penjanaan

4. simpan ID tugas awam

5. semak status sehingga tugasan mencapai keadaan akhir

Gunakan Create Generation untuk bentuk request dan Generation Status untuk pengendalian hasil.

Produk patut melayan queued, processing, succeeded dan failed sebagai state yang kelihatan kepada pengguna. Jangan suruh pengguna membaca butiran sistem atau meneka sebab sesuatu tugas lambat.

Langkah 5: Gunakan Chat API untuk Model Chat

Model chat harus menggunakan Chat API, bukan endpoint penjanaan.

Itu penting kerana kerja chat mempunyai kelakuan berbeza:

• giliran chat boleh tergolong dalam sesi yang dicipta API

• non-streaming dan SSE streaming memberi pengalaman pengguna yang berbeza

• lampiran imej menggunakan ID fail daripada API Fail

• penyelesaian kredit mengikuti giliran chat, bukan tugas media async biasa

Jika produk anda memerlukan jawapan assistant dalam interface sendiri, Chat API mungkin laluan yang betul. Jika pengguna masih meneroka idea, Rivya Chat atau Studio mungkin lebih baik.

Langkah 6: Mulakan dengan Semakan Berkala, Kemudian Tambah Webhook

Untuk versi pertama, semakan berkala lebih mudah dirancang.

Jika webhook diaktifkan untuk persekitaran pelaksanaan, tambah Webhook API apabila:

• produk mempunyai banyak tugas async

• klien yang menunggu tidak sepatutnya menyemak status tanpa henti

• sistem downstream memerlukan event siap bertandatangan

• percubaan semula dan pengendalian pendua sudah direka

Webhook receiver patut membosankan dan ketat: sahkan signature, terima event yang duplicate-safe, kemas kini satu rekod produk dan log hanya perkara yang selamat untuk dilog.

Langkah 7: Jadikan Kredit Kelihatan dalam Produk

Rivya API menggunakan kredit akaun yang sama seperti Studio.

Integrasi anda perlu memutuskan berapa banyak perkara itu ditunjukkan. Sekurang-kurangnya, pasukan perlu tahu:

• akaun yang memiliki kunci API

• aliran kerja mana boleh menggunakan kredit

• apa yang berlaku apabila kredit terlalu rendah

• bagaimana state penjanaan gagal diterangkan

• ke mana pengguna perlu diarahkan untuk soalan kredit dan pengebilan

Gunakan Kredit API, Kredit dan Pengebilan dalam Rivya dan Cara Memahami Kredit, Pek dan Pelan Rivya untuk menerangkan dompet kredit yang dilihat pengguna.

Versi Pertama yang Kecil

Versi pertama yang baik sengaja terhad.

Contohnya:

1. satu kunci API

2. satu model imej terpilih

3. belum ada muat naik fail

4. satu request penjanaan

5. satu laluan semakan status berkala

6. satu preview hasil ringkas dalam produk anda

7. satu mesej ralat kredit yang jelas

Versi itu membuktikan sambungan sebelum menambah lebih banyak bahagian bergerak.

Versi yang Lebih Lengkap

Selepas versi pertama berfungsi, aliran kerja lebih lengkap mungkin menambah:

• API Fail untuk imej atau video rujukan

• kawalan parameter khusus model

• idempotency yang terikat kepada rekod produk anda

• webhook bertandatangan untuk menandakan tugas siap, apabila ciri itu diaktifkan

• Chat API untuk giliran assistant

• aliran acara sisi pelayan apabila Chat memerlukan hasil masa nyata

• paparan admin atau support untuk tugas gagal

Setiap tambahan harus menjawab keperluan produk sebenar. Jika ia hanya membuat demo kelihatan lebih besar, tinggalkan.

Kesilapan Integrasi Biasa

Elakkan corak ini:

• bermula dengan setiap ciri API sekali gus

• menyembunyikan penggunaan kredit daripada pemilik akaun

• menggunakan andaian Studio-only dalam aliran API

• melayan muat naik fail sebagai perkara kemudian

• mencuba semula permintaan penjanaan tanpa idempotensi

• menggunakan Chat API untuk tugas yang sepatutnya async generation

• menggunakan endpoint penjanaan untuk giliran chat

• merekodkan kunci API penuh, rahsia webhook atau butiran fail sementara

Aliran kerja API yang paling selamat jelas tentang pemilikan, state dan pengendalian kegagalan.

Ke Mana Seterusnya

• Mula daripada Developers untuk hub API awam.

• Gunakan Rivya API Quickstart untuk menjalankan request pertama.

• Gunakan Model API sebelum memilih ID model.

• Gunakan API Fail hanya apabila model benar-benar memerlukan media rujukan.

• Gunakan Chat API untuk giliran chat dan respons chat streaming.

• Gunakan Webhook API apabila semakan berkala tidak lagi mencukupi dan akses webhook telah diaktifkan.

• Jika aliran kerja masih memerlukan penerokaan oleh manusia, baca Bila Perlu Menggunakan Rivya API dan Bukannya Studio sebelum mengautomasikannya.