Files
llmgw/llmgw-plan.md
T
ilkerandClaude Opus 5 e07bc46c57 Faz 0: iskelet ve sim-engine
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>
2026-09-16 01:00:03 +02:00

53 KiB
Raw Blame History

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 prefix
  • sm_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ı:

  1. Agent config'inde açık etiket: fabrics: [{name: ib-a, hcas: [mlx5_0, mlx5_1]}] (önerilen)
  2. Her OpenSM'de benzersiz subnet_prefix ayarlanmışsa GID prefix'inden otomatik eşleme (server config'inde prefix → fabric tablosu)
  3. Hiçbiri yoksa: node fabric=unknown olarak 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 T doğal olarak destekler.
  • vLLM: kullanılan sürüme göre ya Ray (leader'da ray start --head, worker'larda ray 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.go içinde iki yol da launchMode ile 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 logs için).
  • Durum makinesi: Pending → Starting → Loading → Ready → Draining → Stopped | Failed.
  • Ready ancak /health 200 ve /v1/models modeli listeliyorsa.
  • Model yükleme uzun sürer; startupTimeout profile'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: StartShard aynı shard_id ile 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 sonra Lost → ü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):

  1. Tüm shard'lar aynı GPUClass.
  2. Nodes > 1 ise tüm node'lar aynı Fabric'e bağlı olmalı ve o fabric'te ACTIVE HCA'ları olmalı.
  3. GPUsPerNode kadar boş GPU; tercihen aynı NVLink domain'inde ve HCA ile aynı NUMA'da.
  4. Node Ready ve Cordoned değil.
  5. Engine Validate geç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:

  1. Router ağırlığı: Profile.Weight artık elle yazılmaz, MaxConcurrencyAtSLO'dan türetilir.
  2. Admission eşikleri: TargetWaitingPerReplica (§7.2.1) ölçülen değerden önerilir.
  3. 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 sadece ctl ile ö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 StartShard gö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), sonra Stop.
  • Node Lost → replikalarını Failed say.

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_ttl sü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:

  1. Havuz seçimi: Priority en 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.
  2. 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'nun router_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_threshold ve balance_rel_threshold: max_load − min_load > abs ve max_load / min_load > rel ise 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_perc yazılmıştı; doğrusu vllm:kv_cache_usage_perc. Metrik adları sürümle değişiyor — ParseMetrics eş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 inflight scorer'ı (§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_seconds boyunca 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 → Fallbacks listesindeki modele (key izin veriyorsa). Yanıta x-llmgw-served-model header'ı. 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 Draining iken 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üksek MaxIdleConnsPerHost, HTTP/1.1 keep-alive (engine'ler genelde h2c desteklemez).
  • bufio.Reader ile satır oku, data: satırlarını geçir, her event sonrası http.Flusher.Flush().
  • Usage için istemci stream_options.include_usage gö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şında max_tokens + tahmini prompt ile 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: 429 veya 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-replica header'ı, 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_id her 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.
  • --apply ile üç değeri birden günceller: profile weight, 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-prefix modu: 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 bench sonucu engine sürümüyle etiketlenir.

11. Yol Haritası

Faz 0 — İskelet (1 hafta)

  • go mod init, cobra komutları, koanf config, slog, Makefile, golangci-lint
  • sim-engine: OpenAI uyumlu sahte engine (ayarlanabilir gecikme, token hızı, kuyruk, /metrics vLLM 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 eklenti
  • queue, kv, inflight scorer'ları; max-score ve p2c picker'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
  • Admission interface + lease, kuyrukta iptal
  • llmgw_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 ctl ile 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-profile header'ı
  • 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, softmax picker'ı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|decode ve "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/quick veya rapid).
  • 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: k6 veya 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)

  1. mkdir llmgw && cd llmgw && go mod init <modul-yolu>/llmgw
  2. cmd/llmgw/main.go: cobra ile server, agent, ctl, sim-engine alt komutlarının boş iskeleti.
  3. internal/sim: sahte engine — ilk yazılacak gerçek kod bu olsun, geri kalan her şey buna karşı test edilecek.
  4. internal/router/proxy: streaming proxy + iptal testi.
  5. internal/router/scheduler: Filter/Scorer/Picker interface'leri + queue, kv, inflight scorer'ları. Tek bir "least-load" fonksiyonu yazma — çerçeveyi en baştan kur, sonradan geri dönmek pahalı.
  6. internal/router/admission: doygunluk dedektörü + bant kuyrukları. Faz 1.5.
  7. Faz 1 ve Faz 1.5 çıkış kriterlerini sağlayan e2e testlerini yaz, sonra Faz 2'ye geç.

internal/router/balancer/ yerine internal/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.