# BI Recall Eval Script

用于评估“根据用户问题召回仪表板/数据集”的三路召回表现。

## 输入

1. `id_map.parquet`

必需字段：

- `card_id`
- `card_name`
- `dashboard_id`
- `dashboard_name`
- `dataset_id`
- `dataset_name`
- `branch_code`

2. `questions.txt`

推荐格式每行一条：

```txt
123456\t本月深圳分行存款趋势
234567\t零售客户AUM周报看板
```

脚本也兼容 `card_id,question`、`card_id|question` 和 `card_id question`。

## 召回逻辑

1. 第一路：从全量仪表板中随机采样 `500` 个，以 `80%` 概率强制放入正确卡片所在仪表板。
2. 第二路：调用召回接口，`recall_type=dashboard`。
3. 第三路：调用召回接口，`recall_type=dataset`。

命中规则：

- 第一路、第二路：只要召回到正确卡片关联的任一 `dashboard_id` 即视为命中。
- 第三路：只要召回到正确卡片关联的任一 `dataset_id` 即视为命中。
- 总召回：三路结果取并集后，只要任一路命中即视为命中。

## 安装依赖

```bash
python3 -m pip install -r requirements.txt
```

## 运行

```bash
python3 recall_eval.py \
  --questions-txt ./questions.txt \
  --id-map-parquet ./id_map.parquet \
  --api-url http://your-recall-api/recall \
  --output-dir ./output
```

## 输出

- `output/recall_summary.json`：汇总指标
- `output/recall_details.csv`：逐题明细，包含第二路/第三路召回结果和错误信息

## 接口约定

脚本默认使用 `POST` JSON：

```json
{
  "question": "本月深圳分行存款趋势",
  "recall_type": "dashboard"
}
```

返回支持以下常见结构之一：

- 顶层数组
- `{"data": [...]}`
- `{"items": [...]}`
- `{"results": [...]}`

每条记录至少包含一个可识别的 ID 字段，例如：

- `dashboard_id`
- `dataset_id`
- `id`