Request-Optionen

Das LLMaaS-Gateway akzeptiert eine Reihe von Request-Headern, die das Verhalten eines einzelnen Requests steuern — ohne die Account-Defaults oder die Modellparameter im Body zu berühren. Diese Optionen gelten pro Request, so dass Sie nur dort opt-in können, wo sie helfen.

Response-Caching

Das Gateway kann Responses cachen und für wiederholte Requests aus dem Cache ausliefern, wodurch ein Roundtrip zum Modell entfällt und sowohl Kosten als auch Latenz sinken. Es unterstützt zwei Lookup-Pfade:

Direct (Hash) Matching — deterministisches, exaktes Replay. Der Request wird normalisiert und gehasht; ein identischer Request wird sofort ausgeliefert, ohne Embeddings.
Semantic (Similarity) Matching — embedding-basiertes Lookup, das eine gecachte Antwort ausliefert, wenn ein neuer Request einem früheren ähnlich genug ist, auch wenn der Wortlaut abweicht.

Caching ist pro Request opt-in: Senden Sie einen x-bf-cache-key-Header, um einen Request einer Cache-Partition zuzuordnen. Ohne diesen Header umgeht der Request den Cache komplett. Der Key isoliert Entries zudem voneinander — ein Request unter einem Key kann nie eine Response ausliefern, die unter einem anderen Key gecacht wurde.

Nur Direct Matching verfügbar

Auf dem LLMaaS-Gateway ist aktuell nur Direct (Hash) Matching aktiviert. Semantic (Similarity) Matching steht noch nicht zur Verfügung — für einen Cache-Hit ist ein identischer (normalisierter) Request erforderlich.

Bei einem Cache-Miss liefert das Gateway die Modell-Response sofort zurück und speichert sie im Hintergrund, so dass der erste Request nie durch einen Cache-Write blockiert wird. Senden Sie denselben Request erneut, um einen Hit zu sehen. Gecachte Entries verfallen nach einer Time-to-Live (TTL) und bleiben über Gateway-Restarts hinweg erhalten.

Caching aktivieren

Caching wird aktiviert, sobald ein Request einen x-bf-cache-key-Header trägt — ein separater Aktivierungsschritt ist nicht erforderlich. Wählen Sie eine beliebige Zeichenkette als Key; er definiert die Cache-Partition. Identische Requests unter demselben Key treffen den Cache, während ein anderer Key die Entries getrennt hält.

curl https://ai.ewcs.ch/v1/chat/completions \
  -H "Authorization: Bearer sk-bf-..." \
  -H "Content-Type: application/json" \
  -H "x-bf-cache-key: my-feature" \
  -d '{
    "model": "ew/glm-5.2",
    "messages": [{"role": "user", "content": "Fasse dies in einem Satz zusammen."}]
  }'

Senden Sie denselben Request erneut — die zweite Response wird aus dem Cache ausgeliefert. Um ein anderes Feature oder einen anderen Tenant separat zu führen, verwenden Sie einen anderen Key.

In opencode setzen Sie den Header über das options.headers-Objekt des Providers (siehe Request-Header in opencode setzen):

"headers": {
  "x-bf-cache-key": "opencode"
}

Cache-Header-Referenz

Jedes Cache-Verhalten lässt sich pro Request über Header überschreiben. Der x-bf-cache-key-Header ist der einzige, der zum Aktivieren des Caching zwingend erforderlich ist; die übrigen sind optionale Overrides.

Header	Context-Key (Go)	Wert	Wirkung
`x-bf-cache-key`	`CacheKey`	String	Ordnet diesen Request einer Cache-Partition zu. Erforderlich (oder `default_cache_key`), damit Caching greift.
`x-bf-cache-ttl`	`CacheTTLKey`	Duration-String oder Sekunden	Überschreibt die TTL für diesen Request. Ungültige Werte werden ignoriert.
`x-bf-cache-threshold`	`CacheThresholdKey`	Float (0–1)	Überschreibt den Schwellwert für die semantische Ähnlichkeit. Auf `[0,1]` begrenzt.
`x-bf-cache-type`	`CacheTypeKey`	`direct` oder `semantic`	Beschränkt das Lookup auf einen Pfad.
`x-bf-cache-no-store`	`CacheNoStoreKey`	`true`	Response nicht speichern (Cache-Treffer werden weiterhin ausgeliefert).

Direct-Only-Modus

Da ausschliesslich Direct (Hash) Matching verfügbar ist, haben x-bf-cache-threshold und x-bf-cache-type: semantic keine Wirkung — jeder Request nutzt Direct Matching. x-bf-cache-key, x-bf-cache-ttl und x-bf-cache-no-store bleiben funktional.

Request- & Response-Logging

Das Gateway protokolliert jeden LLM-Request und die dazugehörige Response, was Operatoren erlaubt, Traffic zu inspizieren, Probleme zu analysieren und die Nutzung zu überwachen. Log-Einträge werden für eine begrenzte Zeit aufbewahrt und sind für Plattform-Operatoren einsehbar.

Standardmässig wird der vollständige Nachrichteninhalt (Prompts und generierte Responses) zusammen mit Metadaten erfasst. Enthält ein Request sensible Daten und soll dessen Inhalt nicht gespeichert werden, können Sie das Content-Logging für genau diesen Request deaktivieren, indem Sie den Header x-bf-disable-content-logging: true mitsenden. Es werden dann nur Metadaten (Zeitstempel, Modell, Token-Counts, Status) behalten — der Nachrichteninhalt wird nicht gespeichert.

Header gilt pro Request

Der Header wirkt ausschliesslich auf den Request, mit dem er gesendet wird. Er ändert weder die globale Logging-Konfiguration des Gateways noch deaktiviert er das Logging von Metadaten.

Request-Header in opencode setzen

opencode reicht Custom-Request-Header über das options.headers-Objekt des Providers weiter. Fügen Sie im ew-Provider-Block aus dem OpenCode-Guide einen headers-Eintrag zu options hinzu:

"options": {
  "baseURL": "https://ai.ewcs.ch/v1",
  "apiKey": "{file:~/.config/opencode/ew-key}",
  "headers": {
    "x-bf-disable-content-logging": "true"
  }
}

Jeder Request, den opencode über diesen Provider sendet, trägt nun den Header, so dass das Content-Logging für diesen Client unterdrückt wird. Dasselbe headers-Objekt kann weitere Gateway-Header aufnehmen — beispielsweise x-bf-cache-key, um einen Request ins Response-Caching aufzunehmen (siehe Response-Caching).