pacod-benchmark

pacod-benchmark misst pacod-gw (Managed- und Proxy-Modus, das minimale Gateway, die Deployment-Varianten) und andere Gateways, in vielen Konfigurationen in einem Lauf. Jede Zelle wird gegen eine Baseline gemessen, die den Mock-Anbieter direkt aufruft; was übrig bleibt, hat das Gateway hinzugefügt. Die Oberfläche schreibt die Suiten, verfolgt die Läufe Sekunde für Sekunde und vergleicht sie; die Berichte gehen in die Konsole des Gateways.

Funktionen

Screenshots

Warum ein Benchmark

Ein Gateway wird an zwei Dingen gemessen: was es jedem Aufruf hinzufügt, und wie es sich verhält, wenn viele Aufrufe gleichzeitig ankommen. Keines davon zeigt sich in einem einzelnen Lasttest mit einer einzigen Einstellung. Den größten Teil der Zeit eines Aufrufs verbraucht der Anbieter; der Anteil des Gateways ist klein, und er ändert sich mit dem Modus, dem Dialekt, dem Cache, dem Audit-Modus, der Last und dem Deployment. pacod-benchmark misst diesen Anteil über all das hinweg in einem Lauf, und jedes Ergebnis sagt, ob es als Kapazität des Gateways gelten kann oder nur als sein Verhalten.

Eigene Last erzeugt es nicht. Die Aufrufe kommen von den Lastagenten von pacod-gw, denselben, die der Tester der Konsole für seine Lasttests nutzt, und die Berichte haben ein Format, das pacod-gw festlegt und prüft. Der Benchmark plant, baut auf, startet die Agenten gemeinsam, summiert ihre Sekunden und sagt, wofür die Zahlen stehen können.

Wie es aufgebaut ist

Browser ──► pacod-caddy ──► bench-ui (SvelteKit, Anmeldung über pacod-id)
                                │ nur serverseitig, mit dem Token der Person
                                ▼
                        bench-api (pacod-bench serve) ──► PostgreSQL "bench"
                          │  Admin-Token     ──► Management-API von pacod-gw (Szene, Live-Zahlen, Berichte)
                          │  Agenten-Token   ──► Lastagenten von pacod-gw ──► das Gateway oder eine externe URL
                          │                                          └─► der Mock, direkt (Baselines)
                          └  Service-Client  ──► pacod-id (Rollen, Feed, Schlüssel)
pacod-bench run (Kommandozeile): derselbe Controller, keine Datenbank, keine Oberfläche, eine Berichtsdatei

• Der Controller ist eine Bibliothek, pacod-bench-engine, ohne Datenbank und ohne Server. Dienst und Kommandozeile führen denselben Code aus.
• Der Dienst, pacod-bench serve, enthält die API, die Warteschlange der Läufe, den Planer und die PostgreSQL-Datenbank bench. Er lauscht nur im internen Netz pacod-admin-net: Nur der Server der Oberfläche ruft ihn auf.
• Die Oberfläche ist ein SvelteKit-Frontend, das die API von seinem Server aus aufruft, mit dem Token der angemeldeten Person. Die Seite eines Laufs folgt ihm live, über einen Strom von Server-Sent Events.
• Die Agenten, der Mock und die Typen des Berichts stammen von pacod-gw, eingebunden bei einem festen Commit. Eine Änderung am Vertrag des Agenten oder des Berichts beginnt in pacod-gw und wird von dort übernommen.

Eine Suite

Eine Suite ist eine Basiskonfiguration und die Achsen, die sie variiert, in YAML oder JSON. Das ist das Beispiel examples/suites/modes.yaml:

name: Managed against proxy mode
description: The same calls in both modes at three load levels, behind the same mock.
base:
  request: { interface: openai, mode: managed, stream: true, prompt_words: 60, max_tokens: 64 }
  mock: { family: openai, delay_ms: 200, chunk_delay_ms: 20, chunks: 20 }
  workspace: { cache: "off", audit: on_request }
  load:
    mode: concurrency
    stages: [{ duration_s: 0, target: 10 }, { duration_s: 60, target: 10 }]
    timeout_s: 120
    warmup_s: 5
axes:
  request.mode: [managed, proxy]
  load.target: [10, 50, 100]

Zwei Modi auf drei Laststufen ergeben sechs Zellen, die drei Laststufen drei Baselines. Was die Konfiguration einer Zelle enthält:

Teil	Felder
request	Die Schnittstelle (OpenAI, Anthropic, Gemini, nativ, Embeddings), Managed- oder Proxy-Modus, gestreamt oder am Stück, Länge des Prompts, max_tokens, HTTP/1.1 oder HTTP/2, weitere Header
mock	Der Dialekt, den das Gateway zum Anbieter hin spricht, und die Latenz des Mocks: vor dem Kopf, zwischen den Chunks, Chunks pro Antwort
workspace	Der Antwort-Cache (off, shadow, enforce), der Audit-Modus, der Responses-Speicher, was bei vollem Nutzungs-Spool geschieht
key	Die Inspektion (full, oder none für das blinde Weiterleiten im Proxy-Modus), die Nutzungsrichtlinie, eine Obergrenze für gleichzeitige Aufrufe
load	Eine geschlossene Schleife von Aufrufern (concurrency) oder eine offene Schleife von Ankünften (rate), ihre Stufen, das Timeout eines Aufrufs, eine Obergrenze für Aufrufe, eine Aufwärmzeit, die nicht in die Zahlen eingeht

Eine Achse benennt ein Feld über seinen Punktpfad; load.target skaliert jede Stufe, sodass eine Rampe auch bei einem anderen Gipfel eine Rampe bleibt. Kombinationen, die nicht laufen können, fallen heraus, und der Plan sagt warum: Der Proxy-Modus braucht den Mock seines eigenen Dialekts, die native Schnittstelle gibt es nur im Managed-Modus, der Cache antwortet nie im Proxy-Modus oder auf Embeddings, und dieselbe Konfiguration zweimal bleibt einmal. Die Reihenfolge grouped hält die Zellen zusammen, die dieselbe Gateway-Konfiguration brauchen, damit das Gateway so selten wie möglich neu lädt; shuffled verteilt sie in einer festen Reihenfolge, damit eine langsame Drift der Maschine nicht mit einer Achse zusammenfällt. Wiederholungen führen jede Konfiguration erneut aus.

Was nur ein Deployment entscheidet (Analysen an oder aus, der Cache-Speicher, das Scale-Layout, das minimale Gateway, die Hardware), ist keine Achse. Jedes solche Deployment wird als eigenes Ziel registriert und bekommt dieselbe Suite. Die Beispiele des Repositorys decken die beiden Modi ab, drei Anbieter-Latenzen (20, 200 und 1.000 ms), den Antwort-Cache, Stufen von Aufrufen pro Sekunde, die Übersetzung zwischen Dialekten und ein externes Ziel. Das vollständige Format steht in docs/suite-format.md.

Ein Lauf, Schritt für Schritt

1. Planen. Die Suite wird für das Ziel ausgerollt. Ein externes Ziel lehnt die Achsen ab, die der Benchmark dort nicht setzen kann (mock, workspace, key). Der Lauf behält seinen Plan, mit Kopien der Suite, des Ziels und der Agenten.
2. Agenten prüfen. Jeder Agent muss antworten, diesen Vertrag sprechen, frei sein und seinen Anteil an jeder Zelle zulassen.
3. Die Szene aufbauen auf einem verwalteten Gateway: seinen Fingerabdruck lesen, die eigenen Mock-Anbieter des Benchmarks anlegen, eine Wegwerf-Organisation bench-<run>, einen Workspace pro Variante mit ausdrücklicher Cache-Bindung, und die Mock-Modelle freigeben. Dann warten, bis jede Instanz des Gateways die Konfiguration übernommen hat.
4. Jede Zelle ausführen. Das Profil des Mocks setzen, falls es sich geändert hat, und den Schlüssel der Zelle anlegen (nur ihr Modus und Modell, gültig bis 15 Minuten nach dem geplanten Ende der Zelle), dann erneut auf die Instanzen warten. Warten, bis die Agenten frei sind, und etwa drei Sekunden lang die laufenden Aufrufe des Gateways beobachten (erwartet werden keine). Alle Agenten zugleich starten. Einmal pro Sekunde die neuen Sekunden jedes Agenten einsammeln, alle zwei Sekunden die eigenen Zahlen des Gateways. Dann die Agenten stoppen, den Schlüssel löschen, zusammenfassen und markieren, was ein Leser wissen sollte.
5. Die Szene abbauen, die Schlüssel zuerst, den Rest vom neuesten zum ältesten. Was sich nicht löschen ließ, wird als Überrest aufgeführt, zum Aufräumen durch einen Admin. Ein Abbruch geht denselben Weg, und hält die API während eines Laufs an, stoppen die Agenten von selbst, und der nächste Start baut ab, was der Lauf angelegt hatte.

Die Baseline-Zellen laufen zuerst: dieselbe Anfrage und Last von denselben Agenten direkt zum Mock, ganz ohne Gateway. Ihr Vergleichsschlüssel umfasst nur, was beim Mock ankommt, sodass sich eine Managed- und eine Proxy-Zelle eine Baseline teilen. Während die Last einer Zelle läuft, wird nichts ins Gateway geschrieben, und die Tests prüfen das.

Die Zahlen lesen

Die Seite eines Laufs zeigt für jede Zelle das stabile Fenster, vom Ende der Aufwärmzeit bis zum Ende der letzten Stufe:

Zahl	Was sie ist
Aufrufe pro Sekunde	Der Mittelwert über das stabile Fenster
Erstes Byte, ganzer Aufruf	Latenz-Perzentile, wie die Agenten sie gesehen haben
Gateway	Die eigene Verzögerung des Gateways (x-gw-delay-ms, bis zum Kopf der Antwort); n/a, wo das Ziel keine sendet
Aufschlag	Die Latenz der Zelle minus die ihrer Baseline: was das Ziel hinzugefügt hat, einschließlich dessen, was die eigene Zahl des Gateways nicht erfasst, etwa das Weiterleiten eines Streams
Markierungen	Ein Agent im Stack des Gateways, mit knapper CPU oder im Verzug; anderer Verkehr am Gateway; eine Konfigurationsänderung während der Zelle; Timeouts; ein kurzes stabiles Fenster

Ein Agent auf der Maschine des Gateways nimmt dem Gateway CPU weg, und das Netz von Docker kostet eigene Zeit. Ein Lauf gilt daher nur dann als Kapazität, wenn jeder Agent als entfernt deklariert ist, keinem die CPU ausging oder er in Verzug geriet, kein anderer Verkehr das Gateway erreichte und das Ziel seinen Mock als seinen eigenen deklariert. Sonst ist es Verhalten, und die Seite des Laufs und sein Bericht sagen das, mit den Gründen. In pacod-demo teilt sich der Agent die Maschine mit dem Gateway, und der Mock bedient auch die Lasttests des Testers; jeder Lauf auf dem Demo-Gateway zeigt also Verhalten.

Der Vergleichsschlüssel einer Zelle ist der SHA-256 ihrer gesamten Konfiguration als kanonisches JSON. Zellen mit demselben Schlüssel hatten dieselbe Konfiguration, in jedem Lauf und auf jedem Ziel. Run again auf einem abgeschlossenen Lauf reiht dessen eigene Kopie der Suite auf demselben Ziel mit denselben Agenten ein, sodass seine Zellen dieselben Schlüssel haben wie die des ersten Laufs.

Ziele und Agenten

Ziel	Was der Benchmark dort tut	Wie es hinzugefügt wird
Ein verwaltetes pacod-gw	Baut die Szene jedes Laufs über die Management-API auf, mit einem Platform-Admin-Token	In der Oberfläche durch einen Admin, mit dem Token; oder aus der Konfiguration (BENCH_GW_ADMIN_URL, BENCH_GW_TARGETS)
Ein externes Ziel	Nichts: Es schickt Aufrufe an eine URL und ein Modell, mit einem Schlüssel, der für jeden Lauf eingefügt wird	In der Oberfläche durch einen Admin

Ein externes Ziel ist nur dann mit einem verwalteten Gateway vergleichbar, wenn es vor demselben Mock mit demselben Profil sitzt, das es deklariert. Ein Ziel, das einen kostenpflichtigen Anbieter erreichen kann, braucht in jeder Zelle eine Obergrenze für Aufrufe und bei jedem Lauf eine Bestätigung der Kosten, und jeder Aufruf wird nur einmal gemacht. Die Prüfung eines Ziels macht einen Aufruf durch es hindurch, mit einer eigenen Probe-Szene, damit ein Mock außerhalb der Egress-Allow-List des Gateways dort auffällt und nicht erst als Lauf voller Fehler.

Die Agenten sind die Lastagenten von pacod-gw, aufgeführt in BENCH_AGENTS oder von einem Admin in der Oberfläche hinzugefügt. Ein Agent führt einen Test zur Zeit aus, sodass Benchmark und Tester der Konsole nie gleichzeitig denselben Agenten belasten; eine Zelle wartet auf einen belegten Agenten und wird dann mit einer Markierung übersprungen.

Wo der Agent läuft	Wie
Im eigenen Stack des Benchmarks	bench-load-agent
In einem pacod-gw-Stack	Dessen gw-load-agent (docker-compose.load.yml)
Auf einer anderen Maschine	deploy/load-agent/ von pacod-gw, gerichtet auf die öffentliche Data Plane des Gateways
Auf Kubernetes	Das Helm-Chart von pacod-gw, loadAgent.enabled

Jeder Agent wird als in_stack, same_host oder remote deklariert, und nur entfernte Agenten können einen Kapazitätslauf machen.

Berichte

Der Bericht eines abgeschlossenen Laufs, pacod-bench-report/1, wird mit dem eigenen Crate von pacod-gw gebaut und mit dessen eigener Validierung geprüft. Er enthält das Ziel; die Fakten des Deployments, jeweils vom Gateway beobachtet oder vom Betreiber deklariert; die Agenten und wo sie standen; Verhalten oder Kapazität und warum; und jede Zelle mit ihren Zahlen, Histogrammen, Sekunden und Markierungen. Er enthält kein Geheimnis, und er nennt, wer den Lauf gemacht hat, nicht wer ihn veröffentlicht hat, sodass ein Download und eine Veröffentlichung derselbe Bericht sind.

• Publish to pacod-gw schickt ihn an die Management-API des Gateways; er erscheint unter Platform → Testing → Benchmarks.
• Download liefert dieselben Bytes, zum Hochladen in jeder pacod-gw-Konsole. Das Gateway behält einen Bericht einmal pro SHA-256, derselbe Bericht zweimal ist also einer.
• pacod-bench validate report.json prüft eine Datei so, wie das Gateway es tut.

Ein Bericht ist höchstens 1 MiB groß: Die Sekunden langer Läufe werden ausgedünnt, die Zahlen und Histogramme nie.

Rollen und Sicherheit

Die Rollen sind die von pacod-id, festgelegt in authz/bench.yaml und bei jedem Start an pacod-id übertragen. Keine Rolle ist implizit: Ein Konto ohne Rolle sieht „no access“.

Rolle	Darf
bench.viewer	Agenten, Ziele, Suiten, Läufe und Ergebnisse lesen; Berichte herunterladen
bench.operator	Dazu Suiten schreiben, Läufe starten und abbrechen, Berichte veröffentlichen
bench.admin	Dazu Gateways, externe Ziele und Agenten hinzufügen, die Laufeinstellungen ändern, Läufe löschen, Überreste aufräumen, Rollen vergeben

Ein Lauf handelt auf einem verwalteten Gateway mit dem Platform-Admin-Token des Benchmarks, nicht mit den Rechten des Aufrufers; die Rollen Operator und Admin sind daher für Menschen, denen man das anvertraut. Das Bedrohungsmodell sagt, was das kostet und was es begrenzt:

• Eine Allow-List. Der Client der Management-API hat eine Methode für jeden Aufruf, den ein Lauf macht, und keine generische. Er löscht nur unterhalb der eigenen Wegwerf-Organisation des Laufs und schreibt Anbieter und Modelle nur unter den Mock-Namen des Benchmarks.
• Versiegelte Tokens. Das Token eines in der Oberfläche hinzugefügten Gateways wird mit einem eigenen Datenschlüssel verschlüsselt (AES-256-GCM), der unter BENCH_KEK verpackt ist, einem Schlüssel aus der Umgebung oder einer Datei, nie aus der Datenbank. Die ID des Ziels und seine Management-API sind in die Verschlüsselung eingebunden: Ein Token, das auf ein anderes Ziel kopiert wird, oder eines, dessen Adresse in der Datenbank geändert wurde, öffnet sich nicht. Keine Antwort, kein Lauf, kein Bericht und kein Log enthält es.
• Außer Reichweite. Die API lauscht nur in pacod-admin-net und wird von Caddy nie veröffentlicht. Das Audit-Log des Gateways nennt den Benchmark bei jeder Änderung, die er macht.
• Schlüssel. Ein eingefügter Schlüssel eines externen Ziels bleibt im Speicher und wird nie geschrieben. Der Wegwerf-Schlüssel einer Zelle erlaubt nur deren Modus und Modell.
• Agenten. Ein Agent vergleicht das Token in konstanter Zeit, und das Token hat mindestens 32 Zeichen. Die API spricht unverschlüsseltes HTTP mit den Agenten; Agenten auf anderen Maschinen brauchen deshalb ein privates Netz oder ein VPN.
• Zeitpläne feuern mit der Autorität ihres Erstellers: Bei jedem Auslösen prüft der Benchmark, ob der Ersteller noch Läufe starten darf, und schaltet den Zeitplan sonst ab.

Die Oberfläche meldet sich als vertraulicher Client von pacod-id mit PKCE an. Die API nimmt nur Tokens für ihre eigene Audience an und lehnt sie ab, wenn ihre Kopie der Rollen älter als eine Minute ist.

Deployment und Betrieb

Dienst	Was
bench-api	pacod-bench serve: die API, die Warteschlange der Läufe und der Planer; Metriken auf Port 9190
bench-ui	Die Oberfläche, hinter Caddy
bench-load-agent, bench-load-mock	Nur im eigenständigen Stack: Lastagent und Mock-Anbieter von pacod-gw
bench-gw-lite	Profil dev-gateway: pacod-gw-lite vor dem Mock, als externes Ziel zu registrieren

docker-compose.yml enthält die eigenen Dienste des Benchmarks; docker-compose.standalone.yml ergänzt seine Kopien der gemeinsamen Komponenten (PostgreSQL, pacod-id, Caddy, Prometheus) sowie einen eigenen Agenten und Mock. Auf einem Laptop startet make dev-up den Stack unter http://localhost:18380 (Anmeldung als admin@pacod-bench.test, Passwort pacod-bench-dev), gerichtet auf einen pacod-gw-Entwicklungsstack auf derselben Maschine. Der Benchmark verwaltet dieses Gateway, sobald er eines seiner Platform-Admin-Tokens hat, eingetragen in der Oberfläche oder in .env.

pacod-demo lädt nur die erste Datei, neben den anderen Produkten, und richtet sie auf das Demo-Gateway, dessen Lastagenten und dessen Mock; die Oberfläche liegt unter bench.demo.pacod.io. Ein eigenes Helm-Chart ist geplant.

Es läuft ein Lauf zur Zeit; die anderen warten in einer Warteschlange, die die Seite Runs umsortiert. Zeitpläne starten eine Suite auf einem verwalteten Gateway in UTC, täglich zu einer Uhrzeit an gewählten Wochentagen oder alle paar Stunden. Ein Auslösen wird übersprungen, solange der vorige Lauf des Zeitplans noch wartet oder läuft, und eines, das um mehr als 15 Minuten verpasst wurde, wird nicht nachgeholt. Die Einstellungen eines Admins können die Grenzen eines Laufs (Zellen, Sekunden, das Warten auf einen belegten Agenten) unter die der Umgebung senken, die standardmäßig 256 Zellen und vier Stunden betragen.

Jeder Dienst schreibt ein Ereignis pro Zeile nach stdout, als JSON oder Text. Das Runbook behandelt die Konfiguration, das Token des Gateways, Ziele, Agenten, das Rotieren von BENCH_KEK und die Fehlersuche.

Die Kommandozeile

pacod-bench run führt eine Suite vom Terminal aus und schreibt ihren Bericht. Die Zieldatei nennt, wo die Geheimnisse liegen, nie die Geheimnisse selbst:

name = "lite on the laptop"
product = "pacod_gw_lite"          # pacod_gw, pacod_gw_lite, third_party
[external]
base_url = "http://127.0.0.1:18381"
model = "openai/gpt-mock"
key_env = "BENCH_TARGET_KEY"
paid = false
mock = { family = "openai", delay_ms = 200, chunk_delay_ms = 20, chunks = 20 }
[declared]
layout = "lite"
arch = "arm64"

Ein verwaltetes Gateway bekommt stattdessen [managed], mit seiner Management-API, der Variable mit seinem Token und dem Mock, wie es ihn erreicht. Strg-C bricht ab, und die Szene wird zuerst abgebaut. scripts/build-binaries.sh baut die Kommandozeile als natives Binary für Linux (statisch) und macOS.

Was getestet ist, und die Grenzen

• Der Controller wird gegen eine Nachbildung der Management-API und einen Agenten im Prozess getestet: Ein verwalteter Lauf baut seine Szene auf, misst und baut sie ab, ohne während der Last einer Zelle etwas zu schreiben; ein externer Lauf baut nichts auf und behält vom Schlüssel nur einen Hinweis; ein belegter Agent stoppt einen Lauf, bevor irgendetwas beginnt.
• Die API wird gegen PostgreSQL getestet: eine Suite von der API bis zu ihrem Ende, ein Abbruch während eines Laufs, ein in der Oberfläche hinzugefügtes Gateway, das sein Token nie zeigt, ein Neustart, der abbaut, was ein unterbrochener Lauf hinterließ, die Warteschlange, die Einstellungen, in der Oberfläche hinzugefügte Agenten und Zeitpläne, die auslösen, veröffentlichen und ein verpasstes Auslösen nie nachholen.
• Die Verträge des Lastagenten und des Berichts werden gegen die eigenen Fixtures von pacod-gw getestet, und make vendor-check lehnt eine Kopie von pacod-gw ab, die nicht von einem Commit stammt.
• In pacod-demo zeigt jeder Lauf auf dem Demo-Gateway Verhalten, nicht Kapazität: Der Agent läuft im Stack des Gateways auf derselben Maschine, und der Mock wird geteilt. Kapazitätszahlen brauchen Agenten auf anderen Maschinen und einen eigenen Mock.
• Das Token eines Laufs ist das eines Platform-Admins: pacod-gw hat dafür noch keine engere Rolle.
• Eine Cache-Zelle misst einen Treffer, keine Mischung aus Treffern und Fehlschüssen: Jeder Aufruf einer Zelle sendet denselben Body.
• Ein eigenes Helm-Chart gibt es noch nicht.

Das Dokument zur Architektur zeigt, wie der Code aufgebaut ist, vom Plan bis zum Bericht.

Schnellstart

Der Stack, neben einem pacod-gw-Entwicklungsstack

make dev-up
open http://localhost:18380

Die Kommandozeile, ohne Docker

make plan SUITE=examples/suites/modes.yaml
cargo run -p pacod-bench -- run --suite examples/suites/modes.yaml --target target.toml --agents local=http://127.0.0.1:18096 --out report.json
cargo run -p pacod-bench -- validate report.json

Funktioniert mit

• pacod-gw: Das Gateway, das es misst. Es steuert die Lastagenten und den Mock von pacod-gw, baut die Szene jedes Laufs über die Management-API auf und veröffentlicht seine Berichte unter Platform → Testing → Benchmarks.
• pacod-id: Die Anmeldung an der Oberfläche läuft über pacod-id, und die API prüft jeden Aufrufer gegen die Rollen aus authz/bench.yaml, die sie bei jedem Start an pacod-id überträgt.
• pacod-demo: Läuft unter bench.demo.pacod.io neben den anderen Produkten, verwaltet das Demo-Gateway mit einem Token, den der Bootstrap erzeugt, und nutzt dessen eigenen Lastagenten und Mock.