# AI Mock Interview Platform

**Repository Path**: hf-sun/AI-Mock-Interview-Platform

## Basic Information

- **Project Name**: AI Mock Interview Platform
- **Description**: AI 智能模拟面试平台
基于 Python 3.13 + FastAPI + Vue 3 的全栈 AI 模拟面试系统，支持智能追问、实时评分、WebSocket 实时交互、RAG 检索增强与 LangGraph Agent 编排。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-15
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 智能模拟面试平台

基于 **Python 3.13 + FastAPI + Vue 3** 的全栈 AI 模拟面试系统，支持智能追问、实时评分、WebSocket 实时交互、RAG 检索增强与 LangGraph Agent 编排。

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Python 3.13、FastAPI、SQLAlchemy 2.0、Alembic |
| 数据层 | MySQL 8.0、Redis 7.x |
| AI | 大模型 API、LangChain、LangGraph、Chroma |
| 语音 | Whisper、Edge-TTS |
| 前端 | Vue 3、Vite、Element Plus |
| 工程化 | JWT、Docker、Nginx、pytest |

## 阶段 1 已实现

- 项目分层架构（api / core / models / schemas / services / utils）
- 异步 MySQL 连接 + Redis 连接封装
- JWT 注册 / 登录 / 鉴权（bcrypt 密码加密）
- 统一响应格式与全局异常处理
- 核心数据表：用户、岗位、题库、面试记录、面试对话
- Alembic 数据库迁移
- Docker Compose 开发环境（MySQL + Redis）

## 环境要求

- Python 3.11+（推荐 3.13）
- Docker & Docker Compose
- Git

## 本地启动

### 1. 克隆项目

```bash
git clone https://gitee.com/hf-sun/AI-Mock-Interview-Platform.git
cd AI-Mock-Interview-Platform
```

### 2. 创建虚拟环境并安装依赖

```bash
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt
```

### 3. 配置环境变量

```bash
# Windows
copy .env.example .env

# macOS / Linux
cp .env.example .env
```

编辑 `.env`，至少配置以下项（与 docker-compose 默认值对齐）：

```env
MYSQL_PORT=3307
MYSQL_PASSWORD=your_password
MYSQL_DB=ai_interview
JWT_SECRET_KEY=your_jwt_secret_key_at_least_32_chars
```

> 若本机 3306 端口已被占用，docker-compose 默认将 MySQL 映射到 **3307** 端口。

### 4. 启动 MySQL 与 Redis

```bash
docker compose -f docker-compose.dev.yml up -d
```

等待容器健康检查通过：

```bash
docker compose -f docker-compose.dev.yml ps
```

### 5. 执行数据库迁移

```bash
alembic upgrade head
```

### 6. 启动后端服务

```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

访问 API 文档：http://127.0.0.1:8000/docs

### 7. 健康检查

```bash
curl http://127.0.0.1:8000/health
```

## 阶段 3 已实现

- 大模型通用对接：兼容 OpenAI 格式，支持豆包/通义千问，密钥全部环境变量读取
- 未配置 API Key 时自动启用 Mock 模式，本地可跑通全流程
- 五阶段面试引擎：自我介绍 → 项目经验 → 专业能力 → 综合能力 → 结束提问
- 智能追问 + 五维度实时评分 + AI 面试官笔记 + 追问方向
- Redis 会话管理，支持多轮对话上下文保持（TTL 可配置）
- `InterviewService` 统一封装：创建 / 回答 / 实时状态 / 结束面试

### AI 面试引擎

| 方法 | 路径 | 说明 | 权限 |
|------|------|------|------|
| POST | `/api/v1/interview-engine/start` | 发起面试 | 登录用户 |
| POST | `/api/v1/interview-engine/{id}/answer` | 提交回答 | 登录用户 |
| GET | `/api/v1/interview-engine/{id}/live` | 实时状态 | 登录用户 |
| POST | `/api/v1/interview-engine/{id}/end` | 结束面试 | 登录用户 |

> 配置 `LLM_API_KEY`、`LLM_BASE_URL`、`LLM_MODEL` 后切换为真实大模型；留空则使用 Mock 响应。

## 阶段 4 已实现

- WebSocket 实时面试：`ws://host/api/v1/ws/interview?token=<JWT>`
- 连接鉴权、心跳 ping/pong、断线重连（resume）
- 实时推送：thinking / dialogue / score / stage_change / interview_end
- 超时自动结束（`INTERVIEW_MAX_DURATION_SECONDS` 可配置）
- 统一消息协议：`app/schemas/ws_message.py`

### WebSocket 消息协议

**客户端 → 服务端**

| type | 字段 | 说明 |
|------|------|------|
| ping | - | 心跳 |
| start | job_id | 发起面试 |
| resume | interview_id | 断线恢复 |
| answer | interview_id, content | 提交回答 |
| end | interview_id | 结束面试 |

**服务端 → 客户端**

| type | 说明 |
|------|------|
| connected / pong | 连接成功 / 心跳 |
| thinking | AI 思考中 |
| dialogue | 对话消息 |
| score | 评分、笔记、追问方向 |
| stage_change | 阶段切换 |
| session_restore | 会话恢复 |
| interview_end | 结束报告 |
| error | 错误 |

## 阶段 5 已实现

- Vue 3 + Vite + Element Plus 前端，还原原型三栏布局
- 页面：登录注册、面试主页、面试记录、岗位库、题库中心、个人中心
- Axios 拦截器统一 JWT 鉴权与错误处理
- WebSocket 工具类：心跳、断线重连、消息分发
- 路由守卫：未登录自动跳转登录页

### 前端启动

```bash
cd frontend
npm install
cp .env.example .env.local   # 配置 API 与 WS 地址
npm run dev                   # http://localhost:5173
```

确保后端已启动：`uvicorn app.main:app --reload --port 8000`

## 阶段 6 已实现

- **ASR**：Whisper 语音转文字，`POST /api/v1/voice/asr`
- **TTS**：Edge-TTS 文字转语音，`POST /api/v1/voice/tts`
- 前端麦克风录音 + AI 回复语音播放
- Docker 多阶段构建 + docker-compose 全栈部署
- Nginx 反向代理（静态 / API / WebSocket）
- Redis 题库列表缓存 + 数据库复合索引优化

详细部署见 [docs/DEPLOY.md](docs/DEPLOY.md)

## 阶段 7 已实现

- **RAG 检索增强**：LangChain + Chroma 向量库，按岗位维度构建知识库
- **知识库管理**：题库批量导入、岗位描述/技能/评分标准同步、自定义文本增量导入
- **简历定制**：PDF 简历解析 → 分块向量化 → 面试 Prompt 注入
- **面试引擎集成**：`RagService` 独立解耦，通过 `RAG_ENABLED` 开关控制
- **Embedding**：OpenAI 兼容接口（豆包、通义等），配置见 `.env.example`

### RAG 启用步骤

```bash
# 1. 配置 Embedding 与 RAG 开关
RAG_ENABLED=true
EMBEDDING_API_KEY=your_key
EMBEDDING_BASE_URL=https://your-embedding-url.com/v1
EMBEDDING_MODEL=embedding-model-name

# 2. 管理员同步岗位知识库（需 admin 角色 JWT）
curl -X POST http://127.0.0.1:8000/api/v1/rag/jobs/1/sync \
  -H "Authorization: Bearer <token>"

# 3. 用户上传 PDF 简历（可选，用于定制化提问）
curl -X POST http://127.0.0.1:8000/api/v1/rag/resume/upload \
  -H "Authorization: Bearer <token>" \
  -F "file=@resume.pdf"
```

## 阶段 8 已实现

- **LangGraph Agent 编排**：面试流程状态机（Prompt → LLM → 评分 → 流转判断 → 追问/切阶段/结束）
- **双图设计**：开场图（`opening`）+ 回答图（`answer`），节点职责清晰
- **Redis 兼容**：Agent 状态与 `InterviewSessionData` 对齐，断线 `resume` 无需额外 Checkpoint
- **WebSocket 无缝对接**：REST / WS 共用 `InterviewService`，自动走 Agent 路径
- **可开关**：`AGENT_ENABLED=false` 时回退至阶段 3 线性流程

### Agent 流程节点

| 节点 | 职责 |
|------|------|
| prepare_prompt | 构建系统 Prompt（含 RAG 增强） |
| invoke_llm | 调用大模型生成 JSON 回复 |
| apply_scores | 提取五维评分与 AI 笔记 |
| judge_transition | LLM 决策 + 轮次兜底，路由三路 |
| append_follow_up | 当前阶段追问 |
| advance_stage | 切换至下一阶段 |
| mark_interview_end | 最后阶段结束语 |

## 阶段 2 已实现

- 岗位库：分类列表、分页查询、分类筛选、详情、管理员 CRUD
- 题库中心：按岗位/分类/难度/题型筛选、管理员 CRUD
- 面试记录：历史列表、详情（含对话）、删除
- 个人中心：资料修改、密码修改、面试统计数据

## API 接口

### 认证

| 方法 | 路径 | 说明 | 鉴权 |
|------|------|------|------|
| POST | `/api/v1/auth/register` | 用户注册 | 否 |
| POST | `/api/v1/auth/login` | 用户登录 | 否 |
| GET | `/api/v1/auth/me` | 当前用户信息 | 是 |
| GET | `/health` | 健康检查 | 否 |

### 岗位库

| 方法 | 路径 | 说明 | 权限 |
|------|------|------|------|
| GET | `/api/v1/jobs/categories` | 岗位分类列表 | 登录用户 |
| GET | `/api/v1/jobs` | 岗位分页列表 | 登录用户 |
| GET | `/api/v1/jobs/{id}` | 岗位详情 | 登录用户 |
| POST | `/api/v1/jobs` | 创建岗位 | 管理员 |
| PUT | `/api/v1/jobs/{id}` | 更新岗位 | 管理员 |
| DELETE | `/api/v1/jobs/{id}` | 删除岗位（软删） | 管理员 |

### 题库中心

| 方法 | 路径 | 说明 | 权限 |
|------|------|------|------|
| GET | `/api/v1/questions` | 题目分页列表 | 登录用户 |
| GET | `/api/v1/questions/{id}` | 题目详情 | 登录用户 |
| POST | `/api/v1/questions` | 创建题目 | 管理员 |
| PUT | `/api/v1/questions/{id}` | 更新题目 | 管理员 |
| DELETE | `/api/v1/questions/{id}` | 删除题目 | 管理员 |

### 面试记录

| 方法 | 路径 | 说明 | 权限 |
|------|------|------|------|
| GET | `/api/v1/interviews` | 面试历史列表 | 登录用户 |
| GET | `/api/v1/interviews/{id}` | 面试详情 | 登录用户 |
| DELETE | `/api/v1/interviews/{id}` | 删除记录 | 登录用户 |

### 个人中心

| 方法 | 路径 | 说明 | 权限 |
|------|------|------|------|
| PUT | `/api/v1/users/me` | 修改资料 | 登录用户 |
| PUT | `/api/v1/users/me/password` | 修改密码 | 登录用户 |
| GET | `/api/v1/users/me/stats` | 面试统计 | 登录用户 |

### RAG 检索增强

| 方法 | 路径 | 说明 | 权限 |
|------|------|------|------|
| POST | `/api/v1/rag/jobs/{id}/sync` | 全量同步岗位知识库 | 管理员 |
| POST | `/api/v1/rag/jobs/{id}/import-questions` | 导入题库到向量库 | 管理员 |
| POST | `/api/v1/rag/jobs/{id}/import-knowledge` | 增量导入自定义知识 | 管理员 |
| GET | `/api/v1/rag/jobs/{id}/stats` | 岗位向量库统计 | 登录用户 |
| DELETE | `/api/v1/rag/jobs/{id}/knowledge` | 清空岗位向量库 | 管理员 |
| POST | `/api/v1/rag/resume/upload` | 上传 PDF 简历并向量化 | 登录用户 |
| GET | `/api/v1/rag/resume/stats` | 简历向量统计 | 登录用户 |
| DELETE | `/api/v1/rag/resume` | 删除简历向量 | 登录用户 |

> RAG 需配置 `RAG_ENABLED=true` 及 Embedding API；未开启时接口返回 503。

> 管理员账号需手动在数据库中将 `users.role` 设为 `admin`。

### 注册示例

```bash
curl -X POST http://127.0.0.1:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"demo_user\",\"email\":\"demo@example.com\",\"password\":\"123456\"}"
```

### 登录示例

```bash
curl -X POST http://127.0.0.1:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"demo_user\",\"password\":\"123456\"}"
```

## 项目结构

```
app/
├── api/v1/          # 接口路由
├── core/            # 配置、鉴权、异常、响应
├── models/          # ORM 模型
├── schemas/         # Pydantic 模型
├── services/        # 业务逻辑
├── utils/           # 工具类
├── database.py      # 数据库连接
└── main.py          # 应用入口
alembic/             # 数据库迁移
```

## 开发规范

- Python 代码遵循 PEP8
- 敏感信息禁止硬编码，全部通过 `.env` 读取
- 分层架构：api 层不写业务逻辑，services 层处理业务

## License

MIT