rtc-voice-chat/backend

AIGC Backend（Python FastAPI）

这是当前 Demo 的后端服务，负责三件事：

• 根据 backend/.env 与 backend/config/custom_scene.py 构建 Custom 场景配置
• 代理调用火山 RTC OpenAPI
• 在同一个 FastAPI 进程里提供本地 CustomLLM 回调接口 /api/chat_callback

环境要求

• Python 3.13+

安装依赖

uv sync

启动方式

uv run uvicorn server:app --host 0.0.0.0 --port 3001 --reload

服务默认监听 http://localhost:3001。

配置方式

Custom 场景固定使用：

• backend/.env
• backend/config/custom_scene.py

不再依赖 backend/scenes/Custom.json。

先复制示例配置：

cp .env.example .env

必填基础配置

变量名	说明
CUSTOM_ACCESS_KEY_ID	火山引擎 AK
CUSTOM_SECRET_KEY	火山引擎 SK
CUSTOM_RTC_APP_ID	RTC 应用 ID，同时作为 RTCConfig.AppId 和 VoiceChat.AppId
CUSTOM_TASK_ID	AIGC 任务 ID
CUSTOM_AGENT_USER_ID	智能体用户 ID
CUSTOM_AGENT_WELCOME_MESSAGE	智能体欢迎语
CUSTOM_LLM_SYSTEM_MESSAGE	System Message
CUSTOM_ASR_APP_ID	ASR 应用 ID
CUSTOM_TTS_APP_ID	TTS 应用 ID

RTC 相关配置

变量名	说明
CUSTOM_RTC_APP_KEY	未提供 CUSTOM_RTC_TOKEN 时，用于自动生成 Token
CUSTOM_RTC_ROOM_ID	房间 ID，留空时服务端自动生成
CUSTOM_RTC_USER_ID	用户 ID，留空时服务端自动生成
CUSTOM_RTC_TOKEN	RTC Token；留空时服务端会自动生成
RTC_OPENAPI_VERSION	StartVoiceChat/StopVoiceChat 使用的 OpenAPI 版本，默认 2025-06-01

LLM 模式一：ArkV3

CUSTOM_LLM_MODE=ArkV3
CUSTOM_LLM_ENDPOINT_ID=your-ark-endpoint-id

LLM 模式二：CustomLLM 本地回调

这个模式不是再起一个额外代理服务，而是直接由当前 backend 自己对外提供回调接口：

CUSTOM_LLM_MODE=CustomLLM
CUSTOM_LLM_URL=http://127.0.0.1:3001/api/chat_callback
CUSTOM_LLM_API_KEY=your-callback-token
CUSTOM_LLM_MODEL_NAME=my-model

推荐调试流程：

1. 先启动当前 backend
2. 用 ngrok 暴露 3001 端口
3. 把 CUSTOM_LLM_URL 改成公网地址，例如：

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

CUSTOM_LLM_API_KEY 是火山调用你这个本地回调接口时带上的 Bearer Token；如果你不需要这层鉴权，可以留空。

当前 backend 内置的 Ark 配置

/api/chat_callback 内部会直接调用方舟 SDK，因此还需要：

ARK_API_KEY=your-ark-api-key
ARK_ENDPOINT_ID=your-ark-endpoint-id
ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
ARK_TIMEOUT_SECONDS=1800
LOCAL_LLM_SYSTEM_PROMPT=
LOCAL_LLM_TEMPERATURE=0.3

如果 LOCAL_LLM_SYSTEM_PROMPT 留空，会回退使用 CUSTOM_LLM_SYSTEM_MESSAGE。

可选 RAG 占位配置

当前仓库内置了一个最小 RAG 占位实现，但首版默认不接入主链路，支持两种输入来源：

RAG_STATIC_CONTEXT=
RAG_CONTEXT_FILE=

• RAG_STATIC_CONTEXT：直接写死一段知识文本
• RAG_CONTEXT_FILE：从本地文件读取全文作为知识上下文

后续如果你要接真实向量检索，直接替换 services/rag_service.py 里的 retrieve，再把 server.py 主链路接回去即可。

CustomLLM 可选参数

变量名	说明
CUSTOM_LLM_HISTORY_LENGTH	历史轮数
CUSTOM_LLM_PREFILL	是否开启 Prefill
CUSTOM_LLM_CUSTOM	透传到请求体的 custom 字段
CUSTOM_LLM_EXTRA_HEADER_JSON	额外请求头，JSON 对象字符串
CUSTOM_LLM_ENABLE_PARALLEL_TOOL_CALLS	是否开启并行工具调用
CUSTOM_LLM_TEMPERATURE	透传温度参数
CUSTOM_LLM_TOP_P	透传 top_p
CUSTOM_LLM_MAX_TOKENS	透传 max_tokens

其余 ASR、TTS、数字人相关可选字段，请直接参考 backend/.env.example。

接口说明

POST /getScenes

返回场景列表，并自动补齐：

• RoomId
• UserId
• Token

POST /proxy?Action={Action}&Version={Version}

代理转发到火山 RTC OpenAPI。

支持：

• StartVoiceChat
• StopVoiceChat

请求体必须包含 SceneID。

版本优先级如下：

1. 查询参数里的 Version
2. 环境变量 RTC_OPENAPI_VERSION
3. 默认值 2025-06-01

POST /api/chat_callback

这是当前 backend 内置的 CustomLLM 回调接口，也是你配置给火山 LLMConfig.Url 的目标地址。

行为说明：

• 接收火山传入的 messages
• 可选校验 Authorization: Bearer <CUSTOM_LLM_API_KEY>
• 内部调用 services/local_llm_service.py 里的 Ark SDK
• 按火山要求返回 text/event-stream
• 结束时一定补 data: [DONE]

POST /debug/chat

本地调试 LLM 文本流，不经过 RTC。

GET /debug/rag?query=...

本地调试 RAG 返回结果。

说明

• 当前前端不会直接决定模型供应商，模型切换统一由后端环境变量控制。
• 如果缺少关键 CUSTOM_* 或 ARK_* 配置，服务会在启动阶段直接报错，而不是进入半可用状态。