COMPUTE_METRICS_README.md

# 计算级联指标使用说明

本脚本用于计算信息级联数据的情感得分、情感deviation、contextual deviation和perplexity。

## 功能说明

脚本 `compute_cascade_metrics.py` 会处理以下两个JSON文件：
- `information_cascade.json`: 包含完整级联数据（原帖、评论、转发）
- `information_cascade_original_posts.json`: 包含原帖数据（可选）

计算以下指标：
1. **情感得分 (Sentiment Score)**: 文本的情感倾向得分
2. **情感偏差 (Sentiment Deviation)**: 相对于原帖的情感偏差
3. **语境偏差 (Contextual Deviation)**: 相对于原帖的语义偏差
4. **困惑度 (Perplexity)**: 文本的语言模型困惑度

## 安装依赖

在云电脑上安装必要的依赖：

```bash
pip install torch transformers numpy tqdm
```

如果需要使用GPU：
```bash
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
```

## 使用方法

### 基本用法（使用默认模型）

```bash
python compute_cascade_metrics.py \
    --input_cascade information_cascade.json \
    --output output_with_metrics.json \
    --batch_size 32
```

### 完整用法（指定所有模型）

```bash
python compute_cascade_metrics.py \
    --input_cascade information_cascade.json \
    --input_original information_cascade_original_posts.json \
    --output output_with_metrics.json \
    --bert_model bert-base-chinese \
    --sentiment_model <情感分析模型路径> \
    --perplexity_model <语言模型路径> \
    --batch_size 32 \
    --max_length 512 \
    --device cuda
```

### 参数说明

- `--input_cascade`: **必需**，输入级联JSON文件路径
- `--input_original`: 可选，输入原帖JSON文件路径
- `--output`: **必需**，输出JSON文件路径
- `--bert_model`: BERT模型名称或路径（默认: `bert-base-chinese`）
- `--sentiment_model`: 情感分析模型路径（可选，不提供则使用简化方法）
- `--perplexity_model`: 语言模型路径（可选，不提供则使用简化方法）
- `--batch_size`: 批处理大小（默认: 32）
- `--max_length`: 最大序列长度（默认: 512）
- `--device`: 计算设备，`cuda` 或 `cpu`（默认: 自动选择）
- `--max_cascades`: 最大处理级联数量（用于测试，默认: 处理所有）

## 输出格式

处理后的JSON文件会在每个节点中添加以下字段：

### 原帖 (`post_info`)
```json
{
  "post_info": {
    "content": "原帖内容",
    "embedding": [0.1, 0.2, ...],        // BERT语义向量 (768维)
    "sentiment_score": 0.7,              // 情感得分
    "perplexity": 15.3                   // 困惑度
  }
}
```

### 评论 (`comment_tree`)
```json
{
  "comment_tree": {
    "comment_id": {
      "content": "评论内容",
      "embedding": [0.1, 0.2, ...],
      "sentiment_score": 0.6,
      "perplexity": 12.5,
      "contextual_deviation": 0.25,      // 语境偏差
      "sentiment_deviation": 0.1         // 情感偏差
    }
  }
}
```

### 转发 (`repost_chain`)
```json
{
  "repost_chain": [
    {
      "forward_text": "转发内容",
      "comment_content": "评论内容",
      "embedding": [0.1, 0.2, ...],
      "sentiment_score": 0.5,
      "perplexity": 18.2,
      "contextual_deviation": 0.35,
      "sentiment_deviation": 0.2
    }
  ]
}
```

## 模型选择建议

### BERT模型
- 中文文本：`bert-base-chinese`
- 英文文本：`bert-base-uncased`
- 自定义模型：提供本地路径

### 情感分析模型
- 中文：可以使用 `uer/roberta-base-finetuned-chinanews-chinese` 或其他中文情感分析模型
- 英文：可以使用 `nlptown/bert-base-multilingual-uncased-sentiment` 等
- 如果不提供，脚本会使用基于关键词的简化方法

### 困惑度模型
- 中文：可以使用 `gpt2-chinese` 或其他中文语言模型
- 英文：可以使用 `gpt2` 等
- 如果不提供，脚本会使用基于词汇多样性的简化方法

## 注意事项

1. **大文件处理**: 如果JSON文件很大，处理时间可能较长。建议：
   - 使用GPU加速（`--device cuda`）
   - 调整批处理大小（`--batch_size`）
   - 先用 `--max_cascades` 测试少量数据

2. **内存使用**: 
   - BERT模型需要较多内存
   - 如果内存不足，减小 `--batch_size`

3. **简化方法**: 
   - 如果不提供情感分析模型或困惑度模型，脚本会使用简化的启发式方法
   - 简化方法的结果可能不如专业模型准确，但计算速度快

4. **数据格式**: 
   - 确保输入的JSON文件格式正确
   - JSON文件应包含 `cascades` 字段，每个级联包含 `post_info`、`comment_tree`、`repost_chain`

## 示例

### 示例1：使用默认设置处理数据
```bash
python compute_cascade_metrics.py \
    --input_cascade /path/to/information_cascade.json \
    --output /path/to/output.json
```

### 示例2：使用GPU和自定义模型
```bash
python compute_cascade_metrics.py \
    --input_cascade /path/to/information_cascade.json \
    --output /path/to/output.json \
    --bert_model bert-base-chinese \
    --sentiment_model /path/to/sentiment_model \
    --device cuda \
    --batch_size 64
```

### 示例3：测试模式（只处理前10个级联）
```bash
python compute_cascade_metrics.py \
    --input_cascade /path/to/information_cascade.json \
    --output /path/to/output.json \
    --max_cascades 10
```

## 故障排除

1. **CUDA内存不足**: 减小 `--batch_size` 或使用 `--device cpu`
2. **模型下载失败**: 检查网络连接，或手动下载模型到本地后指定路径
3. **JSON格式错误**: 检查输入JSON文件格式是否正确
4. **处理速度慢**: 使用GPU（`--device cuda`）和增大批处理大小

## 与EasyTPP集成

处理后的JSON文件可以用于EasyTPP框架的训练。参考 `examples/train_robot_thp_with_features.py` 了解如何使用这些特征。