Δημιουργήστε ένα επίπεδο συμβατότητας API Responses σε μια πύλη AI API

Μην εφαρμόσετε το /v1/responses μεταφράζοντας κάθε αίτημα σε /v1/chat/completions και ελπίζοντας ότι το σχήμα είναι αρκετά κοντά. Αυτός ο προσαρμογέας μπορεί να επιστρέψει κείμενο, αλλά μπορεί να χάσει σιωπηλά τα μέρη για τα οποία ενδιαφέρονται οι προγραμματιστές: στοιχεία απόκρισης, κατάσταση διακομιστή, κλήσεις εργαλείων, συνέχεια συλλογισμού, συμβάντα κύκλου ζωής ροής, σημασιολογία ακύρωσης και απόδοση χρήσης σε επίπεδο στοιχείου.

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

Τι είναι πραγματικό, τι είναι πολιτική και τι είναι η πρόβλεψη;

Γεγονότα: Το OpenAI περιγράφει το Responses API ως ενοποιητικές δυνατότητες που προηγουμένως χωρίζονταν σε Ολοκληρώσεις συνομιλίας και Βοηθούς, συμπεριλαμβανομένης της υποστήριξης για εργαλεία όπως η αναζήτηση ιστού, η αναζήτηση αρχείων και η χρήση υπολογιστή. Το API εκθέτει πεδία όπως previous_response_id, ροή, επιλογή εργαλείου και ενσωματωμένα εργαλεία. Η τεκμηρίωση του SDK δείχνει ότι το previous_response_id μπορεί να παρέχει συνέχεια συνομιλίας, ενώ οι προηγούμενες οδηγίες δεν μεταφέρονται αυτόματα και πρέπει να αποσταλούν εκ νέου όταν εξακολουθούν να ισχύουν. Η αναφορά ροής του OpenAI περιλαμβάνει ξεχωριστό κύκλο ζωής και συμβάντα εξόδου απόκρισης και όχι μόνο διακριτικά δέλτα.

Προτάσεις: Μια πύλη θα πρέπει να διατηρεί αυτές τις σημασιολογίες αντί να τις ισοπεδώνει από προεπιλογή. Θα πρέπει να απορρίπτει ή να υποβαθμίζει ρητά αιτήματα όταν ένας πάροχος-στόχος δεν μπορεί να υποστηρίξει την απαιτούμενη συμπεριφορά.

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

Καθορίστε ένα ξεχωριστό συμβόλαιο συμβατότητας για τις απαντήσεις

Το πρώτο λάθος υλοποίησης είναι η υπόθεση ότι συμβατό με OpenAI σημαίνει ένα καθολικό σχήμα αιτήματος και απόκρισης. Στην πράξη, τα /v1/chat/completions και /v1/responses θα πρέπει να είναι ξεχωριστά συμβόλαια συμβατότητας.

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

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

Αυτός ο διαχωρισμός έχει σημασία για δοκιμές συμμόρφωσης. Ένας προσαρμογέας παρόχου που περνάει σε δοκιμές συνομιλίας ενδέχεται να εξακολουθεί να αποτυγχάνει στις δοκιμές απαντήσεων επειδή δεν μπορεί να διατηρήσει το previous_response_id, την παραγγελία στοιχείων, τη δομή άρνησης, τα μεταδεδομένα φιλοξενούμενου εργαλείου ή τα ονόματα συμβάντων ροής.

Ένα συμβόλαιο ελάχιστης συμβατότητας θα πρέπει να απαντά:

• Ποια πεδία αιτήματος γίνονται αποδεκτά, απορρίπτονται, μετασχηματίζονται ή αγνοούνται;
• Ποιοι τύποι στοιχείων απόκρισης διατηρούνται;
• Ποιοι τύποι εργαλείων υποστηρίζονται ανά πάροχο και μοντέλο;
• Μπορεί ο πάροχος να διατηρήσει την κατάσταση συνομιλίας ή πρέπει να τη διατηρήσει η πύλη;
• Τι συμβαίνει όταν ζητηθεί store=false;
• Ποια συμβάντα ροής είναι εγγυημένα;
• Πώς καταγράφονται η ακύρωση, το χρονικό όριο λήξης και η μερική χρήση;

Εάν έχετε ήδη μια πύλη API AI, αντιμετωπίστε την υποστήριξη Responses ως επέκταση πρωτοκόλλου και όχι ως ψευδώνυμο διαδρομής.

Χρησιμοποιήστε ένα μοντέλο κανονικού στοιχείου απόκρισης

Το Responses API επιστρέφει περισσότερα από ένα μηνύματα βοηθού. Μπορεί να αντιπροσωπεύει διαφορετικά στοιχεία εξόδου και συμβάντα. Η πύλη σας χρειάζεται ένα εσωτερικό κανονικό μοντέλο προτού αντιστοιχιστεί σε οποιονδήποτε πάροχο.

Ένα πρακτικό εσωτερικό σχήμα στοιχείου μπορεί να ξεκινήσει ως εξής:

{
  "gateway_response_id": "gw_resp_...",
  "provider_response_id": "resp_...",
  "tenant_id": "ten_123",
  "key_id": "key_456",
  "model_alias": "agent-default",
  "πάροχος": "openai",
  "στοιχεία": [
    {
      "item_id": "item_1",
      "type": "text",
      "ρόλος": "βοηθός",
      "content": [{ "type": "output_text", "text": "..." }],
      "status": "ολοκληρώθηκε"
    },
    {
      "item_id": "item_2",
      "type": "function_call",
      "call_id": "call_abc",
      "name": "lookup_order",
      "arguments_json": "{\"order_id\":\"123\"}",
      "status": "ολοκληρώθηκε"
    }
  ],
  "χρήση": {
    "input_tokens": 0,
    "output_tokens": 0,
    "reasoning_tokens": null,
    "tool_units": []
  },
  "status": "ολοκληρώθηκε"
}

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

• Έξοδος κειμένου
• Αρνήσεις
• Κλήσεις λειτουργίας
• Έξοδοι συνάρτησης που υποβάλλονται από την εφαρμογή
• Περιλήψεις συλλογισμών ή μεταδεδομένα που σχετίζονται με τη συλλογιστική, όπου είναι διαθέσιμα
• Αναφορές αρχείων
• Αναζήτηση ιστού, αναζήτηση αρχείων, χρήση υπολογιστή ή άλλα συμβάντα εργαλείων που φιλοξενούνται
• Τελική χρήση και μεταδεδομένα χρέωσης

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

Δημιουργήστε ένα κρατικό καθολικό που ανήκει στην πύλη

previous_response_id είναι το πεδίο που εκθέτει περισσότερο τη διαφορά μεταξύ του διακομιστή μεσολάβησης συνομιλίας χωρίς ιθαγένεια και της συμβατότητας Responses. Εάν ένας πελάτης αναφέρει μια προηγούμενη απάντηση, η πύλη πρέπει να γνωρίζει τι σημαίνει αυτό το αναγνωριστικό, εάν επιτρέπεται στον ενοικιαστή να το χρησιμοποιήσει και αν ο πάροχος μπορεί να συνεχίσει από αυτό.

Δημιουργήστε ένα καθολικό κατάστασης με κλειδί από μισθωτή και αναγνωριστικό απάντησης:

{
  "gateway_response_id": "gw_resp_789",
  "provider_response_id": "resp_provider_789",
  "previous_gateway_response_id": "gw_resp_456",
  "tenant_id": "ten_123",
  "user_id": "user_999",
  "key_id": "key_456",
  "model": "gpt-...",
  "πάροχος": "openai",
  "store_mode": "provider|gateway|none",
  "retention_policy": "standard|zero_retention|custom_30d",
  "instructions_hash": "sha256:...",
  "tool_policy_id": "tools_readonly_v3",
  "created_at": "...",
  "expires_at": "...",
  "deleted_at": null
}

Σημαντικός κανόνας: μην κάνετε αυτόματη εξομοίωση του previous_response_id αναπαράγοντας ξανά το πλήρες ιστορικό συνομιλιών, εκτός εάν ο ενοικιαστής έχει επιτρέψει ρητά αυτή τη συμπεριφορά διατήρησης και κόστους. Η επανάληψη μπορεί να αυξήσει το κόστος του διακριτικού, να αλλάξει τη στάση του απορρήτου και να αλλάξει τη συμπεριφορά του μοντέλου. Είναι ασφαλέστερο να επιστρέψετε ένα σαφές σφάλμα δυνατότητας παρά να στείλετε σιωπηλά το αποθηκευμένο περιεχόμενο συνομιλίας που η εφαρμογή δεν περίμενε να διατηρήσετε ή να επαναχρησιμοποιήσετε.

Λειτουργίες διαχείρισης κατάστασης

• Κατάσταση παρόχου: Ο ανάντη πάροχος αποθηκεύει αρκετό περιβάλλον και η πύλη αντιστοιχίζει αναγνωριστικά απόκρισης πύλης σε αναγνωριστικά απόκρισης παρόχου.
• Κατάσταση πύλης: Η πύλη αποθηκεύει τα απαραίτητα προηγούμενα στοιχεία και αναδομεί το περιβάλλον όταν επιτρέπεται.
• Χωρίς κατάσταση: Το αίτημα χρησιμοποιεί store=false ή η πολιτική μισθωτή απαγορεύει τη διατήρηση. Το previous_response_id θα πρέπει να απορριφθεί εκτός εάν ο πάροχος μπορεί να ικανοποιήσει το αίτημα χωρίς διατήρηση πύλης και το επιτρέπει η πολιτική.

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

Επικύρωση εργαλείων πριν από την αποστολή

Οι απαντήσεις κάνουν τη χρήση του εργαλείου πιο κεντρική. Ένα επίπεδο συμβατότητας θα πρέπει να χειρίζεται δύο μεγάλες κατηγορίες:

• Εργαλεία εφαρμογής: Ορισμοί συναρτήσεων που παρέχονται από τον πελάτη, εκτελούνται εκτός του παρόχου μοντέλου, με εξόδους που υποβάλλονται πίσω στο API.
• Εργαλεία φιλοξενούμενου παρόχου: Αναζήτηση ιστού, αναζήτηση αρχείων, χρήση υπολογιστή, εκτέλεση κώδικα, γείωση ή παρόμοια εργαλεία που εκτελούνται από τον πάροχο ή την υποδομή που ελέγχεται από πύλη.

Κατά την είσοδο, επικυρώστε τα σχήματα εργαλείων πριν από τη δρομολόγηση:

• Απορρίψτε νωρίς το μη έγκυρο σχήμα JSON.
• Επιβολή μέγιστου μεγέθους σχήματος και βάθους ένθεσης.
• Ελέγξτε τα ονόματα εργαλείων για συμβατότητα παρόχου.
• Εφαρμογή εμβέλειας μισθωτή, κλειδιού, χρήστη και περιβάλλοντος.
• Απαιτούνται πύλες έγκρισης για εργαλεία που γράφουν δεδομένα, ξοδεύουν χρήματα, έχουν πρόσβαση σε ευαίσθητα συστήματα ή καλούν εξωτερικές συνδέσεις.

Για την κλήση της λειτουργίας εφαρμογής, απαιτείται σταθερό αναγνωριστικό κλήσης. Το μοντέλο εκπέμπει μια κλήση συνάρτησης με call_id. η εφαρμογή υποβάλλει την έξοδο εργαλείου που αναφέρεται σε αυτό το αναγνωριστικό. η πύλη καταγράφει και τα δύο στο ίδιο ίχνος. Χωρίς αυτό το κλειδί σύνδεσης, τα αρχεία καταγραφής ελέγχου και οι επαναλήψεις γίνονται διφορούμενα.

Για τα φιλοξενούμενα εργαλεία, κάντε κράτηση προϋπολογισμού πριν από την αποστολή και διακανονίστε το κόστος μετά. Τα φιλοξενούμενα εργαλεία ενδέχεται να προσθέτουν χρεώσεις εκτός της συνήθους λογιστικής διακριτικών, επομένως συνδέστε το καθολικό εργαλείων στην ενοποιημένη χρέωση API AI αντί να αποκρύψετε αυτά τα κόστη μέσα σε ένα γενικό σύνολο κλήσεων μοντέλου.

Κανονοποίηση της ροής ως συμβάντων, όχι ως συμβολικού κειμένου

Ένας διακομιστής μεσολάβησης συνομιλίας μπορεί συχνά να ξεφύγει από την προώθηση δέλτα διακριτικών. Μια πύλη Responses δεν μπορεί. Η ροή έχει νόημα κύκλου ζωής: μια απόκριση μπορεί να ξεκινήσει, τα στοιχεία εξόδου μπορούν να ξεκινήσουν και να ολοκληρωθούν, το κείμενο μπορεί να φτάσει σε δέλτα, οι κλήσεις εργαλείων μπορούν να συγκεντρωθούν σταδιακά, η χρήση μπορεί να φτάσει στο τέλος ή κατά τη διάρκεια της ροής και η απόκριση μπορεί να αποτύχει ή να ακυρωθεί.

Ορίστε ένα σχήμα συμβάντος πύλης και, στη συνέχεια, αντιστοιχίστε κάθε ροή παρόχου σε αυτό:

γεγονός: answer_started
δεδομένα: { "response_id": "gw_resp_123", "status": "in_progress" }

συμβάν: output_item_startedδεδομένα: { "item_id": "item_1", "type": "text" }

συμβάν: text_delta
data: { "item_id": "item_1", "delta": "Hello" }

συμβάν: tool_call_delta
δεδομένα: { "item_id": "item_2", "call_id": "call_abc", "arguments_delta": "{\"order" }

συμβάν: usage_delta
δεδομένα: { "output_tokens": 12 }

εκδήλωση: ολοκληρώθηκε
δεδομένα: { "response_id": "gw_resp_123", "usage": { ... } }

Προτεινόμενα κανονικοποιημένα συμβάντα:

• response_started
• output_item_started
• output_item_completed
• text_delta
• refusal_delta
• tool_call_delta
• tool_result_received
• usage_delta
• ολοκληρώθηκε
• ακυρώθηκε
• απέτυχε

Όταν ο πελάτης αποσυνδεθεί, διαδώστε την ακύρωση ανάντη, εάν ο πάροχος την υποστηρίζει. Καταγράψτε την κατάσταση μερικής απόκρισης με κάθε τρόπο. Εάν ο πάροχος επιστρέψει αργότερα την τελική χρήση μέσω καθυστερημένης επιστροφής κλήσης ή τελικού κομματιού, συμβιβάστε το καθολικό. Η συμβατότητα ροής σχετίζεται τόσο με τη λογιστική και τον κύκλο ζωής όσο και με τον λανθάνοντα χρόνο.

Δημιουργήστε μια μήτρα δυνατοτήτων παρόχου

Η δρομολόγηση πολλών μοντέλων είναι χρήσιμη μόνο όταν η πύλη κατανοεί τι μπορεί να δρομολογηθεί με ασφάλεια. Προσθέστε δυνατότητες που αφορούν συγκεκριμένα τις απαντήσεις στον κατάλογο μοντέλων σας:

{
  "model_alias": "agent-default",
  "διαδρομές": [
    {
      "πάροχος": "openai",
      "μοντέλο": "...",
      "supports_responses": true,
      "supports_previous_response_id": true,
      "supports_store_false": true,
      "supports_builtin_web_search": true,
      "supports_function_calling": true,
      "supports_stream_lifecycle_events": true,
      "supports_reasoning_context_continuity": true,
      "max_tool_schema_bytes": 65536
    },
    {
      "provider": "provider_b",
      "μοντέλο": "...",
      "supports_responses": false,
      "chat_adapter_available": true,
      "loss_profile": ["no_previous_response_id", "no_hosted_tools", "flattened_stream"]
    }
  ]
}

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

Μια χρήσιμη επιλογή αιτήματος είναι:

{
  "model": "agent-default",
  "input": "...",
  "fallback_policy": {
    "allow_lossy": ψευδής,
    "allowed_losses": []
  }
}

Για λιγότερο ευαίσθητες περιπτώσεις χρήσης, οι ενοικιαστές μπορούν να επιτρέψουν συγκεκριμένες υποβαθμίσεις με απώλειες:

{
  "fallback_policy": {
    "allow_lossy": αληθές,
    "allowed_losses": ["flattened_stream", "no_reasoning_summary"]
  }
}

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

Χρήση χαρακτηριστικών σε επίπεδο απόκρισης και στοιχείου

Οι κλήσεις απόκρισης μπορεί να κοστίζουν περισσότερο από τις ισοδύναμες ολοκληρώσεις συνομιλίας, επειδή μπορεί να περιλαμβάνουν εκτέλεση εργαλείου, μεγαλύτερο πλαίσιο, διακριτικά συλλογισμού, αναζήτηση αρχείων, αναζήτηση στον ιστό ή επαναλαμβανόμενες οδηγίες. Ένας μεμονωμένος συνολικός αριθμός διακριτικών δεν αρκεί για έναν Πίνακα ελέγχου αναλυτικών στοιχείων χρήσης API AI.

Καταγραφή χρήσης σε δύο επίπεδα:

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

Αυτό επιτρέπει στους προγραμματιστές να απαντούν σε συγκεκριμένες ερωτήσεις:

• Αυξήθηκε το κόστος λόγω μεγαλύτερης κατάστασης, προσπάθειας συλλογισμού, κλήσεων εργαλείων ή εναλλακτικών;
• Ποιος μισθωτής ή ποιο κλειδί API δημιουργεί χρεώσεις φιλοξενούμενου εργαλείου;
• Ποια απάντηση απέτυχε μετά από κλήση εργαλείου αλλά πριν από το τελικό κείμενο;
• Ποιες ακυρωμένες ροές εξακολουθούν να έχουν χρήση ανάντη;

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

Η κατάσταση από την πλευρά του διακομιστή είναι χρήσιμη, αλλά αλλάζει τις υποχρεώσεις διατήρησης της πύλης. Δημιουργήστε πολιτική στο επίπεδο πρωτοκόλλου αντί να το αντιμετωπίζετε ως ρύθμιση καταγραφής.

Για κάθε αίτημα απαντήσεων, επιλύστε:

• Πολιτική διατήρησης ενοικιαστών
• Προτίμηση store επιπέδου αιτήματος
• Συμβατότητα διατήρησης παρόχου
• Εάν επιτρέπεται η επανάληψη της πύλης
• Είτε οι είσοδοι και οι έξοδοι εργαλείου μπορούν να αποθηκευτούν
• Συμπεριφορά λήξης και διαγραφής για κατάσταση απόκρισης

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

Στοιχεία συμμόρφωσης για προσθήκη πριν από την κυκλοφορία

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

Ελάχιστο σύνολο δοκιμής

• Βασική απόκριση: το στοιχείο κειμένου επιστρέφεται με σταθερό αναγνωριστικό απόκρισης και χρήση.
• Πολλαπλή στροφή: παραπομπές δεύτερου αιτήματος previous_response_id; Η πύλη επικυρώνει την ιδιοκτησία ενοικιαστή και τη λειτουργία κατάστασης.
• Επαναλαμβανόμενες οδηγίες: βεβαιωθείτε ότι οι παραλειφθείσες οδηγίες δεν επινοούνται σιωπηλά από την πύλη.
• Κλήση λειτουργίας μετ' επιστροφής: το μοντέλο εκπέμπει αναγνωριστικό κλήσης. Η αίτηση υποβάλλει αποτελέσματα· Η τελική απάντηση ενώνει και τις δύο εγγραφές.
• Πολιτική φιλοξενούμενου εργαλείου: το μη εξουσιοδοτημένο ενσωματωμένο εργαλείο έχει αποκλειστεί πριν από την αποστολή.
• Σειρά ροής: η έναρξη απόκρισης, η έναρξη του στοιχείου, τα δέλτα, η ολοκλήρωση, η χρήση και η ολοκλήρωση στοιχείων εκπέμπονται με έγκυρη σειρά.
• Ακύρωση ροής: η αποσύνδεση πελάτη ενεργοποιεί την ακύρωση ανάντη όπου υποστηρίζεται και καταγράφει τη μερική χρήση.
• Εναλλακτική απόρριψη: πάροχος χωρίς απαιτούμενες απαντήσεις επιστρέφει σφάλμα δυνατότητας.
• Επιτροπή με απώλειες: το αίτημα με επιτρεπόμενες απώλειες λαμβάνει έναν ρητό δείκτη υποβάθμισης.
• Λειτουργία μηδενικής διατήρησης: η επανάληψη της κατάστασης και η διατήρηση εντολών από την πλευρά της πύλης είναι αποκλεισμένες.

Συνιστώμενη ακολουθία διάθεσης

1. Εκθέστε μια διαδρομή beta. Προσθέστε /v1/responses χωρίς να αλλάξετε την υπάρχουσα συμπεριφορά συνομιλίας.
2. Εφαρμόστε πρώτα τη διαβίβαση για παρόχους με υποστήριξη εγγενών απαντήσεων. Διατηρήστε αναγνωριστικά, στοιχεία, ροές, χρήση και σφάλματα.
3. Προσθέστε το κρατικό καθολικό. Αντιστοιχίστε τα αναγνωριστικά πύλης σε αναγνωριστικά παρόχου και επιβάλετε την ιδιοκτησία ενοικιαστών.
4. Προσθέστε κανονικά στοιχεία. Αποθηκεύστε τα μεταδεδομένα στοιχείων που απαιτούνται για έλεγχο, χρέωση και ανακατασκευή ροής.
5. Προσθέστε διακυβέρνηση εργαλείου. Επικυρώστε σχήματα, επιβάλλετε πεδία και καταγράψτε συνδέσεις κλήσης εργαλείων.
6. Προσθέστε κανονικοποίηση ροής. Μετατρέψτε ροές για συγκεκριμένο πάροχο σε συμβάντα κύκλου ζωής πύλης.
7. Προσθέστε δρομολόγηση με επίγνωση δυνατοτήτων. Επιτρέπονται μόνο ασφαλείς εναλλακτικές από προεπιλογή.
8. Προσθέστε αναλυτικά στοιχεία και διακανονισμό χρεώσεων. Χαρίστε διακριτικό, συλλογιστική και χρήση εργαλείου ξεχωριστά.
9. Δημοσιεύστε σημειώσεις συμβατότητας. Πείτε στους προγραμματιστές ποια πεδία είναι εγγενή, προσομοιωμένα, μη υποστηριζόμενα ή με απώλειες.

Εκκίνητο συμπέρασμα

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

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

Σχετική ανάγνωση