# 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` |

### CustomLLM 回调配置

当前 `backend` 自己对外提供回调接口，火山 RTC 会回调 `CUSTOM_LLM_URL` 指定的地址：

```dotenv
CUSTOM_LLM_URL=http://127.0.0.1:3001/api/chat_callback
CUSTOM_LLM_API_KEY=your-callback-token
```

推荐调试流程：

1. 先启动当前 `backend`
2. 把 `CUSTOM_LLM_URL` 改成后端服务的公网 HTTPS 地址，例如：

```dotenv
CUSTOM_LLM_URL=https://api.yourdomain.com/v1/api/chat_callback
```

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

### 当前 backend 内置的本地 LLM 回调配置

`/api/chat_callback` 内部会通过 OpenAI SDK 调用方舟，因此还需要：

```dotenv
LOCAL_LLM_API_KEY=your-ark-api-key
LOCAL_LLM_MODEL=your-ark-endpoint-id
LOCAL_LLM_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
LOCAL_LLM_TIMEOUT_SECONDS=1800
LOCAL_LLM_TEMPERATURE=0.3
```

System Prompt 统一使用 `CUSTOM_LLM_SYSTEM_MESSAGE`，Thinking 模式统一使用 `CUSTOM_LLM_THINKING_TYPE`。

### 可选 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_*` 或 `LOCAL_LLM_*` 配置，服务会在启动阶段直接报错，而不是进入半可用状态。