Guide d’intégration de l’affinité de canal

Des identifiants stables favorisent la réutilisation des canaux et du cache de contexte dans les conversations continues, les assistants de programmation et les tâches à contexte long.

AGTCloud utilise l’identifiant stable de la requête pour acheminer en priorité les requêtes suivantes vers un canal ayant déjà réussi. Si ce canal devient indisponible, la plateforme en sélectionne automatiquement un autre. Cet identifiant est appelé clé d’affinité.

L’affinité de canal stabilise le routage, tandis que le cache de contexte réutilise les calculs. Un canal stable ne garantit pas que chaque requête soit servie depuis le cache.

Choisir une méthode d’intégration

Privilégiez les champs d’identification déjà prévus par le protocole. Si modifier le corps est difficile, le SDK ou la passerelle peut transmettre un identifiant stable dans un en-tête.

Utiliser x-conversation-id entre protocoles

x-conversation-id transmet un identifiant stable dans un en-tête, sans ajouter de champ d’affinité au corps. Cette méthode s’applique notamment aux protocoles OpenAI, Anthropic et Gemini :

curl 'https://api.agtcloud.ai/v1/chat/completions' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  -H 'x-conversation-id: conversation_3cb9dd9a4819594254a779c90a2171' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "Continuez à analyser ce problème."
      }
    ]
  }'

Cet en-tête sert à l’affinité de canal de la plateforme ; il n’est pas considéré comme un paramètre du modèle par défaut. Gardez la même valeur pendant une conversation continue au lieu de la régénérer à chaque requête.

Remplacez MODEL_ID dans les exemples par l’ID de votre modèle et utilisez une API Key destinée aux appels de modèles.

Intégration par famille de modèles

OpenAI

OpenAI Prompt Caching s’active automatiquement et repose principalement sur des préfixes de requête identiques. Responses et Chat Completions peuvent utiliser prompt_cache_key pour le routage du cache. AGTCloud l’utilise aussi pour l’affinité de canal et le transmet aux fournisseurs amont qui le prennent en charge.

curl 'https://api.agtcloud.ai/v1/responses' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "input": "Poursuivez la tâche en cours.",
    "prompt_cache_key": "project_knowledge_v3"
  }'

La clé peut identifier une conversation, un projet, une version de base de connaissances ou un dépôt. Pour poursuivre une conversation Responses existante, renseignez aussi previous_response_id avec l’ID de la réponse précédente. Ce champ est inutile pour la première requête.

Claude / Anthropic

Claude marque les préfixes réutilisables avec cache_control dans les blocs de contenu et prend aussi en charge le cache automatique des conversations. metadata.user_id peut servir de clé d’affinité ; des clients comme Claude Code envoient souvent déjà ce type d’identifiant stable. Ce n’est pas un point de rupture du cache et il ne remplace pas cache_control.

curl 'https://api.agtcloud.ai/v1/messages' \
  -H 'x-api-key: your-api-key' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "max_tokens": 1024,
    "metadata": {
      "user_id": "conversation_3cb9dd9a4819594254a779c90a2171"
    },
    "system": [
      {
        "type": "text",
        "text": "Placez ici les règles métier et les contraintes d’outils stables.",
        "cache_control": {
          "type": "ephemeral"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Poursuivez l’analyse de ce dépôt."
      }
    ]
  }'

Claude construit les préfixes dans l’ordre tools, system, messages. Modifier les définitions d’outils, system ou les messages mis en cache affecte le niveau concerné et les niveaux suivants. Des TTL courts ou plus longs peuvent être choisis selon les capacités du fournisseur amont.

Gemini

Utilisez x-conversation-id pour maintenir l’affinité de canal, puis choisissez le cache adapté au scénario :

• Cache implicite : Activé par défaut pour Gemini 2.5 et les modèles plus récents ; adapté aux conversations réutilisant un préfixe stable à intervalles rapprochés.
• Cache explicite : Créez une ressource via /v1beta/cachedContents, puis référencez-la avec cachedContent. Il convient aux longs documents, aux longues vidéos, aux bases de connaissances fixes et à l’analyse de dépôts. Le client gère sa création, sa validité et les références ultérieures.

DeepSeek

DeepSeek active automatiquement le cache de contexte sur disque et réutilise les préfixes complets et stables. deepseek-v4-flash et deepseek-v4-pro utilisent user_id pour distinguer les utilisateurs lors des contrôles de sécurité, de la limitation de débit par utilisateur et de l’isolation du K/V Cache.

Les requêtes ayant le même modèle et le même user_id réutilisent de préférence un canal ayant déjà réussi.

curl 'https://api.agtcloud.ai/v1/chat/completions' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "user_id": "user_123",
    "messages": [
      {
        "role": "system",
        "content": "Placez ici les règles métier, les descriptions d’outils ou le résumé de connaissances stables."
      },
      {
        "role": "user",
        "content": "Continuez à analyser ce problème."
      }
    ]
  }'

user_id doit contenir uniquement des caractères ASCII, ne pas dépasser 512 caractères et rester fixe pour un même utilisateur. Sans ID utilisateur, utilisez un identifiant stable généré par l’application. Si le corps ne peut pas être modifié, utilisez la méthode x-conversation-id ci-dessus.

Limites de concurrence par défaut pour chaque user_id :

Si user_id est absent, la plateforme attribue automatiquement un identifiant disponible depuis son pool UID configuré. La requête peut toujours être envoyée normalement.

Consultez usage.prompt_cache_hit_tokens et usage.prompt_cache_miss_tokens dans la réponse pour connaître les nombres de tokens servis depuis le cache et hors cache.

Qwen

Qwen / DashScope propose le cache implicite, le cache explicite et Session Cache. Pour qwen3.6-plus, qwen3.6-flash, qwen3-coder-plus et les modèles similaires, choisissez selon le protocole d’appel :

• Chat Completions : Le cache implicite est automatique. Pour marquer du contenu réutilisable, ajoutez cache_control aux blocs de contenu.
• Responses sur plusieurs tours : Poursuivez la réponse avec previous_response_id et activez Session Cache avec l’en-tête x-dashscope-session-cache: enable.

Les deux méthodes peuvent aussi transmettre x-conversation-id pour maintenir l’affinité de canal. Exemple Chat Completions :

curl 'https://api.agtcloud.ai/v1/chat/completions' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  -H 'x-conversation-id: conversation_3cb9dd9a4819594254a779c90a2171' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "Placez ici un contexte long et stable dépassant le seuil du cache.",
            "cache_control": { "type": "ephemeral" }
          }
        ]
      },
      {
        "role": "user",
        "content": "Répondez à la question à partir du contenu ci-dessus."
      }
    ],
    "stream": false
  }'

GLM / Z.AI

GLM-5, GLM-5.1, GLM-4.7, GLM-4.6 et GLM-4.5 proposent un cache de contexte automatique adapté aux tâches longues, au code et aux agents. Utilisez un x-conversation-id stable pour un même projet ou une même tâche d’agent :

curl 'https://api.agtcloud.ai/v1/chat/completions' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  -H 'x-conversation-id: agent_task_3cb9dd9a4819594254a779c90a2171' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "system",
        "content": "Placez ici les objectifs stables de l’agent, les contraintes d’outils et le contexte du projet."
      },
      {
        "role": "user",
        "content": "Poursuivez avec l’étape suivante."
      }
    ],
    "stream": false
  }'

Consultez usage.prompt_tokens_details.cached_tokens dans la réponse pour observer les tokens mis en cache. Si vous conservez les contenus de raisonnement, préservez aussi l’ordre et le contenu des segments historiques à réutiliser.

Conseils d’utilisation

• Stabiliser les préfixes : Placez les instructions fixes, les définitions d’outils, les longs documents et les résumés d’historique au début ; la question actuelle, l’heure et les journaux temporaires à la fin. Évitez de réordonner les outils, de réécrire un historique inchangé ou d’insérer des valeurs aléatoires.
• Définir la portée des identifiants : Gardez l’ID de conversation fixe dans une conversation et l’ID utilisateur fixe dans la durée pour cet utilisateur. Distinguez les projets et les versions de base de connaissances. Ne mélangez pas les identifiants entre locataires et ne remplacez pas un identifiant devant distinguer les utilisateurs par un identifiant de projet partagé.
• Éviter les données sensibles en clair : N’utilisez ni téléphone, ni adresse e-mail, ni numéro de pièce d’identité, ni API Key comme clé d’affinité. Vous pouvez transformer irréversiblement les identifiants métier. N’utilisez pas de Request ID à usage unique.
• Tenir compte de la validité : La durée du mappage d’affinité est configurée par la plateforme ; il est recommandé de l’aligner sur la fenêtre de cache amont, généralement de 5 minutes à 1 heure. Aucun TTL supplémentaire n’est à ajouter à la requête. Un identifiant inchangé ne prolonge pas le cache amont.

Résolution des problèmes courants

L’absence de données en cache ne suffit pas à prouver un échec de l’affinité de canal. Pour une requête en erreur, consultez Erreurs et dépannage.

Références associées

• OpenAI Prompt Caching
• Claude Prompt Caching
• Gemini Context Caching
• DeepSeek Context Caching
• Qwen Context Cache
• GLM / Z.AI Context Caching