AKOOLのStreaming Avatar SDKは、リアルタイムのビデオ、オーディオ、テキスト、マイクによるインタラクションの基盤をすでに提供しています。次のステップは、信頼できる製品ドキュメント、ポリシー、トレーニング資料、またはサポートコンテンツにアバターを接続し、ビジネスに役立つ存在にすることです。
このガイドでは、そのナレッジレイヤーに焦点を当てます。AKOOLナレッジベースを作成し、それをStreaming Avatarセッションに接続します。 knowledge_idそして、アバターが自身のアプリケーション内で根拠に基づいた回答を行うことを確認します。
公式SDKドキュメントでは、アバターをストリーミングする方法を解説しています。本ガイドでは、そのアバターにビジネス知識を理解させる方法を説明します。
構築するもの
完成した体験は、承認済みのナレッジソース、それらを会話用に準備するAKOOLナレッジベース、そしてアプリケーションに埋め込まれたStreaming Avatarの3つの要素で構成されます。ユーザーが質問すると、アバターは接続されたナレッジベースをコンテキストとして使用し、同期された音声とビデオを通じて回答を返します。
ナレッジレイヤーとライブセッションの接続は、 knowledge_id フィールドによって行われます。これは、ブラウザがリアルタイムチャネルに参加する前、Streaming Avatarセッションの作成時に追加されます。
ナレッジソースはAKOOL内で処理され、 knowledge_idによって表されます。バックエンドでStreaming Avatarセッションを作成する際、このIDを含めます。その後、ブラウザがAKOOL SDKを通じて返されたセッションに参加することで、認証情報をサーバーに保持したまま、アバターが承認済みの知識に基づいて回答できるようになります。
構築パスの選択
動作するプロトタイプを素早く作成したい場合は、以下のプロンプトをAIコーディングエージェントにコピーしてください。すでにAKOOL Streaming Avatarの統合が完了している場合、またはワークフローを自分で設定したい場合は、クイックスタートに進んでください。どちらのパスでも、独自のコンテンツに基づいた回答を行うライブアバターという同じ結果が得られます。
オプション1：AIエージェントで構築する
このプロンプトを好みのAIコーディングエージェントにコピーし、要求された際にAKOOLの設定情報を提供してください。
AIエージェント構築用プロンプト
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.オプション2：クイックスタートに従う
既存のアプリケーションにナレッジレイヤーを追加したい場合や、AIエージェントに任せる前に統合の仕組みを理解したい場合は、このパスを使用してください。
始める前に
APIアクセス権を持つAKOOLアカウント、Streaming Avatar ID、および公式JavaScript SDKに基づいた動作中のStreaming Avatarアプリケーションが必要です。 AKOOLでストリーミングアバターを作成・管理するアバターに使用するドキュメントまたは公開URLを準備します。Voice IDは任意です。
まだストリーミングアバターに接続していない場合は、先に ストリーミングアバターSDKクイックスタート を完了してください。この記事では、インストール、チャネル接続、メディア処理の手順については繰り返しません。
ステップ1：ナレッジソースを準備する
サポートされているドキュメントをアップロードするか、公開URLを追加します。最初のテストには、シンプルで構成が明確なDOCXファイルから始めるのが実用的です。ナレッジベースが適切な箇所を確実に取得できるよう、各ソースは1つのトピックに絞ってください。
まずは小規模で信頼性の高いソースセットと、限定的なテスト範囲から始めてください。最初の質問で正確な回答が得られたら、ドキュメントやURLを段階的に追加して再テストを行います。
ステップ2：AKOOLナレッジベースを作成する
基本設定項目を入力します。わかりやすい名前、開始時のメッセージ（APIではprologue ）、指示プロンプト、そしてAKOOLのソースとして使用するドキュメントや公開URLを指定します。
開始時のメッセージ（prologue）： セッション開始時にアバターが最初に発するメッセージを作成します。簡潔で親しみやすく、ナレッジベースの範囲に沿った内容にしてください。
プロンプト： 「承認されたナレッジソースを使用して質問に回答してください。簡潔かつ丁寧に回答し、情報がない場合はその旨を明確に伝え、次のサポート手順を提案してください。」
ソースの処理が完了するまで待ち、ナレッジベースIDをコピーします。AKOOLでは、この値をライブセッションの knowledge_id として使用します。
ステップ3：ナレッジベースをセッションに接続する
バックエンドでストリーミングアバターのセッションを作成する際、リクエストにナレッジベースIDを追加してください。ダイアログモードを使用することで、アバターが質問に回答し、会話を継続できるようになります。
セッション設定の例
{
"avatar_id": "your_avatar_id",
"voice_id": "your_voice_id",
"knowledge_id": "your_knowledge_id",
"mode_type": 2
}重要なのは、この処理を行うタイミングです。 knowledge_id はブラウザの joinChat() 呼び出しではなく、セッション作成時に含める必要があります。セッション作成後、ブラウザはAKOOLから返された一時的な認証情報を使用して接続し、標準のSDKインタラクションフローを利用できます。
APIキーを非公開に保つため、セッションはブラウザから直接ではなく、バックエンドから作成してください。以下のcURLの例では、セッション作成時にナレッジベースIDを送信し、ダイアログモードを有効にしています。 mode_type: 2。
ナレッジベースを活用したストリーミングアバターセッションの作成
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"
}'返されたセッション認証情報はサーバーに保存し、必要な接続情報のみをクライアントに渡して、AKOOLストリーミングアバターSDKの初期化に使用してください。
ステップ4：アプリケーションへのアバターの追加
AKOOL JavaScript SDKを使用してリアルタイムチャネルに参加し、ダイアログモードでチャットを開始し、リモートの映像と音声を再生して、テキストやマイク入力を送信します。この部分は公式SDKのクイックスタートと同じです。アプリケーション固有の作業として、アバターの表示場所や、ユーザーによる会話の開始・中断・終了の制御を実装してください。
ナレッジの設定はセッション作成のプロセスで行うようにしてください。これにより、バックエンドで適切なナレッジベースIDを選択するだけで、同じフロントエンドで異なる製品、地域、ターゲット層に対応できるようになります。
ステップ5：回答の根拠（グラウンディング）の確認
アバターが正常に接続された後も、そこで終了しないでください。意図したナレッジが実際に使用されているか、また回答が見つからない場合に適切に応答しているかを確認してください。
ナレッジベースに関する一般的なトラブルシューティング
アバターがナレッジベースを無視する。 正しい knowledge_id がセッション作成リクエストに含まれていることを確認してください。ナレッジベースは、アクティブなストリーミングアバターセッションに紐付けられていなくても、ダッシュボード上に存在している場合があります。
ナレッジベースのコンテンツが見つかりません。 テストを行う前に、アップロードしたすべてのファイルまたは公開URLの処理が完了していることを確認してください。処理が保留中であるか失敗している場合、コンテンツはまだ取得できません。
回答に一貫性がありません。 古い情報、重複した情報、または矛盾するソース資料を削除してください。各事実に対して信頼できるバージョンを1つ保持し、明確な見出しを使用し、ソース内に回答が明示されている直接的な質問で再テストを行ってください。
セッションは機能しますが、対話が機能しません。 セッションが以下を使用して作成されたことを確認してください： mode_type: 2。次に、SDKがバックエンドから返された同じセッションに参加していること、およびアバター、音声、言語、セッション設定が有効であることを確認してください。デバッグ中に代替セッションを作成する場合は、クライアントが以前のレスポンスからの期限切れの認証情報を使用していないことを確認してください。
ユースケース
カスタマーサポート 標準的なヘルプセンター検索よりも自然なインターフェースを通じて、訪問者が製品、セットアップ、保証、またはポリシーに関する質問を行えるようにします。
製品発見 承認済みの販売および製品コンテンツを使用して、見込み客を機能、プラン、推奨ワークフローへと案内します。
従業員トレーニング オンボーディングガイドや社内規定を、対話型のトレーニングアシスタントに変えます。
教育およびイベント 学習者や参加者に、コース教材、講演者ノート、イベントリソースからの質問に回答できるライブプレゼンターを提供します。
ローンチチェックリスト
☐ ナレッジソースが最新かつ信頼できるものであり、完全に処理されていること。
☐ 意図した knowledge_id がセッション作成時に含まれていること。
☐ 正確な質問、言い換えられた質問、範囲外の質問、およびフォローアップの質問についてテスト済みです。
☐ アプリケーションには、セッションの開始、中断、終了を制御する明確な操作機能が備わっています。
☐ 最終的なエクスペリエンスは、テキスト入力とマイク入力の両方でテスト済みです。
リソース
よくある質問
とは knowledge_id AKOOLストリーミングアバターで利用するには？
knowledge_id は、AKOOLナレッジベースの識別子です。これをストリーミングアバターのセッションに追加することで、ナレッジベースに基づいた質問に回答する際、アバターがどの処理済みドキュメントやURLを参照すべきかをAKOOLに指示します。
いつ追加すべきか： knowledge_id ストリーミングアバターのセッションに
セッション作成時にバックエンド側で追加してください。ブラウザがセッションに参加する前に行うことで、最初からナレッジベースが紐付けられ、クライアント側のコードにAKOOL APIキーを露出させるリスクを回避できます。
AKOOLナレッジベースで利用可能なファイル形式は？
AKOOLドキュメントは、PDF、DOC、DOCX、TXT、MD、JSON、XML、CSV形式に対応しています。また、公開URLを追加することも可能です。見出しが明確で整理された最新のソースを使用し、テストを行う前に処理が完了するまで待機してください。
外部のLLMやRAGナレッジベースを直接接続できますか？
ドキュメント化されているストリーミングアバターのワークフローでは、AKOOLナレッジベースを使用します。ドキュメントやURLを追加してその knowledge_idを取得し、セッション作成時にそのIDを含めてください。独自のアプリケーションレベルでの統合を設計・検証しない限り、任意の外部ベクトルデータベースやRAGサービスを直接接続できるとは想定しないでください。
