Options de requête

L'Everyware AI API accepte un certain nombre d'en-têtes de requête qui modifient la manière dont une requête individuelle est traitée — sans toucher aux valeurs par défaut de votre compte ni aux paramètres du modèle dans le corps. Ces options s'appliquent par requête, vous pouvez donc les activer uniquement là où elles sont utiles.

Mise en cache des réponses

Le gateway peut mettre en cache les réponses et les rejouer pour des requêtes répétées, évitant un aller-retour vers le modèle et réduisant à la fois le coût et la latence. Il prend en charge deux chemins de recherche :

Correspondance directe (hachage) — rejeu déterministe par correspondance exacte. La requête est normalisée et hachée ; une requête identique est servie instantanément, sans aucun embedding nécessaire.
Correspondance sémantique (similarité) — recherche basée sur les embeddings qui sert une réponse en cache lorsqu'une nouvelle requête est suffisamment proche d'une précédente, même si la formulation diffère.

La mise en cache est activée par requête : envoyez un en-tête x-bf-cache-key pour rattacher une requête à une partition de cache. Sans cet en-tête, la requête contourne entièrement le cache. La clé isole également les entrées les unes des autres — une requête sous une clé ne peut jamais recevoir une réponse mise en cache sous une autre.

Seule la correspondance directe est disponible

Sur l'Everyware AI API, seule la correspondance directe (hachage) est actuellement activée. La correspondance sémantique (similarité) n'est pas encore disponible — une requête identique (normalisée) est nécessaire pour obtenir un cache hit.

En cas de cache miss, le gateway renvoie immédiatement la réponse du modèle et la stocke en arrière-plan, de sorte que la première requête n'est jamais retardée par une écriture dans le cache. Renvoyez la même requête pour observer un cache hit. Les entrées mises en cache expirent après une durée de vie (TTL) et persistent à travers les redémarrages du gateway.

Activer la mise en cache

La mise en cache s'active dès qu'une requête porte un en-tête x-bf-cache-key — aucune étape d'activation distincte n'est nécessaire. Choisissez n'importe quelle chaîne comme clé ; elle définit la partition de cache. Les requêtes identiques sous la même clé touchent le cache, tandis qu'une clé différente maintient les entrées isolées.

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."}]
  }'

Renvoyez la même requête — la deuxième réponse est servie depuis le cache. Pour rattacher une autre fonctionnalité ou un autre tenant de manière distincte, utilisez une clé différente.

Dans opencode, définissez l'en-tête via l'objet options.headers du fournisseur (voir Définir les en-têtes de requête dans opencode) :

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

Référence des en-têtes de cache

Chaque comportement du cache peut être remplacé par requête via des en-têtes. L'en-tête x-bf-cache-key est le seul requis pour engager la mise en cache ; les autres sont des remplacements facultatifs.

En-tête	Clé de contexte (Go)	Valeur	Effet
`x-bf-cache-key`	`CacheKey`	string	Rattache cette requête à une partition de cache. Requis (ou `default_cache_key`) pour engager la mise en cache.
`x-bf-cache-ttl`	`CacheTTLKey`	chaîne de durée ou secondes	Remplace la TTL pour cette requête. Les valeurs invalides sont ignorées.
`x-bf-cache-threshold`	`CacheThresholdKey`	float (0–1)	Remplace le seuil de similarité sémantique. Borné à `[0,1]`.
`x-bf-cache-type`	`CacheTypeKey`	`direct` ou `semantic`	Limite la recherche à un seul chemin.
`x-bf-cache-no-store`	`CacheNoStoreKey`	`true`	Ignore l'écriture de la réponse (sert toujours les cache hits).

Mode direct uniquement

Avec seulement la correspondance directe (hachage) disponible, x-bf-cache-threshold et x-bf-cache-type: semantic n'ont aucun effet — chaque requête utilise la correspondance directe. x-bf-cache-key, x-bf-cache-ttl et x-bf-cache-no-store restent fonctionnels.

Journalisation des requêtes et des réponses

Le gateway enregistre chaque requête LLM et sa réponse sous forme de métadonnées, ce qui permet aux opérateurs de surveiller l'utilisation et de résoudre les problèmes. La journalisation du contenu est généralement désactivée : seules les métadonnées (horodatages, modèle, nombre de tokens, statut) sont conservées — les prompts et les réponses générées ne sont jamais persistés.

Comme couche de sécurité supplémentaire, l'en-tête x-bf-disable-content-logging: true peut être envoyé explicitement. La journalisation du contenu est alors supprimée pour cette requête, même si la configuration globale de journalisation du gateway venait à changer — seules les métadonnées sont stockées.

L'en-tête est propre à chaque requête

L'en-tête n'affecte que la requête sur laquelle il est envoyé. Il ne modifie pas la configuration globale de journalisation du gateway et ne désactive pas la journalisation des métadonnées.

Définir les en-têtes de requête dans opencode

opencode transmet les en-têtes de requête personnalisés via l'objet options.headers du fournisseur. Dans le bloc du fournisseur ew du guide OpenCode, ajoutez une entrée headers à options :

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

Chaque requête qu'opencode envoie via ce fournisseur porte désormais l'en-tête, de sorte que le contenu des messages n'est jamais journalisé pour ce client — même si la configuration globale de journalisation du gateway change. Le même objet headers peut porter d'autres en-têtes du gateway — par exemple x-bf-cache-key pour activer la mise en cache des réponses pour une requête (voir Mise en cache des réponses).