Fiche aide-mémoire ColdFusion AI

La règle principale

Le LLM n'est pas votre application. C'est un moteur de raisonnement que votre application ColdFusion supervise. ColdFusion conserve toujours :

• l'authentification
• l'autorisation
• la validation
• les règles d'affaires
• l'accès à la base de données
• la consignation
• la gestion des erreurs
• l'encodage de la sortie
• la sécurité

Aperçu de la pile

ChatModel()

Utilisez ChatModel() pour des appels d'IA simples et sans état. Bon pour :

• résumer
• réécrire
• traduire
• classifier
• rédiger
• expliquer
• extraire

Pas bon pour :

• se souvenir des conversations
• vérifier les autorisations
• interroger des données en direct de l'application
• chercher dans des documents privés
• effectuer des actions
• faire respecter les règles d'affaires

Structure de base :

<cfscript>
	chatModel = ChatModel( {
		provider : "openAI",
		modelName : "gpt-5-nano",
		apiKey : application.aiApiKey,
		temperature : 0.3,
		maxTokens : 500,
		timeout : 30
	} );

	response = chatModel.chat(
		"Summarize this support request in one sentence."
	);

	writeOutput( encodeForHtml( response.message ) );
</cfscript>

Rappels sur ChatModel()

À faire :

• définir un délai d'attente
• définir maxTokens
• utiliser une température plus basse pour les tâches factuelles
• encoder la sortie avant l'affichage
• valider le JSON ou la sortie structurée
• garder les clés API hors du contrôle de source

À ne pas faire :

• faire confiance à la sortie du modèle comme HTML
• supposer un JSON valide
• s'attendre à une mémoire
• le laisser prendre des décisions d'autorisation
• l'utiliser comme logique de votre application

Agent()

Utilisez Agent() lorsque l'interaction avec l'IA nécessite plus de structure. Bon pour :

• conversations à plusieurs tours
• instructions système
• mémoire
• contexte propre à l'utilisateur
• demandes d'outils
• flux de travail de type assistant

Modèle mental :

• ChatModel() : la connexion au modèle.
• Agent() : l'enveloppe d'assistant autour du modèle.

Utilisez Agent() lorsque l'interaction est plus que - "Invite en entrée, réponse en sortie."

Mémoire

La mémoire sert au contexte récent de la conversation. Ce n'est pas un stockage permanent. Ce n'est pas une autorisation. Ce n'est pas une vérité.

Mémoire de fenêtre de messages

Conserve les N derniers messages.

CHATMEMORY : {
	TYPE : "messageWindowChatMemory",
	MAXMESSAGES : 20,
	PERUSER : true
}

À utiliser lorsque :

• les messages ont une longueur normale
• vous voulez une configuration simple par défaut
• le nombre prévisible de messages est important

Mémoire de fenêtre de jetons

Conserve autant d'historique que possible dans la limite d'un nombre de jetons.

CHATMEMORY : {
	TYPE : "tokenWindowChatMemory",
	MAXTOKENS : 4000,
	PERUSER : true
}

À utiliser lorsque :

• les utilisateurs collent du contenu long
• le budget de jetons est important
• le nombre de messages ne suffit pas

Règle de clé de mémoire

Utilisez une vraie clé de mémoire par utilisateur.

memoryKey = "tenant-" & session.tenantId & ":user-" & session.userId;

Pour des conversations distinctes :

memoryKey = "tenant-" & session.tenantId
	& ":user-" & session.userId
	& ":conversation-" & session.aiConversationId;

Préférences

Les préférences sont des données applicatives durables. Mémoire :

The user just asked about invoice INV-123.

Préférence :

The user prefers concise CFScript examples.

Stockez les préférences dans votre base de données. Injectez-les intentionnellement dans les invites ou les messages système. Ne comptez pas sur les fenêtres de mémoire pour conserver les préférences à jamais.

Outils CFC

Utilisez les outils CFC lorsque l'assistant a besoin d'un accès contrôlé à votre application. Bon pour :

• vérifier l'état d'un billet
• lister les événements à venir
• calculer des totaux
• valider des coupons
• créer des brouillons
• vérifier l'admissibilité

Mauvais pour :

• du SQL arbitraire
• des méthodes larges qui font "tout"
• les décisions d'autorisation
• exposer des couches de service brutes
• les actions destructrices sans confirmation

Enregistrement des outils

Exposez des méthodes précises.

TOOLS : [
	{
		CFC : "tools.SupportTool",
		METHODS : [
			{
				METHOD : "getTicketStatus",
				DESCRIPTION : "Get the current status of a support ticket by ticket ID. Use this when the user asks about the progress, state, or status of an existing support ticket."
			}
		]
	}
]

Les descriptions comptent. Le modèle les utilise pour décider quand demander l'outil.

Liste de vérification pour l'exécution d'outils

Avant d'exécuter une demande d'outil :

• confirmer que l'outil est sur la liste autorisée
• valider tous les arguments
• injecter le contexte utilisateur depuis ColdFusion
• appliquer l'autorisation à l'intérieur de l'outil ou du service
• ne retourner que les données requises
• consigner l'action de façon sécuritaire
• exiger une confirmation pour les écritures à risque

Ne laissez jamais le modèle fournir :

• userId
• tenantId
• accountId
• le rôle
• le niveau d'autorisation
• le statut de propriété

Outils de lecture vs outils d'écriture

Commencez par les outils de lecture. Les outils de lecture :

• obtiennent l'état
• listent les enregistrements
• calculent les totaux
• vérifient la disponibilité

Les outils d'écriture :

• créent des enregistrements
• envoient des courriels
• émettent des remboursements
• annulent des inscriptions
• mettent à jour des comptes
• suppriment des données

Les outils d'écriture ont besoin de :

• l'authentification
• l'autorisation
• la validation
• la confirmation
• la consignation d'audit
• une gestion sécuritaire des erreurs
• de l'idempotence lorsque c'est approprié

Le modèle ne devrait pas modifier la production simplement parce qu'il semblait sûr de lui.

MCP

Utilisez MCP lorsque des outils, des invites ou des ressources doivent franchir des frontières entre systèmes. Utilisez des outils CFC lorsque la capacité se trouve dans votre application. Utilisez MCP lorsque :

• les outils se trouvent à l'extérieur de votre application
• plusieurs applications ont besoin d'outils partagés
• les ressources ont besoin d'un accès standardisé
• les invites doivent être partagées
• les intégrations ont besoin d'une gouvernance
• la vérifiabilité est importante

Modèle mental :

• Outils CFC : l'assistant utilise votre application.
• MCP : l'assistant se connecte à un écosystème.

Termes MCP

ColdFusion peut agir comme client, serveur ou les deux.

Rappels MCP

À faire :

• se connecter uniquement à des serveurs de confiance
• mettre les outils sur la liste autorisée
• valider les arguments
• authentifier les appelants
• autoriser les ressources
• filtrer les données retournées
• consigner les appels

À ne pas faire :

• exposer chaque CFC
• exposer des fichiers arbitraires
• faire aveuglément confiance aux outils distants
• ignorer les limites entre locataires
• considérer MCP comme un modèle de sécurité

RAG

Utilisez RAG lorsque la réponse se trouve dans des documents. C'est utile pour :

• les FAQ
• les documents de politique
• les manuels
• les bases de connaissances
• la documentation d'API
• les guides d'intégration
• les articles de soutien

Utilisez des outils lorsque la réponse se trouve dans l'état de l'application.

• « Que dit la politique de remboursement ? » RAG.
• « Suis-je admissible à un remboursement ? » Outils plus RAG.
• « Quel est l'état de ma commande ? » Outil.
• « Que dit le guide de l'API à propos des limites de débit ? » RAG.

Flux RAG

Ingestion :

Load documents.
Split into chunks.
Generate embeddings.
Store chunks and vectors.

Récupération :

User asks a question.
Question is embedded.
Similar chunks are retrieved.
Model answers using retrieved context.

RAG ne forme pas le modèle. Il fournit le contexte au moment de l'exécution.

Paramètres RAG

Commencez avec les valeurs par défaut. Posez de vraies questions. Inspectez les segments récupérés. Ajustez en fonction des mauvaises réponses. Le débogage de RAG est généralement un débogage de la récupération.

Rappels de production pour RAG

À faire :

• utiliser des banques vectorielles persistantes
• limiter les documents par locataire, utilisateur ou rôle
• suivre l'état de l'ingestion
• réindexer les documents modifiés
• supprimer les segments obsolètes
• inspecter les segments récupérés
• dire au modèle de ne pas deviner
• inclure des références aux sources lorsque c'est utile

À ne pas faire :

• indexer tout
• ignorer les autorisations
• faire confiance à du contenu obsolète
• utiliser des banques vectorielles en mémoire en production
• supposer que RAG élimine les hallucinations
• appeler base de connaissances un dossier mal organisé

Garde-fous

Utilisez des garde-fous pour valider, masquer, bloquer ou faire échouer de façon sécuritaire les entrées et les sorties de l'IA.

Ils répondent à deux questions :

Before we send this to the model, should we?

Before we show this to the user, should we?

Types de résultats des garde-fous

Utilisez :

• successWith pour le masquage
• failure pour les problèmes de validation normaux
• fatal pour les secrets, les tentatives de contournement ou les demandes dangereuses

Exemples de garde-fous

Garde-fous d'entrée :

• rejeter les requêtes vides
• rejeter les requêtes trop volumineuses
• masquer les valeurs semblables à des cartes de paiement
• bloquer les schémas d'injection de prompt
• bloquer les secrets ou les clés privées
• restreindre les sujets
• faire respecter la portée de la fonctionnalité

Garde-fous de sortie :

• bloquer la fuite du prompt système
• bloquer les détails internes de mise en oeuvre
• valider le JSON
• masquer la sortie sensible
• exiger un soutien par une source RAG
• empêcher les résultats d'outils d'exposer des identifiants internes

Garde-fous opérationnels :

• consigner des codes de raison sûrs
• afficher des messages sûrs pour l'utilisateur
• tester les cas normaux et malveillants
• ajuster selon l'utilisation réelle

Température

Utilisez une température plus basse pour :

• la classification
• les explications factuelles
• la sortie structurée
• la synthèse
• les réponses de soutien
• les réponses RAG

Utilisez une température plus élevée pour :

• la remue-méninges
• la dénomination
• la rédaction créative
• les reformulations
• les brouillons marketing

Liste de vérification du prompt

Un bon prompt comprend généralement :

• la tâche
• le public
• le format
• les contraintes
• la source de vérité
• des exemples, au besoin
• ce qu'il ne faut pas faire

Faible :

Explain ColdFusion.

Meilleur :

Explain ColdFusion session scope to an experienced web developer who is new to CFML. Keep it under 120 words and include one practical use case.

Pour RAG :

Answer only using the retrieved context. If the answer is not present in the retrieved context, say you could not find it in the knowledge base. Do not invent policies, dates, prices, or eligibility rules.

Pour les outils :

Use tools when current application data is required. Do not guess ticket status, order status, registration state, permissions, or account details.

Gestion de la sortie

Texte brut :

writeOutput( encodeForHtml( response.message ) );

HTML :

Sanitize before display.

JSON :

Parse it.
Validate it.
Reject invalid structures.

Automatisation :

Validate it.
Log it.
Require confirmation when risky.

Résultats d'outils :

Filter internal fields before the model sees them.

Réponses RAG :

Prefer source references.
Do not allow unsupported claims.

Journalisation

Consignez suffisamment pour déboguer. Ne consignez pas assez pour créer une deuxième brèche de données. Métadonnées utiles :

• nom de la fonctionnalité
• fournisseur
• nom du modèle
• ID de requête
• ID utilisateur
• ID de locataire/de compte
• latence
• réussite/échec
• code d'erreur
• nom de l'outil
• résultat du garde-fou
• utilisation des jetons, si disponible

Faites attention à :

• les prompts complets
• les réponses complètes
• les secrets
• les données personnelles
• les données de paiement
• les documents privés
• les résultats bruts des outils

Règles de sécurité

Ne laissez jamais le modèle décider :

• l'identité de l'utilisateur
• le locataire
• le rôle
• les permissions
• la propriété
• l'état du paiement
• l'état du compte
• l'autorisation
• si une action destructive est permise

Validez toujours :

• l'entrée de l'utilisateur
• la sortie du modèle
• les arguments des outils
• les réponses MCP
• la portée de récupération RAG
• les structures JSON
• les actions d'écriture

Encodez ou assainissez toujours la sortie avant l'affichage. Exigez toujours une confirmation avant les écritures risquées.

Bonnes premières fonctionnalités IA

Commencez par :

• résumer une demande de soutien
• réécrire une annonce
• suggérer des métadonnées SEO
• classer un message
• expliquer une erreur de validation
• répondre à partir d'une petite FAQ
• vérifier l'état au moyen d'un outil en lecture seule
• générer un brouillon pour examen humain

Évitez de commencer par :

• les remboursements
• les changements d'autorisations
• les courriels automatiques
• la suppression de dossiers
• les mises à jour de facturation
• les journaux internes
• tous les documents privés
• le SQL arbitraire
• les décisions juridiques, financières ou médicales

Guide de décision

• Besoin d'une seule réponse simple ? Utilisez ChatModel().
• Besoin du contexte de la conversation ? Utilisez Agent() avec mémoire.
• Besoin de préférences durables de l'utilisateur ? Stockez les préférences dans votre application.
• Besoin de données actuelles de l'application ? Utilisez les outils CFC.
• Besoin d'outils ou de ressources externes/partagés ? Utilisez MCP.
• Besoin de réponses à partir de documents ? Utilisez RAG.
• Besoin de vérifications de sécurité ? Utilisez des garde-fous.
• Vous modifiez des données ? Exigez une autorisation, une validation, une confirmation et une journalisation.

Rappel final

Utilisez la couche la plus simple qui résout le problème. Ajoutez de la mémoire lorsque la conversation compte. Ajoutez des outils lorsque les données de l'application comptent. Ajoutez MCP lorsque les frontières du système comptent. Ajoutez RAG lorsque les documents comptent. Ajoutez des garde-fous parce qu'il y a des utilisateurs.

Le robot peut aider.

ColdFusion continue de mener la danse.