README.md · master · soucod-github/soucod/interview-guide

智能 AI 面试官平台 - 基于大语言模型的简历分析和模拟面试系统

项目介绍

InterviewGuide 是一个集成了简历分析、模拟面试和知识库管理的智能面试辅助平台。系统利用大语言模型（LLM）和向量数据库技术，为求职者和 HR 提供智能化的简历评估和面试练习服务。

系统架构

提示：架构图采用 draw.io 绘制，导出为 svg 格式，在 Github Dark 模式下的显示效果会有问题。

异步处理流程：

简历分析、知识库向量化和面试报告生成采用 Redis Stream 异步处理，这里以简历分析和知识库向量化为例介绍一下整体流程：


上传请求 → 保存文件 → 发送消息到 Stream → 立即返回
                              ↓
                      Consumer 消费消息
                              ↓
                    执行分析/向量化任务
                              ↓
                      更新数据库状态
                              ↓
                   前端轮询获取最新状态

状态流转： PENDING → PROCESSING → COMPLETED / FAILED。

配套教程

本项目承诺完整功能免费开源，也不会做所谓的 Pro 版或“付费解锁核心功能”之类的设计。

如果你想学习这个项目，或者希望把它作为个人项目经历 / 毕设选题，我也整理了一套相对细致的教程：从基础设施搭建、核心业务实现，到最后如何在面试中讲清楚思路与亮点，尽量把容易卡住的地方讲透。

如果你确实需要更系统的辅导，可以点这里了解详情（教程为付费内容，主要是想覆盖一些时间成本，望理解，感谢支持）：《SpringAI 智能面试平台+RAG 知识库》。

技术栈

后端技术

技术	版本	说明
Spring Boot	4.0	应用框架
Java	21	开发语言
Spring AI	2.0	AI 集成框架
PostgreSQL + pgvector	14+	关系数据库 + 向量存储
Redis	6+	缓存 + 消息队列（Stream）
Apache Tika	2.9.2	文档解析
iText 8	8.0.5	PDF 导出
MapStruct	1.6.3	对象映射
Gradle	8.14	构建工具

技术选型常见问题解答：

数据存储为什么选择 PostgreSQL + pgvector？PG 的向量数据存储功能够用了，精简架构，不想引入太多组件。
为什么引入 Redis？
- Redis 替代 ConcurrentHashMap 实现面试会话的缓存。
- 基于 Redis Stream 实现简历分析、知识库向量化等场景的异步（还能解耦，分析和向量化可以使用其他编程语言来做）。不使用 Kafka 这类成熟的消息队列，也是不想引入太多组件。
构建工具为什么选择 Gradle？个人更喜欢用 Gradle，也写过相关的文章：Gradle核心概念总结。

前端技术

技术	版本	说明
React	18.3	UI 框架
TypeScript	5.6	开发语言
Vite	5.4	构建工具
Tailwind CSS	4.1	样式框架
React Router	7.11	路由管理
Framer Motion	12.23	动画库
Recharts	3.6	图表库
Lucide React	0.468	图标库

功能特性

简历管理模块

多格式解析：支持 PDF、DOCX、DOC、TXT 等多种简历格式。
异步处理流：基于 Redis Stream 实现异步简历分析，支持实时查看处理进度（待分析/分析中/已完成/失败）。
稳定性保障：内置分析失败自动重试机制（最多 3 次）与基于内容哈希的重复检测。
分析报告导出：支持将 AI 分析结果一键导出为结构化的 PDF 简历分析报告。

模拟面试模块

个性化出题：基于简历内容智能生成针对性的面试题目，支持实时问答交互。
智能追问流：支持配置多轮智能追问（默认 1 条），构建模拟真实场景的线性问答流。
分批评估机制：创新性采用分批评估策略，有效规避大模型 Token 溢出风险，确保长文本评估稳定性。
智能汇总建议：对分批评估结果进行二次汇总，提供多维度的改进建议、表现趋势与统计信息。
报告一键导出：支持异步生成并导出详细的 PDF 模拟面试评估报告。

知识库管理模块

文档智能处理：支持 PDF、DOCX、Markdown 等多种格式文档的自动上传、分块与异步向量化。
RAG 检索增强：集成向量数据库，通过检索增强生成（RAG）提升 AI 问答的准确性与专业度。
流式响应交互：基于 SSE（Server-Sent Events）技术实现打字机式流式响应。
智能问答对话：支持基于知识库内容的智能问答，并提供直观的知识库统计信息。

TODO

问答助手的 Markdown 展示优化
知识库管理页面的知识库下载
异步生成模拟面试评估报告
Docker 快速部署
添加 API 限流保护
前端性能优化（RAG 聊天 - 虚拟列表）
模拟面试增加追问功能
打通模拟面试和知识库

效果展示

简历与面试

简历库：

简历上传分析：

简历分析详情：

面试记录：

面试详情：

模拟面试：

知识库

知识库管理：

问答助手：

page-qa-assistant

项目结构


interview-guide/
├── app/                              # 后端应用
│   ├── src/main/java/interview/guide/
│   │   ├── App.java                  # 主启动类
│   │   ├── common/                   # 通用模块
│   │   │   ├── config/               # 配置类
│   │   │   ├── exception/            # 异常处理
│   │   │   └── result/               # 统一响应
│   │   ├── infrastructure/           # 基础设施
│   │   │   ├── export/               # PDF 导出
│   │   │   ├── file/                 # 文件处理
│   │   │   ├── redis/                # Redis 服务
│   │   │   └── storage/              # 对象存储
│   │   └── modules/                  # 业务模块
│   │       ├── interview/            # 面试模块
│   │       ├── knowledgebase/        # 知识库模块
│   │       └── resume/               # 简历模块
│   └── src/main/resources/
│       ├── application.yml           # 应用配置
│       └── prompts/                  # AI 提示词模板
│
├── frontend/                         # 前端应用
│   ├── src/
│   │   ├── api/                      # API 接口
│   │   ├── components/               # 公共组件
│   │   ├── pages/                    # 页面组件
│   │   ├── types/                    # 类型定义
│   │   └── utils/                    # 工具函数
│   ├── package.json
│   └── vite.config.ts
│
└── README.md

快速开始

环境要求：

依赖	版本	必需
JDK	21+	是
Node.js	18+	是
PostgreSQL	14+	是
pgvector 扩展	-	是
Redis	6+	是
S3 兼容存储	-	是

1. 克隆项目


git clone https://github.com/Snailclimb/interview-guide.git
cd interview-guide

2. 配置数据库


-- 创建数据库
CREATE DATABASE interview_guide;

-- 连接数据库并启用 pgvector 扩展（可选，启动后端SpringAI框架底层会自动创建）
CREATE EXTENSION vector;

3. 配置环境变量


# AI API 密钥（阿里云 DashScope）
export AI_BAILIAN_API_KEY=your_api_key

4. 修改应用配置

编辑 app/src/main/resources/application.yml：


spring:
  # PostgreSQL数据库配置
  datasource:
    url: jdbc:postgresql://${POSTGRES_HOST:localhost}:${POSTGRES_PORT:5432}/${POSTGRES_DB:interview_guide}
    username: ${POSTGRES_USER:postgres}
    password: ${POSTGRES_PASSWORD:123456}
    driver-class-name: org.postgresql.Driver

  jpa:
    hibernate:
      ddl-auto: create #首次启动用 create，表创建成功后，改回 update

  # Redisson配置 (使用 spring.redis.redisson，参考官方文档)
  redis:
    redisson:
      config: |
        singleServerConfig:
          address: "redis://${REDIS_HOST:localhost}:${REDIS_PORT:6379}"
          database: 0
          connectionMinimumIdleSize: 10
          connectionPoolSize: 64
          subscriptionConnectionMinimumIdleSize: 1
          subscriptionConnectionPoolSize: 50

# RustFS (S3兼容) 存储配置
app:
  # 面试配置
  interview:
    follow-up-count: ${APP_INTERVIEW_FOLLOW_UP_COUNT:1}    # 每个主问题生成追问数量
    evaluation:
      batch-size: ${APP_INTERVIEW_EVALUATION_BATCH_SIZE:8} # 回答评估分批大小
  storage:
    endpoint: ${APP_STORAGE_ENDPOINT:http://localhost:9000}
    access-key: ${APP_STORAGE_ACCESS_KEY:wr45VXJZhCxc6FAWz0YR}
    secret-key: ${APP_STORAGE_SECRET_KEY:GtKxV57WJkpw4CvASPBzTy2DYElLnRqh8dIXQa0m}
    bucket: ${APP_STORAGE_BUCKET:interview-guide}
    region: ${APP_STORAGE_REGION:us-east-1}

⚠️注意：

JPA 的 ddl-auto 首次启动用 create，表创建成功后，改回 update。
如果本地已经 Minio 的话，可以用其替换 RusfFS。

5. 启动服务

后端：


./gradlew bootRun

后端服务启动于 http://localhost:8080

前端：


cd frontend
pnpm install
pnpm dev

前端服务启动于 http://localhost:5173

Docker 快速部署

本项目提供了完整的 Docker 支持，可以一键启动所有服务（前后端、数据库、中间件）。

1. 前置准备

安装 Docker 和 Docker Compose
申请阿里云百炼 API Key（用于 AI 对话功能）

2. 快速启动

在项目根目录下执行：


# 1. 复制环境变量配置文件
cp .env.example .env

# 2. 编辑 .env 文件，填入 AI 配置
# vim .env
# 必填：AI_BAILIAN_API_KEY=your_key_here
# 可选：AI_MODEL=qwen-plus        # 默认值为 qwen-plus
#        # 也可以改为 qwen-max、qwen-long 等其他可用模型
#
# 面试参数配置（可选）：
# APP_INTERVIEW_FOLLOW_UP_COUNT=1         # 每个主问题生成追问数量（默认 1）
# APP_INTERVIEW_EVALUATION_BATCH_SIZE=8   # 回答评估分批大小（默认 8）

# 3. 构建并启动所有服务
docker-compose up -d --build

3. 服务访问

启动完成后，您可以通过以下地址访问各个服务：

服务	地址	默认账号	默认密码	说明
前端应用	http://localhost	-	-	用户访问入口
后端 API	http://localhost:8080	-	-	Swagger/接口文档
MinIO 控制台	http://localhost:9001	`minioadmin`	`minioadmin`	对象存储管理
MinIO API	`localhost:9000`	-	-	S3 兼容接口
PostgreSQL	`localhost:5432`	`postgres`	`password`	数据库 (包含 pgvector)
Redis	`localhost:6379`	-	-	缓存与消息队列

4. 常用运维命令


# 查看服务状态
docker-compose ps

# 查看后端日志
docker-compose logs -f app

# 停止并移除所有服务
docker-compose down

# 清理无用镜像（构建产生的中间层）
docker image prune -f

使用场景

用户角色	使用场景
求职者	上传简历获取分析建议，进行模拟面试练习
HR/招聘人员	批量分析简历，评估候选人能力
培训机构	提供面试培训服务，管理知识库资源

常见问题

Q: 数据库表创建失败/数据丢失

这大概率是 JPA 的 ddl-auto 配置不对的原因。ddl-auto 模式对比：

模式	行为	适用场景
create	无条件删除并重建所有表	开发/测试环境
update	对比现有 schema，只执行增量更新	开发环境
validate	只验证，不修改	生产环境
none	什么都不做	生产环境

对于新数据库，推荐：


# 首次启动用 create
jpa:
  hibernate:
    ddl-auto: create

# 表创建成功后，改回 update
jpa:
  hibernate:
    ddl-auto: update

记得改回 update，否则每次重启都会删除所有数据！

Q: 知识库向量化失败

当 initialize-schema: false 时，Spring AI 不会自动创建 vector_store 表。


spring:
  ai:
    vectorstore:
      pgvector:
        initialize-schema: true

建议开发环境设置为 true，方便快速启动。生产环境设置为 false，手动管理数据库 schema，避免意外变更。

Q: 简历分析失败

检查一下阿里云 DashScope API KEY 是否配置正确（申请地址：https://bailian.console.aliyun.com/）。

Q: 简历分析一直显示"分析中"？

检查 Redis 连接和 Stream Consumer 是否正常运行。查看后端日志确认是否有错误。

Q: PDF 导出失败或中文显示异常？

项目已内置中文字体（珠圆玉润仿宋），支持跨平台导出。如遇到问题，请检查：

字体文件是否存在：app/src/main/resources/fonts/ZhuqueFangsong-Regular.ttf
检查日志中的字体加载信息
确认 iText 依赖是否正确

贡献

欢迎提交 Issue 和 Pull Request！

许可证

AGPL-3.0 License（只要通过网络提供服务，就必须向用户公开修改后的源码）