Δημιουργία καταλόγου /v1/models Tenant-Aware για μια πύλη πολλαπλών μοντέλων API

Μια πύλη δεν πρέπει να επιστρέφει κάθε μοντέλο που είναι γνωστό σε κάθε συνδεδεμένο πάροχο από το GET /v1/models. Θα πρέπει να επιστρέψει τα μοντέλα που το κλειδί API με έλεγχο ταυτότητας είναι εξουσιοδοτημένο και λειτουργικά μπορεί να καλεί.

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

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

Ορίστε τι σημαίνει "διαθέσιμο"

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

• Η πύλη έχει ένα διαμορφωμένο δημόσιο προϊόν για το μοντέλο.
• Ο μισθωτής, η ομάδα και το κλειδί API δικαιούνται αυτό το προϊόν.
• Το ισχύον εμπορικό σχέδιο επιτρέπει τη χρήση του.
• Η πολιτική επιτρέπει το μοντέλο, τον πάροχο, την περιοχή και τη λειτουργία χειρισμού δεδομένων.
• Υπάρχει τουλάχιστον μία συμβατή ανάντη ανάπτυξη ή διαδρομή.
• Ένα χρησιμοποιήσιμο διαπιστευτήριο παρόχου είναι διαθέσιμο για αυτήν τη διαδρομή.
• Η διαδρομή υποστηρίζει τουλάχιστον μία επιφάνεια API που διαφημίζεται στον κατάλογο.
• Η διαδρομή είναι λειτουργικά έτοιμη σύμφωνα με την πολιτική υγείας της πύλης.

Εκφράζεται ως λειτουργία συνόλου:

visible_models(key) =
  configured_products
  ∩ tenant_entitlements
  ∩ team_grants
  ∩ key_grants
  ∩ commercial_rights
  ∩ policy_eligible_routes
  ∩ compatible_deployments
  ∩ operationally_ready_routes

Αυτή είναι μια σύσταση, όχι μια αξίωση σχετικά με το σχήμα OpenAI. Το τυπικό σχήμα δεν ορίζει όλα αυτά τα συγκεκριμένα στοιχεία ελέγχου πύλης. Ανήκουν στο επίπεδο ελέγχου και στον μεταγλωττιστή καταλόγου της πύλης.

Κανονοποίηση της ανακάλυψης παρόχου χωρίς να γίνει μεσολάβηση

Γεγονός: Τα API ανακάλυψης παρόχου εκθέτουν διαφορετικές έννοιες. Η λίστα μοντέλων του OpenAI παρέχει αναγνωριστικά και βασικά μεταδεδομένα, αλλά όχι έναν πλήρη πίνακα δυνατοτήτων για κάθε επιφάνεια API. Το Anthropic διακρίνει τις καταστάσεις κύκλου ζωής και μπορεί να επιστρέψει πλουσιότερες πληροφορίες δυνατοτήτων όταν ανακτάται ένα μοντέλο ή ένα ψευδώνυμο. Το Gemini εκθέτει πεδία όπως όρια διακριτικών και υποστηριζόμενες μεθόδους παραγωγής. Το Microsoft Foundry ενδέχεται να απαιτεί ένα όνομα ανάπτυξης στο πεδίο model και μια ανάπτυξη μπορεί να είναι ασύμβατη με ένα συγκεκριμένο API ακόμα και όταν υπάρχει το υποκείμενο μοντέλο.

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

Χρησιμοποιήστε μια εγγραφή κανονικού καταλόγου

Μια χρήσιμη εσωτερική εγγραφή διαχωρίζει τη δημόσια σύμβαση από την ανάντη υλοποίηση:

{
  "catalog_revision": "cat_2026_11_05_0182",
  "public_model_id": "reasoning-large",
  "lifecycle": "active",
  "api_surfaces": ["chat.completions", "responses"],
  "input_modalities": ["text", "image"],
  "output_modalities": ["text"],
  "limits": {
    "context_tokens": 200000,
    "max_output_tokens": 32000
  },
  "capabilities": {
    "tools": true,
    "structured_output": true,
    "batch": false
  },
  "entitlement_profile": "advanced-reasoning",
  "routes": [
    {
      "provider": "provider-a",
      "target_type": "deployment",
      "target_id": "prod-reasoning-east",
      "region": "us-east",
      "state": "ready"
    }
  ]
}

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

Χωριστά αναγνωριστικά, ψευδώνυμα και αναπτύξεις

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

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

Σύνταξη του καταλόγου για το πιστοποιημένο κλειδί

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

Μια ντετερμινιστική ακολουθία μεταγλώττισης είναι:

1. Φορτώστε την αναθεώρηση του αμετάβλητου βασικού καταλόγου.
2. Επίλυση ιδιότητας μέλους ενοικιαστή, ιδιότητας μέλους ομάδας και επιχορηγήσεων για συγκεκριμένα κλειδιά.
3. Εφαρμόστε περιορισμούς προγράμματος, γεωγραφίας, κατοίκησης δεδομένων και παρόχου.
4. Κατάργηση διαδρομών χωρίς έγκυρα διαπιστευτήρια ή συμβατές αναπτύξεις.
5. Αξιολογήστε την ετοιμότητα διαδρομής χρησιμοποιώντας το τρέχον στιγμιότυπο υγείας.
6. Συγκεντρώστε τις σωζόμενες διαδρομές σε δημόσια αρχεία μοντέλων.
7. Επιστρέφετε μόνο API επιφάνειες που υποστηρίζονται από τουλάχιστον μία διαδρομή που έχει διασωθεί.

Χρησιμοποιήστε τη σημασιολογία διασταύρωσης όταν υπάρχουν επιχορηγήσεις ομάδας και βασικών. Ένα κλειδί που εκχωρείται σε μια ομάδα περιορισμένης πρόσβασης δεν θα πρέπει να ανακτά ευρύτερη πρόσβαση μόνο και μόνο επειδή ο ενοικιαστής έχει ένα ευρύτερο σχέδιο. Αυτό καθιστά προβλέψιμο τον έλεγχο πρόσβασης μοντέλου AI για ομάδες λογισμικού και μειώνει την τυχαία αποκάλυψη.

Διατηρήστε τη λίστα και ανακτήστε την ίδια συμπεριφορά

GET /v1/models/{model} πρέπει να εκτελεί το ίδιο κατηγόρημα εξουσιοδότησης με τη λειτουργία λίστας. Διαφορετικά, ένας εισβολέας μπορεί να απαριθμήσει κρυφά αναγνωριστικά συγκρίνοντας απαντήσεις επιτυχίας, απαγορευμένες και μη-βρέθηκαν.

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

Ρητή αντιπροσώπευση API συμβατότητας

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

Επομένως, η είσοδος στη διαδρομή θα πρέπει να δέχεται τόσο ένα μοντέλο όσο και μια επιφάνεια API:

admit(key, public_model_id, api_surface, request_features)

Το αποτέλεσμα θα πρέπει να προσδιορίζει μια συμβατή αναθεώρηση καταλόγου και μία ή περισσότερες κατάλληλες διαδρομές. Για παράδειγμα, ένα μοντέλο μπορεί να υποστηρίζει chat.completions αλλά όχι responses ή να υποστηρίζει απαντήσεις μόνο όταν απουσιάζουν ενσωματωμένα εργαλεία. Ένα μόνο Boolean όπως το supports_responses μπορεί να είναι ανεπαρκές όταν η συμβατότητα εξαρτάται από τα ζητούμενα χαρακτηριστικά.

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

Διατήρηση της συμβατότητας SDK κατά την προσθήκη μεταδεδομένων

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

{
  "id": "reasoning-large",
  "object": "model",
  "created": 1793836800,
  "owned_by": "gateway",
  "x_gateway": {
    "catalog_revision": "cat_2026_11_05_0182",
    "lifecycle": "active",
    "api_surfaces": ["chat.completions", "responses"],
    "input_modalities": ["text", "image"],
    "availability": "available"
  }
}

Μια επέκταση χώρου ονομάτων μειώνει τον κίνδυνο σύγκρουσης, αλλά ορισμένοι πελάτες απορρίπτουν άγνωστα πεδία. Εάν οι εφαρμογές χρειάζονται λεπτομερή δεδομένα επιλογής, παρέχετε ένα ξεχωριστό τελικό σημείο πληροφοριών μοντέλου με έλεγχο ταυτότητας με ένα σχήμα έκδοσης. Διατηρήστε το /v1/models αρκετά μικρό για SDK, εργαλεία γραμμής εντολών και επιλογείς μοντέλων.

Επιλέξτε σταθερές καταχωρίσεις ή καταχωρίσεις με φιλτράρισμα υγείας

Υπάρχουν δύο εύλογες πολιτικές διαθεσιμότητας.

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

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

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

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

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

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

(tenant_id, key_id, entitlement_version, catalog_revision, policy_revision)

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

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

Δοκιμάστε τον κατάλογο ως σύμβαση εισδοχής

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

Προσθήκη αυτοματοποιημένων δοκιμών για:

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

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

Καταγράψτε αρκετά στοιχεία για να εξηγήσετε τις αποφάσεις

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

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

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

• σχεδιάζοντας ένα επίπεδο συμβατότητας απαντήσεων API