Έκδοση 1.0.0-alpha.1τελευταία
Κεφάλαιο 2.14
Πάροχοι και μοντέλα AI
Πώς ο Δρομολογητής Παρόχων τεχνητής νοημοσύνης (AI) επιλέγει ένα μοντέλο από τη δεξαμενή κλειδιών του ίδιου του οργανισμού, και πώς τα σενάρια (scripts) και τα εργαλεία AI αποκτούν πρόσβαση στο Nexus εξωτερικά.
Αυτή η σελίδα μεταφράστηκε με AI από το αγγλικό πρωτότυπο. Εάν οτιδήποτε είναι ασαφές, η αγγλική σελίδα αποτελεί το σημείο αναφοράς. Διαβάστε αυτή τη σελίδα στα αγγλικά

Η Harrow Port Authority διατηρεί δύο εγκαταστάσεις. Αυτή στο απομονωμένο (air-gapped) δίκτυο επιχειρήσεων (κεφάλαιο 2.10, Εγκατάσταση σε απομονωμένο δίκτυο) δεν έχει καθόλου φιλοξενούμενο πάροχο. Στη συνδεδεμένη εταιρική εγκατάσταση, την οποία παρακολουθεί αυτό το κεφάλαιο, οι περισσότερες ερωτήσεις απαντώνται από ένα μοντέλο που εκτελείται σε δύο κόμβους μονάδων επεξεργασίας γραφικών (GPU) στο ιδιόκτητο server room του λιμανιού. Ένα κλειδί Google Gemini, το οποίο πληρώνει η Harrow, αναλαμβάνει την υπερχείλιση όταν το τοπικό μοντέλο είναι απασχολημένο, και η Aoife Brennan έχει κλειδώσει την κίνηση τεχνητής νοημοσύνης (AI) του οργανισμού εντός της ΕΕ. Κανείς στη Harrow δεν παραμετροποίησε κάποιο μοντέλο μέσα σε υπηρεσία ή πρόσθετο (plugin). Δήλωσαν σε ένα στοιχείο τι διαθέτει η Harrow, και αυτό το στοιχείο αποφασίζει για κάθε κλήση.
Αυτό το κεφάλαιο καλύπτει το συγκεκριμένο στοιχείο, τον AI Provider Router, τον οποίο το Μέρος 1 και η κονσόλα αποκαλούν τηλεφωνικό κέντρο AI (AI switchboard), καθώς και τη δεξαμενή κλειδιών από την οποία αντλεί. Κλείνει με τους τρόπους με τους οποίους τα σενάρια (scripts) και τα εργαλεία AI επικοινωνούν με το Nexus έξωθεν: κλειδιά για σενάρια, τη διεπαφή προγραμματισμού εφαρμογών (API) REST (representational state transfer) και το Model Context Protocol (MCP).
Ο Δρομολογητής Παρόχων AI
Ο δρομολογητής (router) εκτελείται μέσα στην πύλη (gateway), το nexus-gateway. Είναι η μόνη υπηρεσία που διατηρεί τα διαπιστευτήρια μοντέλων ενός οργανισμού και λαμβάνει την τελική απόφαση σχετικά με το ποιος πάροχος και ποιο μοντέλο θα απαντήσουν σε κάθε αίτημα. Κάθε άλλο τμήμα του Nexus ρωτά αυτόν. Ένα βήμα ροής εργασίας δηλώνει τι θα ήθελε, και ο δρομολογητής αποφασίζει.
Μόνο λίγες υπηρεσίες επιτρέπεται να ρωτούν, και κάθε λίστα είναι καθορισμένη από το chart:
| Τι ζητείται | Ποιος επιτρέπεται να ζητήσει |
|---|---|
Μια συμπλήρωση (completion) (το /internal/ai/chat και η ροή του) |
nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| Κλήσεις εργαλείων και οι άλλες εσωτερικές διαδρομές AI | nexus-orchestrator, nexus-workflows |
| Ενσωματώσεις (embeddings) και επανακατάταξη (reranking) | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Κάθε εσωτερική διαδρομή ελέγχει δύο πράγματα διαδοχικά: το εσωτερικό κλειδί υπηρεσίας του καλούντος και την ταυτότητα του καλούντος σε αντιπαραβολή με την παραπάνω λίστα. Ένα αίτημα χωρίς το κλειδί απορρίπτεται με MISSING_SERVICE_KEY (401), ένα λάθος κλειδί με INVALID_SERVICE_KEY (403), ένα αίτημα που δεν δηλώνει ποιος καλεί με MISSING_CALLER_IDENTITY (403), και ένας καλών εκτός της λίστας με UNAUTHORIZED_CALLER (403). Κανένα από αυτά δεν επαναλαμβάνεται, επειδή κανένα τους δεν είναι παροδικό σφάλμα.
Οι εφαρμογές και τα πρόσθετα δεν εμφανίζονται ποτέ σε αυτήν τη λίστα. Ένα πρόσθετο δηλώνει τις επιθυμίες του στις δεξιότητες (skills) που καταχωρεί και τις αποστέλλει μέσω του UNO, της μηχανής ροής εργασιών. Στη συνέχεια, ο ενορχηστρωτής (orchestrator) ρωτά τον δρομολογητή εκ μέρους του προσθέτου. Αυτός είναι ο λόγος για τον οποίο ένα μυστικό προσθέτου που έχει διαρρεύσει μπορεί να ενεργήσει ως αυτό το πρόσθετο, αλλά δεν μπορεί να ξοδέψει τον προϋπολογισμό μοντέλων κανενός.
Η δεξαμενή κλειδιών του οργανισμού
Τα κλειδιά μοντέλων ανήκουν στον οργανισμό. Κάθε οργανισμός φέρνει τον δικό του λογαριασμό παρόχου και πληρώνει τον δικό του λογαριασμό, ενώ το κλειδί βρίσκεται στη δεξαμενή του οργανισμού, κρυπτογραφημένο στο nexus-auth. Δεν υπάρχει κοινόχρηστο κλειδί πλατφόρμας πίσω από έναν οργανισμό, επομένως κανένας οργανισμός δεν ξοδεύει ποτέ τον προϋπολογισμό κάποιου άλλου. Το τίμημα αυτού του κανόνα είναι απλό: ένας οργανισμός χωρίς κλειδί στη δεξαμενή του δεν λαμβάνει απαντήσεις AI. Ο βοηθός εμφανίζει MODEL_NOT_CONNECTED (503) και αναφέρει ποιος μπορεί να συνδέσει ένα.
Ένα κλειδί μπορεί να προστεθεί στη δεξαμενή για τέσσερις παρόχους:
| Αναγνωριστικό παρόχου | Εμφανίζεται ως |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Ένας δικός σας διακομιστής μοντέλων
Ένας οργανισμός μπορεί επίσης να χρησιμοποιήσει οποιονδήποτε διακομιστή εκτελεί ο ίδιος και ο οποίος υποστηρίζει το API που είναι συμβατό με OpenAI, όπως το μοντέλο στους κόμβους GPU της Harrow. Το πρόγραμμα εγκατάστασης τον ονομάζει στο αρχείο τιμών (values file):
# harrow-values.yaml (Helm values): the AI part
ai:
localProvider:
baseUrl: "https://models.harrow.example/v1"
installationHosts:
- models.harrow.example
- 10.40.20.0/24
networkPolicy:
externalEgressCIDRs:
- 10.40.20.0/24Το ai.localProvider.baseUrl κατευθύνει τον προσαρμογέα της πύλης που είναι συμβατός με OpenAI στον διακομιστή σας. Σε μια εγκατάσταση, η υποδοχή scaleway της δεξαμενής επικοινωνεί με αυτόν τον διακομιστή, επομένως το κλειδί που προσθέτετε για το scaleway είναι το κλειδί που αναμένει ο δικός σας διακομιστής.
Το ai.installationHosts παραθέτει ονόματα κεντρικών υπολογιστών (host names) που βρίσκονται εντός της εγκατάστασης, πέρα από τον τομέα υπηρεσιών της ίδιας της έκδοσης (release) και τους τρεις δημόσιους κεντρικούς υπολογιστές. Κάθε καταχώριση είναι ένα όνομα κεντρικού υπολογιστή, ένα .suffix, μια διεύθυνση IP ή ένα εύρος IPv4 Classless Inter-Domain Routing (CIDR). Ο δρομολογητής χρησιμοποιεί τη λίστα για να ξεχωρίσει μια κλήση που παραμένει εντός των εγκαταστάσεων από μία που εξέρχεται από αυτές, κάτι που αναφέρει ο έλεγχος «Τίποτα δεν φεύγει από αυτήν την τοποθεσία» στη σελίδα «Σύνδεση μοντέλου στο δικό σας υλικό».
Η πολιτική δικτύου έχει εξίσου μεγάλη σημασία με τον δρομολογητή. Ο χώρος ονομάτων (namespace) απορρίπτει όλη την εξερχόμενη κίνηση (egress) από προεπιλογή, επομένως η πύλη μπορεί να προσεγγίσει έναν διακομιστή μοντέλων εκτός του χώρου ονομάτων μόνο όταν το εύρος του βρίσκεται στο networkPolicy.externalEgressCIDRs. Το ίδιο ισχύει και για έναν φιλοξενούμενο πάροχο: εάν η Harrow θέλει να απαντά το κλειδί της για το Gemini, τα εύρη διευθύνσεων του παρόχου πρέπει επίσης να αναφέρονται εκεί, διαφορετικά η κλήση δεν φεύγει ποτέ από τη συστοιχία (cluster). Το Κεφάλαιο 2.16, Ασφάλεια και δικτύωση, καλύπτει την πολιτική πλήρως.
Προσθήκη και απόσυρση κλειδιών
Οι κάτοχοι και οι διαχειριστές ενός οργανισμού διαχειρίζονται τη δεξαμενή του. Κανένας άλλος δεν μπορεί να δει τα κλειδιά ούτε να τα αλλάξει, και ένα αίτημα από αυτούς απορρίπτεται με AUTHORITY_EXCEEDED.
Στην κονσόλα
Στην έκδοση Enterprise η δεξαμενή διατηρείται στο τηλεφωνικό κέντρο AI, κάτω από τις μηχανές. Στην έκδοση Community τα ίδια κλειδιά διατηρούνται στις Ρυθμίσεις, Μοντέλα AI. Αυτή η σελίδα είναι ο βασικός δρομολογητής, όπου προσθέτετε κλειδιά και μια διεύθυνση τοπικού μοντέλου και επιλέγετε ποιο μοντέλο κάνει ποια εργασία. Και οι δύο εμφανίζουν κάθε κλειδί με βάση το ποιος το όρισε και πότε («Ορίστηκε από την Aoife, 3 Σεπτ») και με μια καλυμμένη ένδειξη των τελευταίων τεσσάρων χαρακτήρων του το πολύ, όπως ••••7f2q. Το ίδιο το κλειδί δεν εμφανίζεται ποτέ ξανά αφού το προσθέσετε.
Μέσω του BFF API
Το backend for frontend (BFF) της κονσόλας εξυπηρετεί τρεις διαδρομές για τη δεξαμενή. Καλέστε τες με το προσωπικό διακριτικό πρόσβασης (access token) ενός ατόμου: ο οργανισμός προκύπτει από το διακριτικό, ποτέ από το αίτημα.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
Το GET απαντά με τους παρόχους στη δεξαμενή, το αν ο καθένας μπορεί να απαντήσει, κάθε κλειδί με την ένδειξή του και τους παρόχους για τους οποίους μπορεί να προστεθεί ένα κλειδί. Η προσθήκη ενός κλειδιού δέχεται ένα σώμα JSON με δύο υποχρεωτικά πεδία και ένα προαιρετικό:
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }Το κλειδί ταξιδεύει μία φορά. Το nexus-auth το κρυπτογραφεί και ενημερώνει τον δρομολογητή, ενώ η απάντηση μεταφέρει μόνο την ένδειξη. Η απάντηση είναι 201 με το αναγνωριστικό του νέου κλειδιού και τη γραμμή του: «Προστέθηκε. Το κλειδί Google Gemini ••••7f2q βρίσκεται στη δεξαμενή AI του οργανισμού και ο AI Provider Router μπορεί πλέον να δρομολογεί σε αυτό.» Μια ετικέτα αποτελείται από το πολύ 100 χαρακτήρες και ένα κλειδί είναι μια συμβολοσειρά χωρίς κενά, το πολύ 4.096 χαρακτήρων. Οποιοδήποτε άλλο πεδίο στο σώμα, ή ένα πεδίο που κατονομάζει έναν οργανισμό ή ένα άτομο, απορρίπτεται.
Η απόσυρση δέχεται ένα κενό σώμα. Ο δρομολογητής σταματά αμέσως τη δρομολόγηση προς το κλειδί και το nexus-auth το διατηρεί, καταχωρισμένο ως αποσυρμένο, ώστε να παραμείνει το ιστορικό του. Τίποτα στη δεξαμενή δεν διαγράφεται ποτέ.
| Απόρριψη | HTTP | Πότε |
|---|---|---|
VALIDATION_FAILED |
400 | Ένα σώμα που δεν είναι {provider, api_key, label?}, ένας άγνωστος πάροχος ή η προσωπική συνδρομή ενός ατόμου που προσφέρεται ως κλειδί οργανισμού |
AUTHORITY_EXCEEDED |
403 | Ο καλών δεν είναι κάτοχος ή διαχειριστής του οργανισμού |
RECORD_NOT_FOUND |
404 | Δεν υπάρχει κλειδί με αυτό το αναγνωριστικό στη δεξαμενή του οργανισμού |
TRANSITION_NOT_PERMITTED |
409 | Το κλειδί έχει ήδη αποσυρθεί |
TENANT_NOT_A_PARAMETER |
403 | Το σώμα ή το ερώτημα (query) κατονόμασε έναν οργανισμό |
Καταστάσεις κλειδιών
Κάθε κλειδί στη δεξαμενή βρίσκεται σε μία από τις έξι καταστάσεις. Μόνο ένα κλειδί σε χρήση απαντά σε μια συνομιλία.
| Κατάσταση | Τι σημαίνει |
|---|---|
in_use |
Το κλειδί απαντά, μέχρι την ημερομηνία λήξης του, εάν έχει. |
resting |
Ο δρομολογητής το έθεσε σε ανάπαυση μετά από αποτυχίες, μέχρι μια καθορισμένη ώρα. Στο μεταξύ, τα αιτήματα πηγαίνουν στο επόμενο κλειδί. |
exhausted |
Εξάντλησε το όριό του στον πάροχο. |
invalid |
Ο πάροχος δεν το αποδέχεται πλέον. |
expired |
Έληξε κατά την ημερομηνία λήξης του. |
withdrawn |
Ένας διαχειριστής το απέσυρε. Παραμένει καταχωρισμένο ως ιστορικό. |
Ένα κλειδί που αποτυγχάνει τίθεται σε ανάπαυση για 60 δευτερόλεπτα. Μετά από 5 συνεχόμενες αποτυχίες, ο δρομολογητής το απενεργοποιεί, μεταφέρει το μερίδιό του στα άλλα κλειδιά και καταγράφει την ειδοποίηση PROVIDER_KEY_SWITCHED_OFF. Κανείς δεν απορρίπτεται όσο ένα άλλο κλειδί μπορεί να απαντήσει.
Όταν ένας πάροχος δεν έχει κλειδί σε χρήση, η δεξαμενή αναφέρει τον λόγο («Κανένα κλειδί σε χρήση: 1 αποσυρμένο, 1 ληγμένο»). Όταν κανένας πάροχος στη δεξαμενή δεν έχει κλειδί σε χρήση, μια συνομιλία απορρίπτεται με NO_PROVIDER_FOR_ROLE (422) και τη λύση: ένας κάτοχος ή διαχειριστής προσθέτει ένα κλειδί οργανισμού. Αυτή είναι μια κατάσταση παραμετροποίησης και παραμένει στην οθόνη μέχρι κάποιος να τη διορθώσει.
Ρόλοι, πολιτική και προτιμήσεις
Ο δρομολογητής λειτουργεί με βάση ρόλους. Κάθε αίτημα αφορά έναν από τους πέντε: default, fast, reasoning, code ή long_context. Κάθε μοντέλο ανήκει επίσης σε μια βαθμίδα (tier), frontier, standard ή fast, και μια υψηλότερη βαθμίδα προτιμάται όταν το επιτρέπει ο ρόλος. Ο οργανισμός αποφασίζει ποιος πάροχος εξυπηρετεί κάθε ρόλο (τις αναθέσεις ρόλων του) και τη σειρά εφεδρείας (fallback) όταν ένας πάροχος αποτυγχάνει (την κλίμακα πολιτικής δρομολόγησης). Οι διαχειριστές ορίζουν και τα δύο στο τηλεφωνικό κέντρο AI. Το nexus-auth τα εξυπηρετεί επίσης στα /auth/org/<organisation-id>/settings/ai-provider/role-assignments και /auth/org/<organisation-id>/settings/ai-provider/routing-policy για ένα κλειδί διαχειριστή που διαθέτει το ai_provider:manage.
Οι καλούντες μπορούν να δηλώσουν τι θα ήθελαν. Μια γραμμή δεξιότητας μπορεί να φέρει έναν προτιμώμενο πάροχο και ένα προτιμώμενο μοντέλο, συν ένα προφίλ δυνατοτήτων. Ο δρομολογητής αντιμετωπίζει το καθένα διαφορετικά:
- Ένας προτιμώμενος πάροχος ικανοποιείται μόνο όταν ο οργανισμός έχει ενεργοποιήσει αυτόν τον πάροχο και διαθέτει κλειδί για αυτόν. Διαφορετικά, ο δρομολογητής τον αντικαθιστά.
- Ένα προτιμώμενο μοντέλο ικανοποιείται όταν βρίσκεται στον κατάλογο αυτού του παρόχου και ταιριάζει στο προφίλ.
- Ένα προφίλ δυνατοτήτων είναι ένα φίλτρο που δεν επιλέγει ποτέ. Μπορεί να ζητήσει ένα ελάχιστο παράθυρο συμφραζομένων (context window), χρήση εργαλείων, όραση (vision), ενσωματώσεις (embeddings), εκτεταμένο πλαίσιο συμφραζομένων (long context) ή μια τοποθεσία αποθήκευσης δεδομένων (data residency). Οτιδήποτε δεν πληροί το προφίλ δεν είναι επιλέξιμο.
Ο δρομολογητής επιλέγει με καθορισμένη σειρά. Ικανοποιεί την επιθυμία όταν μπορεί, έπειτα δοκιμάζει ένα άλλο μοντέλο του ίδιου παρόχου, στη συνέχεια την ανάθεση ρόλου και οποιονδήποτε άλλο πάροχο με κλειδί του οποίου ο κατάλογος ταιριάζει. Εάν δόθηκε ένα προφίλ και κανένας κατάλογος δεν ταιριάζει σε αυτό, το αίτημα απορρίπτεται με MODEL_CAPABILITY_UNAVAILABLE (422). Εάν δεν έχει ανατεθεί τίποτα και τίποτα δεν ταιριάζει, επιστρέφεται NO_PROVIDER_FOR_ROLE (422). Δεν υπάρχει προεπιλεγμένο μοντέλο έσχατης ανάγκης. Ένας ρόλος που δεν έχετε παραμετροποιήσει αποτυγχάνει εμφανώς, με τα λόγια του ίδιου του δρομολογητή να αναφέρουν τι πρέπει να οριστεί.
Η τοποθεσία αποθήκευσης δεδομένων (data residency) είναι ο μόνος περιορισμός που δεν μπορεί να παρακαμφθεί μέσω αντικατάστασης. Ένα προφίλ με eu_only εξυπηρετείται από έναν πάροχο της ΕΕ ή απορρίπτεται. Η Harrow ορίζει αυτό το κλείδωμα για ολόκληρο τον οργανισμό και το τηλεφωνικό κέντρο εμφανίζει τον δεύτερο φιλοξενούμενο πάροχο, ο οποίος βρίσκεται σε περιοχή των ΗΠΑ, ως απενεργοποιημένο.
Μια δεξιότητα μπορεί επίσης να καρφιτσώσει ένα ακριβές μοντέλο όταν η δεξιότητα χρειάζεται αυτό το μοντέλο για να λειτουργήσει. Ακόμη και τότε ο δρομολογητής χρησιμοποιεί το κλειδί του ίδιου του οργανισμού για αυτό, και χωρίς κλειδί τίποτα δεν απαντά. Ένας καλών δεν μπορεί ποτέ να κάνει το Nexus να χρησιμοποιήσει έναν πάροχο που ο οργανισμός δεν έχει παραμετροποιήσει.
Μόλις επιλεγεί ένας πάροχος, η μετάβαση σε εφεδρικό σύστημα (failover) είναι ξεχωριστό ζήτημα. Ένα σφάλμα 429, ένα 5xx ή μια αποτυχία δικτύου μετακινεί το αίτημα προς τα κάτω στην κλίμακα, στον επόμενο πάροχο. Ένα 400, 401, 403 ή 404 σταματά αμέσως, επειδή τα διαπιστευτήρια και οι μορφές αιτημάτων δεν μεταφέρονται μεταξύ παρόχων και μια επανάληψη θα κατανάλωνε το όριο (quota) για να καταλήξει στην ίδια αποτυχία.
Για να δείτε τι θα επέλεγε ο δρομολογητής πριν κανείς κάνει μια ερώτηση, διαβάστε το GET /api/ai/routing-policy/effective στην πύλη με το προσωπικό διακριτικό ενός ατόμου. Απαντά με το μοντέλο για τον συνδεδεμένο οργανισμό, ή με την απόρριψη του δρομολογητή ολογράφως όταν δεν υπάρχει κανένα, και δεν στέλνει κανένα αίτημα σε μοντέλο.
Παρακολούθηση του δρομολογητή
Η λωρίδα στοιχείων στο κάτω μέρος κάθε σελίδας δείχνει το μοντέλο που βρίσκεται σε χρήση («Μοντέλο: τοπικό»). Στην έκδοση Enterprise, η σελίδα «Το τηλεφωνικό κέντρο AI, ζωντανά» σχεδιάζει την κίνηση του δρομολογητή την ώρα που συμβαίνει: αιτήματα από τον βοηθό, εργασίες και εφαρμογές που ρέουν μέσω ρόλων προς παρόχους και κλειδιά, ένα κλειδί στην ανάπαυση των 60 δευτερολέπτων σχεδιασμένο με γκρι χρώμα, ένα απενεργοποιημένο κλειδί σχεδιασμένο με κόκκινο και μια μετάβαση στον φιλοξενούμενο πάροχο όταν το τοπικό μοντέλο είναι απασχολημένο. Δίπλα στη ροή απεικονίζει σε γράφημα τον φόρτο ανά πάροχο, τα αιτήματα ανά δευτερόλεπτο και τον χρόνο αναμονής. Ο Tomás την κρατά ανοιχτή κατά την πρώτη εβδομάδα μετά από κάθε αλλαγή στην πολιτική δρομολόγησης, επειδή μια λανθασμένη ανάθεση ρόλου εμφανίζεται εκεί μέσα σε λίγα λεπτά ως κίνηση που πηγαίνει κάπου που κανείς δεν σκόπευε.
Στην έκδοση Community, η σελίδα Μοντέλα AI διαθέτει ένα κουμπί «Δοκιμή κάθε μοντέλου» που ελέγχει κάθε παραμετροποιημένο μοντέλο και σημειώνει εάν απαντά. Είναι ο ταχύτερος τρόπος για να αποδείξετε ότι ένα νέο κλειδί λειτουργεί πριν βασιστεί κανείς σε αυτό.
Ενσωματώσεις (Embeddings)
Η αναζήτηση και το γράφημα γνώσης μετατρέπουν το κείμενο σε διανύσματα (vectors). Από προεπιλογή, η εγκατάσταση το κάνει αυτό με ένα μοντέλο ενσωμάτωσης (embedding model) που εκτελείται εντός της συστοιχίας στον επεξεργαστή, επομένως κανένα κείμενο δεν φεύγει από την τοποθεσία για να ενσωματωθεί και ένας οργανισμός δεν χρειάζεται κλειδί για αυτό. Η χρήση ενός φιλοξενούμενου παρόχου για ενσωματώσεις είναι μια επιλογή που κάνει ένας οργανισμός· στη συνέχεια διέρχεται από την ίδια δεξαμενή και τους ίδιους κανόνες.
Μόνο τρεις υπηρεσίες επιτρέπεται να ζητήσουν από τον δρομολογητή ενσωματώσεις ή επανακατάταξη: τα nexus-graphrag, nexus-skills-engine και nexus-workflows. Το GraphRAG πραγματοποιεί ενσωματώσεις ως ο οργανισμός στον οποίο ανήκει το περιεχόμενο, με τις ρυθμίσεις αυτού του οργανισμού, και δεν διατηρεί δικό του κλειδί παρόχου. Όταν ένας οργανισμός αλλάζει το μοντέλο ενσωμάτωσής του, το nexus-workflows εκτελεί την εργασία εκ νέου ενσωμάτωσης για τους χώρους αποθήκευσης αυτού του οργανισμού.
Τα ατομικά διαπιστευτήρια παραμένουν προσωπικά
Ορισμένα διαπιστευτήρια ανήκουν σε ένα άτομο. Μια συνδρομή Claude Max, συνδεδεμένη μέσω του προσωπικού λογαριασμού αυτού του ατόμου, είναι η συνηθισμένη περίπτωση. Ένα τέτοιο διαπιστευτήριο δεν αποτελεί ποτέ κλειδί οργανισμού: η δεξαμενή το απορρίπτει με VALIDATION_FAILED, δεν καταχωρίζεται ποτέ στον πίνακα κλειδιών του οργανισμού και καμία οθόνη άλλου ατόμου δεν το εμφανίζει.
Τα κλειδιά μοντέλων επίσης δεν πηγαίνουν ποτέ πουθενά αλλού. Η σελίδα Κλειδιά εξωτερικών δεδομένων, η οποία διατηρεί κλειδιά για εξωτερικές πηγές δεδομένων, απορρίπτει οτιδήποτε μοιάζει με κλειδί μοντέλου AI με AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Εάν ο αναγνώστης αρχείων βρει κλειδιά μοντέλων μέσα σε ένα έγγραφο ή μια παραμετροποίηση όπου δεν ανήκουν, καταγράφει CREDENTIALS_IN_WRONG_PLACE και ένας διαχειριστής τα αφαιρεί και τα αντικαθιστά.
Σενάρια, REST και MCP
Το Nexus διαθέτει τρεις δημόσιους κεντρικούς υπολογιστές (hosts). Στη Harrow είναι το console.harrow.example για την κονσόλα, το api.harrow.example για την πύλη και το auth.harrow.example για τη σύνδεση. Τα σενάρια και τα εργαλεία χρησιμοποιούν τον δεύτερο και τον τρίτο.
Κλειδιά για σενάρια
Ένα σενάριο (script) συνδέεται με ένα κλειδί που δημιουργείται στις Ρυθμίσεις, Κλειδιά για σενάρια. Κάθε κλειδί έχει ένα όνομα, μια εμβέλεια (για παράδειγμα, «Έναρξη καταμέτρησης χώρου με drone μόνο»), το άτομο που το δημιούργησε και μια ημερομηνία λήξης· ένας οργανισμός μπορεί να κλειδώσει τη μέγιστη διάρκεια ζωής που μπορεί να έχει ένα κλειδί. Το μυστικό εμφανίζεται μία φορά όταν δημιουργείται το κλειδί. Αντιγράψτε το στον χώρο αποθήκευσης μυστικών του σεναρίου, επειδή το Nexus κρατά μόνο τους τελευταίους τέσσερις χαρακτήρες του. Ένα κλειδί αποσύρεται, δεν αφαιρείται ποτέ: σταματά αμέσως και παραμένει καταχωρισμένο με κάθε κλήση που πραγματοποίησε. Η εναλλαγή (rotation) δίνει στο κλειδί ένα νέο μυστικό και το εμφανίζει μία φορά.
Κάθε κλειδί έχει τη δική του σελίδα με κλήσεις ανά ημέρα, κλήσεις ανά υπηρεσία και ένα αρχείο καταγραφής δραστηριότητας με ώρα, διεύθυνση, υπηρεσία και αποτέλεσμα. Μια κλήση εκτός της εμβέλειας του κλειδιού απορρίπτεται και εμφανίζεται στο αρχείο καταγραφής.
Το nexus-auth εξυπηρετεί τα ίδια κλειδιά σε ένα συνδεδεμένο άτομο στο https://auth.harrow.example/api-keys: δημιουργία και εμφάνιση λίστας, και έπειτα ανάγνωση, αλλαγή, ανάκληση ή εναλλαγή ενός κλειδιού με βάση το αναγνωριστικό του.
REST μέσω της πύλης
Στείλτε κλήσεις REST στο https://api.harrow.example με Authorization: Bearer <token-or-key>. Κάθε κλειδί πρέπει να ανήκει σε έναν οργανισμό. Ένα κλειδί που δεν ανήκει σε κανέναν απορρίπτεται με TOKEN_ORG_MISSING (403) από κάθε υπηρεσία που ελέγχει κλειδιά μέσω του nexus-auth.
Ένας καλών που υποβάλλει αιτήματα πολύ συχνά λαμβάνει απάντηση 429 με RATE_LIMITED, μια κεφαλίδα Retry-After και το όριο και το χρονικό παράθυρο στο σώμα. Περιμένετε για τον αριθμό των δευτερολέπτων που δίνει. Στην έκδοση Enterprise, οι διαχειριστές ορίζουν όρια ανά κλειδί, ανά εφαρμογή και ανά μονάδα στις Ρυθμίσεις, Όρια ρυθμού (Rate limits) (βλ. κεφάλαιο 2.16, Ασφάλεια και δικτύωση).
MCP για εργαλεία AI
Τα εργαλεία AI που υποστηρίζουν το Model Context Protocol συνδέονται στο https://api.harrow.example/mcp. Συνδέονται μέσω του διακομιστή OAuth 2.1 (το OAuth είναι το ανοιχτό πρότυπο για εξουσιοδότηση κατ' εξουσιοδότηση) στο https://auth.harrow.example, ο οποίος υποστηρίζει εγγραφή πελάτη από το ίδιο το εργαλείο, ώστε ένα εργαλείο όπως το Claude Code ή το Cursor να εγγράφεται μόνο του και να ανοίγει το πρόγραμμα περιήγησης του ατόμου για σύνδεση. Στη συνέχεια, η σύνδεση ενεργεί για αυτό το ένα άτομο, με τα δικαιώματα αυτού του ατόμου και τίποτα περισσότερο. Ένα συνδεδεμένο άτομο μπορεί να ανακτήσει μια έτοιμη παραμετροποίηση για ένα εργαλείο γραμμής εντολών από το https://auth.harrow.example/api/v1/mcp/cli-config.
Οι κλήσεις εργαλείων που χρειάζονται ένα μοντέλο διέρχονται από τον δρομολογητή όπως καθετί άλλο, υπό τον οργανισμό του ατόμου.




