# 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 上给它点个星！这有助于更多人发现该项目，也激励我们持续开发。

---

**以整洁架构原则构建，倾注心血 ❤️**