bluebone/rtc-voice-chat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
41 Commits 1 Branch 0 Tags 14 MiB
Python 50.3%
HTML 25.1%
JavaScript 23.8%
Dockerfile 0.8%
275828ce1c
Go to file
lengbone 275828ce1c refactor: simplify LLM integration by replacing volcenginesdkarkruntime with standard OpenAI client and unifying environment configuration.
2026-03-31 20:57:49 +08:00
backend refactor: simplify LLM integration by replacing volcenginesdkarkruntime with standard OpenAI client and unifying environment configuration. 2026-03-31 20:57:49 +08:00
frontend 配置成功。 2026-03-28 18:14:20 +08:00
.gitignore 配置成功。 2026-03-28 18:14:20 +08:00
CLAUDE.md refactor: simplify LLM integration by replacing volcenginesdkarkruntime with standard OpenAI client and unifying environment configuration. 2026-03-31 20:57:49 +08:00
README.md refactor: simplify LLM integration by replacing volcenginesdkarkruntime with standard OpenAI client and unifying environment configuration. 2026-03-31 20:57:49 +08:00

README.md

交互式AIGC场景 AIGC Demo

此 Demo 为简化版本, 如您有 1.5.x 版本 UI 的诉求, 可切换至 1.5.1 分支。 跑通阶段时, 无须关心代码实现。当前推荐直接使用 backend/.env + backend/config/custom_scene.py 完成 Custom 场景配置。

简介

  • 在 AIGC 对话场景下，火山引擎 AIGC-RTC Server 云端服务，通过整合 RTC 音视频流处理，ASR 语音识别，大模型接口调用集成，以及 TTS 语音生成等能力，提供基于流式语音的端到端AIGC能力链路。
  • 用户只需调用基于标准的 OpenAPI 接口即可配置所需的 ASR、LLM、TTS 类型和参数。火山引擎云端计算服务负责边缘用户接入、云端资源调度、音视频流压缩、文本与语音转换处理以及数据订阅传输等环节。简化开发流程，让开发者更专注在对大模型核心能力的训练及调试，从而快速推进AIGC产品应用创新。
  • 同时火山引擎 RTC拥有成熟的音频 3A 处理、视频处理等技术以及大规模音视频聊天能力，可支持 AIGC 产品更便捷的支持多模态交互、多人互动等场景能力，保持交互的自然性和高效性。

【必看】环境准备

本项目已重构为 monorepo 结构，前端位于 frontend/，Python 后端位于 backend/。

前端环境：Node 16.0+ 后端环境：Python 3.13+

1. 运行环境

需要准备两个 Terminal，分别启动后端服务和前端页面。

2. 服务开通

开通 ASR、TTS、LLM、RTC 等服务，可参考 开通服务 进行相关服务的授权与开通。

3. 场景配置

当前真正生效的主配置入口是 backend/.env + backend/config/custom_scene.py。

您可以自定义具体场景, 并按需根据模版填充 SceneConfig、AccountConfig、RTCConfig、VoiceChat 中需要的参数。

Demo 中以 Custom 场景为例，您也可以自行新增其他 JSON 场景。

Custom 场景建议先执行以下步骤：

cp backend/.env.example backend/.env

注意：

  • SceneConfig：场景的信息，例如名称、头像等。
  • AccountConfig：Custom 场景默认从 backend/.env 读取 AK/SK，其他场景仍在 JSON 中配置。
  • RTCConfig：场景下的 RTC 配置。
    • AppId、AppKey 可从 https://console.volcengine.com/rtc/aigc/listRTC 中获取。
    • Custom 场景的 AppId、AppKey、RoomId、UserId、Token 可通过 backend/.env 注入。
    • RoomId、UserId 可自定义也可不填，交由服务端生成。
  • VoiceChat: 场景下的 AIGC 配置。
    • Custom 场景的 TaskId、Agent 用户信息、欢迎语、System Message 以及 LLM 模式参数均通过 backend/.env 注入。
    • 固定使用 CustomLLM 模式，由本后端提供回调接口，推荐通过 ngrok 暴露公网地址。
    • 可参考 https://www.volcengine.com/docs/6348/1558163 中参数描述，完整填写参数内容。
    • ASRConfig、TTSConfig、AvatarConfig 等复杂结构由 backend/config/custom_scene.py 维护默认值，并从 backend/.env 读取关键运行参数。
    • 当前首版默认不启用 RAG 主链路，backend/services/rag_service.py 仅保留为后续扩展位。
    • 可通过 快速跑通 Demo 快速获取参数，再分别填入 backend/.env 和 backend/config/custom_scene.py 的默认结构中。

第三方 CustomLLM 接入

当前 backend 自己提供回调接口，核心配置：

CUSTOM_LLM_URL=http://127.0.0.1:3001/api/chat_callback
CUSTOM_LLM_API_KEY=your-callback-token
LOCAL_LLM_API_KEY=your-ark-api-key
LOCAL_LLM_MODEL=your-ark-endpoint-id

本地起好 backend 以后，用 ngrok 暴露 3001 端口，再把 CUSTOM_LLM_URL 改成公网地址：

CUSTOM_LLM_URL=https://your-ngrok-domain.ngrok-free.app/api/chat_callback

说明：

  • CUSTOM_LLM_URL 是写进 StartVoiceChat.LLMConfig.Url 的地址
  • 默认可以先用本地地址启动服务，等 ngrok 跑起来后再改成公网 https 地址
  • 当前 backend 内置的固定回调路由是 POST /api/chat_callback
  • RTC_OPENAPI_VERSION 默认使用 2025-06-01

快速开始

请注意，服务端和 Web 端都需要启动, 启动步骤如下:

后端服务（Python FastAPI）

cd backend
cp .env.example .env
uv sync
uv run uvicorn server:app --host 0.0.0.0 --port 3001 --reload

前端页面

cd frontend
npm install
npm run dev

常见问题

问题 解决方案
如何使用第三方模型、Coze Bot 当前主配置入口是 backend/.env + backend/config/custom_scene.py。如果接自己的模型，推荐使用当前 backend 内置的 /api/chat_callback 作为 CustomLLM 回调接口，再通过 ngrok 暴露公网地址，并把它填到 CUSTOM_LLM_URL。
启动智能体之后, 对话无反馈，或者一直停留在 "AI 准备中, 请稍侯"；在启用数字人的情况下，一直停留在“数字人准备中，请稍候”
  • 可能因为控制台中相关权限没有正常授予，请参考流程再次确认下是否完成相关操作。此问题的可能性较大，建议仔细对照是否已经将相应的权限开通。
  • 参数传递可能有问题, 例如参数大小写、类型等问题，请再次确认下这类型问题是否存在。
  • 相关资源可能未开通或者用量不足/欠费，请再次确认。
  • 请检查当前使用的模型 ID / 数字人 AppId / Token 等内容都是正确且可用的。
  • 数字人服务有并发限制，当达到并发限制时，同样会表现为一直停留在“数字人准备中”状态
    		•
    浏览器报了 Uncaught (in promise) r: token_error 错误 请检查您填在项目中的 RTC Token 是否合法，检测用于生成 Token 的 UserId、RoomId 以及 Token 本身是否与项目中填写的一致；或者 Token 可能过期, 可尝试重新生成下。
    [StartVoiceChat]Failed(Reason: The task has been started. Please do not call the startup task interface repeatedly.) 报错 如果设置的 RoomId、UserId 为固定值，重复调用 startAgent 会导致出错，只需先调用 stopAgent 后再重新 startAgent 即可。
    为什么麦克风、摄像头开启失败？浏览器报了TypeError: Cannot read properties of undefined (reading 'getUserMedia') 检查当前页面是否为安全上下文（简单来说，检查当前页面是否为 localhost 或者 是否为 https 协议）。浏览器限制 getUserMedia 只能在安全上下文中使用。
    为什么我的麦克风正常、摄像头也正常，但是设备没有正常工作? 可能是设备权限未授予，详情可参考 Web 排查设备权限获取失败问题。
    接口调用时, 返回 "Invalid 'Authorization' header, Pls check your authorization header" 错误 Custom 场景请检查 backend/.env 中的 CUSTOM_ACCESS_KEY_ID / CUSTOM_SECRET_KEY；其他场景请检查对应 backend/scenes/*.json 中的 AK/SK
    什么是 RTC Real Time Communication, RTC 的概念可参考官网文档。
    不清楚什么是主账号，什么是子账号 可以参考官方概念 。
    我有自己的服务端了, 我应该怎么让前端调用我的服务端呢 修改 frontend/src/config/index.ts 中的 AIGC_PROXY_HOST 请求域名；如需同步调整接口路由，可再看 frontend/src/app/api.ts 里的 BasicAPIs / AigcAPIs

    如果有上述以外的问题，欢迎联系我们反馈。

    相关文档

    更新日志

    OpenAPI 更新

    参考 OpenAPI 更新 中与 实时对话式 AI 相关的更新内容。

    Demo 更新

    [1.6.0]

    • 2025-09-30
      • 更新数字人场景相关配置
    • 2025-07-08
      • 更新 RTC Web SDK 版本至 4.66.20
    • 2025-06-26
      • 修复进房有问题的 BUG
    • 2025-06-23
      • 简化 Demo 使用, 配置归一化。
      • 删除无用组件。
      • 追加服务端 README。
    • 2025-06-18
      • 更新 RTC Web SDK 版本至 4.66.16
      • 更新 UI 和参数配置方式
      • 更新 Readme 文档
      • 追加 Node 服务的参数检测能力
      • 追加 Node 服务的 Token 生成能力