README.md

metadata

title: HR Dialogue Evaluation API
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit
app_port: 7860

HR 对话质量评估 API

版本: v1.0 论文: arXiv:2402.01018v1 技术栈: FastAPI + DeepSeek LLM + ML Models

---

应用简介

HR 对话质量评估与智能回复系统的核心 API 服务，提供：

• 三维评估: 正确性 (40%) + 合规性 (35%) + 情绪友好度 (25%)
• 智能对话: 意图识别、知识检索、自动回复生成
• 情绪感知: 根据用户情绪和场景自动调整回复风格
• 多轮对话: 支持上下文追踪

---

快速开始

1. 安装依赖

python3.9 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. 配置环境变量

cp .env.example .env

最小配置示例：

# API 配置
API_PORT=8001
LOG_LEVEL=INFO

# LLM API（重要！影响回复质量）
LLM_API_ENABLED=true
LLM_API_PROVIDER=deepseek
LLM_API_KEY=sk-your-deepseek-api-key
LLM_API_MODEL=deepseek-chat

3. 准备数据文件

确保以下文件存在：

data/
├── knowledge_base.json       # 知识库 Q&A
├── sensitive_words.json      # 敏感词库
└── whitelist.json            # 合规白名单

4. 启动服务

# 开发模式
uvicorn hr_eval_api.main:app --reload --port 8001

# 或使用启动脚本
./start.sh

5. 访问服务

• API 文档: http://localhost:8001/docs
• 健康检查: http://localhost:8001/api/v1/health
• ReDoc 文档: http://localhost:8001/redoc

---

API 使用示例

智能对话（带多轮上下文）

curl -X POST 'http://localhost:8001/api/v1/chat' \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "年假有多少天？",
    "session_id": "user-123",
    "show_reasoning": true
  }'

多轮对话示例：

# 第一轮
curl -X POST 'http://localhost:8001/api/v1/chat' \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "年假有多少天？",
    "session_id": "user-123"
  }'

# 第二轮（带对话历史）
curl -X POST 'http://localhost:8001/api/v1/chat' \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "2020年",
    "conversation_history": [
      {"role": "user", "content": "年假有多少天？"},
      {"role": "assistant", "content": "请问您是哪一年加入公司的呢？"}
    ],
    "session_id": "user-123"
  }'

评估单条对话

curl -X POST 'http://localhost:8001/api/v1/evaluate' \
  -H 'Content-Type: application/json' \
  -d '{
    "dialogue": [
      {"speaker": "HR Assistant", "utterance": "您好，请问有什么可以帮您？"},
      {"speaker": "Employee", "utterance": "我想申请培训。"}
    ],
    "dialogue_id": "001"
  }'

---

项目结构

hr_eval_api/
├── main.py                     # FastAPI 主入口
├── config.py                   # 全局配置
├── requirements.txt            # Python 依赖
├── .env.example                # 环境变量模板
│
├── hr_eval_api/
│   ├── services/               # 业务逻辑
│   │   ├── evaluator.py        # 核心评估器
│   │   ├── chatbot.py          # 智能对话助手
│   │   ├── chatbot_executor.py # 对话执行器（含Prompt系统）
│   │   ├── intelligence_analyzer.py  # 意图/场景分析
│   │   ├── conversation_context.py   # 上下文管理
│   │   ├── llm_api_client.py   # LLM API 客户端
│   │   └── queue_manager.py    # 队列管理
│   │
│   ├── models/                 # ML 模型
│   │   ├── correctness.py      # 正确性评估
│   │   ├── compliance.py       # 合规性检测
│   │   └── sentiment.py        # 情绪分析
│   │
│   ├── schemas/                # 数据模型
│   │   └── api_models.py       # Pydantic 模型
│   │
│   ├── routers/                # API 路由
│   │   └── config.py           # 配置路由
│   │
│   └── middleware/             # 中间件
│       └── access_logging.py   # 访问日志
│
├── data/                       # 数据文件
│   ├── knowledge_base.json     # 知识库
│   ├── sensitive_words.json    # 敏感词库
│   └── whitelist.json          # 白名单
│
├── models/                     # 微调模型
│   ├── sbert-hr-v2/            # Sentence-BERT 微调模型
│   └── sentiment-hr/           # 情绪分析微调模型
│
├── scripts/                    # 工具脚本
│   ├── train_sbert.py         # Sentence-BERT 训练
│   ├── train_bert_classifier.py  # BERT 分类器训练
│   └── ...
│
└── static/                     # 静态文件
    └── chat.html               # 聊天界面

---

文档导航

完整文档请查看项目文档中心 ../docs/

文档	说明
../docs/INDEX.md	📚 文档中心索引
../docs/app/ARCHITECTURE.md	系统架构设计
../docs/app/API_GUIDE.md	API 使用指南
../docs/app/PROMPT_CONFIG_GUIDE.md	Prompt 配置指南
../docs/app/DEPLOYMENT_GUIDE.md	通用部署指南
../docs/app/FLYIO_DEPLOYMENT.md	Fly.io 部署
../docs/app/N8N_INTEGRATION.md	n8n 工作流集成

---

模型说明

已集成模型

模型	用途	状态
Sentence-BERT	语义相似度/正确性评估	✅ 微调完成
情绪分析模型	情感识别	✅ 微调完成
Intent BERT	意图分类	✅ 可选
DeepSeek LLM	对话生成	✅ API 集成
Qwen LoRA	对话生成（本地）	✅ 可选

模型文件结构

models/
├── sbert-hr-v2/              # Sentence-BERT 微调模型
│   ├── config.json
│   ├── model.safetensors
│   └── ...
├── sentiment-hr/             # 情绪分析微调模型
│   └── final_model/
│       ├── config.json
│       └── model_state.pdparams
└── checkpoints/              # 预训练模型缓存

---

配置说明

环境变量

变量	说明	默认值
API_PORT	API 端口	8000
LOG_LEVEL	日志级别	INFO
DEBUG	调试模式	false
CORS_ORIGINS	跨域来源	*

LLM API 配置（重要）

# 启用 LLM API（强烈推荐）
LLM_API_ENABLED=true

# API 提供商
LLM_API_PROVIDER=deepseek  # 可选: openai, moonshot, zhipu 等

# API 密钥
LLM_API_KEY=sk-your-api-key

# 模型名称
LLM_API_MODEL=deepseek-chat

# 生成参数
LLM_API_TEMPERATURE=0.7
LLM_API_MAX_TOKENS=512

Redis 配置（可选）

USE_REDIS=true
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your-password

---

评估结果说明

整体评分 (0-100)

评分 = 正确性(40%) + 合规性(35%) + 情绪(25%)

├─ ≥80: 优秀
├─ 60-79: 良好
└─ <60: 需要改进

正确性等级

• good: 相似度 ≥ 0.85
• fair: 0.6 ≤ 相似度 < 0.85
• poor: 相似度 < 0.6

违规严重程度

• high: 歧视类、违法用工类
• medium: 隐私侵犯、威胁类
• low: 其他违规

---

生产部署

推荐架构

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Netlify    │     │   Fly.io     │     │  Supabase    │
│  (前端)      │────▶│  (hr_eval_api)│◀────│  (DB+Redis)  │
└──────────────┘     └──────────────┘     └──────────────┘
                             │
                             ▼
                      ┌──────────────┐
                      │   Fly.io     │
                      │  (n8n)       │
                      └──────────────┘

快速部署

# 使用 Fly.io 一键部署脚本
cd hr_eval_api
./deploy-fly.sh

详见：FLYIO_DEPLOYMENT.md

---

常见问题

Q: 如何获取 DeepSeek API Key？

访问 DeepSeek 开放平台 注册并获取 API Key。

Q: 模型下载慢怎么办？

# 使用 HF 镜像
export HF_ENDPOINT=https://hf-mirror.com

Q: 如何禁用 LLM API？

# 在 .env 中设置
LLM_API_ENABLED=false

系统会自动回退到本地模型（如果已训练）或模板回复。

---

许可证

本项目基于 MIT 许可证开源。

---

论文引用

@article{hr_dialogue_eval,
  title={HR Dialogue Quality Evaluation: A Multi-Dimensional Assessment Framework},
  author={...},
  journal={arXiv preprint arXiv:2402.01018v1},
  year={2024}
}