AKOOL 的流式数字人 SDK 已经为实时视频、音频、文本和麦克风交互奠定了基础。下一步是通过将数字人连接到您可信的产品文档、政策、培训材料或支持内容，使其能够为您的业务提供实际价值。
本指南重点介绍这一知识层。您将创建一个 AKOOL 知识库，通过以下方式将其连接到流式数字人会话： knowledge_id，并验证数字人是否能在您的应用程序中提供基于事实的准确回答。
官方 SDK 文档介绍了如何实现数字人流式传输。本指南将向您展示如何让数字人理解您的业务。
您将构建的内容
最终的体验由三部分组成：您认可的知识源、用于处理这些知识源以供对话使用的 AKOOL 知识库，以及嵌入在您应用程序中的流式数字人。当用户提问时，数字人会以连接的知识库作为上下文，并通过同步的语音和视频返回答案。
知识层与实时会话之间的连接是 knowledge_id 字段。它在创建流式数字人会话时添加，位于浏览器加入实时频道之前。
知识源在 AKOOL 内部进行处理，并由 knowledge_id表示。您的后端在创建流式数字人会话时会包含该 ID。随后，浏览器通过 AKOOL SDK 加入返回的会话，使数字人能够使用经核准的知识进行回答，同时将凭据保留在服务器端。
选择您的构建路径
如果您想快速获得一个可用的原型，请将下方的提示词复制到 AI 编程助手。如果您已经集成了 AKOOL 流式数字人，或者更倾向于自行配置工作流程，请继续阅读“快速入门”。两种路径的结果相同：一个能够基于您的内容提供准确回答的实时数字人。
选项 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 账户、一个流式数字人 ID，以及一个基于官方 JavaScript SDK 的可用流式数字人应用程序。您可以 在 AKOOL 中创建或管理流式数字人准备好数字人需要使用的文档或公开 URL。语音 ID 为可选配置。
如果您尚未连接流式数字人，请先完成 流式数字人 SDK 快速入门 。本文不再赘述安装、频道连接或媒体处理步骤。
第一步：准备知识库来源
上传支持的文档或添加公开 URL。若要进行首次简单测试，一份结构清晰的 DOCX 文档是理想的起点。请确保每个来源专注于单一主题，以便知识库能准确检索到相关内容。
建议从一小部分权威来源和有限的测试范围开始。在首次提问获得准确回答后，再分批添加更多文档或 URL 并进行复测。
第二步：创建 AKOOL 知识库
填写核心设置字段：明确的名称、开场白（API 中的 prologue ）、指令提示词，以及您希望 AKOOL 作为知识来源使用的文档或公开 URL。
开场白（API 中的 prologue）： 编写数字人在会话开始时说的第一句话。保持简短、友好，并与知识库的范围保持一致。
提示词： “请使用已授权的知识来源回答问题。回答应简洁且有帮助。如果无法获取相关信息，请明确说明并建议下一步支持方案。”
等待来源处理完成，然后复制知识库 ID。AKOOL 将此值用作 knowledge_id 实时会话的参数。
第三步：将知识库连接到会话
当您的后端创建流式数字人会话时，请将知识库 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 是否已完成处理。如果处理仍处于挂起状态或已失败，则内容尚无法检索。
回答不一致。 删除陈旧、重复或冲突的源材料。确保每个事实仅保留一个权威版本，使用清晰的标题，并使用答案明确包含在源文件中的直接问题进行重新测试。
会话正常，但对话无法进行。 验证会话是否已使用 mode_type: 2创建。然后检查 SDK 是否加入了后端返回的同一会话，并确保头像、语音、语言和会话配置有效。如果在调试时创建了新的会话，请确保客户端没有继续使用之前响应中已过期的凭据。
应用场景
客户支持。 让访客通过比标准帮助中心搜索更自然的界面来询问有关产品、设置、保修或政策的问题。
产品发现。 使用经批准的销售和产品内容，引导潜在客户了解功能、方案和推荐的工作流程。
员工培训。 将入职指南和内部流程转化为对话式培训助手。
教育与活动。 为学员或参会者提供一位实时演示者，能够回答来自课程材料、演讲者笔记或活动资源的问题。
发布检查清单
☐ 知识来源是最新的、权威的，且已完全处理完毕。
☐ 预期的 knowledge_id 已包含在创建会话时。
☐ 已对精确匹配、改写、范围外及后续问题进行了测试。
☐ 应用程序提供了清晰的“开始”、“中断”和“结束会话”控件。
☐ 最终体验已通过文本和麦克风输入进行了测试。
资源
常见问题解答
什么是 knowledge_id 在 AKOOL 流式数字人中？
knowledge_id 是 AKOOL 知识库的标识符。将其添加到流式数字人会话中，即可告知 AKOOL 在回答基于知识库的问题时应使用哪些已处理的文档和 URL。
何时应该添加 knowledge_id 到流式数字人会话中？
请在后端创建会话时（即浏览器加入会话之前）添加它。这样可以确保从一开始就关联好知识库，并避免在客户端代码中暴露您的 AKOOL API 密钥。
AKOOL 知识库支持哪些文件类型？
AKOOL 文档支持 PDF、DOC、DOCX、TXT、MD、JSON、XML 和 CSV 文件。您还可以添加公共 URL。请使用内容清晰、最新的源文件，并带有描述性标题；在测试检索功能前，请确保处理过程已完成。
我可以直接连接外部 LLM 或 RAG 知识库吗？
目前记录的流式数字人工作流程使用 AKOOL 知识库：添加文档或 URL，获取其 knowledge_id，并在创建会话时包含该 ID。除非您自行设计并验证了独立的应用程序级集成，否则请勿假设可以直接连接任意外部向量数据库或 RAG 服务。
