Guide d'Intégration du Streaming Chat Completions

Vue d'ensemble

Ce guide explique comment intégrer correctement l'API de streaming chat completions de Devana dans votre application. Il couvre la gestion du streaming SSE (Server-Sent Events), le parsing des tokens, la gestion des balises spéciales (<think>, [tool:]), et les bonnes pratiques d'implémentation.

Architecture du streaming

Le système de streaming repose sur le protocole SSE (Server-Sent Events) qui permet au serveur d'envoyer des mises à jour en temps réel au client. Chaque "chunk" (morceau) reçu contient un token qui peut être :

Du texte normal à afficher
Une balise <think> pour les réflexions internes de l'IA
Une balise [tool:] pour les appels d'outils

Format des messages SSE

texte

data: {"choices":[{"delta":{"content":"token"}}],"conversation_id":"conv-123"}

data: [DONE]

Configuration de la requête

Endpoint

texte

POST /v1/chat/completions

Headers requis

typescript

{
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_TOKEN"
}

Corps de la requête

typescript

{
  "stream": true,                          // Active le streaming
  "messages": [
    { "role": "user", "content": "..." }   // Vos messages
  ],
  "files": ["file-id-1", "file-id-2"],    // IDs de fichiers (optionnel)
  "clientModel": "model-name",             // Modèle spécifique (optionnel)
  "conversation_id": "conv-123",           // ID de conversation (optionnel)
  "model": "agent-id"                      // ID de l'agent
}

Exemple avec Fetch API

typescript

const response = await fetch("/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    stream: true,
    messages: [{ role: "user", content: message }],
    conversation_id: chatId,
    model: agentId,
  }),
  signal: abortController.signal, // Pour permettre l'annulation
});

Parsing du flux SSE

Le parsing du flux SSE nécessite une attention particulière car les données peuvent arriver en morceaux incomplets.

Algorithme de parsing

typescript

const reader = response.body.getReader();
let buffer = "";
let lastFailedChunk = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  // Ajouter les nouvelles données au buffer
  buffer += new TextDecoder().decode(value);

   : ;

  
   ((splitIndex = buffer.()) !== -) {
     messageWithLastFail = buffer.(, splitIndex).();
    buffer = buffer.(splitIndex + );

    
     (!messageWithLastFail.()) ;

    
     (messageWithLastFail === ) ;

     {
      
       jsonString = messageWithLastFail.(, );
       jsonData = .(jsonString);
      lastFailedChunk = ;

      
       token = jsonData?.?.[]?.?.;
       (token) {
        (token); 
      }

      
       (jsonData.) {
        conversationId = jsonData.;
      }
    }  (e) {
      
      
       (messageWithLastFail === lastFailedChunk) ;
      lastFailedChunk = messageWithLastFail;
      buffer = messageWithLastFail +  + buffer;
      ;
    }
  }
}

Points clés du parsing

Buffer : Accumule les données jusqu'à avoir un message complet (\n\n)
Retry logic : Si un chunk échoue au parsing, on le réessaye une fois puis on passe au suivant
conversation_id : Récupérer l'ID pour les nouvelles conversations ou le tracking

Gestion des balises spéciales

1. Balises `<think>` - Réflexions internes

Les balises <think> contiennent la chaîne de pensée de l'IA et ne doivent pas être affichées dans le message principal.

Format

texte

<think>
Je dois d'abord vérifier les données...
Ensuite calculer le résultat...
</think>
Voici la réponse finale

Extraction

typescript

function extractThinkAndMainContent(message: string) {
  let thinkContent = "";
  let mainContent = "";
  let currentPos = 0;
  let hasThinkBlock = false;

  while (currentPos < message.length) {
    const thinkStart = message.indexOf("<think>", currentPos);

    if (thinkStart === -1) {
      // Plus de balises <think>, ajouter le reste au contenu principal
      mainContent += message.(currentPos);
      ;
    }

    hasThinkBlock = ;
    
    mainContent += message.(currentPos, thinkStart);

     thinkEnd = message.(, thinkStart);

     (thinkEnd === -) {
      
       content = message.(thinkStart + );
       (thinkContent && content) thinkContent += ;
      thinkContent += content;
      ;
    }  {
      
       content = message.(thinkStart + , thinkEnd);
       (thinkContent && content) thinkContent += ;
      thinkContent += content;
      currentPos = thinkEnd + ;
    }
  }

  
  thinkContent = thinkContent.();
  mainContent = mainContent.(, ).();

   { thinkContent, mainContent, hasThinkBlock };
}

Affichage UI

typescript

// Dans votre composant de message
const { thinkContent, mainContent, hasThinkBlock } = extractThinkAndMainContent(message);

return (
  <>
    {hasThinkBlock && (
      <ThinkPanel
        content={thinkContent}
        isStreaming={isStreaming}
      />
    )}
    <MarkdownContent content={mainContent} />
  </>
);

2. Balises `[tool:]` - Exécution d'outils

Les balises [tool:] signalent qu'un outil est en cours d'exécution ou terminé.

Format

Les balises tool peuvent avoir deux formats selon l'implémentation serveur :

typescript

// Démarrage d'un outil (toujours en JSON)
[tool:start:{"name":"web_search","args":{"query":"météo Paris"}}]

// Fin d'un outil - Format 1 : Simple (juste le nom)
[tool:end:web_search]

// Fin d'un outil - Format 2 : JSON structuré
[tool:end:{"name":"web_search"}]

Note importante : Le format [tool:end:] peut varier selon la configuration serveur. Votre code doit gérer les deux formats.

Parsing et gestion

typescript

interface ToolInfo {
  id: string;
  name: string;
  args: Record<string, unknown>;
  startTime: number;
  endTime?: ;
}

 () {
  
   (token.()) {
     toolMatch = token.();

     (toolMatch) {
       [, action, dataString] = toolMatch;

       {
         toolData;

        
         {
          toolData = .(dataString);
        }  {
          
          
          toolData = { : dataString };
        }

         (action === ) {
          
           uniqueId = ;

           :  = {
            : uniqueId,
            : toolData.,
            : toolData. || {},
            : .(),
          };

          
          ( [...prev, toolInfo]);
          (toolInfo);
        }   (action === ) {
          
          ( {
             (prev?. === toolData.) {
              (
                tools.(
                  t. === prev. ? { ...t, : .() } : t,
                ),
              );
               ;
            }
             prev;
          });
        }
      }  (e) {
        .(, e);
      }
    }

    
    ;
  }

  
  ( prev + token);
}

Affichage UI des outils

typescript

interface ToolExecutionPanelProps {
  runnedTools: ToolInfo[];
  activeTool: ToolInfo | null;
  isStreaming: boolean;
}

function ToolExecutionPanel({ runnedTools, activeTool, isStreaming }: ToolExecutionPanelProps) {
  return (
    <div className="tool-panel">
      <h4>
        {isStreaming ? "Exécution des outils" : "Outils exécutés"}
        <Badge count={runnedTools.length} />
      </h4>

      {runnedTools.map((tool, index) => (
        <
          =
          =
          = ===  ? ""  ""}
          =
        />
      ))}

      {/* Afficher l'outil actif s'il n'est pas déjà dans la liste */}
      {activeTool && !runnedTools.some(t => t.id === activeTool.id) && (
        
      )}
    
  );
}

3. Balises `[tool:confirm:]` - Confirmation utilisateur

Certains outils nécessitent une confirmation de l'utilisateur avant d'être exécutés.

Format

typescript

[tool:confirm:{"messageId":"msg-123","toolName":"delete_file","args":{...}}]

Gestion

typescript

const TOOL_CONFIRM_KEY = "[tool:confirm:";

// Dans le rendu des messages
if (message.startsWith(TOOL_CONFIRM_KEY)) {
  return (
    <ToolConfirmDialog
      message={message}
      onConfirm={async (confirmed) => {
        // Envoyer la réponse de confirmation
        await sendMessage(
          `[tool:confirm:${JSON.stringify({
            messageId: message.id,
            confirm: confirmed
          })}]`
        );
      }}
    />
  );
}

Gestion de l'état des messages

Structure des messages

typescript

interface Message {
  id: string;
  role: "USER" | "ASSISTANT" | "SYSTEM";
  message: string;
  status: "complete" | "streaming" | "temporary" | "error";
  fiability?: "GOOD" | "BAD" | "DEFAULT";
  comment?: string;
  files?: File[];
  sources?: Source[];
  runnedTools?: ToolInfo[];
  activeTool?: ToolInfo | null;
}

États du flux de conversation

Message temporaire utilisateur : Affiché immédiatement lors de l'envoi
Attente de réponse : Indicateur de chargement
Streaming assistant : Message en cours de réception avec status: "streaming"
Message complet : Streaming terminé avec status: "complete"

Gestion des états

typescript

function useChat() {
  const [isStreaming, setIsStreaming] = useState(false);
  const [streamedResponse, setStreamedResponse] = useState("");
  const [temporaryQuestion, setTemporaryQuestion] = ();
   [waitingForResponse, setWaitingForResponse] = ();
   [runnedTools, setRunnedTools] = useState<[]>([]);
   [activeTool, setActiveTool] = useState< | >();

  
   messages = ( {
     : [] = [...historyMessages];

    
     (temporaryQuestion) {
      msgs.({
        : ,
        : ,
        : temporaryQuestion,
        : ,
      });
    }

    
     (
      streamedResponse ||
      isStreaming ||
      activeTool ||
      runnedTools. > 
    ) {
      
       lastHistoryMsg = msgs[msgs. - ];
       cleanStream = streamedResponse
        .(, )
        .();
       cleanHistory = lastHistoryMsg?.
        ?.(, )
        ?.();

       isDuplicate =
        lastHistoryMsg?. ===  &&
        !isStreaming &&
        (lastHistoryMsg?. === streamedResponse ||
          cleanHistory === cleanStream ||
          (cleanStream. >  && cleanHistory?.(cleanStream)));

       (!isDuplicate) {
        msgs.({
          : ,
          : ,
          : streamedResponse,
          : isStreaming ?  : ,
          runnedTools,
          activeTool,
        });
      }
    }

     msgs;
  }, [
    historyMessages,
    temporaryQuestion,
    streamedResponse,
    isStreaming,
    runnedTools,
    activeTool,
  ]);

   { messages  };
}

Prévention des duplications

Lors du passage du streaming à l'historique permanent, il faut éviter d'afficher le même message deux fois :

typescript

// Comparer le contenu sans les balises <think>
const cleanStream = streamedResponse
  .replace(/<think>[\s\S]*?<\/think>/, "")
  .trim();
const cleanHistory = lastHistoryMsg?.message
  ?.replace(/<think>[\s\S]*?<\/think>/, "")
  ?.trim();

const isDuplicate =
  lastHistoryMsg?.role === "ASSISTANT" &&
  !isStreaming &&
  (lastHistoryMsg?.message === streamedResponse ||
    cleanHistory === cleanStream ||
    (cleanStream.length > 10 && cleanHistory?.includes(cleanStream)));

Gestion des erreurs

Annulation de requête

typescript

const abortControllerRef = useRef<AbortController | null>(null);

function sendMessage(message: string) {
  // Créer un nouveau controller pour cette requête
  abortControllerRef.current = new AbortController();

  try {
    const response = await fetch(url, {
      // ...
      signal: abortControllerRef.current.signal,
    });
    // ...
  } catch (error) {
    if (error.name !== "AbortError") {
      // Erreur réelle, afficher un message
      toast.error();
    }
    
  }  {
    abortControllerRef. = ;
  }
}

 () {
   (abortControllerRef.) {
    abortControllerRef..();
  }
  ();
  ();
  ();
}

Gestion des erreurs réseau

typescript

async function sendMessage(message: string) {
  try {
    const response = await fetch(url, {
      /* ... */
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    if (!response.body) {
      throw new Error("No response body");
    }

    // Traiter le flux...
  } catch (error) {
    if (error.name === "AbortError") {
      // Annulation volontaire, ne rien faire
      return;
    }

    
    .(, error);
    toast.();

    
    ();
    ();
    ();
  }
}

Timeout

typescript

// Créer un timeout pour la requête
const timeoutId = setTimeout(() => {
  abortControllerRef.current?.abort();
  toast.error("La requête a pris trop de temps");
}, 60000); // 60 secondes

try {
  // ... traitement du streaming
} finally {
  clearTimeout(timeoutId);
}

Exemple d'implémentation complète

Voici un exemple React complet d'intégration :

typescript

Bonnes pratiques

1. Performance

Utiliser requestAnimationFrame pour le scroll automatique pendant le streaming
Mémoriser les composants avec React.memo pour éviter les re-renders inutiles
Debounce les updates UI si le streaming est très rapide

typescript

useEffect(() => {
  if (isStreaming && isAttachedToBottom) {
    requestAnimationFrame(() => {
      scrollContainerRef.current?.scrollTo({
        top: scrollContainerRef.current.scrollHeight,
        behavior: "auto",
      });
    });
  }
}, [messages, isStreaming, isAttachedToBottom]);

2. UX

Indicateur de streaming : Afficher clairement que l'IA est en train de répondre
Bouton stop : Permettre à l'utilisateur d'arrêter le streaming
Scroll automatique : Suivre le message pendant le streaming, avec possibilité de désactiver
Affichage progressif : Montrer le texte au fur et à mesure, pas par blocs

typescript

<button
  onClick={stopRequest}
  disabled={!isStreaming}
>
  {isStreaming ? "Arrêter la génération" : "Génération terminée"}
</button>

3. Gestion d'état

Réinitialiser les états lors du changement de conversation
Nettoyer les AbortControllers dans les effets cleanup
Éviter les duplications entre messages streaming et historique

typescript

useEffect(() => {
  // Reset quand la conversation change
  setStreamedResponse("");
  setIsStreaming(false);
  setTemporaryQuestion("");
  setWaitingForResponse(false);
  setRunnedTools([]);
  setActiveTool(null);
}, [chatId]);

4. Accessibilité

ARIA labels sur les boutons et indicateurs
Annonces pour les lecteurs d'écran quand un message arrive
Focus management lors de l'envoi de messages

typescript

<div role="log" aria-live="polite" aria-atomic="false">
  {messages.map(msg => (
    <div key={msg.id} aria-label={`Message de ${msg.role}`}>
      {msg.message}
    </div>
  ))}
</div>

5. Sécurité

Échapper le HTML dans les messages pour éviter les XSS
Valider les tokens avant de les ajouter au DOM
Limiter la taille du buffer pour éviter les attaques par overflow

typescript

function escapeHtml(text: string): string {
  return text
    .replace(/&/g, "&amp;")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;")
    .replace(/'/g, "&#039;");
}

// Appliquer uniquement en dehors des blocs de code
function addEscapeOutsideCodeBlocks(input: string): string {
  const segments = input.split(/(```[\s\S]*?```|`[^`]*`)/);
  return segments
    .( {
       (i %  === ) {
        
         segment.(, ).(, );
      }
       segment;
    })
    .();
}

6. Tests

typescript

// Test du parsing SSE
describe("SSE Parsing", () => {
  it("should parse complete messages", () => {
    const chunk = 'data: {"choices":[{"delta":{"content":"Hello"}}]}\n\n';
    const result = parseSSEChunk(chunk);
    expect(result.token).toBe("Hello");
  });

  it("should handle incomplete messages",  {
     chunk1 = ;
     chunk2 = ;
     buffer = chunk1 + chunk2;
     result = (buffer);
    (result.).();
  });
});


(,  {
  (,  {
     message = ;
     { thinkContent, mainContent } = (message);
    (thinkContent).();
    (mainContent).();
  });

  (,  {
     message = ;
     { thinkContent, mainContent } = (message);
    (thinkContent).();
    (mainContent).();
  });
});


(,  {
  (,  {
     token = ;
     result = (token);
    (result.).();
    (result.).();
    (result.).({ :  });
  });
});

Résumé

L'intégration du streaming chat completions nécessite :

✅ Parser correctement le flux SSE avec gestion du buffer
✅ Extraire les balises <think> pour les afficher séparément
✅ Gérer les balises [tool:] pour afficher l'exécution des outils
✅ Maintenir l'état des messages (temporaires, streaming, complets)
✅ Prévenir les duplications entre streaming et historique
✅ Gérer les erreurs et permettre l'annulation
✅ Optimiser les performances avec mémorisation et RAF
✅ Assurer une bonne UX avec indicateurs et scroll automatique

En suivant ce guide, vous pourrez intégrer de manière robuste et performante le système de streaming chat completions de Devana dans votre application.

Support

Pour toute question ou problème d'intégration, n'hésitez pas à consulter notre documentation complète ou à contacter notre support technique.

SDK

Notes de version

Conformité

Guide d'Intégration du Streaming Chat Completions

Vue d'ensemble

Table des matières

Architecture du streaming

Format des messages SSE

Configuration de la requête

Endpoint

Headers requis

Corps de la requête

Exemple avec Fetch API

Parsing du flux SSE

Algorithme de parsing

Points clés du parsing

Gestion des balises spéciales

1. Balises <think> - Réflexions internes

Format

Extraction

Affichage UI

2. Balises [tool:] - Exécution d'outils

Format

Parsing et gestion

Affichage UI des outils

3. Balises [tool:confirm:] - Confirmation utilisateur

Format

Gestion

Gestion de l'état des messages

Structure des messages

États du flux de conversation

Gestion des états

Prévention des duplications

Gestion des erreurs

Annulation de requête

Gestion des erreurs réseau

Timeout

Exemple d'implémentation complète

Bonnes pratiques

1. Performance

2. UX

3. Gestion d'état

4. Accessibilité

5. Sécurité

6. Tests

Résumé

Support

1. Balises `<think>` - Réflexions internes

2. Balises `[tool:]` - Exécution d'outils

3. Balises `[tool:confirm:]` - Confirmation utilisateur