职业心理特征标定系统 (Career Psychology Profiling System)

基于 LangGraph 构建的多智能体（Multi-Agent）人工智能系统。该系统能够将中文职业描述精准匹配至美国 O*NET 职业数据库，并自动评估该职业的 RIASEC（霍兰德职业兴趣） 和 Big5 OCEAN（大五人格） 心理特征。

核心技术特性：

• 混合检索：向量库检索 (ChromaDB) + LLM 重排序与匹配
• 多专家模拟：通过大模型模拟不同视角的专家（职业心理学家、HR、生涯规划师）进行独立打分
• 数据锚定：结合 O*NET 及真实研究数据（逆距离权重聚合）防止大模型幻觉
• 动态仲裁：基于标准差动态触发法官智能体 (Agent 4) 解决专家分歧
• 工作流编排：使用 LangGraph 实现稳定可靠的 7 节点处理流

---

🏗 系统架构 (7节点工作流)

系统的核心基于 LangGraph 的图状态流转，定义于 src/workflow.py：

1. 节点 1 (检索与重排序): 使用 ChromaDB 获取 Top 50 语义匹配，之后重排序至 Top 20。
2. 节点 2 (Agent 0 匹配): 职业分类专家智能体从中选出 Top 5 匹配职业，并传递向量相似度指标。
3. 节点 3 (数据丰富): 读取 O*NET 和大五人格参考对照表，使用逆距离权重（IDW）计算出客观锚定分数。
4. 节点 4 (并行打分): 3 个不同温度（Temperature）的模拟专家进行独立打分（异步并行）。
5. 节点 5 (统计校验): 计算打分方差和置信度，若标准差超过阈值则触发仲裁。
6. 节点 6 (仲裁 - 动态触发): 仲裁法官智能体解决分歧，统一最终分数。
7. 节点 7 (报告生成): 组装所有的评分、置信度及推理过程，输出结构化报告。

---

📂 项目结构

.
├── main.py                  # 单条职业测试入口程序
├── batch_test.py            # 批量读取 Excel 进行并行处理的脚本
├── build_index.py           # 向量数据库构建脚本 (ChromaDB)
├── config.py                # Pydantic 强类型配置管理
├── requirements.txt         # 核心依赖清单
├── .env                     # 环境变量配置文件（如 API Keys）
│
├── src/                     # 核心源码目录
│   ├── workflow.py          # LangGraph 状态机及节点路由逻辑
│   ├── types.py             # 全局 TypedDict 及数据结构定义
│   ├── embedding.py         # SiliconFlow Embedding & Reranker 封装
│   ├── lookup_tables.py     # 数据表查表及权重计算逻辑
│   ├── agents/              # 智能体逻辑实现 (matcher, scorer, arbitrator)
│   ├── exceptions.py        # 自定义异常类型与恢复策略
│   ├── dynamic_threshold.py # 动态阈值管理器
│   ├── prompt_manager.py    # 提示词管理器
│   └── logger.py            # 日志管理与持久化记录
│
├── prompts/                 # 智能体系统提示词模版文件
├── data/                    # 本地依赖数据源 (O*NET Excel 等)
├── chroma_db/               # 自动生成的本地向量数据库 (不提交至 Git)
└── logs/                    # 每次运行生成的结构化日志及中间结果 (不提交至 Git)

---

🚀 快速开始

1. 环境准备

要求 Python 3.10+，推荐使用虚拟环境：

# 创建并激活虚拟环境
python -m venv venv
# Windows
.\venv\Scripts\activate
# Linux / macOS
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

2. 配置环境变量

在项目根目录创建 .env 文件，填入你的 SiliconFlow API 密钥（系统依赖 DeepSeek / Qwen 接口）：

SILICONFLOW_API_KEY=sk-your_api_key_here
# 可选配置
LOG_LEVEL=INFO
DEBUG=false

3. 构建向量索引 (首次运行必做)

系统需要读取 data/ 下的数据文件并构建本地 ChromaDB：

python build_index.py

此过程会调用 Embedding API，视数据量可能需要几分钟。

4. 运行系统

单条测试：

# 使用默认用例
python main.py

# 测试指定职业
python main.py --test "数据分析师"

# 提供详细职业定义提升准确率
python main.py --test "UI设计师" --def "负责软件界面的美术设计、创意工作和制作工作"

批量测试：

# 处理 Excel 中的职业数据 (多进程并行加速)
python batch_test.py --input data/职业大典_提取结果.xlsx --output output/ --parallel --workers 4

---

📊 输出结果格式

每次测试的结果会打印在控制台，并在 logs/YYYYMMDD_HHMMSS/ 目录下保存所有 7 个节点的中间状态 JSON，最终结果格式参考：

{
  "occupation": "数据分析师",
  "riasec": {
    "R": 2.1, "I": 6.8, "A": 3.0, "S": 3.5, "E": 4.2, "C": 5.8
  },
  "ocean": {
    "O": 4.1, "C": 4.5, "E": 3.2, "A": 3.0, "N": 2.5
  },
  "confidence": {
    "overall": {
      "riasec": "high",
      "ocean": "medium"
    }
  },
  "arbitration_triggered": false
}

---

🛠 开发与调试

• 强制类型检查：添加/修改配置请在 config.py 中的 Settings 类进行，系统中统一使用 from config import get_settings 读取。
• 缓存清理：若遇到重复运行无反应，系统默认有 24 小时工作流缓存，可手动删除 .cache 文件夹。
• 日志排查：节点如果发生异常，会生成标准的 error_response 对象并进入 Fallback 流程，检查对应 logs/ 运行目录下的 JSON 即可复原整个思考过程。
• Windows乱码问题：代码底层已使用 _safe_print 处理 gbk/utf-8 终端显示冲突。