🎯 Interview Agent

AI 模拟面试助手 — 让每一次面试都更有准备

🚀 一键启动 • ✨ 功能特性 • 🧰 技术栈 • 📁 项目结构 • 📖 使用指南 • 🔌 API

---

📖 简介

Interview Agent 是一个基于大语言模型的 AI 模拟面试平台，支持面试官和求职者双重视角。结合 RAG 向量知识库与联网搜索能力，为每一场面试提供上下文感知的智能对话体验。

核心场景

模式	说明
🎯 你是面试官	用户以面试官身份向 AI 求职者提问。AI 结合岗位 JD、简历、代码文件和知识库给出专业回答，帮助面试官练习提问技巧
🧑 你是求职者	用户以求职者身份接受 AI 面试官提问。AI 根据 JD 和简历自动出题，支持设置面试时长、推算题数、追踪进度，结束后生成评估报告

---

✨ 功能特性

• 🤖 双模式 AI 对话 — 面试官 / 求职者自由切换，SSE 流式输出
• 🔑 前端 API Key 配置 — 在界面中直接配置 DeepSeek API Key，密钥仅存本地
• ⏱️ 面试时长推算 — 求职者模式下设置面试时长，自动推算问题数量与阶段拆分
• 🎯 模拟练习流程 — 求职者模式：AI 逐题提问 → 你回答 → 进度追踪 → 生成报告
• 🧑‍💻 编程题模式 — 技术岗专属，根据岗位类型智能选题（LeetCode 风格），支持难度自适应
• 🎓 候选人分级 — 支持实习 / 校招 / 社招三种级别，自动调整问题难度与深度
• 🔄 面试轮次 — 初试 / 复试 / HR 面，不同轮次侧重不同考察方向
• 📚 RAG 向量知识库 — 上传 PDF / Word / 文本，LangChain FAISS 向量检索增强回答质量
• 🌐 联网搜索 — 集成 DuckDuckGo，实时获取最新技术资讯
• 📝 面试报告生成 — 多维度评估（技术能力 / 沟通表达 / 综合素质），支持结构化 QA 逐题评估
• 🗂️ 岗位管理 — 创建岗位、添加多份 JD、关联知识库，支持按 JD 筛选
• 🎛️ 模型选择 — 支持 DeepSeek V4 Pro / Flash，可切换思考模式与推理强度
• 🔒 安全机制 — CORS 域名白名单 + FAISS 索引 SHA-256 完整性校验
• 📐 上下文窗口管理 — tiktoken 精确 token 计数 + LangChain trim_messages 智能裁剪
• 🎤 语音输入 (STT) — 按住说话/空格键录音，faster-whisper 流式识别，实时转文字
• 🔊 语音朗读 (TTS) — AI 回复一键朗读，Piper TTS 中文语音合成
• 🎛️ 灵活语音开关 — 启动时可选择 CPU/GPU，Docker Profile 按需启用，默认关闭零影响
• 🖥️ 现代化 UI — React + Ant Design 6，响应式布局
• 🐳 一键部署 — 支持本地脚本 / Docker Compose / 单容器三种启动方式

---

🚀 一键启动

三种方式任选其一：

方式	命令	平台
📜 本地脚本	start.bat / ./start.sh	Windows / macOS / Linux
🐳 Docker Compose	docker-compose up -d	全平台
📦 单容器	docker run	全平台

首次使用：复制 .env.example → .env，填入 DeepSeek API Key

国内用户注意：首次启动需下载 Embedding 模型（约 90MB），.env 中已默认配置 HuggingFace 镜像 HF_ENDPOINT=https://hf-mirror.com，无需额外操作。

主要配置项

变量	默认值	说明
DEEPSEEK_API_KEY	—	DeepSeek API Key（必填）
DEEPSEEK_MODEL	deepseek-v4-pro	默认模型
AVAILABLE_MODELS	deepseek-v4-pro,deepseek-v4-flash	可选模型列表
EMBEDDING_MODEL	all-MiniLM-L6-v2	Embedding 模型名
HF_ENDPOINT	https://hf-mirror.com	HuggingFace 镜像（国内用户）
VECTOR_SEARCH_TOP_K	3	RAG 检索返回文档数
CORS_ORIGINS	http://localhost:5173,...	允许的前端来源（逗号分隔）
FAISS_VERIFY_INTEGRITY	true	FAISS 索引 SHA-256 完整性校验
MAX_CONTEXT_TOKENS	800000	上下文窗口上限（token）
DEEPSEEK_THINKING_ENABLED	true	默认启用思考模式
VOICE_ENABLED	false	🎤 语音功能总开关
STT_ENABLED	false	语音识别（语音转文字）
TTS_ENABLED	false	语音合成（文字转语音）
STT_MODEL	small	Whisper 模型（base:140MB / small:480MB）
STT_DEVICE	cpu	推理设备（cpu / cuda）
TTS_SPEED	1.0	朗读语速（0.5-2.0）

方式一：本地脚本（开发推荐）

Windows — 双击 start.bat

macOS / Linux：

chmod +x start.sh
./start.sh

脚本自动完成：环境检测 → 安装依赖 → 启动后端 :8000 + 前端 :5173 → 打开浏览器。

方式二：Docker Compose（部署推荐）

前置条件

• Docker 20.10+ & Docker Compose v2+
• DeepSeek API Key

标准部署（含 RAG 向量知识库）

# 1. 配置环境变量
cp .env.example .env
# 编辑 .env，填入 DEEPSEEK_API_KEY

# 2. 启动
docker-compose up -d

# 3. 验证
docker-compose ps

访问 http://localhost

首次启动会自动下载 Embedding 模型（约 90MB），已配置 HuggingFace 镜像。启动耗时约 2-3 分钟。

轻量部署（无 RAG，适合无 CUDA / 低资源环境）

# 不安装向量知识库依赖，镜像体积减少约 2GB
SKIP_RAG=true RAG_ENABLED=false docker-compose up -d

此模式下对话、面试模拟、报告生成等核心功能完全正常，仅知识库上传和 RAG 检索不可用。

架构说明

Browser → Nginx (:80) → /api/* 反代 → FastAPI (:8000)
                       → 其他路径 → 前端静态文件

常用命令

命令	说明
docker-compose up -d	启动（标准模式）
SKIP_RAG=true RAG_ENABLED=false docker-compose up -d	启动（无 RAG）
docker-compose down	停止并删除容器
docker-compose down -v	停止并删除容器+数据卷
docker-compose logs -f backend	查看后端日志
docker-compose restart backend	重启后端
docker compose --profile cpu up	启动（CPU 语音模式）
docker compose --profile gpu up	启动（GPU 语音模式）
docker compose --profile voice up	启动（语音全功能）

语音功能

# 本地开发：启动时选择 y → 选 CPU/GPU → 自动安装依赖+下载模型
start.bat   # 或 ./start.sh

# Docker：通过 Profile 启用
docker compose --profile cpu up    # CPU 语音
docker compose --profile gpu up    # GPU 语音

# 仅语音识别或仅语音合成
docker compose --profile stt up    # 仅 STT
docker compose --profile tts up    # 仅 TTS

首次使用会自动下载模型（whisper ~480MB + Piper ~50MB）。

数据持久化

数据	存储位置	说明
FAISS 向量索引	chroma_data volume	RAG 知识库索引
上传记录/题库	data volume	uploads.json, leetcode_problems.json
STT 模型	stt_models volume	Whisper 模型文件
TTS 模型	tts_models volume	Piper 语音模型文件
岗位数据	positions.json	镜像内置，重建后重置

方式三：单容器 Docker

# 构建（不含 RAG）
docker build --build-arg SKIP_RAG=true -t interview-agent .

# 运行
docker run -d \
  --name interview-agent \
  -p 8000:8000 \
  --env-file .env \
  -e RAG_ENABLED=false \
  -v interview-data:/app/data \
  interview-agent

访问 http://localhost:8000

包含 RAG 时去掉 --build-arg SKIP_RAG=true，并添加 -e RAG_ENABLED=true 和 -v interview-chroma:/app/chroma_data。

---

🧰 技术栈

后端

组件	技术
Web 框架	FastAPI + Uvicorn
LLM	DeepSeek V4 Pro / Flash（OpenAI 兼容协议）
流式输出	Server-Sent Events (SSE)
RAG 管线	LangChain LCEL + FAISS
向量存储	langchain-community FAISS
Embedding	HuggingFace sentence-transformers (all-MiniLM-L6-v2)
Token 计数	tiktoken (cl100k_base)
上下文裁剪	LangChain trim_messages
提示模板	LangChain ChatPromptTemplate
文档分块	langchain-text-splitters RecursiveCharacterTextSplitter
联网搜索	DuckDuckGo Search
文档解析	PyMuPDF + python-docx
数据校验	Pydantic v2

前端

组件	技术
框架	React 19 + TypeScript
构建工具	Vite 8
UI 库	Ant Design 6
路由	React Router 7
状态管理	Zustand
Markdown	react-markdown + remark-gfm

---

📁 项目结构

interview-agent/
├── main.py                  # FastAPI 入口
├── config.py                # 环境变量配置
├── requirements.txt         # Python 依赖
├── Dockerfile               # 多阶段构建（前端+后端）
├── docker-compose.yml       # Docker Compose 编排
├── start.bat                # Windows 一键启动
├── start.sh                 # macOS/Linux 一键启动
├── .env.example             # 环境变量模板
├── positions.json           # 岗位数据
│
├── routers/                 # API 路由
│   ├── chat.py              #   对话 (SSE 流式)
│   ├── interview.py         #   面试控制（开始/停止/报告/计划）
│   ├── position.py          #   岗位管理
│   ├── upload.py            #   文件上传
│   └── knowledge.py         #   知识库管理
│
├── services/                # 业务逻辑
│   ├── llm_client.py        #   DeepSeek 客户端
│   ├── vector_store.py      #   LangChain FAISS 向量存储
│   ├── rag_pipeline.py      #   LCEL RAG 检索管线
│   ├── chunker.py           #   文档分块
│   ├── parser.py            #   文件解析 (PDF/Word)
│   ├── agent_tools.py       #   联网搜索工具
│   ├── coding_problem.py    #   编程题智能选题
│   ├── model_registry.py    #   模型注册表
│   ├── position_store.py    #   岗位持久化
│   └── upload_store.py      #   上传文件持久化
│
├── utils/                   # 工具模块
│   ├── context_manager.py   #   上下文窗口管理 (tiktoken)
│   ├── prompt_loader.py     #   提示模板加载 (LangChain)
│   └── position_classifier.py  # 岗位类型分类器
│
├── models/
│   └── schemas.py           # Pydantic 数据模型
│
├── prompts/                 # 系统提示词
│   ├── interviewer.txt      #   面试官
│   ├── candidate.txt        #   求职者
│   └── report.txt           #   报告生成
│
├── data/
│   └── leetcode_problems.json  # 编程题库
│
├── frontend/                # React 前端
│   ├── Dockerfile           #   前端镜像
│   ├── nginx.conf           #   Nginx 配置
│   └── src/
│       ├── api/             #   API 客户端
│       ├── pages/           #   页面
│       ├── components/      #   组件
│       ├── stores/          #   状态
│       └── hooks/           #   Hooks
│
├── tests/                   # 测试
└── chroma_data/             # FAISS 索引存储
    └── faiss_indexes/       #   按知识库名分目录

---

📖 使用指南

你是面试官

创建岗位 → 添加 JD → 上传知识库 → 上传简历/代码 → 切换模式 → 向 AI 求职者提问

1. 在「岗位管理」页面创建岗位，添加职位描述
2. 在「知识库」页面上传相关文档（技术规范、FAQ 等）
3. 在「上传」页面上传候选人简历（PDF / Word）和代码文件
4. 切换到「AI 对话」页面，选择 🎯 你是面试官 模式
5. 向 AI 求职者提问，AI 会结合 JD、简历、代码和知识库给出专业回答
6. AI 回答完毕后，前往「面试报告」页面生成评估

你是求职者

创建岗位 → 添加 JD → 上传知识库 → 上传简历 → 设置面试时长 → 推算题数 → 开始练习 → AI 提问你回答 → 生成报告

1. 创建目标岗位并填写 JD
2. 在「知识库」页面上传相关文档，在「上传」页面上传你的简历
3. 切换到「AI 对话」页面，选择 🧑 你是求职者 模式
4. 选择面试时长（15/30/45/60 分钟），点击 推算 获取预估题数
5. 点击 开始模拟练习，AI 面试官自动逐题提问
6. 在输入框中回答每个问题，练习中实时显示进度（第 N/M 题）
7. 完成后点击 结束练习，前往「面试报告」页面一键生成多维度评估

ChatRequest 参数

{
  "messages": [{"role": "user", "content": "请介绍一下你自己"}],
  "mode": "interviewer",
  "position_name": "前端工程师",
  "jd_id": "jd_001",
  "use_search": false,
  "coding_enabled": false,
  "model": "deepseek-v4-pro",
  "thinking_enabled": true,
  "reasoning_effort": "high",
  "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "candidate_level": "experienced",
  "interview_round": "first",
  "interview_duration_minutes": 30,
  "interview_question_count": 10
}

参数	类型	说明
mode	string	"interviewer" 面试官 / "candidate" 求职者
position_name	string	关联岗位名称，触发 RAG 检索
jd_id	string	指定使用某份 JD（为空则使用全部 JD）
use_search	bool	是否启用联网搜索
coding_enabled	bool	是否启用编程题（仅求职者模式+技术岗生效）
model	string	模型选择，默认 deepseek-v4-pro
thinking_enabled	bool	是否启用深度思考
reasoning_effort	string	推理强度："high" / "max"
api_key	string	前端配置的 DeepSeek API Key（可选，优先级高于 .env）
candidate_level	string	候选人级别："intern" / "new_grad" / "experienced"
interview_round	string	面试轮次："first" / "second" / "hr"
interview_duration_minutes	int	面试总时长（分钟），影响时间预算感知
interview_question_count	int	计划题目数量

---

🔌 API 概览

模块	方法	路径	说明
对话	GET	/chat/models	可用模型列表
对话	POST	/chat/stream	SSE 流式对话
岗位	GET POST	/positions	列表 / 创建岗位
岗位	GET PUT DELETE	/positions/{name}	岗位 CRUD
岗位	POST PUT DELETE	/positions/{name}/jds	JD 管理（支持多份 JD）
面试	POST	/interview/start	开始面试（组装 system prompt）
面试	POST	/interview/stop	停止面试
面试	POST	/interview/report	生成报告（支持结构化 QA 逐题评估）
面试	POST	/interview/plan	🆕 面试时长推算（含阶段拆分、动态重规划）
上传	POST	/upload/resume	上传简历
上传	POST	/upload/code	上传代码
知识库	POST	/knowledge/upload	上传文档
知识库	GET	/knowledge/collections	列出知识库
知识库	DELETE	/knowledge/{name}	删除知识库
知识库	POST	/knowledge/search	向量检索

完整 API 文档：启动后访问 http://localhost:8000/docs (Swagger) 或 /redoc

---

🧪 运行测试

pytest tests/ -v

---

🤝 贡献

欢迎提交 Issue 和 Pull Request。

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'feat: add amazing feature')
4. 推送分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

---

📄 License

MIT © 2025