Le SDK Streaming Avatar d'AKOOL fournit déjà les bases pour les interactions en temps réel par vidéo, audio, texte et microphone. L'étape suivante consiste à rendre cet avatar utile pour votre entreprise en le connectant à vos documents produits, politiques, supports de formation ou contenus d'assistance de confiance.
Ce guide se concentre sur cette couche de connaissances. Vous allez créer une base de connaissances AKOOL, la connecter à une session Streaming Avatar avec knowledge_id, et vérifier que l'avatar fournit des réponses fiables au sein de votre propre application.
La documentation officielle du SDK vous montre comment diffuser un avatar. Ce guide vous explique comment faire en sorte que cet avatar comprenne votre activité.
Ce que vous allez construire
L'expérience finale combine trois éléments : vos sources de connaissances approuvées, une base de connaissances AKOOL qui prépare ces sources pour la conversation, et un avatar en streaming intégré à votre application. Lorsqu'un utilisateur pose une question, l'avatar utilise la base de connaissances connectée comme contexte et renvoie la réponse via une synthèse vocale et vidéo synchronisée.
La connexion entre la couche de connaissances et la session en direct est le champ knowledge_id . Il est ajouté lors de la création de la session Streaming Avatar, avant que le navigateur ne rejoigne le canal en temps réel.
Les sources de connaissances sont traitées au sein d'AKOOL et représentées par un knowledge_id. Votre backend inclut cet identifiant lors de la création de la session Streaming Avatar. Le navigateur rejoint ensuite la session renvoyée via le SDK AKOOL, permettant à l'avatar de répondre avec les connaissances approuvées tout en conservant les identifiants sur le serveur.
Choisissez votre méthode de construction
Si vous souhaitez obtenir rapidement un prototype fonctionnel, copiez l'invite ci-dessous dans un agent de codage IA. Si vous disposez déjà d'une intégration AKOOL Streaming Avatar — ou si vous préférez configurer le flux de travail vous-même — poursuivez avec le démarrage rapide. Les deux chemins mènent au même résultat : un avatar en direct dont les réponses sont basées sur votre propre contenu.
Option 1 : Construire avec un agent IA
Copiez cette invite dans votre agent de codage IA préféré et fournissez votre configuration AKOOL lorsque cela vous est demandé.
Invite de construction pour l'agent IA
Build a knowledge-powered AKOOL Streaming Avatar application.
Use AKOOL’s official Streaming Avatar SDK Quick Start as the implementation reference:
https://docs.akool.com/sdk/jssdk-start
Start from the official SDK workflow instead of recreating a generic streaming demo. Add the following knowledge-base workflow:
1. Create the avatar session from a backend endpoint.
2. Read the Avatar ID, Knowledge Base ID, optional Voice ID, language, and duration from server-side configuration.
3. Include knowledge_id and mode_type: 2 in the session-creation request.
4. Return only the temporary session credentials required by the browser.
5. Use the official AKOOL JavaScript SDK for video, audio, text, microphone, and interruption controls.
6. Add an explicit End Session action.
7. Provide a small test panel for an exact-source question, a paraphrased question, and an out-of-scope question.
Keep the interface simple and use the linked AKOOL documentation as the source of truth.Option 2 : Suivre le démarrage rapide
Utilisez cette méthode si vous souhaitez ajouter la couche de connaissances à une application existante ou comprendre l'intégration avant de la confier à un agent IA.
Avant de commencer
Vous avez besoin d'un compte AKOOL avec accès API, d'un identifiant Streaming Avatar et d'une application Streaming Avatar fonctionnelle basée sur le SDK JavaScript officiel. Vous pouvez créer ou gérer un avatar en streaming dans AKOOL. Préparez les documents ou les URL publiques que l'avatar doit utiliser. Un identifiant vocal (Voice ID) est facultatif.
Si vous n'êtes pas encore connecté à Streaming Avatar, consultez d'abord le Guide de démarrage rapide du SDK Streaming Avatar . Cet article ne répète volontairement pas les étapes d'installation, de connexion au canal ou de gestion des médias.
Étape 1 : Préparer les sources de connaissances
Téléchargez les documents pris en charge ou ajoutez des URL publiques. Pour un premier test simple, un fichier DOCX propre et bien structuré est un point de départ pratique. Veillez à ce que chaque source se concentre sur un seul sujet afin que la base de connaissances puisse récupérer le passage pertinent de manière fiable.
Commencez par un petit ensemble de sources faisant autorité et un périmètre de test restreint. Une fois que les premières questions obtiennent des réponses précises, ajoutez d'autres documents ou URL par lots contrôlés et effectuez de nouveaux tests.
Étape 2 : Créer la base de connaissances AKOOL
Remplissez les champs de configuration principaux : un nom clair, une déclaration d'ouverture (prologue dans l'API), une instruction (prompt) et les documents ou URL publiques que vous souhaitez qu'AKOOL utilise comme sources.
Déclaration d'ouverture (prologue) : Rédigez le premier message que l'avatar doit prononcer au début de la session. Restez bref, accueillant et en adéquation avec le périmètre de la base de connaissances.
Instruction (Prompt) : « Répondez aux questions en utilisant les sources de connaissances approuvées. Soyez concis et utile. Si l'information n'est pas disponible, indiquez-le clairement et suggérez l'étape de support suivante. »
Attendez que le traitement des sources soit terminé, puis copiez l'identifiant de la base de connaissances (Knowledge Base ID). AKOOL utilise cette valeur comme knowledge_id pour la session en direct.
Étape 3 : Connecter la base de connaissances à la session
Lorsque votre backend crée la session Streaming Avatar, ajoutez l'ID de la base de connaissances à la requête. Utilisez le mode dialogue pour permettre à l'avatar de répondre aux questions et de poursuivre la conversation.
Exemple de configuration de session
{
"avatar_id": "your_avatar_id",
"voice_id": "your_voice_id",
"knowledge_id": "your_knowledge_id",
"mode_type": 2
}Le détail important concerne le moment où cela se produit : knowledge_id doit être inclus lors de la création de la session, et non dans l'appel joinChat() du navigateur. Une fois la session créée, le navigateur peut se connecter avec les identifiants temporaires renvoyés par AKOOL et utiliser le flux d'interaction standard du SDK.
Créez la session depuis votre backend, et non directement dans le navigateur, afin que la clé API reste privée. Cet exemple cURL envoie l'ID de la base de connaissances lors de la création de la session et active le mode dialogue avec mode_type: 2.
Créer une session Streaming Avatar basée sur une base de connaissances
curl --request POST \
--url https://openapi.akool.com/api/open/v4/liveAvatar/session/create \
--header "Content-Type: application/json" \
--header "x-api-key: <api-key>" \
--data '{
"avatar_id": "<avatar-id>",
"voice_id": "<voice-id>",
"language": "en",
"duration": 600,
"mode_type": 2,
"knowledge_id": "<knowledge-id>",
"stream_type": "agora"
}'Stockez les identifiants de session renvoyés sur le serveur, ne transmettez que les valeurs de connexion requises à votre client et utilisez-les pour initialiser le SDK AKOOL Streaming Avatar.
Étape 4 : Ajouter l'avatar à votre application
Utilisez le SDK JavaScript AKOOL pour rejoindre le canal en temps réel, démarrer le chat en mode dialogue, afficher la vidéo et l'audio distants, et envoyer des entrées textuelles ou vocales. Cette partie est identique au guide de démarrage rapide officiel du SDK ; votre travail spécifique consiste à décider où l'avatar apparaît et comment les utilisateurs commencent, interrompent et terminent une conversation.
Maintenez la configuration de la base de connaissances au niveau de la création de session. Cela permet à la même interface de prendre en charge différents produits, régions ou publics en sélectionnant un ID de base de connaissances approuvé différent sur le backend.
Étape 5 : Vérifier la pertinence des réponses
Ne vous arrêtez pas une fois que l'avatar est connecté. Vérifiez qu'il utilise réellement les connaissances prévues et qu'il répond de manière appropriée lorsque la réponse n'est pas disponible.
Dépannage des problèmes courants liés à la base de connaissances
L'avatar ignore la base de connaissances. Vérifiez que le bon knowledge_id est inclus dans la requête de création de session. Une base de connaissances peut exister dans le tableau de bord sans être associée à la session Streaming Avatar active.
Le contenu de la base de connaissances est introuvable. Vérifiez que le traitement de chaque fichier importé ou URL publique est terminé avant de procéder à vos tests. Si le traitement est toujours en attente ou a échoué, le contenu n'est pas encore disponible pour être récupéré.
Les réponses sont incohérentes. Supprimez les sources obsolètes, dupliquées ou contradictoires. Conservez une version faisant autorité pour chaque fait, utilisez des titres clairs et effectuez de nouveaux tests avec des questions directes dont les réponses figurent explicitement dans vos sources.
La session fonctionne, mais le dialogue ne se lance pas. Vérifiez que la session a été créée avec mode_type: 2. Assurez-vous ensuite que le SDK rejoint bien la session renvoyée par votre backend et que l'avatar, la voix, la langue et la configuration de la session sont valides. Si vous créez une session de remplacement lors du débogage, vérifiez que le client n'utilise pas d'identifiants expirés provenant d'une réponse précédente.
Cas d'utilisation
Support client. Permettez aux visiteurs de poser des questions sur les produits, l'installation, la garantie ou les politiques via une interface plus naturelle qu'une recherche classique dans un centre d'aide.
Découverte de produits. Guidez vos prospects à travers les fonctionnalités, les offres et les flux de travail recommandés en utilisant du contenu commercial et produit approuvé.
Formation des employés. Transformez vos guides d'intégration et vos procédures internes en un assistant de formation conversationnel.
Éducation et événements. Offrez aux apprenants ou aux participants un présentateur en direct capable de répondre aux questions à partir des supports de cours, des notes de présentation ou des ressources de l'événement.
Check-list de lancement
☐ Les sources de connaissances sont à jour, font autorité et sont entièrement traitées.
☐ Le knowledge_id souhaité est inclus lors de la création de la session.
☐ Les questions exactes, paraphrasées, hors champ et de suivi ont été testées.
☐ L'application fournit des commandes claires pour démarrer, interrompre et terminer une session.
☐ L'expérience finale a été testée avec des entrées textuelles et vocales (microphone).
Ressources
- Base de connaissances AKOOL
- Créer une session d'avatar en streaming
- Guide de démarrage rapide du SDK Streaming Avatar
- Bonnes pratiques pour le SDK d'avatar en streaming
Foire aux questions
Qu'est-ce que knowledge_id dans l'avatar en streaming AKOOL ?
knowledge_id est l'identifiant d'une base de connaissances AKOOL. L'ajouter à une session d'avatar en streaming indique à AKOOL quels documents et URL traités l'avatar doit utiliser pour répondre aux questions basées sur ces connaissances.
Quand dois-je ajouter knowledge_id à la session d'avatar en streaming ?
Ajoutez-le lors de la création de la session sur votre backend, avant que le navigateur ne rejoigne la session. Cela garantit que la base de connaissances est associée dès le départ et évite d'exposer votre clé API AKOOL dans le code côté client.
Quels types de fichiers une base de connaissances AKOOL peut-elle utiliser ?
Les documents AKOOL prennent en charge les fichiers PDF, DOC, DOCX, TXT, MD, JSON, XML et CSV. Vous pouvez également ajouter des URL publiques. Utilisez des sources propres et à jour avec des titres descriptifs, et attendez que le traitement soit terminé avant de tester la récupération des données.
Puis-je connecter directement un LLM externe ou une base de connaissances RAG ?
Le flux de travail documenté pour l'avatar en streaming utilise une base de connaissances AKOOL : ajoutez des documents ou des URL, obtenez son knowledge_id, et incluez cet identifiant lors de la création de la session. Ne supposez pas qu'une base de données vectorielle externe ou un service RAG arbitraire peut être connecté directement, à moins que vous ne conceviez et validiez une intégration distincte au niveau de l'application.
