Documentation Cloudflare AI Search

Vue d'ensemble

Le widget conversationnel MrTopic utilise Cloudflare AI Search (AutoRAG) pour fournir des réponses intelligentes basées sur vos documents. Cette technologie combine la recherche sémantique et la génération de réponses pour créer une expérience conversationnelle naturelle.

Fonctionnalités clés

  • Recherche sémantique dans vos documents
  • Génération de réponses contextuelles
  • Historique de conversation systématique (question précédente toujours incluse)
  • Configuration multi-site
  • Protection par domaine autorisé
  • Streaming des réponses en temps réel

Variables d'environnement

Configuration par défaut

Pour un site unique, configurez ces variables dans votre projet Vercel :

CLOUDFLARE_ACCOUNT_ID=votre-account-id
CLOUDFLARE_API_TOKEN=votre-api-token
CLOUDFLARE_RAG_ID=votre-rag-id
ALLOWED_DOMAINS=monsite.com,www.monsite.com

Configuration multi-site

Pour gérer plusieurs sites avec des configurations Cloudflare différentes, utilisez le préfixe SITENAME_ :

# Site 1
SITE1_CLOUDFLARE_ACCOUNT_ID=account-id-1
SITE1_CLOUDFLARE_API_TOKEN=token-1
SITE1_CLOUDFLARE_RAG_ID=rag-id-1
SITE1_ALLOWED_DOMAINS=site1.com
# Site 2
SITE2_CLOUDFLARE_ACCOUNT_ID=account-id-2
SITE2_CLOUDFLARE_API_TOKEN=token-2
SITE2_CLOUDFLARE_RAG_ID=rag-id-2
SITE2_ALLOWED_DOMAINS=site2.com,www.site2.com

Comment obtenir ces valeurs ?

  1. Account ID : Visible dans le dashboard Cloudflare (URL ou section Account)
  2. API Token : Créez un token avec les permissions AutoRAG dans Profile → API Tokens
  3. RAG ID : ID de votre instance AutoRAG créée dans Cloudflare AI

Architecture et flux de données

Flux de requête

  1. Client : L'utilisateur pose une question dans le widget
  2. Historique de conversation : Le système inclut systématiquement la question précédente (et sa réponse) dans le contexte envoyé à l'API
  3. Validation de l'origine : Le serveur vérifie que le domaine est autorisé
  4. Récupération de la config : Le serveur charge la configuration Cloudflare pour le site
  5. Enrichissement de la requête : Si un historique est présent, la requête est enrichie avec le contexte des messages précédents
  6. Appel API Cloudflare : Requête POST vers l'API AI Search avec authentification
  7. Traitement de la réponse : Extraction du contenu et des liens pertinents
  8. Streaming au client : La réponse est envoyée en temps réel au widget

Fichiers clés

lib/site-config.ts

Gestion centralisée de la configuration multi-site. Définit l'interface SiteConfig et les fonctions de récupération de configuration.

app/api/chat/route.ts

Point d'entrée API principal. Gère la validation des origines, l'authentification Cloudflare, et le streaming des réponses.

components/floating-chat-interface.tsx

Interface utilisateur du chat. Gère l'enrichissement du contexte pour les questions de suivi et l'affichage des réponses.

public/widget.js

Script d'intégration pour les sites externes. Crée l'iframe et gère la communication avec le widget.

Sécurité et protection

Protection par domaine

Le système vérifie que chaque requête provient d'un domaine autorisé configuré dans ALLOWED_DOMAINS.

Domaines toujours autorisés

  • v0.app et tous ses sous-domaines (pour les tests)
  • localhost (en mode développement uniquement)

Bonnes pratiques

  • Ne jamais exposer vos tokens API côté client
  • Utiliser des tokens avec les permissions minimales nécessaires (AutoRAG Read uniquement)
  • Configurer ALLOWED_DOMAINS de manière restrictive
  • Régénérer les tokens régulièrement
  • Surveiller les logs d'utilisation dans Cloudflare

Fonctionnalités avancées

Historique de conversation

Le système maintient automatiquement un historique de conversation et inclut systématiquement la question précédente (et sa réponse) dans chaque nouvelle requête. Cela permet à Cloudflare AI Search de mieux comprendre le contexte et de fournir des réponses plus pertinentes.

Fonctionnement

  • Historique côté client : Les 4 derniers messages (2 échanges) sont conservés dans le navigateur
  • Envoi automatique : À chaque nouvelle question, l'historique est envoyé à l'API
  • Enrichissement de la requête : L'API enrichit la requête avec le contexte : "Question actuelle (contexte: Question précédente - Réponse précédente)"
  • Recherche contextuelle : Cloudflare AI Search utilise ce contexte enrichi pour trouver les informations les plus pertinentes

Exemple de conversation

Question 1
C'est quoi BEPOS ?
→ Envoyé tel quel (pas d'historique)
Réponse 1
BEPOS signifie Bâtiment à Énergie Positive. C'est un bâtiment qui produit plus d'énergie qu'il n'en consomme...
Question 2
Quels sont les avantages ?
→ Enrichi automatiquement en : "Quels sont les avantages ? (contexte: C'est quoi BEPOS ? - BEPOS signifie Bâtiment à Énergie Positive...)"
Réponse 2
Les avantages d'un BEPOS incluent : réduction des coûts énergétiques, impact environnemental positif...
Question 3
Et les inconvénients ?
→ Enrichi avec le contexte de la question 2 et sa réponse

Pourquoi inclure la question ET la réponse précédentes ?

En incluant à la fois la question et la réponse précédentes, on fournit un contexte complet à Cloudflare AI Search. Cela permet de :

  • Comprendre les questions courtes ou ambiguës ("Et les inconvénients ?" → inconvénients de quoi ?)
  • Maintenir la cohérence dans les réponses successives
  • Éviter les répétitions d'informations déjà fournies
  • Permettre des conversations naturelles et fluides

Limite de l'historique

Seuls les 4 derniers messages (2 échanges question-réponse) sont conservés et envoyés. Cela permet de maintenir un contexte pertinent sans surcharger l'API et garantit des temps de réponse optimaux.

Installation et déploiement

1. Configuration Cloudflare

  1. Créez un compte Cloudflare si vous n'en avez pas
  2. Activez Cloudflare AI dans votre compte
  3. Créez une instance AutoRAG et indexez vos documents
  4. Notez votre Account ID et RAG ID
  5. Créez un API Token avec les permissions AutoRAG

2. Configuration Vercel

  1. Déployez le projet sur Vercel
  2. Ajoutez les variables d'environnement dans Project Settings → Environment Variables
  3. Redéployez pour appliquer les changements

3. Intégration sur votre site

Ajoutez ce code dans votre site :

<script 
  src="https://votre-domaine.vercel.app/widget.js" 
  data-site-id="default" 
  data-mode="float"
></script>

Pour un site spécifique dans une configuration multi-site :

<script 
  src="https://votre-domaine.vercel.app/widget.js" 
  data-site-id="site1" 
  data-mode="float"
></script>

Dépannage

Erreur : "Origin not allowed"

Cause : Le domaine n'est pas dans ALLOWED_DOMAINS

Solution : Ajoutez votre domaine dans la variable d'environnement ALLOWED_DOMAINS (sans https:// et sans /)

Erreur : "Cloudflare AI Search error: 401"

Cause : Token API invalide ou expiré

Solution : Vérifiez que CLOUDFLARE_API_TOKEN est correct et que le token a les bonnes permissions

Erreur : "Je n'ai trouvé aucune information"

Cause : Aucun document pertinent trouvé dans votre RAG

Solution : Vérifiez que vos documents sont bien indexés dans Cloudflare AutoRAG et que la question est pertinente

Le widget ne s'affiche pas

Cause : Script mal intégré ou z-index trop bas

Solution : Vérifiez que le script est bien chargé (console du navigateur) et que data-site-id correspond à votre configuration

Référence API

POST /api/chat

Endpoint principal pour envoyer des questions au système.

Corps de la requête

{
  "query": "Quels sont les avantages ?",
  "siteId": "default",
  "parentOrigin": "https://monsite.com",
  "history": [
    {
      "role": "user",
      "content": "C'est quoi BEPOS ?"
    },
    {
      "role": "assistant",
      "content": "BEPOS signifie Bâtiment à Énergie Positive..."
    }
  ]
}

Paramètres

  • query (string, requis) - La question de l'utilisateur
  • siteId (string, requis) - Identifiant du site
  • parentOrigin (string, requis) - Origine du site parent
  • history (array, optionnel) - Historique de conversation (max 4 messages)

Réponse

{
  "content": "Les avantages d'un BEPOS incluent...",
  "links": [
    {
      "title": "Guide BEPOS",
      "url": "https://...",
      "score": 0.95
    }
  ]
}

Codes d'erreur

  • 400 - Requête invalide (query manquante)
  • 403 - Origine non autorisée
  • 500 - Erreur serveur ou Cloudflare

Support et ressources