Plan v0.2'nin Faz 0 çıktısı. Yazılan sıraya göre:
- cobra tabanlı CLI iskeleti; server/agent/ctl komutları henüz stub.
- internal/sim: OpenAI uyumlu sahte inference engine. Router'ı GPU olmadan
gerçekçi koşullarda test edebilmek için gerçek bir engine'in router
açısından önemli davranışlarını modeller:
* continuous batching ve KV blok muhasebesi (head-of-line blocking dahil)
* zincirlenmiş blok hash'leri + LRU ile otomatik prefix cache
* batch büyüdükçe artan token gecikmesi
* istemci koptuğunda isteğin düşürülüp blokların bırakılması
* vLLM metrik adlarıyla /metrics (plan §7.6 engine kontratı)
- Testler: prefix hash zincirlemesi, LRU tahliyesi, iptal propagasyonu,
kuyruklama, SSE formatı, usage/cached_tokens, metriklerin gerçek
Prometheus parser'ıyla okunabilirliği.
- Gitea Actions CI: gofmt, vet, race detector.
Modül yolu gitea.mynodes.xyz/ilker/llmgw; `make rename` ile değiştirilebilir.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
53 KiB
llmgw — Çoklu IB Fabric ve Heterojen GPU için Tek Binary LLM Gateway
Durum: Tasarım / Plan v0.2 v0.2 değişikliği: mevcut LLM gateway/router projeleri incelendi (§2.5) ve kritik tasarımları plana alındı — en önemlisi admission ile scheduling'in ayrılması (§7.2), eklenti tabanlı filter → score → pick çerçevesi (§7.3) ve prefix/KV cache farkındalığının üç kademeli modeli (§7.5). Hedef: Tek bir Go binary'si ile (farklı roller altında) kendi GPU sunucularımızda çalışan LLM'leri tek bir OpenAI uyumlu uç noktadan sunmak. Arkada birden fazla bağımsız InfiniBand fabric, IB'siz node'lar ve farklı GPU tipleri var.
1. Kapsam
1.1 Yapılacaklar
- OpenAI uyumlu API (
/v1/chat/completions,/v1/completions,/v1/embeddings,/v1/models), SSE streaming dahil. - Her GPU node'unda çalışan bir agent: GPU ve IB keşfi, inference engine süreçlerini (vLLM / SGLang) başlatma, izleme, durdurma.
- Control plane: node envanteri, model kataloğu, replika yerleşimi (placement), durum takibi.
- Router: iki katmanlı — admission (öncelik bantları, tenant adaleti, doygunluk kuyruklaması) ve scheduling (eklenti tabanlı filter/score/pick; kuyruk/KV-cache/prefix farkındalığı), üstüne fallback, retry, cooldown, circuit breaker.
- Fabric farkındalığı: multi-node replika asla iki fabric'e yayılmaz; TP grubu asla farklı GPU tiplerini karıştırmaz.
- API key, rate limit, kullanım (token) muhasebesi, Prometheus metrikleri.
1.2 Yapılmayacaklar (en azından v1'de)
- Inference'ın kendisi. Go sadece orkestrasyon ve proxy yapar; modeli vLLM/SGLang çalıştırır.
- Kubernetes operatörü (bare metal / systemd hedefleniyor; K8s sonra düşünülebilir).
- Prefill/decode ayrıştırması (v2 hedefi, bkz. §12).
- Dış provider'lar (OpenAI, Anthropic) — mimari buna açık bırakılacak ama v1'de yok.
2. Terimler
| Terim | Anlamı |
|---|---|
| Node | Agent'ın çalıştığı fiziksel sunucu. |
| Fabric / Ada (Island) | Bağımsız bir IB fabric'i. IB'siz node'lar none adasındadır ve her biri kendi başına tek-node adası sayılır. |
| GPU Class | Aynı model + aynı VRAM'e sahip GPU grubu (ör. h100-80g, a100-40g, l40s-48g). |
| Pool | (fabric, gpu class) ikilisi. Yerleşim birimi. |
| Model | Katalogdaki mantıksal model (ör. llama-3.3-70b). Kullanıcı bu adı görür. |
| Profile | Bir modelin belirli bir GPU class üzerinde nasıl çalışacağı (TP, PP, quant, max-len, engine argümanları). |
| Replica | Bir modelin çalışan tek bir kopyası. 1..N node'a yayılabilir. Router'ın gördüğü birim budur. |
| Shard | Bir replikanın tek bir node'daki parçası (engine süreci). |
| Yönlendirme Profili | Router'ın bir istek sınıfı için kullandığı scorer seti + ağırlıkları (chat / batch / long-context). §2'deki model Profile'ı ile karıştırma. |
| Band | Öncelik sınıfı (platinum/gold/silver/bronze). Admission kararının birimi. |
| Block | KV cache'in muhasebe birimi; sabit token sayısı (vLLM'de 16, GIE indexer'ında varsayılan 64). |
2.5 Referans Uygulamalar ve Ne Aldık
Sıfırdan tasarlamak yerine bu alanda olgunlaşmış projelerin çözdüğü problemleri devraldık.
| Proje | Konumu | llmgw'ye aldığımız |
|---|---|---|
| Gateway API Inference Extension (EPP) | K8s standardı; Envoy ext_proc üzerinden çalışan Endpoint Picker |
Admission/scheduling ayrımı, eklenti tabanlı filter → score → pick çerçevesi, model server metrik kontratı (§7.6) |
| llm-d | GIE üzerinde "well-lit path"ler | KV event tabanlı kesin prefix index, öncelik bantları + tenant adaleti, doygunluk dedektörü |
| AIBrix (vLLM projesi) | Envoy ext_proc gateway + heterojen GPU optimizer | Heterojen GPU SLO/maliyet modeli (§6.2.1), gateway'de kuyruklama (slo-least-load-pulling), yük dengesizliğinde prefix affinity'yi iptal etme |
| NVIDIA Dynamo | Radix-tree KV router + SLA planner | Maliyet fonksiyonunun formu (§7.4), router_temperature ile sürü etkisine karşı softmax örnekleme |
| SGLang router | Yaklaşık radix tree ile cache-aware LB | v1'in prefix çözümü: yaklaşık ağaç + eşik mantığı (§7.5 Kademe 1) |
| vLLM production-stack / vllm-project/router | vLLM'in kendi router'ları | Session affinity (ölçümlerde %96 vs %93 cache hit), consistent hashing |
| LiteLLM | En yaygın çok-provider proxy'si | Virtual key → takım/proje → bütçe hiyerarşisi, cooldown, spend yazımının istek yolundan çıkarılması, bütçe aşımında fallback |
| Envoy AI Gateway | Envoy tabanlı AI gateway (v1.0, Haziran 2026) | Token bazlı (sadece istek bazlı değil) rate limit |
Bilerek almadıklarımız: Kubernetes bağımlılığı (bare metal hedefi), Envoy ext_proc mimarisi
(tek binary hedefi — router'ı doğrudan Go'da yazıyoruz), semantic router / LLM tabanlı model seçimi
(kapsam dışı), dış provider yönetimi (v1'de yok).
3. Mimari
┌───────────────────────────────────────────┐
İstemciler ─────► │ llmgw server │
(OpenAI API) │ ┌────────────┐ ┌──────────────────────┐ │
│ │ Router │ │ Control Plane │ │
│ │ (data) │◄─┤ - Inventory │ │
│ │ │ │ - Catalog │ │
│ └─────┬──────┘ │ - Scheduler │ │
│ │ │ - Store (SQLite) │ │
│ │ └─────────▲────────────┘ │
└────────┼───────────────────┼──────────────┘
HTTP (eth) │ │ gRPC stream (mTLS, agent başlatır)
┌────────────────────┼───────────────────┼─────────────────────┐
▼ ▼ │ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐
│ llmgw │ IB-A │ llmgw │ │ llmgw │ IB-B │ llmgw │
│ agent │◄──────►│ agent │ │ agent │◄───────►│ agent │ ...
│ vLLM rank0│ NCCL │ vLLM rank1│ │ SGLang │ │ (IB yok) │
└───────────┘ └───────────┘ └───────────┘ └───────────┘
Fabric A adası Fabric B adası none adası
3.1 Tek binary, çok rol
llmgw server --config server.yaml # router + control plane (v1: aynı süreç)
llmgw agent --config agent.yaml # her GPU node'unda
llmgw ctl ... # CLI: node listele, model deploy, drain vs.
llmgw sim-engine # test için sahte OpenAI uyumlu engine
router ve control ileride ayrı süreçler olarak da çalışabilmeli (llmgw server --roles=router), bu yüzden aralarındaki bağımlılık bir interface üzerinden olmalı (bkz. §6.4).
3.2 Build notu
go-nvml cgo gerektirir. Agent'taki NVML kodunu //go:build nvml tag'i arkasına koy; tag'siz build'de sahte/nvidia-smi tabanlı keşif kullanılsın. Böylece server tarafı cgo'suz derlenebilir ve geliştirme makinesinde GPU olmadan test yapılabilir.
4. Proje Yapısı
llmgw/
├── cmd/llmgw/main.go # cobra root; alt komutlar
├── api/
│ └── proto/llmgw/v1/*.proto # agent <-> control plane
├── internal/
│ ├── config/ # koanf ile YAML + env
│ ├── agent/
│ │ ├── agent.go # ana döngü, control plane bağlantısı
│ │ ├── discovery/
│ │ │ ├── gpu_nvml.go # //go:build nvml
│ │ │ ├── gpu_fallback.go
│ │ │ ├── ib.go # /sys/class/infiniband okuma
│ │ │ └── topology.go # NVLink, PCIe, NUMA, GPU<->HCA yakınlığı
│ │ ├── supervisor/ # engine süreç yönetimi (exec, restart, log)
│ │ ├── engines/
│ │ │ ├── engine.go # Engine interface
│ │ │ ├── vllm.go
│ │ │ └── sglang.go
│ │ └── health/ # engine /health ve /metrics yoklama
│ ├── control/
│ │ ├── inventory/ # node & GPU durumu
│ │ ├── catalog/ # model + profile tanımları
│ │ ├── scheduler/ # placement algoritması
│ │ ├── reconciler/ # desired vs actual döngüsü
│ │ └── agentsvc/ # gRPC server
│ ├── router/
│ │ ├── openai/ # HTTP handler'lar, request parse
│ │ ├── proxy/ # upstream'e stream proxy
│ │ ├── admission/ # doygunluk dedektörü, bant kuyrukları (§7.2)
│ │ ├── scheduler/ # Filter/Scorer/Picker çerçevesi (§7.3)
│ │ │ ├── filters/
│ │ │ ├── scorers/ # queue, kv, prefix, load, inflight, session
│ │ │ └── pickers/ # max-score, p2c, softmax
│ │ ├── prefix/ # Kademe 0 session hash, Kademe 1 approx tree, Kademe 2 kv index
│ │ ├── breaker/ # circuit breaker + cooldown
│ │ └── metricsscrape/ # engine /metrics okuma (§7.6 kontratı)
│ ├── auth/ # API key, org/takım/proje, bütçe
│ ├── ratelimit/ # token bucket (istek + token)
│ ├── usage/ # token sayımı, kayıt
│ ├── store/ # SQLite (modernc.org/sqlite), migration
│ ├── obs/ # slog, prometheus, otel
│ └── sim/ # sahte engine
├── deploy/
│ ├── systemd/
│ └── examples/
├── test/e2e/
└── docs/
4.1 Kütüphaneler
| İhtiyaç | Seçim |
|---|---|
| CLI | github.com/spf13/cobra |
| Config | github.com/knadh/koanf/v2 |
| RPC | connectrpc.com/connect (gRPC uyumlu, HTTP/2, debug kolay) |
| GPU | github.com/NVIDIA/go-nvml |
| DB | modernc.org/sqlite (cgo'suz) + pressly/goose migration |
| Metrik | github.com/prometheus/client_golang, parse için github.com/prometheus/common/expfmt |
| Tracing | go.opentelemetry.io/otel |
| Log | log/slog (stdlib) |
| Rate limit | golang.org/x/time/rate (+ token bazlı için kendi bucket'ımız) |
| Hash | github.com/cespare/xxhash/v2 |
| HA (v2) | github.com/hashicorp/raft veya etcd |
| Test | stdlib testing, github.com/stretchr/testify (opsiyonel) |
5. Agent
5.1 GPU keşfi
Her GPU için:
- index, UUID, isim, VRAM, compute capability (FP8 vb. desteği için), sürücü/CUDA sürümü
- NUMA node, PCIe bus id
- NVLink eşleri (NVML
GetNvLinkRemotePciInfo) → aynı node içinde TP için hangi GPU'lar birlikte verimli - sağlık: XID hataları, ECC, sıcaklık, kullanımdaki bellek (engine dışı süreçler var mı?)
GPUClass otomatik türetilir: normalize(name) + "-" + round(vram_gb) + "g" → h100-80g. Config ile override edilebilir.
5.2 IB keşfi ve fabric kimliği
/sys/class/infiniband/<hca>/ports/<n>/ altından:
state(ACTIVE?),phys_state,rate,link_layer(InfiniBand / Ethernet → RoCE)gids/0→ subnet prefixsm_lid,lid- HCA'nın PCIe adresi ve NUMA'sı → GPU yakınlığı
Fabric kimliği nasıl belirlenir? Otomatik tespit güvenilir değildir çünkü OpenSM varsayılan subnet prefix'i (fe80::) tüm fabric'lerde aynıdır. Öncelik sırası:
- Agent config'inde açık etiket:
fabrics: [{name: ib-a, hcas: [mlx5_0, mlx5_1]}](önerilen) - Her OpenSM'de benzersiz
subnet_prefixayarlanmışsa GID prefix'inden otomatik eşleme (server config'indeprefix → fabrictablosu) - Hiçbiri yoksa: node
fabric=unknownolarak işaretlenir ve multi-node yerleşime alınmaz.
Bonus doğrulama (v1.1): aynı fabric'te olduğunu iddia eden iki node arasında agent'lar ibv_rc_pingpong benzeri kısa bir test veya ibping ile erişilebilirliği doğrular. Tutarsızlık alarm üretir.
Bir node'da birden fazla fabric'e bağlı HCA olabilir; model buna izin vermeli (Node.Fabrics []FabricAttachment). Ancak bir replika tek bir fabric seçer ve sadece o fabric'in HCA'larını kullanır.
5.3 Engine interface
type Engine interface {
Name() string // "vllm", "sglang"
Validate(p Profile, gpus []GPU) error // compute capability, quant uyumu vs.
BuildCommand(spec ShardSpec) (*exec.Cmd, error) // argüman + env üretimi
HealthURL(spec ShardSpec) string
MetricsURL(spec ShardSpec) string
ParseMetrics(r io.Reader) (EngineStats, error) // engine'e özgü metrik adları
}
type ShardSpec struct {
ReplicaID string
Rank int // 0 = leader (HTTP'yi sunan)
NNodes int
LeaderAddr string // dist init adresi (ethernet IP)
LeaderPort int
GPUIndices []int
HCAs []string // seçilen fabric'in HCA'ları
HTTPPort int
Profile Profile
ModelPath string
}
type EngineStats struct {
// §7.6'daki zorunlu kontrat — bunlar olmadan router yönlendiremez
Running, Waiting int
KVCacheUsage float64 // 0..1 (vllm:kv_cache_usage_perc)
// opsiyonel
BlockSize, NumGPUBlocks int
PrefixHitRate float64
TTFTp50, TPOTp50 time.Duration // histogramdan
DrainRate float64 // gözlenen tamamlanma/sn; `load` scorer'ı için
LoRA LoRAState // v2
ScrapedAt time.Time // stale tespiti için — router bunu kullanır
}
Yeni bir engine eklemenin tanımı = §7.6'daki zorunlu üçlüyü doldurabilmek.
Multi-node başlatma:
- SGLang:
--nnodes N --node-rank R --dist-init-addr host:port --tp Tdoğal olarak destekler. - vLLM: kullanılan sürüme göre ya Ray (leader'da
ray start --head, worker'lardaray start --address) ya da yeni sürümlerdeki çok-node multiprocessing bayrakları. Kullanacağın vLLM sürümünün dokümanını kontrol et;vllm.goiçinde iki yol dalaunchModeile seçilebilir olsun.
Env üretimi (kritik):
CUDA_VISIBLE_DEVICES=<GPUIndices>
NCCL_IB_HCA=<HCAs, virgülle> # sadece seçilen fabric
NCCL_SOCKET_IFNAME=<mgmt arayüzü> # bootstrap
NCCL_IB_DISABLE=1 # tek-node veya IB'siz ise
NCCL_CROSS_NIC / NCCL_NET_GDR_LEVEL # profile'dan opsiyonel
GLOO_SOCKET_IFNAME=<mgmt arayüzü>
5.4 Supervisor
- Süreçleri kendi process group'unda başlat (
SysProcAttr.Setpgid), durdururken tüm grubu öldür (SIGTERM → timeout → SIGKILL). - stdout/stderr → satır bazlı slog'a + halka tampon (son N satır,
llmgw ctl logsiçin). - Durum makinesi:
Pending → Starting → Loading → Ready → Draining → Stopped | Failed. Readyancak/health200 ve/v1/modelsmodeli listeliyorsa.- Model yükleme uzun sürer;
startupTimeoutprofile'dan gelir (ör. 20 dk). - Çökme: control plane'e raporla, yeniden başlatma kararını control plane verir (multi-node replikada tek shard'ı yeniden başlatmak işe yaramaz; tüm replika yeniden kurulmalı).
- Agent yeniden başlarsa: çalışan engine süreçlerini (pid dosyası + cmdline kontrolü) sahiplenmeyi dene, yoksa temizle.
5.5 Model ağırlıkları
- v1: paylaşımlı dosya sistemi (NFS/Lustre/Weka) veya node'da önceden indirilmiş yol. Agent sadece varlığını ve boyutunu kontrol eder.
- v1.1: agent'ın HF/S3'ten yerel cache'e indirmesi, ilerleme raporlaması, disk kotası.
5.6 Agent ↔ Control plane protokolü
Agent bağlantıyı başlatır (NAT/firewall dostu), çift yönlü stream:
service AgentService {
rpc Connect(stream AgentMessage) returns (stream ControlMessage);
}
message AgentMessage {
oneof msg {
Register register = 1; // node bilgisi, GPU'lar, fabric'ler, sürümler
Heartbeat heartbeat = 2; // her 5 sn: GPU sağlığı, shard durumları
ShardStatus shard = 3; // durum değişimi anında
EngineStats stats = 4; // her 2 sn (router da doğrudan scrape edebilir)
}
}
message ControlMessage {
oneof msg {
StartShard start = 1;
StopShard stop = 2;
DrainShard drain = 3;
Ack ack = 4;
}
}
- Komutlar idempotent:
StartShardaynıshard_idile tekrar gelirse no-op. - mTLS: node kimliği sertifika CN'sinden. v1'de basit bir iç CA;
llmgw ctl cert issue. - Heartbeat 3 kez kaçarsa node
Unreachable, 60 sn sonraLost→ üzerindeki replikalar yeniden planlanır.
6. Control Plane
6.1 Veri modeli (özet)
type Node struct {
ID, Hostname, MgmtAddr string
Labels map[string]string
GPUs []GPU
Fabrics []FabricAttachment // boşsa IB'siz
State NodeState // Ready, Cordoned, Draining, Unreachable, Lost
LastSeen time.Time
}
type FabricAttachment struct {
Fabric string // "ib-a"
HCAs []string
Rate int // Gbps
}
type Model struct {
Name string // kullanıcıya görünen
Aliases []string
Source string // yol veya HF id
Profiles []Profile
Scaling Scaling // min/max replika, hedef kuyruk vs.
Fallbacks []string // başka model adları
}
type Profile struct {
Name string
GPUClass string // "h100-80g"
Engine string // "vllm"
TP, PP int
GPUsPerNode int // genelde TP
Nodes int // PP*... ; >1 ise fabric zorunlu
Args []string // --quantization fp8 --max-model-len 32768 ...
Env map[string]string
Weight int // router için kapasite ağırlığı (benchmark'tan)
Priority int // yerleşim tercihi
StartupTimeout time.Duration
}
type Replica struct {
ID, Model, Profile string
Fabric string // multi-node ise dolu
Shards []Shard
State ReplicaState
Endpoint string // rank0 HTTP adresi
}
6.2 Scheduler (placement)
Girdi: istenen replika sayısı, profile listesi, envanter. Kısıtlar (hard):
- Tüm shard'lar aynı
GPUClass. Nodes > 1ise tüm node'lar aynıFabric'e bağlı olmalı ve o fabric'te ACTIVE HCA'ları olmalı.GPUsPerNodekadar boş GPU; tercihen aynı NVLink domain'inde ve HCA ile aynı NUMA'da.- Node
ReadyveCordoneddeğil. - Engine
Validategeçmeli (ör. FP8 profile'ı compute capability < 8.9 olan karta konmaz).
Tercihler (soft, skor):
- Profile
Priority - Bin-packing: kısmen dolu node'ları önce doldur (büyük modeller için boş node'ları koru)
- Aynı modelin replikalarını farklı fabric/node'lara yay (hata alanı dağıtımı)
- GPU-HCA NUMA yakınlığı
Algoritma (v1, basit ve deterministik):
for each profile in model.Profiles sorted by Priority desc:
pools := groupNodes(by GPUClass == profile.GPUClass, by Fabric if profile.Nodes > 1)
for each pool sorted by score:
nodes := pickNodes(pool, profile.Nodes, profile.GPUsPerNode) // greedy + NVLink grubu seçimi
if nodes != nil:
return Placement{profile, pool.Fabric, nodes, gpuAssignments}
return ErrUnschedulable (sebepleriyle birlikte — debug için çok önemli)
groupNodes: IB'siz node'lar Nodes == 1 profile'ları için havuza girer; Nodes > 1 için asla.
ctl komutu: llmgw ctl explain-placement <model> her havuzun neden elendiğini göstermeli.
6.2.1 Heterojen GPU: SLO/kapasite modeli
Farklı GPU sınıflarını "ağırlık" gibi tek bir skalerle karşılaştırmak yetersiz — AIBrix'in
heterojen GPU optimizer'ından alınan model daha doğru. Her (model, profile) çifti için
ctl bench (§10) bir kapasite profili üretir:
type CapacityProfile struct {
Model, Profile string
GPUClass string
// SLO'yu karşılayan maksimum eşzamanlılık; asıl kapasite ölçüsü
MaxConcurrencyAtSLO int
ThroughputTokPerSec float64
TTFTp99, TPOTp99 time.Duration
RelativeCost float64 // GPU-saat cinsinden göreli maliyet (config'ten)
MeasuredAt time.Time
EngineVersion string // sürüm değişince profil geçersiz
}
SLO örneği: TPOT p99 ≤ 50ms && TTFT p99 ≤ 2s.
Bu profil üç yerde kullanılır:
- Router ağırlığı:
Profile.Weightartık elle yazılmaz,MaxConcurrencyAtSLO'dan türetilir. - Admission eşikleri:
TargetWaitingPerReplica(§7.2.1) ölçülen değerden önerilir. - Yerleşim/autoscaling hedefi: "SLO'yu karşılayarak toplam maliyeti minimize et". Tahmini
yük için gereken replika sayısı GPU sınıfı başına
ceil(load / MaxConcurrencyAtSLO)ile hesaplanır; maliyeti en düşük kombinasyon seçilir. v1'de bu sadecectlile öneri üretir (ctl plan <model> --target-rps N), otomatik uygulama v1.1 autoscaler'ında.
EngineVersion veya profile argümanları değiştiğinde ölçüm bayatlar: llmgw bunu uyarı olarak
yüzeye çıkarmalı (llmgw_capacity_profile_stale{model,profile}), sessizce eski sayıyı kullanmamalı.
6.3 Reconciler
- Her 5 sn veya olay geldiğinde: desired (model scaling) ile actual (replica durumları) karşılaştır.
- Eksik replika → schedule → shard'lar için
StartShardgönder (önce worker'lar, sonra rank0 veya engine'in istediği sıra). - Replika içindeki herhangi bir shard
Failed→ tüm replikayı durdur, backoff ile yeniden planla. - Fazla replika → önce
Drain(router yeni istek göndermez, mevcutlar biter), sonraStop. - Node
Lost→ replikalarınıFailedsay.
Autoscaling (v1.1): model başına targetWaitingPerReplica; router metriklerinden ortalama hesaplanır, cooldown'lı ölçekleme. Boşta GPU yoksa düşük öncelikli modelleri küçültme (preemption) v2.
6.4 Router ile arayüz
type EndpointSource interface {
// model adı -> Ready replikalar (+ pool, weight, fabric, gpuclass, capacity profile)
Endpoints(model string) []Endpoint
Subscribe() <-chan struct{} // değişiklik bildirimi
}
v1'de bellek içi; router ve control ayrılırsa aynı interface bir watch stream'i ile gerçeklenir.
Router bu listeyi her zaman önbellekte tutar: control plane düşse bile mevcut replikalara
yönlendirmeye devam eder (§14'teki SPOF riskinin azaltılması). Önbellek yaşlandığında
(endpoint_cache_max_age, ör. 5 dk) sadece uyarı metriği üretir, trafiği kesmez.
6.5 Store
- SQLite, WAL modu. Tablolar:
nodes,models,profiles,replicas,shards,api_keys,usage_rollup,events. - Envanter ve replika durumu aslında agent'lardan yeniden kurulabilir; kalıcı olması gereken asıl şey katalog, anahtarlar ve kullanım.
- HA (v2): Raft ile replike edilmiş durum veya dış Postgres/etcd.
7. Router
7.1 İstek yaşam döngüsü
İstek
├─ 1. Auth : key → proje/takım, izinli modeller, öncelik bandı, yönlendirme profili
├─ 2. Kota : RPM/TPM + bütçe (bellek içi sayaç; DB istek yolunda değil)
├─ 3. Parse : model, stream, messages/prompt, max_tokens, user.
│ Gövdenin kalanı JSON olarak dokunulmadan iletilir.
├─ 4. Çözümleme : model/alias → aday havuzlar (fabric × gpu_class)
├─ 5. ADMISSION : "şimdi mi?" §7.2 ← havuz doygunsa istek burada bekler
├─ 6. SCHEDULING : "nereye?" §7.3 filter → score → pick
├─ 7. Proxy : upstream'e stream, iptal propagasyonu §7.8
└─ 8. İstek sonrası (asenkron): usage, spend, metrik, log
Kritik ayrım (GIE / llm-d'den alındı). Ne zaman ilerleyeceği ile nereye gideceği iki ayrı karardır ve ayrı tutulmalıdır. Ayrı tutulduğunda router istekleri kendi merkezî kuyruğunda tutup öncelik ve tenant adaletini istek engine kuyruğuna girmeden önce uygulayabilir.
Neden önemli: engine'in kendi kuyruğu FIFO'dur ve tenant/öncelik kavramı yoktur. İstek oraya bir kez girdikten sonra hiçbir önceliklendirme yapılamaz. Bir batch işi 500 istekle vLLM kuyruğunu doldurduğunda, arkadan gelen interaktif sohbet isteğinin TTFT'si çöker ve router'ın yapabileceği hiçbir şey kalmaz. v0.1'de bu katman yoktu; paylaşımlı bir küme için en kritik eksikti.
7.2 Admission control (Flow Control)
7.2.1 Doygunluk dedektörü
Havuz başına tek bir doygunluk sinyali üretilir; iki metriği birleştirir (llm-d'nin yaklaşımı — tek başına kuyruk derinliği yetmez, KV baskısı da gerçek bir tükenme sinyalidir):
// replika başına, sonra havuz için p90 veya ortalama
func saturation(e EngineStats, t Thresholds) float64 {
q := float64(e.Waiting) / t.TargetWaitingPerReplica // ör. hedef 4
kv := e.KVCacheUsage / t.KVCeiling // ör. tavan 0.90
return math.Max(q, kv)
}
Hedef, engine'de küçük ama sağlıklı bir tampon tutmaktır: continuous batching'in verimli
çalışmasına yetecek kadar istek olsun, ama kuyruk şişmesin. TargetWaitingPerReplica çok
düşük olursa GPU aç kalır, çok yüksek olursa kuyruk gecikmesi geri gelir. Bu iki eşik
model/profile başına ayarlanabilir olmalı ve ctl bench (§10) bunları önermeli.
7.2.2 Öncelik bantları
Her API key bir banda eşlenir. Bant, doygunluk tavanını belirler:
bands:
- { name: platinum, priority: 400, saturation_ceiling: 1.00 } # hiç bekletme
- { name: gold, priority: 300, saturation_ceiling: 0.85 }
- { name: silver, priority: 200, saturation_ceiling: 0.60 }
- { name: bronze, priority: 100, saturation_ceiling: 0.30 } # batch işleri
Dispatch döngüsü bantları yüksekten düşüğe tarar. Havuzun doygunluğu bandın tavanını aştıysa o bandın istekleri kuyrukta bekler. Sonuç: küme dolarken önce batch trafiği yavaşlar, interaktif trafik korunur. (llm-d ölçümlerinde platinum/gold/silver 1 sn altında kalırken bronze batch belirgin şekilde geriye düşüyor — istenen davranış tam olarak bu.)
7.2.3 Adalet ve kuyruk yönetimi
- Bant içi adalet: aynı bantta birden fazla tenant varsa dispatch turları round-robin dağıtılır. Tek bir tenant'ın ani yük artışı bandın tüm kapasitesini yutamaz.
- Kapasite: bant başına kuyruk boyu sınırlı. Dolduğunda yeni istek anında
503(kuyrukta sessizce birikmesindense hızlı reddedilsin). - TTL: kuyrukta
queue_ttlsüresini aşan istek düşürülür (504). İstemcinin zaten vazgeçtiği bir isteği GPU'ya göndermenin anlamı yok. - İstemci kopması: kuyruktayken bağlantı koparsa istek sessizce düşer (context iptali).
- Displacement (v1.1): yüksek banda yer açmak için en düşük banttaki en yeni istekler düşürülür (en eskiler zaten TTL'e yakın ve beklemeye en çok yatırım yapmış olanlar).
type Admission interface {
// İstek ilerleyebilene kadar bloke olur; ctx iptal/TTL'de hata döner.
Acquire(ctx context.Context, req *RequestInfo) (Lease, error)
}
Lease.Release() yanıt tamamlandığında çağrılır; router'ın in-flight sayacını da bu tutar.
7.3 Scheduler: filter → score → pick
v0.1'deki "strateji" listesi yerine eklenti çerçevesi (GIE EPP modeli). Her strateji ayrı bir monolit olmaz; scorer'lar ağırlıklandırılarak birleştirilir.
type Filter interface { // adayı eler (hard constraint)
Name() string
Filter(ctx *SchedCtx, eps []Endpoint) []Endpoint
}
type Scorer interface { // 0..1 arası skor; 1 = en iyi
Name() string
Score(ctx *SchedCtx, eps []Endpoint) map[EndpointID]float64
}
type Picker interface { // skorlardan seçim
Pick(ctx *SchedCtx, scores map[EndpointID]float64) Endpoint
}
type RoutingProfile struct {
Name string
Filters []Filter
Scorers []WeightedScorer // {Scorer, Weight}
Picker Picker
}
Toplam skor: score(ep) = Σ wᵢ · scoreᵢ(ep) (her scorer kendi içinde 0..1'e normalize eder).
İki aşamalı karar. Heterojen topoloji yüzünden önce havuz, sonra replika seçilir:
- Havuz seçimi:
Priorityen yüksek havuz; oradaki tüm replikalar doygunsa (§7.2.1) bir sonraki havuza taşma (spillover). Böylece H100 havuzu dolmadan A100 havuzuna düşülmez. - Replika seçimi: seçilen havuz içinde filter/score/pick.
Yönlendirme profilleri (config'ten, model başına varsayılan + x-llmgw-profile header'ı ile
istek başına override):
| Profil | Ağırlıklar | Kullanım |
|---|---|---|
chat |
prefix 3.0, queue 1.0, kv 1.0 | Çok turlu sohbet, agent — cache tekrarı yüksek |
batch |
queue 3.0, kv 1.0, prefix 0.5 | Toplu iş — throughput önemli, TTFT değil |
long-context |
kv 3.0, prefix 2.0, queue 1.0 | Uzun prompt — KV baskısı asıl darboğaz |
debug |
round-robin picker | Hata ayıklama |
7.4 Scorer'lar ve formülleri
| Scorer | Formül | Not |
|---|---|---|
queue |
1 − min(1, waiting / target_waiting) |
Kuyruk derinliği |
kv |
1 − kv_cache_usage |
KV doluluğu; tavan üstü sert ceza |
prefix |
matched_blocks / prompt_blocks |
§7.5 |
load |
1 − norm(running / drain_rate) |
AIBrix: drain_rate = gözlenen tamamlanma hızı. Yavaş bir replikayı running tek başına yakalayamaz. |
inflight |
1 − norm(router_inflight) |
Router'ın kendi saydığı; scrape gecikmesini telafi eder. Scrape aralığı 2 sn iken bu olmadan sürü etkisi kaçınılmaz. |
pool-priority |
profile Priority'den sabit |
Havuz tercihi |
session |
session hash eşleşmesi | §7.5 Kademe 0 |
lora (v2) |
adapter yüklü mü | vllm:lora_requests_info |
Alternatif maliyet formu (Dynamo). Prefill ve decode maliyetini doğrudan blok cinsinden modellemek, normalize skorlardan daha isabetli olabilir:
cost(ep) = w_overlap · (prompt_blocks − cached_blocks(ep)) + decode_blocks(ep)
seçim = argmin cost
w_overlap yüksek → cache tekrarını kollar (TTFT iyileşir); düşük → yükü eşitler (ITL iyileşir).
Her ikisi de Scorer olarak ifade edilebildiği için çerçeve bozulmaz; v1'de ağırlıklı skor,
v1.1'de bu maliyet formu bir scorer olarak eklenir ve ctl bench ile karşılaştırılır.
Picker'lar:
max-score: en yüksek skor. Deterministik ama sürü etkisine açık.p2c(power-of-two-choices): rastgele iki aday, iyisi. Çok replikada varsayılan.softmax(temperature): Dynamo'nunrouter_temperature'ı. Skorları logit sayıp örnekler.temperature=0→ argmax. Küçük bir sıcaklık, eşit skorlu replikalarda senkronize kararların yarattığı salınımı kırar.
7.5 Prefix / KV cache farkındalığı — üç kademe
Bu, router'ın sağlayabileceği en büyük tek kazanç; ama kademeler arasındaki maliyet farkı çok büyük. Kademeleri ayrı tutuyoruz ki model başına açılıp kapatılabilsin.
Kademe 0 — Session affinity (v1, ucuz, yüksek getiri)
İstemcinin verdiği x-session-id header'ı (yoksa OpenAI user alanı) bounded-load consistent
hashing ile bir replikaya eşlenir. Replika aşırı yüklüyse (ortalamanın load_factor katı) sıradakine
geçilir. Kod olarak ~100 satır; production-stack ölçümlerinde round-robin'e göre cache hit
%93 → %96 civarı. Çok turlu sohbette ve agent iş yüklerinde en iyi maliyet/fayda oranı budur.
Kademe 1 — Yaklaşık radix tree (v1.1, orta maliyet)
Router, gördüğü istek prefix'lerinden worker'ların cache'ini tahmin eden bir ağaç tutar (SGLang router'ın yaklaşımı). Gerçek cache durumunu bilmez; lazy güncellenir, maliyeti düşüktür.
Eşikler — gerçek implementasyonlarda kritik olan kısım bunlar:
cache_threshold: eşleşme oranı bunun altındaysa "cache yok" sayılır, yük dengeleme devreye girer.balance_abs_thresholdvebalance_rel_threshold:max_load − min_load > absvemax_load / min_load > relise prefix tamamen yok sayılır ve en az yüklü replikaya gidilir. (AIBrix de aynı korumayı koyuyor.) Bu koruma olmadan prefix affinity tek bir replikayı boğar — cache hit oranı artarken p99 gecikme çöker.eviction_interval+max_tree_size: ağaç sınırsız büyümesin.
Kararın hangi dalından geçtiği metriğe yazılmalı: cache_hit | cache_miss_min_load | load_balance_override | stale | no_tree | no_healthy_worker. Bu olmadan prefix routing'i
ayarlamak körlemesine olur.
Kademe 2 — Kesin KV index (v2, pahalı, opsiyonel)
vLLM --kv-events-config ile blok olaylarını ZMQ üzerinden yayınlar (BlockStored,
BlockRemoved). Router bunlara abone olup block_hash → {replika} haritası tutar; gerçek,
küresel bir görünüm elde eder.
Tuzak — planın kabul etmesi gereken maliyet: blok hash'leri vLLM'in token-id tabanlı
şemasıyla birebir aynı hesaplanmalıdır. Bu, router'ın istekleri engine ile aynı tokenizer'la
tokenize etmesini zorunlu kılar. Go tarafında bu demek: her model için tokenizer yüklemek
(cgo ile HF tokenizers veya saf Go bir implementasyon), sürüm uyumunu takip etmek ve istek
başına tokenizasyon CPU maliyetini ödemek. AIBrix bu yüzden "remote tokenizer" zorunluluğu
koyuyor. Kademe 0 ve 1 tokenizer gerektirmez — bu yüzden onlar v1'de, bu v2'de.
Olay kaybı: olay sıra numaralarında boşluk görülürse replay endpoint'inden eksik aralık istenir; alınamazsa o replikanın index'i düşürülür ve replika Kademe 1'e düşer (sessizce yanlış yönlendirme yapmaktansa yaklaşık bilgiye dönmek doğrudur). Replika yeniden başlarsa index sıfırlanır.
7.6 Engine metrik kontratı
Bu, "yeni bir engine eklemek" demenin resmî tanımıdır. Bir engine bu üçlüyü Prometheus formatında verirse llmgw onu yönlendirebilir (GIE'nin model server protokolü):
| Kontrat alanı | vLLM metriği | Zorunlu |
|---|---|---|
Waiting |
vllm:num_requests_waiting |
✅ |
Running |
vllm:num_requests_running |
✅ |
KVCacheUsage |
vllm:kv_cache_usage_perc |
✅ |
BlockSize, NumGPUBlocks |
vllm:cache_config_info |
➖ |
| LoRA durumu | vllm:lora_requests_info (max_lora, running_lora_adapters, waiting_lora_adapters) |
➖ |
Düzeltme: v0.1'de
vllm:gpu_cache_usage_percyazılmıştı; doğrusuvllm:kv_cache_usage_perc. Metrik adları sürümle değişiyor —ParseMetricseşlemesi config'ten ezilebilir olmalı ve agent, engine sürümünü register ederken bildirmeli.
Scrape kuralları:
- Her Ready endpoint 1–2 sn'de bir, endpoint başına goroutine, jitter ile.
- Başarısız scrape → endpoint "stale"; skoru kötüleşir ama hemen elenmez.
- 3 ardışık hata → breaker (§7.7).
- Stale veriyle karar vermemek için
inflightscorer'ı (§7.4) her zaman açık kalır.
7.7 Güvenilirlik
- Retry: sadece upstream'e ilk byte yazılmadan önce ve bağlantı hatası / 503 / 429 durumunda, farklı endpoint ile, en fazla N kez. Stream başladıktan sonra retry yok.
- Cooldown (LiteLLM dersi): hata veren endpoint
cooldown_secondsboyunca aday havuzundan çıkar. Uzun bir fallback listesi + cooldown'suz retry = retry fırtınası; bir endpoint'in rate limit'i tüm kümeye yayılır. - Circuit breaker: endpoint başına kapalı/açık/yarı-açık durum makinesi, üstel backoff.
- Fallback: modelin tüm endpoint'leri yok/dolu →
Fallbackslistesindeki modele (key izin veriyorsa). Yanıtax-llmgw-served-modelheader'ı. Bütçe fallback'i: key bütçesini aştıysa reddetmek yerine daha ucuz bir modele düşürme seçeneği (§7.9). - Timeout: bağlantı, ilk token (TTFT) ve toplam için ayrı; streaming'de token arası idle timeout.
- İptal: istemci bağlantıyı koparırsa upstream isteği de iptal et (context propagation) — GPU boşa çalışmasın. Kuyrukta bekleyen istekler için de geçerli.
- Drain: replika
Drainingiken yeni istek almaz; aktif istekler bitene veya timeout'a kadar bekler. - Control plane kopması: router son bilinen endpoint listesiyle çalışmaya devam eder (§14).
7.8 Streaming proxy detayları
http.Transport: yüksekMaxIdleConnsPerHost, HTTP/1.1 keep-alive (engine'ler genelde h2c desteklemez).bufio.Readerile satır oku,data:satırlarını geçir, her event sonrasıhttp.Flusher.Flush().- Usage için istemci
stream_options.include_usagegöndermemişse router ekleyebilir (config ile), son chunk'taki usage'ı yakalar; istemci istememişse o chunk'ı istemciye iletmez. - Upstream'in hata JSON'larını OpenAI formatına normalize et.
- Yanıt header'ları:
x-llmgw-replica,x-llmgw-pool,x-llmgw-served-model,x-llmgw-queue-ms(admission'da beklenen süre),x-llmgw-cache-decision(§7.5).
7.9 Kimlik, kota, kullanım (tenancy)
LiteLLM'in üretimde kanıtlanmış modeli:
Organizasyon ─► Takım ─► Proje ─► API Key
Her seviyede: bütçe (token veya sanal maliyet birimi), RPM/TPM limiti, izinli model listesi. Key'de ayrıca: öncelik bandı (§7.2.2) ve varsayılan yönlendirme profili (§7.3).
- API key:
sk-llmgw-..., DB'de sadece hash (SHA-256). Sızarsa upstream'e dokunmadan döndürülür. - Rate limit: RPM (
x/time/rate) + TPM. Token limiti istek başındamax_tokens + tahmini promptile rezerve edilir, yanıt bitince gerçek değerle düzeltilir. (Prompt tahmini v1'de bayt/4; Kademe 2 tokenizer geldiğinde kesinleşir.) - Bütçe: dönemsel (günlük/aylık) harcama. Aşımda:
429veya bütçe fallback'i. Maliyeti sıfır olan modeller bütçe kontrolünden muaf — böylece bütçesi bitmiş bir key'e "ucuz model" fallback'i tanımlanabilir. - Spend yazımı istek yolunun dışında: usage kaydı kanala → batch halinde SQLite'a; saatlik rollup. İstek yolunda hiçbir DB yazımı yok.
- Replika sabitleme (debug):
x-llmgw-replicaheader'ı, key'e scope'lu. Sabitlenen replika cooldown'da veya yoksa normal yönlendirmeye düşer. - v1 tek instance → bellek içi limiter. Çok instance olursa Redis veya tutarlı hash ile sticky (v2).
8. Gözlemlenebilirlik
Prometheus metrikleri (örnek):
llmgw_requests_total{model,pool,status}
llmgw_request_duration_seconds{model,pool}
llmgw_ttft_seconds{model,pool}
llmgw_tokens_total{model,direction="prompt|completion"}
llmgw_endpoint_inflight{replica}
llmgw_endpoint_score{replica}
llmgw_replicas{model,state}
llmgw_gpu_free{node,gpu_class,fabric}
llmgw_schedule_failures_total{model,reason}
llmgw_agent_connected{node}
# admission / flow control (§7.2)
llmgw_admission_queue_depth{band,model}
llmgw_admission_wait_seconds{band,model} # histogram
llmgw_admission_rejected_total{band,reason="full|ttl|client_gone"}
llmgw_pool_saturation{pool} # 0..1, dedektör çıktısı
# yönlendirme kararları (§7.5) — bunlar olmadan prefix routing ayarlanamaz
llmgw_cache_decision_total{model,decision="hit|miss_min_load|balance_override|stale|no_tree"}
llmgw_prefix_match_ratio{model} # histogram
llmgw_scorer_value{scorer,replica}
llmgw_endpoint_metrics_stale{replica}
llmgw_capacity_profile_stale{model,profile}
- OpenTelemetry trace: router span → upstream span (traceparent header engine'e iletilir).
- Yapısal log (slog JSON),
request_idher yerde. llmgw ctl top: havuz bazında anlık kuyruk ve doluluk.
9. Konfigürasyon Örnekleri
9.1 server.yaml
listen: ":8080"
admin_listen: ":9090" # metrics, admin API, pprof
agent_listen: ":7443"
tls:
ca: /etc/llmgw/ca.pem
cert: /etc/llmgw/server.pem
key: /etc/llmgw/server-key.pem
store:
path: /var/lib/llmgw/llmgw.db
fabrics:
- name: ib-a
gid_prefix: "fec0:0000:0000:000a" # opsiyonel otomatik eşleme
- name: ib-b
gid_prefix: "fec0:0000:0000:000b"
router:
scrape_interval: 2s
inject_usage: true
retries: 2
cooldown_seconds: 15 # hata veren endpoint bu süre aday havuzdan çıkar
endpoint_cache_max_age: 5m # control plane düşerse bu kadar eskiye kadar çalışmaya devam
# §7.2 admission — doygunluk dedektörü
admission:
target_waiting_per_replica: 4 # ctl bench önerir
kv_ceiling: 0.90
queue_ttl: 30s
queue_capacity_per_band: 2000
bands:
- { name: platinum, priority: 400, saturation_ceiling: 1.00 }
- { name: gold, priority: 300, saturation_ceiling: 0.85 }
- { name: silver, priority: 200, saturation_ceiling: 0.60 }
- { name: bronze, priority: 100, saturation_ceiling: 0.30 }
# §7.3 yönlendirme profilleri
default_profile: chat
profiles:
chat:
scorers: { prefix: 3.0, queue: 1.0, kv: 1.0, inflight: 1.0 }
picker: { type: p2c }
batch:
scorers: { queue: 3.0, kv: 1.0, load: 1.0, prefix: 0.5 }
picker: { type: max-score }
long-context:
scorers: { kv: 3.0, prefix: 2.0, queue: 1.0 }
picker: { type: softmax, temperature: 0.2 }
# §7.5 prefix farkındalığı
prefix:
session_affinity: { enabled: true, header: x-session-id, load_factor: 1.25 } # Kademe 0
approx_tree: # Kademe 1
enabled: false # v1.1
cache_threshold: 0.30
balance_abs_threshold: 16
balance_rel_threshold: 1.5
max_tree_size: 2000000
eviction_interval: 60s
kv_events: { enabled: false } # Kademe 2 — tokenizer gerektirir, v2
models:
- name: llama-3.3-70b
source: /models/Llama-3.3-70B-Instruct
scaling: { min: 2, max: 6 }
fallbacks: [qwen2.5-32b]
routing_profile: chat
slo: { ttft_p99: 2s, tpot_p99: 50ms } # ctl bench bu SLO'ya göre kapasite ölçer
profiles:
- name: h100-tp4-fp8
gpu_class: h100-80g
engine: vllm
tp: 4
nodes: 1
priority: 100
weight: 100
args: ["--quantization", "fp8", "--max-model-len", "32768"]
- name: a100-tp8
gpu_class: a100-80g
engine: vllm
tp: 8
nodes: 1
priority: 50
weight: 45
- name: deepseek-large
source: /models/DeepSeek-V3
scaling: { min: 1, max: 2 }
profiles:
- name: h100-2node
gpu_class: h100-80g
engine: sglang
tp: 16
nodes: 2 # → aynı fabric zorunlu
gpus_per_node: 8
priority: 100
weight: 100
startup_timeout: 40m
9.2 agent.yaml
node_id: gpu-a-01
server: "llmgw-server.internal:7443"
mgmt_interface: eth0
tls: { ca: ..., cert: ..., key: ... }
labels: { rack: r12 }
fabrics:
- name: ib-a
hcas: [mlx5_0, mlx5_1, mlx5_2, mlx5_3]
port_range: [20000, 20999] # engine HTTP + dist init portları
engines:
vllm: { bin: /opt/venvs/vllm/bin/vllm, launch_mode: ray }
sglang: { python: /opt/venvs/sglang/bin/python }
work_dir: /var/lib/llmgw-agent
10. Benchmark ve Ağırlıklandırma
llmgw ctl bench <model> --profile <p>:
- Hedef replikaya sabit prompt/çıktı uzunluklarıyla artan eşzamanlılıkta yük uygular.
- TTFT p50/p95, TPOT, throughput (tok/s), SLO'yu karşılayan maksimum eşzamanlılık ölçülür.
- Çıktı §6.2.1'deki
CapacityProfile'dır:MaxConcurrencyAtSLO, throughput, TTFT/TPOT p99. --applyile üç değeri birden günceller: profileweight,target_waiting_per_replica, autoscaling hedefi.- Farklı GPU sınıflarını karşılaştırmanın tek sağlıklı yolu bu; tahmini ağırlık kullanma.
--sweep-prefixmodu: prefix cache hit oranını 0/50/90% senaryolarıyla ölçer — yönlendirme profillerinin ağırlıklarını (§7.3) körlemesine değil ölçerek ayarlamak için.- Engine sürümü değişince profil bayatlar;
ctl benchsonucu engine sürümüyle etiketlenir.
11. Yol Haritası
Faz 0 — İskelet (1 hafta)
go mod init, cobra komutları, koanf config, slog, Makefile, golangci-lintsim-engine: OpenAI uyumlu sahte engine (ayarlanabilir gecikme, token hızı, kuyruk,/metricsvLLM formatında)- CI:
go test ./..., race detector
Faz 1 — Statik router (2 hafta)
- OpenAI handler'ları, streaming proxy, iptal propagasyonu
- Config'ten statik endpoint listesi
Filter/Scorer/Pickerçerçevesi (§7.3) — tek bir "strateji" değil, en baştan eklentiqueue,kv,inflightscorer'ları;max-scorevep2cpicker'ları- Session affinity (§7.5 Kademe 0) — ucuz, erken kazanç
- Metrik scrape (§7.6 kontratı), stale tespiti, retry, cooldown, breaker
- Prometheus metrikleri + karar metrikleri (§8)
- Çıkış kriteri: 3 sim-engine arkasında 1000 eşzamanlı stream; istemci kopmalarında upstream'in iptal edildiği doğrulanmış; router overhead p99 < 2 ms.
Faz 1.5 — Admission control (1 hafta) ⭐
- Doygunluk dedektörü (§7.2.1)
- Öncelik bantları, bant içi tenant round-robin, kuyruk kapasitesi + TTL
Admissioninterface + lease, kuyrukta iptalllmgw_admission_*metrikleri- Çıkış kriteri: bronze banttan 500 eşzamanlı batch isteği akarken platinum bandından gelen interaktif isteklerin TTFT p99'u boştaki değerin 1.5 katını aşmıyor. Bu testi yazmadan ileri gitme — Faz 1.5'in tek varlık sebebi bu.
Faz 2 — Agent: keşif + tek node engine (2 hafta)
- GPU keşfi (NVML + fallback), IB keşfi, topoloji
- Engine interface, vLLM ve SGLang tek-node
- Supervisor (process group, log tamponu, durum makinesi, sahiplenme)
- connect-go stream, register/heartbeat, mTLS
- Çıkış kriteri: gerçek bir node'da
ctlile model başlat/durdur.
Faz 3 — Control plane (2–3 hafta)
- SQLite store + migration
- Katalog, envanter, scheduler (tek-node profile'lar), reconciler
- Router'ın
EndpointSource'u dinamik hale gelir ctl: nodes, models, replicas, cordon, drain, explain-placement, logs- Çıkış kriteri: node kapatılınca replikalar başka node'a taşınıyor; router kesintisiz yönlendiriyor.
Faz 4 — Multi-node & fabric (2 hafta)
- Fabric kimliği (config + GID prefix), doğrulama
- Multi-node placement (fabric kısıtı), port ayırma, rank sıralı başlatma
- NCCL env üretimi, HCA seçimi
- Replika bazlı hata yönetimi (bir shard ölürse tümü)
- Çıkış kriteri: her iki fabric'te 2-node replika; bir node'u öldürünce replika aynı fabric'te yeniden kuruluyor, asla diğer fabric'e yayılmıyor.
Faz 5 — Üretim özellikleri (2–3 hafta)
- Tenancy: org/takım/proje/key hiyerarşisi, bütçe, RPM/TPM, usage kaydı (§7.9)
- Bütçe fallback'i, model allowlist, key→band eşlemesi
- Yönlendirme profilleri config'ten +
x-llmgw-profileheader'ı - Yaklaşık radix tree (§7.5 Kademe 1) — eşikler ve karar metrikleriyle birlikte
- Fallback modeller, havuz taşması (spillover)
ctl bench→CapacityProfile(§6.2.1),ctl plan- OTel tracing
- systemd unit'leri, dokümantasyon
Faz 6 — v2 fikirleri
- Kesin KV index (§7.5 Kademe 2) — vLLM KV event'leri + tokenizer entegrasyonu
- Dynamo tarzı blok maliyet fonksiyonu,
softmaxpicker'ın ayarlanması - Admission displacement (düşük banttan istek düşürme)
- Autoscaling ve öncelik bazlı preemption
- Control plane HA (Raft)
- Ağırlık indirme/cache yönetimi
- Prefill/decode ayrıştırması (§12)
- LoRA adapter yönlendirmesi (adapter'ı yüklü replikaya affinity)
- Dış provider desteği (fallback olarak)
- Admin web arayüzü
12. Prefill/Decode Ayrıştırması (v2 notları)
- Prefill ve decode replikaları aynı fabric içinde olmalı (KV transferi RDMA üzerinden).
- Router'da iki aşamalı akış: prefill replikasına gönder → KV handle → decode replikası.
- Engine desteği sürümlere çok bağlı (vLLM KV connector'ları, SGLang PD modu, NVIDIA Dynamo/NIXL). Kendi implementasyon yerine önce engine'in yerleşik PD router'ını bir "endpoint" gibi sarmak daha az riskli.
- llm-d ve Dynamo'nun gösterdiği: PD'nin kazancı esas olarak uzun context'te. Kısa promptlu sohbet trafiğinde KV transferi maliyeti kazancı yiyor. Önce §10'daki bench ile iş yükünüzün ISL/OSL dağılımını ölçün; PD'yi ancak uzun-context modelleri için açın.
- Scheduler'a
Role: prefill|decodeve "aynı fabric'te eşli yerleşim" kısıtı eklenir.
13. Test Stratejisi
- Birim: scheduler (tablo tabanlı: heterojen envanter + beklenen yerleşim / hata sebebi), balancer skorları, SSE parse, metrik parse (gerçek vLLM/SGLang
/metricsçıktılarından fixture). - Özellik tabanlı: scheduler çıktısında "multi-node replika tek fabric'te" ve "tek GPU class" invariant'ları her zaman doğru (
testing/quickveyarapid). - Entegrasyon: tek süreçte server + N sahte agent (sahte GPU/IB envanteri) + sim-engine'ler.
- Kaos: agent öldürme, ağ kesintisi (toxiproxy), engine çökmesi, yavaş engine, control plane'i öldürüp router'ın önbellekle devam ettiğini doğrulama.
- Öncelik izolasyonu: Faz 1.5 çıkış kriteri — düşük öncelikli yük altında yüksek öncelikli TTFT'nin korunduğu regresyon testi. Bu test CI'da kalıcı olmalı.
- Yönlendirme kalitesi: sim-engine'e gerçekçi bir prefix cache modeli koy (blok bazlı LRU), sentetik çok-turlu trafikle cache hit oranını ölç. round-robin / session-affinity / approx-tree karşılaştırması sayısal olsun.
- Yük:
k6veya kendi Go yük üreticimiz; router'ın kendi overhead'ini ölç (hedef: p99 < 2 ms ek gecikme). - Gerçek donanım: her fazın sonunda en az bir IB'li ve bir IB'siz node'da smoke test.
14. Riskler ve Açık Sorular
| Konu | Not |
|---|---|
| Engine sürüm farkları | CLI bayrakları ve metrik adları sık değişiyor → engine adapter'larını sürüm eşlemeli ve config'le ezilebilir yap. |
| vLLM multi-node başlatma | Ray mı yerleşik mp mi? Kullanılacak sürümde test edilmeli. |
| Fabric tespiti | OpenSM'lerde benzersiz subnet prefix ayarlanabilir mi? Değilse manuel etiket şart. |
| Aynı node'da çok fabric | Var mı? Varsa HCA-GPU NUMA eşleşmesi önemli. |
| Model depolama | Paylaşımlı FS var mı, yükleme süreleri? Startup timeout'ları buna göre. |
| Karma sürücü/CUDA sürümleri | Engine venv'leri GPU sınıfına göre farklı olmalı mı? (engines config'i profile başına override edilebilmeli.) |
| Tek control plane | v1'de SPOF. Router endpoint listesini önbellekte tutar (§6.4), control plane kısa süre düşse de çalışmaya devam eder. |
| Güvenlik | Engine portları sadece router'a açık olmalı (firewall / bind adresi). |
| Tokenizer tutarlılığı | Kesin KV index (§7.5 Kademe 2) router'ın engine ile aynı tokenizer'ı kullanmasını zorunlu kılar. Go'da bu cgo veya ayrı bir tokenizer servisi demek. Bu yüzden v2'ye bırakıldı; v1'in prefix çözümü tokenizer gerektirmiyor. TPM limitindeki prompt tahmini de bu yüzden v1'de yaklaşık (bayt/4). |
| Prefix affinity'nin ters tepmesi | Yük dengesizliği koruması (§7.5 Kademe 1 eşikleri) olmadan prefix routing cache hit oranını artırırken tek replikayı boğar ve p99'u bozar. Eşikler açılmadan prefix affinity açılmamalı. |
| Admission eşiklerinin ayarı | target_waiting_per_replica çok düşükse GPU aç kalır, çok yüksekse kuyruk gecikmesi geri gelir. Bu tek sayı sistemin davranışını belirliyor; ctl bench ile ölçülmeli, tahmin edilmemeli. |
| KV event kaybı | ZMQ fire-and-forget; olay kaybında router sessizce yanlış yönlendirir. Sıra numarası boşluğu tespiti + Kademe 1'e düşme zorunlu (§7.5). |
| Metrik bayatlığı | 2 sn'lik scrape aralığında 1000 istek/sn'de karar tamamen bayat veriye dayanır. inflight scorer'ı bu yüzden opsiyonel değil. |
15. İlk Adımlar (VS Code'da buradan devam)
mkdir llmgw && cd llmgw && go mod init <modul-yolu>/llmgwcmd/llmgw/main.go: cobra ileserver,agent,ctl,sim-enginealt komutlarının boş iskeleti.internal/sim: sahte engine — ilk yazılacak gerçek kod bu olsun, geri kalan her şey buna karşı test edilecek.internal/router/proxy: streaming proxy + iptal testi.internal/router/scheduler:Filter/Scorer/Pickerinterface'leri +queue,kv,inflightscorer'ları. Tek bir "least-load" fonksiyonu yazma — çerçeveyi en baştan kur, sonradan geri dönmek pahalı.internal/router/admission: doygunluk dedektörü + bant kuyrukları. Faz 1.5.- Faz 1 ve Faz 1.5 çıkış kriterlerini sağlayan e2e testlerini yaz, sonra Faz 2'ye geç.
internal/router/balancer/yerineinternal/router/scheduler/(§4'teki ağaç buna göre güncellenmeli): "balancer" ismi yaptığı işten dar kalıyor — bu bileşen yük dengelemekten fazlasını yapıyor.