# TalkGuy

**Repository Path**: knifecms/talk-guy

## Basic Information

- **Project Name**: TalkGuy
- **Description**: 借助NVIDIA ACE技术实现的一款虚拟人，用于英语聊天，学习
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-03
- **Last Updated**: 2026-01-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Talk Guy - 虚拟人英语对话游戏

基于 AI 技术的交互式虚拟人游戏，通过开放式语音对话进行英语学习。

## 功能特性

- **语音识别**：使用 OpenAI Whisper 实现实时语音转文字
- **语音合成**：使用 Microsoft Edge TTS 实现自然的文字转语音
- **面部动画**：NVIDIA ACE Audio2Face 实现逼真的口型同步和表情
- **语法纠正**：实时语法和词汇反馈
- **语言游戏**：互动词汇游戏和测验
- **话题探索**：AI驱动的对话话题建议
- **3D虚拟人**：使用 Three.js 的交互式3D虚拟形象

## 技术栈

- **前端**：React + TypeScript + Three.js
- **后端**：Python FastAPI
- **AI/ML**：OpenAI Whisper, Edge TTS, Zhipu AI
- **音频**：Whisper ASR, Edge TTS

## 快速开始

### 前置要求

- Node.js 18+
- Python 3.10+
- FFmpeg（用于音频处理）

### 安装步骤

#### Windows 用户

1. 运行安装脚本：
```bash
install.bat
```

2. 配置环境变量：
```bash
cd backend
copy .env.example .env
```

3. 编辑 `.env` 文件，添加你的 API 密钥（至少需要 Zhipu AI）

4. 启动应用：
```bash
npm run dev
```

#### Mac/Linux 用户

1. 安装依赖：
```bash
npm install
cd frontend && npm install && cd ..
cd backend && pip install -r requirements.txt && cd ..
```

2. 配置环境变量：
```bash
cd backend
cp .env.example .env
```

3. 编辑 `.env` 文件，添加你的 API 密钥

4. 启动应用：
```bash
npm run dev
```

### 配置说明

在 `backend/.env` 文件中配置：

**必需的 API 密钥：**
- `ZHIPUAI_API_KEY`：从 https://open.bigmodel.cn/ 获取

**可选的 API 密钥：**
- `OPENAI_API_KEY`：从 https://platform.openai.com/ 获取（如果不想用 Zhipu AI）

### 运行应用

```bash
npm run dev
```

前端地址：`http://localhost:5173`
后端API地址：`http://localhost:8000`

## 项目结构

```
talk-guy/
├── frontend/          # React 前端应用
│   ├── src/
│   │   ├── components/    # React 组件
│   │   ├── services/      # API 服务
│   │   ├── utils/         # 工具函数
│   │   └── types/         # TypeScript 类型定义
│   └── public/
│       └── models/        # 3D 模型文件
├── backend/           # Python FastAPI 后端
│   ├── api/           # API 端点
│   ├── services/      # 业务逻辑
│   │   ├── asr/       # 语音识别 (Whisper)
│   │   ├── tts/       # 语音合成 (Edge TTS)
│   │   ├── llm/       # LLM 集成 (Zhipu AI/OpenAI)
│   │   ├── grammar/   # 语法纠正
│   │   └── ace/       # NVIDIA ACE 集成
│   └── models/        # 数据库模型
├── install.bat        # Windows 安装脚本
├── SETUP.md          # 详细安装指南
└── README.md         # 本文件
```

## 使用方法

1. 启动应用程序
2. 点击麦克风按钮开始说话
3. 虚拟人会回应并提供反馈
4. 进行对话或玩语言游戏

## 核心功能说明

### 对话模式
- 与虚拟人进行自由对话
- 实时语法纠正和词汇建议
- 智能话题推荐，引导持续交流
- 支持语音和文字输入

### 游戏模式
- **词汇联想**：通过词汇链练习词汇
- **故事构建**：合作创作故事
- **场景角色扮演**：在真实场景中练习英语
- **词汇测验**：测试和扩展词汇量
- **发音练习**：获得发音反馈和指导

### 学习辅助
- 实时语法检查和纠正
- 词汇改进建议
- 发音提示
- 英语水平评估

## 技术实现

### 语音识别 (ASR)
- 使用 OpenAI Whisper 模型
- 支持多种音频格式（WAV, MP3, WebM）
- 自动采样率转换
- 多语言支持

### 语音合成 (TTS)
- 使用 Microsoft Edge TTS
- 无需 API 密钥
- 多种语音选择
- 高质量音频输出

### 对话管理
- 集成 Zhipu AI GLM-4 模型
- 可选 OpenAI GPT-4
- 上下文感知对话
- 智能话题建议

## 故障排除

### Whisper 模型下载问题
- 首次运行时会自动下载模型（约 140MB）
- 确保网络连接正常
- 模型会缓存在本地

### 音频录制不工作
- 确保浏览器有麦克风权限
- 检查麦克风是否正常工作
- 尝试使用 Chrome 或 Edge 浏览器

### 语音合成不工作
- Edge TTS 需要网络连接
- 检查浏览器控制台错误
- 确保后端服务正常运行

## 详细文档

- [安装指南](SETUP.md) - 详细的安装和配置说明
- [API 文档](http://localhost:8000/docs) - FastAPI 自动生成的 API 文档

## 许可证

MIT