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>
1046 lines
53 KiB
Markdown
1046 lines
53 KiB
Markdown
# 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.
|