guoyu/log/Whisper测试指南.md

# Whisper 服务连接测试指南

## 问题描述
Whisper 服务已启动，但 Java 应用无法连接。

## 测试方法

### 方法1：使用命令行脚本（推荐）

#### Windows 服务器
```powershell
# 进入目录
cd C:\Users\Administrator\Desktop\Project\ry_study\log

# 运行测试脚本
powershell -ExecutionPolicy Bypass -File .\test_whisper_connection.ps1
```

#### Linux 服务器
```bash
# 进入目录
cd /path/to/project/log

# 添加执行权限
chmod +x test_whisper_connection.sh

# 运行测试脚本
./test_whisper_connection.sh
```

### 方法2：使用 Java 测试接口

1. **启动 Java 应用**
   ```bash
   # 如果未启动，先启动
   cd Study-Vue-redis
   mvn clean package
   java -jar ry-study-admin/target/ry-study-admin.jar
   ```

2. **访问测试接口**
   
   #### 接口1：检查连接状态
   ```bash
   # 方式1：浏览器访问
   http://localhost:8080/test/whisper/check
   
   # 方式2：curl 命令
   curl http://localhost:8080/test/whisper/check
   ```
   
   **预期响应（成功）：**
   ```json
   {
     "code": 200,
     "msg": "连接成功",
     "data": {
       "injected": true,
       "available": true,
       "status": "运行中",
       "serviceInfo": "本地Whisper服务 (URL: http://localhost:5001, 状态: 运行中✅)",
       "message": "Whisper 服务正常运行，可以进行语音识别"
     }
   }
   ```
   
   **预期响应（失败）：**
   ```json
   {
     "code": 500,
     "msg": "连接失败",
     "data": {
       "injected": true,
       "available": false,
       "status": "未启动",
       "message": "无法连接到 Whisper 服务（http://localhost:5001）",
       "troubleshooting": { ... }
     }
   }
   ```

   #### 接口2：查看详细信息
   ```bash
   curl http://localhost:8080/test/whisper/info
   ```

   #### 接口3：上传音频测试识别
   ```bash
   # 准备一个测试音频文件 test.mp3
   curl -X POST http://localhost:8080/test/whisper/recognize \
     -F "file=@test.mp3"
   ```

   #### 接口4：上传音频测试评测
   ```bash
   curl -X POST http://localhost:8080/test/whisper/evaluate \
     -F "file=@test.mp3" \
     -F "text=春眠不觉晓"
   ```

### 方法3：手动测试 Whisper 服务

#### 测试 Whisper 健康检查
```bash
# 方式1：curl
curl http://localhost:5001/health

# 方式2：浏览器
# 访问 http://localhost:5001/health

# 预期响应：
{"status":"ok"}
```

#### 测试 Whisper 识别接口
```bash
# 准备测试音频
curl -X POST http://localhost:5001/recognize \
  -F "file=@test.mp3" \
  -F "language=zh"

# 预期响应：
{
  "code": 200,
  "msg": "识别成功",
  "data": {
    "text": "春眠不觉晓"
  }
}
```

## 常见问题排查

### 问题1：端口未监听
**现象：** `❌ 端口 5001 未被监听`

**解决方案：**
1. 检查 Whisper 服务是否启动
   ```bash
   # Windows
   netstat -ano | findstr 5001
   
   # Linux
   lsof -i:5001
   netstat -tuln | grep 5001
   ```

2. 启动 Whisper 服务
   ```bash
   cd <whisper_service_directory>
   python app.py
   # 或
   python3 app.py
   ```

### 问题2：连接被拒绝
**现象：** `❌ HTTP 连接失败（连接被拒绝）`

**可能原因：**
- Whisper 服务未启动
- Whisper 监听地址错误（只监听 127.0.0.1 而不是 0.0.0.0）

**解决方案：**
1. 检查 Whisper 服务配置，确保监听 `0.0.0.0:5001` 或 `localhost:5001`
2. 查看 Whisper 启动日志，确认监听地址

### 问题3：防火墙阻止
**现象：** `❌ HTTP 连接超时`

**解决方案：**
```bash
# Windows - 添加防火墙规则
netsh advfirewall firewall add rule name="Whisper Service" dir=in action=allow protocol=TCP localport=5001

# Linux (CentOS/RHEL)
sudo firewall-cmd --add-port=5001/tcp --permanent
sudo firewall-cmd --reload

# Linux (Ubuntu)
sudo ufw allow 5001/tcp
```

### 问题4：服务注入失败
**现象：** `❌ LocalWhisperService 未注入`

**解决方案：**
1. 检查 `LocalWhisperService.java` 是否有 `@Service` 注解
2. 确认类在 Spring 扫描的包路径下
3. 重新编译项目
   ```bash
   mvn clean compile
   ```

### 问题5：端口冲突
**现象：** Whisper 启动失败，提示端口已被占用

**解决方案：**
```bash
# 查找占用端口的进程
# Windows
netstat -ano | findstr 5001
taskkill /PID <进程ID> /F

# Linux
lsof -i:5001
kill -9 <PID>

# 或修改 Whisper 服务端口，同时修改 LocalWhisperService.java 中的配置
```

## 配置说明

### LocalWhisperService 配置
文件位置：`ry-study-system/src/main/java/com/ddnai/system/service/voice/LocalWhisperService.java`

```java
// Whisper服务地址
private static final String WHISPER_URL = "http://localhost:5001";
```

如果 Whisper 运行在不同端口，需要修改此配置。

### Whisper 服务配置
确保 Whisper Python 服务配置如下：

```python
# app.py
if __name__ == '__main__':
    app.run(
        host='0.0.0.0',  # 允许外部访问
        port=5001,       # 端口
        debug=False
    )
```

## 日志查看

### Java 应用日志
```bash
# 查看 Whisper 相关日志
tail -f logs/sys-info.log | grep -i whisper

# 查看完整日志
tail -f logs/sys-info.log
```

### Whisper 服务日志
查看 Whisper Python 服务的启动日志，确认：
- 服务启动成功
- 监听端口正确
- 模型加载成功

## 成功标志

当所有测试通过时，你应该看到：

1. **端口检查：** ✅ 端口 5001 已被监听
2. **HTTP 连接：** ✅ HTTP 连接成功
3. **服务状态：** ✅ Whisper 服务连接成功
4. **测试接口：** 返回 `"available": true`

## 下一步

测试成功后，可以在 APP 中使用语音测评功能：
1. 打开 APP
2. 进入"语音测评"页面
3. 选择测评内容
4. 点击"开始说话"
5. 系统会自动使用本地 Whisper 进行识别和评分

## 技术支持

如果上述方法都无法解决问题，请提供以下信息：
1. 测试脚本的完整输出
2. Java 应用日志（包含 Whisper 相关日志）
3. Whisper 服务启动日志
4. 服务器操作系统版本
5. Java 版本和 Python 版本