入门约 30 分钟 2026-09-03 09:24:53 · 6 阅读

D-ID 实时对话数字人实战：从建 Agent、挂知识库（RAG）到嵌入网站

跟做完你能得到什么

这篇教程带你用 D-ID 做出一个实时对话数字人代理（AI Agent）：它有一张会说话的脸，能听懂你打的字或说的话，回答时优先引用你自己上传的文档（这就是 RAG，检索增强生成），最后还能以一个小挂件的形式嵌到你的网站上，访客点开就能和它视频对话。

全文给你两条路线：路线 A 是 Studio 零代码路线，全程在 D-ID 的网页工作台里点选完成，适合完全不想写代码的读者；路线 B 是 API 路线，用 curl 命令和官方 SDK 把同样的东西做成可编程的服务，适合开发者。两条路线底层是同一套能力，你可以先走 A 跑通概念，再用 B 落地。

本教程属于 D-ID 系列实操之一，站点 AI 视频总纲见《从一句话到成片：AI 视频完整制作流程》；D-ID 产品详情与入口见 D-ID 产品页。

一、先看懂：实时代理是怎么工作的

按官方 Realtime 文档的说法，D-ID 的实时代理是「由大语言模型和可选知识库驱动、通过化身形象和 WebRTC 流式交付的对话式 AI」。一句话提问进去，会经过这样一条流水线：

用户说话 → 语音转文字（STT）→ 轮次检测（判断你说完了没）→ 大语言模型（LLM，可随时查询知识库）→ 文字转语音（TTS）→ 数字人化身开口回答，整条链路通过 WebRTC 实时流式传输，所以延迟很低，体验接近视频通话。

官方把这条管线拆成了六个组件，哪些必选、哪些可选、谁来提供，我直接整理成表：

语音转文字（STT）：必需，D-ID 提供｜轮次检测：必需，D-ID 提供｜大语言模型（LLM）：可选，OpenAI、Google｜知识库（Knowledge，RAG）：可选，D-ID 提供｜文字转语音（TTS）：可选，ElevenLabs 或 Azure｜化身（Avatar）：必需，D-ID 提供

其中「知识库」就是你上传的公司资料、产品 FAQ、帮助文档。模型回答问题前，会先去知识库里检索相关片段，再基于检索到的内容组织答案——这就是 RAG。D-ID 官网用一张流程图画了这个过程：问题作为 Prompt 进入 LLM，LLM 向下发出检索查询，知识库返回相关文本，最终合成 Response 交给数字人说出。

D-ID 官方 RAG 流程图：问题经 LLM 检索知识库后生成回答

D-ID 官方 RAG 流程图（官方文档配图）

二、准备工作：账号、入口与计费

1. 注册账号。打开 studio.d-id.com 注册并登录。D-ID 的网页工作台叫 Creative Studio，左边栏从上到下依次是 Home、Video Studio、Video Translate、Agents、Video Campaigns、Avatars、API、Apps 等入口，本教程主要用 Agents 这一项。

2. 想清楚走哪条路线。不写代码选路线 A（Studio 六步）；要编程控制选路线 B（API 五步）。路线 B 需要能上网的终端和 Node.js 环境（官方 demo 仓库要求 Node v20.19.0 或 v22+）。

3. 了解计费规则再动手。官方帮助中心写明：Agent 按说话时间计费——每条回复（即一段生成的视频）在 15 秒以内消耗 0.5 个 credit；超过 15 秒后，每增加一个 15 秒区间再消耗 0.5 个 credit。官方给的例子：一条 10 秒的回复消耗 0.5 credit；一条 40 秒的回复消耗 1.5 credit（15+15+10 三个区间）。账户 credit 耗尽时，Agent 会停止响应，直到补充额度。套餐价格与赠送额度以官方页面为准。

三、路线 A：Studio 六步建出你的第一个 Agent

步骤 1：进入 Agents 页面，点击创建。登录 Creative Studio 后，点左侧栏的 Agents（当前带 Beta 标签），进入代理列表页。首次进入是空列表，页面中央有虚线框的「Create agent」占位卡，右上角还有橙色 + Create agent 按钮，点任意一个进入创建向导。

D-ID Creative Studio 的 Agents 页面与 Create agent 按钮

Creative Studio 的 Agents 页面，右上角橙色按钮即创建入口（官方帮助中心截图）

步骤 2：选形象（Appearance）。给 Agent 挑一张脸：可以选官方库存化身（stock avatars），也可以用你以前做过的化身；如果都不满意，点 Create 用一张照片或一段视频新建一个专属化身。选好后点 Next。

步骤 3：填代理详情（Agent details）。这一页决定「它是谁、怎么说话」：

Name：给 Agent 起个好认的名字；
Language & Voice：选语言和声音，可以用内置声音、克隆自己的声音，或导入外部声音（例如 ElevenLabs）；
Role：定义身份，比如产品专家、客服助理、虚拟主持人；
Personality：描述语气风格，例如「友好耐心」「专业简洁」；
Agent Instructions（可选）：补充行为准则，比如「回答不超过三句话」；
创造力滑杆（0-100）：官方说明这决定回答的可预测程度，越低越聚焦、越高越发散，建议多试几个档位；
选择 LLM 模型：指定背后用哪个大模型。

填完点 Next。

步骤 4：挂知识库（Knowledge sources）——本教程的核心。这一页左侧是配置区、右侧是实时预览。先选接地模式（Grounding Mode），官方给了三档：

Grounded：只根据你上传的资料回答｜Hybrid：优先你的资料，允许补充通用知识｜Ungrounded：不使用任何自定义数据

做企业客服、产品问答这类场景，选 Grounded 或 Hybrid；只是想要个会聊天的数字人，选 Ungrounded。然后选择喂数据的方式，两种：

上传文件（Upload files）：支持 PDF、TXT、PPTX；一个知识库最多 5 份文档，每份不超过 50 万字符；官方明确建议用段落式文本（文章、FAQ），不要指望它读表格和图片。把文件拖进上传框即可；
直接输入文本（Input text，官方推荐）：把要点直接粘贴进 Knowledge 文本框，上限 8 万字符。官方说这种方式效果更好，因为它直接接入 LLM 提示词，没有检索损耗。

配好后用右侧 Preview 面板先打字测两句——此阶段预览是纯文字模式，能验证它有没有把你的资料吃进去。

Knowledge sources 配置页：接地模式、上传方式、知识文本框与右侧预览

Knowledge sources 配置页，右侧可实时预览测试（官方帮助中心截图）

步骤 5：聊天设置（Chat settings）。四项都影响访客的第一印象：

Welcome message：开场白，输入框带字数计数（示例中为 43/350）；
Conversation starters：最多加 4 个预置问题，帮访客开场；
Topics to avoid：不想它聊的话题，逗号分隔，系统提供 Pricing、Competitors、Legal 等快捷标签；
Max response length：开关打开后可限制单条回答的字数上限，防止它说个没完把 credit 烧光。

右侧预览会随配置实时刷新。确认无误，点黑色 Create agent 按钮。

Chat settings 配置页：开场白、预置问题、回避话题与回答长度限制

Chat settings 配置页，右侧是访客视角的实时预览（官方帮助中心截图）

步骤 6：完成与分享。几秒后，新 Agent 出现在 Agents 列表里。鼠标悬停到它的卡片上，通过分享链接发给别人，或按下一节的方法嵌入网站。

四、路线 B：API 五步，用命令行搭同一个东西

步骤 1：取 API Key。登录 Studio 后进入 Account settings，点 Generate API key。Key 的格式是 API_USER:API_PASSWORD，只显示一次，立刻妥善保存。所有 API 请求都走 Basic 认证，验证命令：

curl -X GET "https://api.d-id.com/agents" \
  -H "Authorization: Basic <你的KEY>"

能返回代理列表就说明 Key 有效。

步骤 2：创建 Agent。一次调用同时定义形象、声音和大模型指令（以下为官方文档原样示例）：

curl -X POST "https://api.d-id.com/agents" \
  -H "Authorization: Basic <你的KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "preview_name": "Amber",
    "presenter": {
      "type": "clip",
      "presenter_id": "v2_public_Amber@0zSz8kflCN",
      "voice": {
        "type": "microsoft",
        "voice_id": "en-US-JennyMultilingualV2Neural"
      }
    },
    "llm": {
      "provider": "openai",
      "model": "gpt-4.1-mini",
      "instructions": "you are a helpful assistant"
    }
  }'

返回体里有 "id": "agt_abc123" 和 "status": "created"。把这个 id 存下来，后面所有操作都靠它。

步骤 3：验证 Agent 就绪。用 GET /agents/{你的agentId} 查详情，看到 "status": "done" 且返回了 idle_video（化身的待机动画地址），说明它准备好了。

步骤 4：建知识库并挂到 Agent（RAG 四连）。四条命令对应四个动作：

① 建一个空知识库容器：

curl -X POST "https://api.d-id.com/knowledge" \
  -H "Authorization: Basic <你的KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyKnowledge",
    "description": "Knowledge base for my agent"
  }'

返回 "id": "knl_abc123"，这就是 knowledgeId（官方限制：每个知识库最多存 5 份文档）。

② 往知识库加文档。给个标题、类型和文件地址（官方示例用 PDF 直链）：

curl -X POST "https://api.d-id.com/knowledge/knl_abc123/documents" \
  -H "Authorization: Basic <你的KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Company FAQ",
    "documentType": "pdf",
    "source_url": "https://your-storage.com/faq.pdf"
  }'

返回 "status": "processing"，文档开始异步处理。多份文档就重复这条命令。

③ 轮询知识库状态，直到 "status": "done"：

curl -X GET "https://api.d-id.com/knowledge/knl_abc123" \
  -H "Authorization: Basic <你的KEY>"

④ 把知识库挂到 Agent，并指定 RAG 模板：

curl -X PATCH "https://api.d-id.com/agents/<你的AGENT_ID>" \
  -H "Authorization: Basic <你的KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledge": {
      "id": "knl_abc123"
    },
    "llm": {
      "template": "rag-ungrounded"
    }
  }'

模板二选一：rag-ungrounded 以你的知识库为主、允许补充通用知识（对应 Studio 的 Hybrid 思路）；rag-grounded 则严格只用你的资料。客服场景怕它瞎编就选 grounded。

步骤 5：发起实时会话。浏览器前端不能直接用上面的管理 Key（会泄露），要先签发 client key：

curl -X POST "https://api.d-id.com/agents/client-key" \
  -H "Authorization: Basic <你的KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_domains": ["http://localhost:3000", "https://yourdomain.com"]
  }'

返回的 client_key 只能在你列出的域名下、且只能用于建会话，改不了删不了你的 Agent，这就是官方说的安全边界。然后装官方 SDK：npm install @d-id/client-sdk，前端核心代码（官方示例）：

import * as did from "@d-id/client-sdk";

const agentId = "agt_abc123";
const auth = { type: "key", clientKey: "<你的CLIENT_KEY>" };
const videoElement = document.getElementById("agent-video");

const callbacks = {
  onSrcObjectReady(value) { videoElement.srcObject = value; },
  onConnectionStateChange(state) { console.log("Connection state:", state); },
  onNewMessage(messages, type) { console.log("Messages:", messages); }
};

const agent = await did.createAgentManager(agentId, { auth, callbacks });
await agent.connect();          // 建立 WebRTC 连接
await agent.chat("你好，你能帮我做什么？");  // 发消息，数字人流式回答
await agent.disconnect();       // 结束会话

页面上放一个视频元素接住画面：<video id="agent-video" autoplay playsinline></video>。不想从零搭界面，官方在 GitHub 提供了完整示例仓库 de-id/agents-sdk-demo（Vite + 原生 JS，含 Chat/Speak 双模式和打断演示，MIT 协议）：clone 后把 client key 与 agentId 粘到 main.js 顶部，npm install 再 npm run dev，浏览器打开 http://localhost:3000 即可，注意它要求 Node v20.19.0 或 v22+。

五、选模型：内置、外部 Key 与自定义 LLM

路线 A 第 3 步和路线 B 第 2 步都绕不开「背后用哪个大模型」。官方把接入方式分成三档，按省事程度排序：

① 内置模型（Built-in Models）：D-ID 预配置好、优化过的 OpenAI 系模型，选一个就能用，基础设施全托管。官方文档列出的可选模型包括 gpt-4o-global（最新 GPT-4o 全球部署版，适合生产环境）、gpt-4o-mini（紧凑版，成本优先）、gpt-4.1（完整版，复杂推理）、gpt-4.1-mini（均衡之选，本文路线 B 示例用的就是它）、gpt-4.1-nano（超低延迟，简单交互）。新手直接选内置，从 mini 档起步。

② 外部 API Key（External API keys）：自带 OpenAI 或 Azure OpenAI 的 Key，D-ID 替你把请求路由到你自己的订阅上。适合已有企业合同、有合规要求或想优化成本的团队。注意官方说明：外部 Key 目前只能在 Studio 网页端配置（API 管理方式「即将推出」），Key 会被 D-ID 加密存储。

③ 自定义 LLM（Custom LLM）：进阶玩法。你自己部署一个 OpenAI 兼容端点（可以是自研模型、专属微调模型），D-ID 把对话历史发到你的端点处理。官方在 llm.provider 里填 "custom"，再给 url、key、streaming、max_messages 等参数，并且放了一个示例仓库 de-id/example-custom-llm 供参考。官方 FAQ 特别提醒：生产环境强烈建议开 streaming（流式返回），对话节奏才自然；非流式模式只适合调试。

三档怎么选，官方给的判断标准直接抄给你：快速起步/原型/不想管基础设施 → 内置；已有 OpenAI/Azure 合同或合规要求 → 外部 Key；专有模型、行业知识库、数据必须留在自己手里 → 自定义 LLM。无论哪档，都可以随时用 PATCH 换掉——进行中的会话用旧配置跑完，新会话即刻生效。

五、把 Agent 嵌进网站：一行 script 的事

Studio 图形方式：Agents 列表 → 悬停你的 Agent → 点三个点（⋯）→ 选 </> Embed → 填允许的域名（安全特性：Agent 只会在这些域名下生效）→ 复制弹出的 embed 代码 → 粘贴到你网站 HTML 中想让它出现的位置。

手写方式：官方文档给的 embed 标签长这样，替换两个占位符即可：

<script
  type="module"
  src="https://agent.d-id.com/v2/index.js"
  data-mode="fabio"
  data-client-key="{client_key}"
  data-agent-id="{agent_id}"
  data-name="did-agent"
></script>

保存刷新后，网页角落会出现数字人挂件，访客点开即可对话。

Agent 嵌入自定义网站后的展开对话效果示例

Agent 嵌入第三方网站后的展开对话效果（官方帮助中心示例截图）

六、RAG 实战：知识库值不值得配，怎么配最稳

很多读者会问：我不传文档，直接让它用通用大模型回答不行吗？分场景说：

通用闲聊、天气寒暄、常识百科——不传文档完全够用，选 Ungrounded 模式，模型靠自身知识就能接住，还省了上传和处理文档的步骤。

你们公司/产品/内部制度相关的问题——必须传。通用模型根本不知道你们产品的参数、退换货政策、门店地址，硬答就是「一本正经地胡说」。挂上知识库后，流程变成：用户提问 → 模型把问题转成检索查询 → 在你的文档里找相关段落 → 只基于检索到的内容组织回答。回答有出处， hallucination（幻觉）被压到最低。

一个直观的验收方法：建两份知识库，A 只放「本公司支持 7 天无理由退货」，B 不放。分别问「你们支持几天退货」——A 版回答 7 天，B 版大概率编一个行业常见值。这一组对照能让你向老板证明知识库的必要性，也能帮你判断某类问题到底该「喂料」还是「调提示词」。

配知识库的三条实操纪律（均来自官方文档的限制说明）：

资料先清洗再上传：每个知识库最多 5 份文档、单份 50 万字符；把分散的 FAQ 合并成长文档，比建一堆小知识库好管理；
段落式文本优先：官方明确说表格和图片为主的文档效果差——价目表、参数对照表请改写成「一句话一个事实」的自然段；
能用 Input text 就别传文件：官方推荐直接粘贴（上限 8 万字符），因为它直接接入 LLM 提示词，没有检索环节的损耗，回答最稳。文件上传留给真正的大部头资料。

测试纪律：知识库状态必须是 done 再开始测（processing 状态下模型检索不到内容）；测试问题要覆盖「文档里明确写了的」「文档里没提的」「诱导瞎编的」三类——第三类比如「你们 CEO 是不是马斯克」，合格的知识库型 Agent 应当回答不知道或拒绝，而不是顺着说。

七、常见问题排查

分享出去的 Agent 谁掏钱：官方帮助中心明确——你把 Agent 分享给其他用户使用时，他们的对话消耗的是你账户的 credit。对外分享前先评估额度，别被白嫖到停机。
API 全部 401：Basic 认证头格式不对，或 Key 复制错。记住 Key 只在生成时显示一次，丢了只能重新生成。
网页里连不上、秒断：十有八九是 client key 的 allowed_domains 没包含当前页面域名（连本机调试也要把 http://localhost:3000 列进去）；本地端口换过就要重新签发。
Agent 答不上你传的资料：先查知识库状态是不是还卡在 processing（必须等 done）；再查模板是不是选了 rag-grounded/Grounded 但资料本身是表格图片为主——官方明说这类文档不友好，换成段落式文本或直接粘贴 Input text。
答非所问、爱自由发挥：接地模式选松了。严格场景用 rag-grounded（Grounded），并在 Agent Instructions 里约束回答范围。
Agent 突然不理人：官方明说 credit 耗尽时 Agent 会停止响应，去账户里确认余额。控制成本靠三招：Max response length 限长、Instructions 要求简答、话题回避挡闲聊。
改了 LLM/TTS 不生效：官方 FAQ 确认 PATCH 更新只对新会话生效，进行中的会话沿用旧配置，断开重连即可。
预览里没声音、脸不动：预览模式横幅已注明「sound and face animations won't show」，这是正常的，正式会话才有完整音画。
想用自己的模型：两条路——外部 Key：填自己的 OpenAI Key，D-ID 帮你路由；Custom LLM：自己部署模型端点，D-ID 把请求发给你。官方 FAQ 明确了这两者的区别。

八、来源与延伸

本文步骤、命令与参数均依据 D-ID 官方文档站 docs.d-id.com（Quickstart、API Keys、Agents、Knowledge、Agent Sessions、Agents Embed、Realtime Overview 各页）与官方帮助中心 help.d-id.com（如何创建交互式可视化 Agent、如何嵌入 Agent、Agent 计费方式等文章）及官方示例仓库 de-id/agents-sdk-demo 的 README 整理；限额与价格类数字以官方页面实时为准。本文步骤与图片依据 D-ID 官方文档及帮助中心整理，版权归原作者所有。

本篇用到的工具

D-ID

NUI（自然用户界面），借助 AI 之力，彻底改变人与数字世界的交互方式。