Δημιουργήστε πολυτροπική ροή εργασίας με το Rivya API

Μια καλή ενσωμάτωση Rivya API δεν είναι απλώς ένα αίτημα προς ένα μοντέλο.

Οι περισσότερες πραγματικές ροές προϊόντος έχουν μια μικρή αλυσίδα: επιλέξτε το σωστό μοντέλο, ετοιμάστε την είσοδο, ανεβάστε αρχεία αναφοράς όταν χρειάζεται, υποβάλετε μια εργασία, παρακολουθήστε την κατάσταση, χειριστείτε τα credits και ειδοποιήστε το προϊόν όταν το αποτέλεσμα είναι έτοιμο.

Αυτό το άρθρο δείχνει το σχήμα σχεδιασμού. Χρησιμοποιήστε το Γρήγορη εκκίνηση του Rivya API για τη συντομότερη εκτελέσιμη διαδρομή και τα έγγραφα API για τα ακριβή πεδία αιτήματος.

Η παρακάτω ροή περιγράφει το υλοποιημένο συμβόλαιο του Public API. Πριν ξεκινήσετε, επιβεβαιώστε ότι η πρόσβαση στο Public API είναι ενεργή για τη συγκεκριμένη εγκατάσταση και τον λογαριασμό, ότι το επιλεγμένο μοντέλο είναι διαθέσιμο μέσω API και ότι τυχόν προαιρετικές λειτουργίες, όπως τα webhooks, είναι πράγματι διαθέσιμες.

Ξεκινήστε από τη στιγμή προϊόντος

Πριν επιλέξετε τελικά σημεία, περιγράψτε τη στιγμή προϊόντος σε μία πρόταση.

Παραδείγματα:

• Δημιούργησε πρόχειρη εικόνα προϊόντος όταν ένας πωλητής υποβάλλει σύνοψη καταχώρισης.

• Δημιούργησε σύντομη ιδέα βίντεο αφού ένας διαχειριστής καμπάνιας εγκρίνει μια στατική κατεύθυνση.

• Στείλε έναν γύρο συνομιλίας μέσα σε εσωτερικό εργαλείο έρευνας και μετάδωσε τμηματικά την απάντηση στον χρήστη.

• Ανέβασε μια εικόνα αναφοράς, υπέβαλε αίτημα υποστηριζόμενου μοντέλου και ειδοποίησε τον χρήστη όταν το αποτέλεσμα είναι έτοιμο.

Αυτή η πρόταση αποτρέπει την ενσωμάτωση από το να γίνει χαλαρή συλλογή κλήσεων API.

Χαρτογραφήστε τη ροή εργασίας πριν γράψετε κώδικα

Χρησιμοποιήστε αυτόν τον πίνακα πριν ανοίξετε το σχήμα του αιτήματος.

Η ροή εργασίας πρέπει να είναι αρκετά σαφής ώστε κάθε περιοχή API να έχει λόγο ύπαρξης.

Βήμα 1: Δημιουργήστε κλειδί για την ενσωμάτωση

Δημιουργήστε ένα API key για τη συγκεκριμένη εφαρμογή, περιβάλλον ή ροή εργασίας που θα το χρησιμοποιήσει.

Αποφύγετε να χρησιμοποιείτε ένα κλειδί για όλα. Η ονομασία κλειδιών με βάση τον σκοπό κάνει τον μεταγενέστερο έλεγχο ευκολότερο:

• production-image-workflow

• staging-video-tests

• internal-chat-assistant

• webhook-smoke-test

Διαβάστε το Πιστοποίηση API πριν αποθηκεύσετε το κλειδί. Το πλήρες μυστικό εμφανίζεται μία φορά, οπότε η ομάδα σας πρέπει να το αποθηκεύσει αμέσως στη σωστή αποθήκη μυστικών στην πλευρά του διακομιστή.

Βήμα 2: Επιλέξτε μοντέλα από τη δημόσια λίστα API

Μην κωδικοποιείτε σταθερά ένα μοντέλο μόνο επειδή λειτούργησε σε χειροκίνητη δοκιμή.

Χρησιμοποιήστε τα Μοντέλα API και Αναφορά API μοντέλων για να επιβεβαιώσετε:

• το δημόσιο αναγνωριστικό μοντέλου

• αν είναι διαθέσιμο μέσω API

• την υποστηριζόμενη λειτουργία εισόδου

• τις απαιτήσεις της οδηγίας και των παραμέτρων

• αν απαιτείται το API αρχείων

• συμπεριφορά credits και σημειώσεις ετοιμότητας

Σε αυτό το σημείο ξεκαθαρίζουν πολλές ενσωματώσεις. Ένα μοντέλο που είναι ιδανικό για χειροκίνητη δοκιμή στο Studio μπορεί να μην είναι η σωστή πρώτη επιλογή για μια αυτοματοποιημένη ροή προϊόντος.

Βήμα 3: Αποφασίστε αν το API αρχείων ανήκει στην πρώτη έκδοση

Αν το μοντέλο μπορεί να τρέξει από είσοδο κειμένου, κρατήστε την πρώτη έκδοση μόνο με κείμενο.

Προσθέστε το API αρχείων μόνο όταν η ροή εργασίας χρειάζεται πραγματικά πολυμέσα αναφοράς.

Όταν το κάνει, ορίστε:

• ποια είδη αρχείων δέχεται το προϊόν

• ποιος κατέχει το βήμα καθαρισμού αρχείων

• τι συμβαίνει όταν αποτύχει η μεταφόρτωση

• πώς τα επιστρεφόμενα δεδομένα αρχείου περνούν στις παραμέτρους μοντέλου

• αν το ίδιο αρχείο πρέπει να επαναχρησιμοποιηθεί ή να ανεβεί ξανά

Αυτό αποτρέπει μια εύθραυστη εμπειρία αρχείων από το να κρυφτεί πίσω από ένα κουμπί δημιουργίας που μοιάζει καθαρό.

Βήμα 4: Υποβάλετε μία εργασία δημιουργίας

Για δημιουργία εικόνας, βίντεο και ήχου, το κανονικό μοτίβο είναι:

1. ετοιμάστε το αναγνωριστικό μοντέλου, την οδηγία και τις υποστηριζόμενες παραμέτρους

2. προσθέστε idempotency key για ασφαλείς επαναλήψεις

3. υποβάλετε το αίτημα μέσω του τελικού σημείου δημιουργίας

4. αποθηκεύστε το δημόσιο αναγνωριστικό εργασίας

5. ελέγχετε περιοδικά την κατάσταση μέχρι η εργασία να φτάσει σε τελική κατάσταση

Χρησιμοποιήστε τη Δημιουργία εργασίας για το σχήμα αιτήματος και την Κατάσταση δημιουργίας για τον χειρισμό των αποτελεσμάτων.

Το προϊόν πρέπει να αντιμετωπίζει τα queued, processing, succeeded και failed ως καταστάσεις που βλέπει ο χρήστης. Μην κάνετε τους χρήστες να διαβάζουν λεπτομέρειες συστήματος ή να μαντεύουν γιατί μια εργασία είναι αργή.

Βήμα 5: Χρησιμοποιήστε το API συνομιλίας για μοντέλα chat

Τα μοντέλα συνομιλίας πρέπει να χρησιμοποιούν το API συνομιλίας και όχι το τελικό σημείο δημιουργίας.

Αυτό έχει σημασία επειδή η εργασία συνομιλίας έχει διαφορετική συμπεριφορά:

• οι γύροι συνομιλίας μπορούν να ανήκουν σε συνεδρίες που δημιουργήθηκαν μέσω API

• η πλήρης απόκριση και η τμηματική μετάδοση μέσω SSE προσφέρουν διαφορετική εμπειρία χρήστη

• τα συνημμένα εικόνων χρησιμοποιούν αναγνωριστικά αρχείων από το API αρχείων

• ο διακανονισμός των credits ακολουθεί τον γύρο συνομιλίας αντί για μια συνηθισμένη ασύγχρονη εργασία πολυμέσων

Αν το προϊόν σας χρειάζεται απάντηση βοηθού μέσα στη δική του διεπαφή, το API συνομιλίας μπορεί να είναι η σωστή διαδρομή. Αν ο χρήστης ακόμη εξερευνά ιδέες, το Rivya Chat ή το Studio μπορεί να είναι καλύτερο.

Βήμα 6: Ξεκινήστε με περιοδικό έλεγχο και μετά προσθέστε webhooks

Για την πρώτη έκδοση, ο περιοδικός έλεγχος της κατάστασης είναι πιο εύκολος στον σχεδιασμό.

Αν τα webhooks είναι ενεργά για την εγκατάσταση, προσθέστε το API για webhooks όταν:

• το προϊόν έχει πολλές ασύγχρονες εργασίες

• οι πελάτες που περιμένουν δεν πρέπει να ελέγχουν απευθείας και περιοδικά την κατάσταση

• μεταγενέστερα συστήματα χρειάζονται υπογεγραμμένα συμβάντα ολοκλήρωσης

• ο χειρισμός επανάληψης και διπλότυπων έχει ήδη σχεδιαστεί

Οι δέκτες webhook πρέπει να είναι βαρετοί και αυστηροί: επαληθεύστε την υπογραφή, αποδεχτείτε συμβάντα ασφαλή ως προς τα διπλότυπα, ενημερώστε μία εγγραφή προϊόντος και καταγράψτε μόνο ό,τι είναι ασφαλές να καταγραφεί.

Βήμα 7: Κάντε τα credits ορατά στο προϊόν

Το Rivya API χρησιμοποιεί τα ίδια credits λογαριασμού με το Studio.

Η ενσωμάτωσή σας πρέπει να αποφασίσει πόσα από αυτά θα δείχνει. Τουλάχιστον, η ομάδα πρέπει να ξέρει:

• ποιος λογαριασμός κατέχει το API key

• ποια ροή εργασίας μπορεί να καταναλώνει credits

• τι συμβαίνει όταν τα credits είναι πολύ χαμηλά

• πώς εξηγούνται οι αποτυχημένες καταστάσεις δημιουργίας

• πού να στείλει κάποιον για ερωτήσεις credits και χρέωσης

Χρησιμοποιήστε τα Credits του API, Credits και χρέωση στο Rivya και Πώς λειτουργούν τα credits, τα πακέτα και τα προγράμματα Rivya για το μοντέλο υπολοίπου που βλέπει ο χρήστης.

Μια μικρή πρώτη έκδοση

Μια καλή πρώτη έκδοση είναι σκόπιμα περιορισμένη.

Για παράδειγμα:

1. ένα κλειδί API

2. ένα επιλεγμένο μοντέλο εικόνας

3. χωρίς μεταφόρτωση αρχείου ακόμη

4. ένα αίτημα δημιουργίας

5. μία διαδρομή περιοδικού ελέγχου κατάστασης

6. μία απλή προεπισκόπηση αποτελέσματος στο προϊόν σας

7. ένα σαφές μήνυμα σφάλματος credits

Αυτή η έκδοση αποδεικνύει τη σύνδεση πριν προσθέσετε περισσότερα κινούμενα μέρη.

Μια πιο πλήρης έκδοση

Αφού λειτουργήσει η πρώτη έκδοση, μια πληρέστερη ροή εργασίας μπορεί να προσθέσει:

• API αρχείων για εικόνες ή βίντεο αναφοράς

• ελέγχους παραμέτρων ειδικούς για μοντέλο

• idempotency δεμένη με την εγγραφή προϊόντος σας

• υπογεγραμμένα webhooks για ολοκλήρωση, όταν η λειτουργία είναι ενεργή

• API συνομιλίας για γύρους με τον βοηθό

• ροή συμβάντων από τον διακομιστή όπου η συνομιλία χρειάζεται άμεση έξοδο

• προβολές διαχείρισης ή υποστήριξης για αποτυχημένες εργασίες

Κάθε προσθήκη πρέπει να απαντά σε πραγματική ανάγκη προϊόντος. Αν απλώς κάνει την επίδειξη να φαίνεται μεγαλύτερη, αφήστε την έξω.

Συνηθισμένα λάθη ενσωμάτωσης

Αποφύγετε αυτά τα μοτίβα:

• να ξεκινάτε με κάθε δυνατότητα API ταυτόχρονα

• να κρύβετε τη χρήση credits από τον κάτοχο λογαριασμού

• να χρησιμοποιείτε υποθέσεις μόνο του Studio σε ροή API

• να αντιμετωπίζετε τις μεταφορτώσεις αρχείων ως δευτερεύουσα σκέψη

• να επαναλαμβάνετε αιτήματα δημιουργίας χωρίς idempotency

• να χρησιμοποιείτε το API συνομιλίας για εργασίες που πρέπει να είναι ασύγχρονη δημιουργία

• να χρησιμοποιείτε τελικά σημεία δημιουργίας για γύρους chat

• να καταγράφετε πλήρη API keys, webhook secrets ή προσωρινές λεπτομέρειες αρχείων

Η ασφαλέστερη ροή εργασίας API είναι ρητή για την ιδιοκτησία, την κατάσταση και τον χειρισμό αποτυχίας.

Πού να πάτε μετά

• Ξεκινήστε από τη σελίδα Για προγραμματιστές για τον δημόσιο κόμβο API.

• Χρησιμοποιήστε το Γρήγορη εκκίνηση του Rivya API για να εκτελέσετε το πρώτο αίτημα.

• Χρησιμοποιήστε τα Μοντέλα API πριν επιλέξετε model IDs.

• Χρησιμοποιήστε το API αρχείων μόνο όταν το μοντέλο χρειάζεται πραγματικά πολυμέσα αναφοράς.

• Χρησιμοποιήστε το API συνομιλίας για γύρους συνομιλίας και τμηματικά μεταδιδόμενες απαντήσεις.

• Χρησιμοποιήστε το API για webhooks όταν ο περιοδικός έλεγχος δεν αρκεί πλέον και η πρόσβαση στα webhooks είναι ενεργή.

• Αν η ροή εργασίας χρειάζεται ακόμη ανθρώπινη εξερεύνηση, διαβάστε Πότε να χρησιμοποιείτε Rivya API αντί για Studio πριν την αυτοματοποιήσετε.