# retrieval

**Repository Path**: taj5/retrieval

## Basic Information

- **Project Name**: retrieval
- **Description**: 检索算法
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-20
- **Last Updated**: 2026-01-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 摄像头智能匹配系统

## 项目简介
摄像头智能匹配系统是一款面向工业场景的摄像头名称检索工具，能够根据用户输入的自然语言指令（如"打开105机头摄像头"），智能提取核心关键词并与摄像头名称库进行匹配，返回精准度排序的匹配结果，并提供行业标准的检索指标分析，适用于工业监控、设备管理等场景。

## 核心特性
- 🎯 **智能匹配算法**：基于数字优先级+关键词匹配+包含关系的多维度评分机制，匹配精准度高
- 📊 **完整指标体系**：提供命中率、精准匹配率、平均得分等7项核心检索指标，量化匹配效果
- ⚙️ **可配置化设计**：所有阈值、规则、文件路径集中配置，支持一键修改
- 🛡️ **鲁棒性保障**：编码容错、空值过滤、分数边界限制，保证程序稳定运行
- 🧪 **双测试模式**：支持批量测试（自动化验证）和交互式测试（手动验证）
- ⚡ **性能优化**：正则预编译、结果数量限制、高效去重，提升检索效率

## 目录结构
```
├── action_words.txt       # 无意义操作词配置文件（如：打开、查看、调取）
├── camera_list.txt        # 摄像头名称库文件
├── test_cases.txt         # 测试用例文件
├── retrival.py            # 核心代码文件
└── README.md              # 项目说明文档
```

## 环境要求
- Python 3.6+
- 无第三方依赖（仅使用Python标准库）

## 快速开始

### 1. 配置文件准备
#### (1) 操作词文件 `action_words.txt`
每行一个无意义操作词，用于预处理时移除：
```
打开
开启
调取
查看
显示
找
查
开
调
看
```

#### (2) 摄像头名称库 `camera_list.txt`
每行一个摄像头名称，支持数字+文本组合：
```
105机头摄像头
3216弧形筛摄像头
208皮带机摄像头
机头全景摄像头
弧形筛特写摄像头
```

#### (3) 测试用例文件 `test_cases.txt`
格式：`输入指令,期望关键词1,期望关键词2,...`（注释行以#开头）：
```
# 测试用例示例
打开105机头,105机头摄像头
调取3216弧形筛,3216弧形筛摄像头
查看机头摄像头,机头全景摄像头,105机头摄像头
```

### 2. 运行程序
```bash
python retrival.py
```

程序会自动执行以下操作：
1. 加载配置文件（操作词、摄像头列表、测试用例）
2. 执行批量测试并输出汇总报告
3. （可选）启动交互式测试模式（取消注释`run_interactive_test()`）

### 3. 交互式测试
取消代码末尾`run_interactive_test()`的注释，运行后可手动输入指令测试：
```
===== 交互式测试模式 (输入'quit/exit/退出'结束) =====

请输入匹配指令: 打开105机头

🎯 匹配结果 (共1条，阈值50分)：
  1. 105机头摄像头 (匹配分: 100分)

📊 本次匹配检索核心指标：
  检索输入: 打开105机头
  摄像头库总量: 5
  命中结果数: 1
  命中率(Recall_Rate): 20.0%
  平均匹配得分(AVG_Score): 100.0
  最高匹配得分(MAX_Score): 100
  最低匹配得分(MIN_Score): 100
  精准匹配率(Precision_Rate): 100.0%
  有效匹配占比(Valid_Rate): 100.0%
  空匹配标识: False
```

## 核心配置说明
在代码头部的统一配置区可调整以下参数：
```python
MATCH_SCORE_THRESHOLD = 50    # 匹配得分阈值，低于此分数的结果会被过滤
MAX_RETURN_NUM = 10           # 单次匹配最多返回结果数，防止数据量过大
ACTION_WORDS_FILE = "action_words.txt"   # 无意义操作词文件路径
CAMERA_LIST_FILE = "camera_list.txt"     # 摄像头名称库文件路径
TEST_CASES_FILE = "test_cases.txt"       # 测试用例文件路径
```

## 匹配算法规则（0-100分制）
匹配分数计算采用优先级权重机制，保证工业场景下的匹配精准度：
1. **最高优先级（100分）**：完全精准匹配（输入与摄像头名称完全一致）
2. **核心匹配（40-50分）**：数字部分匹配（工业编号为核心），数字开头额外加分
3. **关键词匹配（15-35分）**：文本关键词匹配，最多2个关键词，主体关键词额外加分
4. **包含关系（15-20分）**：双向包含关系匹配（输入包含名称/名称包含输入）
5. **惩罚项**：短输入（<3字符）惩罚，避免少量字符匹配过多结果

## 核心指标说明
| 指标名称 | 说明 | 取值范围 | 优化目标 |
|----------|------|----------|----------|
| 命中率(Recall_Rate) | 命中数/总库数 | 0-100% | 越高越好（覆盖全面） |
| 平均匹配得分 | 所有命中结果的平均分 | 0-100 | 越高越好（匹配精准） |
| 精准匹配率 | 高分匹配数(≥80分)/总命中数 | 0-100% | 越高越好（高置信度结果占比） |
| 有效匹配占比 | 达标匹配数(≥阈值)/总命中数 | 0-100% | 100%最优（无低质量结果） |
| 空匹配标识 | 是否无命中结果 | True/False | False最优（有匹配结果） |

## 函数说明
| 函数名 | 功能 |
|--------|------|
| `retrieve_camera()` | 核心检索函数，返回匹配结果（可选返回指标） |
| `calculate_retrieval_metrics()` | 计算检索指标，返回完整指标字典 |
| `read_txt_to_list()` | 通用文件读取函数，支持编码容错和去重 |
| `read_test_cases()` | 读取测试用例文件，支持注释跳过和格式容错 |
| `run_interactive_test()` | 交互式测试函数，支持手动输入指令测试 |
| `run_batch_test_with_metrics()` | 批量测试函数，输出测试通过率和指标汇总 |

## 异常处理
程序包含完善的异常处理机制：
- 文件不存在：提示警告并返回空列表
- 编码错误：自动尝试UTF-8/GBK编码读取
- 空输入/空名称：过滤处理，避免程序崩溃
- 分数溢出：限制分数在0-100分范围内
- 操作词文件为空：自动使用内置默认操作词

## 扩展建议
1. **算法优化**：可增加拼音匹配、模糊匹配，适配多音字/错别字场景
2. **存储扩展**：将摄像头列表迁移至数据库（如MySQL/Redis），支持动态更新
3. **API封装**：封装为HTTP接口，支持跨系统调用
4. **可视化**：结合Matplotlib/Plotly生成匹配指标可视化报表
5. **缓存优化**：增加检索结果缓存，提升高频查询效率