581 lines
16 KiB
Markdown
581 lines
16 KiB
Markdown
# AI模拟面试平台
|
||
|
||
`面试准备` `AI面试` `简历分析` `FastAPI` `Python` `向量数据库` `LLM`
|
||
|
||
# Elios AI 面试服务
|
||
|
||
**一个AI驱动的模拟面试平台，通过个性化简历分析、自适应问题生成和实时答案评估，帮助候选人备战技术面试。**
|
||
|
||
[](https://www.python.org/downloads/)
|
||
[](https://fastapi.tiangolo.com/)
|
||
[](LICENSE)
|
||
[](https://github.com/psf/black)
|
||
|
||
---
|
||
|
||
## 📖 概述
|
||
|
||
Elios AI 面试服务利用**大型语言模型（LLM）**和**向量数据库**，提供智能化、个性化的模拟面试体验。该平台分析候选人简历，生成相关问题，实时评估答案，并提供全面反馈，帮助候选人提升面试表现。
|
||
|
||
### 核心功能
|
||
|
||
- **🎯 简历分析**：从简历中提取技能、经验和教育背景
|
||
- **🤖 自适应问题**：利用基于向量的范例检索生成个性化面试问题
|
||
- **📊 实时评估**：多维度答案评估与即时反馈
|
||
- **💬 语音与文字支持**：通过文字聊天或语音进行面试（语音功能规划中）
|
||
- **📈 综合报告**：详细的表现分析与可执行的改进建议
|
||
- **🔄 可替换AI提供商**：轻松集成 OpenAI、Claude 或 Llama
|
||
|
||
### 技术栈
|
||
|
||
- **后端**：Python 3.11+、FastAPI、Pydantic
|
||
- **数据库**：PostgreSQL（Neon）、SQLAlchemy 2.0（异步）
|
||
- **AI/ML**：OpenAI GPT-4、Pinecone 向量数据库
|
||
- **架构**：整洁架构（六边形/端口与适配器）
|
||
- **测试**：pytest、pytest-asyncio
|
||
- **代码质量**：ruff、black、mypy
|
||
|
||
### 主要流程
|
||
|
||
#### 1. 准备阶段（扫描简历并生成主题）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
actor Candidate as 候选人
|
||
participant ChatUI as 聊天界面 / 前端
|
||
participant CVAnalyzer as 📄 简历分析组件
|
||
participant VectorDB as 🧠 向量数据库
|
||
participant AIEngine as 🤖 AI面试引擎
|
||
|
||
Candidate->>ChatUI: 上传简历文件
|
||
ChatUI->>CVAnalyzer: 发送简历进行分析
|
||
CVAnalyzer->>VectorDB: 生成并存储简历嵌入向量
|
||
VectorDB-->>CVAnalyzer: 确认嵌入向量已存储
|
||
CVAnalyzer-->>ChatUI: 返回提取的技能和建议主题
|
||
ChatUI-->>Candidate: 显示准备摘要
|
||
ChatUI->>AIEngine: 通知就绪状态（技能、主题）
|
||
AIEngine-->>ChatUI: 已确认
|
||
```
|
||
|
||
#### 2. 面试阶段（实时问答）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
actor Candidate as 候选人
|
||
participant ChatUI as 聊天界面 / 前端
|
||
participant AIEngine as 🤖 AI面试引擎
|
||
participant VectorDB as 🧠 向量数据库
|
||
participant QBank as 📚 题库服务
|
||
participant STT as 🎤 语音转文字
|
||
participant TTS as 🗣️ 文字转语音
|
||
participant Analytics as 📊 分析与反馈服务
|
||
|
||
%% --- 开始面试 ---
|
||
Candidate->>ChatUI: 开始面试
|
||
ChatUI->>AIEngine: 请求第一个问题
|
||
AIEngine->>VectorDB: 查询相似问题嵌入向量（基于简历主题）
|
||
VectorDB-->>AIEngine: 返回候选问题
|
||
AIEngine->>QBank: 获取选定问题
|
||
QBank-->>AIEngine: 返回问题详情
|
||
AIEngine-->>ChatUI: 发送问题文本
|
||
ChatUI-->>TTS: 将问题文本转为语音
|
||
TTS-->>Candidate: 播放AI语音问题
|
||
|
||
%% --- 候选人作答 ---
|
||
Candidate->>STT: 口头作答
|
||
STT-->>AIEngine: 发送转录文本
|
||
AIEngine->>VectorDB: 比较答案嵌入向量并评估质量
|
||
VectorDB-->>AIEngine: 返回相似度和语义评分
|
||
AIEngine->>Analytics: 发送答案评估（评分、情感、推理）
|
||
Analytics-->>AIEngine: 已确认
|
||
|
||
alt 还有更多问题
|
||
AIEngine->>VectorDB: 检索下一个合适的问题
|
||
VectorDB-->>AIEngine: 返回下一个候选问题
|
||
AIEngine-->>ChatUI: 发送下一个问题
|
||
ChatUI-->>TTS: 转为语音并播放
|
||
TTS-->>Candidate: 播放下一个问题
|
||
else 面试结束
|
||
AIEngine-->>ChatUI: 通知面试结束
|
||
end
|
||
```
|
||
|
||
#### 3. 最终阶段（评估与报告）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
actor Candidate as 候选人
|
||
participant ChatUI as 聊天界面 / 前端
|
||
participant AIEngine as 🤖 AI面试引擎
|
||
participant Analytics as 📊 分析与反馈服务
|
||
|
||
AIEngine->>Analytics: 发送最终面试摘要（评分、指标、转录）
|
||
Analytics->>Analytics: 汇总结果并生成报告
|
||
Analytics-->>AIEngine: 已确认
|
||
|
||
AIEngine-->>ChatUI: 通知面试完成
|
||
ChatUI->>Analytics: 请求最终反馈报告
|
||
Analytics-->>ChatUI: 返回详细反馈和改进建议
|
||
ChatUI-->>Candidate: 显示表现摘要和洞察
|
||
```
|
||
|
||
---
|
||
|
||
## 🏗️ 架构
|
||
|
||
本项目遵循**整洁架构**（六边形/端口与适配器）：领域层（纯业务逻辑）→ 应用层（用例）→ 适配器层（外部服务）→ 基础设施层（配置、依赖注入）。
|
||
|
||
📚 **[完整架构详情 →](docs/system-architecture.md)**
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### ⚡ 5分钟配置
|
||
|
||
**只想快速运行？** 复制并粘贴以下命令：
|
||
|
||
```bash
|
||
# 配置环境并安装依赖
|
||
python -m venv venv && venv\Scripts\activate && pip install -e ".[dev]"
|
||
|
||
# 配置并运行数据库迁移
|
||
cp .env.example .env.local && alembic upgrade head
|
||
|
||
# 启动服务器
|
||
python -m src.main
|
||
```
|
||
|
||
然后访问：**http://localhost:8000/docs**
|
||
|
||
⚠️ **注意**：完整功能需要先编辑 `.env.local` 填入您的 API 密钥。
|
||
|
||
---
|
||
|
||
### 📋 详细安装说明
|
||
|
||
#### 前提条件
|
||
|
||
- Python 3.11 或更高版本
|
||
- pip（Python 包管理器）
|
||
- PostgreSQL 数据库（或 Neon 账户）
|
||
- OpenAI API 密钥
|
||
- Pinecone API 密钥
|
||
|
||
#### 安装步骤
|
||
|
||
1. **克隆仓库**
|
||
```bash
|
||
git clone https://github.com/elios/elios-ai-service.git
|
||
cd EliosAIService
|
||
```
|
||
|
||
2. **创建虚拟环境**
|
||
```bash
|
||
python -m venv venv
|
||
|
||
# Windows
|
||
venv\Scripts\activate
|
||
|
||
# Linux/macOS
|
||
source venv/bin/activate
|
||
```
|
||
|
||
3. **安装依赖**
|
||
```bash
|
||
pip install -e ".[dev]"
|
||
```
|
||
|
||
4. **配置环境变量**
|
||
```bash
|
||
cp .env.example .env.local
|
||
```
|
||
|
||
编辑 `.env.local` 填入您的凭据：
|
||
```env
|
||
# 数据库
|
||
DATABASE_URL=postgresql://user:password@host:5432/elios_interviews
|
||
|
||
# LLM 提供商
|
||
LLM_PROVIDER=openai
|
||
OPENAI_API_KEY=sk-your-api-key-here
|
||
OPENAI_MODEL=gpt-4
|
||
|
||
# 向量数据库
|
||
VECTOR_DB_PROVIDER=pinecone
|
||
PINECONE_API_KEY=your-pinecone-api-key
|
||
PINECONE_INDEX_NAME=elios-questions
|
||
```
|
||
|
||
5. **运行数据库迁移**
|
||
```bash
|
||
alembic upgrade head
|
||
```
|
||
|
||
6. **验证数据库设置**
|
||
```bash
|
||
python scripts/verify_db.py
|
||
```
|
||
|
||
7. **启动服务器**
|
||
```bash
|
||
python -m src.main
|
||
```
|
||
|
||
服务器运行于：http://localhost:8000
|
||
|
||
API 文档：http://localhost:8000/docs
|
||
|
||
---
|
||
|
||
## 📖 文档
|
||
|
||
### 用户文档
|
||
- **[项目概述与PDR](docs/project-overview-pdr.md)** - 产品需求、功能和路线图
|
||
- **[数据库配置指南](DATABASE_SETUP.md)** - 全面的数据库配置说明
|
||
- **[环境配置指南](ENV_SETUP.md)** - 环境配置最佳实践
|
||
|
||
### 开发者文档
|
||
- **[系统架构](docs/system-architecture.md)** - 详细架构文档
|
||
- **[代码库摘要](docs/codebase-summary.md)** - 项目结构和技术栈
|
||
- **[代码规范](docs/code-standards.md)** - 编码约定和最佳实践
|
||
- **[CLAUDE.md](CLAUDE.md)** - AI助手开发指南
|
||
|
||
---
|
||
|
||
## 🧪 开发
|
||
|
||
### 用于测试的模拟适配器
|
||
|
||
**模拟适配器**在无需 API 费用或网络延迟的情况下模拟外部服务，在开发环境中默认启用。
|
||
|
||
**可用模拟**（共6个）：
|
||
- `MockLLMAdapter` - 模拟 OpenAI/LLM 响应
|
||
- `MockVectorSearchAdapter` - 内存向量搜索
|
||
- `MockSTTAdapter` - 模拟语音转文字
|
||
- `MockTTSAdapter` - 模拟文字转语音
|
||
- `MockCVAnalyzerAdapter` - 基于文件名的简历解析
|
||
- `MockAnalyticsAdapter` - 内存性能跟踪
|
||
|
||
**配置**：
|
||
```env
|
||
# .env.local
|
||
USE_MOCK_ADAPTERS=true # 使用模拟（默认，测试速度快）
|
||
USE_MOCK_ADAPTERS=false # 使用真实服务（需要API密钥）
|
||
```
|
||
|
||
**优势**：
|
||
- 测试速度提升10倍（约5秒 vs 约30秒）
|
||
- 开发期间无 API 费用
|
||
- 无网络依赖
|
||
- 确定性测试结果
|
||
|
||
**注意**：数据库仓库（PostgreSQL）故意不使用模拟——数据完整性测试使用真实数据库。
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
# 运行所有测试（默认启用模拟）
|
||
pytest
|
||
|
||
# 带覆盖率运行
|
||
pytest --cov=src --cov-report=html
|
||
|
||
# 运行特定类型的测试
|
||
pytest tests/unit/ # 仅单元测试
|
||
pytest tests/integration/ # 仅集成测试
|
||
pytest tests/e2e/ # 仅端到端测试
|
||
|
||
# 使用真实适配器测试（需要API密钥）
|
||
USE_MOCK_ADAPTERS=false pytest
|
||
```
|
||
|
||
### 代码质量
|
||
|
||
```bash
|
||
# 格式化代码
|
||
black src/
|
||
|
||
# 代码检查
|
||
ruff check src/
|
||
ruff check --fix src/ # 自动修复问题
|
||
|
||
# 类型检查
|
||
mypy src/
|
||
|
||
# 运行所有检查
|
||
black src/ && ruff check src/ && mypy src/
|
||
```
|
||
|
||
### 数据库操作
|
||
|
||
```bash
|
||
# 创建新迁移
|
||
alembic revision --autogenerate -m "描述"
|
||
|
||
# 应用迁移
|
||
alembic upgrade head
|
||
|
||
# 回滚一个迁移
|
||
alembic downgrade -1
|
||
|
||
# 查看迁移历史
|
||
alembic history
|
||
|
||
# 验证数据库
|
||
python scripts/verify_db.py
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 使用示例
|
||
|
||
### 1. 创建候选人
|
||
|
||
```python
|
||
import httpx
|
||
|
||
async with httpx.AsyncClient() as client:
|
||
response = await client.post(
|
||
"http://localhost:8000/api/candidates",
|
||
json={
|
||
"name": "张三",
|
||
"email": "zhangsan@example.com"
|
||
}
|
||
)
|
||
candidate = response.json()
|
||
print(f"已创建候选人：{candidate['id']}")
|
||
```
|
||
|
||
### 2. 上传并分析简历
|
||
|
||
```python
|
||
async with httpx.AsyncClient() as client:
|
||
with open("resume.pdf", "rb") as cv_file:
|
||
response = await client.post(
|
||
"http://localhost:8000/api/cv/upload",
|
||
files={"file": cv_file},
|
||
data={"candidate_id": candidate['id']}
|
||
)
|
||
cv_analysis = response.json()
|
||
print(f"发现的技能：{cv_analysis['skills']}")
|
||
```
|
||
|
||
### 3. 开始面试
|
||
|
||
```python
|
||
async with httpx.AsyncClient() as client:
|
||
response = await client.post(
|
||
"http://localhost:8000/api/interviews",
|
||
json={
|
||
"candidate_id": candidate['id'],
|
||
"cv_analysis_id": cv_analysis['id']
|
||
}
|
||
)
|
||
interview = response.json()
|
||
print(f"面试准备就绪，共 {len(interview['question_ids'])} 道题目")
|
||
```
|
||
|
||
### 4. 提交答案
|
||
|
||
```python
|
||
async with httpx.AsyncClient() as client:
|
||
response = await client.post(
|
||
f"http://localhost:8000/api/interviews/{interview['id']}/answers",
|
||
json={
|
||
"question_id": interview['question_ids'][0],
|
||
"answer_text": "我的答案..."
|
||
}
|
||
)
|
||
evaluation = response.json()
|
||
print(f"得分：{evaluation['score']}/100")
|
||
print(f"反馈：{evaluation['feedback']}")
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 项目结构
|
||
|
||
```
|
||
EliosAIService/
|
||
├── src/
|
||
│ ├── domain/ # 核心业务逻辑（8个模型，13个端口）
|
||
│ ├── application/ # 用例（共8个）
|
||
│ ├── adapters/ # 外部服务实现（20+）
|
||
│ └── infrastructure/ # 配置、依赖注入、数据库
|
||
├── alembic/ # 数据库迁移
|
||
├── docs/ # 文档
|
||
└── tests/ # 测试套件
|
||
```
|
||
|
||
📚 **[完整结构 →](docs/codebase-summary.md)**
|
||
|
||
---
|
||
|
||
## 🔧 配置
|
||
|
||
配置通过环境变量管理，优先级如下：
|
||
|
||
1. `.env.local`（最高优先级，已加入 .gitignore）
|
||
2. `.env`（可提交，作为模板）
|
||
3. 系统环境变量
|
||
4. Pydantic 默认值
|
||
|
||
### 主要配置项
|
||
|
||
- **应用**：名称、版本、环境
|
||
- **LLM 提供商**：OpenAI、Claude 或 Llama 配置
|
||
- **向量数据库**：Pinecone、Weaviate 或 ChromaDB 设置
|
||
- **PostgreSQL**：数据库连接和凭据
|
||
- **语音服务**：Azure STT、Edge TTS（规划中）
|
||
- **面试设置**：问题数量、评分、超时
|
||
|
||
详细配置指南请参阅 [ENV_SETUP.md](ENV_SETUP.md)。
|
||
|
||
---
|
||
|
||
## 🤝 贡献
|
||
|
||
我们欢迎贡献！请参阅我们的贡献指南（即将发布）。
|
||
|
||
### 开发工作流
|
||
|
||
1. Fork 本仓库
|
||
2. 创建功能分支（`git checkout -b feature/amazing-feature`）
|
||
3. 按照我们的[代码规范](docs/code-standards.md)进行修改
|
||
4. 运行测试和质量检查
|
||
5. 使用[约定式提交](https://www.conventionalcommits.org/)格式提交
|
||
6. 推送到您的分支（`git push origin feature/amazing-feature`）
|
||
7. 提交 Pull Request
|
||
|
||
### 提交信息格式
|
||
|
||
```
|
||
<类型>(<范围>): <主题>
|
||
|
||
示例：
|
||
feat(domain): 添加带状态管理的面试聚合根
|
||
fix(persistence): 处理答案映射器中的 NULL 元数据
|
||
docs: 更新简历上传端点的API文档
|
||
```
|
||
|
||
---
|
||
|
||
## 🗺️ 路线图
|
||
|
||
### 第一阶段：基础（v0.1.0 - v0.2.1）- 已完成 ✅
|
||
- ✅ 领域模型（8个实体）和端口（13个接口）
|
||
- ✅ PostgreSQL 持久化层（7个仓库）
|
||
- ✅ OpenAI 和 Azure OpenAI LLM 适配器
|
||
- ✅ Pinecone 和 ChromaDB 向量适配器
|
||
- ✅ Azure 语音服务（STT/TTS）
|
||
- ✅ 数据库迁移
|
||
- ✅ REST API 实现（5个端点）
|
||
- ✅ WebSocket 实时协议
|
||
- ✅ 领域驱动状态管理
|
||
- ✅ 带追问的上下文感知评估
|
||
- ✅ 会话编排器（状态机）
|
||
|
||
### 第二阶段：核心功能（v0.2.0 - v0.5.0）
|
||
- ⏳ 语音面试支持
|
||
- ⏳ 高级问题生成
|
||
- ⏳ 面试分析
|
||
- ⏳ 性能基准测试
|
||
- ⏳ 前端集成
|
||
|
||
### 第三阶段：智能增强（v0.6.0 - v0.8.0）
|
||
- ⏳ 多LLM支持（Claude、Llama）
|
||
- ⏳ 行为问题分析
|
||
- ⏳ 性格洞察
|
||
- ⏳ 技能差距分析
|
||
|
||
### 第四阶段：规模化与完善（v0.9.0 - v1.0.0）
|
||
- ⏳ 多语言支持
|
||
- ⏳ 团队/组织功能
|
||
- ⏳ 移动应用支持
|
||
- ⏳ 生产环境部署
|
||
|
||
详细路线图请参阅[项目概述与PDR](docs/project-overview-pdr.md)。
|
||
|
||
---
|
||
|
||
## 📊 当前状态
|
||
|
||
**版本**：0.2.1（基础 + 自适应面试 + 会话编排）
|
||
|
||
**已实现**：
|
||
- ✅ 整洁架构结构
|
||
- ✅ 领域模型（8个实体，包括 Evaluation、ErrorCodes）
|
||
- ✅ 仓库端口（13个接口，包括 EvaluationRepositoryPort）
|
||
- ✅ PostgreSQL 持久化（7个仓库）
|
||
- ✅ OpenAI 和 Azure OpenAI LLM 适配器
|
||
- ✅ Pinecone 和 ChromaDB 向量适配器
|
||
- ✅ Azure 语音服务（STT/TTS 适配器）
|
||
- ✅ 带 Alembic 的异步 SQLAlchemy 2.0
|
||
- ✅ 配置管理
|
||
- ✅ 依赖注入容器
|
||
- ✅ 用例（共8个：AnalyzeCV、PlanInterview、ProcessAnswerAdaptive、FollowUpDecision、CombineEvaluation、GenerateSummary、CompleteInterview、GetNextQuestion）
|
||
- ✅ REST API（5个面试端点）+ WebSocket 协议
|
||
- ✅ 领域驱动状态管理（面试状态机）
|
||
- ✅ 带追问的上下文感知评估
|
||
- ✅ 会话编排器（WebSocket 的状态机模式）
|
||
- ✅ 综合面试摘要生成
|
||
|
||
**进行中**：
|
||
- 🔄 简历处理适配器（spaCy、PyPDF2）
|
||
- 🔄 测试覆盖率扩展（核心功能85%+）
|
||
|
||
**计划中**：
|
||
- ⏳ 认证与授权
|
||
- ⏳ 速率限制
|
||
- ⏳ Docker 部署
|
||
- ⏳ 生产环境优化
|
||
|
||
---
|
||
|
||
## 🛡️ 安全
|
||
|
||
- API 密钥存储在环境变量中（从不提交）
|
||
- 通过参数化查询防止 SQL 注入
|
||
- 使用 Pydantic 进行输入验证
|
||
- 强制 HTTPS（生产环境）
|
||
- 静态数据加密（Neon 内置）
|
||
- GDPR 合规性考虑
|
||
|
||
安全漏洞请报告至：security@elios.ai
|
||
|
||
---
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 MIT 许可证，详情请参阅 [LICENSE](LICENSE) 文件。
|
||
|
||
---
|
||
|
||
## 🙏 致谢
|
||
|
||
- **OpenAI** 提供 GPT-4 和 Embeddings API
|
||
- **Pinecone** 提供向量数据库
|
||
- **FastAPI** 提供优秀的 Web 框架
|
||
- **Neon** 提供无服务器 PostgreSQL
|
||
- **Pydantic** 提供数据验证
|
||
- **SQLAlchemy** 提供 ORM
|
||
|
||
---
|
||
|
||
## 📞 联系方式
|
||
|
||
- **网站**：https://elios.ai
|
||
- **邮箱**：contact@elios.ai
|
||
- **问题反馈**：[GitHub Issues](https://github.com/elios/elios-ai-service/issues)
|
||
- **讨论**：[GitHub Discussions](https://github.com/elios/elios-ai-service/discussions)
|
||
|
||
---
|
||
|
||
## ⭐ 支持
|
||
|
||
如果您觉得这个项目有帮助，请考虑在 GitHub 上给它点个星！这有助于更多人发现该项目，也激励我们持续开发。
|
||
|
||
---
|
||
|
||
**以整洁架构原则构建，倾注心血 ❤️** |