Sürüm 1.0.0-alpha.1en son
Bölüm 2.14
YZ sağlayıcıları ve modelleri
Yapay zeka (YZ) Sağlayıcı Yönlendiricisinin (Provider Router) kuruluşun kendi anahtar havuzundan bir modeli nasıl seçtiği ve betikler ile YZ araçlarının dışarıdan Nexus'a nasıl ulaştığı.
Bu sayfa, İngilizce aslından YZ tarafından çevrilmiştir. Anlaşılmayan bir yer olursa İngilizce sayfa esas alınır. Bu sayfayı İngilizce okuyun

Harrow Port Authority iki kurulum çalıştırmaktadır. Hava boşluklu (air-gapped) operasyon ağındaki kurulumda (bölüm 2.10, Hava boşluklu kurulum) barındırılan hiçbir sağlayıcı yoktur. Bu bölümde ele alınan bağlantılı kurumsal kurulumda ise soruların çoğu, limanın kendi sunucu odasındaki iki grafik işlem birimi (GPU) düğümünde çalışan bir model tarafından yanıtlanır. Harrow tarafından ödenen bir Google Gemini anahtarı, yerel model meşgul olduğunda taşan trafiği üstlenir ve Aoife Brennan, kuruluşun yapay zekâ (YZ) trafiğini AB ile sınırlandırmıştır. Harrow'da hiç kimse bir hizmet veya eklenti içinde bir model yapılandırmamıştır. Tek bir bileşene Harrow'un neye sahip olduğunu söylemişlerdir ve her çağrıya o bileşen karar verir.
Bu bölüm, 1. Kısımda ve konsolda YZ santrali olarak adlandırılan söz konusu bileşeni, yani AI Provider Router'ı ve onun kullandığı anahtar havuzunu ele almaktadır. Bölüm, betiklerin ve YZ araçlarının Nexus'a dışarıdan ulaşma yollarıyla sona erer: betikler için anahtarlar, REST (temsili durum aktarımı) uygulama programlama arayüzü (API) ve Model Bağlam Protokolü (MCP).
AI Provider Router
Yönlendirici, ağ geçidi olan nexus-gateway içinde çalışır. Bir kuruluşun model kimlik bilgilerini tutan tek hizmettir ve her isteği hangi sağlayıcının ve hangi modelin yanıtlayacağına dair nihai kararı verir. Nexus'un diğer her parçası ona sorar. Bir iş akışı adımı ne istediğini söyler ve yönlendirici karar verir.
Yalnızca birkaç hizmet sorabilir ve her liste şema (chart) tarafından sabitlenmiştir:
| Ne sorulur | Kim sorabilir |
|---|---|
Bir tamamlama (/internal/ai/chat ve akışı) |
nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| Araç çağrıları ve diğer dahili YZ rotaları | nexus-orchestrator, nexus-workflows |
| Gömme (embeddings) ve yeniden sıralama (reranking) | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Her dahili rota sırasıyla iki şeyi kontrol eder: çağıranın dahili hizmet anahtarını ve çağıranın yukarıdaki listeye göre kimliğini. Anahtarı olmayan bir istek MISSING_SERVICE_KEY (401) ile, yanlış bir anahtar INVALID_SERVICE_KEY (403) ile, kimin çağırdığını belirtmeyen bir istek MISSING_CALLER_IDENTITY (403) ile ve liste dışındaki bir çağıran UNAUTHORIZED_CALLER (403) ile reddedilir. Bunların hiçbiri geçici bir arıza olmadığı için hiçbiri yeniden denenmez.
Uygulamalar ve eklentiler bu listede asla yer almaz. Bir eklenti, kaydettiği beceriler üzerindeki isteklerini bildirir ve bunları iş akışı motoru olan UNO aracılığıyla gönderir. Ardından orkestratör, eklenti adına yönlendiriciye sorar. Bu nedenle, sızdırılan bir eklenti sırrı o eklenti gibi davranabilir ancak kimsenin model bütçesini harcayamaz.
Kuruluşun anahtar havuzu
Model anahtarları kuruluşa aittir. Her kuruluş kendi sağlayıcı hesabını getirir ve kendi faturasını öder; anahtar, kuruluşun havuzunda, nexus-auth içinde şifrelenmiş olarak bulunur. Bir kuruluşun arkasında paylaşılan bir platform anahtarı yoktur, bu nedenle hiçbir kuruluş başka bir kuruluşun bütçesini harcamaz. Bu kuralın bedeli açıktır: havuzunda anahtarı olmayan bir kuruluş hiçbir YZ yanıtı alamaz. Asistan MODEL_NOT_CONNECTED (503) gösterir ve kimin bir anahtar bağlayabileceğini söyler.
Havuza dört sağlayıcı için anahtar eklenebilir:
| Sağlayıcı kimliği | Gösterim şekli |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Kendi model sunucunuz
Bir kuruluş, Harrow'un GPU düğümlerindeki model gibi, OpenAI uyumlu API'yi konuşan kendi çalıştırdığı herhangi bir sunucuyu da kullanabilir. Kurulum programı bunu değerler (values) dosyasında adlandırır:
# 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/24ai.localProvider.baseUrl, ağ geçidinin OpenAI uyumlu bağdaştırıcısını sunucunuza yönlendirir. Bir kurulumda, havuzun scaleway yuvası o sunucuya ulaşır, dolayısıyla scaleway için eklediğiniz anahtar, kendi sunucunuzun beklediği anahtardır.
ai.installationHosts, sürümün kendi hizmet alanı ve üç genel ana bilgisayar (host) dışında, kurulumun içinde yer alan ana bilgisayar adlarını listeler. Her girdi bir ana bilgisayar adı, bir .suffix, bir IP adresi veya bir IPv4 Sınıfsız Alanlar Arası Yönlendirme (CIDR) aralığıdır. Yönlendirici, tesis içinde kalan bir çağrıyı dışarı çıkan bir çağrıdan ayırt etmek için bu listeyi kullanır; Kendi donanımınızda bir model bağlayın sayfasındaki "Bu tesisten hiçbir şey çıkmaz" kontrolünün raporladığı şey budur.
Ağ politikası da yönlendirici kadar önemlidir. Ad alanı (namespace) varsayılan olarak tüm çıkışları reddeder, bu nedenle ağ geçidi ad alanı dışındaki bir model sunucusuna yalnızca aralığı networkPolicy.externalEgressCIDRs içinde olduğunda ulaşabilir. Aynı durum barındırılan bir sağlayıcı için de geçerlidir: Harrow, Gemini anahtarının yanıt vermesini istiyorsa, sağlayıcının adres aralıklarının da orada listelenmesi gerekir, aksi takdirde çağrı kümeden asla çıkmaz. Bölüm 2.16, Güvenlik ve ağ iletişimi, politikayı tüm ayrıntılarıyla ele almaktadır.
Anahtar ekleme ve geri çekme
Bir kuruluşun havuzunu sahipleri ve yöneticileri tutar. Başka hiç kimse anahtarları göremez ve değiştiremez; onlardan gelen bir istek AUTHORITY_EXCEEDED ile reddedilir.
Konsolda
Enterprise sürümünde havuz, motorların altında, YZ santralinde tutulur. Community sürümünde aynı anahtarlar Ayarlar, YZ modelleri sayfasında tutulur. Bu sayfa, anahtarları ve bir yerel model adresini eklediğiniz ve hangi modelin hangi işi yapacağını seçtiğiniz temel yönlendiricidir. Her ikisi de her anahtarı kimin ne zaman ayarladığına göre ("Aoife tarafından ayarlandı, 3 Eyl") ve ••••7f2q gibi en fazla son dört karakterinin maskelenmiş bir ipucuyla gösterir. Anahtarın kendisi, siz onu ekledikten sonra bir daha asla gösterilmez.
BFF API aracılığıyla
Konsolun ön uç için arka ucu (BFF), havuz için üç rota sunar. Bunları bir kişinin kendi erişim belirteciyle (token) çağırın: kuruluş asla istekten değil, belirteçten gelir.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
GET, havuzdaki sağlayıcıları, her birinin yanıt verip veremeyeceğini, ipucuyla birlikte her anahtarı ve kendisi için anahtar eklenebilecek sağlayıcıları yanıtlar. Bir anahtar eklemek, iki zorunlu ve bir isteğe bağlı alana sahip bir JSON gövdesi alır:
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }Anahtar bir kez yolculuk eder. nexus-auth onu şifreler ve yönlendiriciye bildirir; yanıt yalnızca ipucunu taşır. Yanıt, yeni anahtarın kimliği ve satırıyla birlikte 201 şeklindedir: "Eklendi. Google Gemini anahtarı ••••7f2q kuruluşun YZ havuzunda ve AI Provider Router artık ona yönlendirme yapabilir." Bir etiket en fazla 100 karakterdir ve bir anahtar en fazla 4.096 karakterden oluşan boşluksuz tek bir dizedir. Gövdedeki başka herhangi bir alan veya bir kuruluşu ya da kişiyi adlandıran bir alan reddedilir.
Geri çekme işlemi boş bir gövde alır. Yönlendirici anahtara yönlendirme yapmayı derhal durdurur ve nexus-auth, geçmişinin kalması için onu geri çekilmiş olarak listelenmiş şekilde tutar. Havuzdaki hiçbir şey asla silinmez.
| Reddetme | HTTP | Ne zaman |
|---|---|---|
VALIDATION_FAILED |
400 | {provider, api_key, label?} olmayan bir gövde, bilinmeyen bir sağlayıcı veya kuruluş anahtarı olarak sunulan bir kişinin kendi aboneliği |
AUTHORITY_EXCEEDED |
403 | Çağıran, kuruluşun sahibi veya yöneticisi değil |
RECORD_NOT_FOUND |
404 | Kuruluşun havuzunda bu kimliğe sahip bir anahtar yok |
TRANSITION_NOT_PERMITTED |
409 | Anahtar zaten geri çekilmiş |
TENANT_NOT_A_PARAMETER |
403 | Gövde veya sorgu bir kuruluşu adlandırdı |
Anahtar durumları
Havuzdaki her anahtar altı durumdan birindedir. Bir sohbeti yalnızca kullanımda olan bir anahtar yanıtlar.
| Durum | Anlamı |
|---|---|
in_use |
Anahtar, varsa son kullanma tarihine kadar yanıt verir. |
resting |
Yönlendirici, hatalardan sonra belirli bir zamana kadar onu dinlendirmeye aldı. Bu sırada istekler bir sonraki anahtara gider. |
exhausted |
Sağlayıcıdaki limitini tüketti. |
invalid |
Sağlayıcı artık onu kabul etmiyor. |
expired |
Son kullanma tarihinde süresi doldu. |
withdrawn |
Bir yönetici onu geri çekti. Geçmiş olarak listelenmeye devam eder. |
Başarısız olan bir anahtar 60 saniye boyunca dinlenir. Arka arkaya 5 hatadan sonra yönlendirici onu kapatır, payını diğer anahtarlara taşır ve PROVIDER_KEY_SWITCHED_OFF bildirimini kaydeder. Başka bir anahtar yanıt verebildiği sürece kimse reddedilmez.
Bir sağlayıcının kullanımda anahtarı olmadığında, havuz nedenini söyler ("Kullanımda anahtar yok: 1 geri çekildi, 1 süresi doldu"). Havuzdaki hiçbir sağlayıcının kullanımda anahtarı olmadığında, bir sohbet NO_PROVIDER_FOR_ROLE (422) ve çözüm yolu ile reddedilir: bir sahip veya yönetici bir kuruluş anahtarı ekler. Bu bir yapılandırma durumudur ve birisi düzeltene kadar ekranda kalır.
Roller, ilke ve istekler
Yönlendirici roller halinde düşünür. Her istek beş rolden biri içindir: default, fast, reasoning, code veya long_context. Her model aynı zamanda frontier, standard veya fast olmak üzere bir katmandadır ve rol izin verdiğinde daha yüksek bir katman tercih edilir. Kuruluş, her role hangi sağlayıcının hizmet vereceğine (rol atamaları) ve bir sağlayıcı başarısız olduğunda hangi sırayla yedeklemeye geçileceğine (yönlendirme politikası merdiveni) karar verir. Yöneticiler her ikisini de YZ santralinde ayarlar. nexus-auth ayrıca bunları ai_provider:manage tutan bir yönetici anahtarı için /auth/org/<organisation-id>/settings/ai-provider/role-assignments ve /auth/org/<organisation-id>/settings/ai-provider/routing-policy adreslerinde sunar.
Çağıranlar ne istediklerini söyleyebilirler. Bir beceri satırı, tercih edilen bir sağlayıcıyı ve tercih edilen bir modeli, ayrıca bir yetenek profilini taşıyabilir. Yönlendirici her birini farklı şekilde ele alır:
- Tercih edilen bir sağlayıcı, yalnızca kuruluş o sağlayıcıyı etkinleştirdiğinde ve onun için bir anahtara sahip olduğunda dikkate alınır. Aksi takdirde yönlendirici başka bir sağlayıcıyı ikame eder.
- Tercih edilen bir model, o sağlayıcının kataloğunda yer aldığında ve profile uyduğunda dikkate alınır.
- Bir yetenek profili, asla seçim yapmayan bir filtredir. Minimum bir bağlam penceresi, araç kullanımı, görüntü işleme (vision), gömmeler (embeddings), uzun bağlam veya bir veri yerleşimi isteyebilir. Bunu karşılamayan hiçbir şey uygun değildir.
Yönlendirici sabit bir sırayla seçim yapar. Mümkün olduğunda isteği yerine getirir, ardından aynı sağlayıcının başka bir modelini dener, daha sonra rol atamasını ve kataloğu uyan bir anahtara sahip başka herhangi bir sağlayıcıyı dener. Bir profil verilmişse ve hiçbir katalog buna uymuyorsa, istek MODEL_CAPABILITY_UNAVAILABLE (422) ile reddedilir. Hiçbir şey atanmamışsa ve hiçbir şey eşleşmiyorsa, NO_PROVIDER_FOR_ROLE (422) olur. Son çare olarak kullanılan varsayılan bir model yoktur. Yapılandırmadığınız bir rol, yönlendiricinin neyin ayarlanması gerektiğini kendi sözleriyle belirttiği açık bir şekilde başarısız olur.
Veri yerleşimi, etrafından dolaşılarak ikame edilemeyen tek kısıtlamadır. eu_only içeren bir profile bir AB sağlayıcısı tarafından hizmet verilir veya profil reddedilir. Harrow bu kilidi tüm kuruluş için ayarlar ve santral, bir ABD bölgesinde bulunan ikinci barındırılan sağlayıcıyı kapalı olarak gösterir.
Bir beceri, çalışmak için belirli bir modele ihtiyaç duyduğunda o modeli tam olarak sabitleyebilir. O zaman bile yönlendirici bunun için kuruluşun kendi anahtarını kullanır ve anahtar olmadan hiçbir şey yanıt vermez. Bir çağıran, Nexus'a asla kuruluşun yapılandırmadığı bir sağlayıcıyı kullandıramaz.
Bir sağlayıcı seçildikten sonra, hata durumunda yedeklemeye geçiş (failover) ayrı bir konudur. Bir 429, bir 5xx veya bir ağ hatası, isteği merdivenden aşağıya, bir sonraki sağlayıcıya taşır. Bir 400, 401, 403 veya 404 derhal durur, çünkü kimlik bilgileri ve istek biçimleri sağlayıcılar arasında taşınmaz ve yeniden denemek aynı hataya ulaşmak için kotayı harcar.
Henüz kimse bir soru sormadan önce yönlendiricinin ne seçeceğini görmek için, bir kişinin kendi belirteciyle ağ geçidindeki GET /api/ai/routing-policy/effective adresini okuyun. Oturum açmış kuruluş için modeli veya model olmadığında yönlendiricinin reddini sözcüklerle yanıtlar ve bir modele hiçbir istek göndermez.
Yönlendiriciyi izleme
Her sayfanın altındaki rakamlar şeridi kullanımda olan modeli gösterir ("Model: yerel"). Enterprise sürümünde, YZ santrali, canlı sayfası yönlendiricinin trafiğini gerçekleştiği anda çizer: asistandan, işlerden ve uygulamalardan roller aracılığıyla sağlayıcılara ve anahtarlara akan istekler, 60 saniyelik dinlenmesinde gri çizilen bir anahtar, kapatıldığında kırmızı çizilen bir anahtar ve yerel model meşgul olduğunda barındırılan sağlayıcıya yedekleme geçişi. Akışın yanında sağlayıcı başına yükü, saniyedeki istek sayısını ve bekleme süresini grafikleştirir. Tomás, yönlendirme politikasındaki herhangi bir değişiklikten sonraki ilk hafta boyunca bunu açık tutar, çünkü yanlış bir rol ataması, birkaç dakika içinde trafiğin kimsenin amaçlamadığı bir yere gitmesiyle orada kendini gösterir.
Community sürümünde, YZ modelleri sayfasında yapılandırılmış her modeli kontrol eden ve yanıt verip vermediğini işaretleyen bir Her modeli test et düğmesi vardır. Birisi ona güvenmeden önce yeni bir anahtarın çalıştığını kanıtlamanın en hızlı yoludur.
Gömme vektörleri (Embeddings)
Arama ve bilgi grafiği metni vektörlere dönüştürür. Varsayılan olarak kurulum bunu küme içinde işlemci üzerinde çalışan bir gömme (embedding) modeliyle yapar, böylece gömülmek üzere tesisten hiçbir metin çıkmaz ve bir kuruluşun bunun için anahtara ihtiyacı olmaz. Gömmeler için barındırılan bir sağlayıcı kullanmak bir kuruluşun yaptığı bir seçimdir; bu durumda aynı havuzdan ve aynı kurallardan geçer.
Yönlendiriciden yalnızca üç hizmet gömme veya yeniden sıralama isteyebilir: nexus-graphrag, nexus-skills-engine ve nexus-workflows. GraphRAG, içeriğin sahibi olan kuruluş olarak, o kuruluşun ayarlarıyla gömme yapar ve kendisine ait hiçbir sağlayıcı anahtarı tutmaz. Bir kuruluş gömme modelini değiştirdiğinde, nexus-workflows o kuruluşun depoları için yeniden gömme işini çalıştırır.
Kişi başı kimlik bilgileri kişisel kalır
Bazı kimlik bilgileri tek bir kişiye aittir. O kişinin kendi hesabı üzerinden oturum açılan bir Claude Max aboneliği yaygın bir durumdur. Böyle bir kimlik bilgisi asla bir kuruluş anahtarı değildir: havuz bunu VALIDATION_FAILED ile reddeder, kuruluşun anahtarlar tablosunda asla listelenmez ve başka bir kişinin hiçbir ekranı bunu göstermez.
Model anahtarları başka hiçbir yere de gitmez. Dış veri kaynakları için anahtarları tutan Harici veri anahtarları sayfası, bir YZ model anahtarına benzeyen her şeyi AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422) ile reddeder. Dosya okuyucu, ait olmadıkları bir belge veya yapılandırma içinde model anahtarları bulursa CREDENTIALS_IN_WRONG_PLACE kaydeder ve bir yönetici bunları kaldırıp değiştirir.
Betikler, REST ve MCP
Nexus'un üç genel ana bilgisayarı vardır. Harrow'da bunlar konsol için console.harrow.example, ağ geçidi için api.harrow.example ve oturum açma için auth.harrow.example şeklindedir. Betikler ve araçlar ikinci ve üçüncüyü kullanır.
Betikler için anahtarlar
Bir betik, Ayarlar, Betikler için anahtarlar sayfasında oluşturulan bir anahtarla oturum açar. Her anahtarın bir adı, bir erişim kapsamı (örneğin, "Yalnızca Drone saha sayımını başlat"), onu oluşturan kişi ve bir bitiş tarihi vardır; bir kuruluş bir anahtarın sahip olabileceği en uzun ömrü kilitleyebilir. Sır, anahtar oluşturulduğunda bir kez gösterilir. Bunu betiğin sır deposuna kopyalayın, çünkü Nexus yalnızca son dört karakterini tutar. Bir anahtar geri çekilir, asla kaldırılmaz: derhal durur ve yaptığı her çağrıyla birlikte listelenmeye devam eder. Döndürme (rotating) işlemi anahtara yeni bir sır verir ve bunu bir kez gösterir.
Her anahtarın günlük çağrıları, hizmete göre çağrıları ve zaman, adres, hizmet ve sonuçtan oluşan bir etkinlik günlüğünü içeren kendi sayfası vardır. Anahtarın erişim kapsamı dışındaki bir çağrı reddedilir ve günlükte gösterilir.
nexus-auth, oturum açmış bir kişiye https://auth.harrow.example/api-keys adresinde aynı anahtarları sunar: oluşturma ve listeleme, ardından kimliğine göre bir anahtarı okuma, değiştirme, iptal etme veya döndürme.
Ağ geçidi üzerinden REST
REST çağrılarını Authorization: Bearer <token-or-key> ile https://api.harrow.example adresine gönderin. Her anahtar bir kuruluşa ait olmalıdır. Hiçbir kuruluşa ait olmayan bir anahtar, nexus-auth aracılığıyla anahtarları kontrol eden her hizmet tarafından TOKEN_ORG_MISSING (403) ile reddedilir.
Çok sık istekte bulunan bir çağırana RATE_LIMITED ile 429, bir Retry-After üstbilgisi ve gövdede limit ile pencere bilgileri yanıt olarak verilir. Verdiği saniye sayısı kadar bekleyin. Enterprise sürümünde yöneticiler Ayarlar, Hız limitleri sayfasında anahtar başına, uygulama başına ve birim başına limitler belirler (bkz. bölüm 2.16, Güvenlik ve ağ iletişimi).
YZ araçları için MCP
Model Bağlam Protokolü'nü konuşan YZ araçları https://api.harrow.example/mcp adresine bağlanır. Aracın kendisi tarafından istemci kaydını destekleyen https://auth.harrow.example adresindeki OAuth 2.1 sunucusu (OAuth, devredilmiş yetkilendirme için açık standarttır) üzerinden oturum açarlar; böylece Claude Code veya Cursor gibi bir araç kendisini kaydeder ve oturum açmak için kişinin tarayıcısını açar. Bağlantı daha sonra o tek kişi adına, o kişinin haklarıyla ve fazlası olmadan hareket eder. Oturum açmış bir kişi, bir komut satırı aracı için hazır bir yapılandırmayı https://auth.harrow.example/api/v1/mcp/cli-config adresinden alabilir.
Bir modele ihtiyaç duyan araç çağrıları, kişinin kuruluşu altında diğer her şey gibi yönlendiriciden geçer.




