# digital-human-backend

**Repository Path**: pandaoknight/digital-human-backend

## Basic Information

- **Project Name**: digital-human-backend
- **Description**: 数字人后端 digital-human-backend
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-09
- **Last Updated**: 2026-02-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 数字人后端服务

## 项目概述

本项目是数字人展示系统的后端服务部分，主要负责状态管理、地图移动控制、RAG信息接收等功能的实现。作为系统的中间层，本服务连接了数字人Agent核心服务与前端展示系统。

## 系统架构

整体系统架构：

- **核心服务**
  - 数字人Agent服务 (负责感知唤醒词，状态管理，决策等)
  - LiveTalking服务 (提供语音交互能力)

- **外围服务**
  - RAG服务 (知识检索)
  - 知识图谱
  - Text2SQL服务
  - 展厅移动控制
  - 前端展示 (包括视频播放、OpenWebUI图文展示等)

- **本服务 (数字人后端)** 
  - 作为中间层，封装核心服务的接口
  - 提供前端所需的统一API
  - 连接ROS系统进行移动控制

## 后端开发规划

### 一阶段开发（周四完成第一轮联调）

1. **状态更新接口**
   - 对数字人Agent服务的状态管理接口进行封装
   - 提供状态查询和更新的API
   - 支持"4种状态"的实时更新和获取
   - 为前端提供按钮呈现所需数据

2. **地图移动控制接口**
   - 封装ROS系统的HTTP接口
   - 实现内网服务器到ROS系统的通信
   - 通过Android设备进行中转
   - 提供统一的移动控制API

3. **地图点位数据管理**
   - 维护展厅地图点位信息
   - 支持多种移动模式：
     - 模式一："数字人，到 A展厅1号点"
     - 模式二："数字人，移动到 B展厅2号点"
     - 特殊模式："数字人，过来欢迎XX嘉宾"（移动到欢迎点位）

### 二阶段开发

1. **RAG信息接收接口**
   - 接收RAG服务处理结果
   - 提供数据给OpenWebUI使用
   - 支持图文混合展示

2. **建议提示接口**
   - 提供预设问题列表
   - 支持分页查询
   - 用于前端交互界面中提供引导性问题

## API接口说明

### 数字人状态管理API

```
GET /api/status/digital-human
- 获取当前数字人状态（待命、倾听、思考、响应）
- 返回格式: {"state": "STANDBY", "description": "待命"}

POST /api/status/digital-human
- 更新数字人状态
- 参数: state_name (状态名称，如"待命"、"倾听"等)
- 返回格式: {"state": "LISTENING", "description": "倾听"}
```

### 场景状态管理API

```
GET /api/status/scene
- 获取当前场景状态（基础对话、图文列表、视频播放等）
- 返回格式: {"state": "BASIC_DIALOG", "description": "基础对话"}

POST /api/status/scene
- 更新场景状态
- 参数: state_name (状态名称，如"基础对话"、"图文列表"等)
- 返回格式: {"state": "VIDEO_PLAYING", "description": "视频播放"}
```

### WebSocket接口

```
WS /ws
- 建立WebSocket连接实时接收状态更新
- 接收格式: {"digital_human_state": {"value": "待命"}, "scene_state": {"value": "基础对话"}}
```

### 建议提示API

```
GET /api/suggestion/prompts
- 获取建议提示列表
- 参数: page (页码，默认1), page_size (每页条数，默认10)
- 返回格式: {
    "total": 8,
    "page": 1,
    "page_size": 5,
    "items": [
        {"content": "数之联什么时候诞生的"},
        {"content": "数之联的核心技术体系是什么"},
        ...
    ]
}
```

### 移动控制API (计划中)

```
POST /api/movement/goto
- 控制数字人移动到指定位置
- 参数: point_id(点位ID)

GET /api/movement/points
- 获取所有可用点位信息

POST /api/movement/welcome
- 触发欢迎模式
- 参数: guest_name(嘉宾名称，可选)
```

### RAG信息API (计划中)

```
POST /api/rag/result
- 接收RAG查询结果
- 参数: query(查询内容), result(查询结果)
```

### ASR配置接口

```
GET /api/asr/config
- 获取ASR服务的完整配置
- 返回格式: {
    "configs": [...],  // LLM配置列表
    "selected_config": "config_id",  // 当前选中的配置ID
    "parameters": {  // 全局参数设置
        "temperature": 0.7,
        "top_p": 0.9,
        "max_tokens": 2048,
        "stop": null,
        "n": 1
    },
    "service_type": "brain"  // 当前选择的服务类型: "brain" 或 "llm"
}

POST /api/asr/config
- 保存ASR服务的完整配置
- 参数: 同上返回格式
- 返回格式: {"status": "success", "message": "配置已保存"}

PATCH /api/asr/config
- 部分更新ASR服务配置
- 参数: 可包含任意配置字段的子集
- 返回格式: {"status": "success", "message": "配置已更新"}

PATCH /api/asr/config/parameters
- 仅更新参数设置
- 参数: 参数对象
- 返回格式: {"status": "success", "message": "参数已更新"}

PATCH /api/asr/config/service_type
- 仅更新服务类型
- 参数: 服务类型字符串 ("brain" 或 "llm")
- 例如: {"service_type": "brain"}
- 返回格式: {"status": "success", "message": "服务类型已更新"}

PATCH /api/asr/config/llm_configs
- 更新LLM配置列表和选择的配置
- 参数: {
    "configs": [...],  // LLM配置列表
    "selected_config": "config_id"  // 可选，当前选中的配置ID
}
- 返回格式: {"status": "success", "message": "LLM配置已更新"}
```

## 目录结构

```
digital-human-backend/
├── app/
│   ├── main.py               # 主应用入口
│   ├── routers/              # API路由
│   │   ├── status.py         # 状态管理路由
│   │   ├── suggestion.py     # 建议提示路由
│   │   └── websocket.py      # WebSocket路由
│   ├── services/             # 服务层
│   │   └── state_service.py  # 状态管理服务
│   └── models/               # 数据模型
│       ├── state.py          # 状态相关模型
│       └── suggestion.py     # 建议提示相关模型
├── examples/                 # 示例前端
│   ├── index.html            # 导航页面
│   ├── console/              # 控制台页面
│   │   └── index.html
│   ├── client/               # 接收端页面
│   │   └── index.html
│   └── suggestion/           # 建议提示页面
│       └── index.html
├── requirements.txt          # 依赖管理
└── README.md                 # 项目文档
```

## 运行方法

1. 安装依赖：
```
pip install -r requirements.txt
```

2. 运行服务：
```
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

3. 访问API文档：
```
http://localhost:8000/docs
```

4. 访问示例页面：
   - 导航页: http://localhost:8000/examples/index.html
   - 控制台: http://localhost:8000/examples/console/index.html
   - 接收端: http://localhost:8000/examples/client/index.html
   - 建议提示: http://localhost:8000/examples/suggestion/index.html

## 示例用法

### 控制台页面

控制台页面提供了简单的UI界面来控制数字人状态和场景状态，可以直接点击按钮来更新状态。同时，页面还显示了相应的API请求示例，便于集成到其他系统中。

### 接收端页面

接收端页面提供了两种方式获取状态更新：
1. HTTP轮询：每2秒请求一次API获取最新状态
2. WebSocket：建立WebSocket连接实时接收状态更新

### 建议提示页面

建议提示页面展示了如何获取和使用建议提示列表，支持分页查询，可以用作用户交互界面中的预设问题列表。

## 部署指南

待补充...