EmpValue-AI

用大语言模型 Agent 给员工价值做量化评估,同时守住"AI 不替人下结论"这条线。

EmpValue-AI 面向中大型企业,持续接收员工多维工作数据(日报、任务进度、代码贡献、会议记录、截图、语音), 交给 LangGraph Agent 自动分析,一次推理同时产出三套视图:

员工视角: 建设性成长反馈,给本人看
管理视角: 尖锐的人才诊断与调配建议,给主管 / HR 看
审计视角: 每条结论都带原始证据引用,可追溯、可解释

三套视图刻意分离——同一个判断对员工说和给主管看,措辞和立场本就不该一样。部署上按企业算力在本地与云端间弹性切换,但所有评估结果必须经人工审批才能落地,这条是硬约束,不是 feature。

为什么这么设计

双视角同源分离: 一次推理同时生成员工视图和管理视图,逻辑一致;但语气、措辞、暴露范围严格隔离。员工看到的"成长空间"和主管看到的"ROI 下滑"来自同一份判断。
弹性双模部署: 按硬件自动在本地小模型与云端大模型间切换,保密和效果之间不留死结。
AI 不做人事决策: 合规底线,不是可选项。所有评估必须经主管审批,高风险项还要 HR 复核。

系统架构

┌─────────────────────────────────────────────────────────────┐
│              前端交互层 (Vue 3 + Element Plus)                 │
│  员工端 │ 主管端 │ HR端 │ 管理后台                               │
├─────────────────────────────────────────────────────────────┤
│              API 网关层 (FastAPI)                              │
│  RBAC │ 限流 │ 审计日志 │ 护栏拦截 │ 路由分发                       │
├─────────────────────────────────────────────────────────────┤
│              Agent 编排层 (LangGraph)                         │
│  状态机 │ 工具调用 │ 记忆检索 │ 人工中断点                          │
├─────────────────────────────────────────────────────────────┤
│              模型抽象层 (ModelRouter)                          │
│  硬件探测 │ 云端 API │ 本地 LM Studio │ 自动降级                       │
├─────────────────────────────────────────────────────────────┤
│              数据与记忆层                                       │
│  SQLite/PostgreSQL │ ChromaDB │ Redis(队列)                     │
└─────────────────────────────────────────────────────────────┘

详细的"设计 vs 实现偏差"说明见架构实现说明。

技术栈

层级	技术
前端	Vue 3 + JavaScript + Vite + Element Plus + ECharts
后端	Python 3.11+ + FastAPI + SQLAlchemy
Agent 编排	LangGraph
向量记忆	ChromaDB
关系型数据库	SQLite(默认)/ PostgreSQL(生产)
缓存	Redis(任务队列后端,配置 `REDIS_URL` 启用,未配置降级内存)
可观测性	Prometheus + Langfuse(Grafana 已落地)
测试	pytest + locust
部署	Docker Compose

快速开始

方式一:Docker Compose 一键启动(推荐)

适合快速体验完整前后端 + Redis 起来的样貌。

git clone https://github.com/MS33834/EmpValue-AI.git
cd EmpValue-AI

# 1. 准备环境变量(用 .env.example 作为起点,开发模式可不修改)
cp backend/.env.example backend/.env

# 2. 启动所有服务
docker compose up -d --build

启动后访问:

前端: http://localhost
后端 API: http://localhost:8000
健康检查: http://localhost:8000/health
交互式 API 文档(Swagger UI): http://localhost:8000/docs

开发模式下 docker-compose.yml 已注入 JWT_SECRET_KEY 占位值,服务可直接签发 token; 部署到生产前务必通过 backend/.env 覆盖为强随机值并设 EMPVALUE_ENV=production(见部署到生产)。

方式二:本地开发(前后端分离)

适合改代码、跑测试、调试 Agent 链路。

后端:

cd backend
python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -e .                                      # 若有 setup.py;否则跳过

cp .env.example .env                                  # 编辑填入模型 API Key 等
uvicorn main:app --reload --port 8000

前端:

cd frontend
cp .env.example .env
npm install
npm run dev                                           # 默认 http://localhost:5173

前端开发服务器默认通过相对路径 /api/v1 调后端,需要把 VITE_API_BASE_URL 改为 http://localhost:8000/api/v1, 或在前端目录起一个 vite proxy 转发到 8000。详见前端开发说明。

方式三:演示模式快速体验

只想看 Agent 评估怎么跑、不想配模型 API Key?用 Mock Provider 即可端到端跑通:

cd backend
cp .env.example .env                                  # 任何配置都不用改
AUTH_DEMO_MODE=true uvicorn main:app --reload         # 开启演示模式,允许 header 伪造身份

# 另开一个终端,用 Mock Provider 跑一次完整评估
python -m eval.evaluate --mock                         # 跑通评估框架,无需任何外部 API

演示模式仅限本地开发。AUTH_DEMO_MODE=true 时任何人可通过 HTTP header 伪造身份, 部署到任何非本机环境前必须设为 false 并开启 EMPVALUE_ENV=production 守护。

配置详解

所有配置通过 backend/.env 注入,详见 backend/.env.example 的逐项注释。关键的几类:

必改项

配置项	用途	何时改
`JWT_SECRET_KEY`	JWT 签名密钥	生产部署必改为 32 字符以上的强随机值
`EMPVALUE_ENV`	设为 `production` 触发生产守护(强制关闭演示模式)	生产部署必设
`CLOUD_API_KEY` + `CLOUD_BASE_URL`	真实云端 LLM(OpenAI 兼容)	想用真实模型而非 Mock 时必填
`EMBEDDING_API_KEY` + `EMBEDDING_BASE_URL`	真实 Embedding 服务	想要语义检索而非 md5 伪向量时必填
`CORS_ORIGINS`	前端允许来源(逗号分隔)	生产必填实际域名,严禁 `*`,由 `check_prod_readiness` 强校验
`VISION_MODEL`	多模态图片识别用的视觉模型(默认 `gpt-4o-mini`)	接入 OCR 图片抽取时配置
`FIELD_ENCRYPTION_KEY`	manager_view/audit 字段 AES-GCM 加密	生产必填(留空走明文透传,仅开发可接受)

Embedding 服务

长期记忆走 ChromaDB + Embedding。未配置 EMBEDDING_API_KEY 时自动回退到 DummyEmbeddingFunction (md5 hash 伪向量),仅适合接口联调,检索结果无语义意义。生产环境必须配置真实 Embedding 服务。

# 方式一:OpenAI 兼容云端服务(OpenAI / 阿里云 / 智谱等)
EMBEDDING_API_KEY=sk-your-key
EMBEDDING_BASE_URL=https://api.openai.com/v1
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIMENSIONS=1536

# 方式二:本地 Embedding 模型(LM Studio / Ollama / Xinference)
EMBEDDING_API_KEY=local
EMBEDDING_BASE_URL=http://localhost:1234/v1
EMBEDDING_MODEL=bge-large-zh-v1.5
EMBEDDING_DIMENSIONS=1024

配置生效后系统自动启用真实 Embedding,DummyEmbeddingFunction 不再加载。切换 Embedding 模型后必须重建向量库:python -m scripts.seed_kb --clear。

模型档位

MODEL_TIER 控制评估时 LLM 走云端还是本地:

档位	场景	模型示例
`auto`	根据硬件自动推荐(默认)	-
`L0`	云端大模型	GPT-4o / DeepSeek-V3 / Qwen-Max
`L1`	边缘小模型	Qwen2.5-0.5B
`L2`	标准本地模型	Qwen2.5-7B
`L3`	本地旗舰模型	Qwen2.5-14B

未配置 CLOUD_API_KEY 与 LOCAL_BASE_URL 时,系统默认走 Mock Provider 跑通流程不依赖外部模型。

使用教程

下面按一次完整的评估闭环走一遍,从初始化到员工申诉。所有命令假设当前目录是 backend/。

1. 初始化数据库与种子数据

# 启动后端(本地或 docker compose)后,数据库表会自动建好(alembic baseline)
# 跑种子脚本插入:公司知识库、演示用户、一条样例评估
python -m scripts.seed_kb             # 公司知识库(评分标准、价值观、培训材料)
python -m scripts.seed_demo            # 演示数据(一条已审批评估,供前端联调)

# 可选:生成 5 档规模公司的合成试点数据(见 backend/data/pilot/)
python -m scripts.pilot_data_generator

2. 登录与角色切换

四角色:employee / manager / hr / admin。

演示模式(AUTH_DEMO_MODE=true):登录页有"演示账号一键填充"按钮,或直接通过 X-User-Role / X-User-Id header 伪造身份(开发联调用)
正常模式:走 /api/v1/auth/register + /api/v1/auth/login,拿到 JWT 后所有受保护接口带 Authorization: Bearer <token> 访问

前端启动后,在登录页选角色登录即可看到对应的视图(员工看自己的成长反馈,主管看团队诊断, HR 看高风险复核队列,admin 看管理后台)。

3. 发起一次评估

# 通过 API(管理员 / 系统定时任务)
curl -X POST http://localhost:8000/api/v1/evaluations \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "E1001",
    "period": "2026-W25",
    "raw_inputs": [
      {"type": "daily_report", "content": "今天完成订单中心接口重构..."},
      {"type": "task_progress", "content": "JIRA-2051 推进至联调阶段..."}
    ]
  }'

# 或直接用评估框架的 Mock 模式跑通(不调真实 LLM)
python -m eval.evaluate --mock

评估进入 LangGraph 状态机:

input_clean → multimodal_extract → llm_evaluate → parse_output → persist
                       ↑                                ↓
                   retrieve_context            human-in-the-loop interrupt

/api/v1/evaluations-interrupt 接口在 LLM 评估完成后中断,等待人工审批 (查询中断状态 GET /api/v1/evaluations-interrupt/{thread_id}/state, 恢复并提交决策 POST /api/v1/evaluations-interrupt/{thread_id}/resume)。

4. 审批与查看三视图

# 主管审批
curl -X POST http://localhost:8000/api/v1/evaluations/{id}/approve \
  -H "Authorization: Bearer <manager-token>" \
  -d '{"decision": "approve", "comment": "..."}'

# 高风险项由主管申请 HR 复核(路由到 HR 复核队列)
curl -X POST http://localhost:8000/api/v1/evaluations/{id}/request-hr-review \
  -H "Authorization: Bearer <manager-token>" \
  -d '{"comment": "..."}'

# HR 在复核队列中审批(approve/reject)
curl -X POST http://localhost:8000/api/v1/evaluations/{id}/approve \
  -H "Authorization: Bearer <hr-token>" \
  -d '{"comment": "..."}'

评估状态机:

ai_drafted → manager_review → hr_audit(高风险才进) → approved/rejected
                                  ↓ rejected
                            employee_appeal → manager_review(回到主管)

查看三视图:前端评估详情页按角色显示对应视图,或调 API:

curl http://localhost:8000/api/v1/evaluations/{id} \
  -H "Authorization: Bearer <token>"
# 响应里的 employee_view / manager_view / audit_view 字段就是三视图
# 字段级可见性由 RBAC 控制:员工 token 看不到 manager_view / audit_view

5. 员工申诉

curl -X POST http://localhost:8000/api/v1/evaluations/{id}/appeal \
  -H "Authorization: Bearer <employee-token>" \
  -d '{"content": "评估中关于测试自检的结论与事实不符..."}'

申诉会把评估状态从 approved / rejected 回退到 manager_review,并在 re_evaluate 时把历史 feedback 注入 Prompt 上下文重新评估。

6. 可观测性

Prometheus 指标:http://localhost:8000/metrics(21 项业务指标:评估/审批/反馈/LLM 调用/护栏/加密/审计等)
Grafana 看板:生产 compose 启动后 http://localhost:3000,provisioning 自动加载评估吞吐 / 耗时分布 / 审批流转 / LLM 调用 4 个 panel
Langfuse 链路追踪:配置 LANGFUSE_* 后,每次评估的 trace / span 自动上报
审计日志:所有写操作与敏感查看行为入审计表,管理后台可分页查询

生产部署 Prometheus + Grafana 的告警规则见告警规则手册。

测试

# 后端单元测试(默认跑批,自动排除性能测试)
cd backend && python -m pytest tests -q

# E2E 测试(基于 FastAPI TestClient 的 API 级联调,无需浏览器)
cd backend && python -m pytest -m e2e -q

# 显式排除 E2E,只跑单测
cd backend && python -m pytest --ignore=tests/e2e -q

# 使用 Mock Provider 跑通评估流程(无需 API Key)
cd backend && python eval/evaluate.py --mock

# Prompt 版本回归门禁
cd backend && python -m eval.evaluate --mock --compare v1.0

# 性能测试(locust,需先单独起被测服务)
cd backend && locust -f tests/perf/locustfile.py

详细测试覆盖说明见 backend/README.md。

部署到生产

生产部署使用 docker-compose.prod.yml override,在基础 compose 之上叠加:

PostgreSQL 替代 SQLite
MinIO 提供对象存储
Prometheus + Grafana 可观测性栈
NVIDIA GPU 加速本地模型推理(可选)

# 1. 准备生产环境变量(必须设置所有凭据,无默认值,缺失即报错)
cp backend/.env.example backend/.env
# 编辑 backend/.env,设置:
#   EMPVALUE_ENV=production
#   JWT_SECRET_KEY=<32 字符以上的强随机值>
#   CLOUD_API_KEY=<真实云端 LLM key>
#   EMBEDDING_API_KEY=<真实 Embedding key>
#   POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB
#   MINIO_ROOT_USER / MINIO_ROOT_PASSWORD
#   GRAFANA_ADMIN_USER / GRAFANA_ADMIN_PASSWORD

# 2. 跑生产就绪检查(无 FAIL 项才能继续)
cd backend && python scripts/check_prod_readiness.py

# 3. 启动生产栈
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build

详细的生产部署、试点运行、规模化扩展分别见:

项目目录结构

.
├── backend/              # FastAPI 后端 + LangGraph Agent
│   ├── agent/            # Agent 工作流与状态机
│   ├── api/              # REST API 路由
│   ├── auth/             # JWT 认证与 RBAC
│   ├── core/             # 配置、模型路由、数据库、护栏
│   ├── eval/             # LLM 回归评估
│   ├── memory/           # 向量记忆
│   ├── models/           # SQLAlchemy 数据模型
│   ├── prompts/          # Prompt 文件与版本快照
│   ├── schemas/          # Pydantic Schema
│   ├── scripts/          # 运维脚本(种子、巡检、合规审计等)
│   ├── services/         # 业务服务
│   ├── tests/            # 单元测试、E2E 测试、性能测试
│   └── docs/             # OpenAPI 静态快照
├── frontend/             # Vue 3 前端
│   └── src/views/        # 员工/主管/HR/管理后台页面
├── docs/                 # 项目文档
├── monitoring/           # Prometheus 配置 + 告警规则
├── grafana/              # Dashboard + provisioning
├── .github/              # CI(Actions)、Issue/PR 模板、CODEOWNERS
├── docker-compose.yml    # 开发栈编排
├── docker-compose.prod.yml # 生产栈 override
└── CHANGELOG.md          # 变更日志

文档索引

Prompt 工程规范
企业部署手册
告警规则手册
架构实现说明
架构决断记录
开发规范
试点 Runbook
规模化部署 Runbook
后端开发说明
前端开发说明
API 文档(静态快照);服务启动后访问 http://localhost:8000/docs 查看交互式 Swagger UI

Roadmap

EmpValue-AI 当前已经稳定交付核心评估闭环、审批流、可观测性、试点运行、多租户与合规审计。后续版本的工作分两条线:

核心能力深化

接入真实 LLM / Embedding 联调与档位质量对比报告(依赖 API Key,不在代码层)
Prompt 迭代与版本门禁的灰度发布流程化
团队 ROI 九宫格与员工成长路径推荐的看板增强

生态扩展

IM 集成(飞书优先,见 ADR-001)
代码仓库集成(GitLab 优先,见 ADR-002)
任务队列从内存/Redis 演进到 arq(见 ADR-003)
多模态能力补齐(云端 OCR / Whisper ASR 真实接入)

如果你有想推进的方向,欢迎到 Discussions 提议或开 Issue。

FAQ

Q: 不配 JWT_SECRET_KEY 直接 docker compose up 能用吗?

A: 开发模式可以——docker-compose.yml 已注入开发占位值 dev-only-please-change-me-32chars-or-more, 服务可正常签发 token。生产模式不行——docker-compose.prod.yml 用 ${JWT_SECRET_KEY:?...} 语法, 不设置就启动报错;即便绕过,check_prod_readiness.py 也会拦截占位值。

Q: 不配 LLM API Key 能跑吗?

A: 能。系统默认走 Mock Provider,评估流程端到端跑通,但 LLM 输出是模拟的(无真实业务价值)。真实使用必须配置 CLOUD_API_KEY 或 LOCAL_BASE_URL。

Q: Embedding 不配会怎样?

A: 自动降级到 DummyEmbeddingFunction(md5 hash 伪向量),接口能调通但检索结果无语义意义, 仅适合本地联调。生产环境必须配置真实 Embedding 服务。

Q: 评估结果能直接用于人事决策吗?

A: 不能。"AI 不做人事决策"是项目的核心硬约束:所有评估必须经主管审批,高风险项还要 HR 复核, approved / rejected 状态由人决定。Agent 只负责生成与结构化呈现,不替人下结论。

Q: 演示模式的密码 empvalue123 在生产能用吗?

A: 不能。AUTH_DEMO_MODE=true 时才会启用演示账号,生产模式(EMPVALUE_ENV=production)在 Settings 校验层直接 raise ValueError 拒绝启用演示模式。即使有人误开,demo 账号也无法在生产登录。

Q: 多租户隔离是怎么做的?

A: 数据层每个表带 tenant_id 字段,RBAC 在数据级过滤;向量库按 tenant 分 collection; 任务队列前缀带 tenant。详见架构实现说明。

Q: 怎么贡献?

A: 见 CONTRIBUTING.md。首次贡献建议从 good first issue 标签的 Issue 入手。

贡献

欢迎通过 Issue 与 PR 贡献代码或反馈问题。开始前请阅读:

贡献指南 — fork → PR 完整流程
开发规范 — 提交前自检清单
行为准则 — 社区交流规范

CI 在每次 PR 上自动跑 lint / 后端测试 / 前端构建 / Prompt 回归门禁,全绿才能合并。

行为准则

参与本项目的所有成员都需遵守 Code of Conduct。请在所有交流中保持尊重与建设性。

安全

发现安全漏洞请按 SECURITY.md 流程私密报告,不要开公开 Issue。

支持

遇到问题先看获取帮助对号入座:Bug 开 Issue、使用疑问进 Discussions、安全漏洞走私密报告。

Mirror

This repository is primarily hosted on GitHub. A read-only mirror is available on GitCode. Please open Issues and PRs on GitHub.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github		.github
backend		backend
docs		docs
frontend		frontend
grafana		grafana
monitoring		monitoring
tests		tests
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
VERSION		VERSION
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

EmpValue-AI

目录

为什么这么设计

系统架构

技术栈

快速开始

方式一:Docker Compose 一键启动(推荐)

方式二:本地开发(前后端分离)

方式三:演示模式快速体验

配置详解

必改项

Embedding 服务

模型档位

使用教程

1. 初始化数据库与种子数据

2. 登录与角色切换

3. 发起一次评估

4. 审批与查看三视图

5. 员工申诉

6. 可观测性

测试

部署到生产

项目目录结构

文档索引

Roadmap

FAQ

贡献

行为准则

安全

支持

Mirror

许可证

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages