# asrdemo

**Repository Path**: jiang_dn/asrdemo

## Basic Information

- **Project Name**: asrdemo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ASR 校园套餐语音交互系统

## 快速启动

```bash
# 方式1: 使用启动脚本（推荐）
./start_server.sh        # macOS/Linux
start_server.bat          # Windows

# 方式2: 直接启动
# 1. 激活虚拟环境
. venv/bin/activate

# 2. 启动服务
python web_server.py --host localhost --port 8000
```

## 访问地址

```
Web 界面:  http://localhost:8000
API 文档:  http://localhost:8000/docs
API 状态:  http://localhost:8000/api/status
```

## 功能说明

### 🎯 企业级主界面功能

#### 左侧三栏式面板

1. **状态标签页**
   - 系统状态实时监控（Redis、API、FFmpeg）
   - 会话信息显示（会话 ID、对话轮次）
   - ASR 引擎选择（Fun-ASR / Paraformer / Qwen-ASR-Realtime / Qwen3-Omni-Flash 端到端）
   - 诊断工具（麦克风检查、系统检查、音频测试）

2. **统计标签页**
   - 今日统计数据（总请求数、成功率、平均耗时）
   - 意图分布 TOP 5
   - 实时数据更新

3. **历史标签页**
   - 会话历史查看
   - 刷新历史记录
   - 清空当前会话

#### 顶部导航栏

- **🏥 健康检查**: 全面的系统健康检查
- **📊 性能监控**: 实时性能指标和趋势
- **在线状态**: 服务连接状态指示

#### 主内容区域

1. **语音对话**
   - 点击麦克风按钮录音
   - 支持 ASR → NLU → TTS 完整流程
   - 实时流程状态显示

2. **流程状态**
   - ASR、上下文、NLU、意图、指代、TTS 六步流程
   - 每步状态实时更新（处理中/完成/失败）

3. **NLU 分析**
   - ASR 识别结果（含情绪）
   - 意图识别（含置信度）
   - 指代消解结果
   - 槽位抽取结果

## 环境要求

- Python 3.8+
- ffmpeg（用于音频格式转换）
- ALIBABA_BAILIAN_SK 环境变量

### 安装 ffmpeg

```bash
# macOS (使用 Homebrew)
brew install ffmpeg

# macOS (使用 MacPorts)
sudo port install ffmpeg

# Linux (Ubuntu/Debian)
sudo apt-get install ffmpeg
```

## 故障排查

### ASR 返回空结果

1. 检查麦克风：使用诊断工具的"检查麦克风和录音"
2. 检查录音：使用"音频录制测试"单独录制并预览
3. 检查系统：使用"检查系统状态"查看完整诊断信息
4. 确保录音至少 2-3 秒

### 音频格式问题

系统会自动尝试将 WebM 格式转换为 WAV（需要 ffmpeg）。如果转换失败会降级使用原格式。

## 文件说明

- `web_server.py`: FastAPI 服务器
- `web_interface.html`: 主界面（包含所有诊断和测试功能）
- `main.py`: 核心业务逻辑
- `integrations/bailian_client.py`: ASR/TTS 客户端

## 测试建议

1. 首次使用先运行"检查系统状态"
2. 使用"音频录制测试"确认麦克风和录音正常
3. 开始正常语音对话

## 注意事项

- 必须使用 `http://localhost:8000` 而非 `localhost:8000`（浏览器安全限制）
- 首次录音需要授权麦克风权限
- 录音时请清晰说话，至少 2-3 秒
- 在安静环境中录音以获得更好的识别效果

## 📊 企业级特性

### 实时监控
- 系统健康状态实时检查
- 性能指标自动收集
- 响应时间追踪
- 成功率统计

### 数据分析
- 意图分布统计
- 会话历史管理
- 音频/文本请求分离统计
- TOP 5 意图排名

### 诊断能力
- 全面的系统健康检查
- 依赖项验证（Redis、FFmpeg、API Key）
- 麦克风功能测试
- 录音质量检查

### 异常处理
- 全局异常捕获
- 详细错误日志
- 优雅降级机制
- 自动故障恢复

## 📚 更多文档

- [QUICK_START.md](QUICK_START.md) - 快速开始指南
- [ENTERPRISE_FEATURES.md](ENTERPRISE_FEATURES.md) - 企业级功能详细说明
- [DEPLOYMENT_CHECKLIST.md](DEPLOYMENT_CHECKLIST.md) - 部署检查清单
- [CODEBUDDY.md](CODEBUDDY.md) - 开发者指南