====== gpu-broker ======

//Vytvořeno: **12.11.2026** | Aktualizováno: **~~LASTMOD~~**//

[[https://github.com/emergenthq-net/gpu-broker|gpu-broker]] je broker front a obsazení GPU. Umožňuje, aby se chatovací LLM, model pro obrázky a model pro video střídaly na jedné grafické kartě. Mezi modely přepíná automaticky podle toho, jaké požadavky přicházejí.

Řeší situaci, kdy se LLM a difuzní model nevejdou do VRAM současně. Bez brokera je potřeba ručně zastavit LLM, spustit ComfyUI, vygenerovat obrázek a LLM znovu pustit. Agenti, kteří LLM používají, mezitím stojí.

Podobný problém řeší na úrovni CPU, RAM a disku projekt [[ai:mcp:servery:agent-task-queue|Agent Task Queue]]. Ten řadí do fronty drahé příkazy (buildy, testy), které spouští více AI agentů na jednom stroji.

===== Jak funguje =====

gpu-broker sám žádný model nespouští. Řídí servery, které už běží: llama.cpp, vLLM, Ollama nebo jiný OpenAI-kompatibilní server s ''/health'', a k tomu ComfyUI. Všechny požadavky jdou na jednu adresu, výchozí je ''127.0.0.1:8095''.

Když přijde požadavek na obrázek nebo video, broker:

  - nechá doběhnout rozpracované chatové požadavky,
  - zastaví LLM server,
  - spustí úlohu v ComfyUI,
  - požadavky, které mezitím přijdou, zařadí do fronty,
  - po době klidu ''idle_restore_s'' (ve výchozím katalogu 120 s) vrátí LLM zpátky.

Model se přepíná jen mezi úlohami, nikdy uprostřed úlohy. Před startem LLM musí ComfyUI uvolnit své váhy. Stav serverů broker před přepnutím znovu ověřuje, protože je mohl zastavit i někdo jiný.

==== Plánování fronty ====

  * Interaktivní požadavky (lidé) mají přednost před dávkovou prací agentů. Část souběžných slotů LLM je rezervovaná jen pro ně.
  * Mezi ostatními žadateli jde na řadu ten, kdo zatím spotřeboval nejméně očekávaného času GPU. Pořadí úloh jednoho žadatele se zachovává.
  * Dávková úloha, která čeká déle než ''scheduler.max_wait_s'' (výchozí 3600 s), se počítá jako interaktivní.
  * Nastavení ''scheduler.policy: fifo'' vrací striktní pořadí podle příchodu.

Každá změna stavu se zapisuje do SQLite a do JSONL logu. Příkaz ''gpu-broker replay'' přehraje vlastní log přes pravidla fronty v simulovaném čase. Slouží k měření dopadu změn plánovače.

===== Hlavní funkce =====

  * **Kompatibilní API.** Broker poskytuje OpenAI API (Chat Completions i Responses) a Anthropic API. Open WebUI, oficiální SDK nebo Codex CLI se připojí jen změnou base URL a klíče.
  * **Webový dashboard.** Ukazuje, co je načtené, co běží a co čeká, a také každé přepnutí. Grafy zobrazují VRAM, zátěž, příkon a teplotu karty.
  * **Zapůjčení GPU.** Celou kartu lze dočasně vyhradit pro ruční práci v ComfyUI. Po skončení se vrátí chatovací model.
  * **MCP server.** S doplňkem ''mcp'' broker funguje i jako MCP server. Nabízí nástroje ''generate_image'', ''generate_video'', ''edit_image'', ''image_to_video'', ''make_3d'', ''chat_local'', ''gpu_status'' a další.
  * **Command-line modely.** Programy mimo ComfyUI (například převod obrázku na 3D) spouští podle receptu, který napíše správce hostitele. Požadavek recept jen pojmenuje, příkaz nikdy neposílá.
  * **Cloud first, lokálně při výpadku (volitelné).** Sekce ''upstreams'' pošle požadavky na ''claude-*'' a ''gpt-*'' skutečnému poskytovateli s klíčem klienta. Při výpadku, zaseknutém spojení nebo vyčerpané kvótě odpoví lokální model. Circuit breaker (pojistka, která po zotavení poskytovatele vrátí provoz zpět) pak přepne zpět do cloudu.

Ukázka failover konfigurace podle [[https://github.com/emergenthq-net/gpu-broker/blob/main/docs/failover.md|dokumentace]]:

<code yaml>
upstreams:
  providers:
    anthropic: {url: https://api.anthropic.com, api: anthropic}
    openai:    {url: https://api.openai.com, api: openai}
  routes:                      # vyhrává první odpovídající vzor
    "claude-*": [anthropic, my-local-llm]
    "gpt-*":    [openai, my-local-llm]
    "o3*":      [openai]       # jen cloud: při výpadku OpenAI vrátí 503
</code>

Broker ve výchozím stavu neukládá žádný cloudový klíč. Klíč klienta předá poskytovateli a vlastní klíč brokeru posílá v samostatné hlavičce ''x-gpu-broker-key''.

===== Instalace =====

Je potřeba Python 3.12 nebo novější. Příkaz ''setup'' najde GPU (NVIDIA nebo AMD), běžící modelové servery na obvyklých portech a jejich systemd jednotky nebo Docker kontejnery. Zapíše ''config.yaml'', ''catalog.yaml'' a API token do ''broker.env'', spustí službu a otevře dashboard.

<code bash>
pip install gpu-broker
gpu-broker setup              # nebo nejdřív: gpu-broker setup --dry-run
</code>

Bez GPU lze vyzkoušet demo se simulovanou kartou a simulovanými uživateli. Žádný model se nestahuje:

<code bash>
uvx gpu-broker demo
</code>

Ruční nastavení podporuje tři varianty podle toho, kde běží modelové servery: systemd jednotky na stejném stroji, Docker kontejnery, nebo systemd jednotky v Proxmox LXC. U Proxmoxu broker běží ve vlastním LXC nebo VM a hostitele ovládá přes SSH klíč omezený na jeden skript (forced command).

Ukázka volání API:

<code bash>
T="Authorization: Bearer $BROKER_TOKEN"
curl -s localhost:8095/v1/chat/completions -H "$T" -H 'Content-Type: application/json' \
  -d '{"model":"llama","messages":[{"role":"user","content":"hi"}]}'
curl -s localhost:8095/v1/jobs -H "$T" -H 'Content-Type: application/json' \
  -d '{"model":"wan2.2-5b","prompt":"a fox in snow","wait":true}'
</code>

Příkaz ''gpu-broker connect'' najde na stroji nástroje jako Continue, Cline, Aider, Codex nebo Open WebUI a nasměruje je na broker. ''gpu-broker disconnect'' vrátí původní nastavení ze zálohy. Registraci MCP serveru zvládne ''connect'' i pro Claude Code, Claude Desktop a Codex.

===== Srovnání s llama-swap =====

[[https://github.com/mostlygeek/llama-swap|llama-swap]] přepíná mezi OpenAI-kompatibilními LLM servery. Podle autora gpu-brokeru stačí, když se střídají jen LLM. gpu-broker má smysl, když jedna karta obsluhuje chat i difuzní modely.

^ Vlastnost ^ llama-swap ^ gpu-broker ^
| Přepínání LLM serverů podle požadavku | ano | ano |
| LLM a ComfyUI na jedné GPU | ne | ano |
| Fronta s pozicemi, stavy úloh a logem událostí | ne | ano (SQLite + JSONL) |
| Interaktivní GPU relace pro ComfyUI | ne | ano |
| Kde běží modelové servery | procesy, které sám spouští | systemd, Docker, Proxmox LXC |

===== Bezpečnost =====

  * Bez nastaveného tokenu ''serve'' nespustí. Tajné údaje se čtou z prostředí, ne z konfiguračního souboru.
  * Výchozí bind je ''127.0.0.1''. Pro vystavení do sítě je potřeba TLS před brokerem.
  * Broker ovládá jen jednotky uvedené v katalogu (allowlist) a nic nespouští přes shell.
  * Stahování URL od volajícího je ve výchozím stavu vypnuté (''inputs.allow_urls: false''), aby nevzniklo SSRF.
  * Docker driver potřebuje Docker socket, což je přístup ekvivalentní rootu.

===== Omezení =====

  * Jedna GPU, NVIDIA nebo AMD. Intel ani Apple zatím podporované nejsou. Podpora AMD je testovaná jen na testovacích datech, ne na skutečné kartě.
  * Na kartě je vždy jen jeden model, i když by se vešly dva.
  * Obrázky a video jdou jen přes ComfyUI. Některé šablony potřebují vlastní node packy, které broker neinstaluje.
  * Stažené modely broker do ComfyUI nepropojí. Soubory je potřeba umístit do složek ComfyUI ručně.
  * Jeden sdílený token, žádné uživatelské účty ani rate limity.
  * Projekt je mladý. Repozitář vznikl 1.10.2026; k 12.11.2026 měl 14 commitů a verzi 0.5.0 na PyPI.

===== Související články =====

  * [[ai:mcp:servery:agent-task-queue|Agent Task Queue]] – fronta drahých příkazů pro více AI agentů na jednom stroji.
  * [[ai:lokalni-ai:runtimy:vllm-qwen38-27b-rtx3090|vLLM stack pro Qwen3.8-27B na RTX 3090]] – konkrétní provozní konfigurace inference serveru.

===== Zdroje =====

  * [[https://github.com/emergenthq-net/gpu-broker|gpu-broker – repozitář a dokumentace]]
  * [[https://github.com/emergenthq-net/gpu-broker/blob/main/docs/failover.md|gpu-broker – failover cloud/lokálně]]
  * [[https://pypi.org/project/gpu-broker/|gpu-broker na PyPI]]
  * [[https://github.com/mostlygeek/llama-swap|llama-swap]]