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

1046 lines
53 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
```go
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:
```proto
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)
```go
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:
```go
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
```go
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):
```go
// 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:
```yaml
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).
```go
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.
```go
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
```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
```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.