Κέρδη:
- Μπορεί να περιγράψει τη βασική δομή ενός αιτήματος API LLM (τελικό σημείο, μοντέλο, μηνύματα, max_tokens)
- Κατανοεί τη διαφορά μεταξύ των ρόλων συστήματος, χρήστη και βοηθού και ιστορικού συνομιλιών χωρίς ιθαγένεια
- Μπορεί να διαβάσει και να ερμηνεύσει πεδία (μπλοκ περιεχομένου, stop_reason, χρήση) της απάντησης που επιστρέφεται
Σε προηγούμενες ενότητες, χρησιμοποιούσαμε τεχνητή νοημοσύνη από ένα παράθυρο συνομιλίας. Αλλά αν θέλετε να ενσωματώσετε την τεχνητή νοημοσύνη στο δικό σας προϊόν, στον αυτοματισμό ή στη ροή εργασίας σας, μια διεπαφή συνομιλίας δεν θα το κόψει. Πρέπει να συνδεθείτε με το μοντέλο μέσω προγραμματισμού, δηλαδή με κώδικα ή ένα εργαλείο αυτοματισμού. Το όνομα αυτής της γέφυρας είναι API (Application Programming Interface, η σύμβαση που επιτρέπει σε δύο λογισμικά να συνομιλούν με συγκεκριμένους κανόνες). Όταν ολοκληρώσετε αυτήν την ενότητα, θα γνωρίζετε τι συνιστά αίτημα API LLM (Large Language Model), τι κάνουν οι ρόλοι μηνυμάτων και πώς να διαβάσετε την απάντηση. Αυτό είναι το θεμέλιο πάνω στο οποίο θα χτιστεί η υπόλοιπη ενότητα.
Πώς λειτουργεί το API;
Η βασική ροή στο API είναι η εξής: στέλνετε ένα αίτημα σε μια συγκεκριμένη μορφή. Ο διακομιστής επιστρέφει μια απάντηση σε μια συγκεκριμένη μορφή. Στα LLM, αυτή είναι συνήθως μια κλήση HTTP (HTTP: τυπικό πρωτόκολλο για τη μεταφορά αιτήματος-απόκρισης στον Ιστό) σε μία μόνο διεύθυνση (τελικό σημείο, η σταθερή διεύθυνση στον διακομιστή που χειρίζεται το αίτημά σας). Για παράδειγμα, σε ένα API ανταλλαγής μηνυμάτων, όλα τα αιτήματα πηγαίνουν σε μία μόνο διεύθυνση και μεταφέρονται στο σώμα ως JSON (JavaScript Object Notation — μια μορφή κειμένου που αποτελείται από ζεύγη κλειδιών/τιμών που μπορούν να διαβαστούν τόσο από ανθρώπους όσο και από μηχανήματα).
Σε ένα αίτημα, προσδιορίζετε τουλάχιστον αυτά τα τρία πράγματα:
- Μοντέλο: Ποιο μοντέλο θα χρησιμοποιήσετε (π.χ. ένα γρήγορο και φθηνό μοντέλο ή ένα ισχυρό μοντέλο).
- max_tokens: Ο μέγιστος αριθμός διακριτικών (η μικρότερη μονάδα στην οποία γίνεται η επεξεργασία του κειμένου, η οποία θα επεξεργαστεί λεπτομερώς στην επόμενη ενότητα) που μπορεί να παράγει το μοντέλο. δηλαδή όριο εξόδου.
- μηνύματα: Λίστα μηνυμάτων που αποτελούν τη συνομιλία.
Βήμα προς βήμα: Πώς να δημιουργήσετε ένα αίτημα
- Προετοιμάστε το τελικό σημείο και τα διαπιστευτήρια. Προσθέτετε το κλειδί API σας (τη μυστική συμβολοσειρά που αποδεικνύει την ταυτότητά σας) στο αίτημα σε μια κεφαλίδα. Ποτέ δεν ενσωματώνετε το κλειδί στον κώδικα. Θα καλύψουμε την ασφαλή αποθήκευση στην ενότητα 9.
- Επιλέξτε το μοντέλο και το όριο εξόδου. Ελαφρύ μοντέλο + μικρά max_tokens για μια απλή εργασία. Ισχυρό μοντέλο + μεγαλύτερο όριο για μια πολύπλοκη εργασία.
- Ρυθμίστε τη λίστα μηνυμάτων. List the system instruction, user message, and past rounds (if any).
- Στείλτε το αίτημα και αναλύστε την απάντηση. Διαβάστε το περιεχόμενο κειμένου, σταματήστε τη χρήση του λόγου και του διακριτικού από το JSON που επιστράφηκε.
Ρόλοι μηνυμάτων: σύστημα, χρήστης, βοηθός
Μια συνομιλία αποτελείται από μηνύματα ταξινομημένα σε μια σειρά και κάθε μήνυμα έχει έναν ρόλο. Ο ρόλος καθορίζει πώς το μοντέλο αντιμετωπίζει αυτό το κείμενο.
Ρόλος
Ποιος γράφει
Σκοπός
σύστημα
Προγραμματιστής/διαχειριστής
Μόνιμες οδηγίες, προσωπικότητα και κανόνες που ισχύουν σε όλη τη διάρκεια της συνομιλίας
χρήστη
τελικό χρήστη
Η τρέχουσα ερώτηση ή εισαγωγή του χρήστη
βοηθός
μοντέλο
Απόκριση που παράγεται από το μοντέλο (και προηγούμενες απαντήσεις)
Ο ρόλος του συστήματος είναι διαθέσιμος ως ξεχωριστό πεδίο συστήματος στο σώμα αιτήματος στους περισσότερους παρόχους. χρήστης και βοηθός παρατίθενται διαδοχικά στη λίστα μηνυμάτων. Critical point: the system instruction is the high-level instruction, the user message is the request to be answered at that moment.
{ "model": "claude-opus-4-8", "max_tokens": 1024, "system": "Είστε βοηθός εταιρικής υποστήριξης. Δώστε μια σύντομη, επίσημη και επαληθευμένη απάντηση. Μην δημιουργείτε πληροφορίες για τις οποίες δεν είστε βέβαιοι.", "messages": [ { "role": "user", "ow επιστρέφω τη διαδικασία μου": } ]}
Ο λόγος είναι ανιθαγενής
Ακολουθεί η πιο κοινή παρανόηση: Οι κλήσεις LLM API είναι χωρίς κατάσταση — ο διακομιστής δεν διατηρεί μνήμη μεταξύ δύο αιτημάτων. Το μοντέλο δεν θυμάται το προηγούμενο αίτημά σας. Εάν ρυθμίζετε μια συζήτηση πολλών γύρων, θα πρέπει να στέλνετε ξανά τους προηγούμενους γύρους με κάθε νέο αίτημα. Η «μνήμη» του μοντέλου αποτελείται από μια λίστα μηνυμάτων που έχετε στείλει.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Γεια σου, με λένε Deniz." }, { "role": "assistant", "content": "Γεια σου Deniz, πώς μπορώ να σε βοηθήσω;" }, { "role": "user", "content": "Μόλις είπα το όνομά μου, θυμάσαι;" } ]}
Η σωστή απάντηση στο τρίτο μήνυμα εξαρτάται από την αποστολή και των δύο προηγούμενων μηνυμάτων. Εάν δεν το στείλετε, το μοντέλο δεν θα γνωρίζει το "Sea" και θα απαντήσει λάθος. Αυτό επηρεάζει επίσης άμεσα το κόστος: όσο μεγαλύτερη είναι η συνομιλία, τόσο μεγαλύτερη είναι η λίστα, κάθε αίτημα καταναλώνει περισσότερα διακριτικά.
Συμβουλή: Σε μεγάλες συνομιλίες, η σύνοψη και η μετακίνηση παλιών κύκλων (σύνοψη + τελευταίοι γύροι) αντί της αποστολής ολόκληρου του ιστορικού μειώνει το κόστος και διατηρεί το παράθυρο περιβάλλοντος. Θα το εμβαθύνουμε στις ενότητες 6 και 11.
Διαβάστε την Απάντηση
Όταν το μοντέλο επιστρέφει μια απάντηση, λαμβάνετε ένα δομημένο αντικείμενο, όχι απλό κείμενο. Τυπικές περιοχές:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "Για να ξεκινήσετε μια επιστροφή, μεταβείτε στη σελίδα "Οι παραγγελίες μου" στον λογαριασμό σας..." } ] ], "stop": "input_tokens": 47, "output_tokens": 88 }}
- Περιεχόμενο: Η ίδια η απάντηση. Είναι μια λίστα μπλοκ περιεχομένου. Το πεδίο κειμένου του μπλοκ κειμένου είναι η πραγματική απάντηση.
- stop_reason: Γιατί σταμάτησε το μοντέλο. end_turn = φυσικό τέλος; max_tokens = κολλημένο στο όριο εξόδου (η απόκριση μπορεί να είναι ελλιπής). άρνηση = αρνήθηκε για λόγους ασφαλείας. Ο κώδικάς σας πρέπει πάντα να κοιτάζει πρώτα το stop_reason.
- χρήση: Εισαγωγή και έξοδος αριθμών διακριτικών. Είναι η βάση της παρακολούθησης κόστους και ορίων.
Προσοχή: Εάν το stop_reason είναι max_tokens, η απάντηση δεν ολοκληρώνεται. Η αντιμετώπιση αυτού ως "επιτυχημένης απάντησης" και η εμφάνιση μισού κειμένου στον χρήστη είναι ένα από τα πιο συνηθισμένα λάθη στην παραγωγή. Είτε αυξήστε τα max_tokens είτε χρησιμοποιήστε ροή.
Αδύναμη προτροπή / Ισχυρή προτροπή
Ίδια εργασία με δύο διαφορετικές προτροπές συστήματος:
# ΑΔΥΝΑΜΟΣ Είσαι βοηθός. Απαντήστε στις ερωτήσεις.
# STRONG Είστε βοηθός εταιρικής υποστήριξης. Κανόνες: - Βασιστείτε αποκλειστικά στις πληροφορίες στο παρεχόμενο έγγραφο πολιτικής. Εάν δεν υπάρχει στο έγγραφο, πείτε «Δεν έχω αυτές τις πληροφορίες, τις κατευθύνω στην αρμόδια μονάδα». - Οι απαντήσεις δεν πρέπει να υπερβαίνουν τις 3 προτάσεις, να είναι επίσημες και σαφείς. - Μην ζητάτε προσωπικά δεδομένα (αριθμός ταυτότητας TC, αριθμός κάρτας) και μην επαναλάβετε. - Μην μαντεύετε όταν δεν είστε σίγουροι.
Ισχυρή έκδοση. Καθορίζει το εύρος, τη μορφή, το περιθώριο ασφαλείας και τη συμπεριφορά σε συνθήκες αβεβαιότητας. Η συνέπεια της παραγωγής του μοντέλου προέρχεται απευθείας από αυτή τη σαφήνεια.
Τρεις Μίνι Θήκες
Περίπτωση 1 — Ρομπότ υποστήριξης (παγίδα ανιθαγένειας). Μια ομάδα ηλεκτρονικού εμπορίου έβγαλε ζωντανά το bot. Όταν ο χρήστης είπε "ακύρωση της προηγούμενης παραγγελίας", το bot "ξέχασε" τον αριθμό παραγγελίας. Αιτία: έστελναν κάθε αίτημα μόνο με το τελευταίο μήνυμα. Λύση: πρόσθεσαν τους τελευταίους 6 γύρους στη λίστα μηνυμάτων. Αποτέλεσμα: το περιβάλλον διατηρήθηκε, αλλά η είσοδος ανά αίτημα αυξήθηκε από 40 μάρκες σε ~600 μάρκες — θα καλύψουμε το μάθημα κόστους στην ενότητα 2.
Περίπτωση 2 — Ελλιπής περίληψη της σύμβασης. Μια νομική ομάδα περιέγραφε συμβάσεις 10 σελίδων. max_tokens: 300 παρέμειναν χαμηλά, οι περιλήψεις έκοβαν τη μέση πρόταση. Το stop_reason ήταν max_tokens κάθε φορά, αλλά κανείς δεν κοίταζε. αύξησε τα max_tokens στα 1500 και πρόσθεσε τον έλεγχο stop_reason. Το περικομμένο συνοπτικό ποσοστό μειώθηκε από 18% σε 0%.
Περίπτωση 3 — Μίξη ρόλων. Μια ομάδα μάρκετινγκ έγραφε όλες τις οδηγίες στο μήνυμα χρήστη, αφήνοντας το σύστημα κενό. Όταν η εισαγωγή του χρήστη αναμιγνύεται με οδηγίες, το μοντέλο μερικές φορές συμμορφώνεται με την εντολή του χρήστη να "ξεχάσει τους προηγούμενους κανόνες". Μετέφεραν μόνιμους κανόνες στο σύστημα. Διαχωρίζοντας τα δεδομένα χρήστη από την οδηγία, οι παραβιάσεις κανόνων μειώθηκαν σημαντικά.
Συνήθη λάθη
- Ξεχνώντας να στείλετε το παρελθόν: Το μοντέλο θεωρείται ότι «δεν θυμάται». ενώ είναι ανιθαγενής. Εσείς κουβαλάτε το πλαίσιο.
- Δεν εξετάζουμε το `stop_reason`: Η απάντηση που διακόπηκε με max_tokens θεωρείται ολοκληρωμένη.
- Ενσωμάτωση της εντολής στο «χρήστης»: Μόνιμοι κανόνες στο σύστημα. Η άμεση εισαγωγή πηγαίνει στον χρήστη. Η μίξη δημιουργεί ευπάθειες ασφαλείας.
- Λάθος «περιεχόμενο» για μια απλή συμβολοσειρά: Η απάντηση είναι μια λίστα μπλοκ. διαβάστε το πεδίο κειμένου του πρώτου μπλοκ κειμένου, επαληθεύστε τον τύπο του πριν λάβετε περιεχόμενο[0] με ένα τυφλό ευρετήριο.
- Ενσωμάτωση του κλειδιού στον κώδικα: Χρησιμοποιήστε μια μεταβλητή περιβάλλοντος (μονάδα 9).
Βαθύτερα: Αποκλεισμοί περιεχομένου και απαντήσεις σε πολλά μέρη
Η κατανόηση του γιατί το πεδίο περιεχομένου στην απάντηση είναι μια λίστα είναι θεμελιώδους σημασίας για τις προηγμένες λειτουργίες που θα συναντήσετε αργότερα. Μερικές φορές το μοντέλο δεν επιστρέφει ένα μπλοκ κειμένου, αλλά πολλά μπλοκ: ένα μπλοκ σκέψης, ακολουθούμενο από ένα μπλοκ κειμένου. ή ένα μπλοκ κειμένου που ακολουθείται από ένα μπλοκ χρήσης εργαλείου. Γι' αυτό η τυφλή καταμέτρηση περιεχομένου[0] ως "απάντηση" είναι εύθραυστη. Η σωστή προσέγγιση είναι να περάσετε από τη λίστα και να την ταξινομήσετε κατά τύπο: συλλέγετε το περιεχόμενο κειμένου των μπλοκ των οποίων το πεδίο τύπου είναι κείμενο και αντιμετωπίζετε άλλους τύπους (σκέψη, εργαλείο) ξεχωριστά.
Αυτό που κάνει αυτή η διάκριση στην πράξη είναι ότι μπορείτε να καταγράψετε το σκεπτικό του μοντέλου (αν υπάρχει) χωρίς να το αποκαλύψετε στον χρήστη, να ανακατευθύνετε τις κλήσεις εργαλείων σε ξεχωριστή λογική και να εκτυπώσετε μόνο την πραγματική απάντηση στην οθόνη. Καθώς η ενότητα προχωρά (ειδικά στις μονάδες 4 και 11) θα δείτε πόσο χρήσιμη είναι αυτή η δομή μπλοκ για την επικύρωση και την κατεύθυνση της εξόδου.
Ένα άλλο πρακτικό σημείο: μπορείτε να έχετε πρόσβαση στο ίδιο μοντέλο από διαφορετικές πλατφόρμες παρόχων (άμεσο API, μέσω παρόχου cloud). Αν και η διεύθυνση τελικού σημείου και η μορφή ελέγχου ταυτότητας μπορεί να αλλάξουν, βασικές έννοιες όπως οι ρόλοι του μηνύματος, η ανιθαγένεια και η δομή απόκρισης παραμένουν οι ίδιες. Επομένως, τα βασικά σε αυτή τη μονάδα ισχύουν ανεξάρτητα από την πλατφόρμα που χρησιμοποιείτε.
Συνοπτικά
Ένα αίτημα LLM API αποτελείται από το μοντέλο, το όριο εξόδου και τη λίστα μηνυμάτων. ρόλοι (σύστημα, χρήστης, βοηθός) καθορίζουν τη συμπεριφορά του μοντέλου. Οι κλήσεις είναι ανιθαγενείς: φέρετε το πλαίσιο με κάθε αίτημα. Η απόκριση είναι ένα δομημένο αντικείμενο. Η ανάγνωση και η ερμηνεία των πεδίων περιεχομένου, stop_reason και χρήσης είναι η βάση της ανθεκτικότητας στην παραγωγή.
Εργασία εφαρμογής
Επιλέξτε μια εργασία από το δικό σας επάγγελμα (π.χ. ταξινόμηση εισερχόμενων e-mail, δημιουργία σύντομων περιλήψεων). Σε ένα κομμάτι χαρτί: (1) γράψτε την προτροπή συστήματος με 4-5 κανόνες, (2) ορίστε ένα δείγμα μηνύματος χρήστη και ένα ιστορικό 2 γύρων εάν υπάρχει, (3) καθορίστε μια λογική τιμή για max_tokens και γράψτε την αιτιολόγηση, (4) λίστα ποιες τιμές stop_reason θα χειριστείτε στην επιστρεφόμενη απάντηση και πώς.
λίστα ελέγχου
- [ ] Μπορώ να μετρήσω τα τρία υποχρεωτικά μέρη ενός αιτήματος (μοντέλο, max_tokens, μηνύματα).
- [ ] Μπορώ να εξηγήσω τη διαφορά μεταξύ των ρόλων συστήματος, χρήστη και βοηθού.
- [ ] Γνωρίζω ότι οι κλήσεις είναι ανιθαγενείς και ότι πρέπει να κουβαλήσω το παρελθόν.
- Μπορώ να διαβάσω και να σχολιάσω το περιεχόμενο [ ], τα πεδία stop_reason και χρήσης.
- [ ] Με το max_tokens μπορώ να παρατηρήσω και να χειριστώ την περικομμένη απόκριση.