mc-skills/catalog

Fork 0

mc-skills 52efc07510 catalog: 更新 2026-04-07 11:44

2026-04-07 11:44:56 +08:00

16 KiB

Raw Permalink Blame History

AI模拟面试平台

面试准备 AI面试 简历分析 FastAPI Python 向量数据库 LLM

Elios AI 面试服务

一个AI驱动的模拟面试平台，通过个性化简历分析、自适应问题生成和实时答案评估，帮助候选人备战技术面试。

📖 概述

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. 准备阶段（扫描简历并生成主题）

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. 面试阶段（实时问答）

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. 最终阶段（评估与报告）

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: 显示表现摘要和洞察

🏗️ 架构

本项目遵循整洁架构（六边形/端口与适配器）：领域层（纯业务逻辑）→ 应用层（用例）→ 适配器层（外部服务）→ 基础设施层（配置、依赖注入）。

📚 完整架构详情 →

🚀 快速开始

⚡ 5分钟配置

只想快速运行？ 复制并粘贴以下命令：

# 配置环境并安装依赖
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 密钥

安装步骤

克隆仓库

git clone https://github.com/elios/elios-ai-service.git
cd EliosAIService

创建虚拟环境

python -m venv venv

# Windows
venv\Scripts\activate

# Linux/macOS
source venv/bin/activate

安装依赖
```
pip install -e ".[dev]"
```

配置环境变量

cp .env.example .env.local

编辑 .env.local 填入您的凭据：

# 数据库
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

运行数据库迁移
```
alembic upgrade head
```
验证数据库设置
```
python scripts/verify_db.py
```
启动服务器
```
python -m src.main
```
服务器运行于：http://localhost:8000

API 文档：http://localhost:8000/docs

📖 文档

用户文档

项目概述与PDR - 产品需求、功能和路线图
数据库配置指南 - 全面的数据库配置说明
环境配置指南 - 环境配置最佳实践

开发者文档

系统架构 - 详细架构文档
代码库摘要 - 项目结构和技术栈
代码规范 - 编码约定和最佳实践
CLAUDE.md - AI助手开发指南

🧪 开发

用于测试的模拟适配器

模拟适配器在无需 API 费用或网络延迟的情况下模拟外部服务，在开发环境中默认启用。

可用模拟（共6个）：

MockLLMAdapter - 模拟 OpenAI/LLM 响应
MockVectorSearchAdapter - 内存向量搜索
MockSTTAdapter - 模拟语音转文字
MockTTSAdapter - 模拟文字转语音
MockCVAnalyzerAdapter - 基于文件名的简历解析
MockAnalyticsAdapter - 内存性能跟踪

配置：

# .env.local
USE_MOCK_ADAPTERS=true   # 使用模拟（默认，测试速度快）
USE_MOCK_ADAPTERS=false  # 使用真实服务（需要API密钥）

优势：

测试速度提升10倍（约5秒 vs 约30秒）
开发期间无 API 费用
无网络依赖
确定性测试结果

注意：数据库仓库（PostgreSQL）故意不使用模拟——数据完整性测试使用真实数据库。

运行测试

# 运行所有测试（默认启用模拟）
pytest

# 带覆盖率运行
pytest --cov=src --cov-report=html

# 运行特定类型的测试
pytest tests/unit/         # 仅单元测试
pytest tests/integration/  # 仅集成测试
pytest tests/e2e/          # 仅端到端测试

# 使用真实适配器测试（需要API密钥）
USE_MOCK_ADAPTERS=false pytest

代码质量

# 格式化代码
black src/

# 代码检查
ruff check src/
ruff check --fix src/  # 自动修复问题

# 类型检查
mypy src/

# 运行所有检查
black src/ && ruff check src/ && mypy src/

数据库操作

# 创建新迁移
alembic revision --autogenerate -m "描述"

# 应用迁移
alembic upgrade head

# 回滚一个迁移
alembic downgrade -1

# 查看迁移历史
alembic history

# 验证数据库
python scripts/verify_db.py

🎯 使用示例

1. 创建候选人

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. 上传并分析简历

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. 开始面试

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. 提交答案

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/                   # 测试套件

📚 完整结构 →

🔧 配置

配置通过环境变量管理，优先级如下：

.env.local（最高优先级，已加入 .gitignore）
.env（可提交，作为模板）
系统环境变量
Pydantic 默认值

主要配置项

应用：名称、版本、环境
LLM 提供商：OpenAI、Claude 或 Llama 配置
向量数据库：Pinecone、Weaviate 或 ChromaDB 设置
PostgreSQL：数据库连接和凭据
语音服务：Azure STT、Edge TTS（规划中）
面试设置：问题数量、评分、超时

详细配置指南请参阅 ENV_SETUP.md。

🤝 贡献

我们欢迎贡献！请参阅我们的贡献指南（即将发布）。

开发工作流

Fork 本仓库
创建功能分支（git checkout -b feature/amazing-feature）
按照我们的代码规范进行修改
运行测试和质量检查
使用约定式提交格式提交
推送到您的分支（git push origin feature/amazing-feature）
提交 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。

📊 当前状态

版本：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 文件。

🙏 致谢

OpenAI 提供 GPT-4 和 Embeddings API
Pinecone 提供向量数据库
FastAPI 提供优秀的 Web 框架
Neon 提供无服务器 PostgreSQL
Pydantic 提供数据验证
SQLAlchemy 提供 ORM

📞 联系方式

网站：https://elios.ai
邮箱：contact@elios.ai
问题反馈：GitHub Issues
讨论：GitHub Discussions

⭐ 支持

如果您觉得这个项目有帮助，请考虑在 GitHub 上给它点个星！这有助于更多人发现该项目，也激励我们持续开发。

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

16 KiB Raw Permalink Blame History Unescape Escape