🎙️ 语音助手项目

智能语音助手系统，集成了音频录制、上传处理和地图查询功能。

📋 项目结构

yuyinzhushou/
├── frontend/              # 前端应用 (React + Vite)
│   ├── src/
│   │   ├── App.jsx       # 主应用组件（含音频录制功能）
│   │   ├── App.css       # 样式
│   │   └── main.jsx      # 入口文件
│   ├── package.json      # 前端依赖
│   └── vite.config.js    # Vite 配置
│
├── Storage/              # 音频文件存储目录（自动创建）
│   └── .gitkeep
│
├── main.py               # FastAPI 后端主应用
├── requirements.txt      # Python 依赖
├── .env                  # 环境配置文件
├── .gitignore           # Git 忽略文件
│
├── start-frontend.bat    # 启动前端脚本
├── start-backend.bat     # 启动后端脚本
├── start-all.bat         # 一键启动全部服务
├── test.html            # 后端测试页面
│
├── README.md            # 项目总览（本文件）
└── README_BACKEND.md    # 后端详细文档

🚀 快速开始

方式1: 一键启动（推荐）

# 双击运行或在命令行执行
start-all.bat

这将自动启动后端服务（8000端口）和前端服务（5173端口）。

方式2: 分别启动

1. 启动后端服务

# 安装 Python 依赖
pip install -r requirements.txt

# 启动后端
python main.py
# 或者
start-backend.bat

后端服务地址: http://localhost:8000

2. 启动前端服务

cd frontend
npm install
npm run dev
# 或者
start-frontend.bat

前端服务地址: http://localhost:5173

🔧 功能特性

✅ 已实现

• 🎤 实时音频录制 - 浏览器内录制音频
• 📤 音频上传 - 将音频文件上传到后端
• 💾 文件存储 - 自动保存到 Storage 目录
• 📝 文件管理 - 查看已上传的音频文件列表
• 🔐 文件验证 - 类型和大小检查
• 🌐 CORS 支持 - 跨域资源共享
• 📱 响应式UI - 适配移动和桌面设备
• 📖 API 文档 - 自动生成的 Swagger 文档

🔄 开发中

• 语音转文字（ASR）
• 集成地图API
• 智能对话功能
• 对话历史记录

🛠️ 技术栈

后端

• FastAPI - 现代化 Python Web 框架
• Uvicorn - ASGI 服务器
• Pydantic - 数据验证
• Python-dotenv - 环境变量管理

前端

• React 19 - UI 框架
• Vite 8 - 构建工具
• MediaRecorder API - 音频录制
• Fetch API - HTTP 请求

📖 API 接口

1. 健康检查

GET http://localhost:8000/

2. 上传音频文件

POST http://localhost:8000/api/upload-audio
Content-Type: multipart/form-data

file: [音频文件]

3. 获取文件列表

GET http://localhost:8000/api/files

4. API 文档

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🧪 测试

测试后端服务

1. 在浏览器打开 test.html
2. 或访问 http://localhost:8000/docs 使用 Swagger UI

测试音频录制

1. 访问前端: http://localhost:5173
2. 点击 🎤 按钮开始录音
3. 再次点击停止录音
4. 音频将自动上传到后端

⚙️ 配置说明

编辑 .env 文件自定义配置:

# 服务器配置
HOST=0.0.0.0
PORT=8000

# 存储配置
STORAGE_PATH=Storage

# CORS 配置
CORS_ORIGINS=http://localhost:5173,http://localhost:3000

# 文件限制
MAX_AUDIO_SIZE=50  # MB
ALLOWED_AUDIO_TYPES=audio/mpeg,audio/wav,audio/ogg,audio/webm,audio/mp4,audio/x-m4a

📁 存储说明

• 所有上传的音频文件保存在 Storage/ 目录
• 文件名格式: {时间戳}_{原文件名}
• 支持的音频格式: MP3, WAV, OGG, WebM, MP4, M4A

🐛 常见问题

Q: 无法录制音频？

A: 请确保浏览器允许访问麦克风，建议使用 Chrome、Edge 或 Firefox 浏览器。

Q: 上传失败？

A: 检查后端服务是否正常运行，查看控制台错误信息。

Q: CORS 错误？

A: 确保 .env 中的 CORS_ORIGINS 包含前端地址。

Q: 如何修改端口？

A: 编辑 .env 文件中的 PORT 配置。

📚 详细文档

• 后端详细文档 - 后端 API 和开发指南
• 前端文档 - 前端组件和开发说明
• 高德地图 MCP 服务文档 - 地图服务集成

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可

MIT License

📧 联系方式

如有问题或建议，请创建 Issue。