Skip to main content

Seni bina penyelesaian

Yabanin ialah gerbang AI kendalian sendiri. Aplikasi dan ejen yang serasi menghantar permintaan model kepadanya; gerbang menggunakan kawalan yang dikonfigurasi, memilih huluan, memajukan permintaan dan merekod bukti operasi. Alat pembangunan pelanggan kekal bertanggungjawab untuk menyunting kod, menjalankan ujian dan menerima perubahan.

Dokumen ini menerangkan perlaksanaan yang diperiksa pada 24 September 2026. Rajah-rajah ini ialah pandangan logik, bukan dakwaan bahawa setiap ciri didayakan dalam setiap pemasangan. Komponen pilihan memerlukan konfigurasi dan kebergantungan masing-masing. Laluan sumber di bawah relatif kepada akar repositori. Blok Mermaid ialah sumber rajah yang boleh disunting dan dipaparkan dalam pemapar Markdown yang menyokong Mermaid.

1. Konteks sistem dan pemilikan​

flowchart LR
Developer["Developer / application"] --> Agent["Compatible agent or SDK"]
Operator["Platform operator"] --> UI["Dashboard / operator CLI"]

subgraph Customer["Customer-operated environment"]
Gateway["Yabanin gateway"]
Admin["Admin API"]
Stores[("PostgreSQL and Redis")]
Local["Optional local inference"]
Tools["Optional internal tool servers"]
Gateway --> Local
Gateway --> Stores
Admin --> Stores
Gateway -. "Configured MCP invocation" .-> Tools
end

Agent -->|"Model requests"| Gateway
UI --> Admin
Gateway -->|"Approved external route"| Cloud["External model provider"]
Gateway -. "Configured MCP invocation" .-> ExternalTools["External tool server"]
Agent --> Checks["Customer sandbox, tests and code review"]

Gerbang ialah perantara bagi trafik yang dihantar melalui endpoint yang dikonfigurasinya. Ia bukan masa jalan ejen, kotak pasir sistem pengendalian, atau pengganti bagi semakan kod. Panggilan rangkaian langsung ejen memintas sempadan ini melainkan pelaksanaan mengehadkannya secara berasingan. Gerbang kendalian sendiri dan inferens tempatan berbeza: laluan model luaran menghantar data permintaan ke luar persekitaran pelanggan.

2. Komponen masa jalan​

flowchart TB
Client["Agent / SDK"] --> GW["Gateway :8082"]
Dashboard["React dashboard / yb CLI"] --> Admin["Admin API :8086"]
Bridge["Optional MCP partner bridge"] --> GW
Bridge --> Admin

subgraph Data["Request processing"]
GW --> Resolve["Model resolver and routing"]
Resolve --> Adapter["Provider adapter / upstream client"]
GW --> Cache["Optional cache service"]
Resolve -. "Optional complexity classification" .-> Classifier["Classifier"]
Cache -. "Semantic lookup" .-> Embedder["Embedding endpoint"]
end

Adapter --> Inference["Local or external inference"]
Cache --> Redis[("Redis: exact cache and auth state")]
Cache --> PG[("PostgreSQL: configuration, logs, lineage, pgvector")]
Resolve --> PG
GW -->|"Async request events"| Stream[("Redis Stream: events:queue")]
Stream --> Logger["Loggerd :8085"]
Logger -->|"Request logs and accounting"| PG
GW -. "Optional async lineage writer" .-> PG
Admin --> PG
Admin --> Redis

Cache Redis dan Redis Stream ditunjukkan secara berasingan mengikut tanggungjawab; kedua-duanya boleh menggunakan pelaksanaan Redis yang sama. Gerbang juga membaca data identiti, bajet dan dasar; rajah mengelompokkan bacaan tersebut dengan konfigurasi dan bukannya melukis setiap pertanyaan.

KomponenTanggungjawabTitik masuk perlaksanaan
GerbangMiddleware HTTP, pengesahan, API sembang, penghalaan, penstriman, API seruan MCP pilihanservices/gateway/cmd/main.go, pkg/gateway/gateway.go
Saluran permintaanPengesahan data, cabang cache, pemilihan model, perlaksanaan huluan dan peristiwapkg/gateway/chat.go, pkg/gateway/stream.go
PentadbirPengurusan konfigurasi dan identiti, analitik, pengesahan salasilah, bahagian belakang papan pemukaservices/admin/handlers/router.go, pkg/adminstore
LoggerdKumpulan pengguna Redis, kegigihan log permintaan, perakaunan, pemulihan mesej tertunggak dan pengendalian surat matiservices/run/loggerd.go, services/loggerd/consumer/stream.go
Jambatan rakan MCPMendedahkan alat Yabanin kepada klien MCP; memanggil API gerbang/pentadbirservices/run/mcp.go, pkg/mcppartner
PostgreSQLKonfigurasi tahan lama dan rekod operasi; vektor cache semantik pilihanmigrations, pkg/migrate/migrations
RedisCache, cache penyelesaian identiti, strim peristiwa dan keadaan masa jalan lain yang dikonfigurasipkg/cache, pkg/auth, pkg/eventpublisher
Pengelas / pembenamPengelasan penghalaan pilihan dan pembenaman cache semantikpkg/classifier, pkg/embeddings, deploy/docker-compose.yml

Pendengar operasi berasingan gerbang (lalai :9090) bukan perkhidmatan satah kawalan pentadbir. Dalam tindanan Compose pembangunan, port kontena pentadbir :8086 diterbitkan sebagai port hos :9091. Jambatan MCP menyokong stdio dan pendengar HTTP-SSE pilihan pada :8787; ia tidak diperlukan untuk panggilan sembang biasa.

3. Laluan permintaan sembang​

API utama ialah POST /v1/chat/completions, dengan respons JSON dan SSE. Tertib di bawah mengikut chatCompletions; ciri yang dilumpuhkan atau tidak diwayar dilangkau. Cabang penolakan menamatkan permintaan sebelum peringkat seterusnya yang digambarkan.

flowchart TD
In["POST /v1/chat/completions"] --> HTTP["Body limit, timeout, rate limit, request ID"]
HTTP --> Auth["Authentication and resolved identity"]
Auth --> Admission["Optional credit guard and regional failover middleware"]
Admission --> Parse["Parse JSON and run configured input guards"]
Parse --> Access["Resolve requested model; check model access and budgets"]
Access --> Validate["Validate request; optional vertical transforms"]
Validate --> Cache{"Eligible cache hit?"}
Cache -->|"Yes"| Replay["Return cached JSON or replay as SSE"]
Cache -->|"No / bypass / lookup error"| Tier["Optional classifier and tier selection"]
Tier --> Rules["Organization routing-rule overrides"]
Rules --> Time["Optional time-window or batch downgrade"]
Time --> Residency["Configured residency enforcement / model remap"]
Residency --> Execute["Provider adapter, circuit breaker, retry and fallback"]
Execute --> Result["Return JSON or stream SSE"]
Result -. "Eligible successful response" .-> Write["Cache write"]
Replay -.-> Evidence["Request event and optional signed lineage"]
Result -.-> Evidence

Identiti dan kemasukan​

Pengesahan membuang pengepala identiti organisasi, kunci, pasukan dan ejen yang dibekalkan klien sebelum mengisinya daripada prinsipal yang diselesaikan. Tingkah laku kunci statik dan penyelesai pangkalan data bergantung pada mod pengesahan yang dikonfigurasi; kunci statik bukan pengganti bagi identiti organisasi/ejen. Lihat pkg/gateway/auth.go.

Apabila diwayar, semakan akses model dan bajet boleh menolak permintaan; ralat stor data dalam semakan ini tidak membenarkan perbelanjaan. Semakan bajet pasukan/ejen dan perakaunan yang kemudian ialah operasi berasingan, jadi rajah ini tidak membayangkan tempahan atomik bagi kos akhir setiap permintaan serentak.

Tertib cache dan penghalaan​

Carian cache mendahului penghalaan pengelas/peraturan dan blok penguatkuasaan residensi yang kemudian dalam pengendali semasa. Hit menyebabkan pulangan awal. Jangan tafsir rajah sebagai bukti bahawa setiap dasar selepas cache dinilai semula pada respons yang dicache. Skop cache, pembatalan dan perubahan dasar mesti dinilai bersama.

Cache-Control: no-store memintas cache gerbang bagi permintaan itu. Carian yang layak mencuba padanan tepat Redis, secara pilihan padanan tepat PostgreSQL, kemudian padanan semantik apabila didayakan oleh dasar organisasi. Padanan semantik menggunakan endpoint pembenaman dan pgvector. Ia bukan bukti bahawa jawapan yang diguna semula sesuai bagi setiap tugas. Butiran: seni bina cache.

Pada miss, pengelasan boleh memilih peringkat, peraturan organisasi boleh menindih pemilihan, dan penghalaan berasaskan masa yang dikonfigurasi boleh mengubahnya lagi sebelum penguatkuasaan residensi. Ini ialah keputusan yang berbeza. Kegagalan bacaan peraturan penghalaan pada masa ini merekod ralat dan meneruskan tanpa peraturan tersebut; ia bukan lapisan dasar gagal-tertutup yang universal. Model yang akhirnya menjawab juga boleh berbeza selepas sandaran.

Penstriman dan cubaan semula​

sequenceDiagram
participant C as Client
participant G as Gateway
participant A as Selected upstream
participant B as Configured fallback
C->>G: Chat request with stream=true
G->>G: Admission, cache miss, routing
G->>A: Open stream through provider adapter
alt Connection setup fails
G->>A: Retry when policy permits
opt Selected upstream remains unavailable
G->>B: Try configured fallback
B-->>G: Accepted stream
end
else Selected upstream accepts
A-->>G: Accepted stream
end
Note over G,B: Successful setup commits to one upstream stream
G-->>C: Translated SSE chunks from winning upstream
Note over C,G: A mid-stream failure cannot be transparently replayed
G->>G: Record outcome and observed usage

Jujukan ini menggambarkan persediaan yang berjaya melalui salah satu laluan. Jika semua percubaan persediaan gagal, gerbang memulangkan ralat. Cubaan semula/sandaran penstriman hanya terpakai pada persediaan sambungan: selepas menerima respons huluan, ia membaca strim itu hingga habis tanpa memulakannya semula secara senyap. Penstriman badan mentah khusus penyedia melumpuhkan sandaran merentas penyedia. Lihat pkg/gateway/stream.go dan integrasi penyedia.

4. Peristiwa, storan dan bukti​

flowchart LR
GW["Gateway request outcome"] --> Pub["Bounded async event publisher"]
Pub --> Stream[("Redis Stream")]
Stream --> Consumer["Loggerd consumer group"]
Consumer --> DB[("PostgreSQL request_logs and accounting")]
Consumer -->|"Successful processing"| Ack["Acknowledge stream entry"]
Consumer -->|"Processing failure"| Pending["Pending entry / reclaim"]
Pending --> Consumer
Pending -->|"Poison-message handling"| DLQ[("Dead-letter stream")]
GW -. "When lineage enabled" .-> Sign["Sign attestation with organization key"]
Sign --> Writer["Async lineage writer"]
Writer --> Ledger[("PostgreSQL request_lineage")]
UI["Dashboard / operator"] --> Admin["Admin analytics and verification API"]
Admin --> DB
Admin --> Ledger

Pengelogan permintaan dan salasilah mempunyai laluan kegigihan yang berbeza. Loggerd menggunakan peristiwa permintaan; penulis salasilah gerbang menambah perakuan secara berasingan. Respons klien tidak menunggu loggerd mengekalkan peristiwanya, dan analitik boleh ketinggalan berbanding penyiapan permintaan.

Penerbitan peristiwa terhad dan bersifat usaha terbaik: gerbang mencuba semula penerbitan, tetapi boleh menggugurkan peristiwa apabila tunggakannya penuh atau percubaan telah habis. Penciptaan salasilah juga usaha terbaik dan tidak menyekat permintaan apabila gagal. Tuntutan semula pengguna, penyahduplikatan dan pengendalian surat mati tidak menjadikan keseluruhan saluran suatu transaksi tepat-sekali yang tanpa kehilangan.

RekodMaksudSempadan tafsiran
model_requested, model_used, keputusan penghalaanLabel yang diminta, model yang melayan yang direkod dan konteks pemilihanNama model yang diminta sahaja tidak mencukupi untuk menetapkan harga atau membandingkan beban kerja yang dilaksanakan
Token, tempoh, pemasaan bait pertama dan percubaanPemerhatian yang tersedia pada laluan yang dilaksanakanMedan yang tiada atau strim yang terganggu bukan bukti kerja sifar atau jawapan yang lengkap
Anggaran kos dan kos kontrafaktualAnggaran harga berasaskan penggunaan dan alternatif yang dimodelkanKedua-duanya bukan invois penyedia atau penjimatan terjamin yang direalisasikan
Tandatangan salasilah dan bukti rantauIntegriti sesuatu perakuan dan sumber bukti yang dinyatakanTandatangan yang sah tidak secara bebas membuktikan lokasi inferens fizikal
Pengecam tugas / sesi / ejenAtribusi dan korelasiTag tugas tidak menunjukkan bahawa outputnya lulus ujian atau semakan

Prompt, sampel respons, entri cache, pembenaman, strim peristiwa dan sandaran ialah permukaan data yang berasingan. Jangan simpulkan bahawa mencincang satu prompt yang dilog membuang kandungan daripada kesemuanya. Periksa tetapan tangkapan, penghitaman, pengekalan dan endpoint bagi pelaksanaan sebenar. Lihat salasilah, tadbir urus ejen dan mod bayang.

Mod bayang ialah pilihan; ia menjalankan perbandingan tersampel terhadap model calon dan tidak menggantikan jawapan utama. Ia membuat panggilan inferens tambahan dan boleh menanggung kos tambahan; laluan calon ialah sebahagian daripada sempadan keluar data.

5. Dua laluan integrasi MCP​

flowchart LR
subgraph BridgePath["A. Clients invoke Yabanin tools"]
Client["MCP client"] -->|"stdio / HTTP-SSE"| Bridge["Partner bridge"]
Bridge -->|"Route prompt"| Chat["Gateway chat API"]
Bridge -->|"Spend, policy, lineage operations"| Admin["Admin API"]
end
subgraph InvokePath["B. Agents invoke registered external tools"]
Agent["Agent principal"] -->|"POST /api/mcp/invoke"| Invoke["Gateway invoke endpoint"]
Invoke --> Grants["Organization registry and agent grants"]
Grants --> Guards["Tool allow-list, input guards and SSRF checks"]
Guards --> Remote["Registered external MCP server"]
Guards -. "Audit event" .-> Events["Redis Stream / loggerd"]
end

Jambatan ialah proses integrasi yang berasingan. Endpoint seruan ialah sebahagian daripada gerbang dan dilekapkan hanya apabila proxy MCP dikonfigurasi (YABANIN_MCP_GATEWAY=1 dan persediaan bersandarkan pangkalan data). Ia memerlukan prinsipal ejen dan geran pelayan yang didayakan; kunci API biasa tidak mencukupi.

Laluan seruan luaran ialah laluan panggilan alat HTTP yang disokong, bukan dakwaan keserasian pengangkutan MCP yang universal. Ia tidak melancarkan pelayan stdio huluan. Pengepala identiti ejen yang dimajukan ialah atribusi, bukan kelayakan huluan. Pengawal input tidak mewujudkan penghitaman output. Butiran: gerbang MCP.

6. Pelaksanaan dan operasi​

flowchart TB
Users["Applications and operators"] --> Edge["Deployment-managed ingress / TLS"]
subgraph Boundary["Customer host, VPC or Kubernetes environment"]
Edge --> GW["Gateway replicas"]
Edge --> Admin["Admin API / dashboard"]
GW --> Redis[("Redis")]
Redis --> Logger["Loggerd workers"]
GW --> PG[("PostgreSQL / pgvector")]
Admin --> PG
Logger --> PG
Migration["Migration job"] --> PG
GW -. "Optional" .-> Local["Local model endpoints"]
GW -. "Optional" .-> Support["Classifier / embedder"]
GW -. "Metrics and traces" .-> Observe["Configured monitoring"]
end
GW -->|"Explicitly permitted egress"| Cloud["Approved cloud inference"]

Ini ialah corak pelaksanaan, bukan kiraan replika yang ditetapkan atau jaminan ketersediaan. Ingress, rahsia, sandaran, had sumber dan dasar rangkaian menjadi tanggungjawab pemasangan. Lindungi pendengar operasi secara berasingan daripada API klien.

PelaksanaanAset repositoriMaksud operasi
Pembangunan tempatandeploy/docker-compose.ymlPangkalan data, Redis, kerja migrasi, perkhidmatan dan profil inferens/pemantauan pilihan; pendedahan pembangunan bukan konfigurasi keselamatan pengeluaran
Kubernetesdeploy/helm/yabaninPelaksanaan perkhidmatan yang boleh dikonfigurasi; topologi serantau pilihan memerlukan konfigurasi tambahan
Di premis sendirideploy/helm/yabanin-onpremKomponen kendalian sendiri dengan pilihan infrastruktur tempatan; kesediaan jurang udara memerlukan pemeriksaan setiap kebergantungan dan laluan keluar
Berbilang rantaupkg/regionrouter, pkg/regionrepl, tests/integration/multiregionPengendalian rantau organisasi pilihan dan replikasi; berasingan daripada mencuba semula penyedia model dalam sesuatu permintaan

Middleware gerbang serantau boleh mengubah hala permintaan dengan HTTP 307 kepada rakan sebaya atau menolak organisasi yang disemat apabila rantaunya tidak tersedia. Klien mesti mengendalikan tingkah laku yang dipilih; ini bukan proxy merentas rantau yang tidak kelihatan. Lihat operasi berbilang rantau, pilihan pelaksanaan dan senarai semak jurang udara.

7. Peta sumber dan sempadan semakan​

SoalanKod untuk diperiksa
Kebergantungan dan ciri pilihan mana yang diwayar?pkg/gateway/gateway.go, pkg/config, deploy/docker-compose.yml
Dalam tertib apakah semakan sembang dan pilihan model dibuat?pkg/gateway/chat.go
Apa yang boleh dicuba semula selepas penstriman bermula?pkg/gateway/stream.go
Bagaimana identiti diterbitkan?pkg/gateway/auth.go, pkg/auth
Bagaimana skop cache dan dasar mempengaruhi hit?pkg/cache/service.go, pkg/cache/semantic.go
Apa yang berlaku apabila penerbitan atau kegigihan gagal?pkg/gateway/events.go, pkg/eventpublisher/redis_publisher.go, services/loggerd/consumer/stream.go
Di manakah salasilah ditandatangani dan disimpan?pkg/gateway/lineage.go, pkg/lineage
Permintaan MCP mana yang diterima?pkg/gateway/gateway.go, pkg/mcpagg/proxy.go, services/run/mcp.go
Di manakah pengendali menukar konfigurasi?services/admin/handlers/router.go, pkg/adminstore, web/dashboard

Perubahan konfigurasi mungkin diperhatikan melalui cache dengan jangka hayat yang berbeza; respons pentadbir bukan penghalang konfigurasi yang global dan serta-merta. Sahkan perambatan dan pembatalan bagi tetapan yang diubah.

Rajah-rajah ini mendokumentasikan tanggungjawab dan laluan kod semasa. Ia tidak memperakui keselamatan pelaksanaan, kualiti output model, daya tarikan pelanggan atau ketersediaan perkhidmatan. Langkah penggunaan pertama kekal satu aliran kerja yang disokong dengan semakan penerimaan yang jelas dan hasil operasi yang boleh diperhatikan.