Documentation

Profils de modèles, contexte et Extra JSON

Ce que définit un profil

Dans Sapphire I.C.D.S., le modèle décrit les capacités techniques, tandis que le profil fixe les règles de leur utilisation. Il est par exemple possible de créer pour un même modèle un profil d'assistance strict, un profil de classification concis et un profil d'analyse étendu. Chacun possède sa propre instruction système, sa longueur de réponse et son budget de contexte, mais tous doivent rester dans les limites du même modèle enregistré.

Dans la section AI Settings → Profiles, sélectionnez le fournisseur et le modèle. Ils doivent correspondre : un profil ne peut pas être associé au modèle d'un autre fournisseur. Profile key est un identifiant machine stable, par exemple support_ru. N'utilisez ni le nom d'un employé ni un numéro de tâche temporaire. Un profil activé peut être sélectionné ; le profil par défaut est utilisé lorsque le client n'indique aucun enregistrement précis. Ne le désignez comme default qu'après vérification.

Instruction système et format de réponse

System prompt définit le rôle et les règles permanentes du mode choisi. Rédigez-le comme un contrat vérifiable : périmètre des tâches, langue, format du résultat, restrictions et critère d'achèvement. N'y placez pas de clés d'API, de données personnelles, le contenu intégral de la base de connaissances ou des instructions que l'opérateur doit modifier à chaque requête.

Au démarrage, le système commence par l'instruction système du profil et ajoute les instructions de gestion activées comme politique d'entreprise obligatoire. L'historique de la session et son résumé restent des données. La mémoire et la base de connaissances ne sont pas chargées intégralement dans le prompt : le modèle les obtient à la demande grâce aux outils autorisés. L'allongement du system prompt ne remplace donc pas la configuration des instructions, de la mémoire, des connaissances et des droits d'outils.

Définissez Response format uniquement sous une forme comprise par l'adaptateur et le modèle choisis. Pour une conversation ordinaire, une réponse textuelle constitue un point de départ sûr. Si un JSON structuré est nécessaire, vérifiez d'abord sa prise en charge par le modèle et par le consommateur : une chaîne dans le profil ne garantit pas à elle seule le respect de votre schéma métier.

Reasoning, Temperature et Top P

N'utilisez Reasoning effort qu'avec les modèles qui documentent ce mode. Ne copiez pas une valeur issue d'une autre famille. Temperature et Top P disposent d'interrupteurs distincts. Lorsqu'un paramètre est désactivé, le profil ne doit pas l'imposer au fournisseur ; cela vaut mieux que de transmettre accidentellement une valeur nulle. Il suffit généralement de piloter une méthode de variabilité et de laisser l'autre désactivée. Pour l'extraction de faits et la classification, on choisit des réglages plus stables ; pour produire des variantes, des réglages plus libres, mais la plage exacte doit toujours être vérifiée dans la documentation du modèle.

Calcul du contexte

L'enregistrement du modèle comporte trois plafonds : contexte total, entrée maximale et sortie maximale. Le profil définit quatre valeurs opérationnelles. Max output tokens limite une réponse. Active context tokens est le budget que l'agent est autorisé à utiliser. Compaction reserve tokens est la part de ce budget réservée à un compactage sûr. Le seuil automatique est égal à :

active_context_tokens - compaction_reserve_tokens

La réserve doit être positive et strictement inférieure au budget actif. Le budget actif ne peut dépasser l'entrée maximale du modèle, la limite de réponse ne peut dépasser la sortie maximale, et leur somme ne peut dépasser le contexte total. Par exemple, avec un contexte de 128000, une entrée de 120000 et une sortie de 8192, il est possible de définir un budget actif de 64000, une réserve de 16000 et une réponse de 4096. Le seuil de compactage sera de 48000. Il s'agit uniquement d'un exemple arithmétique, pas d'une recommandation universelle pour tous les modèles.

Maximum agent rounds limite le nombre de cycles modèle-outil, et Maximum agent runtime le temps total en secondes. La valeur 0 signifie que ce plafond précis du profil est absent, mais elle n'annule ni les limites du fournisseur, ni l'annulation par l'utilisateur, ni la protection contre l'absence de progrès, ni les restrictions système. Pour un scénario critique ou coûteux, définissez des valeurs finies explicites et mesurez le fonctionnement réel avant de les augmenter.

Streaming et changement de modèle

L'interrupteur de streaming détermine le mode de remise de réponse privilégié. Il ne transforme pas une API synchrone en flux si le fournisseur ne le prend pas en charge. Lors d'un changement de modèle, créez un nouveau profil ou recalculez soigneusement tous les budgets. L'état de compactage associé à une paire fournisseur-modèle ne peut pas être considéré comme transférable à une autre paire.

Extra JSON sans surprise cachée

Extra JSON est un objet JSON facultatif destiné aux paramètres supplémentaires documentés par un fournisseur donné. C'est une extension, pas un second profil. Commencez par un objet vide :

{}

Si l'API exige réellement une option supplémentaire, ajoutez uniquement celle-ci. Exemple neutre de forme :

{
  "metadata": {
    "integration": "sapphire-docs"
  }
}

L'exemple n'est valable que si l'API choisie prend en charge le champ metadata. Le JSON doit être un objet avec des guillemets doubles, sans commentaires ni virgule finale. N'y placez pas de secret, Authorization, base URL, model key, identifiants utilisateur ou contenu confidentiel.

Ne dupliquez pas dans Extra JSON les champs principaux de la requête tels que le modèle, les outils, le choix d'outil, les messages d'entrée, temperature, Top P ou max output tokens. Un conflit complique le diagnostic et peut modifier le comportement après une mise à jour de l'adaptateur. Le champ enable_tools ne permet pas de contourner la gestion des outils, et une configuration arbitraire ne doit pas remplacer la politique de contexte administrée. Les outils sont autorisés par le catalogue du serveur, les droits du groupe et la sélection de la session.

Vérification du profil

Enregistrez le profil activé, mais ne le désignez pas comme profil par défaut.
Créez une nouvelle session et sélectionnez explicitement le profil.
Vérifiez une réponse courte, l'instruction système et le format annoncé.
Effectuez un test long en observant le seuil de contexte et le compactage.
Vérifiez l'arrêt selon le nombre de cycles et le temps si les limites ne sont pas nulles.
Ajoutez les clés d'Extra JSON une par une et répétez le test.
Ne désignez le profil comme default qu'après ces étapes.

Si la requête est rejetée, videz d'abord Extra JSON, désactivez les paramètres facultatifs de sampling et recommencez le test minimal. Vérifiez ensuite les limites et la prise en charge de reasoning/response format. Cet ordre distingue une erreur d'enregistrement de base d'une option supplémentaire incompatible.

Choix de la taille du budget

Ne commencez pas par le maximum du modèle, mais par un scénario de travail mesuré. Évaluez la longueur de l'instruction système, l'historique habituel, les résultats d'outils attendus et la marge nécessaire à la réponse. Un active context trop grand augmente le coût et le temps de traitement ; un budget trop petit entraîne des compactages fréquents. La réserve doit permettre de produire un résumé correct avant d'atteindre la limite stricte et ne peut donc pas être réduite à une valeur symbolique.

Séparez les profils des différentes tâches lorsque leurs exigences de longueur, de reasoning ou de temps diffèrent. Un profil « universel » unique est plus difficile à tester et à modifier sans risque. Consignez l'objectif du profil dans le nom et la description de la procédure de travail, mais n'intégrez ni le routage ni les droits dans le system prompt : la sélection du profil et l'autorisation des outils sont contrôlées par d'autres couches.