# AI 女友项目 - 快速参考

## 🚀 启动命令

```bash
# 方法 1：使用启动脚本（推荐）
双击 "启动项目.bat"

# 方法 2：手动启动
# PHP 服务器
cd xunifriend_RaeeC/public
php -S 0.0.0.0:30100 router.php

# Python 后端
python -m uvicorn lover.main:app --host 0.0.0.0 --port 30101 --reload
```

## 🌐 服务地址

| 服务 | 地址 | 说明 |
|------|------|------|
| PHP 后台 | http://127.0.0.1:30100/admin | 用户管理、后台管理 |
| Python API | http://127.0.0.1:30101/docs | AI 功能、API 文档 |
| 健康检查 | http://127.0.0.1:30101/health | 服务状态检查 |

## 📡 API 端点

### 语音对话

| 端点 | 方法 | 功能 | 响应时间 |
|------|------|------|---------|
| `/voice/call/asr` | POST | 仅 ASR 识别 | 3-5秒 |
| `/voice/call/conversation` | POST | 完整对话（ASR+LLM+TTS） | 7-15秒 |

### 请求格式

```json
{
  "audio_data": "base64编码的音频",
  "format": "wav"
}
```

### 响应格式

**ASR 模式**:
```json
{
  "code": 1,
  "msg": "ok",
  "data": {
    "text": "识别的文字"
  }
}
```

**对话模式**:
```json
{
  "code": 1,
  "msg": "ok",
  "data": {
    "user_text": "用户说的话",
    "ai_text": "AI的回复",
    "audio_data": "base64编码的AI语音",
    "audio_format": "mp3"
  }
}
```

## 🔧 前端配置

```javascript
// xuniYou/utils/request.js

// 本地开发
export const baseURL = 'http://127.0.0.1:30100'
export const baseURLPy = 'http://127.0.0.1:30101'

// 局域网测试（替换为你的电脑 IP）
export const baseURL = 'http://192.168.1.141:30100'
export const baseURLPy = 'http://192.168.1.141:30101'
```

## 🔍 调试命令

```bash
# 检查端口占用
netstat -ano | findstr :30100
netstat -ano | findstr :30101

# 测试健康检查
curl http://127.0.0.1:30101/health

# 查看进程
tasklist | findstr php.exe
tasklist | findstr python.exe

# 停止进程
taskkill /F /IM php.exe
taskkill /F /IM python.exe
```

## 📋 环境变量

```bash
# .env 文件

# DashScope API Key（必需）
DASHSCOPE_API_KEY=sk-xxx

# OSS 配置（语音功能必需）
ALIYUN_OSS_ACCESS_KEY_ID=xxx
ALIYUN_OSS_ACCESS_KEY_SECRET=xxx
ALIYUN_OSS_BUCKET_NAME=xxx
ALIYUN_OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
ALIYUN_OSS_CDN_DOMAIN=https://xxx.oss-cn-hangzhou.aliyuncs.com

# 数据库
DATABASE_URL=mysql+pymysql://root:password@localhost:3306/fastadmin

# LLM 配置
LLM_MODEL=qwen-plus
LLM_TEMPERATURE=0.8
LLM_MAX_TOKENS=2000

# TTS 配置
VOICE_CALL_TTS_MODEL=cosyvoice-v2
VOICE_CALL_TTS_VOICE=longxiaochun_v2

# ASR 配置
VOICE_CALL_ASR_MODEL=paraformer-v2
VOICE_CALL_ASR_SAMPLE_RATE=16000
```

## 🐛 常见错误

| 错误 | 原因 | 解决方案 |
|------|------|---------|
| 端口被占用 | 服务已在运行 | 使用启动脚本自动清理 |
| ModuleNotFoundError | Python 依赖缺失 | `pip install -r lover/requirements.txt` |
| 连接失败 | 前端配置错误 | 检查 `request.js` 中的 IP 和端口 |
| ASR 识别失败 | 音频格式错误 | 使用 WAV 格式，16kHz，单声道 |
| OSS 上传失败 | OSS 配置错误 | 检查 `.env` 中的 OSS 配置 |

## 📊 性能指标

| 步骤 | 时间 |
|------|------|
| 录音 | 2-5秒 |
| ASR 识别 | 2-5秒 |
| LLM 生成 | 1-3秒 |
| TTS 合成 | 1-2秒 |
| **总计** | **7-15秒** |

## 🎯 测试流程

1. 双击 `启动项目.bat`
2. 等待两个窗口启动完成
3. 访问 http://127.0.0.1:30101/docs 验证
4. 打开前端应用
5. 进入语音通话页面
6. 按住说话按钮
7. 说话 2-3 秒
8. 松开按钮
9. 等待 AI 回复
10. 听到 AI 语音

## 📞 技术支持

遇到问题时提供：
1. 前端控制台日志
2. Python 后端窗口日志
3. PHP 服务器窗口日志
4. 环境配置信息
5. 错误截图

---

**快速链接**:
- [完整启动指南](完整启动指南.md)
- [语音对话功能说明](语音对话功能说明.md)
- [语音对话快速开始](语音对话快速开始.md)
- [ASR问题修复总结](ASR问题修复总结.md)

**最后更新**: 2026-03-05