mc-skills/catalog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
catalog/repos/aia-11-hn-mib--mib-mockinterviewaibot.md

581 lines
16 KiB
Markdown
Raw Normal View History

catalog: 更新 2026-04-07 11:44
2026-04-07 11:44:56 +08:00
# AI模拟面试平台
`面试准备` `AI面试` `简历分析` `FastAPI` `Python` `向量数据库` `LLM`
# Elios AI 面试服务
**一个AI驱动的模拟面试平台，通过个性化简历分析、自适应问题生成和实时答案评估，帮助候选人备战技术面试。**
[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.104+-green.svg)](https://fastapi.tiangolo.com/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](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 上给它点个星！这有助于更多人发现该项目，也激励我们持续开发。
---
**以整洁架构原则构建，倾注心血 ❤️**
Reference in New Issue Copy Permalink