# AI-Robot 虚拟面试助手

**Repository Path**: yoodb/AI-Robot

## Basic Information

- **Project Name**: AI-Robot 虚拟面试助手
- **Description**: AI-Robot 是一个 Java 面试官虚拟助手。「小机」用 Ollama（Qwen2.5）做多轮面试；题库经 Chroma + RAG 检索后作参考。链路是：听（ASR）→ 想（LLM+题库）→ 说（TTS）→ 看（形象），Gradio Web UI 交互；重型能力（CosyVoice / MuseTalk）可外挂 HTTP。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI-Robot · Java 面试官（本地）

本地可商用方向的虚拟助手。当前完成 **第 1–4 阶段**：文字多轮 + 题库 RAG + 语音 + 形象。  
默认人设：**小机 = Java 面试官**，你是**候选人**。

## 组件一览

整体链路：**听（ASR）→ 想（LLM + 题库）→ 说（TTS）→ 看（形象）**。重型能力（CosyVoice / MuseTalk）走独立 HTTP，主 venv 保持轻量。

```text
候选人（文字/麦克风）
        │
        ▼
   ┌─────────┐     ┌──────────────┐
   │ Gradio  │────▶│ faster-whisper│  ASR（可选）
   │  Web UI │     └──────────────┘
   └────┬────┘
        │ 候选人发言
        ▼
   ┌─────────┐     ┌──────────────┐     ┌─────────────┐
   │ RAG 题库│────▶│ Chroma       │◀────│ Ollama      │
   │ knowledge│     │ + bge-m3 嵌入 │     │ embeddings  │
   └────┬────┘     └──────────────┘     └─────────────┘
        │ 题库参考
        ▼
   ┌─────────┐     ┌──────────────┐
   │ 对话编排 │────▶│ Ollama Chat  │  Qwen2.5
   │ main.py │     │ /api/chat    │
   └────┬────┘     └──────────────┘
        │ 面试官回复
        ├──────────▶ edge-tts / CosyVoice HTTP   TTS（可选）
        └──────────▶ static+ffmpeg / MuseTalk HTTP 形象（可选）
```

### 核心组件

| 层级 | 组件 | 作用 | 安装/位置 |
|------|------|------|-----------|
| 界面 | **Gradio** | Web 聊天、录音、音频/视频展示 | `requirements.txt` |
| 对话 LLM | **Ollama** + **Qwen2.5** | 面试官多轮对话 | 本机 Ollama 服务 |
| HTTP 客户端 | **requests** | 调 Ollama / CosyVoice / MuseTalk | `requirements.txt` |
| 配置 | **python-dotenv** | 读 `.env` | `requirements.txt` |
| 向量库 | **Chroma** | 题库切分后持久化检索 | `requirements.txt` → `data/chroma/` |
| 嵌入 | **Ollama bge-m3** | 题库向量化（不额外装 PyTorch） | `ollama pull bge-m3` |
| ASR | **faster-whisper** | 语音→文字 | `requirements-voice.txt` → `models/whisper/` |
| TTS（默认） | **edge-tts** | 文字→语音（需联网） | `requirements-voice.txt` |
| TTS（可选） | **CosyVoice** | 本地高质量合成 | 独立服务，见 `scripts/setup_cosyvoice.md` |
| 形象（默认） | **static** + **ffmpeg**（可选） | 静图或静图+音频拼口播视频 | 系统 PATH 中的 ffmpeg |
| 形象（可选） | **MuseTalk** | 口型驱动视频 | 独立服务，见 `scripts/setup_musetalk.md` |
| 模型镜像 | **HF_ENDPOINT**（如 hf-mirror） | 国内下载 Whisper 权重 | `.env` |

### 本仓库模块对应

| 文件 | 组件职责 |
|------|----------|
| `app/main.py` | Gradio UI、面试对话编排、ASR/TTS/形象开关 |
| `app/config.py` | 环境变量、面试官人设 `SYSTEM_PROMPT` |
| `app/ollama_client.py` | Ollama `/api/chat`、历史消息规范化 |
| `app/embeddings.py` | Ollama 嵌入，供 Chroma 使用 |
| `app/knowledge.py` | 题库加载/切分/入库/检索、面试向 RAG 提示词 |
| `app/asr.py` | faster-whisper 封装 |
| `app/tts.py` | edge-tts / CosyVoice HTTP |
| `app/avatar.py` | static+ffmpeg / MuseTalk HTTP |
| `scripts/ingest_knowledge.py` | 题库全量重建 |
| `scripts/check_env.py` | Ollama / 题库 / 语音 / 形象自检 |
| `scripts/download_whisper.py` | 镜像下载 Whisper |
| `scripts/make_default_avatar.py` | 生成默认形象图 |
| `scripts/musetalk_api_stub.py` | MuseTalk 接口联调 stub（ffmpeg） |

### Python 依赖清单

**主依赖**（`requirements.txt`）：`gradio`、`chromadb`、`requests`、`python-dotenv`  

**语音依赖**（`requirements-voice.txt`）：`faster-whisper`、`soundfile`、`numpy`、`edge-tts`  

**不进主 venv、按需外挂**：CosyVoice 运行时、MuseTalk 运行时、系统 **ffmpeg**、本机 **Ollama**。

## 目录

```text
AI-Robot/
  app/                 # Gradio、Ollama、题库、ASR/TTS、形象
  data/knowledge/      # Java 面试题（.md / .txt）
  data/chroma/         # 向量库落盘（自动生成）
  data/audio/          # TTS 临时音频
  data/avatar/         # 形象素材与生成视频
  models/              # Whisper 等本地权重
  scripts/             # 自检、入库、CosyVoice/MuseTalk 说明
```

## 环境要求

- Windows 10/11
- Python 3.10–3.12
- [Ollama](https://ollama.com/download)
- 显卡建议 ≥8GB（跑 `qwen2.5:7b`）；不够可用 `qwen2.5:3b`
- 语音：麦克风；TTS 默认 edge-tts（需联网）；本地 CosyVoice 见下方
- 形象：默认静图；有 [ffmpeg](https://ffmpeg.org/) 时可拼口播视频；真口型见 MuseTalk

## 快速开始

### 1. 安装 Ollama 并拉取模型

```powershell
ollama pull qwen2.5:7b
ollama pull bge-m3
```

### 2. 安装 Python 依赖

```powershell
cd "d:\项目源码\自学\AI-Robot"
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip install -r requirements-voice.txt
copy .env.example .env
.\.venv\Scripts\python.exe scripts\make_default_avatar.py
```

### 3. 入库题库

Java 面试题已在 `data/knowledge/`。修改文档后执行：

```powershell
.\.venv\Scripts\python.exe scripts\ingest_knowledge.py
```

### 4. 自检并启动

在项目根目录执行（推荐，无需激活虚拟环境）：

```powershell
cd "d:\项目源码\自学\AI-Robot"
.\.venv\Scripts\python.exe scripts\check_env.py
.\.venv\Scripts\python.exe -m app.main
```

浏览器打开 `http://127.0.0.1:7860`。

若先激活再启动，可用：

```powershell
# 方式 A：直接指定解释器（推荐）
.\.venv\Scripts\python.exe -m app.main

# 方式 B：cmd 激活（避开 PowerShell 对 .ps1 的限制）
cmd /c ".\.venv\Scripts\activate.bat && python -m app.main"

# 方式 C：当前会话临时允许执行 Activate.ps1
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1
python -m app.main
```

> PowerShell 若提示“打开 / 无法加载 Activate.ps1”，是执行策略拦截，用方式 A 或 B 即可。

可试问 / 面试用法：

- 输入「开始面试」开场
- 用文字或语音回答面试官的问题
- 需要标准答法时说「请讲解这题」

题库目录：`data/knowledge/`（Java 面试题 md）；改完后执行入库脚本。

语音：录音/上传 →「语音作答」；勾选「朗读回复」可听面试官。首次 Whisper 模型见 `models/whisper/`。  
形象：勾选「显示形象」；默认 static，有 ffmpeg 时可拼口播视频。

## 配置说明

| 变量 | 含义 | 默认 |
|------|------|------|
| `OLLAMA_MODEL` | 对话模型 | `qwen2.5:7b` |
| `EMBED_MODEL` | 嵌入模型 | `bge-m3` |
| `RAG_ENABLED` | 是否启用题库检索 | `true` |
| `RAG_TOP_K` | 检索条数 | `3` |
| `MAX_HISTORY_TURNS` | 保留最近几轮 | `10` |
| `GRADIO_SERVER_PORT` | 网页端口 | `7860` |
| `VOICE_ENABLED` | 是否启用语音 UI | `true` |
| `ASR_MODEL_SIZE` | Whisper 规格 | `small` |
| `ASR_DEVICE` | `cpu` / `cuda` | `cpu` |
| `HF_ENDPOINT` | HuggingFace 镜像 | `https://hf-mirror.com` |
| `TTS_ENGINE` | `edge` / `cosyvoice` / `none` | `edge` |
| `COSYVOICE_API_URL` | CosyVoice 服务地址 | `http://127.0.0.1:50000` |
| `AVATAR_ENABLED` | 是否启用形象 UI | `true` |
| `AVATAR_ENGINE` | `static` / `musetalk` / `none` | `static` |
| `AVATAR_SOURCE` | 形象素材路径 | `data/avatar/default.png` |
| `MUSETALK_API_URL` | MuseTalk HTTP 地址 | `http://127.0.0.1:50001` |

嵌入走 **Ollama 的 bge-m3**，主对话链路不强制装 PyTorch。

### CosyVoice（本地 TTS）

默认 `TTS_ENGINE=edge` 便于马上试通。换成本地 CosyVoice：见 `scripts/setup_cosyvoice.md`。

### MuseTalk（真口型，可选）

默认 `AVATAR_ENGINE=static` 即可看形象。升级真口型：见 `scripts/setup_musetalk.md`（可用 stub 先联调，再接官方 MuseTalk）。

## 常见问题

**无法连接 Ollama**  
安装并启动 Ollama，确认 `ollama list` 有输出。

**找不到对话 / 嵌入模型**  

```powershell
ollama pull qwen2.5:7b
ollama pull bge-m3
```

**题库为空**  
先 `.\.venv\Scripts\python.exe scripts\ingest_knowledge.py`。

**改了文档但回答没变**  
入库是全量重建，改完必须重新跑入库脚本。

**Activate.ps1 被打开或无法执行**  
不要双击 `.ps1`。用 `.\.venv\Scripts\python.exe -m app.main`，或见上方「自检并启动」方式 B/C。

**语音识别不可用**  
安装语音依赖：`.\.venv\Scripts\python.exe -m pip install -r requirements-voice.txt`。

**ASR / Whisper 下载超时（WinError 10060）**  
连不上 HuggingFace。用镜像预下载后重启应用：

```powershell
# .env 建议：
# HF_ENDPOINT=https://hf-mirror.com
# HF_HUB_DISABLE_XET=1

.\.venv\Scripts\python.exe scripts\download_whisper.py base
# 需要更高精度再下：.\.venv\Scripts\python.exe scripts\download_whisper.py small
```

下载完成后可设 `ASR_MODEL_PATH=models/whisper/faster-whisper-base`（程序也会自动发现该目录）。

**TTS / CosyVoice 失败**  
- `edge`：需能访问微软语音服务  
- `cosyvoice`：确认独立服务已启动，见 `scripts/setup_cosyvoice.md`

**形象只有静图、没有视频**  
安装 ffmpeg 并加入 PATH；勾选「朗读回复」与「显示形象」。真口型见 `scripts/setup_musetalk.md`。

## 路线图

| 阶段 | 内容 | 所用组件 | 状态 |
|------|------|----------|------|
| P1 | 文字多轮面试对话 | Gradio + Ollama/Qwen | ✅ |
| P2 | Java 题库 RAG | Chroma + bge-m3 | ✅ |
| P3 | 语音听/说 | faster-whisper + edge-tts / CosyVoice | ✅ |
| P4 | 形象 | static+ffmpeg / MuseTalk | ✅ |