Opzioni di richiesta

L'Everyware AI API accetta una serie di intestazioni di richiesta che modificano il modo in cui una singola richiesta viene gestita — senza toccare i valori predefiniti del vostro account o i parametri del modello nel corpo. Queste opzioni vengono applicate per singola richiesta, quindi potete attivarle solo dove sono utili.

Memorizzazione in cache delle risposte

Il gateway può memorizzare in cache le risposte e riprodurle per richieste ripetute, evitando un round-trip verso il modello e riducendo sia i costi sia la latenza. Supporta due percorsi di ricerca:

Corrispondenza diretta (hash) — riproduzione deterministica per corrispondenza esatta. La richiesta viene normalizzata e sottoposta a hash; una richiesta identica viene servita istantaneamente, senza necessità di embedding.
Corrispondenza semantica (similarità) — ricerca basata su embedding che serve una risposta in cache quando una nuova richiesta è sufficientemente simile a una precedente, anche se la formulazione è diversa.

La memorizzazione in cache è attivata per singola richiesta: inviate un'intestazione x-bf-cache-key per associare una richiesta a una partizione della cache. Senza di essa, la richiesta aggira completamente la cache. La chiave isola inoltre le voci l'una dall'altra — una richiesta sotto una chiave non può mai ricevere una risposta memorizzata sotto un'altra.

È disponibile solo la corrispondenza diretta

Sull'Everyware AI API è attualmente attiva solo la corrispondenza diretta (hash). La corrispondenza semantica (similarità) non è ancora disponibile — per un cache hit è necessaria una richiesta identica (normalizzata).

In caso di cache miss, il gateway restituisce immediatamente la risposta del modello e la memorizza in background, così la prima richiesta non viene mai ritardata da una scrittura in cache. Inviate di nuovo la stessa richiesta per osservare un cache hit. Le voci memorizzate scadono dopo un time-to-live (TTL) e persistono attraverso i riavvii del gateway.

Attivare la memorizzazione in cache

La memorizzazione in cache si attiva nel momento in cui una richiesta contiene un'intestazione x-bf-cache-key — non è necessario alcun passaggio di attivazione separato. Scegliete una stringa qualsiasi come chiave; essa definisce la partizione della cache. Le richieste identiche sotto la stessa chiave colpiscono la cache, mentre una chiave diversa mantiene le voci isolate.

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.3-flash",
    "messages": [{"role": "user", "content": "Summarize this in one sentence."}]
  }'

Inviate di nuovo la stessa richiesta — la seconda risposta viene servita dalla cache. Per associare separatamente un'altra funzionalità o un altro tenant, utilizzate una chiave diversa.

In opencode, impostate l'intestazione tramite l'oggetto options.headers del provider (vedere Impostare le intestazioni di richiesta in opencode):

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

Riferimento delle intestazioni di cache

Ogni comportamento della cache può essere sovrascritto per singola richiesta tramite intestazioni. L'intestazione x-bf-cache-key è l'unica necessaria per attivare la memorizzazione in cache; le altre sono sostituzioni facoltative.

Intestazione	Chiave di contesto (Go)	Valore	Effetto
`x-bf-cache-key`	`CacheKey`	string	Associa questa richiesta a una partizione della cache. Necessaria (o `default_cache_key`) per attivare la memorizzazione in cache.
`x-bf-cache-ttl`	`CacheTTLKey`	stringa di durata o secondi	Sostituisce la TTL per questa richiesta. I valori non validi vengono ignorati.
`x-bf-cache-threshold`	`CacheThresholdKey`	float (0–1)	Sostituisce la soglia di similarità semantica. Limitata a `[0,1]`.
`x-bf-cache-type`	`CacheTypeKey`	`direct` o `semantic`	Limita la ricerca a un solo percorso.
`x-bf-cache-no-store`	`CacheNoStoreKey`	`true`	Salta la scrittura della risposta (serve comunque i cache hit).

Modalità solo diretta

Con la sola corrispondenza diretta (hash) disponibile, x-bf-cache-threshold e x-bf-cache-type: semantic non hanno alcun effetto — ogni richiesta utilizza la corrispondenza diretta. x-bf-cache-key, x-bf-cache-ttl e x-bf-cache-no-store restano funzionanti.

Registrazione di richieste e risposte

Il gateway registra ogni richiesta LLM e la relativa risposta come metadati, il che consente agli operatori di monitorare l'utilizzo e risolvere i problemi. La registrazione del contenuto è generalmente disattivata: vengono conservati solo i metadati (timestamp, modello, conteggio dei token, stato) — i prompt e le risposte generate non vengono mai memorizzati.

Come ulteriore livello di sicurezza, l'intestazione x-bf-disable-content-logging: true può essere inviata esplicitamente. La registrazione del contenuto viene quindi soppressa per quella richiesta, anche se la configurazione globale di registrazione del gateway dovesse cambiare — vengono memorizzati solo i metadati.

L'intestazione è per singola richiesta

L'intestazione influisce solo sulla richiesta su cui viene inviata. Non modifica la configurazione globale di registrazione del gateway e non disattiva la registrazione dei metadati.

Impostare le intestazioni di richiesta in opencode

opencode trasmette le intestazioni di richiesta personalizzate tramite l'oggetto options.headers del provider. Nel blocco del provider ew della guida OpenCode, aggiungete una voce headers a options:

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

Ogni richiesta inviata da opencode tramite questo provider contiene ora l'intestazione, quindi il contenuto dei messaggi non viene mai registrato per quel client — anche se la configurazione globale di registrazione del gateway cambia. Lo stesso oggetto headers può contenere altre intestazioni del gateway — ad esempio x-bf-cache-key per attivare la memorizzazione in cache delle risposte per una richiesta (vedere Memorizzazione in cache delle risposte).