191 lines
5.1 KiB
Markdown
191 lines
5.1 KiB
Markdown
# AIGC Backend（Python FastAPI）
|
||
|
||
这是当前 Demo 的后端服务，负责三件事：
|
||
|
||
- 根据 `backend/.env` 与 `backend/config/custom_scene.py` 构建 `Custom` 场景配置
|
||
- 代理调用火山 RTC OpenAPI
|
||
- 在同一个 FastAPI 进程里提供本地 `CustomLLM` 回调接口 `/api/chat_callback`
|
||
|
||
## 环境要求
|
||
|
||
- Python 3.13+
|
||
|
||
## 安装依赖
|
||
|
||
```shell
|
||
uv sync
|
||
```
|
||
|
||
## 启动方式
|
||
|
||
```shell
|
||
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`。
|
||
|
||
先复制示例配置：
|
||
|
||
```shell
|
||
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
|
||
|
||
```dotenv
|
||
CUSTOM_LLM_MODE=ArkV3
|
||
CUSTOM_LLM_ENDPOINT_ID=your-ark-endpoint-id
|
||
```
|
||
|
||
### LLM 模式二：CustomLLM 本地回调
|
||
|
||
这个模式不是再起一个额外代理服务，而是直接由当前 `backend` 自己对外提供回调接口：
|
||
|
||
```dotenv
|
||
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` 改成公网地址，例如：
|
||
|
||
```dotenv
|
||
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，因此还需要：
|
||
|
||
```dotenv
|
||
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 占位实现，但首版默认不接入主链路，支持两种输入来源：
|
||
|
||
```dotenv
|
||
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_*` 配置，服务会在启动阶段直接报错，而不是进入半可用状态。
|