diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index 96b9ed68..b2f51c85 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -39,6 +39,16 @@ jobs: - name: Build run: go build ./... + # The Terraform provider is a module of its own, which ./... above does + # not reach. Its tests check its client against docs/admin-api.openapi.json, + # so a change to the admin API that breaks the provider fails here. The + # acceptance tests (TF_ACC=1) are left out: they need Terraform itself. + - name: Test the Terraform provider + working-directory: terraform-provider-llmgw + run: | + go vet ./... + go test ./... + # The NVML backend needs cgo and cannot run without a driver, but it must # at least keep compiling: it is the only source of NVLink topology and a # break would otherwise surface on a GPU node, far from here. diff --git a/.gitignore b/.gitignore index 31cc8427..d3819d0b 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,7 @@ *.db-shm .DS_Store coverage.out +# The provider built in place, and what Terraform leaves beside an example. +/terraform-provider-llmgw/terraform-provider-llmgw +/terraform-provider-llmgw/examples/.terraform* +/terraform-provider-llmgw/examples/terraform.tfstate* diff --git a/BACKLOG.md b/BACKLOG.md index c61dfe03..4be277b7 100644 --- a/BACKLOG.md +++ b/BACKLOG.md @@ -412,62 +412,352 @@ portal is not done — the page shows; the console and ctl change. templates driven by `server init` or the console; llmgw-native webhooks for model parked, budget spent, update available (from the reconciler and `modelserve`). -6. **Request metadata and tags (S).** Accept `metadata`/`user` from the +6. **Done (branch `features-c2`):** `metadata`, `x-llmgw-tags` and `user` + on the usage record (migration 0023), `ctl request` shows them, + `router.tag_labels` metrics with 100 values per tag. Left: export and + `ctl usage` by tag or end user (the hourly and daily sums do not carry + tags; it would read the request records, within their retention). + **Request metadata and tags (S).** Accept `metadata`/`user` from the body or `x-llmgw-tags`; store on the usage row; tenant metric labels behind an allowlist. `router/handlers.go` parse, `accounting/recorder.go`. -7. **Canary and weighted A/B between model revisions (M).** +7. **Done (branch `features-c2`):** `ctl model canary/promote/canaries`, + session-sticky split with `x-llmgw-variant` pins, rollback on error rate + or TTFT, `canary_rolled_back` notification, console menu. Left: A/B + between two different models (the split is between a model and its + newer weights); the comparison is per control plane and lives in memory, + so a restart begins it again; a key-level pin. + **Canary and weighted A/B between model revisions (M).** `control/modelserve/updates.go` `replace` swaps every replica; add weighted routing across two revisions/aliases (scheduler filter, alias resolution in `router/router.go:569`), a header/key pin, automatic rollback on error-rate or TTFT regression from per-replica metrics. -8. **Batch API and Files (M–L).** `/v1/files`, `/v1/batches`, JSONL +8. **Done (branch `features-c2`):** `/v1/files` and `/v1/batches` + (OpenAI's shape), worker under a store lease, lines kept as served, + lowest band, usage tagged `batch=`, output and error files with + retention, `no_store` refused. Left: the Responses API (`/v1/responses`) + as a batch endpoint; the console and `ctl` do not list batches (an + operator sees them through usage tags); a file is one row in the store, + so a store backup carries batch files with it. + **Batch API and Files (M–L).** `/v1/files`, `/v1/batches`, JSONL storage, a worker feeding the bronze band, accounting. New `internal/router/batch`. -9. **Request/response logging and replay (M).** Opt-in per project with +9. **Done (branch `features-c2`):** `keys requests` (retention, sample), + kept after redaction, `ctl request --body/--replay`, console, pruning. + Left: a streamed answer is kept as its text, not its chunks; replay is + one request at a time (a set of them against a model is item 21's eval). + **Request/response logging and replay (M).** Opt-in per project with retention like threads; sampled or full; redaction hooks from B; `ctl request --body`; replay against another model. -10. **OpenAI compatibility gaps (S–M each).** Responses: `text.format` → +10. **Done (branch `features-c2`):** Responses `text.format`, + `input_image`, `previous_response_id` (thread in the id); rerank and + score passthrough; transcription and translation as multipart; + `/v1/moderations` by the judge. Left: audio is charged no tokens (an + engine's duration usage is not read); `input_image` by `file_id`; + moderation scores are 0 or 1, as a judge says yes or no. + **OpenAI compatibility gaps (S–M each).** Responses: `text.format` → `response_format`, `input_image`, `previous_response_id` via threads (`router/responses.go`). Rerank/score passthrough for vLLM, `/v1/audio/transcriptions` for a whisper engine, `/v1/moderations` mapped to the guard model. -11. **Anthropic `/v1/messages` (M).** Translate like `responses.go`. -12. **`server restore` (S).** Restore is manual shell today +11. **Done (branch `features-c2`):** `/v1/messages` and `count_tokens`, + streamed and not, tools, images, `x-api-key`, Anthropic error shape. + Left: extended thinking (a reasoning model's thoughts are not mapped to + thinking blocks); prompt caching; the account page's "Connect your + editor" does not offer Claude Code yet. + **Anthropic `/v1/messages` (M).** Translate like `responses.go`. +12. **Done (branch `features-c2`):** `server restore` (dry run, version + check, decryption, modes and owners, SQLite and PostgreSQL), + `backup_copy_to` (directory or ssh), the drill in docs/install.md. + Left: restoring a replicated store's members (restore into the primary; + Patroni replicates it); the console's Back up now does not offer + restore; an ssh copy holds the archive in memory while it sends it. + **`server restore` (S).** Restore is manual shell today (`docs/install.md:1187`); add the command with version check, dry run, off-host copy target; a documented DR drill. -13. **SLO-based admission and token-level metrics (S–M).** TPOT and +13. **Done (branch `features-c2`):** TPOT, inter-token and tokens/s + histograms by model, pool and tenant; `slo` pressure in admission's + saturation; `llmgw_model_slo_seconds` and `llmgw-slo` alerts. Left: the + p99 is per control plane, from its own requests; an SLO per band or per + tenant; placement does not yet add replicas for an SLO (item 14). + **SLO-based admission and token-level metrics (S–M).** TPOT and inter-token histograms, output tokens/s per model and tenant in `router/metrics.go`; use `catalog.SLO` in `admission/saturation.go`. -14. **Scheduled and warm-pool autoscaling (S–M).** Time-of-day min/max, +14. **Done (branch `features-c2`):** `scaling.schedule` (days, from, to, + min, max; past midnight), `scaling.prewarm`, `control.timezone`; + queue-depth scaling was there already. Left: `ctl scale` sets min and + max only (a schedule is set in the definition); scaling for an SLO + rather than for queue depth. + **Scheduled and warm-pool autoscaling (S–M).** Time-of-day min/max, pre-warm, queue-depth scaling in `catalog.Scaling`, `control/reconciler/demand.go`, `headroom.go`. -15. **Secrets management (S–M).** Vault/KMS for `api_key_file`, the DSN, the +15. **Done (branch `features-c2`):** `env:` and `vault:` references + wherever a secret file is named (store address, api_key_file, OIDC, + SCIM, webhooks), Vault KV with token or AppRole, `secrets.master_key` + sealing cluster_secrets (Vault transit or a local key). Left: the + certificate authority's key is still a file in /etc/llmgw (signing in + Vault's PKI engine instead is its own change); rotating the master key; + `backup_copy_key` and `admin_token_file` are files only. + **Secrets management (S–M).** Vault/KMS for `api_key_file`, the DSN, the CA key, `cluster_secrets` (`store/secrets.go`, `store/seal.go`); envelope-encrypt them in backups (with A8 backups). -16. **GDPR and residency (S).** "Forget user" anonymises `user_id` in usage +16. **Done (branch `features-c2`):** `users forget` (pseudonymised usage + and sums, kept requests, files, batches, limits and audit names), `keys + residency --in-cluster` (asked-for, fallback and canary). Left: an + export of everything held about a person (article 15); residency by + region between several clusters; backups keep what was forgotten until + they age out. + **GDPR and residency (S).** "Forget user" anonymises `user_id` in usage and rollups and erases threads/memory (`store/hierarchy.go:241` leaves it today); per-project "never route to an External provider". -17. **Response/semantic cache (M).** Exact-match first, per project, +17. **Done (branch `features-c2`):** exact-match answer cache per project (`keys + cache --ttl/--any/--off`, console **Cache answers…**, `projects` + columns, 30-second setting cache), reproducible answers only unless + `--any`, LRU in memory bounded by `router.cache.max_bytes` and + `max_entry_bytes`, streamed answers kept and replayed as chunks, + `x-llmgw-cache` and `Cache-Control: no-cache`, guardrails before a hit + and the output policy on it, `no_store` and threads bypass, a hit + recorded as `cache_hit` with no tokens and no cost (migration 0027), + metrics, docs. Left: semantic (embedding-similarity) caching through the + embeddings models; a cache shared across control planes (each process + keeps its own, deliberately: a shared one would write every answer to + the store); a hit still waits its turn in admission, because the + guardrails judge the request after admission and the key is the request + they let through; logprobs in a streamed answer leave it unkept; `users + forget` does not reach into the cache (answers age out by the TTL); no + listing or flushing of what is cached (`--off` stops it being served at + once, the memory is freed by TTL and LRU). + **Response/semantic cache (M).** Exact-match first, per project, opt-in, TTL; semantic via the embeddings models later. Before `dispatch` in `router/handlers.go`. -18. **Kubernetes/Helm and an air-gapped bundle (M).** `deploy/`, +18. **Done (branch `features-c2`):** offline bundles — `llmgw bundle create` + (releases with signed checksums, every llama.cpp build per arch/variant + with GitHub's checksums, starter/judge and named Hugging Face model + files pinned and checked; directory or tar; manifest sha256), `bundle + import` (checked, all-or-nothing, into the mirror under `_llmgw/`), + `bundle trust`, `bundle show --verify`; + `offline.mirror`/`offline.checksums` in server.yaml, with nodes + installing llama.cpp from the mirror against checksums the control plane + sends over the agent stream (proto `EngineWant.offline_*`), releases + defaulting to the mirror for `node add`, `ctl upgrade` and agent + upgrades, update checks off; `server init --bundle` and the setup form's + bundle fields; docs/data.md's offline claim corrected; install.md + "Offline sites". A Helm chart for the control plane + (`deploy/helm/llmgw`, one replica, SQLite PVC or external PostgreSQL, + Secrets, Services, Ingress, ServiceMonitor) with + `deploy/container/Dockerfile` and docs/kubernetes.md; GPU nodes stay + outside Kubernetes by design. Left: vLLM/SGLang offline (a wheelhouse of + several GB per CUDA build and a uv `--find-links` install path); the + NVML release binary and uv in bundles; the setup wizard's preflight + still fails a machine without internet; `join`'s printed `curl` from the + mirror checks nothing; models in a bundle are single files (no whole- + repository safetensors sets yet); the chart runs one replica (a standby + is never ready, so HA in Kubernetes needs a different readiness design), + has not been installed on a real cluster, and ships no agent DaemonSet; + no published container image. + **Kubernetes/Helm and an air-gapped bundle (M).** `deploy/`, `agent/provision`; `docs/data.md` claims offline operation but install assumes the internet. -19. **OpenAPI for the admin API, Terraform provider (M).** Generate from +19. **Done (branch `features-c2`):** `adminapi.Routes` and + `internal/docgen/openapi` generating `docs/admin-api.openapi.json` (3.1, + bearer security, every route, query parameters, schemas from the Go + types with their comments), served embedded at `GET + /api/v1/openapi.json`, kept true by a route-table test and a staleness + test; validated with openapi-spec-validator and openapi-generator-cli. + `GET /api/v1/models/{name}`. `docs/admin-api.md`. `terraform-provider- + llmgw/` (terraform-plugin-framework): `llmgw_model`, `llmgw_quota`, + `llmgw_guard_attachment`, data sources `llmgw_models` and `llmgw_nodes`; + client tests against a fake admin API and the OpenAPI document; + acceptance tests with Terraform and OpenTofu against the fake; one + apply, empty plan, in-place change and destroy against a real `llmgw + server` run by hand. Left: organizations, teams, projects, people and + keys are not in the admin API (they are `llmgw org`/`users`/`keys` + against the store), so not in the provider; a model's definition beyond + scaling, class, owner and adapters is changed by replacing it (the API + has no edit, and `resources` is not used yet); `canary`, `slo`, + `scaling.schedule` and `prewarm`, `guard` role and `origin` are not in + `llmgw_model`; models cannot be imported; the provider is not published + to a registry and has no release build; the acceptance tests are not run + in CI (they need Terraform); the document's schemas mark nothing + required and give no enums; `catalog.SLO`'s fields have no JSON tags, so + they are `TTFTp99` and `TPOTp99` on the wire. + **OpenAPI for the admin API, Terraform provider (M).** Generate from `adminapi/api.go` routes via `docgen`. -20. **Tracing beyond the router (S).** Spans for reconciler, placement, +20. **Done (branch `features-c2`):** spans for the reconcile pass (begun only + when a pass does something), placement with its answer or rejections, + scale-up/down, drain, stop, eviction, preemption, reaping, restarts and + lost nodes; a `replica start` span from placement to serving whose + context travels to the agent in the start command + (`ControlMessage.trace`), where weights fetch, engine launch, rendezvous + and readiness wait continue the trace; stops, drains, adoption and + engine installs; modelserve jobs as a trace with a span per step linked + to the replica's start; an agent `tracing` block; docs in install.md's + "Tracing". Left: the router's span for a request does not link to the + replica it was sent to's start; heartbeats, fabric scans, logs and agent + upgrades are not traced; the supervisor has no restart span because it + never restarts an engine itself (a restart is the reconciler's `restart + replica` and reaches a node as a stop and a start); canary and promote + jobs, which landed on `features-c2` after this was branched, are traced + only through the shared step recording (as ` model`), unchecked by + a test. + **Tracing beyond the router (S).** Spans for reconciler, placement, agent start (`obs/trace.go`, `control/reconciler`, `agent/supervisor`). -21. **Eval harness (M).** `llmgw eval` extending `internal/bench` with +21. **Done (branch `features-c2`):** `internal/bench/eval` (suites in YAML or + JSON lines; exact, contains, regex, number, a JSON Schema subset, and a + judge model with a rubric; weights and a threshold), run on the control + plane through `Router.Replay`; `llmgw ctl eval MODEL --suite FILE|NAME`, + `--history`, `--run`, `--suites`; runs and their cases kept (migration + 0028, `eval_runs` and `eval_cases`); `model update`/`promote --eval + SUITE --min-score N`, a model's standing gate (`ctl model gate`, `eval:` + in the catalog) — a promote asks the canary first, an update tries the + new weights as a 0% canary and promotes or removes it; the console's + model menu; `arithmetic` and `json-format` in `deploy/eval/`, carried in + the binary. Left: the suite of a model's standing gate is read by name + on the control plane at the time of the update, so two control planes + need the same `control.eval_dir`; a gated update needs room for one more + replica while it runs (there is no in-place gate, and a declared model + in server.yaml cannot be updated at all); no comparison against the old + weights' score (the gate is an absolute threshold, not "no worse than + before"); a run is not stopped once started (Esc in the console only + stops watching it), and the in-memory progress of a run lives on the + control plane that started it; runs are never pruned; the JSON Schema + support is a subset (no `$ref`, `oneOf`, `not`, `uniqueItems`); judge + cases go through the same concurrency as the model's, and a judge's + answers are not kept, only its score and reason; a gateway without a + control plane cannot run suites (there is no mode that asks through the + client API with a key). + **Eval harness (M).** `llmgw eval` extending `internal/bench` with quality suites gating `model update`. -22. **MIG (M–L).** Treat a MIG slice as a GPU class in +22. **Done (branch `features-c2`):** MIG instances discovered on both paths + (nvidia-smi `-L` + `-q -x`; NVML through an interface with a faithful + fake) and reported instead of their card, each with its MIG UUID, own + memory and class `-mig-`; device numbers 1000 + 100 + × card + instance, shown as `card/migN`; placement on MIG classes; + tp/pp/gpus/nodes above 1 on a MIG class refused in catalog validation + and again in placement; `CUDA_VISIBLE_DEVICES=MIG-` for vLLM and + llama.cpp (no Vulkan device variable on MIG); per-instance memory and + processes in heartbeats and the GPU check, card sensors under each + instance, utilisation absent rather than zero; doctor MIG findings (`mig + -lgi`/`-lci` parsed); `ctl nodes`, console, `ctl status`, `ctl model + plan`/`serve` by class; docs/install.md MIG section. Written and tested + against fakes only — untested on real MIG hardware. Left: run it on an + A100/H100 in MIG mode (check `-L`/`-q -x`/`mig -lgi`/`-lci` and NVML MIG + device names against the parsers, and that `CUDA_VISIBLE_DEVICES=MIG-…` + reaches vLLM's workers through Ray); instances changed while the agent + runs are only seen when it restarts (no rescan); llmgw does not create + or reshape instances (no mig-parted integration); quotas count an + instance as one GPU, the same as a whole card; SGLang on MIG not + checked; device numbers assume fewer than 100 instances per card and + that instance numbers stay put while shards run on them. + **MIG (M–L).** Treat a MIG slice as a GPU class in `agent/discovery/gpu_nvml.go` and `control/placement`. -23. **More engines (M each).** TensorRT-LLM/Triton adapter; Ollama/GGUF +23. **Done (branch `features-c2`):** engine `trtllm` + (`internal/agent/engines/trtllm.go`): `trtllm-serve` through a launcher + of llmgw's that demands the replica's key (trtllm-serve has none) and + writes the options file that turns on `/prometheus/metrics` and the + iteration statistics; the scrape contract for it + (`scrape.TRTLLMMapping`, with a per-engine metrics path); found, not + installed — `engines.trtllm.python` in `agent.yaml`, probed from the + package's metadata; catalog validation (GPU class, one node, no GGUF + source, the flags a profile may not give); `ctl engine-check trtllm`, + which asks `trtllm-serve serve --help` through its module. Ollama/GGUF + import: `mirror import-ollama` (manifest parsing, blob digest check, + projector beside the model, all or nothing, a model definition printed), + `mirror import` for any local file, and the console's **I** on the + Mirror view. Left: TensorRT-LLM has not run on real hardware — the first + node with one should run `engine-check` and serve a model before anyone + relies on it; no installer for it; no multi-node TensorRT-LLM replica + (it needs an MPI or Slurm launch from one node); Triton Inference Server + as an engine is not done; trtllm's queue gauges are set per iteration, + so an idle engine shows its last batch until the next request; + `--num_serve_frontends` is refused because extra front ends would not + demand the key. The Ollama import runs on the mirror machine only — the + mirror's API takes no files, so an Ollama elsewhere means copying the + blob or running the import there; Ollama models kept as separate tensors + or as several weight layers, and its LoRA adapters, are refused or left + with a sentence; files an import run with `sudo` writes are root's, as + `mirror add`'s are. + **More engines (M each).** TensorRT-LLM/Triton adapter; Ollama/GGUF import. `agent/engines/engine.go` interface and the metric contract in `router/scrape`. -24. Lower: precise KV-index routing (plan phase 6), LoRA affinity for +24. **Done (branch `features-c2`), all six parts.** Lower: precise KV-index routing (plan phase 6), LoRA affinity for vLLM, multi-cluster federation via External providers, facility-aware placement (`docs/facility-aware-placement.md`), portal i18n, SDK/docs portal. + What was built, and what is left: + - 24 (portal i18n): built — English/Turkish catalogue with fallback, per- + language templates, cookie/Accept-Language/`landing.language` choice + and a footer switcher, Turkish numbers and dates, every template and + handler message translated, tests that no template text stays English; + left — errors built with fmt.Errorf in other packages (store, catalog, + mirror, adminapi) still English on Turkish pages, percent sign + placement is mixed (%50 on limits, 93% on cluster pages), RFC3339 + footer timestamps and plain-text http.Error bodies untranslated, the + /docs documents themselves English, a per-person language column + (cookie only today). + - 24 (SDK/docs portal): built — /docs renders the embedded manual (goldmark, + GFM, heading anchors, links rewritten, no script; public, + `landing.docs_sign_in` to require a session), and docs/clients.md + shows the official OpenAI/Anthropic SDKs against llmgw. Left: the + console's generated "Commands" page is not in the portal (it is built + from the cobra tree, which internal/web cannot see); no search across + documents. + - [~] 24. Precise KV index (tier 2) — built: vLLM KV events via the agent + (loopback ZMQ, pure-Go zmq4, msgpack in both of vLLM's encodings) + forwarded as net block-hash changes over the agent stream; router + index, tokenize via the replica's `/tokenize`, sha256_cbor block-hash + chain checked against cbor2/hashlib golden values; scorer by leading- + block share with tier 1 fallback; opt-in `kv_events` per profile; + metrics; docs. Left: validation against a real vLLM (event shape, hash + agreement, `/tokenize` matching the served prompt, cost of + tokenizing); vLLM's replay endpoint instead of resetting on a gap; + data-parallel ranks (one publisher each, ports offset); hybrid models' + cache groups and CPU-offloaded blocks; LoRA/multimodal/cache_salt + requests (extra keys); a router-only deployment (no agents) + subscribing directly; standby control planes have no index until they + lead; a per-replica fallback when only some candidates have an index; + caching tokenizations of repeated prompts. + - **24 LoRA affinity (branch `features-c2`):** built `max_loaded_adapters` + (catalog), vLLM adapter support at start and on demand + (`engines/lora.go`, `vllm.go`), the agent linking fetched adapters as + `llmgw-lora/` in the engines' working directory, the router's + adapter tracker (`router/lora.go`: loads/unloads with the engine key, + LRU eviction never of an adapter in use, one load per adapter per + replica, `/v1/models` sync, 404 reload) and the `adapter-affinity` + scheduler filter in the chat, batch and long-context profiles, with + metrics and docs; tested against a fake of vLLM's HTTP interface. + **Left:** never run against a real vLLM — in particular that vLLM + resolves the relative `llmgw-lora/` path against its working + directory on every node (multi-node too) and that unloading an adapter + mid-request is harmless; the agent still fetches every adapter at + replica start, so a new adapter needs a restart (fetching on first + load would need an agent command and a proto change); load timeout and + resync interval are constants, not config; SGLang's runtime LoRA API + is not driven; no per-replica "adapters held" view in the console or + admin API; the debug profile has no affinity. + - 24. Multi-cluster federation — built: peers via `ctl federation` kept in + the store, their models as PEER/MODEL synced from /v1/models + (withdrawn-while-referenced), /ready health with latency and routing + withdrawal, `ctl model fallbacks` for overflow, hop header loop + refusal, residency/no_store hold, optional attribution tags, console + view, metrics, docs. Left: server.yaml-declared models cannot name a + peer model as a fallback (config catalog is validated before peers are + read); per-peer CA / mTLS for peers behind a private CA; transitive + federation (A→B→C models) deliberately not offered; latency is /ready + RTT only (no per-request peer TTFT used in routing or weighting); the + peer's adapters are not imported (listed as aliases); no console form + to add/remove peers (CLI only); key file must exist on every control + plane. + - 24 (facility) — built: location labels (`ctl label`, agent.yaml), + spreading across racks/PDUs, `keep_within`, held domains with drain + (`ctl facility hold/release`, kept in the store), power caps from + `facility.budgets` against declared/derived/measured draw, shown in + explain-placement, `ctl nodes`, `ctl facility`, the console and the + API. Left: temperature conditions with hysteresis and their + enforcement (steps 3–4), a Prometheus/DCIM source, power headroom as a + rack-levelling score, spreading multi-node replicas across racks, + `llmgw_domain_*` metrics and alerts (near cap, over cap, stale data), + shedding and tokens per watt (step 5), and a drained node's state + surviving a restart. --- diff --git a/CHANGELOG.md b/CHANGELOG.md index cf7b0f41..f56e9a95 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,7 +21,484 @@ is only released once its **exit criterion** is met, not when its code lands. Until v1.0.0 the minor version is the breaking one: configuration formats and Go APIs change between minors without a deprecation period. -## Unreleased +## v0.11.2 — 2026-10-05 + +### Routing by what each vLLM replica's cache holds + +- A vLLM profile can set `kv_events: true`. The agent then starts the engine + publishing its KV cache events (`--kv-events-config`) to a port on + 127.0.0.1 the agent listens on, with `--prefix-caching-hash-algo + sha256_cbor` and `PYTHONHASHSEED=1729`, so its block hashes can be + computed outside Python. The events never leave the node. +- The agent mirrors each engine's set of cached blocks and sends the net + changes up its existing stream to the control plane four times a second + (new `KVEvents` agent message), starting every new stream with a full + copy. Lost events (a gap in vLLM's sequence numbers), an engine restart or + `AllBlocksCleared` start a replica's index again; blocks offloaded to CPU, + remote ones and a hybrid model's second cache group are not indexed. +- The control plane passes them to the router's index, only for replicas + the sending node runs, and empties what a stream described when it closes. +- For a model with `kv_events`, the router asks one of its replicas to + tokenize the request (vLLM's `/tokenize`, with messages and tools, so the + chat template is applied exactly), hashes the tokens into blocks as vLLM + does, and scores replicas by the share of the prompt's leading blocks they + hold. The imbalance guard still applies. With no answer — no events yet, + an image, a cache salt, a LoRA adapter, a failed or slow tokenize — it falls + back to the approximate tree (`router.prefix`) or to load. +- The agent checks first blocks against llmgw's hashing; an engine that + hashes another way (a profile overriding the algorithm, a changed vLLM) is + reported in the agent's log and `llmgw_kv_index_problem`, and routed as + though it published nothing. +- New settings `router.kv_index.tokenize_timeout` (250ms), `min_blocks` (4) + and `max_blocks` (4096). New metrics `llmgw_kv_index_decisions_total` + (`kv_hit`, `kv_miss_min_load`, `load_balance_override`, + `fallback_no_index`, `fallback_unsupported`, `fallback_tokenize_failed`), + `llmgw_kv_index_tokenize_seconds`, `llmgw_kv_index_blocks`. +- Experimental: tested against vLLM's event format and hashing as its source + defines them, and against libzmq and msgspec publishing — not yet against a + running vLLM. + +### LoRA adapters on vLLM, loaded on demand + +- **vLLM models can carry adapters.** A PEFT adapter directory (a mirror + version ending in `/`, a path on the nodes, or a Hugging Face repository + id) is registered at start with `--enable-lora --lora-modules`, and a + request names it as its model, as on llama.cpp. `scale` applies on + llama.cpp only. SGLang and TensorRT-LLM profiles still refuse adapters. +- **`max_loaded_adapters: N` on a model** has each replica hold at most N of + its adapters. Replicas start holding none (vLLM with + `VLLM_ALLOW_RUNTIME_LORA_UPDATING=True` and `--max-loras N`, unless the + profile's args set their own). The router loads an adapter on a replica + through `/v1/load_lora_adapter` when a request first wants it there, and + unloads the least recently used one no request is running on to make room. + vLLM profiles only; llama.cpp keeps loading every adapter at start, since + llama-server can rescale an adapter it started with but not load another. +- **Adapter affinity:** a request for an adapter goes to a replica that has + it, or is loading it, while that replica is not saturated; otherwise to one + with room for another adapter; otherwise where load sends it — which is how + a busy adapter spreads to a second replica. Requests arriving during a load + wait for it instead of loading the adapter again. +- **Self-correcting:** each replica's `/v1/models` is read when the router + first meets it and every 30 seconds, so adapters loaded before a restart or + by another router are known; a 404 for an adapter the router thought loaded + loads it again and retries. An adapter vLLM refuses (not found, rank above + `--max-lora-rank`) fails the request with vLLM's reason, without trying it + on every replica. +- **Metrics:** `llmgw_adapter_affinity_total{model,result=hit|joined|loaded}`, + `llmgw_adapter_loads_total{model,outcome}`, + `llmgw_adapter_evictions_total{model,outcome}`. +- The admin API and `ctl model adapters` read the file as GGUF only for a + model with llama.cpp profiles. + +### Federating clusters: another llmgw cluster as a provider + +- `llmgw ctl federation add NAME --url URL --key-file FILE [--send-tags]` + makes another llmgw gateway a peer. It is checked first (its `/ready`, + timed, and its `/v1/models` with the key) and kept in the store (migration + 0029, `federation_peers`) with the models it offers. +- A peer's models join the catalog as `NAME/MODEL`, always prefixed, and + follow the peer's own list every `federation.interval` (10s). A model the + peer drops goes, unless a model here still falls back to it: then it is + kept withdrawn (in the catalog, sent nothing) until the fallback changes. + The peer's aliases and its own peers' models are not taken. +- A peer whose `/ready` fails, which refuses the key, or which does not answer + is taken out of routing until it answers again. `/ready` now counts only a + gateway's own endpoints, not its peers'. +- `llmgw ctl model fallbacks MODEL [FALLBACK...]` (and `PUT + /api/v1/models/{name}/fallbacks`) sets a runtime model's fallbacks, so + overflow can go to a peer's model. +- Requests to a peer carry `x-llmgw-hop` with the ids of the clusters they + have passed through (each cluster's id is kept in the store). A request that + comes back to a cluster is refused with 508 `federation_loop`, and a peer a + request came from is not sent it. +- The peer sees one key, this cluster's, and the request's `X-Request-Id`. + With `--send-tags`, also `x-llmgw-tags: federated_from=, + org=,team=,project=` (ids); off by default. +- In-cluster residency and `no_store` keep requests off peers, by name and as + fallbacks. Usage records the peer's model as served, and `peer:NAME/MODEL` + as the replica. +- `ctl federation list|remove|sync`, a Federation view in the console, + `llmgw_federation_peer_up`, `_latency_seconds` and `_models` metrics, admin + API `/api/v1/federation`, and a "Federating clusters" section in + docs/install.md. New `federation:` block in server.yaml (`name`, + `interval`). +- A response header the gateway already set (X-Request-Id, + x-llmgw-served-model) is no longer repeated from the upstream's. + +### Facility-aware placement: racks, PDUs, holds and power caps + +- **Where a node is**, from five labels: `llmgw.io/site`, `room`, `row`, + `rack` and `pdu` (a list, for a dual-fed rack), in `agent.yaml` or set from + the control plane with **`llmgw ctl label NODE key=value… [key-…]`**, which + is kept in the store (migration 0031, `node_labels`), wins over the agent's + labels, works before the node joins, and refuses a misspelt `llmgw.io/` key. + A node with no location places as before. +- **Replicas spread across racks and PDUs.** A model's next replica goes to a + node sharing no rack or PDU with its others when there is one: an ordering + above weights already on disk and bin packing, never a filter. +- **`keep_within: rack`** (or row, room, site) on a profile keeps a + multi-node replica's nodes in one such domain. +- **Holds.** **`llmgw ctl facility hold rack:r12-07 --reason … [--drain]`** + places nothing new in a rack, row, room, site or PDU; `--drain` also drains + its nodes. **`llmgw ctl facility release`** undoes both. Kept across + restarts (migration 0031, `facility_holds`). +- **Power caps.** `facility.budgets` in `server.yaml` gives a domain's + `cap_watts` and `other_watts`, with a `margin`; a replica's draw is the + profile's `power_watts`, or its cards at the power limit they report + (`gpu_watts` otherwise) and its cores at `cpu_core_watts`, with `node_watts` + per node. Use is the larger of reserved and measured, node by node; a shard + that would take a domain past its cap less the margin is refused, and a + multi-node replica's shards are counted together. Unknown draw never blocks. +- **Seen everywhere it matters.** `ctl explain-placement` names the held + domain or the kilowatts, and keeps the rejections of a replica that was + placed, so one in an unexpected rack says why. `ctl nodes` has LOCATION, + *ready, held* and `--domain`. **`llmgw ctl facility`** lists every domain + with nodes, use, limit, reserved, measured and holds. The console's Nodes + view has WHERE; a node's menu has **Location…** and **Hold rack…/Release**. + Admin API: `GET /api/v1/facility`, `POST /api/v1/facility/holds`, + `DELETE /api/v1/facility/holds/{domain}`, `POST /api/v1/nodes/{id}/labels`. +- Docs: `docs/facility-aware-placement.md` says what is built and where it + departs from the design; `docs/install.md` and `docs/console.md`. + +### SGLang measured, checked and benchmarked as itself + +- **Fixed:** the router read SGLang replicas with vLLM's metric names, and + SGLang was started without `--enable-metrics`, so it served no `/metrics` + at all: every scrape failed as though the replica were unreachable, quietly, + and requests were routed to it blind. SGLang is now started with + `--enable-metrics` and read in its own names — `sglang:num_running_reqs`, + `sglang:num_queue_reqs`, `sglang:token_usage` (the KV pool's fill), the + prompt and generation token counters and `sglang:num_requests_total`, as + 0.5.21 publishes them. +- **Fixed:** `llmgw ctl engine-check sglang` asked the interpreter for + `--help` and checked SGLang's flags against Python's. It now asks + `python -m sglang.launch_server --help`, in the environment SGLang was + installed into (or `--bin`). +- **Fixed:** SGLang was given `--tp`, which argparse accepts only as an + abbreviation of `--tp-size`; it is given `--tp-size`. +- **Fixed:** `llmgw ctl bench --metrics` read an engine's metrics with the + key given for `--target` — a client's key when the target is the gateway, + or none — so llama.cpp and TensorRT-LLM, which guard their metrics with the + engine's key, refused every read, and the run reported a queue depth of + zero and suggested no thresholds without saying why. The engine key is now + asked of the admin API for the replica at `--metrics`' address (or given + with the new `--metrics-key`); metrics that cannot be read — refused, or in + another engine's names than `--engine` — fail the run before any load, + saying why; and a step whose metrics went unread shows `-` and the reason + rather than zeros. + +### Reusing answers + +- **A response cache, per project, off until asked for.** `llmgw keys cache + --project P --ttl 1h` has the same request — same project, endpoint, + model by its catalog name, and body with `stream`, `stream_options`, + `user`, `metadata`, `store` and `service_tier` left out and its keys in + any order — answered from the gateway's memory instead of the model, for + the TTL. `--off` stops it; without either it says how it stands. The + console has it as **Cache answers…** on a project. +- **Only answers that come out the same are reused:** chat and completions + asked at temperature 0 or with a seed, and embeddings, rerank and score. + `--any` reuses sampled answers too. Only a whole 200 from the model asked + for is kept — not an error, a fallback's or a canary's answer, one a + guardrail changed or stopped, or one over `router.cache.max_entry_bytes`. +- **Streams both ways:** a streamed answer is kept put back together into + one completion (tool calls and reasoning included), and a kept answer is + streamed as chunks — with the usage chunk if the client asked — to a + client that streams. `/v1/messages` and `/v1/responses` get it too. +- **Headers:** `x-llmgw-cache: hit|miss|bypass` on every answer of a + project that reuses answers, `Age` on a hit. `Cache-Control: no-cache` + or `no-store`, or `x-llmgw-cache: no`, asks the model anew. +- **Policies still apply:** limits and the input guardrails run before the + cache is looked in, the output policy judges a reused answer as it would + a new one, and a request under `no_store` or continuing a stored + conversation is never served from it nor kept in it. A project's answers + are never looked up by another project's keys. +- **A hit costs nothing:** recorded as a 200 with no tokens and no cost, + marked `cache_hit` on the usage record (migration 0027), and shown by + `llmgw ctl request`; it counts towards the requests-per-minute limit only. +- **In memory only:** `router.cache.max_bytes` (128 MB) for all projects + together in each gateway process, least recently used dropped first; + nothing is written to the store. `llmgw_cache_requests_total{model,result}`, + `llmgw_cache_bytes` and `llmgw_cache_entries`. + +### Offline sites and Kubernetes + +- **Offline bundles.** `llmgw bundle create` (on any machine with internet) + collects what a cluster would otherwise download — llmgw's release for + each `--arch` with its signed checksums, every llama.cpp build for those + architectures (or the `--variant` ones) with the checksums GitHub + publishes, the starter model and guardrails' judge, and any `--model + name/version=hf:owner/repo/file` pinned to the registry's commit and its + checksum — each checked as it arrives, into a directory or one `.tar` + (`--tar`), with a manifest whose sha256 it prints to carry apart from the + bundle. Run again into the same directory, it downloads only what is + missing. `llmgw bundle show --verify` reads one back. +- **`llmgw bundle import`** checks every file against the manifest and + llmgw's release against the project's signing key, and only then puts them + into the mirror — releases and engines under `_llmgw/`, models where the + mirror keeps models, with their checksums — so a damaged bundle leaves the + mirror as it was; a different file under a version already there is + refused. On a control plane it also records the engines' checksums in + `offline.checksums` (`/etc/llmgw/offline.sha256`); `llmgw bundle trust` + does that alone, for a mirror on another machine. +- **`offline.mirror` in server.yaml** makes the cluster reach nothing + outside: nodes install llama.cpp from the mirror, each file held to the + checksum the control plane sends them over the agent's authenticated + connection — never one from the mirror — and `releases` defaults to the + mirror's copy, so `node add`, `ctl upgrade` and agents upgrading fetch + from it; no registry is asked about newer weights. A release may now come + over plain HTTP when the build trusts a signing key, since the signature + holds whatever carries it. vLLM and SGLang come from PyPI and are said to + be unsupported on an offline node rather than attempted. +- **`llmgw server init --bundle PATH --bundle-sha256 …`**, and the same two + fields on the setup form: installs a control plane offline — the bundle + into the mirror, the checksums trusted, `offline:` written to server.yaml, + the starter model and judge served from the bundle or skipped when it does + not carry them. +- `docs/data.md` no longer says only weights and `ctl plan` reach outside: + it lists everything that does, and what an offline cluster changes. +- **A Helm chart for the control plane** (`deploy/helm/llmgw`): one replica + in a StatefulSet, SQLite on a claim or an external PostgreSQL, the agent + port's certificate and the admin token from Secrets, the API and metrics + Service, a LoadBalancer for the agents' mutual TLS, an optional Ingress + and ServiceMonitor, `config` laid into server.yaml, and the offline + checksums from a ConfigMap; read-only root, non-root, ready on `/leader`. + `deploy/container/Dockerfile` builds the image it runs. GPU nodes stay + outside Kubernetes and join with `node add` (docs/kubernetes.md says why). + +### The admin API described, and a Terraform provider + +- **The admin API in OpenAPI 3.1.** Every endpoint under `/api/v1`, its path + and query parameters, and the schema of each request and answer with the + meaning of each field, in + [docs/admin-api.openapi.json](docs/admin-api.openapi.json) and served by + every control plane at `GET /api/v1/openapi.json` (with the token, like the + rest). The bearer token, the `X-Llmgw-Actor` header and the error shape are + in it. Generated by `go generate ./internal/docgen` from a route table in + `internal/control/adminapi/routes.go` and the Go types the handlers use, with + the fields' comments as descriptions; a test fails when an endpoint is + served and not in the table, another when the committed document is stale. + Checked with openapi-spec-validator and openapi-generator-cli's validate. +- **[docs/admin-api.md](docs/admin-api.md)**: how to reach the API (loopback, + an SSH tunnel, `admin_remote`), the token at `/var/lib/llmgw/admin-token`, + what a request must carry — an address in `Host`, `application/json` on + every change, even a `DELETE` — and some calls with `curl`. +- **`GET /api/v1/models/{name}`**: one model's whole definition as it is in + force, with the defaults the catalog filled in. The listing has only its + state and its profiles' names. +- **A Terraform provider**, in `terraform-provider-llmgw/`, a module of its + own so the gateway does not carry its dependencies. `llmgw_model` (a model + added at runtime: scaling, class, owner and adapters change in place, the + rest replaces it), `llmgw_quota`, `llmgw_guard_attachment`, and the + `llmgw_models` and `llmgw_nodes` data sources. Its client is checked + against the OpenAPI document, endpoint by endpoint and field by field, so a + change to the admin API that breaks it fails its tests; CI runs them. + Built and installed by hand for now: see its + [README](terraform-provider-llmgw/README.md). + +### Tracing beyond the router + +- **The control plane traces what it does to the fleet.** A reconcile pass + that does something is a `reconcile` trace — passes with nothing to do are + not traced at all — with what it did beneath it: `scale up` with `place` + (the profile, engine, GPU class, pool, fabric and nodes chosen, or every + candidate turned down and why, as `ctl explain-placement` would print it), + `scale down`, `drain replica` and `stop replica` each with its reason, + `evict`, `preempt` with its victims, `reap replica` with the error and + when the model is tried again, `restart replica`, `restart refused`, + `node unreachable` and `node lost`. +- **A replica's start is one trace, down to the node.** `replica start` + stays open from placement until the replica serves, fails or is stopped, + with each shard's progress as an event and how long it took. The command + to each node is a `send start` span whose context travels in the command + (a new `trace` field on the agent protocol's `ControlMessage`), and the + agent continues the same trace: `start shard`, with `fetch weights` + (local, cached, downloaded, or downloaded by another shard; a `download` + with its bytes and where a resume began, the source's credentials and + query left out), `launch engine` (and `wait for rendezvous` on a worker + of a multi-node replica), and `wait for engine` with how often the engine + was asked and its last answer. "Why did qwen take four minutes to start" + is that one trace. +- **Stops, drains and adoptions on a node** are in the control plane's + trace too: `stop shard` and `stop engine`, saying whether the engine had + to be killed; `drain shard`; and `adopt` when a registering node reports + engines already running, with how many nobody claimed. An engine install + is an `install engine` trace on the node. +- **Model jobs are traces.** `ctl model serve` and `ctl model update` are + `serve model` and `update model`, with a span per step — registry, + mirror, check, catalog, placement, smoke test, replicas — and from the + placement step a link to the replica's own start. +- **The agent has a `tracing` block** in `agent.yaml`, the same as + `server.yaml`'s (`endpoint`, `sample_ratio`; `OTEL_EXPORTER_OTLP_ENDPOINT` + when unset). Point both at one collector. A node follows the control + plane's sampling for every start it is sent. Traces from a node carry its + id as `service.instance.id`, and a control plane's its host name. +- With no endpoint nothing changes: every span is the no-op one, and a + command carries no trace context. + +### Quality suites, and new weights held to one + +- **`llmgw ctl eval MODEL --suite FILE|NAME`** asks a model a quality suite + and scores its answers: per case, then the cases weighed into one score, 0 + to 1, against the suite's `threshold` (or `--min-score`); it exits non-zero + below it. `--concurrency`, `--judge`, `--detach`, `--json`. + - **Suites** are YAML or JSON lines: a prompt or a conversation, a weight, + and one way to score it — `exact`, `contains`, `regex`, `number` within + a `tolerance` (the last number in the answer), `json_schema` (the answer + read as JSON, in a code fence or a sentence or not, held to a schema), or + `judge`: a rubric another model on the cluster grades 0 to 1. A + reasoning model's `` is not part of its answer. + - **Run on the control plane**, through the router as its own requests, + as a replay is: past admission, quotas, accounting and the guardrails. + `--suite` is a file sent whole, or a suite's name in `control.eval_dir` + (`/etc/llmgw/eval`) or built in: `arithmetic` and `json-format`, in + `deploy/eval/`, sized for small models. `--suites` lists them. + - **Kept** in the store (migration 0028): every run with its model, the + repository and revision of the weights that answered, the suite's name + and hash, its score and each case's answer and reason. + `llmgw ctl eval --history [MODEL]` lists them, `--run ID` shows one. +- **Updates and promotions held to a suite.** `llmgw ctl model update` and + `model promote` take `--eval SUITE --min-score N`, or a model carries one + (`llmgw ctl model gate MODEL --eval SUITE`, `eval:` in its definition). + A promotion asks the canary first and leaves it in place below the score; + an update runs the new weights first as a canary given none of the + model's requests, asks it, and promotes it or takes it out again, so the + old weights serve until the new have passed. The job's `eval` step says + the score; `--skip-eval` moves once without the model's suite. +- **The console** has **Ask it a quality suite…** (the score counted in as it + comes), **Its quality runs** and **Hold its updates to a quality suite…** + on a model's menu. +- **Fixed:** a change to the admin API with a body over 64 KiB reached its + handler cut off at 64 KiB, by the audit log's reading of it. + +### MIG instances as GPUs of their own class + +- **A card in MIG mode is placed as its instances.** Discovery reports a card + in MIG mode as its MIG instances instead of the whole card, each a device of + its own with its UUID (`MIG-…`), its own memory, and a class named from the + card's and the profile: two `3g.40gb` instances of an A100 80GB are two + devices of class `a100-80g-mig-3g.40gb`. A profile names that class like + any other, and placement puts a replica on a free instance of it. Both + discovery paths do it: nvidia-smi (instances from `nvidia-smi -L`, their + memory and ids from `nvidia-smi -q -x`) and NVML (`GetMigMode`, + `GetMaxMigDeviceCount`, `GetMigDeviceHandleByIndex`). llmgw does not create + instances; `docs/install.md` has a MIG section on making them. +- **One instance a replica.** A process opens only one MIG device, and + instances have no NVLink or peer-to-peer between them, so a profile on a + MIG class asking for more than one GPU, tp or pp above 1, or more than one + node is refused when the model is added, with that reason; placement + refuses it again. `ctl model plan` and `ctl model serve` plan an instance + for a model one holds and never several together. +- **Engines are given the instance by UUID.** Placement numbers card 0's + instance 2 as device 1002 (1000 + 100 × card + instance); the agent turns + that into `CUDA_VISIBLE_DEVICES=MIG-` for vLLM and llama.cpp, and + leaves `GGML_VK_VISIBLE_DEVICES` unset (Vulkan cannot see MIG). Every view + shows the device as `0/mig2`. +- **Memory per instance, no made-up utilisation.** Each instance's memory, + and the processes holding it, are its own — read per GPU and compute + instance from nvidia-smi's report, so a foreign process on one instance + keeps that instance out of placement and not its neighbours. Temperature, + power and wear are the card's. No driver reports utilisation per instance, + so none is published for one: the console says `n/a on MIG`, and + `llmgw_gpu_utilization_percent` has no series for it rather than a zero. +- **A card in MIG mode with nothing carved is kept out of placement**, with + the reason in `ctl nodes`, since CUDA will not open the whole card while MIG + is on. +- **`llmgw doctor` reports MIG**: each card's mode and instances, and warns + of a card in MIG mode with no instances, of GPU instances with no compute + instance, and of a mode change waiting for a reset, with the `nvidia-smi` + command for each. +- `ctl nodes` counts a node's devices by class when it has MIG instances or + more than one class (`a100-80g-mig-3g.40gb×2,a100-80g×1`); the console's + GPU list shows instances under their card with their own memory and the + card's heat and power, and a node's page lists its classes with counts. + `ctl status` and the plan count each device under its own class, where a + node's cards were all put under its first class before. +- The agent protocol's `GPU` gains `mig` (parent card, its memory, profile, + GPU and compute instance ids); the node API's GPUs gain `label`, `class`, + `card`, `mig_profile` and memory, and nodes gain `gpus_by_class`. + +### Engines and the mirror + +- **TensorRT-LLM as an engine** (`engine: trtllm`), on nodes where you + installed it: name its interpreter in the node's `agent.yaml` + (`engines.trtllm.python`) and the node offers it while that interpreter + has the `tensorrt_llm` package. llmgw does not install it. The agent starts + `trtllm-serve serve` with the replica's host, port, `--tp_size`, + `--pp_size` and served name, through a few lines of its own that make it + demand the gateway's key on every path but `/health` (trtllm-serve has no + key option), turn on the Prometheus endpoint and iteration statistics, and + keep usage reports to NVIDIA off. The router reads it at + `/prometheus/metrics` — `trtllm_num_requests_running`, + `trtllm_num_requests_waiting`, `trtllm_kv_cache_utilization`, tokens and + successes. Needs TensorRT-LLM 1.3 (rc13 or later) and an Ampere or newer + GPU; one node per replica. Profiles may not give it an options file, + `--trust_remote_code`, `--grpc`, `--num_serve_frontends` or the flags the + agent sets; `--set PATH=VALUE` changes a setting instead. `llmgw ctl + engine-check trtllm --bin ` checks an installed one. Written + against TensorRT-LLM's documented command line, server and metrics and + tested with stand-ins for them; not yet run on a datacenter GPU. +- **`llmgw mirror import-ollama [NAME[:TAG]]`** puts a model you already + have in Ollama into the mirror for llama.cpp: its GGUF, and a vision + model's projector beside it, each checked against the sha256 Ollama named + its file by. With no name it lists Ollama's models; it finds Ollama's + directory itself (`OLLAMA_MODELS`, `~/.ollama/models`, Ollama's Linux + service) or takes `--ollama-dir`. The version is the tag and the start of + the digest, since a tag moves in Ollama. It prints a model definition to + add, with Ollama's `num_ctx` as `--ctx-size`. The console's **Mirror** + view does the same with **I**, for the mirror beside the control plane. +- **`llmgw mirror import FILE... --model NAME`** copies files already on the + mirror machine into it the way a download is kept: whole or not at all, the + checksum beside it, a version never replaced, a `.gguf` checked to be one, + and `--sha256` checked when given. + +### The portal in Turkish + +- **The web portal speaks English and Turkish** — the landing page, sign-up + and sign-in, the account page and its editor setup, the claim page, chat, + the about page, and every administrators' page (cluster, nodes, NVLink and + fabrics, people, limits, usage, organizations, mirror, guardrails), and + the docs portal around its documents, which stay English. Flash + messages and form errors built by the server are translated too. +- **A switcher at the foot of every page** (English · Türkçe) remembers the + choice in a cookie; without one the browser's Accept-Language decides, and + without that the new `landing.language` (`en` or `tr`, empty is English). + An unknown code stops the server starting. `` and + Content-Language follow the page. +- **Figures and dates in the page's language**: a Turkish page writes + 1.234,5, 04.10.2026 and "3 saat önce"; chart tooltips name the day in + Turkish. Form values, CSS and SVG coordinates are unchanged. +- **Ready for more languages**: the catalogue is JSON under + `internal/web/locales//`, and a language is a directory. Tests refuse + a key a page uses that some language lacks, a translation with different + arguments from English, and any template text left in English — so a new + page cannot quietly ship English-only. +- Messages that come from the control plane and other packages (node + warnings, engine errors, store refusals) are still shown as written, in + English; the API, CLI and console are English. + +### Documentation + +- **A docs portal at /docs.** The manual the binary carries — the pages + `llmgw docs` prints and the console's Manual shows, the configuration + reference among them — rendered on the client port in the portal's own + look: a sidebar of the documents in reading order, the open one's sections + under it, a link on every heading, and links between documents kept inside + the portal (links to files that are not in the binary, such as `deploy/`, + go to the repository). No script on the page, so the Content-Security-Policy + has nothing to allow. Public by default, like the landing page; set + `landing.docs_sign_in: true` to send visitors to sign in first. Signed in, + the page carries the usual menu, which now has a **Docs** link. +- **A client developer's guide, `docs/clients.md`.** How to use llmgw from + the official OpenAI and Anthropic SDKs — there is no llmgw SDK, and none is + needed — in Python, TypeScript, Go and curl: the base URL and key, + streaming, tools, embeddings, the Responses API, batches, the Anthropic SDK + against `/v1/messages`, and what llmgw adds as headers (`x-llmgw-thread`, + `x-session-id`, metadata and `x-llmgw-tags`, `x-llmgw-variant`, + `/v1/memory`, `/mcp`), with the statuses a client meets. The portal's index + leads with it, and the landing page and the account page link to it. +- The console's Manual and the portal read one list of documents in one + order (`llmgw.Manual`), so the two cannot drift. ### Administration @@ -71,6 +548,129 @@ APIs change between minors without a deprecation period. - **Other ways in:** `GET /api/v1/usage/export` (CSV, or `format=json`) and **E** on the console's Usage view. +### Forgetting a person, and requests that stay in the cluster + +- **`llmgw users forget`** erases a person for a request to be forgotten: + their usage kept under a random pseudonym so totals stay true, their kept + requests, personal files, batches and limits deleted, their name taken out + of the audit log, the account removed. +- **`llmgw keys residency --project P --in-cluster`**: no model served by an + outside provider for the project's keys, asked for, as a fallback or as a + canary. +- Both are on the console's menus. + +### Secrets in Vault + +- **Secrets from Vault or the environment.** Every setting naming a secret's + file also takes `env:VARIABLE` or `vault:mount/path#field` (HashiCorp + Vault or OpenBao, KV v1 or v2; a token, AppRole, or VAULT_TOKEN). +- **The store's own secrets sealed** under `secrets.master_key`: Vault's + transit engine (`vault-transit:KEY`), or a 32-byte key read from a + reference. A store, or a backup of it, then does not hold what engine keys + are derived from. Values from before are sealed as they are next read. + +### Scaling by the clock + +- **`scaling.schedule`**: windows of the week with their own `min` and + `max` — more replicas through working hours, an on-demand model kept + loaded while people are at work — in `control.timezone`. +- **`scaling.prewarm`** opens a window early, so its replicas have loaded + when it starts. + +### Token-level timing, and admission by SLO + +- **Per-token metrics:** `llmgw_tpot_seconds`, `llmgw_inter_token_seconds` + and `llmgw_output_tokens_per_second` by model and pool, and TPOT and + tokens a second by tenant. +- **A model's `slo` counts in admission:** past its `ttft_p99` or + `tpot_p99` (the recent p99), it is treated as saturated, so the lower bands + wait. `llmgw_model_slo_seconds` and the `llmgw-slo` alerts make the + promise visible in Prometheus. + +### Restoring a backup, and copies off the machine + +- **`llmgw server restore ARCHIVE`** puts a backup back: checks it first + (whole, opens with `--identity`, not newer than this llmgw, where the store + goes), says so with `--dry-run`, then moves `/etc/llmgw` aside, restores it + with modes and owners, restores the store (SQLite, or PostgreSQL with + `pg_restore --clean`), and starts the server. A drill is in + docs/install.md. +- **`backup_copy_to`** copies each archive to a directory or over ssh as it + is written, keeping as many there as here; refused without + `backup_recipients`. +- Archives now record each file's owner by name, so a restore on another + machine gives the llmgw user its files back. + +### Anthropic's Messages API + +- **`/v1/messages`** (and `/v1/messages/count_tokens`) translated to chat + completions and back, streamed or not: text, images, tools and their + results, the system prompt, stop sequences. Claude Code and Anthropic's + SDKs reach the models here; the key may come in `x-api-key`. Errors come + back in Anthropic's shape. + +### More of OpenAI's API + +- **Responses:** `text.format` asks for structured output, `input_image` + sends images, and `previous_response_id` continues a conversation the + gateway keeps as a thread (for a project that keeps conversations). +- **Passed through:** `/v1/rerank` and `/v1/score` for vLLM's rerankers, and + `/v1/audio/transcriptions` and `/translations` as the multipart form came, + for an engine serving Whisper. +- **`/v1/moderations`** is answered by the guardrails' judge model. + +### Requests kept, and replayed + +- **A project can keep its requests and answers** (`llmgw keys requests + --project P --retain-hours N [--sample 0.05]`, or **Keep requests…** in the + console): what the model was sent, after redaction, and what the client + got. Off until asked; never under `no_store`; pruned hourly. +- **`llmgw ctl request ID --body`** shows one; **`--replay MODEL`** sends it + to another model and shows both answers. + +### Batches + +- **OpenAI's Batch and Files APIs.** `POST /v1/files` (purpose batch), + `POST /v1/batches`, and reading, listing, cancelling and deleting them, so + OpenAI's clients send batches here unchanged. + - **Serving:** each line goes as a request of the key that made the batch, + in the lowest admission band, a few at a time; rate limits are waited + out. Answers and failures are written to files kept 30 days. + - **Accounting:** each line is an ordinary usage record tagged + `batch=`. + - **Restarts:** answered lines are kept as they are answered, and any + gateway on the store carries a batch on under a lease. + - **Limits:** `router.batch` bounds the file, the lines and the + concurrency. Refused to a project under a `no_store` policy. + +### New weights tried on a share of the traffic first + +- **Canaries.** `llmgw ctl model canary MODEL --percent 10` fetches the newer + weights of a model's repository and runs them beside it as `MODEL-canary`, + given that share of its requests. + - **Routing:** a session stays on one side; `x-llmgw-variant` pins a + request to `canary` or `stable` and says which served it. Clients cannot + name the canary. + - **Rolled back by itself** when, over 50 of its requests or more, its + error rate is five points above the model's or its time to the first + token half again as long; `canary_rolled_back` is sent to the + notification webhooks. + - **Then:** `--percent` changes its share, `llmgw ctl model promote` + moves the model to it, `--abort` takes it out, and `llmgw ctl model + canaries` compares the two sides. All of it is also on the console's + model menu. + +### Requests can be tagged + +- **Tags and end users on every usage record.** OpenAI's `metadata` and the + `x-llmgw-tags` header (`feature=search, env=prod`) tag a request; OpenAI's + `user` field names the client's own end user. Both are kept with the + request's usage and shown by `llmgw ctl request`. Tags are not sent to the + engine. A malformed one is refused with 400. +- **Counted by tag, for the tags named.** `router.tag_labels` lists the tags + counted in `llmgw_tagged_requests_total` and `llmgw_tagged_tokens_total`, + the first 100 values of each apart and the rest as `other`. + ### A hardened install by default - **`server init` and the setup screens write a hardened configuration.** diff --git a/README.md b/README.md index 248b9696..d1be6041 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,19 @@ Since v0.11.0, not yet released (see [CHANGELOG.md](CHANGELOG.md), - **Notifications** — webhooks, signed or Slack-shaped, for a model parked, a node lost, a budget spent and new weights published (`notify.webhooks`, `ctl notify test`), and Alertmanager receiver templates. +- **Traffic and models** — request tags, canaries of new weights with + automatic rollback, quality suites gating updates, a response cache, + kept and replayed requests, batches, Anthropic's Messages API, more of + OpenAI's (structured output, images, rerank, audio, moderations), + scaling by the clock, SLO-aware admission, TensorRT-LLM, MIG, models + imported from Ollama, routing by what each vLLM replica's cache holds, + LoRA adapters loaded on demand, other llmgw clusters as providers, and + placement that knows racks, PDUs and power caps. +- **Operations** — `server restore` and off-machine backup copies, secrets + in Vault, forgetting a person and keeping a project's requests in the + cluster, offline installs from a bundle, a Helm chart, tracing from the + control plane to the engines, the admin API in OpenAPI with a Terraform + provider, and the portal in English and Turkish with its docs at /docs. Every one of these is in the console as well as on the command line: [docs/console.md](docs/console.md). @@ -95,6 +108,8 @@ Every page is also in the binary: `llmgw docs`, or **Manual** in the console. the firewall, upgrades, backups - [docs/node-onboarding.md](docs/node-onboarding.md) — adding nodes to a cluster that exists +- [docs/kubernetes.md](docs/kubernetes.md) — the control plane on + Kubernetes with the Helm chart, and why GPU nodes stay outside it - [docs/fabrics.md](docs/fabrics.md) — InfiniBand fabrics and NVLink: what llmgw needs of them, checking a node with `llmgw doctor`, and what to look at when a replica spanning nodes will not run @@ -105,6 +120,8 @@ Every page is also in the binary: `llmgw docs`, or **Manual** in the console. every view, and the command each of its actions runs - [docs/onboarding.md](docs/onboarding.md) — accounts, keys, limits, staff roles and single sign-on +- [docs/clients.md](docs/clients.md) — using the gateway from code with the + official OpenAI and Anthropic SDKs, and llmgw's extensions - [docs/guardrails.md](docs/guardrails.md) — checking requests and answers: policies, detectors, a judge model, and where each applies - [docs/choosing-models.md](docs/choosing-models.md) — which models to run, @@ -117,6 +134,9 @@ Every page is also in the binary: `llmgw docs`, or **Manual** in the console. does not exist or miss one that does - [docs/data.md](docs/data.md) — what llmgw stores, what it does not, and what leaves the machine; written for a security review +- [docs/admin-api.md](docs/admin-api.md) and its OpenAPI document — the + admin API, for scripts; [terraform-provider-llmgw/](terraform-provider-llmgw/) + manages models, quotas and guardrails with Terraform or OpenTofu - [deploy/](deploy/) — [a mirror](deploy/mirror/) on its own machine, [Caddy and nginx](deploy/proxy/) in front of the client port, [two control planes](deploy/ha/) behind a balancer, and [Prometheus, Alertmanager and diff --git a/api/gen/llmgw/v1/agent.pb.go b/api/gen/llmgw/v1/agent.pb.go index d26030c2..32aed9e8 100644 --- a/api/gen/llmgw/v1/agent.pb.go +++ b/api/gen/llmgw/v1/agent.pb.go @@ -90,7 +90,7 @@ func (x ShardStatus_State) Number() protoreflect.EnumNumber { // Deprecated: Use ShardStatus_State.Descriptor instead. func (ShardStatus_State) EnumDescriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{21, 0} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{23, 0} } // AgentMessage is anything a node tells the control plane. @@ -105,6 +105,7 @@ type AgentMessage struct { // *AgentMessage_FabricScan // *AgentMessage_FabricTest // *AgentMessage_Upgrade + // *AgentMessage_KvEvents Msg isAgentMessage_Msg `protobuf_oneof:"msg"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache @@ -210,6 +211,15 @@ func (x *AgentMessage) GetUpgrade() *UpgradeReply { return nil } +func (x *AgentMessage) GetKvEvents() *KVEvents { + if x != nil { + if x, ok := x.Msg.(*AgentMessage_KvEvents); ok { + return x.KvEvents + } + } + return nil +} + type isAgentMessage_Msg interface { isAgentMessage_Msg() } @@ -242,6 +252,10 @@ type AgentMessage_Upgrade struct { Upgrade *UpgradeReply `protobuf:"bytes,7,opt,name=upgrade,proto3,oneof"` } +type AgentMessage_KvEvents struct { + KvEvents *KVEvents `protobuf:"bytes,8,opt,name=kv_events,json=kvEvents,proto3,oneof"` +} + func (*AgentMessage_Register) isAgentMessage_Msg() {} func (*AgentMessage_Heartbeat) isAgentMessage_Msg() {} @@ -256,6 +270,109 @@ func (*AgentMessage_FabricTest) isAgentMessage_Msg() {} func (*AgentMessage_Upgrade) isAgentMessage_Msg() {} +func (*AgentMessage_KvEvents) isAgentMessage_Msg() {} + +// KVEvents is a change to what one vLLM replica's prefix cache holds, read +// by the agent from the engine's KV cache events and sent on for the router's +// precise index (plan §7.5 tier 2). +// +// A net effect since the last one, not the events themselves: a block stored +// and evicted between two sends is not worth the bytes. On every new stream +// the agent first sends each replica in full, with clear_first set, because a +// control plane that has just started or taken over knows nothing. +type KVEvents struct { + state protoimpl.MessageState `protogen:"open.v1"` + ReplicaId string `protobuf:"bytes,1,opt,name=replica_id,json=replicaId,proto3" json:"replica_id,omitempty"` + // block_size is how many tokens make one of the replica's blocks. + BlockSize int32 `protobuf:"varint,2,opt,name=block_size,json=blockSize,proto3" json:"block_size,omitempty"` + // clear_first says to forget what was known of the replica before applying the + // rest: its cache was cleared, its engine restarted, events were lost, or + // this is the first piece of a full copy. + ClearFirst bool `protobuf:"varint,3,opt,name=clear_first,json=clearFirst,proto3" json:"clear_first,omitempty"` + // stored and removed are block hashes as vLLM publishes them: the low 64 + // bits of the sha256_cbor digest. + Stored []uint64 `protobuf:"fixed64,4,rep,packed,name=stored,proto3" json:"stored,omitempty"` + Removed []uint64 `protobuf:"fixed64,5,rep,packed,name=removed,proto3" json:"removed,omitempty"` + // problem, when set, is why the replica's events cannot be used — most + // likely an engine hashing another way than llmgw configured. Its index is + // empty while it stands. + Problem string `protobuf:"bytes,6,opt,name=problem,proto3" json:"problem,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *KVEvents) Reset() { + *x = KVEvents{} + mi := &file_llmgw_v1_agent_proto_msgTypes[1] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *KVEvents) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*KVEvents) ProtoMessage() {} + +func (x *KVEvents) ProtoReflect() protoreflect.Message { + mi := &file_llmgw_v1_agent_proto_msgTypes[1] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use KVEvents.ProtoReflect.Descriptor instead. +func (*KVEvents) Descriptor() ([]byte, []int) { + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{1} +} + +func (x *KVEvents) GetReplicaId() string { + if x != nil { + return x.ReplicaId + } + return "" +} + +func (x *KVEvents) GetBlockSize() int32 { + if x != nil { + return x.BlockSize + } + return 0 +} + +func (x *KVEvents) GetClearFirst() bool { + if x != nil { + return x.ClearFirst + } + return false +} + +func (x *KVEvents) GetStored() []uint64 { + if x != nil { + return x.Stored + } + return nil +} + +func (x *KVEvents) GetRemoved() []uint64 { + if x != nil { + return x.Removed + } + return nil +} + +func (x *KVEvents) GetProblem() string { + if x != nil { + return x.Problem + } + return "" +} + // ControlMessage is anything the control plane tells a node. type ControlMessage struct { state protoimpl.MessageState `protogen:"open.v1"` @@ -272,14 +389,20 @@ type ControlMessage struct { // *ControlMessage_FabricTest // *ControlMessage_Upgrade // *ControlMessage_ControlPlanes - Msg isControlMessage_Msg `protobuf_oneof:"msg"` + Msg isControlMessage_Msg `protobuf_oneof:"msg"` + // trace is the W3C trace context (traceparent, and tracestate when there + // is one) of the control plane's span that sent this command, so what the + // agent does for it — fetching weights, launching the engine, waiting for + // it to answer — lands in the same trace. Empty when the control plane is + // not tracing, and ignored by an agent that is not. + Trace map[string]string `protobuf:"bytes,12,rep,name=trace,proto3" json:"trace,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache } func (x *ControlMessage) Reset() { *x = ControlMessage{} - mi := &file_llmgw_v1_agent_proto_msgTypes[1] + mi := &file_llmgw_v1_agent_proto_msgTypes[2] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -291,7 +414,7 @@ func (x *ControlMessage) String() string { func (*ControlMessage) ProtoMessage() {} func (x *ControlMessage) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[1] + mi := &file_llmgw_v1_agent_proto_msgTypes[2] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -304,7 +427,7 @@ func (x *ControlMessage) ProtoReflect() protoreflect.Message { // Deprecated: Use ControlMessage.ProtoReflect.Descriptor instead. func (*ControlMessage) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{1} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{2} } func (x *ControlMessage) GetMsg() isControlMessage_Msg { @@ -413,6 +536,13 @@ func (x *ControlMessage) GetControlPlanes() *ControlPlanes { return nil } +func (x *ControlMessage) GetTrace() map[string]string { + if x != nil { + return x.Trace + } + return nil +} + type isControlMessage_Msg interface { isControlMessage_Msg() } @@ -496,7 +626,7 @@ type ControlPlanes struct { func (x *ControlPlanes) Reset() { *x = ControlPlanes{} - mi := &file_llmgw_v1_agent_proto_msgTypes[2] + mi := &file_llmgw_v1_agent_proto_msgTypes[3] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -508,7 +638,7 @@ func (x *ControlPlanes) String() string { func (*ControlPlanes) ProtoMessage() {} func (x *ControlPlanes) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[2] + mi := &file_llmgw_v1_agent_proto_msgTypes[3] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -521,7 +651,7 @@ func (x *ControlPlanes) ProtoReflect() protoreflect.Message { // Deprecated: Use ControlPlanes.ProtoReflect.Descriptor instead. func (*ControlPlanes) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{2} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{3} } func (x *ControlPlanes) GetServers() []string { @@ -621,7 +751,7 @@ type Register struct { func (x *Register) Reset() { *x = Register{} - mi := &file_llmgw_v1_agent_proto_msgTypes[3] + mi := &file_llmgw_v1_agent_proto_msgTypes[4] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -633,7 +763,7 @@ func (x *Register) String() string { func (*Register) ProtoMessage() {} func (x *Register) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[3] + mi := &file_llmgw_v1_agent_proto_msgTypes[4] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -646,7 +776,7 @@ func (x *Register) ProtoReflect() protoreflect.Message { // Deprecated: Use Register.ProtoReflect.Descriptor instead. func (*Register) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{3} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{4} } func (x *Register) GetNodeId() string { @@ -798,7 +928,7 @@ type Host struct { func (x *Host) Reset() { *x = Host{} - mi := &file_llmgw_v1_agent_proto_msgTypes[4] + mi := &file_llmgw_v1_agent_proto_msgTypes[5] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -810,7 +940,7 @@ func (x *Host) String() string { func (*Host) ProtoMessage() {} func (x *Host) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[4] + mi := &file_llmgw_v1_agent_proto_msgTypes[5] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -823,7 +953,7 @@ func (x *Host) ProtoReflect() protoreflect.Message { // Deprecated: Use Host.ProtoReflect.Descriptor instead. func (*Host) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{4} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{5} } func (x *Host) GetOsId() string { @@ -890,7 +1020,7 @@ type Storage struct { func (x *Storage) Reset() { *x = Storage{} - mi := &file_llmgw_v1_agent_proto_msgTypes[5] + mi := &file_llmgw_v1_agent_proto_msgTypes[6] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -902,7 +1032,7 @@ func (x *Storage) String() string { func (*Storage) ProtoMessage() {} func (x *Storage) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[5] + mi := &file_llmgw_v1_agent_proto_msgTypes[6] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -915,7 +1045,7 @@ func (x *Storage) ProtoReflect() protoreflect.Message { // Deprecated: Use Storage.ProtoReflect.Descriptor instead. func (*Storage) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{5} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{6} } func (x *Storage) GetPath() string { @@ -982,7 +1112,7 @@ type RunningShard struct { func (x *RunningShard) Reset() { *x = RunningShard{} - mi := &file_llmgw_v1_agent_proto_msgTypes[6] + mi := &file_llmgw_v1_agent_proto_msgTypes[7] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -994,7 +1124,7 @@ func (x *RunningShard) String() string { func (*RunningShard) ProtoMessage() {} func (x *RunningShard) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[6] + mi := &file_llmgw_v1_agent_proto_msgTypes[7] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -1007,7 +1137,7 @@ func (x *RunningShard) ProtoReflect() protoreflect.Message { // Deprecated: Use RunningShard.ProtoReflect.Descriptor instead. func (*RunningShard) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{6} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{7} } func (x *RunningShard) GetReplicaId() string { @@ -1149,13 +1279,18 @@ type GPU struct { ClusterUuid string `protobuf:"bytes,19,opt,name=cluster_uuid,json=clusterUuid,proto3" json:"cluster_uuid,omitempty"` CliqueId string `protobuf:"bytes,20,opt,name=clique_id,json=cliqueId,proto3" json:"clique_id,omitempty"` FabricBandwidth string `protobuf:"bytes,21,opt,name=fabric_bandwidth,json=fabricBandwidth,proto3" json:"fabric_bandwidth,omitempty"` - unknownFields protoimpl.UnknownFields - sizeCache protoimpl.SizeCache + // mig is set when this is a MIG instance rather than a whole card. index + // is then 1000 + 100 × card + device, uuid the instance's (MIG-…), and + // memory the instance's share; utilization_percent stays zero, because no + // driver measures it per instance. + Mig *MIGDevice `protobuf:"bytes,22,opt,name=mig,proto3" json:"mig,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache } func (x *GPU) Reset() { *x = GPU{} - mi := &file_llmgw_v1_agent_proto_msgTypes[7] + mi := &file_llmgw_v1_agent_proto_msgTypes[8] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -1167,7 +1302,7 @@ func (x *GPU) String() string { func (*GPU) ProtoMessage() {} func (x *GPU) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[7] + mi := &file_llmgw_v1_agent_proto_msgTypes[8] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -1180,7 +1315,7 @@ func (x *GPU) ProtoReflect() protoreflect.Message { // Deprecated: Use GPU.ProtoReflect.Descriptor instead. func (*GPU) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{7} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{8} } func (x *GPU) GetIndex() int32 { @@ -1330,6 +1465,109 @@ func (x *GPU) GetFabricBandwidth() string { return "" } +func (x *GPU) GetMig() *MIGDevice { + if x != nil { + return x.Mig + } + return nil +} + +// MIGDevice is which card a MIG instance is carved from, and how. +type MIGDevice struct { + state protoimpl.MessageState `protogen:"open.v1"` + ParentIndex int32 `protobuf:"varint,1,opt,name=parent_index,json=parentIndex,proto3" json:"parent_index,omitempty"` + ParentUuid string `protobuf:"bytes,2,opt,name=parent_uuid,json=parentUuid,proto3" json:"parent_uuid,omitempty"` + // parent_memory_total_mb is the whole card's: the class is named from it. + ParentMemoryTotalMb int32 `protobuf:"varint,3,opt,name=parent_memory_total_mb,json=parentMemoryTotalMb,proto3" json:"parent_memory_total_mb,omitempty"` + // device is the instance's number on its card, as nvidia-smi -L lists it. + Device int32 `protobuf:"varint,4,opt,name=device,proto3" json:"device,omitempty"` + // profile is NVIDIA's name for the slice, like 3g.40gb. + Profile string `protobuf:"bytes,5,opt,name=profile,proto3" json:"profile,omitempty"` + GpuInstance int32 `protobuf:"varint,6,opt,name=gpu_instance,json=gpuInstance,proto3" json:"gpu_instance,omitempty"` + ComputeInstance int32 `protobuf:"varint,7,opt,name=compute_instance,json=computeInstance,proto3" json:"compute_instance,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *MIGDevice) Reset() { + *x = MIGDevice{} + mi := &file_llmgw_v1_agent_proto_msgTypes[9] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *MIGDevice) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*MIGDevice) ProtoMessage() {} + +func (x *MIGDevice) ProtoReflect() protoreflect.Message { + mi := &file_llmgw_v1_agent_proto_msgTypes[9] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use MIGDevice.ProtoReflect.Descriptor instead. +func (*MIGDevice) Descriptor() ([]byte, []int) { + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{9} +} + +func (x *MIGDevice) GetParentIndex() int32 { + if x != nil { + return x.ParentIndex + } + return 0 +} + +func (x *MIGDevice) GetParentUuid() string { + if x != nil { + return x.ParentUuid + } + return "" +} + +func (x *MIGDevice) GetParentMemoryTotalMb() int32 { + if x != nil { + return x.ParentMemoryTotalMb + } + return 0 +} + +func (x *MIGDevice) GetDevice() int32 { + if x != nil { + return x.Device + } + return 0 +} + +func (x *MIGDevice) GetProfile() string { + if x != nil { + return x.Profile + } + return "" +} + +func (x *MIGDevice) GetGpuInstance() int32 { + if x != nil { + return x.GpuInstance + } + return 0 +} + +func (x *MIGDevice) GetComputeInstance() int32 { + if x != nil { + return x.ComputeInstance + } + return 0 +} + type FabricAttachment struct { state protoimpl.MessageState `protogen:"open.v1"` // fabric is the operator-assigned name. It is not derived from the GID @@ -1344,7 +1582,7 @@ type FabricAttachment struct { func (x *FabricAttachment) Reset() { *x = FabricAttachment{} - mi := &file_llmgw_v1_agent_proto_msgTypes[8] + mi := &file_llmgw_v1_agent_proto_msgTypes[10] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -1356,7 +1594,7 @@ func (x *FabricAttachment) String() string { func (*FabricAttachment) ProtoMessage() {} func (x *FabricAttachment) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[8] + mi := &file_llmgw_v1_agent_proto_msgTypes[10] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -1369,7 +1607,7 @@ func (x *FabricAttachment) ProtoReflect() protoreflect.Message { // Deprecated: Use FabricAttachment.ProtoReflect.Descriptor instead. func (*FabricAttachment) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{8} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{10} } func (x *FabricAttachment) GetFabric() string { @@ -1411,7 +1649,7 @@ type LocalWeights struct { func (x *LocalWeights) Reset() { *x = LocalWeights{} - mi := &file_llmgw_v1_agent_proto_msgTypes[9] + mi := &file_llmgw_v1_agent_proto_msgTypes[11] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -1423,7 +1661,7 @@ func (x *LocalWeights) String() string { func (*LocalWeights) ProtoMessage() {} func (x *LocalWeights) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[9] + mi := &file_llmgw_v1_agent_proto_msgTypes[11] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -1436,7 +1674,7 @@ func (x *LocalWeights) ProtoReflect() protoreflect.Message { // Deprecated: Use LocalWeights.ProtoReflect.Descriptor instead. func (*LocalWeights) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{9} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{11} } func (x *LocalWeights) GetPath() string { @@ -1492,7 +1730,7 @@ type NodeLoad struct { func (x *NodeLoad) Reset() { *x = NodeLoad{} - mi := &file_llmgw_v1_agent_proto_msgTypes[10] + mi := &file_llmgw_v1_agent_proto_msgTypes[12] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -1504,7 +1742,7 @@ func (x *NodeLoad) String() string { func (*NodeLoad) ProtoMessage() {} func (x *NodeLoad) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[10] + mi := &file_llmgw_v1_agent_proto_msgTypes[12] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -1517,7 +1755,7 @@ func (x *NodeLoad) ProtoReflect() protoreflect.Message { // Deprecated: Use NodeLoad.ProtoReflect.Descriptor instead. func (*NodeLoad) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{10} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{12} } func (x *NodeLoad) GetCpuPercent() float64 { @@ -1650,7 +1888,7 @@ type GPUSensor struct { func (x *GPUSensor) Reset() { *x = GPUSensor{} - mi := &file_llmgw_v1_agent_proto_msgTypes[11] + mi := &file_llmgw_v1_agent_proto_msgTypes[13] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -1662,7 +1900,7 @@ func (x *GPUSensor) String() string { func (*GPUSensor) ProtoMessage() {} func (x *GPUSensor) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[11] + mi := &file_llmgw_v1_agent_proto_msgTypes[13] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -1675,7 +1913,7 @@ func (x *GPUSensor) ProtoReflect() protoreflect.Message { // Deprecated: Use GPUSensor.ProtoReflect.Descriptor instead. func (*GPUSensor) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{11} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{13} } func (x *GPUSensor) GetIndex() int32 { @@ -1889,7 +2127,7 @@ type ShardLoad struct { func (x *ShardLoad) Reset() { *x = ShardLoad{} - mi := &file_llmgw_v1_agent_proto_msgTypes[12] + mi := &file_llmgw_v1_agent_proto_msgTypes[14] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -1901,7 +2139,7 @@ func (x *ShardLoad) String() string { func (*ShardLoad) ProtoMessage() {} func (x *ShardLoad) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[12] + mi := &file_llmgw_v1_agent_proto_msgTypes[14] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -1914,7 +2152,7 @@ func (x *ShardLoad) ProtoReflect() protoreflect.Message { // Deprecated: Use ShardLoad.ProtoReflect.Descriptor instead. func (*ShardLoad) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{12} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{14} } func (x *ShardLoad) GetShardId() string { @@ -1982,7 +2220,7 @@ type IBPort struct { func (x *IBPort) Reset() { *x = IBPort{} - mi := &file_llmgw_v1_agent_proto_msgTypes[13] + mi := &file_llmgw_v1_agent_proto_msgTypes[15] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -1994,7 +2232,7 @@ func (x *IBPort) String() string { func (*IBPort) ProtoMessage() {} func (x *IBPort) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[13] + mi := &file_llmgw_v1_agent_proto_msgTypes[15] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -2007,7 +2245,7 @@ func (x *IBPort) ProtoReflect() protoreflect.Message { // Deprecated: Use IBPort.ProtoReflect.Descriptor instead. func (*IBPort) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{13} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{15} } func (x *IBPort) GetHca() string { @@ -2150,7 +2388,7 @@ type SubnetManager struct { func (x *SubnetManager) Reset() { *x = SubnetManager{} - mi := &file_llmgw_v1_agent_proto_msgTypes[14] + mi := &file_llmgw_v1_agent_proto_msgTypes[16] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -2162,7 +2400,7 @@ func (x *SubnetManager) String() string { func (*SubnetManager) ProtoMessage() {} func (x *SubnetManager) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[14] + mi := &file_llmgw_v1_agent_proto_msgTypes[16] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -2175,7 +2413,7 @@ func (x *SubnetManager) ProtoReflect() protoreflect.Message { // Deprecated: Use SubnetManager.ProtoReflect.Descriptor instead. func (*SubnetManager) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{14} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{16} } func (x *SubnetManager) GetGuid() string { @@ -2218,7 +2456,7 @@ type IMEX struct { func (x *IMEX) Reset() { *x = IMEX{} - mi := &file_llmgw_v1_agent_proto_msgTypes[15] + mi := &file_llmgw_v1_agent_proto_msgTypes[17] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -2230,7 +2468,7 @@ func (x *IMEX) String() string { func (*IMEX) ProtoMessage() {} func (x *IMEX) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[15] + mi := &file_llmgw_v1_agent_proto_msgTypes[17] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -2243,7 +2481,7 @@ func (x *IMEX) ProtoReflect() protoreflect.Message { // Deprecated: Use IMEX.ProtoReflect.Descriptor instead. func (*IMEX) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{15} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{17} } func (x *IMEX) GetState() string { @@ -2275,7 +2513,7 @@ type GPUFabricState struct { func (x *GPUFabricState) Reset() { *x = GPUFabricState{} - mi := &file_llmgw_v1_agent_proto_msgTypes[16] + mi := &file_llmgw_v1_agent_proto_msgTypes[18] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -2287,7 +2525,7 @@ func (x *GPUFabricState) String() string { func (*GPUFabricState) ProtoMessage() {} func (x *GPUFabricState) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[16] + mi := &file_llmgw_v1_agent_proto_msgTypes[18] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -2300,7 +2538,7 @@ func (x *GPUFabricState) ProtoReflect() protoreflect.Message { // Deprecated: Use GPUFabricState.ProtoReflect.Descriptor instead. func (*GPUFabricState) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{16} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{18} } func (x *GPUFabricState) GetIndex() int32 { @@ -2415,7 +2653,7 @@ type Heartbeat struct { func (x *Heartbeat) Reset() { *x = Heartbeat{} - mi := &file_llmgw_v1_agent_proto_msgTypes[17] + mi := &file_llmgw_v1_agent_proto_msgTypes[19] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -2427,7 +2665,7 @@ func (x *Heartbeat) String() string { func (*Heartbeat) ProtoMessage() {} func (x *Heartbeat) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[17] + mi := &file_llmgw_v1_agent_proto_msgTypes[19] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -2440,7 +2678,7 @@ func (x *Heartbeat) ProtoReflect() protoreflect.Message { // Deprecated: Use Heartbeat.ProtoReflect.Descriptor instead. func (*Heartbeat) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{17} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{19} } func (x *Heartbeat) GetNodeId() string { @@ -2595,7 +2833,7 @@ type Provision struct { func (x *Provision) Reset() { *x = Provision{} - mi := &file_llmgw_v1_agent_proto_msgTypes[18] + mi := &file_llmgw_v1_agent_proto_msgTypes[20] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -2607,7 +2845,7 @@ func (x *Provision) String() string { func (*Provision) ProtoMessage() {} func (x *Provision) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[18] + mi := &file_llmgw_v1_agent_proto_msgTypes[20] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -2620,7 +2858,7 @@ func (x *Provision) ProtoReflect() protoreflect.Message { // Deprecated: Use Provision.ProtoReflect.Descriptor instead. func (*Provision) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{18} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{20} } func (x *Provision) GetEngines() []*EngineWant { @@ -2637,14 +2875,23 @@ type EngineWant struct { Version string `protobuf:"bytes,2,opt,name=version,proto3" json:"version,omitempty"` // "b10991" // variant is the build to install, when one is chosen for the node rather // than left to its hardware: "cu13", "cu129". Empty is the agent's choice. - Variant string `protobuf:"bytes,3,opt,name=variant,proto3" json:"variant,omitempty"` + Variant string `protobuf:"bytes,3,opt,name=variant,proto3" json:"variant,omitempty"` + // offline_base, on a cluster with no way to the internet, is where this + // engine version's files are on its mirror: + // http://mirror:8081/_llmgw/engines/llamacpp/b10991. Set, the node never + // asks the engine's publisher. + OfflineBase string `protobuf:"bytes,4,opt,name=offline_base,json=offlineBase,proto3" json:"offline_base,omitempty"` + // offline_sha256 is each of those files' checksum by name, from the + // bundle the control plane trusts — not from the mirror, which serves + // every node over plain HTTP. + OfflineSha256 map[string]string `protobuf:"bytes,5,rep,name=offline_sha256,json=offlineSha256,proto3" json:"offline_sha256,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache } func (x *EngineWant) Reset() { *x = EngineWant{} - mi := &file_llmgw_v1_agent_proto_msgTypes[19] + mi := &file_llmgw_v1_agent_proto_msgTypes[21] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -2656,7 +2903,7 @@ func (x *EngineWant) String() string { func (*EngineWant) ProtoMessage() {} func (x *EngineWant) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[19] + mi := &file_llmgw_v1_agent_proto_msgTypes[21] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -2669,7 +2916,7 @@ func (x *EngineWant) ProtoReflect() protoreflect.Message { // Deprecated: Use EngineWant.ProtoReflect.Descriptor instead. func (*EngineWant) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{19} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{21} } func (x *EngineWant) GetEngine() string { @@ -2693,6 +2940,20 @@ func (x *EngineWant) GetVariant() string { return "" } +func (x *EngineWant) GetOfflineBase() string { + if x != nil { + return x.OfflineBase + } + return "" +} + +func (x *EngineWant) GetOfflineSha256() map[string]string { + if x != nil { + return x.OfflineSha256 + } + return nil +} + // ProvisionStatus is where one engine's installation stands on a node. type ProvisionStatus struct { state protoimpl.MessageState `protogen:"open.v1"` @@ -2709,7 +2970,7 @@ type ProvisionStatus struct { func (x *ProvisionStatus) Reset() { *x = ProvisionStatus{} - mi := &file_llmgw_v1_agent_proto_msgTypes[20] + mi := &file_llmgw_v1_agent_proto_msgTypes[22] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -2721,7 +2982,7 @@ func (x *ProvisionStatus) String() string { func (*ProvisionStatus) ProtoMessage() {} func (x *ProvisionStatus) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[20] + mi := &file_llmgw_v1_agent_proto_msgTypes[22] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -2734,7 +2995,7 @@ func (x *ProvisionStatus) ProtoReflect() protoreflect.Message { // Deprecated: Use ProvisionStatus.ProtoReflect.Descriptor instead. func (*ProvisionStatus) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{20} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{22} } func (x *ProvisionStatus) GetEngine() string { @@ -2798,7 +3059,7 @@ type ShardStatus struct { func (x *ShardStatus) Reset() { *x = ShardStatus{} - mi := &file_llmgw_v1_agent_proto_msgTypes[21] + mi := &file_llmgw_v1_agent_proto_msgTypes[23] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -2810,7 +3071,7 @@ func (x *ShardStatus) String() string { func (*ShardStatus) ProtoMessage() {} func (x *ShardStatus) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[21] + mi := &file_llmgw_v1_agent_proto_msgTypes[23] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -2823,7 +3084,7 @@ func (x *ShardStatus) ProtoReflect() protoreflect.Message { // Deprecated: Use ShardStatus.ProtoReflect.Descriptor instead. func (*ShardStatus) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{21} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{23} } func (x *ShardStatus) GetNodeId() string { @@ -2897,7 +3158,7 @@ type FetchProgress struct { func (x *FetchProgress) Reset() { *x = FetchProgress{} - mi := &file_llmgw_v1_agent_proto_msgTypes[22] + mi := &file_llmgw_v1_agent_proto_msgTypes[24] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -2909,7 +3170,7 @@ func (x *FetchProgress) String() string { func (*FetchProgress) ProtoMessage() {} func (x *FetchProgress) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[22] + mi := &file_llmgw_v1_agent_proto_msgTypes[24] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -2922,7 +3183,7 @@ func (x *FetchProgress) ProtoReflect() protoreflect.Message { // Deprecated: Use FetchProgress.ProtoReflect.Descriptor instead. func (*FetchProgress) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{22} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{24} } func (x *FetchProgress) GetSource() string { @@ -2985,7 +3246,7 @@ type StartShard struct { func (x *StartShard) Reset() { *x = StartShard{} - mi := &file_llmgw_v1_agent_proto_msgTypes[23] + mi := &file_llmgw_v1_agent_proto_msgTypes[25] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -2997,7 +3258,7 @@ func (x *StartShard) String() string { func (*StartShard) ProtoMessage() {} func (x *StartShard) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[23] + mi := &file_llmgw_v1_agent_proto_msgTypes[25] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -3010,7 +3271,7 @@ func (x *StartShard) ProtoReflect() protoreflect.Message { // Deprecated: Use StartShard.ProtoReflect.Descriptor instead. func (*StartShard) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{23} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{25} } func (x *StartShard) GetReplicaId() string { @@ -3147,14 +3408,17 @@ type EngineProfile struct { ServedModelName string `protobuf:"bytes,11,opt,name=served_model_name,json=servedModelName,proto3" json:"served_model_name,omitempty"` // adapters are LoRA adapters loaded beside the model, in order: the index // is the id a request applies one by. - Adapters []*LoraAdapter `protobuf:"bytes,12,rep,name=adapters,proto3" json:"adapters,omitempty"` + Adapters []*LoraAdapter `protobuf:"bytes,12,rep,name=adapters,proto3" json:"adapters,omitempty"` + // kv_events has a vLLM engine publish its KV cache events to the agent, for + // the router's precise index. + KvEvents bool `protobuf:"varint,13,opt,name=kv_events,json=kvEvents,proto3" json:"kv_events,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache } func (x *EngineProfile) Reset() { *x = EngineProfile{} - mi := &file_llmgw_v1_agent_proto_msgTypes[24] + mi := &file_llmgw_v1_agent_proto_msgTypes[26] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -3166,7 +3430,7 @@ func (x *EngineProfile) String() string { func (*EngineProfile) ProtoMessage() {} func (x *EngineProfile) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[24] + mi := &file_llmgw_v1_agent_proto_msgTypes[26] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -3179,7 +3443,7 @@ func (x *EngineProfile) ProtoReflect() protoreflect.Message { // Deprecated: Use EngineProfile.ProtoReflect.Descriptor instead. func (*EngineProfile) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{24} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{26} } func (x *EngineProfile) GetName() string { @@ -3266,6 +3530,13 @@ func (x *EngineProfile) GetAdapters() []*LoraAdapter { return nil } +func (x *EngineProfile) GetKvEvents() bool { + if x != nil { + return x.KvEvents + } + return false +} + // RemoveWeights deletes cached model files a node no longer needs. // // The paths are computed by the control plane from the catalog, but the agent @@ -3282,7 +3553,7 @@ type RemoveWeights struct { func (x *RemoveWeights) Reset() { *x = RemoveWeights{} - mi := &file_llmgw_v1_agent_proto_msgTypes[25] + mi := &file_llmgw_v1_agent_proto_msgTypes[27] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -3294,7 +3565,7 @@ func (x *RemoveWeights) String() string { func (*RemoveWeights) ProtoMessage() {} func (x *RemoveWeights) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[25] + mi := &file_llmgw_v1_agent_proto_msgTypes[27] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -3307,7 +3578,7 @@ func (x *RemoveWeights) ProtoReflect() protoreflect.Message { // Deprecated: Use RemoveWeights.ProtoReflect.Descriptor instead. func (*RemoveWeights) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{25} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{27} } func (x *RemoveWeights) GetPaths() []string { @@ -3327,7 +3598,7 @@ type StopShard struct { func (x *StopShard) Reset() { *x = StopShard{} - mi := &file_llmgw_v1_agent_proto_msgTypes[26] + mi := &file_llmgw_v1_agent_proto_msgTypes[28] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -3339,7 +3610,7 @@ func (x *StopShard) String() string { func (*StopShard) ProtoMessage() {} func (x *StopShard) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[26] + mi := &file_llmgw_v1_agent_proto_msgTypes[28] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -3352,7 +3623,7 @@ func (x *StopShard) ProtoReflect() protoreflect.Message { // Deprecated: Use StopShard.ProtoReflect.Descriptor instead. func (*StopShard) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{26} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{28} } func (x *StopShard) GetShardId() string { @@ -3372,7 +3643,7 @@ type DrainShard struct { func (x *DrainShard) Reset() { *x = DrainShard{} - mi := &file_llmgw_v1_agent_proto_msgTypes[27] + mi := &file_llmgw_v1_agent_proto_msgTypes[29] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -3384,7 +3655,7 @@ func (x *DrainShard) String() string { func (*DrainShard) ProtoMessage() {} func (x *DrainShard) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[27] + mi := &file_llmgw_v1_agent_proto_msgTypes[29] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -3397,7 +3668,7 @@ func (x *DrainShard) ProtoReflect() protoreflect.Message { // Deprecated: Use DrainShard.ProtoReflect.Descriptor instead. func (*DrainShard) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{27} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{29} } func (x *DrainShard) GetShardId() string { @@ -3419,7 +3690,7 @@ type Ack struct { func (x *Ack) Reset() { *x = Ack{} - mi := &file_llmgw_v1_agent_proto_msgTypes[28] + mi := &file_llmgw_v1_agent_proto_msgTypes[30] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -3431,7 +3702,7 @@ func (x *Ack) String() string { func (*Ack) ProtoMessage() {} func (x *Ack) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[28] + mi := &file_llmgw_v1_agent_proto_msgTypes[30] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -3444,7 +3715,7 @@ func (x *Ack) ProtoReflect() protoreflect.Message { // Deprecated: Use Ack.ProtoReflect.Descriptor instead. func (*Ack) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{28} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{30} } func (x *Ack) GetMessageId() string { @@ -3488,7 +3759,7 @@ type LogsRequest struct { func (x *LogsRequest) Reset() { *x = LogsRequest{} - mi := &file_llmgw_v1_agent_proto_msgTypes[29] + mi := &file_llmgw_v1_agent_proto_msgTypes[31] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -3500,7 +3771,7 @@ func (x *LogsRequest) String() string { func (*LogsRequest) ProtoMessage() {} func (x *LogsRequest) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[29] + mi := &file_llmgw_v1_agent_proto_msgTypes[31] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -3513,7 +3784,7 @@ func (x *LogsRequest) ProtoReflect() protoreflect.Message { // Deprecated: Use LogsRequest.ProtoReflect.Descriptor instead. func (*LogsRequest) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{29} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{31} } func (x *LogsRequest) GetRequestId() string { @@ -3553,7 +3824,7 @@ type LogsReply struct { func (x *LogsReply) Reset() { *x = LogsReply{} - mi := &file_llmgw_v1_agent_proto_msgTypes[30] + mi := &file_llmgw_v1_agent_proto_msgTypes[32] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -3565,7 +3836,7 @@ func (x *LogsReply) String() string { func (*LogsReply) ProtoMessage() {} func (x *LogsReply) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[30] + mi := &file_llmgw_v1_agent_proto_msgTypes[32] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -3578,7 +3849,7 @@ func (x *LogsReply) ProtoReflect() protoreflect.Message { // Deprecated: Use LogsReply.ProtoReflect.Descriptor instead. func (*LogsReply) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{30} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{32} } func (x *LogsReply) GetRequestId() string { @@ -3624,7 +3895,7 @@ type FabricScanRequest struct { func (x *FabricScanRequest) Reset() { *x = FabricScanRequest{} - mi := &file_llmgw_v1_agent_proto_msgTypes[31] + mi := &file_llmgw_v1_agent_proto_msgTypes[33] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -3636,7 +3907,7 @@ func (x *FabricScanRequest) String() string { func (*FabricScanRequest) ProtoMessage() {} func (x *FabricScanRequest) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[31] + mi := &file_llmgw_v1_agent_proto_msgTypes[33] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -3649,7 +3920,7 @@ func (x *FabricScanRequest) ProtoReflect() protoreflect.Message { // Deprecated: Use FabricScanRequest.ProtoReflect.Descriptor instead. func (*FabricScanRequest) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{31} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{33} } func (x *FabricScanRequest) GetRequestId() string { @@ -3688,7 +3959,7 @@ type FabricScanReply struct { func (x *FabricScanReply) Reset() { *x = FabricScanReply{} - mi := &file_llmgw_v1_agent_proto_msgTypes[32] + mi := &file_llmgw_v1_agent_proto_msgTypes[34] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -3700,7 +3971,7 @@ func (x *FabricScanReply) String() string { func (*FabricScanReply) ProtoMessage() {} func (x *FabricScanReply) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[32] + mi := &file_llmgw_v1_agent_proto_msgTypes[34] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -3713,7 +3984,7 @@ func (x *FabricScanReply) ProtoReflect() protoreflect.Message { // Deprecated: Use FabricScanReply.ProtoReflect.Descriptor instead. func (*FabricScanReply) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{32} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{34} } func (x *FabricScanReply) GetRequestId() string { @@ -3769,7 +4040,7 @@ type FabricTestRequest struct { func (x *FabricTestRequest) Reset() { *x = FabricTestRequest{} - mi := &file_llmgw_v1_agent_proto_msgTypes[33] + mi := &file_llmgw_v1_agent_proto_msgTypes[35] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -3781,7 +4052,7 @@ func (x *FabricTestRequest) String() string { func (*FabricTestRequest) ProtoMessage() {} func (x *FabricTestRequest) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[33] + mi := &file_llmgw_v1_agent_proto_msgTypes[35] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -3794,7 +4065,7 @@ func (x *FabricTestRequest) ProtoReflect() protoreflect.Message { // Deprecated: Use FabricTestRequest.ProtoReflect.Descriptor instead. func (*FabricTestRequest) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{33} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{35} } func (x *FabricTestRequest) GetRequestId() string { @@ -3863,7 +4134,7 @@ type FabricTestReply struct { func (x *FabricTestReply) Reset() { *x = FabricTestReply{} - mi := &file_llmgw_v1_agent_proto_msgTypes[34] + mi := &file_llmgw_v1_agent_proto_msgTypes[36] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -3875,7 +4146,7 @@ func (x *FabricTestReply) String() string { func (*FabricTestReply) ProtoMessage() {} func (x *FabricTestReply) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[34] + mi := &file_llmgw_v1_agent_proto_msgTypes[36] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -3888,7 +4159,7 @@ func (x *FabricTestReply) ProtoReflect() protoreflect.Message { // Deprecated: Use FabricTestReply.ProtoReflect.Descriptor instead. func (*FabricTestReply) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{34} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{36} } func (x *FabricTestReply) GetRequestId() string { @@ -3948,7 +4219,7 @@ type UpgradeAgent struct { func (x *UpgradeAgent) Reset() { *x = UpgradeAgent{} - mi := &file_llmgw_v1_agent_proto_msgTypes[35] + mi := &file_llmgw_v1_agent_proto_msgTypes[37] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -3960,7 +4231,7 @@ func (x *UpgradeAgent) String() string { func (*UpgradeAgent) ProtoMessage() {} func (x *UpgradeAgent) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[35] + mi := &file_llmgw_v1_agent_proto_msgTypes[37] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -3973,7 +4244,7 @@ func (x *UpgradeAgent) ProtoReflect() protoreflect.Message { // Deprecated: Use UpgradeAgent.ProtoReflect.Descriptor instead. func (*UpgradeAgent) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{35} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{37} } func (x *UpgradeAgent) GetRequestId() string { @@ -4010,7 +4281,7 @@ type UpgradeReply struct { func (x *UpgradeReply) Reset() { *x = UpgradeReply{} - mi := &file_llmgw_v1_agent_proto_msgTypes[36] + mi := &file_llmgw_v1_agent_proto_msgTypes[38] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -4022,7 +4293,7 @@ func (x *UpgradeReply) String() string { func (*UpgradeReply) ProtoMessage() {} func (x *UpgradeReply) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[36] + mi := &file_llmgw_v1_agent_proto_msgTypes[38] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -4035,7 +4306,7 @@ func (x *UpgradeReply) ProtoReflect() protoreflect.Message { // Deprecated: Use UpgradeReply.ProtoReflect.Descriptor instead. func (*UpgradeReply) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{36} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{38} } func (x *UpgradeReply) GetRequestId() string { @@ -4071,7 +4342,7 @@ type LoraAdapter struct { func (x *LoraAdapter) Reset() { *x = LoraAdapter{} - mi := &file_llmgw_v1_agent_proto_msgTypes[37] + mi := &file_llmgw_v1_agent_proto_msgTypes[39] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -4083,7 +4354,7 @@ func (x *LoraAdapter) String() string { func (*LoraAdapter) ProtoMessage() {} func (x *LoraAdapter) ProtoReflect() protoreflect.Message { - mi := &file_llmgw_v1_agent_proto_msgTypes[37] + mi := &file_llmgw_v1_agent_proto_msgTypes[39] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -4096,7 +4367,7 @@ func (x *LoraAdapter) ProtoReflect() protoreflect.Message { // Deprecated: Use LoraAdapter.ProtoReflect.Descriptor instead. func (*LoraAdapter) Descriptor() ([]byte, []int) { - return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{37} + return file_llmgw_v1_agent_proto_rawDescGZIP(), []int{39} } func (x *LoraAdapter) GetName() string { @@ -4117,7 +4388,7 @@ var File_llmgw_v1_agent_proto protoreflect.FileDescriptor const file_llmgw_v1_agent_proto_rawDesc = "" + "\n" + - "\x14llmgw/v1/agent.proto\x12\bllmgw.v1\"\x86\x03\n" + + "\x14llmgw/v1/agent.proto\x12\bllmgw.v1\"\xb9\x03\n" + "\fAgentMessage\x120\n" + "\bregister\x18\x01 \x01(\v2\x12.llmgw.v1.RegisterH\x00R\bregister\x123\n" + "\theartbeat\x18\x02 \x01(\v2\x13.llmgw.v1.HeartbeatH\x00R\theartbeat\x12-\n" + @@ -4127,8 +4398,19 @@ const file_llmgw_v1_agent_proto_rawDesc = "" + "fabricScan\x12<\n" + "\vfabric_test\x18\x06 \x01(\v2\x19.llmgw.v1.FabricTestReplyH\x00R\n" + "fabricTest\x122\n" + - "\aupgrade\x18\a \x01(\v2\x16.llmgw.v1.UpgradeReplyH\x00R\aupgradeB\x05\n" + - "\x03msg\"\xdb\x04\n" + + "\aupgrade\x18\a \x01(\v2\x16.llmgw.v1.UpgradeReplyH\x00R\aupgrade\x121\n" + + "\tkv_events\x18\b \x01(\v2\x12.llmgw.v1.KVEventsH\x00R\bkvEventsB\x05\n" + + "\x03msg\"\xb5\x01\n" + + "\bKVEvents\x12\x1d\n" + + "\n" + + "replica_id\x18\x01 \x01(\tR\treplicaId\x12\x1d\n" + + "\n" + + "block_size\x18\x02 \x01(\x05R\tblockSize\x12\x1f\n" + + "\vclear_first\x18\x03 \x01(\bR\n" + + "clearFirst\x12\x16\n" + + "\x06stored\x18\x04 \x03(\x06R\x06stored\x12\x18\n" + + "\aremoved\x18\x05 \x03(\x06R\aremoved\x12\x18\n" + + "\aproblem\x18\x06 \x01(\tR\aproblem\"\xd0\x05\n" + "\x0eControlMessage\x12,\n" + "\x05start\x18\x01 \x01(\v2\x14.llmgw.v1.StartShardH\x00R\x05start\x12)\n" + "\x04stop\x18\x02 \x01(\v2\x13.llmgw.v1.StopShardH\x00R\x04stop\x12,\n" + @@ -4143,7 +4425,12 @@ const file_llmgw_v1_agent_proto_rawDesc = "" + "fabricTest\x122\n" + "\aupgrade\x18\n" + " \x01(\v2\x16.llmgw.v1.UpgradeAgentH\x00R\aupgrade\x12@\n" + - "\x0econtrol_planes\x18\v \x01(\v2\x17.llmgw.v1.ControlPlanesH\x00R\rcontrolPlanesB\x05\n" + + "\x0econtrol_planes\x18\v \x01(\v2\x17.llmgw.v1.ControlPlanesH\x00R\rcontrolPlanes\x129\n" + + "\x05trace\x18\f \x03(\v2#.llmgw.v1.ControlMessage.TraceEntryR\x05trace\x1a8\n" + + "\n" + + "TraceEntry\x12\x10\n" + + "\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n" + + "\x05value\x18\x02 \x01(\tR\x05value:\x028\x01B\x05\n" + "\x03msg\")\n" + "\rControlPlanes\x12\x18\n" + "\aservers\x18\x01 \x03(\tR\aservers\"\x80\a\n" + @@ -4210,7 +4497,7 @@ const file_llmgw_v1_agent_proto_rawDesc = "" + "\vleader_port\x18\x0e \x01(\x05R\n" + "leaderPort\x12\x1d\n" + "\n" + - "profile_fp\x18\x0f \x01(\tR\tprofileFp\"\xa3\x06\n" + + "profile_fp\x18\x0f \x01(\tR\tprofileFp\"\xca\x06\n" + "\x03GPU\x12\x14\n" + "\x05index\x18\x01 \x01(\x05R\x05index\x12\x12\n" + "\x04uuid\x18\x02 \x01(\tR\x04uuid\x12\x12\n" + @@ -4235,10 +4522,20 @@ const file_llmgw_v1_agent_proto_rawDesc = "" + "\rfabric_status\x18\x12 \x01(\tR\ffabricStatus\x12!\n" + "\fcluster_uuid\x18\x13 \x01(\tR\vclusterUuid\x12\x1b\n" + "\tclique_id\x18\x14 \x01(\tR\bcliqueId\x12)\n" + - "\x10fabric_bandwidth\x18\x15 \x01(\tR\x0ffabricBandwidth\x1a;\n" + + "\x10fabric_bandwidth\x18\x15 \x01(\tR\x0ffabricBandwidth\x12%\n" + + "\x03mig\x18\x16 \x01(\v2\x13.llmgw.v1.MIGDeviceR\x03mig\x1a;\n" + "\rNicPathsEntry\x12\x10\n" + "\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n" + - "\x05value\x18\x02 \x01(\tR\x05value:\x028\x01\"[\n" + + "\x05value\x18\x02 \x01(\tR\x05value:\x028\x01\"\x84\x02\n" + + "\tMIGDevice\x12!\n" + + "\fparent_index\x18\x01 \x01(\x05R\vparentIndex\x12\x1f\n" + + "\vparent_uuid\x18\x02 \x01(\tR\n" + + "parentUuid\x123\n" + + "\x16parent_memory_total_mb\x18\x03 \x01(\x05R\x13parentMemoryTotalMb\x12\x16\n" + + "\x06device\x18\x04 \x01(\x05R\x06device\x12\x18\n" + + "\aprofile\x18\x05 \x01(\tR\aprofile\x12!\n" + + "\fgpu_instance\x18\x06 \x01(\x05R\vgpuInstance\x12)\n" + + "\x10compute_instance\x18\a \x01(\x05R\x0fcomputeInstance\"[\n" + "\x10FabricAttachment\x12\x16\n" + "\x06fabric\x18\x01 \x01(\tR\x06fabric\x12\x12\n" + "\x04hcas\x18\x02 \x03(\tR\x04hcas\x12\x1b\n" + @@ -4369,12 +4666,17 @@ const file_llmgw_v1_agent_proto_rawDesc = "" + "\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n" + "\x05value\x18\x02 \x01(\tR\x05value:\x028\x01\";\n" + "\tProvision\x12.\n" + - "\aengines\x18\x01 \x03(\v2\x14.llmgw.v1.EngineWantR\aengines\"X\n" + + "\aengines\x18\x01 \x03(\v2\x14.llmgw.v1.EngineWantR\aengines\"\x8d\x02\n" + "\n" + "EngineWant\x12\x16\n" + "\x06engine\x18\x01 \x01(\tR\x06engine\x12\x18\n" + "\aversion\x18\x02 \x01(\tR\aversion\x12\x18\n" + - "\avariant\x18\x03 \x01(\tR\avariant\"\x8b\x01\n" + + "\avariant\x18\x03 \x01(\tR\avariant\x12!\n" + + "\foffline_base\x18\x04 \x01(\tR\vofflineBase\x12N\n" + + "\x0eoffline_sha256\x18\x05 \x03(\v2'.llmgw.v1.EngineWant.OfflineSha256EntryR\rofflineSha256\x1a@\n" + + "\x12OfflineSha256Entry\x12\x10\n" + + "\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n" + + "\x05value\x18\x02 \x01(\tR\x05value:\x028\x01\"\x8b\x01\n" + "\x0fProvisionStatus\x12\x16\n" + "\x06engine\x18\x01 \x01(\tR\x06engine\x12\x18\n" + "\aversion\x18\x02 \x01(\tR\aversion\x12\x18\n" + @@ -4432,7 +4734,7 @@ const file_llmgw_v1_agent_proto_rawDesc = "" + "profile_fp\x18\x0f \x01(\tR\tprofileFp\x12\x17\n" + "\aapi_key\x18\x10 \x01(\tR\x06apiKey\x12\x1f\n" + "\vcpu_threads\x18\x11 \x01(\x05R\n" + - "cpuThreads\"\xb0\x03\n" + + "cpuThreads\"\xcd\x03\n" + "\rEngineProfile\x12\x12\n" + "\x04name\x18\x01 \x01(\tR\x04name\x12\x16\n" + "\x06engine\x18\x02 \x01(\tR\x06engine\x12\x1b\n" + @@ -4447,7 +4749,8 @@ const file_llmgw_v1_agent_proto_rawDesc = "" + "model_path\x18\n" + " \x01(\tR\tmodelPath\x12*\n" + "\x11served_model_name\x18\v \x01(\tR\x0fservedModelName\x121\n" + - "\badapters\x18\f \x03(\v2\x15.llmgw.v1.LoraAdapterR\badapters\x1a6\n" + + "\badapters\x18\f \x03(\v2\x15.llmgw.v1.LoraAdapterR\badapters\x12\x1b\n" + + "\tkv_events\x18\r \x01(\bR\bkvEvents\x1a6\n" + "\bEnvEntry\x12\x10\n" + "\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n" + "\x05value\x18\x02 \x01(\tR\x05value:\x028\x01\"%\n" + @@ -4532,110 +4835,118 @@ func file_llmgw_v1_agent_proto_rawDescGZIP() []byte { } var file_llmgw_v1_agent_proto_enumTypes = make([]protoimpl.EnumInfo, 1) -var file_llmgw_v1_agent_proto_msgTypes = make([]protoimpl.MessageInfo, 44) +var file_llmgw_v1_agent_proto_msgTypes = make([]protoimpl.MessageInfo, 48) var file_llmgw_v1_agent_proto_goTypes = []any{ (ShardStatus_State)(0), // 0: llmgw.v1.ShardStatus.State (*AgentMessage)(nil), // 1: llmgw.v1.AgentMessage - (*ControlMessage)(nil), // 2: llmgw.v1.ControlMessage - (*ControlPlanes)(nil), // 3: llmgw.v1.ControlPlanes - (*Register)(nil), // 4: llmgw.v1.Register - (*Host)(nil), // 5: llmgw.v1.Host - (*Storage)(nil), // 6: llmgw.v1.Storage - (*RunningShard)(nil), // 7: llmgw.v1.RunningShard - (*GPU)(nil), // 8: llmgw.v1.GPU - (*FabricAttachment)(nil), // 9: llmgw.v1.FabricAttachment - (*LocalWeights)(nil), // 10: llmgw.v1.LocalWeights - (*NodeLoad)(nil), // 11: llmgw.v1.NodeLoad - (*GPUSensor)(nil), // 12: llmgw.v1.GPUSensor - (*ShardLoad)(nil), // 13: llmgw.v1.ShardLoad - (*IBPort)(nil), // 14: llmgw.v1.IBPort - (*SubnetManager)(nil), // 15: llmgw.v1.SubnetManager - (*IMEX)(nil), // 16: llmgw.v1.IMEX - (*GPUFabricState)(nil), // 17: llmgw.v1.GPUFabricState - (*Heartbeat)(nil), // 18: llmgw.v1.Heartbeat - (*Provision)(nil), // 19: llmgw.v1.Provision - (*EngineWant)(nil), // 20: llmgw.v1.EngineWant - (*ProvisionStatus)(nil), // 21: llmgw.v1.ProvisionStatus - (*ShardStatus)(nil), // 22: llmgw.v1.ShardStatus - (*FetchProgress)(nil), // 23: llmgw.v1.FetchProgress - (*StartShard)(nil), // 24: llmgw.v1.StartShard - (*EngineProfile)(nil), // 25: llmgw.v1.EngineProfile - (*RemoveWeights)(nil), // 26: llmgw.v1.RemoveWeights - (*StopShard)(nil), // 27: llmgw.v1.StopShard - (*DrainShard)(nil), // 28: llmgw.v1.DrainShard - (*Ack)(nil), // 29: llmgw.v1.Ack - (*LogsRequest)(nil), // 30: llmgw.v1.LogsRequest - (*LogsReply)(nil), // 31: llmgw.v1.LogsReply - (*FabricScanRequest)(nil), // 32: llmgw.v1.FabricScanRequest - (*FabricScanReply)(nil), // 33: llmgw.v1.FabricScanReply - (*FabricTestRequest)(nil), // 34: llmgw.v1.FabricTestRequest - (*FabricTestReply)(nil), // 35: llmgw.v1.FabricTestReply - (*UpgradeAgent)(nil), // 36: llmgw.v1.UpgradeAgent - (*UpgradeReply)(nil), // 37: llmgw.v1.UpgradeReply - (*LoraAdapter)(nil), // 38: llmgw.v1.LoraAdapter - nil, // 39: llmgw.v1.Register.LabelsEntry - nil, // 40: llmgw.v1.Register.EngineVersionsEntry - nil, // 41: llmgw.v1.GPU.NicPathsEntry - nil, // 42: llmgw.v1.IBPort.CountersEntry - nil, // 43: llmgw.v1.Heartbeat.EngineVersionsEntry - nil, // 44: llmgw.v1.EngineProfile.EnvEntry + (*KVEvents)(nil), // 2: llmgw.v1.KVEvents + (*ControlMessage)(nil), // 3: llmgw.v1.ControlMessage + (*ControlPlanes)(nil), // 4: llmgw.v1.ControlPlanes + (*Register)(nil), // 5: llmgw.v1.Register + (*Host)(nil), // 6: llmgw.v1.Host + (*Storage)(nil), // 7: llmgw.v1.Storage + (*RunningShard)(nil), // 8: llmgw.v1.RunningShard + (*GPU)(nil), // 9: llmgw.v1.GPU + (*MIGDevice)(nil), // 10: llmgw.v1.MIGDevice + (*FabricAttachment)(nil), // 11: llmgw.v1.FabricAttachment + (*LocalWeights)(nil), // 12: llmgw.v1.LocalWeights + (*NodeLoad)(nil), // 13: llmgw.v1.NodeLoad + (*GPUSensor)(nil), // 14: llmgw.v1.GPUSensor + (*ShardLoad)(nil), // 15: llmgw.v1.ShardLoad + (*IBPort)(nil), // 16: llmgw.v1.IBPort + (*SubnetManager)(nil), // 17: llmgw.v1.SubnetManager + (*IMEX)(nil), // 18: llmgw.v1.IMEX + (*GPUFabricState)(nil), // 19: llmgw.v1.GPUFabricState + (*Heartbeat)(nil), // 20: llmgw.v1.Heartbeat + (*Provision)(nil), // 21: llmgw.v1.Provision + (*EngineWant)(nil), // 22: llmgw.v1.EngineWant + (*ProvisionStatus)(nil), // 23: llmgw.v1.ProvisionStatus + (*ShardStatus)(nil), // 24: llmgw.v1.ShardStatus + (*FetchProgress)(nil), // 25: llmgw.v1.FetchProgress + (*StartShard)(nil), // 26: llmgw.v1.StartShard + (*EngineProfile)(nil), // 27: llmgw.v1.EngineProfile + (*RemoveWeights)(nil), // 28: llmgw.v1.RemoveWeights + (*StopShard)(nil), // 29: llmgw.v1.StopShard + (*DrainShard)(nil), // 30: llmgw.v1.DrainShard + (*Ack)(nil), // 31: llmgw.v1.Ack + (*LogsRequest)(nil), // 32: llmgw.v1.LogsRequest + (*LogsReply)(nil), // 33: llmgw.v1.LogsReply + (*FabricScanRequest)(nil), // 34: llmgw.v1.FabricScanRequest + (*FabricScanReply)(nil), // 35: llmgw.v1.FabricScanReply + (*FabricTestRequest)(nil), // 36: llmgw.v1.FabricTestRequest + (*FabricTestReply)(nil), // 37: llmgw.v1.FabricTestReply + (*UpgradeAgent)(nil), // 38: llmgw.v1.UpgradeAgent + (*UpgradeReply)(nil), // 39: llmgw.v1.UpgradeReply + (*LoraAdapter)(nil), // 40: llmgw.v1.LoraAdapter + nil, // 41: llmgw.v1.ControlMessage.TraceEntry + nil, // 42: llmgw.v1.Register.LabelsEntry + nil, // 43: llmgw.v1.Register.EngineVersionsEntry + nil, // 44: llmgw.v1.GPU.NicPathsEntry + nil, // 45: llmgw.v1.IBPort.CountersEntry + nil, // 46: llmgw.v1.Heartbeat.EngineVersionsEntry + nil, // 47: llmgw.v1.EngineWant.OfflineSha256Entry + nil, // 48: llmgw.v1.EngineProfile.EnvEntry } var file_llmgw_v1_agent_proto_depIdxs = []int32{ - 4, // 0: llmgw.v1.AgentMessage.register:type_name -> llmgw.v1.Register - 18, // 1: llmgw.v1.AgentMessage.heartbeat:type_name -> llmgw.v1.Heartbeat - 22, // 2: llmgw.v1.AgentMessage.shard:type_name -> llmgw.v1.ShardStatus - 31, // 3: llmgw.v1.AgentMessage.logs:type_name -> llmgw.v1.LogsReply - 33, // 4: llmgw.v1.AgentMessage.fabric_scan:type_name -> llmgw.v1.FabricScanReply - 35, // 5: llmgw.v1.AgentMessage.fabric_test:type_name -> llmgw.v1.FabricTestReply - 37, // 6: llmgw.v1.AgentMessage.upgrade:type_name -> llmgw.v1.UpgradeReply - 24, // 7: llmgw.v1.ControlMessage.start:type_name -> llmgw.v1.StartShard - 27, // 8: llmgw.v1.ControlMessage.stop:type_name -> llmgw.v1.StopShard - 28, // 9: llmgw.v1.ControlMessage.drain:type_name -> llmgw.v1.DrainShard - 29, // 10: llmgw.v1.ControlMessage.ack:type_name -> llmgw.v1.Ack - 26, // 11: llmgw.v1.ControlMessage.remove_weights:type_name -> llmgw.v1.RemoveWeights - 19, // 12: llmgw.v1.ControlMessage.provision:type_name -> llmgw.v1.Provision - 30, // 13: llmgw.v1.ControlMessage.logs:type_name -> llmgw.v1.LogsRequest - 32, // 14: llmgw.v1.ControlMessage.fabric_scan:type_name -> llmgw.v1.FabricScanRequest - 34, // 15: llmgw.v1.ControlMessage.fabric_test:type_name -> llmgw.v1.FabricTestRequest - 36, // 16: llmgw.v1.ControlMessage.upgrade:type_name -> llmgw.v1.UpgradeAgent - 3, // 17: llmgw.v1.ControlMessage.control_planes:type_name -> llmgw.v1.ControlPlanes - 39, // 18: llmgw.v1.Register.labels:type_name -> llmgw.v1.Register.LabelsEntry - 8, // 19: llmgw.v1.Register.gpus:type_name -> llmgw.v1.GPU - 9, // 20: llmgw.v1.Register.fabrics:type_name -> llmgw.v1.FabricAttachment - 40, // 21: llmgw.v1.Register.engine_versions:type_name -> llmgw.v1.Register.EngineVersionsEntry - 7, // 22: llmgw.v1.Register.running_shards:type_name -> llmgw.v1.RunningShard - 10, // 23: llmgw.v1.Register.weights:type_name -> llmgw.v1.LocalWeights - 6, // 24: llmgw.v1.Register.storage:type_name -> llmgw.v1.Storage - 5, // 25: llmgw.v1.Register.host:type_name -> llmgw.v1.Host - 16, // 26: llmgw.v1.Register.imex:type_name -> llmgw.v1.IMEX - 0, // 27: llmgw.v1.RunningShard.state:type_name -> llmgw.v1.ShardStatus.State - 41, // 28: llmgw.v1.GPU.nic_paths:type_name -> llmgw.v1.GPU.NicPathsEntry - 13, // 29: llmgw.v1.NodeLoad.shards:type_name -> llmgw.v1.ShardLoad - 12, // 30: llmgw.v1.NodeLoad.gpus:type_name -> llmgw.v1.GPUSensor - 42, // 31: llmgw.v1.IBPort.counters:type_name -> llmgw.v1.IBPort.CountersEntry - 15, // 32: llmgw.v1.IBPort.subnet_managers:type_name -> llmgw.v1.SubnetManager - 6, // 33: llmgw.v1.Heartbeat.storage:type_name -> llmgw.v1.Storage - 10, // 34: llmgw.v1.Heartbeat.weights:type_name -> llmgw.v1.LocalWeights - 43, // 35: llmgw.v1.Heartbeat.engine_versions:type_name -> llmgw.v1.Heartbeat.EngineVersionsEntry - 21, // 36: llmgw.v1.Heartbeat.provision:type_name -> llmgw.v1.ProvisionStatus - 11, // 37: llmgw.v1.Heartbeat.load:type_name -> llmgw.v1.NodeLoad - 14, // 38: llmgw.v1.Heartbeat.ib_ports:type_name -> llmgw.v1.IBPort - 9, // 39: llmgw.v1.Heartbeat.fabrics:type_name -> llmgw.v1.FabricAttachment - 17, // 40: llmgw.v1.Heartbeat.gpu_fabric:type_name -> llmgw.v1.GPUFabricState - 16, // 41: llmgw.v1.Heartbeat.imex:type_name -> llmgw.v1.IMEX - 20, // 42: llmgw.v1.Provision.engines:type_name -> llmgw.v1.EngineWant - 0, // 43: llmgw.v1.ShardStatus.state:type_name -> llmgw.v1.ShardStatus.State - 23, // 44: llmgw.v1.ShardStatus.fetch:type_name -> llmgw.v1.FetchProgress - 25, // 45: llmgw.v1.StartShard.profile:type_name -> llmgw.v1.EngineProfile - 44, // 46: llmgw.v1.EngineProfile.env:type_name -> llmgw.v1.EngineProfile.EnvEntry - 38, // 47: llmgw.v1.EngineProfile.adapters:type_name -> llmgw.v1.LoraAdapter - 1, // 48: llmgw.v1.AgentService.Connect:input_type -> llmgw.v1.AgentMessage - 2, // 49: llmgw.v1.AgentService.Connect:output_type -> llmgw.v1.ControlMessage - 49, // [49:50] is the sub-list for method output_type - 48, // [48:49] is the sub-list for method input_type - 48, // [48:48] is the sub-list for extension type_name - 48, // [48:48] is the sub-list for extension extendee - 0, // [0:48] is the sub-list for field type_name + 5, // 0: llmgw.v1.AgentMessage.register:type_name -> llmgw.v1.Register + 20, // 1: llmgw.v1.AgentMessage.heartbeat:type_name -> llmgw.v1.Heartbeat + 24, // 2: llmgw.v1.AgentMessage.shard:type_name -> llmgw.v1.ShardStatus + 33, // 3: llmgw.v1.AgentMessage.logs:type_name -> llmgw.v1.LogsReply + 35, // 4: llmgw.v1.AgentMessage.fabric_scan:type_name -> llmgw.v1.FabricScanReply + 37, // 5: llmgw.v1.AgentMessage.fabric_test:type_name -> llmgw.v1.FabricTestReply + 39, // 6: llmgw.v1.AgentMessage.upgrade:type_name -> llmgw.v1.UpgradeReply + 2, // 7: llmgw.v1.AgentMessage.kv_events:type_name -> llmgw.v1.KVEvents + 26, // 8: llmgw.v1.ControlMessage.start:type_name -> llmgw.v1.StartShard + 29, // 9: llmgw.v1.ControlMessage.stop:type_name -> llmgw.v1.StopShard + 30, // 10: llmgw.v1.ControlMessage.drain:type_name -> llmgw.v1.DrainShard + 31, // 11: llmgw.v1.ControlMessage.ack:type_name -> llmgw.v1.Ack + 28, // 12: llmgw.v1.ControlMessage.remove_weights:type_name -> llmgw.v1.RemoveWeights + 21, // 13: llmgw.v1.ControlMessage.provision:type_name -> llmgw.v1.Provision + 32, // 14: llmgw.v1.ControlMessage.logs:type_name -> llmgw.v1.LogsRequest + 34, // 15: llmgw.v1.ControlMessage.fabric_scan:type_name -> llmgw.v1.FabricScanRequest + 36, // 16: llmgw.v1.ControlMessage.fabric_test:type_name -> llmgw.v1.FabricTestRequest + 38, // 17: llmgw.v1.ControlMessage.upgrade:type_name -> llmgw.v1.UpgradeAgent + 4, // 18: llmgw.v1.ControlMessage.control_planes:type_name -> llmgw.v1.ControlPlanes + 41, // 19: llmgw.v1.ControlMessage.trace:type_name -> llmgw.v1.ControlMessage.TraceEntry + 42, // 20: llmgw.v1.Register.labels:type_name -> llmgw.v1.Register.LabelsEntry + 9, // 21: llmgw.v1.Register.gpus:type_name -> llmgw.v1.GPU + 11, // 22: llmgw.v1.Register.fabrics:type_name -> llmgw.v1.FabricAttachment + 43, // 23: llmgw.v1.Register.engine_versions:type_name -> llmgw.v1.Register.EngineVersionsEntry + 8, // 24: llmgw.v1.Register.running_shards:type_name -> llmgw.v1.RunningShard + 12, // 25: llmgw.v1.Register.weights:type_name -> llmgw.v1.LocalWeights + 7, // 26: llmgw.v1.Register.storage:type_name -> llmgw.v1.Storage + 6, // 27: llmgw.v1.Register.host:type_name -> llmgw.v1.Host + 18, // 28: llmgw.v1.Register.imex:type_name -> llmgw.v1.IMEX + 0, // 29: llmgw.v1.RunningShard.state:type_name -> llmgw.v1.ShardStatus.State + 44, // 30: llmgw.v1.GPU.nic_paths:type_name -> llmgw.v1.GPU.NicPathsEntry + 10, // 31: llmgw.v1.GPU.mig:type_name -> llmgw.v1.MIGDevice + 15, // 32: llmgw.v1.NodeLoad.shards:type_name -> llmgw.v1.ShardLoad + 14, // 33: llmgw.v1.NodeLoad.gpus:type_name -> llmgw.v1.GPUSensor + 45, // 34: llmgw.v1.IBPort.counters:type_name -> llmgw.v1.IBPort.CountersEntry + 17, // 35: llmgw.v1.IBPort.subnet_managers:type_name -> llmgw.v1.SubnetManager + 7, // 36: llmgw.v1.Heartbeat.storage:type_name -> llmgw.v1.Storage + 12, // 37: llmgw.v1.Heartbeat.weights:type_name -> llmgw.v1.LocalWeights + 46, // 38: llmgw.v1.Heartbeat.engine_versions:type_name -> llmgw.v1.Heartbeat.EngineVersionsEntry + 23, // 39: llmgw.v1.Heartbeat.provision:type_name -> llmgw.v1.ProvisionStatus + 13, // 40: llmgw.v1.Heartbeat.load:type_name -> llmgw.v1.NodeLoad + 16, // 41: llmgw.v1.Heartbeat.ib_ports:type_name -> llmgw.v1.IBPort + 11, // 42: llmgw.v1.Heartbeat.fabrics:type_name -> llmgw.v1.FabricAttachment + 19, // 43: llmgw.v1.Heartbeat.gpu_fabric:type_name -> llmgw.v1.GPUFabricState + 18, // 44: llmgw.v1.Heartbeat.imex:type_name -> llmgw.v1.IMEX + 22, // 45: llmgw.v1.Provision.engines:type_name -> llmgw.v1.EngineWant + 47, // 46: llmgw.v1.EngineWant.offline_sha256:type_name -> llmgw.v1.EngineWant.OfflineSha256Entry + 0, // 47: llmgw.v1.ShardStatus.state:type_name -> llmgw.v1.ShardStatus.State + 25, // 48: llmgw.v1.ShardStatus.fetch:type_name -> llmgw.v1.FetchProgress + 27, // 49: llmgw.v1.StartShard.profile:type_name -> llmgw.v1.EngineProfile + 48, // 50: llmgw.v1.EngineProfile.env:type_name -> llmgw.v1.EngineProfile.EnvEntry + 40, // 51: llmgw.v1.EngineProfile.adapters:type_name -> llmgw.v1.LoraAdapter + 1, // 52: llmgw.v1.AgentService.Connect:input_type -> llmgw.v1.AgentMessage + 3, // 53: llmgw.v1.AgentService.Connect:output_type -> llmgw.v1.ControlMessage + 53, // [53:54] is the sub-list for method output_type + 52, // [52:53] is the sub-list for method input_type + 52, // [52:52] is the sub-list for extension type_name + 52, // [52:52] is the sub-list for extension extendee + 0, // [0:52] is the sub-list for field type_name } func init() { file_llmgw_v1_agent_proto_init() } @@ -4651,8 +4962,9 @@ func file_llmgw_v1_agent_proto_init() { (*AgentMessage_FabricScan)(nil), (*AgentMessage_FabricTest)(nil), (*AgentMessage_Upgrade)(nil), + (*AgentMessage_KvEvents)(nil), } - file_llmgw_v1_agent_proto_msgTypes[1].OneofWrappers = []any{ + file_llmgw_v1_agent_proto_msgTypes[2].OneofWrappers = []any{ (*ControlMessage_Start)(nil), (*ControlMessage_Stop)(nil), (*ControlMessage_Drain)(nil), @@ -4671,7 +4983,7 @@ func file_llmgw_v1_agent_proto_init() { GoPackagePath: reflect.TypeOf(x{}).PkgPath(), RawDescriptor: unsafe.Slice(unsafe.StringData(file_llmgw_v1_agent_proto_rawDesc), len(file_llmgw_v1_agent_proto_rawDesc)), NumEnums: 1, - NumMessages: 44, + NumMessages: 48, NumExtensions: 0, NumServices: 1, }, diff --git a/api/proto/llmgw/v1/agent.proto b/api/proto/llmgw/v1/agent.proto index 98caf135..606399ae 100644 --- a/api/proto/llmgw/v1/agent.proto +++ b/api/proto/llmgw/v1/agent.proto @@ -27,9 +27,36 @@ message AgentMessage { FabricScanReply fabric_scan = 5; FabricTestReply fabric_test = 6; UpgradeReply upgrade = 7; + KVEvents kv_events = 8; } } +// KVEvents is a change to what one vLLM replica's prefix cache holds, read +// by the agent from the engine's KV cache events and sent on for the router's +// precise index (plan §7.5 tier 2). +// +// A net effect since the last one, not the events themselves: a block stored +// and evicted between two sends is not worth the bytes. On every new stream +// the agent first sends each replica in full, with clear_first set, because a +// control plane that has just started or taken over knows nothing. +message KVEvents { + string replica_id = 1; + // block_size is how many tokens make one of the replica's blocks. + int32 block_size = 2; + // clear_first says to forget what was known of the replica before applying the + // rest: its cache was cleared, its engine restarted, events were lost, or + // this is the first piece of a full copy. + bool clear_first = 3; + // stored and removed are block hashes as vLLM publishes them: the low 64 + // bits of the sha256_cbor digest. + repeated fixed64 stored = 4; + repeated fixed64 removed = 5; + // problem, when set, is why the replica's events cannot be used — most + // likely an engine hashing another way than llmgw configured. Its index is + // empty while it stands. + string problem = 6; +} + // ControlMessage is anything the control plane tells a node. message ControlMessage { oneof msg { @@ -45,6 +72,12 @@ message ControlMessage { UpgradeAgent upgrade = 10; ControlPlanes control_planes = 11; } + // trace is the W3C trace context (traceparent, and tracestate when there + // is one) of the control plane's span that sent this command, so what the + // agent does for it — fetching weights, launching the engine, waiting for + // it to answer — lands in the same trace. Empty when the control plane is + // not tracing, and ignored by an agent that is not. + map trace = 12; } // ControlPlanes is every control plane an agent may dial, sent by the leader @@ -252,6 +285,25 @@ message GPU { string cluster_uuid = 19; string clique_id = 20; string fabric_bandwidth = 21; + // mig is set when this is a MIG instance rather than a whole card. index + // is then 1000 + 100 × card + device, uuid the instance's (MIG-…), and + // memory the instance's share; utilization_percent stays zero, because no + // driver measures it per instance. + MIGDevice mig = 22; +} + +// MIGDevice is which card a MIG instance is carved from, and how. +message MIGDevice { + int32 parent_index = 1; + string parent_uuid = 2; + // parent_memory_total_mb is the whole card's: the class is named from it. + int32 parent_memory_total_mb = 3; + // device is the instance's number on its card, as nvidia-smi -L lists it. + int32 device = 4; + // profile is NVIDIA's name for the slice, like 3g.40gb. + string profile = 5; + int32 gpu_instance = 6; + int32 compute_instance = 7; } message FabricAttachment { @@ -515,6 +567,15 @@ message EngineWant { // variant is the build to install, when one is chosen for the node rather // than left to its hardware: "cu13", "cu129". Empty is the agent's choice. string variant = 3; + // offline_base, on a cluster with no way to the internet, is where this + // engine version's files are on its mirror: + // http://mirror:8081/_llmgw/engines/llamacpp/b10991. Set, the node never + // asks the engine's publisher. + string offline_base = 4; + // offline_sha256 is each of those files' checksum by name, from the + // bundle the control plane trusts — not from the mirror, which serves + // every node over plain HTTP. + map offline_sha256 = 5; } // ProvisionStatus is where one engine's installation stands on a node. @@ -625,6 +686,9 @@ message EngineProfile { // adapters are LoRA adapters loaded beside the model, in order: the index // is the id a request applies one by. repeated LoraAdapter adapters = 12; + // kv_events has a vLLM engine publish its KV cache events to the agent, for + // the router's precise index. + bool kv_events = 13; } // RemoveWeights deletes cached model files a node no longer needs. diff --git a/cmd/llmgw/main.go b/cmd/llmgw/main.go index e31dee73..b1666664 100644 --- a/cmd/llmgw/main.go +++ b/cmd/llmgw/main.go @@ -5,6 +5,8 @@ package main import ( "fmt" "os" + // Time zones for scaling schedules, on a machine without the tz database. + _ "time/tzdata" "gitea.mynodes.xyz/ilker/llmgw/internal/cli" ) diff --git a/deploy/container/Dockerfile b/deploy/container/Dockerfile new file mode 100644 index 00000000..3f217c73 --- /dev/null +++ b/deploy/container/Dockerfile @@ -0,0 +1,40 @@ +# The llmgw control plane as a container image, for deploy/helm/llmgw. +# +# The project publishes binaries, not an image, so this is built where the +# image is to live: +# +# docker build -f deploy/container/Dockerfile --build-arg VERSION=v0.11.1 \ +# -t registry.internal/llmgw:v0.11.1 . +# docker push registry.internal/llmgw:v0.11.1 +# +# The binary is static (CGO_ENABLED=0, as every release is), so the image is +# that one file on a base with nothing else in it: no shell, no package +# manager. `kubectl exec ... -- llmgw ctl status` still works, because it +# runs the binary rather than a shell. +# +# Only the control plane runs from it. An agent installs engines on its +# machine, manages its GPUs and supervises processes there as root, which is +# what a container is built to prevent: docs/kubernetes.md. + +FROM golang:1.26 AS build +WORKDIR /src +COPY go.mod go.sum ./ +RUN go mod download +COPY . . +ARG VERSION=dev +RUN CGO_ENABLED=0 go build -trimpath \ + -ldflags "-s -w -X gitea.mynodes.xyz/ilker/llmgw/internal/version.Version=${VERSION}" \ + -o /out/llmgw ./cmd/llmgw && \ + mkdir -p /out/state + +FROM gcr.io/distroless/static-debian12:nonroot +COPY --from=build /out/llmgw /usr/local/bin/llmgw +# The chart mounts server.yaml, the certificates and the token under +# /etc/llmgw, and the SQLite store, when it is one, under /var/lib/llmgw — +# owned by the user the server runs as, so a volume Docker fills from the +# image is writable without Kubernetes' fsGroup. +COPY --from=build --chown=65532:65532 /out/state /var/lib/llmgw +USER 65532:65532 +EXPOSE 8080 7443 9091 +ENTRYPOINT ["/usr/local/bin/llmgw"] +CMD ["server", "--config", "/etc/llmgw/server.yaml"] diff --git a/deploy/eval/arithmetic.yaml b/deploy/eval/arithmetic.yaml new file mode 100644 index 00000000..c1bf1aea --- /dev/null +++ b/deploy/eval/arithmetic.yaml @@ -0,0 +1,58 @@ +# Arithmetic a small instruction model gets right: sums, products and a +# little reading, each answer scored by the last number in it. A quantisation +# that has gone wrong, or a chat template that no longer matches the +# weights, shows up here as a falling score long before anyone notices it in +# conversation. +# +# llmgw ctl eval MODEL --suite arithmetic +# llmgw ctl model update MODEL --eval arithmetic --min-score 0.8 +# +# Copy it into control.eval_dir (/etc/llmgw/eval) to change it; a suite +# there of the same name replaces this one. +name: arithmetic +description: Sums, products and word problems, each scored by the number in its answer. +threshold: 0.7 +system: You are a careful calculator. Answer with the number only, without words or units. +max_tokens: 64 +cases: + - id: add-small + prompt: What is 17 + 25? + number: 42 + - id: add-carry + prompt: What is 389 + 476? + number: 865 + - id: subtract + prompt: What is 1000 - 357? + number: 643 + - id: subtract-negative + prompt: What is 12 - 30? + number: -18 + - id: multiply + prompt: What is 12 * 12? + number: 144 + - id: multiply-larger + prompt: What is 23 * 17? + number: 391 + weight: 2 + - id: divide + prompt: What is 144 / 6? + number: 24 + - id: decimal + prompt: What is 2.5 * 4? + number: 10 + - id: percent + prompt: What is 15% of 200? + number: 30 + - id: words-apples + prompt: Ana has 7 apples and buys 5 more, then gives 3 away. How many apples does she have? + number: 9 + weight: 2 + - id: words-time + prompt: A train leaves at 14:00 and the trip takes 150 minutes. How many hours does the trip take? + number: 2.5 + tolerance: 0.01 + weight: 2 + - id: order-of-operations + prompt: What is 2 + 3 * 4? + number: 14 + weight: 2 diff --git a/deploy/eval/json-format.yaml b/deploy/eval/json-format.yaml new file mode 100644 index 00000000..f23e5a48 --- /dev/null +++ b/deploy/eval/json-format.yaml @@ -0,0 +1,94 @@ +# Following a format: asked for JSON of a given shape, does the model give +# it — the thing an application parsing its answers depends on, and the +# first to go when a chat template drifts. Each answer is read as JSON (a +# code fence or a sentence around it is forgiven) and held to a schema. +# +# llmgw ctl eval MODEL --suite json-format +# +# Copy it into control.eval_dir (/etc/llmgw/eval) to change it; a suite +# there of the same name replaces this one. +name: json-format +description: Answers asked for as JSON of a given shape, held to a schema. +threshold: 0.7 +system: You answer with a single JSON value and nothing else. +max_tokens: 200 +cases: + - id: person + prompt: >- + Give a JSON object for a person named Ada Lovelace, born in 1815, with the + keys "name" (a string) and "born" (a number). + json_schema: + type: object + required: [name, born] + properties: + name: {type: string, pattern: "Ada"} + born: {type: integer, minimum: 1815, maximum: 1815} + + - id: list-of-colours + prompt: Give a JSON array of exactly three colour names, as strings. + json_schema: + type: array + minItems: 3 + maxItems: 3 + items: {type: string, minLength: 1} + + - id: boolean-answer + prompt: >- + Is water wet? Answer as a JSON object with one key, "answer", whose + value is true or false. + json_schema: + type: object + required: [answer] + properties: + answer: {type: boolean} + + - id: nested + prompt: >- + Give a JSON object describing a book: "title" (a string), "author" (an + object with "first" and "last", both strings) and "pages" (a whole number + above zero). Use any book. + json_schema: + type: object + required: [title, author, pages] + properties: + title: {type: string, minLength: 1} + author: + type: object + required: [first, last] + properties: + first: {type: string} + last: {type: string} + pages: {type: integer, exclusiveMinimum: 0} + weight: 2 + + - id: enum-choice + prompt: >- + Classify the sentence "I love this product!" as positive, negative or + neutral. Answer as a JSON object {"sentiment": "..."} using one of those + three words in lower case. + json_schema: + type: object + required: [sentiment] + properties: + sentiment: {enum: [positive]} + weight: 2 + + - id: numbers + prompt: 'Give a JSON object {"sum": N} where N is the sum of 4, 5 and 6.' + json_schema: + type: object + required: [sum] + properties: + sum: {const: 15} + + - id: no-extra-keys + prompt: >- + Give a JSON object with exactly two keys, "city" and "country", for + Paris. No other keys. + json_schema: + type: object + required: [city, country] + additionalProperties: false + properties: + city: {type: string} + country: {type: string} diff --git a/deploy/examples/server.yaml b/deploy/examples/server.yaml index 5f6edf4f..8f6d9f6d 100644 --- a/deploy/examples/server.yaml +++ b/deploy/examples/server.yaml @@ -159,6 +159,12 @@ router: # back to a client that did not ask for it. inject_usage: true max_body_bytes: 33554432 + # Memory for the answers of projects that reuse them (llmgw keys cache), + # all together; the least recently used go first. Nothing is reused until a + # project turns it on. + # cache: + # max_bytes: 134217728 # 128 MB + # max_entry_bytes: 1048576 # 1 MB timeouts: dial: 5s diff --git a/deploy/helm/llmgw/Chart.yaml b/deploy/helm/llmgw/Chart.yaml new file mode 100644 index 00000000..e2d899ab --- /dev/null +++ b/deploy/helm/llmgw/Chart.yaml @@ -0,0 +1,17 @@ +apiVersion: v2 +name: llmgw +description: >- + The llmgw control plane — the OpenAI-compatible gateway, the router and the + scheduler that places models on GPU and CPU nodes. The nodes themselves run + outside Kubernetes; see docs/kubernetes.md. +type: application +# The chart's own version; appVersion is the llmgw release the image holds. +version: 0.1.0 +appVersion: "v0.11.1" +home: https://gitea.mynodes.xyz/ilker/llmgw +sources: + - https://gitea.mynodes.xyz/ilker/llmgw +keywords: + - llm + - gateway + - inference diff --git a/deploy/helm/llmgw/templates/NOTES.txt b/deploy/helm/llmgw/templates/NOTES.txt new file mode 100644 index 00000000..52912cac --- /dev/null +++ b/deploy/helm/llmgw/templates/NOTES.txt @@ -0,0 +1,27 @@ +The llmgw control plane is starting as {{ include "llmgw.fullname" . }}. + +The admin API listens on the pod's loopback only. To reach it from here: + + kubectl -n {{ .Release.Namespace }} port-forward statefulset/{{ include "llmgw.fullname" . }} 9090:9090 & + export LLMGW_ADMIN_TOKEN=$(kubectl -n {{ .Release.Namespace }} get secret {{ include "llmgw.adminSecret" . }} \ + -o jsonpath='{.data.{{ if .Values.adminToken.existingSecret }}{{ .Values.adminToken.secretKey }}{{ else }}admin-token{{ end }}}' | base64 -d) + llmgw ctl status + +The first administrator: + + kubectl -n {{ .Release.Namespace }} exec -it statefulset/{{ include "llmgw.fullname" . }} -- \ + llmgw users create you@example.com --password '' + kubectl -n {{ .Release.Namespace }} exec -it statefulset/{{ include "llmgw.fullname" . }} -- \ + llmgw users role you@example.com admin + +Agents connect to the {{ include "llmgw.fullname" . }}-agents Service on port {{ .Values.agentService.port }}: + + kubectl -n {{ .Release.Namespace }} get service {{ include "llmgw.fullname" . }}-agents + +Its address must be in the certificate in {{ .Values.agentTLS.existingSecret }}. Nodes join from +the machine holding llmgw's authority: + + sudo llmgw node add ubuntu@gpu01 --server https://:{{ .Values.agentService.port }} \ + --pki ./pki --admin 127.0.0.1:9090 + +docs/kubernetes.md has the rest, and why the nodes stay outside Kubernetes. diff --git a/deploy/helm/llmgw/templates/_helpers.tpl b/deploy/helm/llmgw/templates/_helpers.tpl new file mode 100644 index 00000000..388d2482 --- /dev/null +++ b/deploy/helm/llmgw/templates/_helpers.tpl @@ -0,0 +1,74 @@ +{{/* The release's name for everything the chart makes. */}} +{{- define "llmgw.fullname" -}} +{{- if contains .Chart.Name .Release.Name -}} +{{- .Release.Name | trunc 63 | trimSuffix "-" -}} +{{- else -}} +{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" -}} +{{- end -}} +{{- end -}} + +{{- define "llmgw.selectorLabels" -}} +app.kubernetes.io/name: {{ .Chart.Name }} +app.kubernetes.io/instance: {{ .Release.Name }} +{{- end -}} + +{{- define "llmgw.labels" -}} +{{ include "llmgw.selectorLabels" . }} +app.kubernetes.io/version: {{ .Values.image.tag | default .Chart.AppVersion | quote }} +app.kubernetes.io/managed-by: {{ .Release.Service }} +helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" }} +{{- end -}} + +{{- define "llmgw.image" -}} +{{- if not .Values.image.repository -}} +{{- fail "image.repository: the image built from deploy/container/Dockerfile, pushed where the cluster can pull it (the project publishes binaries, not an image)" -}} +{{- end -}} +{{- printf "%s:%s" .Values.image.repository (.Values.image.tag | default .Chart.AppVersion) -}} +{{- end -}} + +{{- define "llmgw.adminSecret" -}} +{{- .Values.adminToken.existingSecret | default (printf "%s-admin" (include "llmgw.fullname" .)) -}} +{{- end -}} + +{{/* +server.yaml: what the chart decides — listeners, where the certificates, +the token and the store are mounted — laid over .Values.config. The chart's +keys win, because each names a port or a path the pod is built around. +*/}} +{{- define "llmgw.serverConfig" -}} +{{- $store := "/var/lib/llmgw/llmgw.db" -}} +{{- if eq .Values.store.type "postgres" -}} +{{- $store = "@/etc/llmgw/store/dsn" -}} +{{- end -}} +{{- $base := dict + "listen" ":8080" + "admin_listen" "127.0.0.1:9090" + "metrics_listen" ":9091" + "agent_listen" ":7443" + "admin_token_file" "/etc/llmgw/admin/admin-token" + "agent_tls" (dict "ca" "/etc/llmgw/tls/ca.pem" "cert" "/etc/llmgw/tls/server.pem" "key" "/etc/llmgw/tls/server-key.pem") + "auth" (dict "store" $store) +-}} +{{- if .Values.offlineChecksums.configMap -}} +{{- $_ := set $base "offline" (dict "checksums" "/etc/llmgw/offline/offline.sha256") -}} +{{- end -}} +{{- $cfg := mustMergeOverwrite (deepCopy (.Values.config | default dict)) $base -}} +# Made by the llmgw Helm chart from its values. Every key: docs/reference.md +{{ toYaml $cfg }} +{{- end -}} + +{{/* Refuses values that would make a pod that cannot work. */}} +{{- define "llmgw.validate" -}} +{{- if not (has .Values.store.type (list "sqlite" "postgres")) -}} +{{- fail (printf "store.type %q: sqlite or postgres" .Values.store.type) -}} +{{- end -}} +{{- if ne (int .Values.replicas) 1 -}} +{{- fail "replicas: this chart runs one control plane; values.yaml says why" -}} +{{- end -}} +{{- if and (eq .Values.store.type "postgres") (not .Values.store.postgres.existingSecret) -}} +{{- fail "store.postgres.existingSecret: a Secret holding the PostgreSQL address" -}} +{{- end -}} +{{- if not .Values.agentTLS.existingSecret -}} +{{- fail "agentTLS.existingSecret: a Secret with ca.pem, server.pem and server-key.pem from llmgw's authority (see values.yaml)" -}} +{{- end -}} +{{- end -}} diff --git a/deploy/helm/llmgw/templates/configmap.yaml b/deploy/helm/llmgw/templates/configmap.yaml new file mode 100644 index 00000000..f4d63ddc --- /dev/null +++ b/deploy/helm/llmgw/templates/configmap.yaml @@ -0,0 +1,10 @@ +{{- include "llmgw.validate" . -}} +apiVersion: v1 +kind: ConfigMap +metadata: + name: {{ include "llmgw.fullname" . }} + labels: + {{- include "llmgw.labels" . | nindent 4 }} +data: + server.yaml: | + {{- include "llmgw.serverConfig" . | nindent 4 }} diff --git a/deploy/helm/llmgw/templates/ingress.yaml b/deploy/helm/llmgw/templates/ingress.yaml new file mode 100644 index 00000000..9d0d09b0 --- /dev/null +++ b/deploy/helm/llmgw/templates/ingress.yaml @@ -0,0 +1,37 @@ +{{- if .Values.ingress.enabled }} +# The OpenAI-compatible API, the portal and the chat page on port 8080. Never +# the agent port: its mutual TLS cannot pass through an HTTP proxy. +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: {{ include "llmgw.fullname" . }} + labels: + {{- include "llmgw.labels" . | nindent 4 }} + {{- with .Values.ingress.annotations }} + annotations: + {{- toYaml . | nindent 4 }} + {{- end }} +spec: + {{- with .Values.ingress.className }} + ingressClassName: {{ . }} + {{- end }} + {{- with .Values.ingress.tls }} + tls: + {{- toYaml . | nindent 4 }} + {{- end }} + rules: + {{- range .Values.ingress.hosts }} + - host: {{ .host | quote }} + http: + paths: + {{- range .paths }} + - path: {{ .path }} + pathType: {{ .pathType }} + backend: + service: + name: {{ include "llmgw.fullname" $ }} + port: + name: api + {{- end }} + {{- end }} +{{- end }} diff --git a/deploy/helm/llmgw/templates/secret-admin.yaml b/deploy/helm/llmgw/templates/secret-admin.yaml new file mode 100644 index 00000000..69f9f637 --- /dev/null +++ b/deploy/helm/llmgw/templates/secret-admin.yaml @@ -0,0 +1,19 @@ +{{- if not .Values.adminToken.existingSecret }} +{{- $name := include "llmgw.adminSecret" . }} +{{- $token := randAlphaNum 64 }} +{{- /* Kept across upgrades: a new token on every upgrade would lock out every console holding the old one. */}} +{{- with lookup "v1" "Secret" .Release.Namespace $name }} +{{- $token = index .data "admin-token" | b64dec }} +{{- end }} +apiVersion: v1 +kind: Secret +metadata: + name: {{ $name }} + labels: + {{- include "llmgw.labels" . | nindent 4 }} + annotations: + helm.sh/resource-policy: keep +type: Opaque +data: + admin-token: {{ $token | b64enc | quote }} +{{- end }} diff --git a/deploy/helm/llmgw/templates/servicemonitor.yaml b/deploy/helm/llmgw/templates/servicemonitor.yaml new file mode 100644 index 00000000..a060466e --- /dev/null +++ b/deploy/helm/llmgw/templates/servicemonitor.yaml @@ -0,0 +1,21 @@ +{{- if .Values.serviceMonitor.enabled }} +# For the Prometheus Operator: the metrics port, which serves metrics and +# nothing else. deploy/monitoring holds the rules and dashboards that read them. +apiVersion: monitoring.coreos.com/v1 +kind: ServiceMonitor +metadata: + name: {{ include "llmgw.fullname" . }} + labels: + {{- include "llmgw.labels" . | nindent 4 }} + {{- with .Values.serviceMonitor.labels }} + {{- toYaml . | nindent 4 }} + {{- end }} +spec: + selector: + matchLabels: + {{- include "llmgw.selectorLabels" . | nindent 6 }} + endpoints: + - port: metrics + path: /metrics + interval: {{ .Values.serviceMonitor.interval }} +{{- end }} diff --git a/deploy/helm/llmgw/templates/services.yaml b/deploy/helm/llmgw/templates/services.yaml new file mode 100644 index 00000000..e599b58d --- /dev/null +++ b/deploy/helm/llmgw/templates/services.yaml @@ -0,0 +1,70 @@ +# The API and the metrics, for the cluster and an Ingress. +apiVersion: v1 +kind: Service +metadata: + name: {{ include "llmgw.fullname" . }} + labels: + {{- include "llmgw.labels" . | nindent 4 }} + {{- with .Values.service.annotations }} + annotations: + {{- toYaml . | nindent 4 }} + {{- end }} +spec: + type: {{ .Values.service.type }} + selector: + {{- include "llmgw.selectorLabels" . | nindent 4 }} + ports: + - name: api + port: {{ .Values.service.port }} + targetPort: api + - name: metrics + port: {{ .Values.service.metricsPort }} + targetPort: metrics +--- +# Where agents on the nodes connect. Mutual TLS ends in the pod: whatever is +# in between must pass TCP through untouched. +apiVersion: v1 +kind: Service +metadata: + name: {{ include "llmgw.fullname" . }}-agents + labels: + {{- include "llmgw.labels" . | nindent 4 }} + {{- with .Values.agentService.annotations }} + annotations: + {{- toYaml . | nindent 4 }} + {{- end }} +spec: + type: {{ .Values.agentService.type }} + {{- if and (eq .Values.agentService.type "LoadBalancer") .Values.agentService.loadBalancerIP }} + loadBalancerIP: {{ .Values.agentService.loadBalancerIP }} + {{- end }} + {{- with .Values.agentService.loadBalancerSourceRanges }} + loadBalancerSourceRanges: + {{- toYaml . | nindent 4 }} + {{- end }} + {{- if has .Values.agentService.type (list "LoadBalancer" "NodePort") }} + externalTrafficPolicy: {{ .Values.agentService.externalTrafficPolicy }} + {{- end }} + selector: + {{- include "llmgw.selectorLabels" . | nindent 4 }} + ports: + - name: agents + port: {{ .Values.agentService.port }} + targetPort: agents +--- +# The StatefulSet's own, giving each pod a stable name. +apiVersion: v1 +kind: Service +metadata: + name: {{ include "llmgw.fullname" . }}-headless + labels: + {{- include "llmgw.labels" . | nindent 4 }} +spec: + clusterIP: None + publishNotReadyAddresses: true + selector: + {{- include "llmgw.selectorLabels" . | nindent 4 }} + ports: + - name: api + port: 8080 + targetPort: api diff --git a/deploy/helm/llmgw/templates/statefulset.yaml b/deploy/helm/llmgw/templates/statefulset.yaml new file mode 100644 index 00000000..da11cd05 --- /dev/null +++ b/deploy/helm/llmgw/templates/statefulset.yaml @@ -0,0 +1,181 @@ +apiVersion: apps/v1 +kind: StatefulSet +metadata: + name: {{ include "llmgw.fullname" . }} + labels: + {{- include "llmgw.labels" . | nindent 4 }} +spec: + # One control plane: Kubernetes replaces it within seconds when it goes, + # and the agents reconnect on their own. See replicas in values.yaml. + replicas: 1 + serviceName: {{ include "llmgw.fullname" . }}-headless + selector: + matchLabels: + {{- include "llmgw.selectorLabels" . | nindent 6 }} + template: + metadata: + labels: + {{- include "llmgw.selectorLabels" . | nindent 8 }} + {{- with .Values.podLabels }} + {{- toYaml . | nindent 8 }} + {{- end }} + annotations: + # server.yaml is read at start: a changed one restarts the pod. + checksum/config: {{ include "llmgw.serverConfig" . | sha256sum }} + {{- with .Values.podAnnotations }} + {{- toYaml . | nindent 8 }} + {{- end }} + spec: + {{- with .Values.imagePullSecrets }} + imagePullSecrets: + {{- toYaml . | nindent 8 }} + {{- end }} + # Agents reconnect within seconds of a control plane going; a long + # grace period only delays the one that replaces it. + terminationGracePeriodSeconds: 30 + securityContext: + runAsNonRoot: true + runAsUser: 65532 + runAsGroup: 65532 + fsGroup: 65532 + seccompProfile: + type: RuntimeDefault + containers: + - name: llmgw + image: {{ include "llmgw.image" . }} + imagePullPolicy: {{ .Values.image.pullPolicy }} + args: ["server", "--config", "/etc/llmgw/server.yaml"] + env: + # For `kubectl exec ... -- llmgw ctl`, which reads the token + # from here; the server reads admin_token_file. + - name: LLMGW_ADMIN_TOKEN + valueFrom: + secretKeyRef: + name: {{ include "llmgw.adminSecret" . }} + key: {{ if .Values.adminToken.existingSecret }}{{ .Values.adminToken.secretKey }}{{ else }}admin-token{{ end }} + ports: + - name: api + containerPort: 8080 + - name: agents + containerPort: 7443 + - name: metrics + containerPort: 9091 + # Up is /health. Ready is /leader: a control plane holds the + # agents' connections and places models only once it leads — on + # PostgreSQL, once the lease of the one it replaced has run out. A + # cluster with no node yet is still ready: /ready would wait for a + # replica, and nodes could then never connect. + startupProbe: + httpGet: {path: /health, port: api} + periodSeconds: 5 + failureThreshold: 60 + livenessProbe: + httpGet: {path: /health, port: api} + periodSeconds: 10 + failureThreshold: 6 + readinessProbe: + httpGet: {path: /leader, port: api} + periodSeconds: 5 + failureThreshold: 2 + securityContext: + allowPrivilegeEscalation: false + readOnlyRootFilesystem: true + capabilities: + drop: ["ALL"] + resources: + {{- toYaml .Values.resources | nindent 12 }} + volumeMounts: + - name: config + mountPath: /etc/llmgw/server.yaml + subPath: server.yaml + readOnly: true + - name: agent-tls + mountPath: /etc/llmgw/tls + readOnly: true + - name: admin-token + mountPath: /etc/llmgw/admin + readOnly: true + {{- if eq .Values.store.type "postgres" }} + - name: store + mountPath: /etc/llmgw/store + readOnly: true + {{- end }} + {{- if .Values.offlineChecksums.configMap }} + - name: offline + mountPath: /etc/llmgw/offline + readOnly: true + {{- end }} + - name: data + mountPath: /var/lib/llmgw + - name: tmp + mountPath: /tmp + volumes: + - name: config + configMap: + name: {{ include "llmgw.fullname" . }} + - name: agent-tls + secret: + secretName: {{ .Values.agentTLS.existingSecret }} + defaultMode: 0440 + items: + - {key: ca.pem, path: ca.pem} + - {key: server.pem, path: server.pem} + - {key: server-key.pem, path: server-key.pem} + - name: admin-token + secret: + secretName: {{ include "llmgw.adminSecret" . }} + defaultMode: 0440 + items: + - key: {{ if .Values.adminToken.existingSecret }}{{ .Values.adminToken.secretKey }}{{ else }}admin-token{{ end }} + path: admin-token + {{- if eq .Values.store.type "postgres" }} + - name: store + secret: + secretName: {{ .Values.store.postgres.existingSecret }} + defaultMode: 0440 + items: + - key: {{ .Values.store.postgres.secretKey }} + path: dsn + {{- end }} + {{- if .Values.offlineChecksums.configMap }} + - name: offline + configMap: + name: {{ .Values.offlineChecksums.configMap }} + items: + - key: {{ .Values.offlineChecksums.key }} + path: offline.sha256 + {{- end }} + - name: tmp + emptyDir: {} + {{- if eq .Values.store.type "postgres" }} + # The store is PostgreSQL; nothing here outlives the pod. + - name: data + emptyDir: {} + {{- end }} + {{- with .Values.nodeSelector }} + nodeSelector: + {{- toYaml . | nindent 8 }} + {{- end }} + {{- with .Values.tolerations }} + tolerations: + {{- toYaml . | nindent 8 }} + {{- end }} + {{- with .Values.affinity }} + affinity: + {{- toYaml . | nindent 8 }} + {{- end }} + {{- if eq .Values.store.type "sqlite" }} + volumeClaimTemplates: + - metadata: + name: data + labels: + {{- include "llmgw.selectorLabels" . | nindent 10 }} + spec: + accessModes: ["ReadWriteOnce"] + {{- with .Values.store.sqlite.storageClass }} + storageClassName: {{ . }} + {{- end }} + resources: + requests: + storage: {{ .Values.store.sqlite.size }} + {{- end }} diff --git a/deploy/helm/llmgw/values.yaml b/deploy/helm/llmgw/values.yaml new file mode 100644 index 00000000..b989ccca --- /dev/null +++ b/deploy/helm/llmgw/values.yaml @@ -0,0 +1,132 @@ +# The llmgw control plane in Kubernetes. docs/kubernetes.md says what this +# runs, what it does not, and how nodes outside the cluster join it. + +image: + # Where you pushed the image built from deploy/container/Dockerfile. The + # project publishes binaries, not an image, so this has no default. + repository: "" + # Empty takes the chart's appVersion. + tag: "" + pullPolicy: IfNotPresent +imagePullSecrets: [] + +# One control plane, always. Two against PostgreSQL would elect a leader and +# keep a standby, but a standby serves nothing and is never ready, so a +# rollout would wait on it for ever. Until the chart handles that, it runs +# one: Kubernetes replaces it within seconds when it goes, and the agents +# reconnect on their own. +replicas: 1 + +store: + # sqlite: a file on a PersistentVolumeClaim, for one replica. + # postgres: a PostgreSQL you run, its address in a Secret. + type: sqlite + sqlite: + size: 10Gi + storageClass: "" + postgres: + # A Secret holding the address, postgres://user:password@host:5432/llmgw?sslmode=verify-full + existingSecret: "" + secretKey: dsn + +# The agent port's certificate. It comes from llmgw's own authority, not a +# public one — agents present certificates from the same authority — so it +# is made outside the cluster, where the authority's key stays: +# +# llmgw ctl cert init-ca --dir ./pki +# llmgw ctl cert issue-server llmgw-ctl --host --dir ./pki --out ./pki +# kubectl create secret generic llmgw-agent-tls \ +# --from-file=ca.pem=pki/ca.pem \ +# --from-file=server.pem=pki/server.pem \ +# --from-file=server-key.pem=pki/server-key.pem +# +# --host is every address agents dial: agentService's load balancer address +# or DNS name. +agentTLS: + existingSecret: "" + +# The admin API's token (llmgw ctl, the console). Empty makes one, kept in a +# Secret across upgrades. +adminToken: + existingSecret: "" + secretKey: admin-token + +# server.yaml beyond what the chart sets (listeners, TLS, store, admin +# token): any key of docs/reference.md, laid over the chart's. An offline +# cluster sets offline.mirror here, and offlineChecksums below. +config: + control: + enabled: true + auth: + enabled: true + signup_open: false + default_rpm: 60 + default_tpm: 200000 + default_price: + prompt_per_1k: 1000 + completion_per_1k: 1000 + max_key_ttl: 2160h + # mirror: + # api: https://models.internal:8082 + # offline: + # mirror: http://models.internal:8081 + # firewall_networks: ["10.42.0.0/16"] # the pods' network, so nodes' engines answer the router + +# On an offline cluster, a ConfigMap or Secret holding the engine checksums +# 'llmgw bundle trust' writes (offline.sha256), mounted where offline.checksums +# points. Empty mounts none. +offlineChecksums: + configMap: "" + key: offline.sha256 + +# The OpenAI-compatible API and the metrics, inside the cluster. +service: + type: ClusterIP + port: 8080 + metricsPort: 9091 + annotations: {} + +# Where agents connect, with mutual TLS. Nodes run outside the cluster, so +# this is a load balancer by default; the TLS ends in the pod, never at a +# proxy in between. +agentService: + type: LoadBalancer + port: 7443 + annotations: {} + loadBalancerIP: "" + loadBalancerSourceRanges: [] + # Keeps the agents' addresses as they are, which the node's identity does + # not need but the logs and the audit read better with. + externalTrafficPolicy: Local + +ingress: + enabled: false + className: "" + annotations: {} + hosts: + - host: llm.example.com + paths: + - path: / + pathType: Prefix + tls: [] + # - secretName: llm-example-com + # hosts: [llm.example.com] + +# A ServiceMonitor for the Prometheus Operator, scraping the metrics port. +serviceMonitor: + enabled: false + interval: 30s + labels: {} + +resources: + requests: + cpu: 500m + memory: 512Mi + limits: + memory: 2Gi + +nodeSelector: {} +tolerations: [] +affinity: {} +podAnnotations: {} +podLabels: {} diff --git a/deploy/mirror/README.md b/deploy/mirror/README.md index 44d3bf6a..9a5ee541 100644 --- a/deploy/mirror/README.md +++ b/deploy/mirror/README.md @@ -25,6 +25,13 @@ An HTTP server serving a directory. That is the whole design. model.safetensors ``` +At an offline site the mirror also holds what the nodes would otherwise fetch +from the internet — llmgw's releases and the llama.cpp builds — under +`_llmgw/releases/` and `_llmgw/engines/`, put there by `llmgw bundle import` +(docs/install.md, "Offline sites"). They are not models: `mirror list` and +`mirror unused` pass over them, and a node checks each against what the +control plane says it must be, not against anything the mirror says. + The date in the path is the point of the layout, not decoration. A model repository that changes upstream changes what you are running, and the first sign is a prompt that worked last week answering differently this week with diff --git a/deploy/monitoring/llmgw-rules.yml b/deploy/monitoring/llmgw-rules.yml index 1055462f..341df173 100644 --- a/deploy/monitoring/llmgw-rules.yml +++ b/deploy/monitoring/llmgw-rules.yml @@ -555,3 +555,32 @@ groups: It was stopped or rewritten if the policy enforces; either way a model has seen it, in its prompt or its training. The usage rows with guard_category secret say which request. + + - name: llmgw-slo + rules: + - alert: ModelTTFTOverSLO + expr: >- + histogram_quantile(0.99, sum by (le, model) (rate(llmgw_ttft_seconds_bucket[10m]))) + > on (model) group_left llmgw_model_slo_seconds{kind="ttft_p99"} + for: 15m + labels: { severity: warning } + annotations: + summary: "{{ $labels.model }} answers its first token past its SLO at p99" + description: >- + The p99 time to the first token over ten minutes is past the + model's slo.ttft_p99. Admission already holds the lower bands back + while it is; this says it has lasted. More replicas, or less + traffic in the bands above. + + - alert: ModelTPOTOverSLO + expr: >- + histogram_quantile(0.99, sum by (le, model) (rate(llmgw_tpot_seconds_bucket[10m]))) + > on (model) group_left llmgw_model_slo_seconds{kind="tpot_p99"} + for: 15m + labels: { severity: warning } + annotations: + summary: "{{ $labels.model }} produces tokens slower than its SLO at p99" + description: >- + The p99 time per output token is past slo.tpot_p99: replicas are + batching more than they can decode quickly, or a slower card is + serving. llmgw_output_tokens_per_second by pool says which. diff --git a/docs.go b/docs.go index 11e35bcd..ff3b4490 100644 --- a/docs.go +++ b/docs.go @@ -1,10 +1,103 @@ -// Package llmgw holds what the binary carries besides code: its manual. +// Package llmgw holds what the binary carries besides code: its manual, the +// description of its admin API, and the example quality suites. package llmgw -import "embed" +import ( + "embed" + "io/fs" + "sort" + "strings" +) // Docs is the documentation, read on any machine by `llmgw docs` and the // console's manual without a checkout or the internet. // //go:embed README.md CHANGELOG.md docs/*.md var Docs embed.FS + +// Doc is one page of the manual. +type Doc struct { + // Key is what `llmgw docs KEY` takes, and the page's address under /docs/ + // on the gateway. + Key string + // Path is the file in Docs. + Path string + // Title is the document's first heading. + Title string +} + +// Source is the document's markdown. +func (d Doc) Source() string { + b, err := fs.ReadFile(Docs, d.Path) + if err != nil { + return "# " + d.Path + "\n\nNot in this build." + } + return string(b) +} + +// docOrder is the documents in the order someone new reads them. Here rather +// than with either reader, because the console's manual and the gateway's +// docs portal both list them, and two lists drift. +var docOrder = []string{"console", "quick-install", "install", "node-onboarding", "onboarding", + "clients", "guardrails", "choosing-models", "fabrics", "facility-aware-placement", "data", + "reference", "development"} + +// Manual is every document, in reading order: those docOrder names, then any +// other under docs/ alphabetically, so a new one is never missing, then the +// README and the changes. +func Manual() []Doc { + var out []Doc + seen := map[string]bool{} + add := func(key, path string) { + if seen[key] { + return + } + b, err := fs.ReadFile(Docs, path) + if err != nil { + return + } + seen[key] = true + out = append(out, Doc{Key: key, Path: path, Title: titleOf(string(b), path)}) + } + for _, k := range docOrder { + add(k, "docs/"+k+".md") + } + entries, _ := fs.ReadDir(Docs, "docs") + var rest []string + for _, e := range entries { + if strings.HasSuffix(e.Name(), ".md") { + rest = append(rest, strings.TrimSuffix(e.Name(), ".md")) + } + } + sort.Strings(rest) + for _, k := range rest { + add(k, "docs/"+k+".md") + } + add("readme", "README.md") + add("changes", "CHANGELOG.md") + return out +} + +// titleOf is a document's first top-level heading, or its path when it has +// none. +func titleOf(src, path string) string { + for _, l := range strings.Split(src, "\n") { + if strings.HasPrefix(l, "# ") { + return strings.TrimSpace(strings.TrimPrefix(l, "# ")) + } + } + return path +} + +// AdminOpenAPI is the admin API described in OpenAPI 3.1, generated from its +// route table by `go generate` in internal/docgen and served at +// /api/v1/openapi.json, so a client can be pointed at the server it talks to. +// +//go:embed docs/admin-api.openapi.json +var AdminOpenAPI []byte + +// EvalSuites are the example quality suites under deploy/eval, which the +// control plane runs by name when its eval directory has none of the name. +// +//go:embed deploy/eval/*.yaml +var EvalSuites embed.FS diff --git a/docs/admin-api.md b/docs/admin-api.md new file mode 100644 index 00000000..964969e4 --- /dev/null +++ b/docs/admin-api.md @@ -0,0 +1,160 @@ +# The admin API + +Written for whoever automates a cluster rather than typing at it: how to reach +the control plane's management API, what it asks of a request, and where its +description is. + +`llmgw ctl` and the console are clients of this API and nothing more, so +anything they do can be done with `curl`, a generated client or the +[Terraform provider](../terraform-provider-llmgw/README.md). It adds and +removes models, scales them, cordons and upgrades nodes, sets capacity +quotas, attaches guardrail policies, and reads the fleet, usage and the audit +log. + +## Reaching it + +The API is under `/api/v1` on the admin listener, `admin_listen` in +`/etc/llmgw/server.yaml`: `127.0.0.1:9090` unless changed. It is on loopback +on purpose. The same listener serves pprof when it is turned on, and the +server refuses to start with it on any other address unless +`admin_remote: true` — the token would cross the network in clear. + +From another machine, tunnel to it rather than moving it: + +```sh +ssh -N -L 9090:127.0.0.1:9090 admin@control-plane & +curl -s -H "Authorization: Bearer $LLMGW_ADMIN_TOKEN" http://127.0.0.1:9090/api/v1/summary +``` + +With `admin_remote: true` and `admin_listen: 10.0.0.5:9090`, call that address +directly — on a network you trust, or behind a TLS proxy that keeps the +`Host` header an address. + +## The token + +Every path under `/api` needs the admin token as a bearer token: + +``` +Authorization: Bearer 6f1c… +``` + +The server writes it the first time it starts, 0600, to +`/var/lib/llmgw/admin-token` under its systemd unit (`admin_token_file` +moves it; a server run by hand keeps it in `secrets/admin-token` beside its +configuration). `llmgw ctl` reads it from there, which is why it runs with +sudo, or from `LLMGW_ADMIN_TOKEN`. To give it to automation: + +```sh +sudo cat /var/lib/llmgw/admin-token +``` + +The token is the whole of the API's authorisation: whoever holds it can do +everything the API does. Keep it where you keep other root credentials. + +## What a request must look like + +Besides the token, the listener refuses three things before a handler sees +them, as defences against a browser being turned against it: + +- **A name in `Host`.** The listener answers to an address or `localhost`, + not a DNS name, so a page on some other site cannot reach it by rebinding + a name to 127.0.0.1. Call it as `http://127.0.0.1:9090`, not + `http://cp.example.com:9090`; behind a proxy, have the proxy send an + address. +- **A cross-site request.** One whose `Origin` is another host, or whose + `Sec-Fetch-Site` says another site sent it. +- **A change that is not JSON.** Every method but `GET` and `HEAD` must carry + `Content-Type: application/json`, even a `DELETE` or a `POST` with no body. + A form post from a page cannot set that header. + +A change is recorded in the audit log with who made it, as the request says +in `X-Llmgw-Actor` (letters, digits and `._-@`, at most 64; `unknown` when +absent). `llmgw ctl` sends the name of whoever ran it; automation should send +its own, `terraform` or `ci@deploy`, so `llmgw ctl audit` can tell them apart. + +A refusal is a 4xx or 5xx with `{"error": "…"}` saying why. 501 means this +control plane lacks what the endpoint needs — a store, a mirror, guard +policies — and says which. + +## Some calls + +```sh +H=(-H "Authorization: Bearer $LLMGW_ADMIN_TOKEN" -H "Content-Type: application/json" -H "X-Llmgw-Actor: $USER") +API=http://127.0.0.1:9090/api/v1 + +# The fleet in one answer, and every model. +curl -s "${H[@]}" $API/summary +curl -s "${H[@]}" $API/models + +# Add a model, read back its definition with the defaults filled in, scale it. +curl -s "${H[@]}" -X POST $API/models -d '{ + "name": "qwen-small", + "source": "/srv/models/qwen2.5-1.5b-instruct-q4_k_m.gguf", + "profiles": [{"name": "cpu", "engine": "llamacpp", "min_memory_gb": 4, "cpu_cores": 4}], + "scaling": {"min": 1, "max": 2} +}' +curl -s "${H[@]}" $API/models/qwen-small +curl -s "${H[@]}" -X POST $API/models/qwen-small/scale -d '{"min": 0, "max": 2, "idle_timeout": 1800000000000}' + +# A team's capacity quota. +curl -s "${H[@]}" -X PUT $API/quotas -d '{"scope": "team:Acme/ml", "limit": {"gpus": 8}}' + +# Remove the model; a DELETE carries the content type too. +curl -s "${H[@]}" -X DELETE $API/models/qwen-small +``` + +Durations in bodies are integer nanoseconds, as Go encodes them: half an hour +is `1800000000000`. + +## The description + +The API is described in OpenAPI 3.1: + +- served by every control plane at `GET /api/v1/openapi.json` (with the + token, like the rest), as built into that binary, so it describes the + server you are talking to; +- committed as [admin-api.openapi.json](admin-api.openapi.json) for reading + without a cluster. + +```sh +curl -s "${H[@]}" $API/openapi.json > llmgw-admin.json +``` + +It lists every endpoint, its path and query parameters, and the schema of +each request and answer, with the meaning of each field. Load it into any +OpenAPI tool — Swagger UI, Redoc, an editor — or generate a client from it: + +```sh +docker run --rm -v "$PWD:/w" openapitools/openapi-generator-cli generate \ + -i /w/llmgw-admin.json -g python -o /w/llmgw-admin-client +``` + +### How it is kept true + +The document is generated, not written. `internal/control/adminapi/routes.go` +holds a table of every endpoint: its method and path, a summary, its query +parameters, and Go values of the types it reads and answers with. The +generator in `internal/docgen/openapi` reads those types by reflection, the +way `encoding/json` encodes them, and takes each field's description from its +comment in the source. + +Two tests keep it from drifting. One registers the API on a recording mux and +fails when an endpoint is served and not in the table, or in the table and not +served. The other regenerates the document and fails when it differs from the +committed one. After changing an endpoint or a type it carries: + +```sh +go generate ./internal/docgen +``` + +## What it does not cover + +- **Organizations, teams, projects, people and API keys.** These live in the + store and are managed with `llmgw org`, `llmgw users` and `llmgw keys` on the + control plane, or in the web console's `/admin` pages on the client port + behind a session. The admin API reads the tree only where a quota or a + policy names a part of it. +- **The client-facing API** (`/v1/chat/completions` and the rest), which is + OpenAI's and Anthropic's, on `listen`, with API keys. +- **The rest of the admin listener**: `/metrics`, `/health`, the dashboard + pages and `/debug/pprof`, which are not under `/api`. diff --git a/docs/admin-api.openapi.json b/docs/admin-api.openapi.json new file mode 100644 index 00000000..3b255bb7 --- /dev/null +++ b/docs/admin-api.openapi.json @@ -0,0 +1,7466 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "llmgw admin API", + "version": "v1", + "description": "The control plane's management API: what `llmgw ctl` and the console use.\n\nIt is served on the admin listener (admin_listen, 127.0.0.1:9090 by default), which stays on loopback unless admin_remote is set: reach it from elsewhere through an SSH tunnel. Every path under /api needs the admin token as a bearer token.\n\nThe listener also refuses, before the token is looked at: a Host header that is a name rather than an address or localhost; a request another site's page sent; and any method but GET and HEAD whose Content-Type is not application/json, even one with no body.\n\nDurations in bodies are integer nanoseconds, as Go encodes them. Generated from the route table in internal/control/adminapi; see docs/admin-api.md." + }, + "servers": [ + { + "url": "http://127.0.0.1:9090", + "description": "The admin listener at its default address, admin_listen." + } + ], + "security": [ + { + "adminToken": [] + } + ], + "tags": [ + { + "name": "audit" + }, + { + "name": "canaries" + }, + { + "name": "capacity" + }, + { + "name": "eval" + }, + { + "name": "explain-placement" + }, + { + "name": "fabric-test" + }, + { + "name": "fabrics" + }, + { + "name": "facility" + }, + { + "name": "federation" + }, + { + "name": "guard" + }, + { + "name": "jobs" + }, + { + "name": "metrics" + }, + { + "name": "models" + }, + { + "name": "nodes" + }, + { + "name": "notify" + }, + { + "name": "nvlink" + }, + { + "name": "openapi" + }, + { + "name": "plan" + }, + { + "name": "quotas" + }, + { + "name": "replicas" + }, + { + "name": "requests" + }, + { + "name": "restart" + }, + { + "name": "summary" + }, + { + "name": "updates" + }, + { + "name": "usage" + }, + { + "name": "weights" + } + ], + "paths": { + "/api/v1/audit": { + "get": { + "operationId": "getAudit", + "summary": "Changes made, newest first", + "tags": [ + "audit" + ], + "parameters": [ + { + "name": "since", + "in": "query", + "description": "How far back: 90m, 24h, 7d; 7d when absent.", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "The most events to answer with.", + "schema": { + "type": "integer" + } + }, + { + "name": "actor", + "in": "query", + "description": "Only changes by this actor.", + "schema": { + "type": "string" + } + }, + { + "name": "contains", + "in": "query", + "description": "Only events whose action or target contains this.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/store.AuditEvent" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/canaries": { + "get": { + "operationId": "getCanaries", + "summary": "Every canary, and how its two sides serve", + "tags": [ + "canaries" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/modelserve.CanaryView" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/capacity": { + "get": { + "operationId": "getCapacity", + "summary": "Every recorded measurement", + "tags": [ + "capacity" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CapacityView" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/eval/runs": { + "get": { + "operationId": "getEvalRuns", + "summary": "Quality runs, the newest first", + "tags": [ + "eval" + ], + "parameters": [ + { + "name": "model", + "in": "query", + "description": "Only this model's runs.", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "How many; a sensible number when absent.", + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/eval.Live" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/eval/runs/{id}": { + "get": { + "operationId": "getEvalRunsId", + "summary": "One quality run, with each case", + "tags": [ + "eval" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "description": "The quality run's ID, as starting it answered.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/eval.Live" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/eval/suites": { + "get": { + "operationId": "getEvalSuites", + "summary": "The quality suites the control plane can run by name", + "tags": [ + "eval" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/eval.SuiteInfo" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/explain-placement": { + "get": { + "operationId": "getExplainPlacement", + "summary": "Why a model could not be placed", + "tags": [ + "explain-placement" + ], + "parameters": [ + { + "name": "model", + "in": "query", + "required": true, + "description": "The model's name or an alias.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExplainView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/fabric-test": { + "post": { + "operationId": "postFabricTest", + "summary": "Measure bandwidth between two nodes, rail by rail", + "tags": [ + "fabric-test" + ], + "parameters": [ + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FabricTestRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FabricTestView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/fabrics": { + "get": { + "operationId": "getFabrics", + "summary": "The physical fabrics and the names nodes give them", + "tags": [ + "fabrics" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/fabrics.Report" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/fabrics/{id}/topology": { + "get": { + "operationId": "getFabricsIdTopology", + "summary": "One fabric's map, with the cluster's adapters live on it", + "tags": [ + "fabrics" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "description": "The physical fabric's ID, as GET /api/v1/fabrics lists it.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TopologyView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/facility": { + "get": { + "operationId": "getFacility", + "summary": "The failure domains, their power against their caps, and what is held", + "tags": [ + "facility" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FacilityView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/facility/holds": { + "post": { + "operationId": "postFacilityHolds", + "summary": "Hold a domain for maintenance: nothing new is placed in it", + "description": "With drain, each of its nodes is drained too, one replica at a time with the replacement up first.", + "tags": [ + "facility" + ], + "parameters": [ + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HoldRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HoldView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/facility/holds/{domain}": { + "delete": { + "operationId": "deleteFacilityHoldsDomain", + "summary": "Release a held domain", + "description": "Nodes a draining hold drained are made ready again.", + "tags": [ + "facility" + ], + "parameters": [ + { + "name": "domain", + "in": "path", + "required": true, + "description": "The domain as level:name, rack:r12-07, as `llmgw ctl facility` lists it.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HoldView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/federation": { + "get": { + "operationId": "getFederation", + "summary": "This cluster's id, and its federation peers with their health and models", + "tags": [ + "federation" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FederationView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + }, + "post": { + "operationId": "postFederation", + "summary": "Add another llmgw cluster as a peer, or change one", + "description": "The peer is checked first: its /ready, timed, and its /v1/models with the key. Its models join the catalog as PEER/MODEL.", + "tags": [ + "federation" + ], + "parameters": [ + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/federation.AddRequest" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/federation.Status" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/federation/{peer}": { + "delete": { + "operationId": "deleteFederationPeer", + "summary": "Remove a federation peer and its models", + "description": "Refused while a model here falls back to one of the peer's.", + "tags": [ + "federation" + ], + "parameters": [ + { + "name": "peer", + "in": "path", + "required": true, + "description": "The federation peer's name, as `llmgw ctl federation list` lists it.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Removed" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/federation/{peer}/sync": { + "post": { + "operationId": "postFederationPeerSync", + "summary": "Check a peer now, rather than at the next interval", + "tags": [ + "federation" + ], + "parameters": [ + { + "name": "peer", + "in": "path", + "required": true, + "description": "The federation peer's name, as `llmgw ctl federation list` lists it.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/federation.Status" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/guard": { + "get": { + "operationId": "getGuard", + "summary": "The guardrail policies and where they are attached", + "tags": [ + "guard" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GuardView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/guard/attachments": { + "post": { + "operationId": "postGuardAttachments", + "summary": "Attach a guardrail policy", + "tags": [ + "guard" + ], + "parameters": [ + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GuardAttachmentRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/guard.Attachment" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + }, + "delete": { + "operationId": "deleteGuardAttachments", + "summary": "Detach a guardrail policy", + "tags": [ + "guard" + ], + "parameters": [ + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GuardAttachmentRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/guard.Attachment" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/jobs": { + "get": { + "operationId": "getJobs", + "summary": "Every job since the control plane started", + "tags": [ + "jobs" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/modelserve.Job" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/jobs/{id}": { + "get": { + "operationId": "getJobsId", + "summary": "One job", + "tags": [ + "jobs" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "description": "The job's ID, as starting it answered.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/modelserve.Job" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/metrics/range": { + "post": { + "operationId": "postMetricsRange", + "summary": "Several Prometheus range queries at once", + "description": "Read from the Prometheus monitoring.prometheus names; configured is false without one.", + "tags": [ + "metrics" + ], + "parameters": [ + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetricsRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetricsResult" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models": { + "get": { + "operationId": "getModels", + "summary": "Every model, with its replicas and state", + "tags": [ + "models" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ModelView" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + }, + "post": { + "operationId": "postModels", + "summary": "Add a model to the catalog", + "description": "Kept in the store across restarts. Refused when the name is taken, a model in configuration has it, or the definition would make the catalog invalid.", + "tags": [ + "models" + ], + "parameters": [ + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/catalog.Model" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ModelAdded" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/serve": { + "post": { + "operationId": "postModelsServe", + "summary": "Fetch a registry repository and serve it", + "tags": [ + "models" + ], + "parameters": [ + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/modelserve.Request" + } + } + } + }, + "responses": { + "202": { + "description": "Accepted: started, and running on.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/modelserve.Job" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}": { + "get": { + "operationId": "getModelsName", + "summary": "One model's definition, as it is in force", + "description": "With the defaults the catalog filled in. By its name only, not an alias.", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/catalog.Model" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + }, + "delete": { + "operationId": "deleteModelsName", + "summary": "Remove a model added at runtime", + "description": "A model declared in configuration is refused: it would come back on the next restart.", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Removed" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}/adapters": { + "post": { + "operationId": "postModelsNameAdapters", + "summary": "Replace a model's LoRA adapters", + "description": "Each new file is read first, to check it is an adapter for the model's architecture.", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AdaptersRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AdaptersRequest" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}/canary": { + "post": { + "operationId": "postModelsNameCanary", + "summary": "Start a canary of a model's newer weights", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/catalog.Canary" + } + } + } + }, + "responses": { + "202": { + "description": "Accepted: started, and running on.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/modelserve.Job" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + }, + "put": { + "operationId": "putModelsNameCanary", + "summary": "Change the share of requests a canary takes", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CanaryPercentRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Result" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + }, + "delete": { + "operationId": "deleteModelsNameCanary", + "summary": "Take a canary out: its share first, then the candidate", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Result" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}/capacity": { + "put": { + "operationId": "putModelsNameCapacity", + "summary": "Record what a replica was measured to serve", + "description": "Replaces an earlier measurement of the same model on the same profile.", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/bench.Capacity" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/bench.Capacity" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}/class": { + "post": { + "operationId": "postModelsNameClass", + "summary": "Set a model's capacity class", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClassRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClassView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}/eval": { + "post": { + "operationId": "postModelsNameEval", + "summary": "Ask a model a quality suite", + "description": "Started at once and answered with the run, to be followed at /api/v1/eval/runs/{id}.", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/eval.Request" + } + } + } + }, + "responses": { + "202": { + "description": "Accepted: started, and running on.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/eval.Live" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}/eval-gate": { + "put": { + "operationId": "putModelsNameEvalGate", + "summary": "Hold a model's updates and promotions to a quality suite", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EvalGateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EvalGateView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + }, + "delete": { + "operationId": "deleteModelsNameEvalGate", + "summary": "Stop holding a model's updates to a suite", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EvalGateView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}/fallbacks": { + "put": { + "operationId": "putModelsNameFallbacks", + "summary": "Replace the models a model falls back to when it has no capacity", + "description": "A model added at runtime only. A federation peer's model, PEER/MODEL, sends the overflow to the other cluster.", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FallbacksRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FallbacksView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}/headroom": { + "get": { + "operationId": "getModelsNameHeadroom", + "summary": "How many more replicas of a model fit now, and where", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "The most to try placing; 16 when absent or past 64.", + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HeadroomView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}/origin": { + "post": { + "operationId": "postModelsNameOrigin", + "summary": "Record the repository a model's weights came from", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OriginRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OriginView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}/owner": { + "post": { + "operationId": "postModelsNameOwner", + "summary": "Set the part of the tenancy tree a model's capacity counts against", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OwnerRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OwnerView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}/promote": { + "post": { + "operationId": "postModelsNamePromote", + "summary": "Make a canary's weights the model's", + "description": "With a quality suite, or the model's standing gate, the canary is asked it first and kept below the score.", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/modelserve.Change" + } + } + } + }, + "responses": { + "202": { + "description": "Accepted: started, and running on.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/modelserve.Job" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}/resources": { + "post": { + "operationId": "postModelsNameResources", + "summary": "Set what a model's profiles reserve of a node", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResourcesRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/catalog.Model" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}/retry": { + "post": { + "operationId": "postModelsNameRetry", + "summary": "Try a parked model again", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetryView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}/rollback": { + "post": { + "operationId": "postModelsNameRollback", + "summary": "Go back to the weights the last update replaced", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Result" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}/scale": { + "post": { + "operationId": "postModelsNameScale", + "summary": "Set how many replicas a model runs", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScaleRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScaleResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}/target": { + "get": { + "operationId": "getModelsNameTarget", + "summary": "How many replicas a throughput needs, and whether they fit", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "name": "tokens_per_sec", + "in": "query", + "required": true, + "description": "The output tokens a second wanted of the model.", + "schema": { + "type": "number" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TargetView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/models/{name}/update": { + "post": { + "operationId": "postModelsNameUpdate", + "summary": "Move a model to its repository's newer weights", + "description": "With a quality suite, or the model's standing gate, the new weights are asked it first as a hidden canary.", + "tags": [ + "models" + ], + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "description": "The model's name in the catalog.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/modelserve.Change" + } + } + } + }, + "responses": { + "202": { + "description": "Accepted: started, and running on.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/modelserve.Job" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/nodes": { + "get": { + "operationId": "getNodes", + "summary": "Every node, with its cards, load and fabrics", + "tags": [ + "nodes" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NodeView" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/nodes/{id}": { + "delete": { + "operationId": "deleteNodesId", + "summary": "Forget a node that has gone", + "description": "Only a node that is lost, or unreachable with nothing on it; its certificate is revoked.", + "tags": [ + "nodes" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "description": "The node's ID, as `llmgw ctl nodes` lists it.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NodeRemoved" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/nodes/{id}/engines": { + "post": { + "operationId": "postNodesIdEngines", + "summary": "Choose an engine's build for a node", + "description": "The node installs the build chosen. Build is auto, a build such as cu129, or none.", + "tags": [ + "nodes" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "description": "The node's ID, as `llmgw ctl nodes` lists it.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NodeEngineRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NodeEngineRequest" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/nodes/{id}/labels": { + "post": { + "operationId": "postNodesIdLabels", + "summary": "Set or remove labels on a node, over its agent's own", + "description": "Kept in the store. llmgw.io/site, room, row, rack and pdu say where the node is, for facility-aware placement.", + "tags": [ + "nodes" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "description": "The node's ID, as `llmgw ctl nodes` lists it.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NodeLabelsRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NodeLabelsView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/nodes/{id}/logs": { + "get": { + "operationId": "getNodesIdLogs", + "summary": "The last lines of a node's logs", + "tags": [ + "nodes" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "description": "The node's ID, as `llmgw ctl nodes` lists it.", + "schema": { + "type": "string" + } + }, + { + "name": "lines", + "in": "query", + "description": "How many lines; 300 when absent, at most 2000.", + "schema": { + "type": "integer" + } + }, + { + "name": "source", + "in": "query", + "description": "Which log: agent when absent, or an engine the node lists in sources.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LogsView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/nodes/{id}/state": { + "post": { + "operationId": "postNodesIdState", + "summary": "Cordon, drain or ready a node", + "tags": [ + "nodes" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "description": "The node's ID, as `llmgw ctl nodes` lists it.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NodeStateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NodeStateView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/nodes/{id}/upgrade": { + "post": { + "operationId": "postNodesIdUpgrade", + "summary": "Have a node run a release", + "tags": [ + "nodes" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "description": "The node's ID, as `llmgw ctl nodes` lists it.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpgradeRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpgradeView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/notify/test": { + "post": { + "operationId": "postNotifyTest", + "summary": "Send a test notification to every webhook", + "tags": [ + "notify" + ], + "parameters": [ + { + "$ref": "#/components/parameters/Actor" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/notify.Result" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/nvlink": { + "get": { + "operationId": "getNvlink", + "summary": "The multi-node NVLink domains and what keeps nodes out of them", + "tags": [ + "nvlink" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/nvlink.Report" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/openapi.json": { + "get": { + "operationId": "getOpenapiJson", + "summary": "This document", + "description": "The admin API in OpenAPI 3.1, generated from the route table and built into the binary.", + "tags": [ + "openapi" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": {} + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/plan": { + "get": { + "operationId": "getPlan", + "summary": "How a registry repository would be served here", + "tags": [ + "plan" + ], + "parameters": [ + { + "name": "repo", + "in": "query", + "required": true, + "description": "The repository, owner/name.", + "schema": { + "type": "string" + } + }, + { + "name": "format", + "in": "query", + "description": "gguf or safetensors; gguf when absent.", + "schema": { + "type": "string" + } + }, + { + "name": "context", + "in": "query", + "description": "The context length to plan for, in tokens.", + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/modelserve.Plan" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/quotas": { + "get": { + "operationId": "getQuotas", + "summary": "Every capacity quota, with what its scope holds now", + "tags": [ + "quotas" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/QuotaView" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + }, + "put": { + "operationId": "putQuotas", + "summary": "Set a scope's capacity quota", + "description": "Replaces the scope's quota whole. The scope may be named by path or by ID; the answer names it by ID.", + "tags": [ + "quotas" + ], + "parameters": [ + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QuotaRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QuotaSet" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/quotas/{scope}": { + "delete": { + "operationId": "deleteQuotasScope", + "summary": "Remove a scope's capacity quota", + "tags": [ + "quotas" + ], + "parameters": [ + { + "name": "scope", + "in": "path", + "required": true, + "description": "The scope: org:NAME, team:ORG/TEAM, project:ORG/TEAM/PROJECT, or their IDs after the colon.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Removed" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/replicas": { + "get": { + "operationId": "getReplicas", + "summary": "Every replica, with its shards", + "tags": [ + "replicas" + ], + "parameters": [ + { + "name": "model", + "in": "query", + "description": "Only this model's replicas.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ReplicaView" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/requests/{id}": { + "get": { + "operationId": "getRequestsId", + "summary": "What one request went through", + "tags": [ + "requests" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "description": "The request's ID: the x-request-id a client was answered with.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RequestView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/requests/{id}/body": { + "get": { + "operationId": "getRequestsIdBody", + "summary": "A kept request and its answer", + "tags": [ + "requests" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "description": "The request's ID: the x-request-id a client was answered with.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/store.RequestBody" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/requests/{id}/replay": { + "post": { + "operationId": "postRequestsIdReplay", + "summary": "Send a kept request again, to any model", + "tags": [ + "requests" + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "description": "The request's ID: the x-request-id a client was answered with.", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReplayRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReplayView" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/restart": { + "post": { + "operationId": "postRestart", + "summary": "Restart replicas, every replica of some models, or all", + "tags": [ + "restart" + ], + "parameters": [ + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RestartRequest" + } + } + } + }, + "responses": { + "202": { + "description": "Accepted: started, and running on.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RestartResult" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/summary": { + "get": { + "operationId": "getSummary", + "summary": "The whole fleet in one answer", + "tags": [ + "summary" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Summary" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/updates": { + "get": { + "operationId": "getUpdates", + "summary": "Newer weights the registry has for models", + "tags": [ + "updates" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/modelserve.UpdateInfo" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/updates/check": { + "post": { + "operationId": "postUpdatesCheck", + "summary": "Ask the registry now, about one model or every one", + "tags": [ + "updates" + ], + "parameters": [ + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CheckRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/modelserve.UpdateInfo" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/usage": { + "get": { + "operationId": "getUsage", + "summary": "What each group of the tenancy tree spent", + "tags": [ + "usage" + ], + "parameters": [ + { + "name": "by", + "in": "query", + "description": "org, team or project; team when absent.", + "schema": { + "type": "string" + } + }, + { + "name": "since", + "in": "query", + "description": "A duration back from now, like 24h; 24h when absent.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ScopeUsageView" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/usage/export": { + "get": { + "operationId": "getUsageExport", + "summary": "Usage totals by period and dimension, as CSV or JSON", + "tags": [ + "usage" + ], + "parameters": [ + { + "name": "from", + "in": "query", + "description": "A date (2026-09-01) or an RFC 3339 time; the first of this month when absent.", + "schema": { + "type": "string" + } + }, + { + "name": "to", + "in": "query", + "description": "A date or an RFC 3339 time; now when absent.", + "schema": { + "type": "string" + } + }, + { + "name": "period", + "in": "query", + "description": "hour, day or month; day when absent.", + "schema": { + "type": "string" + } + }, + { + "name": "by", + "in": "query", + "description": "Dimensions, comma-separated: org, team, project, user, key, model.", + "schema": { + "type": "string" + } + }, + { + "name": "format", + "in": "query", + "description": "json for JSON; CSV otherwise.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/store.ExportRow" + } + } + }, + "text/csv": { + "schema": { + "type": "string" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/weights/collect": { + "post": { + "operationId": "postWeightsCollect", + "summary": "Delete weights that no model uses", + "tags": [ + "weights" + ], + "parameters": [ + { + "$ref": "#/components/parameters/Actor" + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CollectRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CollectResult" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + }, + "/api/v1/weights/orphans": { + "get": { + "operationId": "getWeightsOrphans", + "summary": "Weights on nodes that no model uses", + "tags": [ + "weights" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrphanView" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "default": { + "$ref": "#/components/responses/Error" + } + } + } + } + }, + "components": { + "securitySchemes": { + "adminToken": { + "type": "http", + "scheme": "bearer", + "description": "The admin token: the contents of /var/lib/llmgw/admin-token on the control plane (admin_token_file), readable by root and the server. Sent as Authorization: Bearer TOKEN." + } + }, + "parameters": { + "Actor": { + "name": "X-Llmgw-Actor", + "in": "header", + "required": false, + "description": "Who the change is recorded as made by in the audit log: letters, digits and ._-@, at most 64. unknown when absent.", + "schema": { + "type": "string" + } + } + }, + "responses": { + "Error": { + "description": "Refused: the error says why.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorView" + } + } + } + }, + "Unauthorized": { + "description": "The admin token is missing or wrong.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorView" + } + } + } + } + }, + "schemas": { + "AdaptersRequest": { + "type": "object", + "description": "AdaptersRequest replaces a model's LoRA adapters with these.", + "properties": { + "adapters": { + "type": "array", + "items": { + "$ref": "#/components/schemas/catalog.Adapter" + } + } + } + }, + "CanaryPercentRequest": { + "type": "object", + "description": "CanaryPercentRequest changes the share of a model's requests its canary takes.", + "properties": { + "percent": { + "type": "integer" + } + } + }, + "CapacityView": { + "type": "object", + "description": "CapacityView is one stored measurement, with who recorded it.", + "properties": { + "model": { + "type": "string" + }, + "profile": { + "type": "string" + }, + "max_concurrency_at_slo": { + "type": "integer", + "description": "MaxConcurrencyAtSLO is the capacity: the highest concurrency that still met the target. Zero means even one request did not, which is a real result and not a missing one — it says this hardware cannot serve this model at this SLO at all." + }, + "throughput_tok_per_sec": { + "type": "number", + "description": "ThroughputTokPerSec and the latencies are taken at that level, not at the peak. Peak throughput arrives long after latency has become unusable, so reporting it would overstate what the hardware can serve." + }, + "ttft_p99": { + "type": "integer", + "format": "int64", + "description": "A duration, in nanoseconds." + }, + "tpot_p99": { + "type": "integer", + "format": "int64", + "description": "A duration, in nanoseconds." + }, + "suggested_target_waiting": { + "type": "integer", + "description": "SuggestedTargetWaiting and SuggestedKVCeiling are the queue depth and cache pressure seen while the SLO was still being met, which is what admission should treat as healthy for this model. Admission currently applies one global default to every model; these are the per-model numbers it should be using instead." + }, + "suggested_kv_ceiling": { + "type": "number" + }, + "slo": { + "$ref": "#/components/schemas/bench.SLO", + "description": "SLO is recorded because capacity is meaningless without it. The same replica has a different capacity against a 200ms first-token target than against a 2s one, and a number stored without the target it was measured against cannot be compared with anything." + }, + "target": { + "type": "string", + "description": "Target is the endpoint the load actually went to, kept so a profile measured against the gateway is never mistaken for one measured against a replica. Only the second says anything about the hardware." + }, + "measured_at": { + "type": "string", + "format": "date-time" + }, + "measured_by": { + "type": "string" + } + } + }, + "CheckRequest": { + "type": "object", + "description": "CheckRequest asks the registry about one model now, or every one.", + "properties": { + "model": { + "type": "string" + } + } + }, + "ClassGPUs": { + "type": "object", + "description": "ClassGPUs is how many of a node's devices are of one class, and how many of those are free or kept out of placement.", + "properties": { + "class": { + "type": "string" + }, + "total": { + "type": "integer" + }, + "free": { + "type": "integer" + }, + "unhealthy": { + "type": "integer" + }, + "mig": { + "type": "boolean", + "description": "MIG marks a class of MIG instances, each of which takes a replica of its own and never joins a tensor-parallel group." + } + } + }, + "ClassRequest": { + "type": "object", + "description": "ClassRequest sets a model's capacity class: critical, standard or opportunistic, or empty to go back to what its scaling implies.", + "properties": { + "class": { + "type": "string" + } + } + }, + "ClassUse": { + "type": "object", + "description": "ClassUse is how much of one kind of card is in use.", + "properties": { + "class": { + "type": "string" + }, + "total": { + "type": "integer" + }, + "used": { + "type": "integer" + }, + "unhealthy": { + "type": "integer", + "description": "Unhealthy GPUs are neither used nor available, and counting them as free is how a cluster looks like it has room it does not have." + } + } + }, + "ClassView": { + "type": "object", + "description": "ClassView is a model's capacity class now.", + "properties": { + "model": { + "type": "string" + }, + "class": { + "type": "string" + } + } + }, + "CollectRequest": { + "type": "object", + "description": "CollectRequest limits a sweep to one node. Empty means every node, which is the common case after removing a model from the catalog.", + "properties": { + "node": { + "type": "string" + } + } + }, + "CollectResult": { + "type": "object", + "description": "CollectResult is what was deleted on one node, or why nothing was.", + "properties": { + "node": { + "type": "string" + }, + "files": { + "type": "integer" + }, + "bytes": { + "type": "integer", + "format": "int64" + }, + "error": { + "type": "string" + } + } + }, + "DomainView": { + "type": "object", + "description": "DomainView is one domain: its nodes, its power and whether it is held.", + "properties": { + "domain": { + "type": "string" + }, + "level": { + "type": "string" + }, + "name": { + "type": "string" + }, + "nodes": { + "type": "array", + "items": { + "type": "string" + } + }, + "cap_watts": { + "type": "number", + "description": "CapWatts is the domain's cap, LimitWatts the cap less the margin; both zero when it has none." + }, + "limit_watts": { + "type": "number" + }, + "other_watts": { + "type": "number" + }, + "reserved_watts": { + "type": "number", + "description": "ReservedWatts is what is placed in it is estimated to draw; MeasuredWatts what its nodes' sensors read; UsedWatts what counts against the cap, the larger of the two node by node." + }, + "measured_watts": { + "type": "number" + }, + "used_watts": { + "type": "number" + }, + "held": { + "$ref": "#/components/schemas/HoldView", + "description": "Held is set when the domain is held." + } + } + }, + "ErrorView": { + "type": "object", + "description": "ErrorView is every refusal: a 4xx or 5xx status with what went wrong.", + "properties": { + "error": { + "type": "string" + } + } + }, + "EvalGateRequest": { + "type": "object", + "description": "EvalGateRequest sets a model's standing quality suite; an empty suite takes it away.", + "properties": { + "suite": { + "type": "string" + }, + "min_score": { + "type": "number" + }, + "judge": { + "type": "string" + } + } + }, + "EvalGateView": { + "type": "object", + "description": "EvalGateView is a model's standing quality gate, as it is now; Eval is absent when it has none.", + "properties": { + "model": { + "type": "string" + }, + "eval": { + "$ref": "#/components/schemas/catalog.EvalGate" + } + } + }, + "ExplainView": { + "type": "object", + "description": "ExplainView is why a model could not be placed.", + "properties": { + "model": { + "type": "string" + }, + "placed": { + "type": "boolean", + "description": "Placed is true when the model has replicas, in which case there is nothing to explain." + }, + "rejections": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RejectionView" + }, + "description": "Rejections is empty when placement was never attempted, which is itself the answer: the model is satisfied, or the reconciler has not run yet." + } + } + }, + "FabricTestRequest": { + "type": "object", + "description": "FabricTestRequest is a bandwidth test between two nodes.", + "properties": { + "a": { + "type": "string" + }, + "b": { + "type": "string" + }, + "fabric": { + "type": "string", + "description": "Fabric is the declared fabric to test over; empty is the one the two nodes share." + }, + "seconds": { + "type": "integer", + "description": "Seconds each rail is measured for, from 1 to 30." + } + } + }, + "FabricTestView": { + "type": "object", + "description": "FabricTestView is a bandwidth test between two nodes.", + "properties": { + "a": { + "type": "string" + }, + "b": { + "type": "string" + }, + "fabric": { + "type": "string" + }, + "ok": { + "type": "boolean" + }, + "rails": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RailView" + } + }, + "notes": { + "type": "array", + "items": { + "type": "string" + } + }, + "took": { + "type": "string" + } + } + }, + "FabricUse": { + "type": "object", + "description": "FabricUse is capacity within one fabric.", + "properties": { + "fabric": { + "type": "string" + }, + "nodes": { + "type": "integer" + }, + "nodes_with_weights": { + "type": "integer", + "description": "ModelsPresent is how many nodes here hold weights at all, and Models how many distinct models they hold between them.\n\nPer fabric because that is the unit at which the answer is actionable. Fabrics are not connected to one another, so weights in one are not weights in another: a model seeded into a single fabric leaves the rest of the cluster unable to serve it without first moving tens of gigabytes over the management network, and nothing said so." + }, + "models_present": { + "type": "integer" + }, + "largest_free_block": { + "type": "integer", + "description": "LargestFreeBlock is the most nodes on this fabric that are entirely free, which is the number that decides whether a multi-node replica can land." + } + } + }, + "FacilityView": { + "type": "object", + "description": "FacilityView is the failure domains as placement sees them.", + "properties": { + "domains": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DomainView" + }, + "description": "Domains are every domain a node is in or a budget names, by level (site, room, row, rack, pdu) and then name." + }, + "holds": { + "type": "array", + "items": { + "$ref": "#/components/schemas/HoldView" + }, + "description": "Holds are every domain held, including one no node is in yet." + }, + "margin": { + "type": "number", + "description": "Margin is the share of every cap kept free." + }, + "unlocated": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Unlocated are the nodes with no location label, which placement treats as each in a rack of its own." + } + } + }, + "FallbacksRequest": { + "type": "object", + "description": "FallbacksRequest replaces a model's fallbacks; empty takes them all away.", + "properties": { + "fallbacks": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "FallbacksView": { + "type": "object", + "description": "FallbacksView is a model's fallbacks, as they are now.", + "properties": { + "model": { + "type": "string" + }, + "fallbacks": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "FederationView": { + "type": "object", + "description": "FederationView is this cluster's id and its peers.", + "properties": { + "cluster": { + "type": "string", + "description": "Cluster is this cluster's own id, which its peers see in the hop header." + }, + "peers": { + "type": "array", + "items": { + "$ref": "#/components/schemas/federation.Status" + } + } + } + }, + "FetchView": { + "type": "object", + "description": "FetchView is a download in flight.", + "properties": { + "source": { + "type": "string" + }, + "bytes_done": { + "type": "integer", + "format": "int64" + }, + "bytes_total": { + "type": "integer", + "format": "int64", + "description": "BytesTotal is 0 when the server did not say how large the file is." + }, + "percent": { + "type": "integer", + "description": "Percent is absent rather than zero when the total is unknown: an invented percentage that stops moving is worse than a byte count that keeps rising." + } + } + }, + "GPUView": { + "type": "object", + "description": "GPUView is one card as a node's page shows it.", + "properties": { + "index": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "label": { + "type": "string", + "description": "Label is the device as people are shown it: \"3\" for a whole card, \"0/mig2\" for card 0's MIG instance 2." + }, + "class": { + "type": "string" + }, + "card": { + "type": "integer", + "description": "Card is the physical card's index: the device's own, or for a MIG instance its parent's, which is what the card's sensors are under." + }, + "mig_profile": { + "type": "string", + "description": "MIGProfile is the instance's profile, like 3g.40gb; empty for a whole card." + }, + "memory_total_mb": { + "type": "integer" + }, + "memory_used_mb": { + "type": "integer" + }, + "compute_capability": { + "type": "string", + "description": "ComputeCapability is what decides which engine builds run on the card: CUDA 13 builds need 7.5, so a V100 (7.0) runs only older ones." + }, + "numa": { + "type": "integer" + }, + "nvlink_peers": { + "type": "array", + "items": { + "type": "integer" + } + }, + "nearest_nic": { + "type": "string", + "description": "NearestNIC is the adapter closest to the card, and how close." + }, + "nic_path": { + "type": "string" + }, + "fabric_state": { + "type": "string" + }, + "domain": { + "type": "string" + }, + "bandwidth": { + "type": "string" + } + } + }, + "GuardAttachmentRequest": { + "type": "object", + "description": "GuardAttachmentRequest attaches a policy to a part of the tenancy tree, a key or a person, or with DELETE takes it off again.", + "properties": { + "target": { + "type": "string", + "description": "Target is org:NAME, team:ORG/TEAM, project:ORG/TEAM/PROJECT (or the ID after the colon), key:KEY-ID or user:USER-ID." + }, + "policy": { + "type": "string", + "description": "Policy is a policy's name in server.yaml's guard.policies." + } + } + }, + "GuardAttachmentView": { + "type": "object", + "description": "GuardAttachmentView is one attachment, with the name people know its scope by.", + "properties": { + "Scope": { + "type": "string" + }, + "ScopeID": { + "type": "string" + }, + "Policy": { + "type": "string" + }, + "name": { + "type": "string" + } + } + }, + "GuardView": { + "type": "object", + "description": "GuardView is the library and where its policies are attached.", + "properties": { + "policies": { + "type": "array", + "items": { + "type": "string" + } + }, + "default": { + "type": "array", + "items": { + "type": "string" + } + }, + "attachments": { + "type": "array", + "items": { + "$ref": "#/components/schemas/GuardAttachmentView" + } + } + } + }, + "HeadroomView": { + "type": "object", + "description": "HeadroomView is how many more replicas of a model fit now, and where.", + "properties": { + "model": { + "type": "string" + }, + "current": { + "type": "integer", + "description": "Current is the replicas holding capacity: starting or ready." + }, + "more": { + "type": "integer", + "description": "More is how many more placement would find room for now." + }, + "nodes": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "string" + } + }, + "description": "Nodes is where each of those would go." + }, + "limited": { + "type": "boolean", + "description": "Limited is set when More stopped at the limit asked rather than at the cluster's edge: there may be room for more." + }, + "blocked": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Blocked says why one more does not fit, a line per node considered." + }, + "tok_per_sec": { + "type": "number", + "description": "TokPerSec is what one more replica was measured to serve; 0 unmeasured." + }, + "by_preempting": { + "type": "integer", + "description": "ByPreempting is how many more would fit by stopping replicas this model's class may take; Preempts the models those belong to." + }, + "preempts": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "HoldRequest": { + "type": "object", + "description": "HoldRequest holds a domain.", + "properties": { + "domain": { + "type": "string", + "description": "Domain is level:name: rack:r12-07, pdu:r12-07-a, row:12." + }, + "reason": { + "type": "string" + }, + "drain": { + "type": "boolean", + "description": "Drain moves the work in the domain elsewhere too." + } + } + }, + "HoldView": { + "type": "object", + "description": "HoldView is a hold, and the nodes holding or releasing it changed.", + "properties": { + "domain": { + "type": "string" + }, + "reason": { + "type": "string" + }, + "drain": { + "type": "boolean" + }, + "by": { + "type": "string" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "nodes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Nodes are those this call drained, or made ready again on release." + } + } + }, + "IBPortView": { + "type": "object", + "description": "IBPortView is one port as a page shows it.", + "properties": { + "hca": { + "type": "string" + }, + "port": { + "type": "integer" + }, + "state": { + "type": "string" + }, + "phys_state": { + "type": "string" + }, + "rate_gbps": { + "type": "integer" + }, + "link_layer": { + "type": "string" + }, + "active": { + "type": "boolean" + }, + "fabric": { + "type": "string", + "description": "Fabric is the declared fabric this port's adapter carries, if any." + }, + "physical": { + "type": "string", + "description": "Physical is the fabric the port is physically on: its subnet manager, or its RoCE network. SMError says why that is not known." + }, + "sm_error": { + "type": "string" + }, + "errors": { + "type": "object", + "additionalProperties": { + "type": "integer", + "format": "int64" + }, + "description": "Errors are the error counters that are not zero, by name." + }, + "tx_bytes": { + "type": "integer", + "format": "int64" + }, + "rx_bytes": { + "type": "integer", + "format": "int64" + } + } + }, + "IdleReplica": { + "type": "object", + "description": "IdleReplica is a replica holding hardware nothing is asking for.", + "properties": { + "id": { + "type": "string" + }, + "model": { + "type": "string" + }, + "idle_seconds": { + "type": "integer", + "format": "int64" + }, + "gpus": { + "type": "integer" + } + } + }, + "Live": { + "type": "object", + "description": "Live is one of the cluster's adapters as its node last reported it.", + "properties": { + "node": { + "type": "string" + }, + "hca": { + "type": "string" + }, + "state": { + "type": "string" + }, + "phys_state": { + "type": "string" + }, + "gbps": { + "type": "integer" + }, + "tx_bps": { + "type": "number" + }, + "rx_bps": { + "type": "number" + }, + "errors": { + "type": "object", + "additionalProperties": { + "type": "integer", + "format": "int64" + } + } + } + }, + "LoadView": { + "type": "object", + "description": "LoadView is a node's CPU and memory in use, at its last heartbeat.", + "properties": { + "cpu_percent": { + "type": "number" + }, + "cpus": { + "type": "integer" + }, + "load1": { + "type": "number" + }, + "load5": { + "type": "number" + }, + "load15": { + "type": "number" + }, + "memory_used_bytes": { + "type": "integer", + "format": "int64" + }, + "memory_total_bytes": { + "type": "integer", + "format": "int64" + }, + "memory_percent": { + "type": "number", + "description": "MemPercent is used over used plus available." + }, + "age_seconds": { + "type": "integer", + "format": "int64" + }, + "cpu_temp_c": { + "type": "number", + "description": "What the node's sensors say; zero is not measured." + }, + "cpu_power_w": { + "type": "number" + }, + "inlet_temp_c": { + "type": "number" + }, + "gpu_sensors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/inventory.GPUSensor" + } + } + } + }, + "LogsView": { + "type": "object", + "description": "LogsView is one of a node's logs, as the node sent it.", + "properties": { + "node": { + "type": "string" + }, + "source": { + "type": "string" + }, + "lines": { + "type": "array", + "items": { + "type": "string" + } + }, + "sources": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Sources are every log the node can show: \"agent\", and one per engine running there." + }, + "error": { + "type": "string" + } + } + }, + "MetricsQuery": { + "type": "object", + "description": "MetricsQuery is one line set of a chart: a PromQL expression, and the label naming each line.", + "properties": { + "id": { + "type": "string" + }, + "expr": { + "type": "string" + }, + "by": { + "type": "string" + } + } + }, + "MetricsRequest": { + "type": "object", + "description": "MetricsRequest asks for several queries over one window at once.", + "properties": { + "window": { + "type": "integer", + "format": "int64", + "description": "A duration, in nanoseconds." + }, + "step": { + "type": "integer", + "format": "int64", + "description": "A duration, in nanoseconds." + }, + "queries": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MetricsQuery" + } + } + } + }, + "MetricsResult": { + "type": "object", + "description": "MetricsResult is each query's lines, by id; Configured is false when no Prometheus is set, and Errors says which queries failed and why.", + "properties": { + "configured": { + "type": "boolean" + }, + "series": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "$ref": "#/components/schemas/promq.Series" + } + } + }, + "errors": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "ModelAdded": { + "type": "object", + "description": "ModelAdded names the model added to the catalog.", + "properties": { + "added": { + "type": "string" + } + } + }, + "ModelTotals": { + "type": "object", + "description": "ModelTotals counts models by whether they have what they asked for.", + "properties": { + "total": { + "type": "integer" + }, + "satisfied": { + "type": "integer" + }, + "short": { + "type": "integer" + } + } + }, + "ModelView": { + "type": "object", + "description": "ModelView is a model as `ctl models` shows it.", + "properties": { + "name": { + "type": "string" + }, + "canary": { + "$ref": "#/components/schemas/catalog.Canary", + "description": "Canary is a share of its requests sent to a candidate; CanaryOf is set on the candidate, naming the model it is a canary of." + }, + "canary_of": { + "type": "string" + }, + "eval": { + "$ref": "#/components/schemas/catalog.EvalGate", + "description": "Eval is the quality suite its new weights must pass, when it has one." + }, + "description": { + "type": "string", + "description": "Description is what the model is for, when somebody said." + }, + "aliases": { + "type": "array", + "items": { + "type": "string" + } + }, + "source": { + "type": "string" + }, + "min_replicas": { + "type": "integer" + }, + "max_replicas": { + "type": "integer" + }, + "ready_replicas": { + "type": "integer" + }, + "total_replicas": { + "type": "integer" + }, + "desired_replicas": { + "type": "integer", + "description": "Desired is how many it should have now: Min, or for an on-demand model one while it is being asked for and none otherwise." + }, + "failures": { + "type": "integer", + "description": "Failures counts replicas that failed to start in a row." + }, + "parked": { + "type": "boolean", + "description": "Parked is set once Failures reached the limit; the model is not retried until its definition changes or `ctl retry` is run. Reason is the last error." + }, + "reason": { + "type": "string" + }, + "unplaceable": { + "type": "boolean", + "description": "Unplaceable is set when it is short and the last attempt found no node." + }, + "fallbacks": { + "type": "array", + "items": { + "type": "string" + } + }, + "profiles": { + "type": "array", + "items": { + "type": "string" + } + }, + "memory_gb": { + "type": "integer", + "description": "MemoryGB and CPUCores are what one replica reserves, from its first profile; MeasuredMemoryGB is the most one of its replicas uses now, 0 when none is measured." + }, + "cpu_cores": { + "type": "integer" + }, + "measured_memory_gb": { + "type": "number" + }, + "warnings": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Warnings are what makes its reservation wrong: nothing declared where placement needs a figure, or less declared than it uses." + }, + "class": { + "type": "string", + "description": "Class is its capacity class; Preempted the replicas it lost to a higher class; HeldFor the model it is giving room to now, if any." + }, + "owner": { + "type": "string" + }, + "external": { + "type": "string", + "description": "External is where a model served outside the cluster goes, provider host and its name for the model; empty for one served here." + }, + "adapters": { + "type": "array", + "items": { + "$ref": "#/components/schemas/catalog.Adapter" + }, + "description": "Adapters are the LoRA adapters it serves." + }, + "preempted": { + "type": "integer" + }, + "held_for": { + "type": "string" + }, + "origin": { + "$ref": "#/components/schemas/OriginView", + "description": "Origin is the registry repository its weights came from, and at which commit; Update what that repository had when it was last asked." + }, + "update": { + "$ref": "#/components/schemas/modelserve.UpdateInfo" + } + } + }, + "NodeEngineRequest": { + "type": "object", + "description": "NodeEngineRequest chooses one engine's build for a node.", + "properties": { + "engine": { + "type": "string" + }, + "build": { + "type": "string", + "description": "Build is \"auto\", a build such as \"cu129\", or \"none\"." + } + } + }, + "NodeLabelsRequest": { + "type": "object", + "description": "NodeLabelsRequest sets and removes labels on a node.", + "properties": { + "set": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "remove": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Remove are keys whose label set through the control plane goes; the agent's own value for the key, if it has one, is in force again." + } + } + }, + "NodeLabelsView": { + "type": "object", + "description": "NodeLabelsView is a node's labels after a change.", + "properties": { + "id": { + "type": "string" + }, + "operator_labels": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "OperatorLabels are those set through the control plane." + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Labels are what placement matches: the agent's with the operator's over them. Absent for a node that has not registered yet." + }, + "location": { + "$ref": "#/components/schemas/facility.Location" + } + } + }, + "NodeRemoved": { + "type": "object", + "description": "NodeRemoved names the node forgotten. Removed is the string \"true\".", + "properties": { + "id": { + "type": "string" + }, + "removed": { + "type": "string" + } + } + }, + "NodeStateRequest": { + "type": "object", + "description": "NodeStateRequest cordons, drains or readies a node: ready (or uncordon), cordoned (or cordon), draining (or drain).", + "properties": { + "state": { + "type": "string" + } + } + }, + "NodeStateView": { + "type": "object", + "description": "NodeStateView is a node's state after the change.", + "properties": { + "id": { + "type": "string" + }, + "state": { + "type": "string" + } + } + }, + "NodeTotals": { + "type": "object", + "description": "NodeTotals counts nodes by the states that need different responses.", + "properties": { + "total": { + "type": "integer" + }, + "ready": { + "type": "integer" + }, + "cordoned": { + "type": "integer" + }, + "draining": { + "type": "integer" + }, + "unreachable": { + "type": "integer" + } + } + }, + "NodeView": { + "type": "object", + "description": "NodeView is a node as `ctl nodes` shows it.", + "properties": { + "id": { + "type": "string" + }, + "hostname": { + "type": "string" + }, + "mgmt_addr": { + "type": "string" + }, + "state": { + "type": "string" + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "gpu_total": { + "type": "integer" + }, + "gpu_free": { + "type": "integer" + }, + "memory_gb": { + "type": "integer", + "description": "MemoryGB is the machine's RAM, 0 when the agent did not report it. It is what decides whether a CPU profile can be placed here, so it belongs where someone looks when a model will not schedule." + }, + "cpu_count": { + "type": "integer", + "description": "CPUCount is the machine's CPUs, 0 when the agent did not report them." + }, + "engines": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Engines are the inference engines installed here, as the agent found them. Absent means the agent is older than the probe and said nothing, which is not the same as having none — placement treats it that way too, or a control plane upgrade would empty a fleet." + }, + "provision": { + "type": "array", + "items": { + "$ref": "#/components/schemas/inventory.EngineInstall" + }, + "description": "Provision is where installing each wanted engine stands. An engine is in Engines only once its installation here is ready." + }, + "engine_builds": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "EngineBuilds are the builds chosen for this node, by engine: \"auto\" (its hardware decides), a build (\"cu129\"), or \"none\". Only on a node with GPUs, the only kind with a choice to make." + }, + "os": { + "type": "string", + "description": "OS is the operating system and architecture, as the agent read them." + }, + "warnings": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Warnings are facts about the machine that make it slow or unusable without making it unhealthy: a VM with no vector instructions runs every model, at a fifth of the speed." + }, + "models_on_disk": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Models are the weights this node can see. Absent means it was not asked to look, which is not the same as holding none." + }, + "disk_free_gb": { + "type": "integer", + "description": "DiskFreeGB and DiskTotalGB are the filesystems holding those weights, summed. Zero means the agent did not report any, which an older agent and a node with no model directories both do — so it reads as unknown rather than as a full disk.\n\nSummed because an operator asking \"can this node take another model\" wants one number; the per-filesystem detail is in the node's own record for anyone who needs it. Shared filesystems are left out of the sum: the space on a filer is not this node's to spend, and adding it would let a fleet of twenty nodes each believe it has the same free terabyte." + }, + "disk_total_gb": { + "type": "integer" + }, + "gpu_classes": { + "type": "array", + "items": { + "type": "string" + } + }, + "gpus_by_class": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ClassGPUs" + }, + "description": "ClassGPUs counts the node's devices by class, in the order of Classes. A node with a card in MIG mode has several classes — each profile its instances are cut to, and any whole card beside them — and GPUTotal alone would add 3g.40gb instances to 80 GB cards." + }, + "fabrics": { + "type": "array", + "items": { + "type": "string" + } + }, + "unhealthy_gpus": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Unhealthy lists GPUs kept out of placement and why, which is usually the answer when a node looks idle but nothing will schedule onto it." + }, + "location": { + "$ref": "#/components/schemas/facility.Location", + "description": "Location is where the node is in the building, from its llmgw.io/site, room, row, rack and pdu labels; absent when it carries none." + }, + "held": { + "type": "string", + "description": "Held names the hold keeping the node out of placement, \"rack r12-07 is held: PDU swap\"; empty when none is." + }, + "held_domain": { + "type": "string", + "description": "HeldDomain is the held domain, level:name, for releasing it." + }, + "operator_labels": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "OperatorLabels are the labels set through the control plane, which Labels already includes over the agent's own." + }, + "last_seen_ago": { + "type": "string" + }, + "agent_version": { + "type": "string" + }, + "features": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Features are the requests the agent answers beyond the usual: \"fabric-test\". Absent is an agent too old to say." + }, + "replicas": { + "type": "integer" + }, + "load": { + "$ref": "#/components/schemas/LoadView", + "description": "Load is how busy the machine is, absent when its agent has not measured it lately — which is unknown, not idle." + }, + "ib_ports": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IBPortView" + }, + "description": "IBPorts are the node's InfiniBand and RoCE ports at the last heartbeat." + }, + "gpus": { + "type": "array", + "items": { + "$ref": "#/components/schemas/GPUView" + }, + "description": "GPUs are the cards, with how they are wired: NVLink peers, the adapter nearest each, and the NVLink domain each has joined." + }, + "nvlink_domain": { + "type": "string", + "description": "NVLinkDomain is the multi-node domain every card has joined, if any." + }, + "imex": { + "type": "string" + }, + "imex_channels": { + "type": "integer" + } + } + }, + "OriginRequest": { + "type": "object", + "description": "OriginRequest names the repository a model's weights came from.", + "properties": { + "repo": { + "type": "string" + } + } + }, + "OriginView": { + "type": "object", + "description": "OriginView is where a model's weights were published.", + "properties": { + "repo": { + "type": "string" + }, + "revision": { + "type": "string" + }, + "previous": { + "type": "string", + "description": "Previous is the commit the last update replaced, which it can go back to." + } + } + }, + "OrphanView": { + "type": "object", + "description": "OrphanView is cached weights on one node that no catalog model accounts for.", + "properties": { + "node": { + "type": "string" + }, + "paths": { + "type": "array", + "items": { + "type": "string" + } + }, + "bytes": { + "type": "integer", + "format": "int64", + "description": "Bytes is what deleting them would free, as far as the node reported. A file whose size was not reported counts as zero rather than being left out, so the list and the number always describe the same set." + } + } + }, + "OwnerRequest": { + "type": "object", + "description": "OwnerRequest sets the part of the tenancy tree a model's capacity counts against: org:NAME, team:ORG/TEAM or project:ORG/TEAM/PROJECT, or their IDs. Empty makes the model shared.", + "properties": { + "owner": { + "type": "string" + } + } + }, + "OwnerView": { + "type": "object", + "description": "OwnerView is a model's owner now, as scope:ID.", + "properties": { + "model": { + "type": "string" + }, + "owner": { + "type": "string" + } + } + }, + "ParkedModel": { + "type": "object", + "description": "ParkedModel is a model no longer retried, and why.", + "properties": { + "model": { + "type": "string" + }, + "failures": { + "type": "integer" + }, + "reason": { + "type": "string" + } + } + }, + "QuotaRequest": { + "type": "object", + "description": "QuotaRequest sets a scope's quota. Scope may be written with an ID or a name: org:Acme, team:Acme/ml, project:Acme/ml/training.", + "properties": { + "scope": { + "type": "string" + }, + "guarantee": { + "$ref": "#/components/schemas/store.Resources" + }, + "limit": { + "$ref": "#/components/schemas/store.Resources" + } + } + }, + "QuotaSet": { + "type": "object", + "description": "QuotaSet is the scope a quota was set on, as org:ID, team:ID or project:ID whatever name it was asked by.", + "properties": { + "scope": { + "type": "string" + } + } + }, + "QuotaView": { + "type": "object", + "description": "QuotaView is one scope's quota with what it holds now.", + "properties": { + "scope": { + "type": "string", + "description": "Scope is team:ID; Name is how people know it, \"Acme / ml\"." + }, + "name": { + "type": "string" + }, + "guarantee": { + "$ref": "#/components/schemas/store.Resources" + }, + "limit": { + "$ref": "#/components/schemas/store.Resources" + }, + "holds": { + "$ref": "#/components/schemas/quota.Amount" + }, + "updated_by": { + "type": "string" + }, + "updated_at": { + "type": "string", + "format": "date-time" + } + } + }, + "RailView": { + "type": "object", + "description": "RailView is one rail's result.", + "properties": { + "a": { + "type": "string" + }, + "b": { + "type": "string" + }, + "rate_gbps": { + "type": "integer" + }, + "gbps": { + "type": "number" + }, + "verdict": { + "type": "string" + }, + "detail": { + "type": "string" + } + } + }, + "RejectionView": { + "type": "object", + "description": "RejectionView is one rejected candidate.", + "properties": { + "profile": { + "type": "string" + }, + "pool": { + "type": "string" + }, + "node": { + "type": "string" + }, + "reason": { + "type": "string" + } + } + }, + "Removed": { + "type": "object", + "description": "Removed names what was taken away: a model, or a quota's scope.", + "properties": { + "removed": { + "type": "string" + } + } + }, + "ReplayRequest": { + "type": "object", + "description": "ReplayRequest names the model a kept request is sent to again.", + "properties": { + "model": { + "type": "string" + } + } + }, + "ReplayView": { + "type": "object", + "description": "ReplayView is a kept request sent again, beside what it got the first time.", + "properties": { + "original": { + "$ref": "#/components/schemas/store.RequestBody" + }, + "model": { + "type": "string" + }, + "status": { + "type": "integer" + }, + "body": { + "description": "Any JSON value." + }, + "took_ms": { + "type": "integer", + "format": "int64" + } + } + }, + "ReplicaTotal": { + "type": "object", + "description": "ReplicaTotal counts replicas by state.", + "properties": { + "ready": { + "type": "integer" + }, + "starting": { + "type": "integer" + }, + "draining": { + "type": "integer" + }, + "failed": { + "type": "integer" + } + } + }, + "ReplicaView": { + "type": "object", + "description": "ReplicaView is a replica as `ctl replicas` shows it.", + "properties": { + "id": { + "type": "string" + }, + "engine_key": { + "type": "string", + "description": "EngineKey is the key this replica's engine demands, for `ctl bench` and anyone else holding the admin listener who needs to reach an engine directly. The client-facing pages never render it." + }, + "restart": { + "type": "string", + "description": "Restart is \"queued\" or \"replacing\" while an operator's restart of this replica is under way." + }, + "model": { + "type": "string" + }, + "profile": { + "type": "string" + }, + "stale": { + "type": "boolean", + "description": "Stale is true when the profile has been edited since this replica was placed, so it is running a definition the catalog no longer holds.\n\nReported rather than acted on. Moving a replica that is serving costs more than the imperfection, and the operator who made the edit is the one who should decide whether it is worth a restart." + }, + "state": { + "type": "string" + }, + "pool": { + "type": "string" + }, + "fabric": { + "type": "string" + }, + "endpoint": { + "type": "string" + }, + "age_seconds": { + "type": "integer", + "format": "int64" + }, + "idle_seconds": { + "type": "integer", + "format": "int64", + "description": "IdleSec is how long since a request was routed here. Negative means the router has not reported any use of this replica, which is not the same as idle — it is what a replica looks like before anything has asked for it, and after a router restart." + }, + "error": { + "type": "string" + }, + "shards": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ShardView" + } + } + } + }, + "RequestView": { + "type": "object", + "description": "RequestView is what one request went through.", + "properties": { + "request_id": { + "type": "string" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "key_id": { + "type": "string" + }, + "user_id": { + "type": "string" + }, + "project_id": { + "type": "string" + }, + "model": { + "type": "string" + }, + "served_model": { + "type": "string" + }, + "replica": { + "type": "string" + }, + "status": { + "type": "integer" + }, + "latency_ms": { + "type": "integer", + "format": "int64" + }, + "queue_ms": { + "type": "integer", + "format": "int64" + }, + "ttft_ms": { + "type": "integer", + "format": "int64" + }, + "prompt_tokens": { + "type": "integer", + "format": "int64" + }, + "completion_tokens": { + "type": "integer", + "format": "int64" + }, + "cost_micros": { + "type": "integer", + "format": "int64" + }, + "guard_action": { + "type": "string", + "description": "What the guardrails did, by name." + }, + "guard_policy": { + "type": "string" + }, + "guard_category": { + "type": "string" + }, + "guard_ms": { + "type": "integer", + "format": "int64" + }, + "end_user": { + "type": "string", + "description": "What the client said about it: OpenAI's user field, and its tags." + }, + "tags": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "cache_hit": { + "type": "boolean", + "description": "CacheHit is an answer reused from the project's answer cache." + } + } + }, + "ResourcesRequest": { + "type": "object", + "description": "ResourcesRequest sets what a model's profiles reserve of a node.", + "properties": { + "profile": { + "type": "string", + "description": "Profile is one profile's name; empty is every profile." + }, + "memory_gb": { + "type": "integer" + }, + "cpu_cores": { + "type": "integer" + } + } + }, + "RestartRequest": { + "type": "object", + "description": "RestartRequest names what to restart: replicas by id, every replica of some models, or — All — every ready replica in the cluster.", + "properties": { + "replicas": { + "type": "array", + "items": { + "type": "string" + } + }, + "models": { + "type": "array", + "items": { + "type": "string" + } + }, + "all": { + "type": "boolean" + }, + "in_place": { + "type": "boolean", + "description": "InPlace stops each replica before starting its replacement, rather than starting the replacement beside it first." + } + } + }, + "RestartResult": { + "type": "object", + "description": "RestartResult lists the replicas queued.", + "properties": { + "queued": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "Result": { + "type": "object", + "description": "Result is what a change that has no other answer says it did.", + "properties": { + "result": { + "type": "string" + } + } + }, + "RetryView": { + "type": "object", + "description": "RetryView says whether the model had been parked, given up on after failing to start, before it was retried.", + "properties": { + "was_parked": { + "type": "boolean" + } + } + }, + "ScaleRequest": { + "type": "object", + "description": "ScaleRequest is how many replicas a model should run.", + "properties": { + "min": { + "type": "integer" + }, + "max": { + "type": "integer", + "description": "Max omitted follows Min, which is what the catalog does for a model that declares only a minimum." + }, + "idle_timeout": { + "type": "integer", + "format": "int64", + "description": "A duration, in nanoseconds." + } + } + }, + "ScaleResponse": { + "type": "object", + "description": "ScaleResponse reports the scaling that is now in force.\n\nWhat is in force rather than what was asked for: the catalog fills in a max that was left out, and a caller that echoed its own request would print a number the cluster is not using.", + "properties": { + "model": { + "type": "string" + }, + "min": { + "type": "integer" + }, + "max": { + "type": "integer" + }, + "idle_timeout": { + "type": "integer", + "format": "int64", + "description": "A duration, in nanoseconds." + }, + "on_demand": { + "type": "boolean" + } + } + }, + "ScopeUsageView": { + "type": "object", + "description": "ScopeUsageView is one group's spend, with its quota when it has one.", + "properties": { + "scope": { + "type": "string" + }, + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "keys": { + "type": "integer", + "format": "int64" + }, + "requests": { + "type": "integer", + "format": "int64" + }, + "prompt_tokens": { + "type": "integer", + "format": "int64" + }, + "completion_tokens": { + "type": "integer", + "format": "int64" + }, + "cost_micros": { + "type": "integer", + "format": "int64" + }, + "errors": { + "type": "integer", + "format": "int64" + }, + "last_at": { + "type": "string", + "format": "date-time" + }, + "budget_micros": { + "type": "integer", + "format": "int64", + "description": "Budget is what this level sets, absent when it sets none. A group bounded only by its parent has no budget of its own, and reporting the parent's against each child would read as though each had that much." + }, + "budget_period": { + "type": "string" + }, + "fraction": { + "type": "number", + "description": "Fraction is spend over budget, absent for the same reason." + } + } + }, + "ShardView": { + "type": "object", + "description": "ShardView is one shard of a replica.", + "properties": { + "id": { + "type": "string" + }, + "node": { + "type": "string" + }, + "rank": { + "type": "integer" + }, + "gpus": { + "type": "array", + "items": { + "type": "integer" + } + }, + "state": { + "type": "string" + }, + "error": { + "type": "string" + }, + "fetch": { + "$ref": "#/components/schemas/FetchView", + "description": "Fetch is the download this shard is waiting on, absent when it is not waiting on one. It is what tells a replica pulling a hundred gigabytes apart from one that is wedged — which look identical without it." + }, + "cpu_cores": { + "type": "number", + "description": "CPUCores and MemoryBytes are the engine's use of its node, from the node's last heartbeat; zero when not measured." + }, + "memory_bytes": { + "type": "integer", + "format": "int64" + } + } + }, + "StoreMember": { + "type": "object", + "description": "StoreMember is one member of a replicated store, as its Patroni reports it.", + "properties": { + "name": { + "type": "string" + }, + "host": { + "type": "string" + }, + "role": { + "type": "string" + }, + "state": { + "type": "string" + }, + "lag": { + "type": "integer", + "format": "int64", + "description": "Lag is bytes behind the leader; -1 unknown, 0 for the leader." + } + } + }, + "Summary": { + "type": "object", + "description": "Summary is the whole fleet in one answer.\n\nA per-node listing is the right tool for four nodes and the wrong one for two hundred: the questions that matter at that size — how full am I, what is broken, what is holding cards it is not using — are aggregates, and reading them off a long table is a chore that gets skipped. Everything here is derived from the same state the tables show, so it can never disagree with them; it is a different question asked of the same facts.", + "properties": { + "nodes": { + "$ref": "#/components/schemas/NodeTotals" + }, + "gpus": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ClassUse" + } + }, + "fabrics": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FabricUse" + }, + "description": "Fabrics matter because a multi-node replica may never span two of them, so free capacity in the wrong fabric is not capacity for the model that needs it." + }, + "replicas": { + "$ref": "#/components/schemas/ReplicaTotal" + }, + "models": { + "$ref": "#/components/schemas/ModelTotals" + }, + "unplaceable": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Unplaceable names models the scheduler currently cannot satisfy. This is the line that turns \"something is wrong\" into a place to look." + }, + "parked": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ParkedModel" + }, + "description": "Parked are models that failed every time they started and are no longer retried, with the last error." + }, + "idle_replicas": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IdleReplica" + }, + "description": "IdleReplicas are serving replicas nothing has asked for in a while, which on a fleet with more models than GPUs is the first place to find room." + }, + "store": { + "type": "array", + "items": { + "$ref": "#/components/schemas/StoreMember" + }, + "description": "Store is the members of the store's cluster when it is replicated, and StoreError why it could not be read; both empty for a single database." + }, + "store_error": { + "type": "string" + } + } + }, + "TargetView": { + "type": "object", + "description": "TargetView is how many replicas a model needs to serve a throughput, from what one replica was measured to serve, and whether the cluster has room.", + "properties": { + "model": { + "type": "string" + }, + "tok_per_sec": { + "type": "number", + "description": "TokPerSec is what was asked for; PerReplica what one replica was measured to serve at its SLO, on Profile." + }, + "per_replica_tok_per_sec": { + "type": "number" + }, + "profile": { + "type": "string" + }, + "needed": { + "type": "integer", + "description": "Needed replicas in all; Current hold capacity now; More is how many of Needed are not running, and Room how many more fit." + }, + "current": { + "type": "integer" + }, + "more": { + "type": "integer" + }, + "room": { + "type": "integer" + }, + "fits": { + "type": "boolean" + }, + "blocked": { + "type": "array", + "items": { + "type": "string" + } + }, + "preempts": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Preempts is whose replicas would be stopped to make the room, when free room alone is not enough; Room counts that room too." + } + } + }, + "TopologyView": { + "type": "object", + "description": "TopologyView is one fabric's map, with the cluster's own adapters on it live: their state, rate and traffic from the last heartbeat.", + "properties": { + "id": { + "type": "string" + }, + "key": { + "type": "string" + }, + "label": { + "type": "string" + }, + "declared": { + "type": "array", + "items": { + "type": "string" + } + }, + "scanned_at": { + "type": "string", + "format": "date-time" + }, + "scanned_by": { + "type": "string" + }, + "took_ms": { + "type": "integer", + "format": "int64" + }, + "error": { + "type": "string" + }, + "map": { + "$ref": "#/components/schemas/topology.View" + }, + "live": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/Live" + } + }, + "problems": { + "type": "array", + "items": { + "$ref": "#/components/schemas/fabrics.Problem" + }, + "description": "Problems are the fabric's own, from the analysis of its identity and subnet managers." + }, + "sm": { + "$ref": "#/components/schemas/fabrics.SM" + }, + "sms": { + "type": "array", + "items": { + "$ref": "#/components/schemas/fabrics.SM" + } + } + } + }, + "UpgradeRequest": { + "type": "object", + "description": "UpgradeRequest names the release a node should run.", + "properties": { + "version": { + "type": "string" + } + } + }, + "UpgradeView": { + "type": "object", + "description": "UpgradeView is the release a node was told to run.", + "properties": { + "node": { + "type": "string" + }, + "version": { + "type": "string" + } + } + }, + "bench.Capacity": { + "type": "object", + "description": "Capacity is what one replica was measured to serve, kept so the measurement outlives the terminal it was printed in.\n\nThe conclusion of a run, not the run. The ramp itself — every concurrency level, its latencies, its errors — is worth reading once, while deciding whether the run was sound; it is not worth carrying around afterwards, and storing it would grow without bound as a model is re-benchmarked. What a later reader needs is the number and enough provenance to judge whether it is still true.", + "properties": { + "model": { + "type": "string" + }, + "profile": { + "type": "string" + }, + "max_concurrency_at_slo": { + "type": "integer", + "description": "MaxConcurrencyAtSLO is the capacity: the highest concurrency that still met the target. Zero means even one request did not, which is a real result and not a missing one — it says this hardware cannot serve this model at this SLO at all." + }, + "throughput_tok_per_sec": { + "type": "number", + "description": "ThroughputTokPerSec and the latencies are taken at that level, not at the peak. Peak throughput arrives long after latency has become unusable, so reporting it would overstate what the hardware can serve." + }, + "ttft_p99": { + "type": "integer", + "format": "int64", + "description": "A duration, in nanoseconds." + }, + "tpot_p99": { + "type": "integer", + "format": "int64", + "description": "A duration, in nanoseconds." + }, + "suggested_target_waiting": { + "type": "integer", + "description": "SuggestedTargetWaiting and SuggestedKVCeiling are the queue depth and cache pressure seen while the SLO was still being met, which is what admission should treat as healthy for this model. Admission currently applies one global default to every model; these are the per-model numbers it should be using instead." + }, + "suggested_kv_ceiling": { + "type": "number" + }, + "slo": { + "$ref": "#/components/schemas/bench.SLO", + "description": "SLO is recorded because capacity is meaningless without it. The same replica has a different capacity against a 200ms first-token target than against a 2s one, and a number stored without the target it was measured against cannot be compared with anything." + }, + "target": { + "type": "string", + "description": "Target is the endpoint the load actually went to, kept so a profile measured against the gateway is never mistaken for one measured against a replica. Only the second says anything about the hardware." + }, + "measured_at": { + "type": "string", + "format": "date-time" + } + } + }, + "bench.SLO": { + "type": "object", + "description": "SLO is the latency target capacity is measured against.", + "properties": { + "TTFTp99": { + "type": "integer", + "format": "int64", + "description": "A duration, in nanoseconds." + }, + "TPOTp99": { + "type": "integer", + "format": "int64", + "description": "A duration, in nanoseconds." + } + } + }, + "canary.Side": { + "type": "object", + "description": "Side is what one side of a canary served since it began.", + "properties": { + "requests": { + "type": "integer", + "format": "int64" + }, + "errors": { + "type": "integer", + "format": "int64", + "description": "Errors are answers of 500 and up: the engine's failures, not the client's mistakes." + }, + "ttft_ms": { + "type": "number", + "description": "TTFT is over streamed requests, Latency over the rest, both means in milliseconds with how many they are over." + }, + "ttft_count": { + "type": "integer", + "format": "int64" + }, + "latency_ms": { + "type": "number" + }, + "latency_count": { + "type": "integer", + "format": "int64" + } + } + }, + "canary.Stat": { + "type": "object", + "description": "Stat compares the two sides of one model's canary.", + "properties": { + "canary": { + "type": "string" + }, + "since": { + "type": "string", + "format": "date-time" + }, + "stable": { + "$ref": "#/components/schemas/canary.Side" + }, + "candidate": { + "$ref": "#/components/schemas/canary.Side" + } + } + }, + "catalog.Adapter": { + "type": "object", + "description": "Adapter is a LoRA adapter served on a model's replicas.", + "properties": { + "name": { + "type": "string", + "description": "Name is what clients ask for, like a model name." + }, + "source": { + "type": "string", + "description": "Source is the adapter: a GGUF file for llama.cpp; for vLLM a PEFT adapter directory (a mirror version ending in \"/\", a path on the node, or a Hugging Face repository id). Fetched by each node as the model's weights are." + }, + "scale": { + "type": "number", + "description": "Scale is how strongly it is applied; zero takes 1." + } + } + }, + "catalog.Canary": { + "type": "object", + "description": "Canary is a share of a model's requests sent to a candidate, and when to give up on it.", + "properties": { + "model": { + "type": "string", + "description": "Model is the candidate: a catalog model, usually this one at newer weights, which clients cannot name themselves." + }, + "percent": { + "type": "integer", + "description": "Percent of requests go to it, 0 to 100." + }, + "min_requests": { + "type": "integer", + "description": "The candidate is taken out — rolled back — when, over at least MinRequests of its own, its error rate is MaxErrorIncrease above this model's (0.05 is five points), or its mean time to the first token is MaxTTFTRatio times this model's. Zero is 50, 0.05 and 1.5." + }, + "max_error_increase": { + "type": "number" + }, + "max_ttft_ratio": { + "type": "number" + } + } + }, + "catalog.Capabilities": { + "type": "object", + "description": "Capabilities describes what a client may ask a model for.\n\nDeclared by the operator rather than discovered, because there is no way to ask an engine what its model can do. That makes these claims, and a wrong claim is worse than none — which is why `ctl engine-check` verifies tool calling against a running engine rather than trusting this.\n\nThe reason it exists: the gateway forwards a tools array to any model, and a model that cannot use them answers in prose. Every OpenAI-compatible client then behaves as though the model is broken, and the only way to find out was to try it. That cost an afternoon.", + "properties": { + "tools": { + "type": "boolean" + }, + "vision": { + "type": "boolean" + }, + "embeddings": { + "type": "boolean" + } + } + }, + "catalog.EvalGate": { + "type": "object", + "description": "EvalGate is a quality suite a model's new weights must pass.", + "properties": { + "suite": { + "type": "string", + "description": "Suite is a suite's name in control.eval_dir, or one the binary carries (arithmetic, json-format)." + }, + "min_score": { + "type": "number", + "description": "MinScore is the score, 0 to 1, to pass at; zero is the suite's own threshold." + }, + "judge": { + "type": "string", + "description": "Judge grades the suite's rubric cases, instead of the judge it names." + } + } + }, + "catalog.External": { + "type": "object", + "description": "External is a provider outside the cluster that serves a model.", + "properties": { + "url": { + "type": "string", + "description": "URL is the provider's base address, without /v1: https://api.openai.com." + }, + "model": { + "type": "string", + "description": "Model is what the provider calls it; requests are rewritten to it." + }, + "api_key_file": { + "type": "string", + "description": "APIKeyFile holds the provider's key, on the control plane. A file rather than the key itself, so the key is in neither the catalog, the store nor the audit log; empty for a provider that asks for none." + }, + "peer": { + "type": "string", + "description": "Peer names the federated llmgw cluster this model is offered by, for a model that federation added (`llmgw ctl federation add`) rather than one written by hand. Such a model is named PEER/MODEL, comes and goes with the peer's own list, and is sent only while the peer is up." + } + } + }, + "catalog.GuardModel": { + "type": "object", + "description": "GuardModel is how a judge model's answers are read.", + "properties": { + "format": { + "type": "string", + "description": "Format is llamaguard3 (Meta's Llama Guard 3: \"safe\", or \"unsafe\" and the categories), shieldgemma (Google's ShieldGemma: Yes or No), or json ({\"safe\": false, \"categories\": [\"...\"]})." + }, + "categories": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Categories the model is asked about, for shieldgemma — each a policy sentence — and the names reported for llamaguard3's S1, S2, …." + } + } + }, + "catalog.Model": { + "type": "object", + "description": "Model is a catalog entry as clients see it.", + "properties": { + "name": { + "type": "string" + }, + "aliases": { + "type": "array", + "items": { + "type": "string" + } + }, + "description": { + "type": "string", + "description": "Description is what this model is for, in a line.\n\nWritten by whoever added it, because nobody else can say it. A registry offers a pipeline tag and a wall of README, and neither answers the question a person picking from a list is asking: which of these nine names should I send this request to.\n\nIt reaches clients through /v1/models, which is the only view most of them ever see. A gateway serving nine models by name alone makes that choice by guesswork." + }, + "source": { + "type": "string", + "description": "Source is the weights path or a HuggingFace id." + }, + "profiles": { + "type": "array", + "items": { + "$ref": "#/components/schemas/catalog.Profile" + } + }, + "scaling": { + "$ref": "#/components/schemas/catalog.Scaling" + }, + "class": { + "type": "string", + "description": "Class is how much this model's capacity is worth against another's, when there is not enough for both: critical, standard or opportunistic. Empty is standard, or opportunistic for a model loaded on demand. See EffectiveClass." + }, + "owner": { + "type": "string", + "description": "Owner is the part of the tenancy tree whose capacity quota this model counts against, written org:ID, team:ID or project:ID. Empty is shared: held by the cluster, counted against nobody." + }, + "external": { + "$ref": "#/components/schemas/catalog.External", + "description": "External is a model served by someone else — an OpenAI-compatible API outside the cluster — rather than by replicas placed here. Such a model has no profiles and nothing is placed for it; the router sends its requests to the provider. Most useful named in another model's fallbacks: used only when the cluster has no capacity left. Its prompts leave the cluster, so which keys may name it is worth an allowlist." + }, + "adapters": { + "type": "array", + "items": { + "$ref": "#/components/schemas/catalog.Adapter" + }, + "description": "Adapters are LoRA adapters served on this model's replicas, each asked for by its own name as though it were a model. Every replica loads every adapter, applying one only to a request that names it — unless MaxLoadedAdapters is set." + }, + "max_loaded_adapters": { + "type": "integer", + "description": "MaxLoadedAdapters, above zero, has each replica hold at most this many adapters at once, loaded when a request first asks for one and unloaded least recently used first to make room. The router sends a request for an adapter to a replica that already holds it while that one has room to take it. vLLM profiles only: llama-server loads adapters at start and cannot load one afterwards. Zero loads every adapter on every replica at start." + }, + "fallbacks": { + "type": "array", + "items": { + "type": "string" + } + }, + "canary": { + "$ref": "#/components/schemas/catalog.Canary", + "description": "Canary sends a share of this model's requests to another catalog model — the same model at new weights — to compare the two before moving to it (`llmgw ctl model canary`)." + }, + "eval": { + "$ref": "#/components/schemas/catalog.EvalGate", + "description": "Eval is a quality suite new weights must pass before they replace this model's: `llmgw ctl model update` and `model promote` run it against them first, and stop below its score." + }, + "routing_profile": { + "type": "string", + "description": "RoutingProfile selects how the router scores endpoints for this model." + }, + "slo": { + "$ref": "#/components/schemas/catalog.SLO" + }, + "context_length": { + "type": "integer", + "description": "ContextLength is how many tokens one request may use, prompt and completion together, and MaxOutput bounds the completion alone. Zero means unknown, which is what every model was until now.\n\nThe gateway knew neither, so an over-long prompt was not refused: it was admitted, given a replica, and failed at the engine, and a client sizing its prompts from /v1/models had nothing to read. Worse, the number is not the one an operator writes in the engine's arguments — llama.cpp divides --ctx-size across its parallel slots, so a pool of 8192 across four slots is 2048 a request, and nothing said so." + }, + "max_output": { + "type": "integer" + }, + "capabilities": { + "$ref": "#/components/schemas/catalog.Capabilities", + "description": "Capabilities is what this model can do beyond plain completion." + }, + "role": { + "type": "string", + "description": "Role \"guard\" is a model that judges the gateway's traffic for the guardrails rather than serving clients: hidden from /v1/models and the chat page, refused to any key that names it, critical by default, and always running. Guard says how its answers are read." + }, + "guard": { + "$ref": "#/components/schemas/catalog.GuardModel" + }, + "origin": { + "$ref": "#/components/schemas/catalog.Origin", + "description": "Origin is the registry repository the weights came from, at which commit, and each file's checksum there. Written when a model is served from the registry; for one that was not, worked out from the mirror's record of where it fetched the file. It is what lets the control plane say that the repository has published different weights since, and move the model to them." + } + } + }, + "catalog.Origin": { + "type": "object", + "description": "Origin is where a model's weights were published.", + "properties": { + "repo": { + "type": "string", + "description": "Repo is the repository, owner/name." + }, + "revision": { + "type": "string", + "description": "Revision is the commit the files were fetched at." + }, + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/catalog.OriginFile" + }, + "description": "Files are the weights fetched from it, with what the registry published as each one's sha256. A new commit that leaves them alone — a README edited — is not an update." + }, + "previous": { + "$ref": "#/components/schemas/catalog.PreviousOrigin", + "description": "Previous is what the last update replaced, kept so it can be gone back to while its files are still on the mirror." + } + } + }, + "catalog.OriginFile": { + "type": "object", + "description": "OriginFile is one weights file of an origin.", + "properties": { + "path": { + "type": "string" + }, + "sha256": { + "type": "string" + }, + "bytes": { + "type": "integer", + "format": "int64" + } + } + }, + "catalog.PreviousOrigin": { + "type": "object", + "description": "PreviousOrigin is a model's source before an update, and where it came from.", + "properties": { + "source": { + "type": "string" + }, + "revision": { + "type": "string" + }, + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/catalog.OriginFile" + } + } + } + }, + "catalog.Profile": { + "type": "object", + "description": "Profile is how a model runs on one GPU class.", + "properties": { + "name": { + "type": "string" + }, + "engine": { + "type": "string" + }, + "gpu_class": { + "type": "string" + }, + "tp": { + "type": "integer" + }, + "pp": { + "type": "integer" + }, + "gpus_per_node": { + "type": "integer", + "description": "GPUsPerNode defaults to TP for a single-node profile." + }, + "nodes": { + "type": "integer", + "description": "Nodes above 1 makes this a multi-node profile, which requires a fabric." + }, + "args": { + "type": "array", + "items": { + "type": "string" + } + }, + "env": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "min_memory_gb": { + "type": "integer", + "description": "MinMemoryGB is the host RAM this profile needs to run.\n\nThe number that matters is the model's working set: the weights, plus the KV cache for the whole context pool, plus the engine's own overhead. For a GPU profile that lives in the cards and this is small; for a CPU profile it is the whole thing, and getting it wrong means an OOM on a node that reported itself healthy.\n\nZero means unconstrained, which is every profile that existed before this. A node that does not report its memory is not excluded either — an older agent must not have its nodes quietly emptied by an upgrade of the control plane." + }, + "cpu_cores": { + "type": "integer", + "description": "CPUCores is the cores a replica of a profile with no GPU is given: reserved out of its node's CPUs by placement, as memory is, and what its engine computes on (llama.cpp's --threads).\n\nReserved because an engine takes every core it is told about, and two on one node that each think they have all of them spin against each other: on an 8-vCPU node, two 7B replicas fell from 10 tokens a second to under one each. Zero reserves nothing and leaves the thread count to the node, which is every profile from before this." + }, + "min_disk_gb": { + "type": "integer", + "description": "MinDiskGB is the free space a node needs before it can hold these weights.\n\nOnly checked when the node does not already have them: a node holding the file needs no room for it, and requiring the space twice would keep a model off the one node best placed to run it.\n\nDeclared rather than derived, because the size of a model that has never been fetched anywhere is not knowable from here — and a wrong guess fails late, halfway through a download, which is the failure this exists to prevent. Zero means unconstrained, and a node that reports no storage is not excluded: unknown is not full." + }, + "node_selector": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "NodeSelector restricts this profile to nodes carrying every one of these labels, with these values.\n\nA CPU profile otherwise fits everywhere, because there is no card to be free — which is right for a 0.5B model and wrong for a 14B one. Nothing in the inventory says how much memory a node has, so the operator says which nodes are meant for a model instead of the scheduler inferring it. Agents have reported labels since the beginning; this is what reads them." + }, + "power_watts": { + "type": "number", + "description": "PowerWatts is what one replica of this profile draws, in watts, split evenly over its nodes, counted against the power cap of every rack, PDU or other domain its nodes are in (facility.budgets in server.yaml). Zero derives it: each card at the power limit it reports, each reserved core at facility.cpu_core_watts. Only matters where a domain has a cap." + }, + "keep_within": { + "type": "string", + "description": "KeepWithin keeps a multi-node replica's nodes inside one rack, row, room or site, read from their llmgw.io/rack (and so on) labels: for a fabric whose leaves do not reach across racks, or cables that do not. Nodes without the label are passed over for such a profile. Empty is no constraint." + }, + "weight": { + "type": "number", + "description": "Weight is the router's capacity weight. It should come from ctl bench rather than a guess (plan §6.2.1)." + }, + "priority": { + "type": "integer", + "description": "Priority orders profiles during placement; highest that fits wins." + }, + "startup_timeout": { + "type": "integer", + "format": "int64", + "description": "StartupTimeout bounds model loading. A 70B model across two nodes takes tens of minutes, so this is per profile rather than global.\n\nA duration, in nanoseconds." + }, + "kv_events": { + "type": "boolean", + "description": "KVEvents has vLLM publish what its prefix cache holds, and the router route this model's requests by it: to the replica holding the most of a prompt's leading blocks (plan §7.5 tier 2). vLLM only.\n\nOff by default, because it costs something on every request: the router asks a replica to tokenize the prompt before placing it, a round trip and the chat template run twice. It pays where prompts share long prefixes that the approximate tree guesses wrong — many replicas, conversations that move between them, evictions. The engine is started with sha256_cbor block hashing and a fixed PYTHONHASHSEED, which the router's hashing assumes; arguments overriding either leave the index empty, and the agent says so in its log." + } + } + }, + "catalog.SLO": { + "type": "object", + "description": "SLO is the latency target a model is expected to meet. `ctl bench` measures capacity against it (plan §6.2.1), and admission holds the lower bands back while the model's recent p99 is past it.", + "properties": { + "TTFTp99": { + "type": "integer", + "format": "int64", + "description": "TTFTp99 is the time to the first token 99 requests in 100 are within.\n\nA duration, in nanoseconds." + }, + "TPOTp99": { + "type": "integer", + "format": "int64", + "description": "TPOTp99 is the time per output token, after the first, 99 streamed requests in 100 are within.\n\nA duration, in nanoseconds." + } + } + }, + "catalog.ScaleWindow": { + "type": "object", + "description": "ScaleWindow is a part of the week with its own min and max.", + "properties": { + "days": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Days are mon … sun, or weekdays, weekends; empty is every day." + }, + "from": { + "type": "string", + "description": "From and To are HH:MM; a window whose To is before its From runs past midnight." + }, + "to": { + "type": "string" + }, + "min": { + "type": "integer" + }, + "max": { + "type": "integer", + "description": "Max, when set, is the window's ceiling for load scaling; zero keeps the model's own." + } + } + }, + "catalog.Scaling": { + "type": "object", + "description": "Scaling is how many replicas a model should have.", + "properties": { + "min": { + "type": "integer" + }, + "max": { + "type": "integer" + }, + "idle_timeout": { + "type": "integer", + "format": "int64", + "description": "IdleTimeout is how long an on-demand model may go unasked-for before its replicas are stopped. Zero takes the cluster default.\n\nMinutes rather than seconds, always. Stopping a replica throws away the KV cache prefix routing spent its effort filling, and a model that flaps in and out loses that entirely — so the saving has to be worth more than the cache, which it only is over a real idle period.\n\nA duration, in nanoseconds." + }, + "schedule": { + "type": "array", + "items": { + "$ref": "#/components/schemas/catalog.ScaleWindow" + }, + "description": "Schedule changes min and max by the time of day, in the control plane's control.timezone: more replicas kept through working hours, fewer at night, an on-demand model kept loaded while people are at work. The first window that holds now wins; outside them all, Min and Max apply." + }, + "prewarm": { + "type": "integer", + "format": "int64", + "description": "Prewarm starts a window this long before it opens, so its replicas have loaded by then: loading a model is minutes, and the people who arrive at nine are the reason for the window.\n\nA duration, in nanoseconds." + } + } + }, + "eval.Live": { + "type": "object", + "description": "Live is a run as it stands: one running, with how many of its cases are done, or one finished.", + "properties": { + "id": { + "type": "string" + }, + "model": { + "type": "string", + "description": "Model is the model the run is about; Target the catalog model that answered, when that was another — its canary, or the new weights an update tried before moving to them." + }, + "target": { + "type": "string" + }, + "repo": { + "type": "string", + "description": "Repo and Revision are where the weights that answered came from, when that is known." + }, + "revision": { + "type": "string" + }, + "suite": { + "type": "string", + "description": "Suite is its name, SuiteHash the sha256 of its text." + }, + "suite_hash": { + "type": "string" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "took_ms": { + "type": "integer", + "format": "int64" + }, + "score": { + "type": "number", + "description": "Score is the cases' scores weighed, 0 to 1; Passed whether it reached Threshold." + }, + "threshold": { + "type": "number" + }, + "passed": { + "type": "boolean" + }, + "cases": { + "type": "integer", + "description": "Cases were asked; Below scored under half; Errors got no answer." + }, + "below": { + "type": "integer" + }, + "errors": { + "type": "integer" + }, + "judge": { + "type": "string" + }, + "by": { + "type": "string" + }, + "job": { + "type": "string", + "description": "Job is the update or promotion the run gated, if one did." + }, + "error": { + "type": "string", + "description": "Error is why the run could not be scored at all." + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/store.EvalCase" + } + }, + "state": { + "type": "string" + }, + "done": { + "type": "integer" + } + } + }, + "eval.Request": { + "type": "object", + "description": "Request is a suite to run against a model: one on the control plane, by its name, or one sent whole.", + "properties": { + "suite": { + "type": "string", + "description": "Suite is a suite's name in the eval directory, or carried in the binary (arithmetic, json-format)." + }, + "content": { + "type": "string", + "description": "Content is a suite's text instead, and File the name of the file it was read from, which names the suite unless it names itself." + }, + "file": { + "type": "string" + }, + "concurrency": { + "type": "integer", + "description": "Concurrency, Judge and MinScore are as Options has them." + }, + "judge": { + "type": "string" + }, + "min_score": { + "type": "number" + } + } + }, + "eval.SuiteInfo": { + "type": "object", + "description": "SuiteInfo is a suite the control plane can run by name.", + "properties": { + "name": { + "type": "string" + }, + "from": { + "type": "string", + "description": "From is the file it is read from, or \"built in\"." + }, + "description": { + "type": "string" + }, + "cases": { + "type": "integer" + }, + "threshold": { + "type": "number" + }, + "judge": { + "type": "boolean" + }, + "hash": { + "type": "string" + }, + "error": { + "type": "string", + "description": "Error is why the file cannot be run." + } + } + }, + "fabrics.Change": { + "type": "object", + "description": "Change is a fabric's master subnet manager changing, as its ports saw it.", + "properties": { + "at": { + "type": "string", + "format": "date-time" + }, + "from": { + "type": "string" + }, + "to": { + "type": "string" + }, + "ports": { + "type": "integer" + } + } + }, + "fabrics.Member": { + "type": "object", + "description": "Member is one node's adapters on a physical fabric.", + "properties": { + "node": { + "type": "string" + }, + "hcas": { + "type": "array", + "items": { + "type": "string" + } + }, + "declared": { + "type": "string", + "description": "Declared is the name this node gives these adapters, empty when it declares them in no fabric." + } + } + }, + "fabrics.Physical": { + "type": "object", + "description": "Physical is one fabric as the adapters find it.", + "properties": { + "key": { + "type": "string" + }, + "kind": { + "type": "string", + "description": "Kind is infiniband or roce." + }, + "label": { + "type": "string", + "description": "Label is the key as a person reads it." + }, + "sm": { + "$ref": "#/components/schemas/fabrics.SM", + "description": "SM is the master subnet manager, on InfiniBand: the one most of its ports see." + }, + "sms": { + "type": "array", + "items": { + "$ref": "#/components/schemas/fabrics.SM" + }, + "description": "SMs is every subnet manager the fabric lists, master first; empty when no port could ask. Standbys counts those that could take over." + }, + "standbys": { + "type": "integer" + }, + "masters": { + "type": "object", + "additionalProperties": { + "type": "integer" + }, + "description": "Masters is how many ports see each master, when they do not all agree." + }, + "changes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/fabrics.Change" + }, + "description": "Changes are the master changes seen in the last day, newest first." + }, + "declared": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Declared are the names nodes gave this fabric; one, when all is well." + }, + "members": { + "type": "array", + "items": { + "$ref": "#/components/schemas/fabrics.Member" + } + }, + "rate_gbps": { + "type": "integer" + }, + "gid_prefix": { + "type": "string" + } + } + }, + "fabrics.Problem": { + "type": "object", + "description": "Problem is one disagreement, in words.", + "properties": { + "level": { + "type": "string" + }, + "fabric": { + "type": "string" + }, + "message": { + "type": "string" + } + } + }, + "fabrics.Report": { + "type": "object", + "description": "Report is the whole picture.", + "properties": { + "physical": { + "type": "array", + "items": { + "$ref": "#/components/schemas/fabrics.Physical" + } + }, + "problems": { + "type": "array", + "items": { + "$ref": "#/components/schemas/fabrics.Problem" + } + }, + "unverified": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + }, + "description": "Unverified are declared fabrics some of whose nodes cannot say which physical fabric they are on, with why." + } + } + }, + "fabrics.SM": { + "type": "object", + "description": "SM is a subnet manager as the ports see it.", + "properties": { + "guid": { + "type": "string" + }, + "lid": { + "type": "integer" + }, + "priority": { + "type": "integer" + }, + "state": { + "type": "string" + } + } + }, + "facility.Location": { + "type": "object", + "description": "Location is where a node is, read from its labels. Empty fields are not known, which places as it always did.", + "properties": { + "site": { + "type": "string" + }, + "room": { + "type": "string" + }, + "row": { + "type": "string" + }, + "rack": { + "type": "string" + }, + "pdus": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "federation.AddRequest": { + "type": "object", + "description": "AddRequest adds a peer.", + "properties": { + "name": { + "type": "string", + "description": "Name is what this cluster calls the peer, and the prefix of its models: NAME/MODEL." + }, + "url": { + "type": "string", + "description": "URL is the peer gateway's client address, without /v1." + }, + "key_file": { + "type": "string", + "description": "KeyFile is a file on the control plane holding a key the peer issued to this cluster (or env:NAME, vault:PATH#FIELD)." + }, + "send_tags": { + "type": "boolean", + "description": "SendTags makes requests sent to the peer carry x-llmgw-tags naming this cluster and the sending project. Off unless asked: the peer learns who in this cluster is asking." + } + } + }, + "federation.ModelStatus": { + "type": "object", + "description": "ModelStatus is one of a peer's models: its name here, the peer's own, and whether the peer has stopped offering it.", + "properties": { + "name": { + "type": "string" + }, + "upstream": { + "type": "string" + }, + "withdrawn": { + "type": "boolean" + } + } + }, + "federation.Status": { + "type": "object", + "description": "Status is a peer as `llmgw ctl federation list` shows it.", + "properties": { + "name": { + "type": "string" + }, + "url": { + "type": "string" + }, + "key_file": { + "type": "string" + }, + "send_tags": { + "type": "boolean" + }, + "cluster": { + "type": "string", + "description": "Cluster is the peer's own cluster id." + }, + "up": { + "type": "boolean" + }, + "checked": { + "type": "string", + "format": "date-time", + "description": "Checked is when; zero before the first check." + }, + "latency_ns": { + "type": "integer", + "format": "int64", + "description": "Latency is how long the peer took to answer /ready: the network to the other site and the peer's front, not a model's speed.\n\nA duration, in nanoseconds." + }, + "error": { + "type": "string", + "description": "Error is why the peer is down, empty while it is up." + }, + "latency_ms": { + "type": "number", + "description": "LatencyMs is Latency in milliseconds, for reading." + }, + "synced_at": { + "type": "string", + "format": "date-time", + "description": "SyncedAt is when its models last changed here." + }, + "models": { + "type": "array", + "items": { + "$ref": "#/components/schemas/federation.ModelStatus" + } + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "created_by": { + "type": "string" + } + } + }, + "guard.Attachment": { + "type": "object", + "description": "Attachment ties a policy to a part of the tenancy tree: scope is org, team, project, user or key, and ScopeID which one.", + "properties": { + "Scope": { + "type": "string" + }, + "ScopeID": { + "type": "string" + }, + "Policy": { + "type": "string" + } + } + }, + "inventory.EngineInstall": { + "type": "object", + "description": "EngineInstall is where one engine's installation stands on a node.", + "properties": { + "engine": { + "type": "string" + }, + "version": { + "type": "string" + }, + "variant": { + "type": "string" + }, + "state": { + "type": "string", + "description": "State is \"installing\", \"ready\", \"failed\" or \"unsupported\"." + }, + "detail": { + "type": "string" + } + } + }, + "inventory.GPUSensor": { + "type": "object", + "description": "GPUSensor is one card's heat and power, and what is throttling it.", + "properties": { + "index": { + "type": "integer" + }, + "temp_c": { + "type": "number" + }, + "memory_temp_c": { + "type": "number" + }, + "power_w": { + "type": "number" + }, + "power_limit_w": { + "type": "number" + }, + "throttle": { + "type": "array", + "items": { + "type": "string" + } + }, + "util_percent": { + "type": "number", + "description": "How busy the card is, as of this sample; -1 is not reported. Zero MemoryTotalMB is an agent too old to send these, whose figures are the ones it read at registration." + }, + "mem_util_percent": { + "type": "number" + }, + "memory_used_mb": { + "type": "number" + }, + "memory_total_mb": { + "type": "number" + }, + "sm_clock_mhz": { + "type": "number" + }, + "ecc_uncorrected": { + "type": "number" + }, + "wear": { + "$ref": "#/components/schemas/inventory.GPUWear", + "description": "Wear is what wears the card out, read every minute; nil from an agent that does not read it." + } + } + }, + "inventory.GPUWear": { + "type": "object", + "description": "GPUWear is a card's wear and failures. Counts of -1 are not reported for it: a card before Ampere has no remapped rows, one after no retired pages.", + "properties": { + "pcie_replays": { + "type": "integer", + "format": "int64" + }, + "retired_pages_sbe": { + "type": "integer", + "format": "int64" + }, + "retired_pages_dbe": { + "type": "integer", + "format": "int64" + }, + "retire_pending": { + "type": "boolean" + }, + "remapped_rows_correctable": { + "type": "integer", + "format": "int64" + }, + "remapped_rows_uncorrectable": { + "type": "integer", + "format": "int64" + }, + "remap_pending": { + "type": "boolean" + }, + "remap_failure": { + "type": "boolean" + }, + "nvlink_crc_errors": { + "type": "integer", + "format": "int64" + }, + "nvlink_replay_errors": { + "type": "integer", + "format": "int64" + }, + "nvlink_recovery_errors": { + "type": "integer", + "format": "int64" + }, + "xid_errors": { + "type": "integer", + "format": "int64" + }, + "last_xid": { + "type": "integer" + }, + "last_xid_text": { + "type": "string" + }, + "last_xid_at": { + "type": "string", + "format": "date-time" + } + } + }, + "modelplan.Option": { + "type": "object", + "description": "Option is one way to run one artifact.", + "properties": { + "artifact": { + "type": "string" + }, + "format": { + "type": "string" + }, + "engine": { + "type": "string" + }, + "cpu": { + "type": "boolean" + }, + "gpu_class": { + "type": "string" + }, + "fabric": { + "type": "string" + }, + "gpus_per_node": { + "type": "integer", + "description": "GPUsPerNode cards on each of Nodes nodes." + }, + "nodes": { + "type": "integer" + }, + "need_gb": { + "type": "number", + "description": "NeedGB is what one card holds, or for CPU the whole replica in RAM; HaveGB what a card, or the node, offers for it." + }, + "have_gb": { + "type": "number" + }, + "hosts": { + "type": "integer", + "description": "Hosts is how many nodes could run it at all, and FreeNow whether one (or enough, together) could right now." + }, + "free_now": { + "type": "boolean" + }, + "bits_per_weight": { + "type": "number", + "description": "BitsPerWeight is the artifact's precision, 0 when unknown." + } + } + }, + "modelserve.CanaryView": { + "type": "object", + "description": "CanaryView is one model's canary as it stands.", + "properties": { + "model": { + "type": "string" + }, + "canary": { + "$ref": "#/components/schemas/catalog.Canary" + }, + "serving": { + "$ref": "#/components/schemas/canary.Stat" + } + } + }, + "modelserve.Change": { + "type": "object", + "description": "Change is how an update or a promotion is held to quality.", + "properties": { + "eval": { + "$ref": "#/components/schemas/eval.Request", + "description": "Eval is a suite the new weights must pass first. Nil takes the model's own (eval: in its catalog entry), if it has one." + }, + "skip_eval": { + "type": "boolean", + "description": "SkipEval moves without the model's own suite; the job says so." + } + } + }, + "modelserve.Job": { + "type": "object", + "description": "Job is one model being served, and where it stands.", + "properties": { + "id": { + "type": "string" + }, + "kind": { + "type": "string", + "description": "Kind is \"update\" for a model moved to new weights, empty for one served." + }, + "request": { + "$ref": "#/components/schemas/modelserve.Request" + }, + "state": { + "type": "string" + }, + "error": { + "type": "string" + }, + "model": { + "type": "string" + }, + "steps": { + "type": "array", + "items": { + "$ref": "#/components/schemas/modelserve.Step" + } + }, + "started": { + "type": "string", + "format": "date-time" + }, + "reply": { + "type": "string", + "description": "Reply is what the model said to the smoke test, and TokensPerSecond how fast it said it." + }, + "tokens_per_second": { + "type": "number" + }, + "eval": { + "$ref": "#/components/schemas/store.EvalRun", + "description": "Eval is the quality suite the new weights were asked before they replaced the old, and how they scored, without each case." + } + } + }, + "modelserve.Plan": { + "type": "object", + "description": "Plan is every way a repository's files could run here, best first.", + "properties": { + "repo": { + "type": "string" + }, + "revision": { + "type": "string" + }, + "format": { + "type": "string" + }, + "architecture": { + "type": "string" + }, + "license": { + "type": "string" + }, + "params": { + "type": "integer", + "format": "int64" + }, + "context": { + "type": "integer" + }, + "gated": { + "type": "boolean" + }, + "servable": { + "type": "boolean", + "description": "Servable is false when the nodes' engine cannot run the model at all, and Reason says why." + }, + "reason": { + "type": "string" + }, + "note": { + "type": "string", + "description": "Note is anything the plan could not know, said once." + }, + "projectors": { + "type": "array", + "items": { + "type": "string" + } + }, + "artifacts": { + "type": "array", + "items": { + "$ref": "#/components/schemas/modelserve.PlannedArtifact" + } + }, + "options": { + "type": "array", + "items": { + "$ref": "#/components/schemas/modelplan.Option" + } + } + } + }, + "modelserve.PlannedArtifact": { + "type": "object", + "description": "PlannedArtifact is one file a repository offers, and the best way to run it.", + "properties": { + "name": { + "type": "string", + "description": "Name is the file, or the set's name; for original weights, \"original\"." + }, + "format": { + "type": "string", + "description": "\"gguf\" or \"safetensors\"" + }, + "bytes": { + "type": "integer", + "format": "int64" + }, + "shards": { + "type": "integer" + }, + "quant": { + "type": "string", + "description": "Quant is the quantisation read from the name, like Q4_K_M; \"bf16\" for original weights." + }, + "best": { + "$ref": "#/components/schemas/modelplan.Option" + } + } + }, + "modelserve.Request": { + "type": "object", + "description": "Request is what to serve.", + "properties": { + "repo": { + "type": "string", + "description": "Repo is the registry repository, owner/name." + }, + "quant": { + "type": "string", + "description": "Quant picks the file by its quantisation, Q4_K_M unless given." + }, + "file": { + "type": "string", + "description": "File picks it by name instead." + }, + "projector": { + "type": "string", + "description": "Projector is a vision model's mmproj file in the repository, fetched beside the weights and loaded with them; empty serves text alone." + }, + "format": { + "type": "string", + "description": "Format is \"gguf\", run by llama.cpp, or \"safetensors\": the original weights with their config and tokenizer, run by vLLM on GPUs of GPUClass, across TP of them." + }, + "cpu": { + "type": "boolean", + "description": "Where it runs: on the CPU, or on GPUsPerNode cards of GPUClass on each of Nodes nodes. Left empty, the plan decides: the best way the cluster can run the chosen file. TP is GPUsPerNode's older name." + }, + "gpu_class": { + "type": "string" + }, + "gpus_per_node": { + "type": "integer" + }, + "nodes": { + "type": "integer" + }, + "tp": { + "type": "integer" + }, + "fallbacks": { + "type": "boolean", + "description": "Fallbacks adds the next best ways, lower in priority, so a model whose first choice is busy runs on another rather than waiting." + }, + "name": { + "type": "string", + "description": "Name is the catalog name; the repository suggests one otherwise." + }, + "aliases": { + "type": "array", + "items": { + "type": "string" + } + }, + "description": { + "type": "string" + }, + "replicas": { + "type": "integer", + "description": "Replicas to run; 0 makes it on demand, loaded when first asked for." + }, + "guard_format": { + "type": "string", + "description": "GuardFormat makes it a judge model for the guardrails (role: guard): llamaguard3, shieldgemma or json. Empty serves clients." + }, + "ctx_pool": { + "type": "integer", + "description": "CtxPool is llama.cpp's --ctx-size; ContextLength what one request may use. They default to 16384 and 4096, what four parallel slots divide." + }, + "context_length": { + "type": "integer" + }, + "cpu_cores": { + "type": "integer", + "description": "CPUCores is what a replica computes on; zero takes half the smallest node it fits on." + } + } + }, + "modelserve.Step": { + "type": "object", + "description": "Step is one stage of a job.", + "properties": { + "name": { + "type": "string" + }, + "state": { + "type": "string" + }, + "detail": { + "type": "string" + }, + "at": { + "type": "string", + "format": "date-time" + } + } + }, + "modelserve.UpdateInfo": { + "type": "object", + "description": "UpdateInfo is what the registry has for a model against what it runs.", + "properties": { + "model": { + "type": "string" + }, + "repo": { + "type": "string" + }, + "current": { + "type": "string", + "description": "Current is the commit the model runs, Latest the repository's now." + }, + "latest": { + "type": "string" + }, + "changed": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Changed are the model's files whose weights differ at Latest, and Missing those Latest no longer has at all." + }, + "missing": { + "type": "array", + "items": { + "type": "string" + } + }, + "bytes": { + "type": "integer", + "format": "int64", + "description": "Bytes is what an update downloads." + }, + "available": { + "type": "boolean", + "description": "Available is true when the model can be moved to Latest." + }, + "previous": { + "type": "string", + "description": "Previous is the commit an update replaced, which it can go back to." + }, + "checked_at": { + "type": "string", + "format": "date-time" + }, + "error": { + "type": "string" + } + } + }, + "notify.Result": { + "type": "object", + "description": "Result is how one webhook answered a test.", + "properties": { + "url": { + "type": "string" + }, + "error": { + "type": "string" + } + } + }, + "nvlink.Domain": { + "type": "object", + "description": "Domain is one multi-node NVLink domain.", + "properties": { + "key": { + "type": "string" + }, + "cluster_uuid": { + "type": "string" + }, + "clique_id": { + "type": "string" + }, + "members": { + "type": "array", + "items": { + "$ref": "#/components/schemas/nvlink.Member" + } + }, + "gpus": { + "type": "integer" + }, + "joined": { + "type": "integer" + }, + "usable_nodes": { + "type": "integer" + } + } + }, + "nvlink.GPU": { + "type": "object", + "description": "GPU is one card as its domain sees it.", + "properties": { + "index": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "state": { + "type": "string" + }, + "status": { + "type": "string" + }, + "bandwidth": { + "type": "string" + }, + "joined": { + "type": "boolean" + } + } + }, + "nvlink.Member": { + "type": "object", + "description": "Member is one node of a domain.", + "properties": { + "node": { + "type": "string" + }, + "gpus": { + "type": "array", + "items": { + "$ref": "#/components/schemas/nvlink.GPU" + } + }, + "usable": { + "type": "boolean", + "description": "Usable is every card joined and IMEX up: what placement requires." + }, + "imex": { + "type": "string" + }, + "imex_channels": { + "type": "integer" + } + } + }, + "nvlink.Problem": { + "type": "object", + "description": "Problem is one thing wrong with a domain.", + "properties": { + "level": { + "type": "string" + }, + "domain": { + "type": "string" + }, + "message": { + "type": "string" + } + } + }, + "nvlink.Report": { + "type": "object", + "description": "Report is every domain and what is wrong with them.", + "properties": { + "domains": { + "type": "array", + "items": { + "$ref": "#/components/schemas/nvlink.Domain" + } + }, + "problems": { + "type": "array", + "items": { + "$ref": "#/components/schemas/nvlink.Problem" + } + } + } + }, + "promq.Point": { + "type": "object", + "description": "Point is one sample.", + "properties": { + "At": { + "type": "string", + "format": "date-time" + }, + "Value": { + "type": "number" + } + } + }, + "promq.Series": { + "type": "object", + "description": "Series is one line: a name and its points, oldest first.", + "properties": { + "Name": { + "type": "string" + }, + "Points": { + "type": "array", + "items": { + "$ref": "#/components/schemas/promq.Point" + } + } + } + }, + "quota.Amount": { + "type": "object", + "description": "Amount is how much of each resource something holds or needs.", + "properties": { + "GPUs": { + "type": "integer" + }, + "CPUCores": { + "type": "integer" + }, + "MemoryGB": { + "type": "integer" + } + } + }, + "store.AuditEvent": { + "type": "object", + "description": "AuditEvent is one change: who made it, through what, to what, and how it ended. Detail never holds a secret; the writer takes them out.", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "actor": { + "type": "string" + }, + "source": { + "type": "string", + "description": "api, web" + }, + "action": { + "type": "string", + "description": "\"POST /api/v1/models\", \"POST /admin/users/{id}/suspend\"" + }, + "target": { + "type": "string" + }, + "detail": { + "type": "string" + }, + "status": { + "type": "integer" + } + } + }, + "store.EvalCase": { + "type": "object", + "description": "EvalCase is one case of a run: how its answer scored, and why.", + "properties": { + "id": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "weight": { + "type": "number" + }, + "score": { + "type": "number" + }, + "passed": { + "type": "boolean" + }, + "answer": { + "type": "string" + }, + "detail": { + "type": "string" + }, + "error": { + "type": "string" + }, + "took_ms": { + "type": "integer", + "format": "int64" + } + } + }, + "store.EvalRun": { + "type": "object", + "description": "EvalRun is one quality suite run against a model, as `llmgw ctl eval` and the gate on an update keep it.", + "properties": { + "id": { + "type": "string" + }, + "model": { + "type": "string", + "description": "Model is the model the run is about; Target the catalog model that answered, when that was another — its canary, or the new weights an update tried before moving to them." + }, + "target": { + "type": "string" + }, + "repo": { + "type": "string", + "description": "Repo and Revision are where the weights that answered came from, when that is known." + }, + "revision": { + "type": "string" + }, + "suite": { + "type": "string", + "description": "Suite is its name, SuiteHash the sha256 of its text." + }, + "suite_hash": { + "type": "string" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "took_ms": { + "type": "integer", + "format": "int64" + }, + "score": { + "type": "number", + "description": "Score is the cases' scores weighed, 0 to 1; Passed whether it reached Threshold." + }, + "threshold": { + "type": "number" + }, + "passed": { + "type": "boolean" + }, + "cases": { + "type": "integer", + "description": "Cases were asked; Below scored under half; Errors got no answer." + }, + "below": { + "type": "integer" + }, + "errors": { + "type": "integer" + }, + "judge": { + "type": "string" + }, + "by": { + "type": "string" + }, + "job": { + "type": "string", + "description": "Job is the update or promotion the run gated, if one did." + }, + "error": { + "type": "string", + "description": "Error is why the run could not be scored at all." + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/store.EvalCase" + } + } + } + }, + "store.ExportRow": { + "type": "object", + "description": "ExportRow is one line of a usage export: a period, the place, person, key and model it is about — those asked for, the rest empty — and what was used.", + "properties": { + "Period": { + "type": "string", + "format": "date-time" + }, + "Org": { + "type": "string" + }, + "Team": { + "type": "string" + }, + "Project": { + "type": "string" + }, + "User": { + "type": "string" + }, + "Key": { + "type": "string" + }, + "Model": { + "type": "string" + }, + "Requests": { + "type": "integer", + "format": "int64" + }, + "Errors": { + "type": "integer", + "format": "int64" + }, + "Limited": { + "type": "integer", + "format": "int64" + }, + "Prompt": { + "type": "integer", + "format": "int64" + }, + "Completion": { + "type": "integer", + "format": "int64" + }, + "CostMicros": { + "type": "integer", + "format": "int64" + } + } + }, + "store.RequestBody": { + "type": "object", + "description": "RequestBody is one kept request and its answer.", + "properties": { + "request_id": { + "type": "string" + }, + "project_id": { + "type": "string" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "expires_at": { + "type": "string", + "format": "date-time" + }, + "path": { + "type": "string" + }, + "model": { + "type": "string" + }, + "served_model": { + "type": "string" + }, + "status": { + "type": "integer" + }, + "request": { + "type": "string" + }, + "response": { + "type": "string", + "description": "Response is the answer's text as the client was sent it; Truncated says it was longer than what is kept." + }, + "truncated": { + "type": "boolean" + } + } + }, + "store.Resources": { + "type": "object", + "description": "Resources are amounts of the three things a replica holds of a cluster. Nil is not governed: nothing guaranteed, or nothing limited.", + "properties": { + "gpus": { + "type": "integer" + }, + "cpu_cores": { + "type": "integer" + }, + "memory_gb": { + "type": "integer" + } + } + }, + "topology.HostView": { + "type": "object", + "description": "HostView is an adapter, and the node it is in when the cluster knows it.", + "properties": { + "guid": { + "type": "string" + }, + "desc": { + "type": "string" + }, + "node": { + "type": "string" + }, + "hca": { + "type": "string" + }, + "rail": { + "type": "integer" + }, + "leaf": { + "type": "string" + } + } + }, + "topology.LinkView": { + "type": "object", + "description": "LinkView is a cable, with what it trained at and whether that is short of its kind.", + "properties": { + "from": { + "type": "string" + }, + "from_port": { + "type": "integer" + }, + "to": { + "type": "string" + }, + "to_port": { + "type": "integer" + }, + "rate": { + "type": "string" + }, + "gbps": { + "type": "integer" + }, + "host": { + "type": "boolean" + }, + "degraded": { + "type": "boolean" + } + } + }, + "topology.Rail": { + "type": "object", + "description": "Rail is the leaves one rail's adapters reach.", + "properties": { + "index": { + "type": "integer" + }, + "leaves": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "topology.SwitchView": { + "type": "object", + "description": "SwitchView is a switch and its place in the tiers.", + "properties": { + "guid": { + "type": "string" + }, + "name": { + "type": "string" + }, + "tier": { + "type": "integer", + "description": "1 leaf, 2 spine, 3 core" + }, + "ports": { + "type": "integer" + }, + "used": { + "type": "integer" + }, + "lid": { + "type": "integer" + }, + "hosts": { + "type": "integer", + "description": "Hosts counts adapters hanging off it." + } + } + }, + "topology.View": { + "type": "object", + "description": "View is a fabric's shape, ready to draw.", + "properties": { + "switches": { + "type": "array", + "items": { + "$ref": "#/components/schemas/topology.SwitchView" + } + }, + "hosts": { + "type": "array", + "items": { + "$ref": "#/components/schemas/topology.HostView" + } + }, + "links": { + "type": "array", + "items": { + "$ref": "#/components/schemas/topology.LinkView" + } + }, + "tiers": { + "type": "integer", + "description": "Tiers is how many switch levels: 1 for a single switch, 2 for leaf and spine, 3 with a core." + }, + "expected_host_gbps": { + "type": "integer", + "description": "Expected is the rate most links of each kind trained at; a link below it is degraded." + }, + "expected_switch_gbps": { + "type": "integer" + }, + "degraded": { + "type": "integer" + }, + "rails": { + "type": "array", + "items": { + "$ref": "#/components/schemas/topology.Rail" + }, + "description": "Rails is, per rail — an adapter's position on its node — the leaves it reaches, and Aligned whether each rail has its own." + }, + "rail_aligned": { + "type": "boolean" + }, + "notes": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } +} diff --git a/docs/clients.md b/docs/clients.md new file mode 100644 index 00000000..59e3dc51 --- /dev/null +++ b/docs/clients.md @@ -0,0 +1,548 @@ +# Using llmgw from code + +Written for a developer whose program talks to a model through llmgw. There +is no llmgw SDK, and there will not be one: the gateway speaks OpenAI's API +and Anthropic's Messages API, so the official SDKs for both work as they are. +Only two things change — the base URL and the key. Everything llmgw adds on +top is an HTTP header, which every one of those SDKs lets you set. + +The examples use `https://llm.example.com` for the gateway; use the address +your operator gave you, or the one on the gateway's own front page. Every +example reads the key from `LLMGW_API_KEY`. `` is a model this +gateway serves: `GET /v1/models` lists the ones your key may use, and sending +the placeholder unchanged is answered with that list rather than with an +error. + +## Getting a key + +Keys are made on the gateway's **Account** page after signing in, or issued +by an operator. A key is shown once and never again — only its hash is kept — +so put it in a password manager straight away. `GET /me` with the key says +what it may do and what it has spent. + +## The base URL and the key + +| SDK | Base URL | Key | +|---|---|---| +| OpenAI (any language) | `https://llm.example.com/v1` | `Authorization: Bearer …`, as the SDK sends it | +| Anthropic (any language) | `https://llm.example.com` — the SDK adds `/v1/messages` | `x-api-key: …`, as the SDK sends it | + +Both SDKs also read their usual environment variables, so a program that +already uses them needs no change at all: + +``` +export OPENAI_BASE_URL=https://llm.example.com/v1 +export OPENAI_API_KEY=$LLMGW_API_KEY + +export ANTHROPIC_BASE_URL=https://llm.example.com +export ANTHROPIC_API_KEY=$LLMGW_API_KEY +``` + +## A first request + +### curl + +``` +curl https://llm.example.com/v1/chat/completions \ + -H "Authorization: Bearer $LLMGW_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"model": "", + "messages": [{"role": "user", "content": "Say hello in Turkish."}]}' +``` + +### Python + +``` +pip install openai +``` + +```python +import os +from openai import OpenAI + +client = OpenAI(base_url="https://llm.example.com/v1", + api_key=os.environ["LLMGW_API_KEY"]) + +reply = client.chat.completions.create( + model="", + messages=[{"role": "user", "content": "Say hello in Turkish."}], +) +print(reply.choices[0].message.content) +``` + +### TypeScript + +``` +npm install openai +``` + +```typescript +import OpenAI from "openai"; + +const client = new OpenAI({ + baseURL: "https://llm.example.com/v1", + apiKey: process.env.LLMGW_API_KEY, +}); + +const reply = await client.chat.completions.create({ + model: "", + messages: [{ role: "user", content: "Say hello in Turkish." }], +}); +console.log(reply.choices[0].message.content); +``` + +### Go + +``` +go get github.com/openai/openai-go/v3 +``` + +```go +package main + +import ( + "context" + "fmt" + "log" + "os" + + "github.com/openai/openai-go/v3" + "github.com/openai/openai-go/v3/option" +) + +func main() { + client := openai.NewClient( + option.WithBaseURL("https://llm.example.com/v1/"), + option.WithAPIKey(os.Getenv("LLMGW_API_KEY")), + ) + reply, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{ + Model: "", + Messages: []openai.ChatCompletionMessageParamUnion{openai.UserMessage("Say hello in Turkish.")}, + }) + if err != nil { + log.Fatal(err) + } + fmt.Println(reply.Choices[0].Message.Content) +} +``` + +The import path carries the SDK's major version; use the one your module +already has. + +## Streaming + +Set `stream` and read the chunks. llmgw may send a last chunk that carries +only the token counts and no choices, so check for a choice before reading +one — the OpenAI API does the same when usage is asked for. + +```python +stream = client.chat.completions.create( + model="", + messages=[{"role": "user", "content": "Count to ten."}], + stream=True, +) +for chunk in stream: + if chunk.choices and chunk.choices[0].delta.content: + print(chunk.choices[0].delta.content, end="", flush=True) +print() +``` + +```typescript +const stream = await client.chat.completions.create({ + model: "", + messages: [{ role: "user", content: "Count to ten." }], + stream: true, +}); +for await (const chunk of stream) { + process.stdout.write(chunk.choices[0]?.delta?.content ?? ""); +} +``` + +```go +stream := client.Chat.Completions.NewStreaming(ctx, openai.ChatCompletionNewParams{ + Model: "", + Messages: []openai.ChatCompletionMessageParamUnion{openai.UserMessage("Count to ten.")}, +}) +for stream.Next() { + chunk := stream.Current() + if len(chunk.Choices) > 0 { + fmt.Print(chunk.Choices[0].Delta.Content) + } +} +if err := stream.Err(); err != nil { + log.Fatal(err) +} +``` + +With curl, add `"stream": true` to the body and `-N` so curl prints the +events as they come. + +## Tools + +Function calling is OpenAI's: describe the tools, run the ones the model +asks for, send the results back. Whether a model calls tools well is the +model's business, not the gateway's; ask your operator which of the served +models are set up for it. + +```python +import json + +tools = [{ + "type": "function", + "function": { + "name": "get_weather", + "description": "The current weather in a city.", + "parameters": { + "type": "object", + "properties": {"city": {"type": "string"}}, + "required": ["city"], + }, + }, +}] + +messages = [{"role": "user", "content": "Is it raining in Ankara?"}] +reply = client.chat.completions.create(model="", messages=messages, tools=tools) +msg = reply.choices[0].message + +if msg.tool_calls: + messages.append(msg) + for call in msg.tool_calls: + args = json.loads(call.function.arguments) + result = {"city": args["city"], "raining": False} # your code here + messages.append({"role": "tool", "tool_call_id": call.id, + "content": json.dumps(result)}) + reply = client.chat.completions.create(model="", messages=messages, tools=tools) + +print(reply.choices[0].message.content) +``` + +## Embeddings + +```python +result = client.embeddings.create( + model="", + input=["llmgw routes requests", "to GPUs it can reach"], +) +vectors = [d.embedding for d in result.data] +``` + +```typescript +const result = await client.embeddings.create({ + model: "", + input: ["llmgw routes requests", "to GPUs it can reach"], +}); +const vectors = result.data.map((d) => d.embedding); +``` + +An embedding model is a model of its own; a chat model does not answer +`/v1/embeddings`. + +## The Responses API + +`/v1/responses` is served too, for clients that speak nothing else (Codex +among them). llmgw translates it to chat completions, so it works with every +model the gateway serves; what has no equivalent there — OpenAI's hosted +tools, reasoning summaries — is ignored rather than refused. + +```python +response = client.responses.create( + model="", + instructions="Answer in one sentence.", + input="Why is the sky blue?", +) +print(response.output_text) +``` + +Streamed, the events are the Responses API's own: + +```python +stream = client.responses.create(model="", input="Count to ten.", stream=True) +for event in stream: + if event.type == "response.output_text.delta": + print(event.delta, end="", flush=True) +``` + +## Batches + +For work that need not finish now: OpenAI's Files and Batch APIs. A batch runs +at the lowest priority, so it uses what interactive traffic leaves free, and +each line is counted against the key that submitted it. + +```python +import json + +with open("requests.jsonl", "w") as f: + for i, text in enumerate(["first document", "second document"]): + f.write(json.dumps({ + "custom_id": f"doc-{i}", + "method": "POST", + "url": "/v1/chat/completions", + "body": {"model": "", + "messages": [{"role": "user", "content": "Summarise: " + text}]}, + }) + "\n") + +batch_file = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch") +batch = client.batches.create( + input_file_id=batch_file.id, + endpoint="/v1/chat/completions", + completion_window="24h", +) + +# Later: +batch = client.batches.retrieve(batch.id) +if batch.status == "completed": + for line in client.files.content(batch.output_file_id).text.splitlines(): + result = json.loads(line) + print(result["custom_id"], result["response"]["body"]["choices"][0]["message"]["content"]) +``` + +## The Anthropic SDK + +`/v1/messages` is Anthropic's Messages API, translated to chat completions and +back, streamed or not, with tools and images. It serves the gateway's own +models — `model` is a model this gateway serves, not a Claude model. + +``` +pip install anthropic +``` + +```python +import os +import anthropic + +client = anthropic.Anthropic(base_url="https://llm.example.com", + api_key=os.environ["LLMGW_API_KEY"]) + +message = client.messages.create( + model="", + max_tokens=1024, + messages=[{"role": "user", "content": "Say hello in Turkish."}], +) +print(message.content[0].text) + +with client.messages.stream( + model="", + max_tokens=1024, + messages=[{"role": "user", "content": "Count to ten."}], +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) +``` + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic({ + baseURL: "https://llm.example.com", + apiKey: process.env.LLMGW_API_KEY, +}); + +const message = await client.messages.create({ + model: "", + max_tokens: 1024, + messages: [{ role: "user", content: "Say hello in Turkish." }], +}); +for (const block of message.content) { + if (block.type === "text") console.log(block.text); +} +``` + +```go +client := anthropic.NewClient( + option.WithBaseURL("https://llm.example.com/"), + option.WithAPIKey(os.Getenv("LLMGW_API_KEY")), +) +message, err := client.Messages.New(ctx, anthropic.MessageNewParams{ + Model: "", + MaxTokens: 1024, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("Say hello in Turkish.")), + }, +}) +if err != nil { + log.Fatal(err) +} +for _, block := range message.Content { + if text, ok := block.AsAny().(anthropic.TextBlock); ok { + fmt.Println(text.Text) + } +} +``` + +(`github.com/anthropics/anthropic-sdk-go` and its `option` package.) + +With curl: + +``` +curl https://llm.example.com/v1/messages \ + -H "x-api-key: $LLMGW_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "Content-Type: application/json" \ + -d '{"model": "", "max_tokens": 1024, + "messages": [{"role": "user", "content": "Say hello in Turkish."}]}' +``` + +## What llmgw adds + +Each is a header, so a request stays exactly what the SDK would send anywhere +else. Set one for every request on the client, or for one request: + +| | Every request | One request | +|---|---|---| +| Python (both SDKs) | `OpenAI(..., default_headers={...})` | `create(..., extra_headers={...})` | +| TypeScript (both SDKs) | `new OpenAI({ ..., defaultHeaders: {...} })` | `create({...}, { headers: {...} })` | +| Go (both SDKs) | `openai.NewClient(..., option.WithHeader(k, v))` | `New(ctx, params, option.WithHeader(k, v))` | +| curl | | `-H "k: v"` | + +### Stored conversations: `x-llmgw-thread` + +Send the same thread id with each request and only the new turn; llmgw puts +the stored conversation in front of it. The conversation continues on +whichever model serves the next turn, even a different one. It must be +turned on for your project by an operator (`llmgw keys threads`); a request +that names a thread on a gateway that keeps none is refused rather than +answered without its history. + +```python +import uuid + +thread = str(uuid.uuid4()) # anyone in your project who knows it reads it +for turn in ["My name is Deniz.", "What is my name?"]: + reply = client.chat.completions.create( + model="", + messages=[{"role": "user", "content": turn}], + extra_headers={"x-llmgw-thread": thread}, + ) + print(reply.choices[0].message.content) +``` + +A thread belongs to the project, not to the key, so use an id nobody can +guess: at most 128 letters, digits and `- _ . :`. When the conversation no +longer fits the model, the oldest turns are left out and the reply carries +`x-llmgw-thread-trimmed` with how many. `DELETE /v1/threads/{id}` forgets one: + +``` +curl -X DELETE https://llm.example.com/v1/threads/$THREAD \ + -H "Authorization: Bearer $LLMGW_API_KEY" +``` + +### Sessions: `x-session-id` + +Requests with the same session id go to the same replica while it is +healthy, so a conversation that resends its history finds it already in that +replica's cache and answers sooner. Without the header, the body's `user` +field is used. Nothing is stored; it is only a routing hint. + +```python +client = OpenAI(base_url="https://llm.example.com/v1", api_key=os.environ["LLMGW_API_KEY"], + default_headers={"x-session-id": "chat-7f3a"}) +``` + +### Tags and metadata + +Requests can be labelled so the usage they record can be told apart — by +feature, by customer, by job. Send OpenAI's own `metadata`, string keys to +string values, or the same as the `x-llmgw-tags` header for a client that +cannot set `metadata`; the `user` field is recorded too. Which tags also +become metric labels is the operator's choice (`router.tag_labels`). + +```python +reply = client.chat.completions.create( + model="", + messages=[{"role": "user", "content": "Classify this ticket."}], + metadata={"feature": "triage", "customer": "acme"}, + user="user-1234", +) +``` + +``` +curl https://llm.example.com/v1/chat/completions \ + -H "Authorization: Bearer $LLMGW_API_KEY" \ + -H "x-llmgw-tags: feature=triage,customer=acme" \ + -H "Content-Type: application/json" \ + -d '{"model": "", "messages": [{"role": "user", "content": "Classify this ticket."}]}' +``` + +### Canaries: `x-llmgw-variant` + +While an operator tries a model's newer weights on a share of its traffic, a +session stays on one side. `x-llmgw-variant: canary` sends a request to the +canary deliberately — to try it before it is promoted, or to compare the two. + +```python +reply = client.chat.completions.create( + model="", + messages=[{"role": "user", "content": "hello"}], + extra_headers={"x-llmgw-variant": "canary"}, +) +``` + +### Memory notes: `/v1/memory` + +Notes an agent keeps for itself across conversations: a key, some text, and +optional tags, private to your project and to the agent named in +`x-llmgw-agent` (`default` when it is not sent). An operator turns them on for +a project (`llmgw keys memory`). They are plain REST, so any HTTP client +will do: + +``` +H="Authorization: Bearer $LLMGW_API_KEY" + +curl -X PUT https://llm.example.com/v1/memory/favourite-colour -H "$H" \ + -H "x-llmgw-agent: helper" -H "Content-Type: application/json" \ + -d '{"text": "The user likes dark green.", "tags": ["preference"]}' + +curl "https://llm.example.com/v1/memory?q=green" -H "$H" -H "x-llmgw-agent: helper" +curl "https://llm.example.com/v1/memory?tag=preference" -H "$H" -H "x-llmgw-agent: helper" +curl https://llm.example.com/v1/memory/favourite-colour -H "$H" -H "x-llmgw-agent: helper" +curl -X DELETE https://llm.example.com/v1/memory/favourite-colour -H "$H" -H "x-llmgw-agent: helper" +``` + +A key is up to 200 bytes, a note up to 16 KiB, with at most 16 tags of +lowercase letters, digits, `-` and `_`, and 1000 notes per agent. + +### MCP: `/mcp` + +The same notes as tools an agent can be given — `remember`, `recall` and +`forget` — from an MCP server at `https://llm.example.com/mcp` (the HTTP +transport, answered as plain JSON). Add it to your agent's MCP servers with +the key as a bearer token and, if you want notes kept apart, `x-llmgw-agent`. +llmgw does not put these tools into requests by itself: an agent that is not +given the server never sees its notes. + +``` +curl https://llm.example.com/mcp \ + -H "Authorization: Bearer $LLMGW_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' +``` + +### Headers llmgw sends back + +| Header | Says | +|---|---| +| `x-request-id` | The request's id in the gateway's logs and usage records — quote it when asking an operator about a request. | +| `x-llmgw-served-model` | The model that answered, when it was not the one asked for: a spent budget can move a request to a cheaper model. | +| `x-llmgw-queue-ms` | How long the request waited for room before it was sent. | +| `x-llmgw-thread-trimmed` | How many stored turns were left out to fit the model. | + +## When something is refused + +Errors come back in the shape of the API that was called — OpenAI's +`{"error": {"message": …, "type": …}}` or Anthropic's — so each SDK raises +its usual exception with the gateway's message in it. The ones worth knowing: + +| Status | Usually means | +|---|---| +| 400 | Besides a malformed request: a prompt too long for the model, or a guardrail policy refused it (the code `content_policy_violation`). | +| 401 | No key, a mistyped one, or one that was revoked or has expired. | +| 403 | The key may not use that model. | +| 429 | A rate limit or budget of the key, its project or its team was reached. `Retry-After` says when to try again, and is absent when waiting will not help — a spent monthly budget. | +| 503 | No model of that name is served (the message lists the ones that are), the model is still loading, or every replica is busy and the request waited as long as it may. The SDKs retry by themselves; a name that is not served will not start to be. | + +## Priority + +With keys on, the key decides the request's priority band and routing +profile, set by an operator; the `x-llmgw-band` and `x-llmgw-profile` headers +are ignored, so a client cannot promote itself. On a gateway without keys +they are read from the request. diff --git a/docs/console.md b/docs/console.md index 8a8b0476..a5a86889 100644 --- a/docs/console.md +++ b/docs/console.md @@ -52,6 +52,18 @@ cluster, a backup and adding a node change this machine or another over ssh; those close the screen and run in the terminal, so their output is there to read, and Enter brings the console back. +## Setting up + +On a machine with nothing installed, the control plane is set up from one +form (`sudo llmgw server init`): the administrator's email, other names nodes +reach the machine by, and ticks for PostgreSQL, the model mirror, this machine +as a node, the starter model and the guardrails' judge. **Offline bundle** +and **Its sha256** are for a site with no internet: the path of a bundle made +by `llmgw bundle create`, and the sha256 it printed. Given, the bundle goes +into the mirror, every file checked, and the cluster is set up to fetch +nothing from outside (install.md, "Offline sites"). A bundle with no sha256, +or with the mirror unticked, is said in the form and nothing starts. + ## Watch **Overview** is `llmgw ctl status`: nodes, GPUs by class, fabrics, replicas, @@ -71,11 +83,18 @@ installs. **N** sends a test notification to each webhook in server.yaml's `notify` section and says how each answered (`llmgw ctl notify test`). A node's and a model's own pages have their charts too, over the same range. -**Nodes** lists every node with its state, load, GPUs, replicas, disk and -agent version. On a row: +**Nodes** lists every node with its state, where it is (its rack, or row, +room or site, and PDUs), load, GPUs, replicas, disk and agent version. A node +in a held rack reads *ready, held*. On a row: -- **Details** — its address, system, load, engines and GPUs, and any warning. +- **Details** — its address, location and any hold, system, load, engines and + GPUs, and any warning. - **Cordon** places nothing new on it; **Uncordon** undoes it. +- **Location…** sets its site, room, row, rack and PDUs (the `llmgw.io/` + labels), which placement spreads replicas across. +- **Hold rack …** places nothing new in the node's rack, and can drain it; + **Release …** on a node in a held domain undoes it. See + [facility-aware-placement.md](facility-aware-placement.md). - **Drain** moves its replicas off one at a time, each replacement up before the original stops. - **vllm build / sglang build** (nodes with GPUs) — which build of the engine @@ -110,6 +129,23 @@ and **UPDATE** when the registry has new weights for it. On a row: **Go back to …** returns to the weights the update replaced. **Ask the registry for new weights now** checks without waiting for the next scheduled look (`mirror.update_check`, six hours by default). +- **Try the new weights as a canary…** — instead of swapping them in, runs + them beside the model as `MODEL-canary`, one replica, given the share of + its requests you choose. With a canary running the menu has **Canary's + share…**, **Promote the canary…** (the model moves to its weights, the + canary is removed) and **Take the canary out…**. A canary that errs or + answers more slowly than the model is taken out by itself. The MODEL + column shows `(10% to canary)` and `(canary of …)`. +- **Ask it a quality suite…** — one of the suites the control plane has (in + `control.eval_dir`, or built in: `arithmetic`, `json-format`), asked + through the router; the dialog counts the answers as they come in, then + shows the score, each case and the model's last runs. Esc stops watching; + the run carries on and is kept. **Its quality runs** lists them, as + `llmgw ctl eval --history` does. +- **Hold its updates to a quality suite…** — the suite and score its new + weights must reach before an update or a promotion moves it to them + (`llmgw ctl model gate`); **none** takes it away. With one set, **Update + to …** and **Promote the canary…** say so. - **Why is it placed where it is** — `llmgw ctl explain-placement`. - **Try again**, for a model parked after failing every start. - **Remove** — its replicas stop and it leaves the catalog. A model from @@ -131,7 +167,10 @@ team or project is guaranteed and may at most hold, and what it holds now. **Mirror** is what the model mirror holds, one row for each version of each model — a file, or the set of files a model of several is: shards, a vision projector, a config and tokenizer — with how far its download has got and -which models use it. **A** downloads a URL into it; on a row, its files with +which models use it. **A** downloads a URL into it; **I** imports a model +from an Ollama on this machine into a mirror directory on this machine — the +mirror beside the control plane — and shows the model definition to add for +it (a mirror elsewhere: `llmgw mirror import-ollama` there); on a row, its files with their checksums and where each was fetched from, the source a model definition names for it, or remove it — with a warning when a model still uses it. @@ -155,7 +194,8 @@ and change it with the same commands as `llmgw users`, `llmgw keys` and dashboard, and what they belong to. **A** creates an account, already approved. On a row: approve one waiting, suspend or reinstate, give or take the cluster dashboard, add to or take out of an organization, team or -project, their limits, a new password (their sessions close), delete. +project, their limits, a new password (their sessions close), delete, and +**Forget them…** for a request to be forgotten (`llmgw users forget`). **API keys** — every key, its project, owner, state and last use. **A** issues one; the key is shown once, in the result, and never again. On a row: @@ -185,7 +225,11 @@ with anything secret taken out. `llmgw ctl audit` is the same, with filters. projects, with members, keys and limits. **A** adds an organization. On a row: add a team or project inside it, rename, move, limits for the level and for each of its members, its capacity quota, and for a project how long -conversations and agent notes are kept. **Longest key lifetime…** caps how +conversations and agent notes are kept, and whether its requests are +(**Keep requests…**: for how long, and what share), and whether they stay in +the cluster (**Requests stay in the cluster…**: never an outside provider), +and whether the same request is answered again from memory (**Cache +answers…**: for how long, and whether only reproducible answers or any). **Longest key lifetime…** caps how long a key made there may live, and is the expiry of one made without any (`llmgw keys ttl`; `auth.max_key_ttl` in server.yaml caps every key). **Remove** takes away only something empty. diff --git a/docs/data.md b/docs/data.md index 77ed63a4..bd40ca14 100644 --- a/docs/data.md +++ b/docs/data.md @@ -32,13 +32,22 @@ the text, the value that matched, or the placeholder map of a redaction. See **Usage records**, one per request: the key, the project, the model asked for, the model that answered, prompt and completion token counts, cost, HTTP status and latency. No message content. The row is in `internal/store/store.go` as -`Usage` and there is no field for text in it. +`Usage` and there is no field for text in it. What the client chose to say +about the request is kept with it: OpenAI's `user` field and its `metadata` +or `x-llmgw-tags` — short strings, set by the client, for attributing spend. +A client that puts a person's name or address there puts it in the usage +records; the field is the client's, and so is that choice. Tags are not sent +on to the engine. **API keys**, as SHA-256 hashes. The key itself is shown once, at creation, and never stored — so a leaked database hands over no working credential, and neither llmgw nor an administrator can recover a key somebody lost. A prefix is kept so a key can be identified in a listing without revealing it. +**The store's own secrets**, like the one engine keys are derived from, plain +unless `secrets.master_key` seals them — with Vault's transit engine, so that +neither the store nor its backups hold them. + **People and tenancy**: accounts, the organisation/team/project tree, and the limits attached to it. Passwords are hashed. @@ -46,10 +55,32 @@ limits attached to it. Passwords are hashed. **Conversations and agent notes** — only for a project that asked. See below. +**Kept requests** — only for a project that asked (`llmgw keys requests`): +what each request sent the model, after the guardrails' redaction and with +any stored conversation in it, and the answer the client got, for the hours +it said, all of them or a share. Never under a `no_store` policy. + +**Batch files** — when a client uses the Batch API: the file of requests it +uploaded (prompts) and the files the batch wrote (answers), in the store, +until deleted (`DELETE /v1/files/{id}`) or, for what a batch wrote, until +`router.batch.retain_days` (30) pass. Only keys of the project that made +them can read them, and a project under a `no_store` policy cannot make +them. + +**Reused answers** — only for a project that asked (`llmgw keys cache`): +each answer that may be reused, as the client got it, and a hash of the +request it answers, in the gateway process's memory — never in the store, +never on disk — for the project's TTL or until pushed out by newer ones +(`router.cache.max_bytes`), and gone with a restart. Never under a `no_store` +policy. Forgetting a person does not reach into it; the answers age out by +the TTL. The store keeps only the setting, and a usage record's mark that it +was answered from the cache. + ## What is not stored Prompts. Completions. Anything the model was shown or produced, unless the -project turned on conversations or notes. +project turned on conversations, notes or kept requests, or sent a batch. +(Reused answers are held in memory only, as above.) The chat page in llmgw's own web interface keeps the conversation in a JavaScript variable in the browser. Refresh it and the conversation is gone, @@ -95,22 +126,62 @@ your own hardware, and the answer comes back. The router talks to engines, the engines talk to nothing, the agents talk to the control plane. All of it is inside the cluster. -Two things can reach outside, both started by an operator rather than by a -request: +Around the serving path, a cluster set up the ordinary way does reach out. +None of it carries a prompt, an answer, a key or a user — it is software and +public model files coming in — but a review should know each one: -**Fetching weights.** When a model's `source` is a URL, the agent downloads it. -Point that at an internal mirror and nothing leaves at all — which is also the +**Installing engines.** Each node's agent downloads the llama.cpp build for its +hardware from GitHub, checked against the checksum GitHub publishes, and vLLM +(SGLang when asked) from PyPI, with `uv` from GitHub. On every node, when it +joins and when the engine version changes. + +**Releases.** `llmgw node add`, `llmgw ctl upgrade` and `llmgw upgrade` fetch +llmgw's own release binaries from the project's release server, checked against +its signed checksums. + +**Fetching weights.** When a model's `source` is a URL, the agent downloads it; +the mirror fetches what it is asked to, from Hugging Face or another URL, and +`server init` has it fetch the starter model and the guardrails' judge. Point +sources at the mirror and the nodes fetch only from it — which is also the faster arrangement, because eight nodes pulling forty gigabytes from the internet is a day's work and from a local mirror it is minutes. A `source` that is a path on disk is never fetched. -**`llmgw ctl plan`.** Reads a model's architecture from huggingface.co to work -out whether it fits your hardware. An operator command run at planning time, -not part of serving, and not run by anything automatically. +**The registry.** With a mirror configured, the control plane asks Hugging Face +every six hours whether the models served from it have newer files +(`mirror.update_check`), and `/admin/mirror` searches it. `llmgw ctl plan` +reads a model's architecture from huggingface.co to work out whether it fits +your hardware. -There is no telemetry, no licence check, and no call home. The binary is -static, built with `CGO_ENABLED=0`, and runs in a network with no route to the -internet as long as the weights are already on disk. +There is no telemetry, no licence check, and no call home. + +### A cluster with no way out + +A site with no route to the internet installs from an **offline bundle** +instead, and then nothing at all leaves the cluster (docs/install.md, "Offline +sites"). The bundle is made on a machine that has internet — llmgw's release +binaries with their signed checksums, the llama.cpp builds with the checksums +GitHub publishes, the model files with the checksums Hugging Face publishes, +each checked as it is downloaded — carried in, and imported into the mirror. +With `offline.mirror` set in `server.yaml`, nodes install engines from the +mirror and never from GitHub, releases come from the mirror, and the registry +is not asked about newer weights. + +Verification is not weakened by any of this. A release is held to the project's +signing key wherever it is fetched from. An engine file is held to the checksum +recorded when the bundle was made, which the control plane keeps and hands each +node over the agent's authenticated connection: the mirror serves plain HTTP, +and nothing a node runs is taken on the mirror's word. The bundle itself is +checked against the sha256 its maker printed, carried to the site apart from +the bundle. + +What does not come in a bundle: vLLM and SGLang, which are Python environments +from PyPI — an offline node serves with llama.cpp unless one is installed on it +by hand — and the operating system's own packages (the OpenMP runtime the +engine needs, PostgreSQL when chosen), which come from the machines' package +sources: at an offline site, the distribution mirror it already has. Searching +the registry from `/admin/mirror` and `llmgw ctl plan` need the internet and +do not work offline; `mirror.registry` can point the first at an internal copy. ## What the software cannot do for you @@ -140,3 +211,29 @@ touch, whatever the catalog says. | Scope is part of the lookup | `internal/store/threads.go`, `Thread` | | Deletion is a client endpoint | `internal/router/threads.go`, `handleDeleteThread` | | Weight fetching is the only serving-path egress | `internal/agent/weights/fetch.go` | + +## Forgetting a person + +`llmgw users forget --yes` (or **Forget them…** in the console) is for +a request to be forgotten: + +- their usage — every request record and every sum — is kept, so totals and + budgets stay true, but under a random pseudonym that links to nothing; +- their kept requests (`keys requests`), personal files and batches, and + their own limits are deleted; +- their email and id are taken out of the audit log, which keeps what was + done; +- then the account goes, as `users delete` removes it: sessions ended, keys + revoked and left without an owner. + +Conversations and agent notes belong to projects, not to the people in them, +and are not touched: a project forgets them by its retention, and a thread by +`DELETE /v1/threads/{id}`. Backups taken before still hold everything until +they age out; that is what their retention is for. + +## Keeping a project's requests in the cluster + +`llmgw keys residency --project --in-cluster` refuses the project's +keys any model served by an outside provider, and never uses one for them as +a fallback or a canary: their prompts do not leave the machines the cluster +runs on. `--anywhere` lifts it. diff --git a/docs/facility-aware-placement.md b/docs/facility-aware-placement.md index a57efab1..e2b01129 100644 --- a/docs/facility-aware-placement.md +++ b/docs/facility-aware-placement.md @@ -1,13 +1,109 @@ # Facility-aware placement: rack power, temperature and cooling -**Status: step 0, reading the nodes' own sensors, is built; steps 1–5 are -deferred** until the rack, PDU and power information of a real site is at -hand — without it they would be designed against guesses. -This is the design for step 5 of resource allocation, after reserved CPU cores -and memory (1), capacity classes and preemption (2), tenant capacity quotas (3) -and sizing by measured throughput (4), all of which shipped in v0.10.5. Of -what follows, only the node sensors (rollout step 0) exist in the code: they -are read, published and shown, and change no decision. +**Status: steps 0, 1 and 2 are built, with the manual hold of step 4; +temperature conditions (steps 3 and 4) and shedding (step 5) are not**, +until the thermal data of a real site is at hand — without it thresholds would +be designed against guesses. This is the design for step 5 of resource +allocation, after reserved CPU cores and memory (1), capacity classes and +preemption (2), tenant capacity quotas (3) and sizing by measured throughput +(4). [What is built](#what-is-built) says what works today and where it +departs from the design below; the rest of the document is the design. + +## What is built + +**Where a node is.** Five labels: `llmgw.io/site`, `room`, `row`, `rack` and +`pdu` (a comma separated list, for a dual-fed rack). They come from the node's +`agent.yaml` under `labels:`, or from the control plane: + +``` +llmgw ctl label gpu01 llmgw.io/rack=r12-07 llmgw.io/pdu=r12-07-a,r12-07-b +llmgw ctl label gpu01 llmgw.io/rack- # back to agent.yaml's value, if any +``` + +Labels set with `ctl label` are kept in the store, win over the agent's, and +may be set before the node joins. A misspelt `llmgw.io/` key is refused. A +domain is named `level:name` — `rack:r12-07`, `pdu:r12-07-a` — and names are +taken as given, so two rooms that both have a rack `r1` must label them apart. +A node without location labels is in no domain and places as it always did. + +**Spreading.** A model's next replica goes first to a node sharing no rack and +no PDU with the nodes the model already runs on; nodes sharing fewer come +before nodes sharing more. It is an ordering, never a filter: a rack holding +the only free cards still takes the replica. It ranks above preferring a node +that already holds the weights — a second replica one breaker away from the +first is worth less than the copy saved — and above bin packing. + +**Keeping a replica together.** A profile's `keep_within: rack` (or `row`, +`room`, `site`) keeps a multi-node replica's nodes in one such domain, inside +the fabric or NVLink domain placement already requires; nodes without the +label are passed over for it, with the reason. + +**Holds.** `llmgw ctl facility hold rack:r12-07 --reason "PDU swap"` places +nothing new in the domain, as a cordon of each of its nodes would, including +nodes labelled into it later. `--drain` also drains its nodes, one replica at +a time with the replacement up first; `llmgw ctl facility release` undoes +both. Holds are kept in the store across restarts (the drain itself is node +state, which is not: after a restart the hold still keeps work out, and +replicas not yet moved stay where they are). Any domain can be held: a PDU +holds every rack on it. + +**Power budgets.** In `server.yaml`: + +```yaml +facility: + margin: 0.1 # share of every cap kept free + gpu_watts: 700 # a card that reports no power limit + cpu_core_watts: 10 # a core reserved by a CPU replica (cpu_cores) + node_watts: 350 # each node's own draw beyond its cards + budgets: + - domain: rack:r12-07 + cap_watts: 16000 # what one feed carries alone, derated + other_watts: 800 # switches, storage + - domain: pdu:r12-07-a + cap_watts: 7400 +``` + +A replica's draw is the profile's `power_watts` (split over its nodes) when +declared; otherwise each card at the power limit it reports through the agent's +sensors (or `gpu_watts`), and each reserved core at `cpu_core_watts`. A +domain's use is, node by node, `node_watts` plus the larger of what is placed +there and what the node's sensors read in the last two minutes +(`measured_fresh`), plus the domain's `other_watts`. A shard that would take +any of its node's domains past `cap × (1 − margin)` is refused; a multi-node +replica's shards are counted together, so two that each fit a rack alone do not +both go into it. A draw nobody knows — no declared figure, no card limit, no +`gpu_watts` — counts as nothing: missing data never blocks. + +**What people see.** `llmgw ctl explain-placement` names the domain: *rack +r12-07 is held: PDU swap*, *rack r12-07: 14.2 kW of a 14.4 kW limit (16.0 kW +cap less 10%) in use, the shard needs ~2.8 kW*. The rejections of a placed +replica are kept too, so a replica in an unexpected rack says why. `llmgw ctl +nodes` has a LOCATION column, shows *ready, held*, and filters with `--domain +rack:r12-07`. `llmgw ctl facility` lists every domain with its nodes, use, +limit, reserved and measured draw, and holds. The console's Nodes view has a +WHERE column; a node's page shows its location and hold, and its menu sets +the location (**Location…**) and holds or releases its rack. The admin API: +`GET /api/v1/facility`, `POST /api/v1/facility/holds`, `DELETE +/api/v1/facility/holds/{domain}`, `POST /api/v1/nodes/{id}/labels`. + +**Where it departs from the design below, and why.** + +- Domains come from labels alone; there is no facility file declaring them. + Budgets are in `server.yaml`, the one file the control plane already reads. + A DCIM export would generate that block. +- Feeds are not modelled. The cap given is what one feed carries alone, + derated — the figure the design says matters — so the operator gives the + one number instead of llmgw deriving it from two. +- The manual hold of step 4 is built now, without conditions: it needs no + sensor data and answers the commonest facility event, planned maintenance. + Its command is `ctl facility hold`, with a `--drain` the design did not have. +- `keep_within` is new: the request that a multi-node replica stay in one rack + where the cabling requires it. +- Spreading is an ordering of candidates, not the scoring of the design; power + headroom does not yet order racks ("level load across racks"), and + multi-node replicas are not spread across racks. +- No `llmgw_domain_*` metrics or alerts yet; `ctl facility` and the API carry + the same figures. ## Why @@ -260,16 +356,17 @@ Each step ships on its own and is useful without the next: 0. **Node sensors, observe-only (built).** GPU heat, power and throttling, CPU heat and power, inlet air where the board has a sensor; published and shown, no decision changed. -1. **Location and spreading.** Well-known labels, domains from labels, replicas +1. **Location and spreading (built).** Well-known labels, domains from labels, replicas spread across racks and PDUs, locations on the node views. No facility data needed. -2. **Power budgets from a static file.** Caps and margins, estimated draw per +2. **Power budgets from a static file (built, without headroom + scoring).** Caps and margins, estimated draw per replica (declared or derived), hard limit in placement and headroom. 3. **Readings, observe-only.** The Prometheus source beside the agents', conditions with hysteresis (throttling first among them), measured power folded into headroom; decisions shown, not enforced. -4. **Thermal enforcement.** `warm` scored down, `hot` refused, manual hold and - release. +4. **Thermal enforcement.** `warm` scored down, `hot` refused; the manual hold + and release are built. 5. **Shedding and tokens per watt.** Opt-in shedding through step 2's preemption; measured power in profile preference. diff --git a/docs/install.md b/docs/install.md index 9059a9ba..668ec5ba 100644 --- a/docs/install.md +++ b/docs/install.md @@ -252,7 +252,8 @@ knowing before you edit it: `LLMGW_ADMIN_TOKEN` gives it from elsewhere. pprof, whose heap holds the API keys requests presented, is off unless `debug_pprof: true`, and then behind the token too. To see the dashboard from elsewhere use `/admin` on the - client port — do not move this listener. + client port — do not move this listener. The API itself is described in + [admin-api.md](admin-api.md). - `default_rpm`, `default_tpm` and `default_price` are what make limits and budgets mean anything. Without a price every request costs zero and a budget never binds; without the defaults, a project created without limits is @@ -383,6 +384,46 @@ llmgw mirror fetch --model qwen2.5-14b-instruct --version 2026-03 \ or from the admin page, or by copying files into the directory by hand — the mirror is a directory, and anything that puts files in it works. +Files already on the mirror machine go in with `import`, which copies them the +way a download is kept — under a temporary name until whole, the checksum +beside them for nodes to check against, a version never replaced — and checks +that a `.gguf` is one: + +``` +llmgw mirror import ./qwen2.5-7b-instruct-q4_k_m.gguf --model qwen2.5-7b-instruct \ + --version 2026-10 --sha256 +``` + +#### From Ollama + +Models you already run in Ollama are GGUFs llama.cpp serves as they are. +On the mirror machine, with Ollama's models readable there: + +``` +llmgw mirror import-ollama # lists what Ollama has +llmgw mirror import-ollama llama3.2:3b +``` + +It finds Ollama's models directory where Ollama keeps it — `OLLAMA_MODELS`, +`~/.ollama/models`, or `/usr/share/ollama/.ollama/models` for Ollama's Linux +service, which needs `sudo` to read — or takes `--ollama-dir`. It copies the +model's GGUF, and a vision model's projector beside it, each checked against +the sha256 Ollama named its file by; a file that does not match is not +mirrored, and nothing of the model is. The version is the tag and the start of +the digest (`llama3.2/3b-a80c4f17acd5/llama3.2-3b.gguf`), because a tag like +`latest` moves in Ollama and a mirror version must not; `--model` and +`--version` choose otherwise. It ends with a model definition to save and +`llmgw ctl model add -f`, with `--ctx-size` set to the `num_ctx` Ollama ran it +with. + +Ollama's prompt template is not carried: llama.cpp renders the chat template +inside the GGUF, which for any recent model is the one it was trained on. Its +system prompt and adapters are not carried either, and the import says so. +Models Ollama keeps as separate tensors rather than one GGUF, or as several +weight layers, are refused with a sentence saying so — mirror that model's GGUF +from its publisher instead. When the mirror runs beside the control plane, the +console's Mirror view does the same with **I**. + ## 4. Preparing a node **Do this before onboarding.** A node missing its driver or engine registers @@ -428,6 +469,71 @@ sudo llmgw doctor A `-nvml` build is still published beside the portable one; it reads NVLink from NVML directly, and needs a libc no older than the builder's. +### MIG, if you want to cut a card into pieces + +An A100, A30, H100, H200 or later card can be split into MIG (Multi-Instance +GPU) instances, each with its own memory, its own share of the card's compute +and its own UUID. llmgw places a model on an instance as it would on a card, +which makes MIG the way to run several small models on one large card without +them competing for it. + +**llmgw does not create the instances.** How a card is cut is your decision, +made once with `nvidia-smi` on the node; the agent reads what is there when +it starts: + +``` +sudo nvidia-smi -i 0 -mig 1 # MIG mode on card 0; may need a reset +sudo nvidia-smi mig -i 0 -lgip # the profiles this card offers +sudo nvidia-smi mig -i 0 -cgi 3g.40gb,3g.40gb -C # two instances, each with its compute instance +nvidia-smi -L # the instances, with their MIG- UUIDs +sudo systemctl restart llmgw-agent # so it registers the new devices +``` + +`-C` matters: a GPU instance with no compute instance inside it is not a +device yet. Turning MIG on takes effect at the card's next reset +(`nvidia-smi -i 0 -r` with nothing running on it, or a reboot), and instances +do not survive a reboot unless something recreates them — NVIDIA's +`mig-parted` or a systemd unit of your own. + +**Classes.** A card in MIG mode is reported as its instances instead of as +the whole card, and each instance's class is the card's class and the +profile: two `3g.40gb` instances of an A100 80GB are two devices of class +`a100-80g-mig-3g.40gb`, an H100's `1g.10gb+me` is `h100-80g-mig-1g.10gb-me`. +`llmgw ctl nodes` lists the classes, and a profile names one like any other: + +```yaml +profiles: + - name: mig + engine: vllm + gpu_class: a100-80g-mig-3g.40gb +``` + +**One instance a replica.** A process can open only one MIG device, and +instances have no NVLink or peer-to-peer access between them, so a replica on +MIG runs on exactly one instance: `tp: 1`, one GPU, one node. A profile on a +MIG class asking for more is refused when the model is added, with that +reason. A model too large for one instance wants a larger profile or a whole +card. `llmgw ctl model plan` and `ctl model serve` plan the same way: an +instance is offered for a model it holds, and never several together. + +**How they are numbered and shown.** Placement numbers card 0's instance 2 as +device 1002 (1000 + 100 × card + instance), and every view shows it as +`0/mig2`. The engine is given the instance by its UUID — +`CUDA_VISIBLE_DEVICES=MIG-…` — which works for vLLM and for llama.cpp's CUDA +build. llama.cpp's Vulkan build cannot see MIG instances at all. + +**What is measured.** Each instance's memory is its own; temperature, power +and wear are its card's, shown on each of its instances. Utilisation is not +reported for an instance, because no driver measures it per instance: the +console says `n/a on MIG`, and no `llmgw_gpu_utilization_percent` series is +published for it rather than a zero. + +`sudo llmgw doctor` lists each card's MIG mode and instances, and warns of a +card in MIG mode with none created (nothing can run on it: CUDA will not open +the whole card while MIG is on), of GPU instances with no compute instance, +and of a mode change waiting for a reset. Such a card is also kept out of +placement, with the reason, in `llmgw ctl nodes`. + ### InfiniBand, if you have it ``` @@ -458,6 +564,7 @@ Nothing to do: the agent installs them once the node joins, under | llama.cpp | every node | the release build for its processor and GPU — CUDA 13.3, CUDA 12.8 (x64), or Vulkan for GPUs and drivers the CUDA builds do not cover; the CPU build only where there is no NVIDIA GPU — checked against GitHub's checksum and seen to list the GPU | | vLLM | nodes with an NVIDIA GPU it can run on | a Python environment built by uv from PyPI, about 8 GB | | SGLang | only when you ask for it | the same way as vLLM | +| TensorRT-LLM | only nodes where you installed it | not installed by llmgw: see [TensorRT-LLM, which you bring](#tensorrt-llm-which-you-bring) | vLLM is resolved as PyPI stood a day after that vLLM was published, so every node gets the same dependencies whenever it is built, and installed with @@ -490,10 +597,15 @@ engines: sglang: "0.5.20" # SGLang only when named ``` +SGLang is started with `--enable-metrics`, without which it serves no +`/metrics`; the router reads `sglang:num_running_reqs`, `sglang:num_queue_reqs` +and `sglang:token_usage` there. Check an SGLang against the flags llmgw builds +with `llmgw ctl engine-check sglang --bin /bin/python`. + A changed version reaches every node when it next connects. To use an engine you installed yourself on a node, name its path in that node's `agent.yaml` -(`engines.llamacpp.bin`, `engines.vllm.bin`, `engines.sglang.python`): the agent -then installs none of its own beside it. +(`engines.llamacpp.bin`, `engines.vllm.bin`, `engines.sglang.python`, +`engines.trtllm.python`): the agent then installs none of its own beside it. #### Choosing a node's vLLM build @@ -544,6 +656,82 @@ which drift between releases: llmgw ctl engine-check vllm --bin /opt/llmgw/engines/vllm/0.30.0-cu13/bin/vllm ``` +#### TensorRT-LLM, which you bring + +llmgw does not install TensorRT-LLM. It is a pip package tied to one CUDA, one +PyTorch and an MPI the machine has to provide, and NVIDIA's own advice is its +container; an installer guessing at all of that would fail on most machines it +met, a long way into a large download. Install it on the node yourself — a +virtual environment, or NVIDIA's TensorRT-LLM container — and name its +interpreter in that node's `agent.yaml`: + +```yaml +engines: + trtllm: + python: /opt/trtllm/venv/bin/python # python3 inside NVIDIA's container +``` + +The node then offers the engine `trtllm` whenever that interpreter has the +`tensorrt_llm` package; without the line it offers nothing, whatever is on +`PATH`. It needs **TensorRT-LLM 1.3** (1.3.0rc13 or later): 1.2 has no +`--served_model_name`, and publishes none of the queue figures the router +reads. Check a node's against the flags llmgw builds: + +``` +llmgw ctl engine-check trtllm --bin /opt/trtllm/venv/bin/python +``` + +A model for it names a Hugging Face checkpoint, as for vLLM — trtllm-serve +downloads a repository itself, or loads one from the mirror: + +```yaml +name: llama-3.1-70b-instruct +source: meta-llama/Llama-3.1-70B-Instruct +profiles: + - name: h100x4 + engine: trtllm + gpu_class: h100-80g + tp: 4 + args: ["--max_batch_size", "64", "--free_gpu_memory_fraction", "0.85"] +``` + +The agent starts `trtllm-serve serve --host … --port … --tp_size … +--served_model_name …`, through a few lines of Python of its own that do what +trtllm-serve has no flag for: + +- **the key.** trtllm-serve checks none; every path but `/health` is made to + demand the one the gateway gives the replica, so the port on the node is not + a way around the gateway. +- **the metrics.** Its options file turns on `return_perf_metrics` and + `enable_iter_perf_stats`, without which `/prometheus/metrics` does not exist + and its queue figures do not move. The router reads + `trtllm_num_requests_running`, `trtllm_num_requests_waiting` and + `trtllm_kv_cache_utilization` there — not `/metrics`, which on trtllm-serve + is JSON. They are set as the engine iterates, so an engine gone idle shows + its last batch until the next request. +- **no usage reports to NVIDIA**: `TRTLLM_NO_USAGE_STATS` and `DO_NOT_TRACK` + are set, after the profile's own `env`. + +What it does not do: + +- **span nodes.** A TensorRT-LLM replica larger than one machine is launched + under MPI or Slurm from one of them, which the agents, each starting its own + node's part, do not do. A profile with `nodes` above 1 is refused; use vLLM + or SGLang for one. +- **run before Ampere.** Compute capability 8.0 or newer, which is what current + TensorRT-LLM builds kernels for. +- **take an options file from a profile.** `--config` and + `--extra_llm_api_options` are llmgw's; change a setting with `--set + PATH=VALUE` instead (`--set kv_cache_config.enable_block_reuse=false`). Also + refused, like the other engines' equivalents: `--trust_remote_code`, + `--tokenizer`, `--middleware`, `--chat_template`, `--grpc` and + `--num_serve_frontends` (both would serve without the key), and the flags the + agent sets. + +This engine was written against TensorRT-LLM's documented command line, +server and metrics, and tested with stand-ins for them; it has not yet run on a +datacenter GPU. Run `engine-check` on the first node before placing a model on it. + ### Weights Nothing to do here if you built the mirror in step 3 — the agent fetches what a @@ -674,8 +862,8 @@ llmgw ctl nodes ``` ``` -NODE STATE GPUS MEM CLASSES FABRICS REPLICAS LAST SEEN -llmgw-node01 ready 8/8 free 503G h100-80g ib-a 0 2s +NODE STATE LOCATION GPUS MEM CLASSES FABRICS REPLICAS LAST SEEN +llmgw-node01 ready - 8/8 free 503G h100-80g ib-a 0 2s ``` If it does not appear, the control plane's log says why. A certificate whose @@ -687,6 +875,27 @@ Repeat for each node. Nodes in the same fabric must be given the same `--fabric` name; nodes with no InfiniBand take no `--fabric` at all and are each their own island, which is fine for single-node models. +### Saying where the node is + +On more than one rack, tell llmgw which rack, and which PDUs, each node is in. +Placement then keeps a model's replicas in different racks and on different +PDUs, places nothing in a rack held for maintenance, and keeps each rack under +a power cap if you give it one: + +``` +llmgw ctl label llmgw-node01 llmgw.io/rack=r12-07 llmgw.io/pdu=r12-07-a,r12-07-b +llmgw ctl label llmgw-node01 llmgw.io/row=12 llmgw.io/room=hall-b llmgw.io/site=sto1 +``` + +Labels set this way are kept by the control plane and win over the node's +`agent.yaml`, where the same keys can go under `labels:` instead; a node need +not have joined yet. `llmgw ctl nodes` shows the LOCATION, `--domain +rack:r12-07` lists one rack, and `llmgw ctl facility` lists every rack, row and +PDU with what it draws. In the console it is the node's menu, **Location…**. +A node with no location is placed as before, as a rack of its own. +See [facility-aware-placement.md](facility-aware-placement.md) for power caps +and holds. + ## 6. Setting the node's CPU model, if it is a VM Proxmox defaults a VM to `kvm64`, which hides AVX, AVX2, FMA and even SSE4.2 @@ -845,6 +1054,114 @@ The adapter file must be a GGUF LoRA made for this model — llama.cpp's `convert_lora_to_gguf.py` makes one from a PEFT adapter — and not a model with the adapter already merged in, which is what most "LoRA GGUF" repositories hold. +#### Adapters on vLLM, and loading them on demand + +A vLLM model carries adapters the same way. There an adapter is a PEFT adapter +directory (`adapter_config.json` and `adapter_model.safetensors`): a mirror +version ending in `/`, a path on the nodes, or a Hugging Face repository id, +which vLLM downloads itself. A request names the adapter as its model, as on +llama.cpp; `scale` applies on llama.cpp only. Without anything more, every +replica registers every adapter at start (`--enable-lora --lora-modules`). +vLLM mixes one adapter per batch by default; raise that with `--max-loras` in +the profile's `args`, and `--max-lora-rank` (16 by default) for adapters of a +higher rank. + +With many adapters, have each replica hold only some of them: + +```yaml +- name: qwen2.5-7b-instruct + source: Qwen/Qwen2.5-7B-Instruct + max_loaded_adapters: 4 # per replica; vllm profiles only + adapters: + - name: support-de + source: http://mirror:8081/support-de/v3/ + - name: support-fr + source: someone/support-fr-lora + profiles: [...] +``` + +Replicas then start holding none (vLLM runs with +`VLLM_ALLOW_RUNTIME_LORA_UPDATING=True` and `--max-loras 4`). The first +request for an adapter has the router load it on a replica through vLLM's +`/v1/load_lora_adapter`, and the requests after it go to that replica while +it is not saturated; when it is, the next request goes where load sends it and +the adapter is loaded there too. Requests that arrive while an adapter is being +loaded wait for that load rather than starting another. A replica that holds +`max_loaded_adapters` already unloads the one least recently used, never one a +request is running on. Each node still fetches every adapter when a replica +starts, and links it as `llmgw-lora/` in the directory engines run in, +which is the path the router has vLLM load it from — so adding an adapter +still needs the replicas restarted, as above. An adapter vLLM refuses (not +found, a rank above `--max-lora-rank`, not for this model) fails the request +with vLLM's reason. + +What each replica holds is what the router loaded there, checked against each +replica's `/v1/models` when the router first meets it and every 30 seconds. +`llmgw_adapter_affinity_total` counts where requests found their adapter (hit, +joined a load, loaded it), `llmgw_adapter_loads_total` and +`llmgw_adapter_evictions_total` what that cost. llama.cpp keeps loading every +adapter at start: llama-server can change the scale of an adapter it started +with, not load a new one. + +### Routing by what each replica's cache actually holds + +With several replicas of a vLLM model, a request is fastest on the replica +that already holds its prompt's prefix in KV cache. The router guesses which +that is from what it has sent where (`router.prefix`). It can also be told: +vLLM publishes an event every time it stores or evicts a cache block, and with +`kv_events` on a profile llmgw routes that model by those events. + +```yaml +- name: llama-3.1-8b-instruct + source: meta-llama/Llama-3.1-8B-Instruct + routing_profile: chat # chat or long-context; batch ignores prefixes + profiles: + - name: h100 + gpu_class: h100-80g + kv_events: true +``` + +How it works, so you know what you are paying for: + +- The node agent starts vLLM with `--kv-events-config` publishing to a port + on 127.0.0.1 that the agent listens on, `--prefix-caching-hash-algo + sha256_cbor`, and `PYTHONHASHSEED=1729`. The events never leave the node: + the agent keeps the set of blocks each engine holds and sends the changes, + four times a second, up the stream it already has to the control plane, + which hands them to the router. A new stream — a control plane restart, a + failover — starts with a full copy. Nothing new is opened in the firewall. +- For each request to such a model, the router asks one of its replicas to + tokenize the prompt (vLLM's `/tokenize`, with the request's messages and + tools), hashes the token ids into blocks the way vLLM does, and prefers the + replica holding the most leading blocks. Tokenizing at the engine is what + makes the hashes agree: the chat template is part of the tokens, and only + the engine runs it exactly. It costs a round trip before the request is + placed and the template run twice; `router.kv_index.tokenize_timeout` + (250ms) bounds it. +- When the index has nothing to say — no events have arrived yet, the + request has an image or a `cache_salt` or names a LoRA adapter, the + tokenize call failed — the router routes as it would without it: by the + approximate tree if `router.prefix.enabled`, else by load. The imbalance + guard of `router.prefix` applies to both. + +Turning `kv_events` on changes how the engine is started, so replicas already +running keep running without it (and show as stale) until they are replaced. +Leave `--prefix-caching-hash-algo` out of the profile's `args`: an engine +hashing another way publishes blocks the router can never match. The agent +checks the first block of prompts against its own hashing, and if they never +agree it says so in its log and on `llmgw_kv_index_problem`, and the replica +is routed as though it published nothing. + +Watch `llmgw_kv_index_decisions_total` beside `llmgw_prefix_decisions_total`: +`kv_hit` is the index deciding, `kv_miss_min_load` is it knowing no replica +holds enough (`router.kv_index.min_blocks`, 4 blocks), and the `fallback_*` +values say why it could not answer. `llmgw_kv_index_tokenize_seconds` is what +the tokenize call costs, and `llmgw_kv_index_blocks` what each replica holds. + +This has been built and tested against vLLM's event format and its hashing as +its source defines them, with libzmq and msgspec publishing — not yet against +a running vLLM. Treat it as experimental until it has been. + ### Models served outside the cluster A model can be an OpenAI-compatible API elsewhere — a hosted provider, or @@ -879,6 +1196,207 @@ prices and budgets, rate limits, usage records, and key allowlists. whose allowlist leaves the external model out cannot reach it, as a fallback or by name. The cluster page and `ctl models` mark it `external`. +### Federating clusters + +Another llmgw cluster — another site, another team's GPUs — can be a provider +of this one, and llmgw knows it is one. Ask the other cluster's operator for a +key in one of their projects (`llmgw keys create`), put it in a file on this +control plane (on every control plane, with HA), and add the peer: + +``` +llmgw ctl federation add east --url https://llm.east.example --key-file /etc/llmgw/secrets/east.key +llmgw ctl federation list +llmgw ctl model fallbacks qwen-7b east/qwen-7b # overflow goes to east +``` + +- **Its models, named PEER/MODEL.** What the peer's `/v1/models` offers that + key is offered here as `east/qwen-7b` and so on, always with the prefix — + never under the peer's own name, even when nothing here uses it, so + whether a request leaves the cluster never depends on what else is in the + catalog, and every usage record and `x-llmgw-served-model` header says which + site answered. A model here called `east/...` wins over the peer's of the + same name. The peer's aliases, and models the peer has from peers of its + own, are not taken: federation is one hop. +- **Kept in step.** Each peer is checked every `federation.interval` (10s): + its `/ready`, timed — the latency `ctl federation list` shows — and its + `/v1/models`. A model it adds appears here; one it drops goes, unless a + model here still falls back to it, when it is kept *withdrawn* (in the + catalog, sent nothing) until the fallback is changed. `ctl federation sync + east` checks now. +- **Taken out when down.** A peer whose `/ready` fails, which refuses the key, + or which does not answer is sent nothing until it answers again; its models + stay in the catalog. A peer's `/ready` counts only what it serves itself, so + two clusters federating each other are not each ready because of the other. +- **Overflow.** Named in a model's fallbacks (`ctl model fallbacks`, for + models added at runtime), a peer's model is used only when the model has + no capacity here — as for any external model. +- **What stays here, stays here.** A peer's model is an external model: a + project with `keys residency --in-cluster`, or under a guardrails policy with + `no_store`, is refused it by name and never sent to it as a fallback. +- **One key, and who is asking.** The peer sees this cluster's key, so its + usage, limits and budgets are one tenant's. The request's `X-Request-Id` + goes with it, so one id finds the request on both sides. With + `--send-tags` the request also carries `x-llmgw-tags: + federated_from=,org=…,team=…,project=…` (ids), for the + peer's usage records to attribute it; off unless given, because it tells + the other site who here is asking. +- **No loops.** Each cluster has an id (`ctl federation list` shows it), and a + request sent to a peer carries `x-llmgw-hop` with the ids it has passed + through. A cluster refuses a request that has already passed through it + (508, `federation_loop`), and does not send one to a peer it came from — + so two clusters falling back to each other try each once. +- `llmgw_federation_peer_up`, `_latency_seconds` and `_models` are on + `/metrics`; the console has a Federation view. `ctl federation remove east` + takes the peer and its models away, refused while a fallback names one. + +Not yet: models declared in server.yaml cannot name a peer's model as a +fallback (the catalog in the file is checked before the peers are read), and +a peer behind a private CA needs that CA in the system's trust store. + +### Trying new weights on some of the traffic first + +When a model's repository publishes new weights, `llmgw ctl model update` +swaps them in. To see how they serve first, run them as a canary: + +``` +llmgw ctl model canary qwen-7b --percent 10 # fetched, started beside, given 10% +llmgw ctl model canaries # how each side has served +llmgw ctl model canary qwen-7b --percent 50 # more +llmgw ctl model promote qwen-7b # the model moves to them +llmgw ctl model canary qwen-7b --abort # or not +``` + +- **What runs:** the new files are fetched into the mirror and checked as + for an update, then run as `qwen-7b-canary` — the same model in everything + but its weights, one replica. Clients cannot name it; it gets its share + of `qwen-7b`'s requests. +- **Who goes where:** a session (`x-session-id`, or the `user` field) + stays on one side, so a conversation does not change weights halfway. + `x-llmgw-variant: canary` or `stable` pins a request to one side; the + response says which served it in the same header, and the usage record + names `qwen-7b-canary` as the model that served it. +- **Rolled back by itself:** once the canary has served `--min-requests` + (50), it is taken out if its error rate is `--max-error-increase` (0.05, + five points) above the model's, or its mean time to the first token — or + to the answer, unstreamed — is `--max-ttft-ratio` (1.5) times the + model's. `canary_rolled_back` goes to the notification webhooks. The + comparison is the router's own count since the canary began, kept per + control plane. +- **Promote** is the update the canary was a trial of: the model's replicas + are replaced one at a time, and `llmgw ctl model rollback` goes back. + +### Quality suites, and holding new weights to one + +A canary says whether new weights serve as fast and as reliably; it does not +say whether their answers are as good. A republished quantisation or a chat +template that no longer matches can make a model faster and worse at once. A +quality suite is a handful of questions with known answers, asked of a model +and scored: + +``` +llmgw ctl eval --suites # what the control plane can run +llmgw ctl eval qwen-7b --suite arithmetic # by name, on the control plane +llmgw ctl eval qwen-7b --suite ./support.yaml --judge llama-70b --concurrency 8 +llmgw ctl eval --history qwen-7b # the runs kept +llmgw ctl eval --run eval-20261004-101500-1a2b3c4d # one, case by case +``` + +It prints each case's score and why, then the suite's: the cases' scores +weighed, 0 to 1, and whether it reached the suite's `threshold` (or +`--min-score`); it exits non-zero below it, so a script can stop on it. + +- **How it is asked:** on the control plane, through the router as the + gateway's own requests, the way a replay is — past admission, quotas, + accounting and the guardrails, so the score is the weights' and not a + tenant's limits'. It reaches the model exactly as a client's request + would, a canary or a model loading on demand included. Answers are asked + at temperature 0 unless a case says otherwise, and a reasoning model's + `` block is not part of its answer. +- **Where suites come from:** `--suite` is a file on the machine running + `ctl`, sent whole, or the name of one in the control plane's + `control.eval_dir` (`/etc/llmgw/eval`). Two are built in and run on small + models: `arithmetic` (sums and word problems, each scored by the number in + the answer) and `json-format` (answers asked for as JSON of a given shape); + their files are in `deploy/eval/`, to copy and change. A file in the + directory with the same name replaces the built-in one. +- **What is kept:** every run, in the store, with the model, the repository + and revision the answering weights came from (when known), the suite's name + and sha256, when, the score, and each case's answer (up to 2,000 + characters), score and reason. A run on a canary is filed under the model + it is a canary of. Runs are not pruned. + +A suite is YAML (or JSON lines: one case on each line, and optionally a line +without a prompt that holds the suite's own settings): + +```yaml +name: support # the file's name unless given +threshold: 0.8 # the score to pass at, 0 to 1; 0.8 unless given +judge: llama-70b # grades the cases scored by a rubric +system: You are a support agent for Acme. # every case's, unless it has one +max_tokens: 256 # every case's; 512 unless given +cases: + - id: refund-window + prompt: How many days do customers have to ask for a refund? + number: 30 # the last number in the answer, ±tolerance + tolerance: 0 + - prompt: Which plan includes SSO? + contains: [Enterprise] # every string must appear + ignore_case: true + - prompt: Reply with only the word OK. + exact: OK # the whole answer, white space around it aside + - prompt: What is today's ISO date format? + regex: '\d{4}-\d{2}-\d{2}' # matches somewhere in the answer + - prompt: Give the order as JSON with "id" and "total". + json_schema: # the answer, read as JSON, satisfies it + type: object + required: [id, total] + properties: { id: {type: string}, total: {type: number, minimum: 0} } + - messages: # a conversation instead of a prompt + - { role: user, content: My card was charged twice. } + judge: Apologises, and says the duplicate charge is refunded within 5 days. + weight: 3 # counts three times; 1 unless given +``` + +Each case is scored by exactly one of `exact`, `contains`, `regex`, `number`, +`json_schema` or `judge`. A JSON answer in a code fence or inside a sentence is +still read. The schema supports `type`, `properties`, `required`, +`additionalProperties`, `items`, `enum`, `const`, the numeric and length bounds, +`pattern`, `anyOf` and `allOf`; a suite using anything else is refused when it +is read rather than passed unchecked. A `judge` case asks another model on the +cluster (`judge_model:` on the case, else the suite's `judge:`, else `--judge`) +to grade the answer by the rubric, 0 to 1. A case passes at 0.5; a case that +got no answer scores 0 and says why. + +**Holding updates to a suite.** `model update` and `model promote` take +`--eval SUITE --min-score N` (and `--judge`); or a model carries one — set +with `ctl model gate`, or `eval: { suite: arithmetic, min_score: 0.8 }` in a +definition added with `ctl model add` — so every update and promotion of it +is held to it, from `ctl`, the console or anywhere: + +``` +llmgw ctl model gate qwen-7b --eval arithmetic --min-score 0.8 +llmgw ctl model update qwen-7b # asked the suite first +llmgw ctl model update qwen-7b --skip-eval # once, without it; the job says so +llmgw ctl model gate qwen-7b --off +``` + +- **Promote** asks the canary the suite before anything moves; below the + score the job fails with the score, and the canary stays, with its share, + until you take it out. +- **Update** runs the new weights first as `MODEL-canary` given none of the + model's requests (hidden from clients like any canary), asks it the suite, + then either promotes it — the model's replicas are replaced one at a time, + as for any update — or takes it out again, leaving the model on its old + weights. That needs room for one more replica while it runs; a model that + already has a canary is promoted or aborted first. Without a suite, an + update swaps the weights in as it always has. +- The job's `eval` step says the score (`llmgw ctl jobs JOB`), and the run is + kept with the job's id beside it. + +The console has it on a model's menu: **Ask it a quality suite…** (a suite the +control plane has, the score as it comes in), **Its quality runs**, and **Hold +its updates to a quality suite…**. + ### How many replicas, and how much each one carries Replica count is changed while the cluster runs, without editing the @@ -892,6 +1410,26 @@ Models added at runtime only. One declared in `server.yaml` is read again on every start, so a number set here would hold until the next restart and then revert — change it in the file instead. +Between `min` and `max` a model scales with its load: requests waiting at +every replica add one, a quiet spell takes it back. For load that comes by the +clock, a schedule says so ahead of time: + +```yaml +scaling: + min: 1 + max: 4 + prewarm: 30m # start a window's replicas this long before it opens + schedule: + - {days: [weekdays], from: "08:00", to: "18:00", min: 3, max: 6} + - {from: "22:00", to: "02:00", min: 1} # past midnight +``` + +Times are in `control.timezone` (`Europe/Istanbul`; empty is the control +plane's own). The first window that holds wins; outside every window, `min` +and `max` apply. An on-demand model (`min: 0`) with a window is kept loaded +through it, and loaded again on the first request after. Days are `mon` … +`sun`, `weekdays` or `weekends`. + How much traffic each replica is given is the profile's `weight`, and guessing it is how a cluster ends up with one saturated replica beside two idle ones. Measure it instead: @@ -927,6 +1465,19 @@ Or open `/chat` in a browser and use it without a key at all — the page carrie your session, and the request still goes through admission, rate limits, budget and accounting exactly as an API call does. +### What the client port answers + +| Path | What | +|---|---| +| `POST /v1/chat/completions`, `/v1/completions`, `/v1/embeddings` | OpenAI's, served by the models in the catalog | +| `POST /v1/responses` | OpenAI's Responses API, translated to chat completions: tools, `text.format` (structured output), `input_image` (by URL or `data:` URL), and `previous_response_id` — the conversation is kept as a thread, so the project must keep conversations (`llmgw keys threads`); `store: false` keeps none | +| `POST /v1/messages`, `/v1/messages/count_tokens` | Anthropic's Messages API, translated to chat completions: text, images, tools and their results, the system prompt, streaming; the key in `x-api-key` or `Authorization`. Extended thinking, prompt caching and server tools are ignored | +| `POST /v1/rerank`, `/v1/score` | passed through to an engine that serves them: vLLM with a reranker or a cross-encoder | +| `POST /v1/audio/transcriptions`, `/v1/audio/translations` | the multipart form passed through as it came, to an engine that serves speech to text: vLLM with Whisper | +| `POST /v1/moderations` | answered by the guardrails' judge model (`role: guard`): `flagged`, and the judge's own categories | +| `/v1/files`, `/v1/batches` | batches; see [Batches](#batches) | +| `GET /v1/models` | the models this key may use | + ## Watching it The control plane exports both halves on one endpoint: what the cluster is @@ -966,6 +1517,28 @@ fleet means the measurement is missing, not that the fleet is idle. And `llmgw_gpu_nvlink_peers` at zero everywhere means the topology is unknown, which is what a binary built without the nvml tag reports. +### Token by token, and SLOs + +Beside time to the first token, every streamed answer is timed per token: +`llmgw_tpot_seconds` (each output token after the first), +`llmgw_inter_token_seconds` (the gaps between streamed events, which show the +stalls a mean hides) and `llmgw_output_tokens_per_second`, by model and pool, +and `llmgw_tenant_tpot_seconds` and `llmgw_tenant_output_tokens_per_second` by +tenant. + +A model can say what it promises: + +```yaml +slo: {ttft_p99: 2s, tpot_p99: 80ms} +``` + +Then its recent p99 — the last five minutes, once there are twenty streamed +requests — counts in admission: a model past its SLO is treated as saturated +by as much as it is past, so the lower bands wait while the queue and the +cache still look healthy. `llmgw_model_slo_seconds` publishes the SLOs, and +the `llmgw-slo` alerts in deploy/monitoring fire when a p99 stays past one for +fifteen minutes. + ### Being told Prometheus alerts travel once `alertmanager.yml` names a receiver; it ships @@ -981,6 +1554,7 @@ control plane sends those itself: | `node_lost` | A node was silent past `control.lost_after`; its replicas are rebuilt elsewhere. | | `budget_spent` | A key, project, team or organization reached its budget; priced models are refused. | | `update_available` | A model's registry repository published different weights. Once per revision. | +| `canary_rolled_back` | A model's canary served worse than the model and was taken out. | | `judge_unavailable` | A guardrails judge gave no verdict: with `fail: closed` requests are being refused, with `open` served unjudged. | ```yaml @@ -1002,6 +1576,46 @@ same event about the same thing is sent at most once an hour, so a budget that refuses a thousand requests is one message. `llmgw ctl notify test` sends a test event to each webhook and says how each answered. +### Tracing + +Metrics say that a model took four minutes to start; a trace says where they +went. Give the control plane and every agent the same OpenTelemetry collector, +over OTLP/HTTP — Jaeger, Tempo, Honeycomb, anything that takes OTLP: + +```yaml +# /etc/llmgw/server.yaml, and the same block in each node's agent.yaml +tracing: + endpoint: http://otel.internal:4318 + sample_ratio: 1 # of requests that arrive without a decision of their own +``` + +`OTEL_EXPORTER_OTLP_ENDPOINT` does the same when the file does not say. With +neither, nothing is traced and nothing is sent: every span is a no-op, and a +command to a node carries no trace context. + +What is traced: + +| Trace | Spans | +|---|---| +| An inference request (`llmgw-server`) | `inference /v1/…` with `admission`, `schedule` and an `upstream` per attempt beneath it; a caller's `traceparent` is continued and the engine is sent one. | +| A reconcile pass that did something | `reconcile`, and beneath it what it did: `scale up` with `place` (the profile, GPU class, pool, fabric and nodes chosen, or every candidate turned down and why) and `replica start`; `scale down`; `drain replica` and `stop replica`, each with its reason; `evict`, `preempt` with its victims; `reap replica` with the error and when it is tried again; `restart replica`, `restart refused`; `node unreachable`, `node lost`. A pass that found nothing to do is not traced. | +| A replica's start | `replica start` stays open from placement until the replica serves, fails or is stopped, with each shard's progress as an event on it and how long it took. A `send start` per shard beneath it is the command to the node, and the node's spans (`llmgw-agent`) continue the same trace: `start shard`, with `fetch weights` (local, cached, downloaded or fetched by another shard, and a `download` with its bytes), `launch engine` (and `wait for rendezvous` on a worker of a multi-node replica) and `wait for engine` (how often the engine was asked, and its last answer if it never came up). | +| A stop on a node | `stop shard` and `stop engine` in the trace of the control plane's `stop replica`, saying whether the engine had to be killed. | +| An adoption | `adopt`, when a node that registers reports engines already running, with how many nobody claimed. | +| A model job | `serve model` or `update model`, with a span per step — `registry`, `mirror`, `check`, `catalog`, `placement`, `smoke test`, `replicas` — and from the placement step a link to the replica's own start. | +| An engine install | `install engine` on the node, a trace of its own. | + +So "why did qwen take four minutes to start" is one trace: find `replica start` +with `llmgw.model` = qwen, and the node's spans beneath it say whether the +time went to the download, the launch or the engine loading. + +A node follows the control plane's decision: a start the control plane kept is +traced on the node whatever the agent's own `sample_ratio`, and one it sampled +out is not; the agent's ratio decides only for what arrives with no trace, as +from a control plane that is not tracing. The agent needs its own `tracing` +block either way — without one its spans go nowhere, and the control plane's +trace simply ends at `send start`. + ## PostgreSQL, when SQLite is no longer the right shape SQLite is the default and stays the right answer for most installations: one @@ -1062,6 +1676,162 @@ outcome than a smaller cache, so cap it: `shared_buffers = 96MB` and `max_connections = 40` are enough for a store whose working set is measured in megabytes. +## Tagging requests + +A client can say what a request was for — which feature, which customer, +which environment — and the spend can then be found by it inside a project: + +``` +curl http://gateway:8080/v1/chat/completions \ + -H "Authorization: Bearer $LLMGW_API_KEY" \ + -H "x-llmgw-tags: feature=search, env=prod" \ + -d '{"model": "qwen-1.5b", "user": "customer-42", + "metadata": {"feature": "search"}, + "messages": [{"role": "user", "content": "hello"}]}' +``` + +- **`metadata`** is OpenAI's: an object of strings, up to 16 keys. **`x-llmgw-tags`** + is the same as a header, for clients that cannot change the body; for a + key both give, the header wins. A key is 1 to 64 letters, digits, `_`, + `.` or `-`, a value at most 512 bytes; anything else is refused with 400 + rather than dropped, since a tag lost silently is spend nobody finds. +- **`user`** is OpenAI's end-user field: the client's own name for whoever + it serves, not an account here. It is passed on to the engine, as OpenAI + does; tags are not. +- **Where they show:** every usage record keeps them, and `llmgw ctl request + ` prints them. For Prometheus, name the tags worth a series: + + ```yaml + router: + tag_labels: [feature, env] + ``` + + `llmgw_tagged_requests_total{tag,value,outcome}` and + `llmgw_tagged_tokens_total{tag,value,direction}` count those, the first + 100 values of each apart and the rest as `other`: a tag is the client's + to set, and every value is a series. + +## Keeping requests, and replaying them + +To follow a request up — what exactly was sent, what came back — or to try +real traffic on another model, a project can keep its requests: + +``` +llmgw keys requests --project Acme/ml/train --retain-hours 72 # every one +llmgw keys requests --project Acme/ml/train --retain-hours 168 --sample 0.05 +llmgw ctl request req_3f2a… --body # what was sent and answered +llmgw ctl request req_3f2a… --replay qwen2.5-14b-instruct # the same, to another model +llmgw keys requests --project Acme/ml/train --off +``` + +- **What is kept:** the request as the model was sent it — after the + guardrails' redaction, with any stored conversation spliced in — and the + answer as the client got it, up to 128 KB of it. A share (`--sample`) is + the same requests every time for the same ids. +- **Replay** sends it as the gateway itself: past the limits, the budget and + the guardrails, which judged it the first time, and charged to nobody. +- **Never** for a project under a guardrails policy with `no_store`. Kept + requests past their hours, or of a project turned off, are removed hourly. + The console has it as **Keep requests…** on a project. + +## Reusing answers + +A project that asks the same thing again and again — an evaluation run over +the same prompts, embeddings of documents that do not change, an agent that +retries — can have the same request answered from memory rather than by the +model: + +``` +llmgw keys cache --project Acme/ml/train --ttl 1h # reproducible answers +llmgw keys cache --project Acme/ml/eval --ttl 24h --any # every answer +llmgw keys cache --project Acme/ml/train # how it stands +llmgw keys cache --project Acme/ml/train --off +``` + +- **What is the same request:** the same project, the same endpoint, the same + model (by its catalog name, whichever alias was used) and the same body, + with `stream`, `stream_options`, `user`, `metadata`, `store` and + `service_tier` left out and the keys in any order. Keys of another project + never see the answer, whatever they send. +- **Which answers are reused:** a chat or completion asked at `temperature` + 0 or with a `seed`, and every embedding, rerank and score, which sample + nothing. A request sampled above temperature 0 with no seed asks for a new + answer, and is asked anew — unless the project says `--any`. Only a whole + 200 from the model that was asked for is kept: not an error, not a + fallback model's or a canary's answer, not one a guardrail changed or + stopped, not one longer than `router.cache.max_entry_bytes` (1 MB). +- **Streams:** an answer given whole is streamed to a client that asks for a + stream, as one chunk per choice with the usage chunk if it asked for that; + a streamed answer is kept put back together, and served whole to a client + that does not stream. Through `/v1/messages` and `/v1/responses` too. +- **The client decides too:** `Cache-Control: no-cache` (or `no-store`), or + `x-llmgw-cache: no`, is always asked anew. Every answer of a project that + reuses answers says `x-llmgw-cache: hit`, `miss` or `bypass` (not one that + can be reused), and a hit says its `Age` in seconds. +- **Policies still apply:** the limits are checked and the guardrails judge + the request before the cache is looked in, and the output policy judges a + reused answer as it would a new one. A request continuing a stored + conversation, or under a `no_store` policy, is never answered from the + cache nor kept in it. +- **What a hit costs:** nothing. It is recorded as a request — status 200, + the model, the key, the rate limit's count — with no tokens and no cost, + marked as a cache hit (`llmgw ctl request ` says so), so it spends no + budget and no token limit. The answer itself carries the usage the model + reported when it was first given. +- **Where it lives:** in each gateway process's memory, at most + `router.cache.max_bytes` (128 MB) of answers for all projects together, + those used longest ago dropped first; nothing is written to the store, and + a restart begins it again. With two control planes behind a balancer each + keeps its own. A change of setting is seen within 30 seconds; a shorter TTL + applies to what is already kept. + +```yaml +router: + cache: + max_bytes: 268435456 # 256 MB + max_entry_bytes: 2097152 # 2 MB +``` + +`llmgw_cache_requests_total{model,result}` counts hits, misses and +bypasses, `llmgw_cache_bytes` and `llmgw_cache_entries` what is held. The +console has it as **Cache answers…** on a project. + +## Batches + +Work that can wait — a night's classification, embeddings for a document +store — goes as a batch: OpenAI's Batch API, so its clients work unchanged. + +``` +curl http://gateway:8080/v1/files -H "Authorization: Bearer $LLMGW_API_KEY" \ + -F purpose=batch -F file=@requests.jsonl +curl http://gateway:8080/v1/batches -H "Authorization: Bearer $LLMGW_API_KEY" \ + -d '{"input_file_id": "file-…", "endpoint": "/v1/chat/completions", "completion_window": "24h"}' +curl http://gateway:8080/v1/batches/batch_… -H "Authorization: Bearer $LLMGW_API_KEY" +curl http://gateway:8080/v1/files/file-…/content -H "Authorization: Bearer $LLMGW_API_KEY" +``` + +Each line of the file is `{"custom_id": …, "method": "POST", "url": +"/v1/chat/completions", "body": {…}}`, at most 50 000 of them +(`router.batch.max_lines`) in at most 100 MB (`router.batch.max_file_bytes`). + +- **How it is served:** each line as a request of the key that made the + batch — its limits, its budget, its guardrails — in the lowest admission + band, behind every interactive request, `router.batch.concurrency` (4) at + a time. A rate limit or a model still loading is waited out; a spent + budget fails the lines left. +- **What comes back:** answers in an output file, failures in an error + file, both OpenAI's form, kept `router.batch.retain_days` (30). Each + request is a usage record tagged `batch=`, so `llmgw ctl request` + finds it. +- **Who sees it:** files and batches belong to the key's project; every key + of the project sees them, no other does. +- **Surviving a restart:** every answered line is kept as it is answered, + and whichever gateway holds the batch's lease carries on from there; a + control plane that stops hands its batches to another within two minutes. +- **What it keeps:** a batch is prompts and answers stored until deleted + or past their retention — a project under a guardrails policy with + `no_store` is refused it. + ## Conversations across models Off everywhere until a project asks. llmgw otherwise stores no message content @@ -1155,6 +1925,34 @@ thing to get right is the health check: point it at `/ready`, not `/health`. so a load balancer using it would send half the traffic to something that refuses every request. +## The portal's language + +The web portal — the landing page, sign-up and sign-in, the account and chat +pages, and the administrators' pages — speaks English and Turkish. Each person +gets, in this order: + +1. the language they chose with the switcher at the foot of every page, which + is remembered in a cookie (`llmgw_lang`) for a year; +2. otherwise the first language their browser asks for that the portal speaks; +3. otherwise the server's own default: + +```yaml +# /etc/llmgw/server.yaml +landing: + language: tr # en or tr; empty is English +``` + +A code the portal does not speak stops the server starting, rather than +quietly serving English. Figures and dates follow the page's language: a +Turkish page writes 1.234,5 and 04.10.2026. Messages that come from the +control plane itself — a node's warnings, an engine's errors — are shown as +they were written, in English. The API, the CLI and the console are English. + +Adding a language is adding a directory: `internal/web/locales//` with +the same files and keys as `locales/en/`, and its `_meta.*` entries saying how +it writes numbers and dates. The tests refuse a catalogue that lacks a key a +page uses. + ## Single sign-on People can sign in through your identity provider — Keycloak, Entra ID, @@ -1212,6 +2010,43 @@ and point it at `https:///scim/v2` with that token as the bearer. join and leave them. Membership in a group is removed when someone leaves it. +## Secrets in Vault + +Every setting that names a file holding a secret — the store's `@address`, +`api_key_file`, `auth.oidc.client_secret_file`, `auth.scim.token_file`, a +webhook's `secret_file` — also takes `env:VARIABLE` or a field of a secret in +HashiCorp Vault or OpenBao: + +```yaml +auth: + store: "@vault:secret/llmgw/store#dsn" +secrets: + vault: + addr: https://vault.internal:8200 + ca_file: /etc/llmgw/vault-ca.pem + role_id_file: /etc/llmgw/secrets/vault-role-id # AppRole; or token_file, + secret_id_file: /etc/llmgw/secrets/vault-secret-id # or VAULT_TOKEN + master_key: vault-transit:llmgw +``` + +These are read when the gateway starts (an external model's key, each time +the catalog changes): a secret rotated in Vault is taken up at the next +restart. + +**The store's own secrets** — what every engine's key is derived from — are +kept in the store, and so in its backups. `secrets.master_key` seals them: + +- `vault-transit:KEY` seals with Vault's transit engine. The key never leaves + Vault, so neither the store nor any backup of it opens without Vault. +- Anything else is a reference to 32 random bytes (`openssl rand -hex 32`), + used here: better than nothing, but a key in `/etc/llmgw` is in every backup + beside what it seals. Keep it in Vault or the environment. + +Values kept plain from before are sealed the first time they are read after +the key is set. The key cannot be changed once set without losing them: a new +one cannot open what the old one sealed (the engines are then restarted with +new keys: `llmgw ctl restart --all`). + ## The firewall `server init`, `node add`, `server add` and `mirror init` each keep that @@ -1245,6 +2080,139 @@ doctor` on a node says when the table is missing. `--no-firewall` on any of the four commands leaves the firewall alone; `sudo systemctl disable --now llmgw-firewall` removes it. +## Offline sites + +Everything above downloads: the nodes fetch llama.cpp from GitHub and vLLM from +PyPI, `node add` and upgrades fetch llmgw's releases, and the mirror fetches +models from Hugging Face. A site with no route to the internet gets all of that +in a **bundle**, made somewhere that has one and carried in. + +### Making the bundle + +On any machine with internet and llmgw — a laptop will do: + +``` +llmgw bundle create --out llmgw-bundle --arch amd64 --tar +``` + +That carries: + +- **llmgw's release** for each `--arch` (default: this llmgw's own version; + `--version` for another), with `checksums.txt` and its signature, checked + against the project's signing key as `ctl upgrade` checks it. +- **llama.cpp** at the version this llmgw installs, every build for each + architecture — CPU, CUDA 13.3, CUDA 12.8 (amd64), Vulkan — each checked + against the checksum GitHub publishes, the same check a node does online. + `--variant cpu --variant cuda-13.3` carries only those, for a site whose + hardware you know; `--engine llamacpp=b10991` names the version. +- **The starter model and the guardrails' judge** that `server init` serves + (about 1.3 GB; `--no-starter-models` leaves them out), and any + `--model name/version=hf:owner/repo/file` you add, pinned to the commit the + registry had and checked against the checksum it publishes. + +It ends by printing the manifest's **sha256**. Carry that apart from the bundle +— in the ticket, read out over the phone — because it is what says the bundle +that arrived is the one that was made. `llmgw bundle show llmgw-bundle.tar +--verify` reads every file back, worth doing once it is on the disk that +carries it. Run `create` again with the same `--out` (without `--tar`) to add +to a bundle; what is there already is not downloaded again. + +What a bundle does **not** carry: vLLM and SGLang, which are Python +environments of several gigabytes from PyPI. Offline nodes serve with llama.cpp; +on a GPU node that needs vLLM, install it by hand and name it with `node add +--vllm-bin` (the node reports vLLM as unsupported until then). Nor the +operating system's packages — the OpenMP runtime llama.cpp needs, PostgreSQL +with `--postgres` — which come from each machine's own package sources: at an +offline site, its distribution mirror. + +### Installing from it + +On the control plane, with the bundle on a local disk: + +``` +sudo llmgw server init --bundle /media/usb/llmgw-bundle.tar --bundle-sha256 3f2a… +``` + +(The console's setup form has the same two fields.) Init then does what it +always does, with these differences: + +1. Before the control plane starts, the bundle goes into the mirror beside it: + every file checked against the manifest, the release against the signing + key, and only then put in place. llmgw's releases and the engines go under + `/srv/models/_llmgw/`, the models where the mirror keeps models. +2. The engines' checksums are written to `/etc/llmgw/offline.sha256`. That + file, on the control plane, is what each node's engine files are held to. +3. `server.yaml` gets + + ```yaml + offline: + mirror: http://10.0.0.5:8081 # the mirror's file port, as nodes reach it + ``` + + and from then on the cluster asks nothing of the internet: nodes install + llama.cpp from the mirror, `releases` defaults to the mirror's copy (so + `node add` and `ctl upgrade` fetch from it), and the registry is not asked + about newer weights. +4. The starter model and the judge are served from the mirror when the bundle + carries them, and skipped — not waited for — when it does not. Without the + judge, the guard policy is written without one. + +With the mirror on another machine (`--mirror`), import the bundle there first +and then run init with `--bundle` as above: the control plane records only the +checksums. + +``` +# on the mirror machine +sudo llmgw bundle import /media/usb/llmgw-bundle.tar --sha256 3f2a… +``` + +Nodes join as usual with `sudo llmgw node add`: it fetches the node's binary +from the mirror and checks its signature, and the agent installs llama.cpp +from the mirror. Nothing on the node needs the internet. + +### How it stays checked + +Online, a node trusts GitHub, over TLS, for the checksum of the llama.cpp it +installs, and the project's signing key for llmgw. Offline it is the same +strength by a different route: the checksum GitHub published is recorded when +the bundle is made, the bundle is held to its sha256 when it is imported, and +the control plane keeps the checksums and tells each node, over its mutually +authenticated connection, what every file it fetches must be. The mirror serves +plain HTTP and is never asked for a checksum: a file changed on it, or on the +way from it, is refused by the node. Releases carry the project's signature, +which holds whatever server they come from — so plain HTTP from the mirror is +allowed for releases only because this build trusts a signing key. + +### Later + +A new llmgw release or llama.cpp version is another bundle. Make it the same +way — `--version v0.12.0`, `--engine llamacpp=b11200` — and on the control plane +(and the mirror, if separate): + +``` +sudo llmgw bundle import new-bundle.tar --sha256 … +``` + +The control plane sees the new checksums without a restart. Then set +`engines.llamacpp` in `server.yaml` to the new version and restart +`llmgw-server`, or run `sudo llmgw ctl upgrade v0.12.0` for the release. A +mirror on its own machine, which is not an agent, is upgraded from its own +copy: `sudo llmgw upgrade v0.12.0 --service llmgw-mirror --releases +http://127.0.0.1:8081/_llmgw/releases`. A control plane whose bundle lacks the +llama.cpp version it asks for says so in its log at start, and the node says +which `bundle create` would carry it. More models: `--model` in a bundle, or +copy the files into the mirror by hand — it is a directory. + +A cluster set up online becomes offline the same way: `bundle import` on the +mirror and control plane, then the `offline:` block in `server.yaml` and a +restart. + +## Kubernetes + +The control plane runs in Kubernetes from the Helm chart in +`deploy/helm/llmgw`; GPU nodes are best kept outside it, as ordinary hosts +joined with `node add`. Why, and how, is in [kubernetes.md](kubernetes.md). + ## Upgrading On the control plane: @@ -1389,35 +2357,63 @@ anywhere else.** Restoring an old store restores which keys exist and who owns them, not their secrets. A key created after the backup is gone and has to be reissued. +### Copying archives off the machine + +```yaml +backup_recipients: [age1…] # required: an archive leaves only encrypted +backup_copy_to: + - /mnt/backups/llmgw # a mounted share or another disk + - ssh://backup@10.0.0.20/srv/llmgw-backups +backup_copy_key: /etc/llmgw/secrets/backup-ssh-key +``` + +Each archive is copied there as soon as it is written, and the same number is +kept there as here (`--keep`, 14). An ssh host's key is learnt the first time +and checked every time after, in `/etc/llmgw/backup_known_hosts`. A copy that +fails makes the backup fail, so the timer's unit shows it. + ### Restoring -On a machine with llmgw installed (the same version or newer) and, for -PostgreSQL, an empty database and role as `server init --postgres` would create -them: +On a machine with llmgw installed — the same version as the archive's, or +newer — and, for PostgreSQL, the database and role the store's address names: ``` -sudo systemctl stop llmgw-server -mkdir /tmp/restore && sudo tar -xzf /var/backups/llmgw-server/llmgw-backup--`) //nolint:gosec // escaped, and the scheme is allowlisted + } + return template.HTML(`` + esc(text) + ``) //nolint:gosec // escaped +} + // looksLikeEmail is deliberately crude: it decides whether to add a mailto:, // and being wrong means a link that does not open a mail client rather than // anything worse. diff --git a/internal/web/csp_test.go b/internal/web/csp_test.go index 978d2010..51734602 100644 --- a/internal/web/csp_test.go +++ b/internal/web/csp_test.go @@ -28,7 +28,7 @@ func TestAPageNamesItsInlineScriptsAndNothingElse(t *testing.T) { func TestRenderedPagesCarryThePolicy(t *testing.T) { rec := httptest.NewRecorder() - renderStatus(rec, 401, "login", loginData{Error: "no"}) + renderStatus(rec, nil, 401, "login", loginData{Error: "no"}) if rec.Code != 401 { t.Errorf("status %d", rec.Code) } diff --git a/internal/web/dashboard.go b/internal/web/dashboard.go index 14283a60..e2a02b3b 100644 --- a/internal/web/dashboard.go +++ b/internal/web/dashboard.go @@ -5,6 +5,8 @@ import ( "html/template" "log/slog" "net/http" + "slices" + "strconv" "time" "gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi" @@ -94,8 +96,38 @@ type DashboardData struct { // way to tell that from a bug. Nav NavExtras RefreshSec int - Version string - Now string + // RefreshMeta is the reload for a browser without script. + RefreshMeta template.HTML + Version string + Now string +} + +// stateWords are every state a node, a replica, a shard or an engine's +// installation can be in. Each is a CSS class and a word; the class stays as +// it is and the word is looked up, as dash.state.. A state not listed +// here shows its key, which the catalogue test is there to stop. +var stateWords = []string{ + "ready", "cordoned", "draining", "unreachable", "lost", "unknown", + "placing", "pending", "starting", "loading", "stopped", "failed", + "installing", "unsupported", "skipped", +} + +func init() { + for _, s := range stateWords { + registerKeys("dash.state." + s) + } + // How bad a fabric's or an NVLink domain's problem is. + registerKeys("fabric.level.fail", "fabric.level.warn", "fabric.level.info") +} + +// refreshMeta is the meta element that reloads a page every sec seconds, +// for the