PsyMtricAI

PsyMtricAI 是一个基于 AI 的心理学量表自动化评估与分析系统。它能够模拟 AI 被试对心理学量表进行作答，并基于生成的数据进行专业的信度与效度分析，帮助研究人员快速评估量表质量。

✨ 核心功能

📄 量表解析: 支持 .txt、.docx、.pdf、.md 格式的量表文件上传与自动解析
🤖 AI 被试模拟: 集成通义千问大模型 API，可配置不同模型和人格特质进行稳定作答
📊 专业统计分析:
- 信度分析: Cronbach's Alpha 系数、分半信度
- 效度分析: KMO 检验、Bartlett 球形度检验、探索性因子分析 (EFA/PCA)
- 项目分析: 题目区分度、难度及相关性分析
🎯 问卷优化: 基于信效度分析结果，AI 自动优化问卷题目，提升量表质量
📈 可视化报告: 前端实时展示分析进度、虚拟被试人设及详细的评估摘要
⚡ 实时进度: 分析过程中实时显示进度和状态
🎨 直观界面: 美观的用户界面，操作简单易用

📁 项目结构

PsyMtricAI/
├── backend/                    # Flask 后端服务
│   ├── app/                    # 核心业务逻辑
│   │   ├── utils/              # 工具模块
│   │   │   ├── analyzer.py     # 统计分析
│   │   │   ├── parser.py       # 文件解析
│   │   │   └── qwen_respondent.py  # Qwen API 被试生成
│   │   ├── routes.py           # API 路由
│   │   └── services.py        # 业务逻辑
│   ├── uploads/                # 文件上传目录
│   ├── .env.example           # 环境变量示例
│   ├── config.py              # 配置文件
│   ├── requirements.txt       # Python 依赖
│   └── run.py                # 启动入口
├── frontend/                   # React 前端界面
│   ├── public/               # 静态资源
│   └── src/
│       ├── components/        # React 组件
│       ├── App.js           # 主应用
│       └── config.js        # 前端配置
├── .gitignore
├── LICENSE                    # 许可证文件
└── README.md

🚀 快速开始

环境要求

Python: 3.8+
Node.js: 14+
通义千问 API Key: 获取地址
浏览器: Chrome, Firefox, Safari, Edge (最新版本)

后端启动

# 1. 进入后端目录
cd backend

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

# 3. 配置环境变量
# Windows
copy .env.example .env
# Linux/Mac
cp .env.example .env

# 4. 编辑 .env 文件，填写 API Key
# 打开 .env 文件，将 DASHSCOPE_API_KEY 替换为您的真实 API Key

# 5. 启动服务
python run.py

后端服务将在 http://localhost:5000 启动。

前端启动

# 1. 进入前端目录
cd frontend

# 2. 安装依赖
npm install

# 3. 启动开发服务器
npm start

前端页面将自动在浏览器打开 (通常为 http://localhost:3000)。

📋 示例量表

项目提供了一个专业的心理学量表示例，位于项目根目录下，供测试和学习使用：

生活满意度量表 (SWLS)

文件: example_scale.txt

量表名称: 生活满意度量表 (Satisfaction with Life Scale, SWLS)
编制者: Diener, Emmons, Larsen & Griffin (1985)
题目数量: 5题
评分方式: 7点李克特量表（1-7分）
计分方法: 5个题目得分相加，总分范围5-35分
解释: 得分越高表示生活满意度越高
信度: Cronbach's α 通常在 0.79-0.89 之间
效度: 具有良好的结构效度和效标效度
特点: 简单易用，世界最广泛使用的生活满意度量表
适用场景: 生活质量评估、幸福感研究、跨文化比较

使用示例量表

上传测试: 在前端页面上传 example_scale.txt 文件
等待分析: 系统会自动生成 AI 被试并分析量表的信效度
查看结果: 分析完成后，查看信效度评估报告和 AI 被试数据预览
调整阈值: 根据分析结果，在页面上调整信度和效度阈值
决定优化: 如果问卷未达到阈值，可以选择让 AI 优化问卷

注意事项

示例量表仅供学习和测试使用
在实际研究中，请使用经过信效度验证的标准化量表
不同的量表适用于不同的研究目的和人群
使用量表时请遵守相关的伦理规范和版权要求

⚙️ 配置说明

后端配置 (backend/.env)

创建 .env 文件（复制 .env.example），然后根据需要修改以下配置：

1. 通义千问 API Key 配置

# 通义千问 API Key (必填)
# 获取方式：访问 https://dashscope.console.aliyun.com/
# 登录后进入 API-KEY 管理页面创建新的 API Key
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

如何更改:

访问阿里云百炼平台
登录或注册账号
进入 "API-KEY 管理" 页面
点击 "创建新的 API-KEY"
复制生成的 API Key
在 backend/.env 文件中替换 DASHSCOPE_API_KEY 的值
重启后端服务使配置生效

注意事项:

API Key 格式通常为 sk- 开头的字符串
请妥善保管 API Key，不要泄露
如果 API Key 失效，需要重新生成

2. Qwen 模型名称配置

# Qwen 模型名称 (可选，默认: qwen2-vl-7b-instruct)
# 可选值: qwen-flash, qwen-flash-character, qwen-plus, qwen-max
QWEN_MODEL=qwen-flash-character

如何更改:

在 backend/.env 文件中找到 QWEN_MODEL 配置项
根据需求选择合适的模型：
- qwen-flash: 快速响应，适合实时交互
- qwen-flash-character: 平衡性能和质量
- qwen-plus: 更强的模型，适合复杂任务
- qwen-max: 最强模型，适合高质量需求
修改模型名称
重启后端服务使配置生效

模型对比:

模型	速度	质量	适用场景
qwen2-vl-7b-instruct	⚡⚡	⭐⭐⭐	默认选择、视觉理解、性价比高
qwen-flash	⚡⚡⚡	⭐⭐	快速测试、实时交互
qwen-flash-character	⚡⚡	⭐⭐⭐	平衡方案、通用场景
qwen-plus	⚡	⭐⭐⭐⭐	复杂任务、高质量需求
qwen-max	⚡	⭐⭐⭐⭐⭐	最高质量、关键任务

3. 问卷优化阈值配置

# 信度阈值 (Cronbach's Alpha): 默认0.7
# 当问卷信度低于此值时，建议进行AI优化
RELIABILITY_THRESHOLD=0.7

# 效度阈值 (KMO): 默认0.6
# 当问卷效度低于此值时，建议进行AI优化
VALIDITY_THRESHOLD=0.6

如何更改信度阈值:

在 backend/.env 文件中找到 RELIABILITY_THRESHOLD 配置项
根据需求调整阈值：
- 0.9: 非常严格（学术研究）
- 0.8: 严格（正式量表）
- 0.7: 标准（默认值，推荐）
- 0.6: 宽松（测试阶段）
- 0.5: 非常宽松（探索性研究）
修改阈值数值
重启后端服务使配置生效

信度解释:

≥ 0.9: 非常好
0.8-0.9: 好
0.7-0.8: 可接受
0.6-0.7: 勉强可接受
< 0.6: 不可接受

如何更改效度阈值:

在 backend/.env 文件中找到 VALIDITY_THRESHOLD 配置项
根据需求调整阈值：
- 0.8: 非常严格（学术研究）
- 0.7: 严格（正式量表）
- 0.6: 标准（默认值，推荐）
- 0.5: 宽松（测试阶段）
- 0.4: 非常宽松（探索性研究）
修改阈值数值
重启后端服务使配置生效

效度解释:

≥ 0.9: 非常适合因子分析
0.8-0.9: 适合
0.7-0.8: 勉强适合
0.6-0.7: 勉强可接受
< 0.6: 不适合因子分析

前端阈值设置（推荐方式）

前端页面提供了直观的阈值设置界面，用户可以在分析完成后直接在页面上调整信度和效度阈值，无需修改配置文件：

功能特点:

🎨 可视化界面: 美观的渐变背景和卡片式布局
🔢 数字输入: 支持精确的数值输入
🎯 快速预设: 提供四种常用预设（学术研究、正式量表、测试阶段、探索性研究）
📊 范围限制: 信度阈值范围 0.5-0.95，效度阈值范围 0.4-0.9
⚡ 实时生效: 设置后立即生效，无需重启服务
🔄 动态更新: 修改阈值后，优化按钮和提示会实时更新

显示时机:

阈值设置模块在分析完成后才显示
用户可以先查看分析结果，再根据实际情况调整阈值
这样可以避免在未看到结果前就设置不合理的阈值

使用方法:

上传量表文件并等待分析完成
查看分析结果（信效度指标、AI 被试数据预览等）
在"⚙️ 问卷优化阈值设置"区域调整阈值
- 方式1：直接输入数值
- 方式2：点击快速预设按钮
系统会根据新的阈值自动更新优化按钮和提示
如果问卷未达到阈值，点击"让AI优化问卷"按钮进行优化

快速预设说明:

学术研究: 信度 ≥ 0.8，效度 ≥ 0.7（最严格）
- 适用于学术研究、论文发表等需要高质量的场景
正式量表: 信度 ≥ 0.7，效度 ≥ 0.6（默认值，推荐）
- 适用于正式的问卷调查、量表开发等标准场景
测试阶段: 信度 ≥ 0.6，效度 ≥ 0.5（宽松）
- 适用于量表测试、初步验证等场景
探索性研究: 信度 ≥ 0.5，效度 ≥ 0.4（最宽松）
- 适用于探索性研究、初步调查等场景

动态交互说明:

修改阈值后，系统会立即判断问卷是否达到新阈值
如果未达到阈值：显示"问卷优化"按钮
如果达到阈值：显示"问卷已达到阈值提示"
用户可以反复调整阈值，直到找到合适的标准

前端配置文件 (frontend/src/config.js)

前端配置文件用于设置默认阈值：

export const config = {
  // 问卷优化阈值配置
  reliabilityThreshold: 0.7,  // 信度阈值
  validityThreshold: 0.6       // 效度阈值
};

说明:

配置文件中的值是默认值，页面加载时会使用这些值
用户可以在页面上修改这些值，修改后的值会覆盖默认值
如果需要永久更改默认值，可以修改此文件

配置生效说明

前端页面设置（推荐）:

✅ 无需重启服务
✅ 立即生效
✅ 支持快速预设
✅ 界面友好，操作简单

前端配置文件:

修改 config.js 文件后需要重启前端服务
重启命令：npm start
配置在服务启动时加载
仅修改默认值，用户仍可在页面上覆盖

后端配置文件:

修改 .env 文件后需要重启后端服务
重启命令：python run.py
配置在服务启动时加载
当前端未提供阈值时使用此配置作为默认值

📖 使用说明

上传量表: 在前端页面上传心理学量表文件（支持 txt/docx/pdf/md）
自动分析: 系统自动执行：解析题目 → 生成 AI 被试 → 运行统计分析
查看报告: 等待进度条完成，查看信效度评估报告和 AI 被试数据预览
调整阈值: 根据分析结果，在页面上调整信度和效度阈值（分析完成后才显示）
问卷优化: 如果问卷未达到质量标准，可选择让 AI 优化问卷
下载结果: 优化完成后可下载优化后的问卷文件

🎯 问卷优化功能

系统会根据问卷的信效度分析结果自动判断是否需要优化：

达到阈值: 信度 ≥ 0.7 且效度 ≥ 0.6，显示绿色提示，问卷可直接使用
未达到阈值: 显示"让AI优化问卷"按钮，可选择进行 AI 优化

优化过程:

AI 分析原问卷的问题
生成优化后的题目
生成虚拟被试测试优化效果
评估优化后的信效度
循环优化直到达到阈值或达到最大轮数
生成最终版本的问卷文件供下载

🔌 API 接口

根路径

GET /

返回 API 服务信息和可用端点。

上传量表

POST /api/upload_scale

上传问卷量表文件，开始分析流程。

请求参数:

file: 量表文件（支持 txt/docx/pdf/md）
file_format: 文件格式（例如：txt, docx, pdf, md）
target_description: 目标群体描述（可选）
reliability_threshold: 信度阈值（可选）
validity_threshold: 效度阈值（可选）

响应:

{
  "status": "success",
  "progress_id": "unique-id",
  "message": "分析任务已启动"
}

查询进度

GET /api/progress/{progress_id}

查询分析任务的进度和状态。

响应:

{
  "status": "processing",
  "overall_progress": 45,
  "message": "正在生成 AI 被试...",
  "stages": [
    {
      "stage": "解析题目",
      "progress": 100,
      "message": "文件解析完成"
    },
    {
      "stage": "AI被试生成",
      "progress": 50,
      "message": "正在生成被试 25/50"
    },
    {
      "stage": "统计分析",
      "progress": 0,
      "message": "等待开始"
    }
  ],
  "result": null
}

停止任务

POST /api/stop/{progress_id}

停止正在运行的分析任务。

响应:

{
  "status": "success",
  "message": "任务已停止"
}

优化问卷

POST /api/optimize_scale

优化问卷量表，基于之前的分析结果。

请求参数:

progress_id: 原始分析任务的进度 ID

响应:

{
  "status": "success",
  "progress_id": "unique-id",
  "message": "优化任务已启动"
}

🛠️ 技术栈

后端

Flask: Web 框架
NumPy: 数值计算
scikit-learn: 机器学习和统计分析
scipy: 科学计算
python-docx: Word 文档处理
PyPDF2: PDF 文档处理

前端

React: UI 框架
Create React App: 项目脚手架

AI 服务

通义千问 API: 阿里云大语言模型

📊 支持的文件格式

格式	扩展名	支持情况
文本文件	.txt	✅ 完全支持
Word 文档	.docx	✅ 完全支持
PDF 文档	.pdf	✅ 完全支持
Markdown	.md	✅ 完全支持

❓ 常见问题

1. 如何获取通义千问 API Key？

访问阿里云百炼平台，注册账号后即可获取 API Key。

2. 分析需要多长时间？

分析时间取决于题目数量和被试数量，通常在 1-5 分钟之间。

3. 支持哪些 Qwen 模型？

支持 qwen2-vl-7b-instruct、qwen-flash、qwen-flash-character、qwen-plus、qwen-max 等模型。

4. 如何调整问卷优化阈值？

在前端页面分析完成后，在"⚙️ 问卷优化阈值设置"区域调整阈值，或在 backend/.env 文件中修改配置。

5. 上传文件大小有限制吗？

最大支持 16MB 的文件。

6. 配置修改后如何生效？

后端配置：修改 .env 文件后需要重启 python run.py
前端配置：修改 config.js 文件后需要重启 npm start

7. 信度和效度阈值应该设置多少？

学术研究: 信度 ≥ 0.8，效度 ≥ 0.7
正式量表: 信度 ≥ 0.7，效度 ≥ 0.6（默认值）
测试阶段: 信度 ≥ 0.6，效度 ≥ 0.5
探索性研究: 信度 ≥ 0.5，效度 ≥ 0.4

8. 如何选择合适的 Qwen 模型？

快速测试: 使用 qwen-flash
平衡方案: 使用 qwen-flash-character
高质量需求: 使用 qwen-plus
最高质量: 使用 qwen-max

🛡️ 故障排查

常见错误及解决方案

1. API Key 错误

错误信息: "API Key 无效或已过期" 解决方案:

检查 .env 文件中的 DASHSCOPE_API_KEY 是否正确
登录阿里云百炼平台，确认 API Key 是否有效
如过期，重新生成 API Key

2. 模型错误

错误信息: "模型不存在或无权限访问" 解决方案:

确认选择的模型名称是否正确
检查您的阿里云账号是否有权限使用该模型
尝试使用其他可用模型

3. 文件解析错误

错误信息: "文件解析失败" 解决方案:

确保文件格式正确（支持 txt/docx/pdf/md）
检查文件内容是否符合量表格式
尝试使用示例量表测试

4. 网络错误

错误信息: "网络连接失败" 解决方案:

检查网络连接
确认阿里云 API 服务是否正常
尝试重启服务

📝 开发说明

后端开发

cd backend
pip install -r requirements.txt
python run.py

前端开发

cd frontend
npm install
npm start

代码规范

后端遵循 PEP 8 规范
前端遵循 ESLint 规范
提交代码前请确保通过 lint 检查

项目结构说明

后端核心模块

app/utils/parser.py: 负责解析不同格式的量表文件
app/utils/qwen_respondent.py: 负责调用 Qwen API 生成 AI 被试
app/utils/analyzer.py: 负责统计分析和信效度计算
app/services.py: 核心业务逻辑，协调各个模块
app/routes.py: API 路由和请求处理

前端核心组件

src/components/FileUpload.jsx: 文件上传组件
src/components/ProgressDisplay.jsx: 进度显示组件
src/components/ScaleAnalysis.jsx: 主分析组件
src/components/ChatDialog.jsx: AI 被试对话展示
src/components/ThresholdSettings.jsx: 阈值设置组件
src/components/SuccessResult.jsx: 分析结果展示

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

通义千问 API: 提供强大的 AI 能力支持
Flask: 轻量级 Web 框架
React: 现代化前端框架
scikit-learn: 机器学习和统计分析库
所有贡献者: 感谢您的支持和贡献

Powered by X-Lab

让心理学研究更智能、更高效

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
backend		backend
frontend		frontend
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
example_scale.txt		example_scale.txt
生活满意度量表 (Satisfaction with Life Scale, SWLS).md		生活满意度量表 (Satisfaction with Life Scale, SWLS).md

Folders and files

Latest commit

History

Repository files navigation

PsyMtricAI

✨ 核心功能

📁 项目结构

🚀 快速开始

环境要求

后端启动

前端启动

📋 示例量表

生活满意度量表 (SWLS)

使用示例量表

注意事项

⚙️ 配置说明

后端配置 (backend/.env)

1. 通义千问 API Key 配置

2. Qwen 模型名称配置

3. 问卷优化阈值配置

前端阈值设置（推荐方式）

前端配置文件 (frontend/src/config.js)

配置生效说明

📖 使用说明

🎯 问卷优化功能

🔌 API 接口

根路径

上传量表

查询进度

停止任务

优化问卷

🛠️ 技术栈

后端

前端

AI 服务

📊 支持的文件格式

❓ 常见问题

1. 如何获取通义千问 API Key？

2. 分析需要多长时间？

3. 支持哪些 Qwen 模型？

4. 如何调整问卷优化阈值？

5. 上传文件大小有限制吗？

6. 配置修改后如何生效？

7. 信度和效度阈值应该设置多少？

8. 如何选择合适的 Qwen 模型？

🛡️ 故障排查

常见错误及解决方案

1. API Key 错误

2. 模型错误

3. 文件解析错误

4. 网络错误

📝 开发说明

后端开发

前端开发

代码规范

项目结构说明

后端核心模块

前端核心组件

📄 许可证

🙏 致谢

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages