# test

**Repository Path**: luoxiaofang/test

## Basic Information

- **Project Name**: test
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-01
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 档案语义检索 PoC

8000万份JPEG档案资料的语义检索、模糊检索、精确检索 - 小规模验证（1000张）

## 项目结构

```
archive_search/
├── data/
│   ├── images/              # 1000张模拟档案JPEG图片
│   ├── metadata.json        # 原始元数据（ground truth）
│   ├── ocr_results.json     # OCR识别结果
│   ├── embeddings/          # 向量数据
│   │   ├── text_embeddings.npy
│   │   ├── image_embeddings.npy
│   │   ├── index_map.json
│   │   ├── tfidf_vectorizer.pkl
│   │   └── svd_model.pkl
│   └── evaluation_report.json
├── src/
│   ├── generate_mock_archives.py   # 生成模拟档案
│   ├── ocr_pipeline.py             # OCR流水线
│   ├── embedding_pipeline.py       # 向量化流水线
│   ├── search_engine.py            # 混合检索引擎
│   └── evaluate.py                 # 端到端评估
└── requirements.txt
```

## 三种检索能力

### 1. 精确检索
基于结构化字段（档案号、部门、区域、日期等）的精确匹配。

```python
from src.search_engine import HybridSearchEngine
engine = HybridSearchEngine()
results = engine.exact_search("department", "市水利局")
```

### 2. 模糊检索
基于BM25的全文检索，支持：
- 关键词部分匹配
- OCR噪声容忍（错别字、空格等）
- 组合关键词查询

```python
results = engine.fuzzy_search("水利工程 立项批复", top_k=50)
```

### 3. 语义检索
基于稠密向量的语义相似度检索，支持：
- 同义词/近义词查询
- 概念扩展查询
- 以图搜图

```python
results = engine.semantic_search("河道建设", top_k=50)
results = engine.search_by_image("path/to/image.jpg", top_k=20)
```

### 4. 混合检索
统一检索网关，自动融合BM25 + 向量相似度，支持精确过滤。

```python
results = engine.hybrid_search(
    "海淀区水利工程",
    top_k=20,
    exact_field="department",
    exact_value="市水利局"
)
```

## 评估结果

| 检索类型 | 平均Recall | 平均Precision | 平均F1 | 平均MRR | 平均NDCG |
|---------|-----------|--------------|--------|---------|----------|
| 精确检索 | 0.878 | 1.000 | 0.931 | 1.000 | 1.000 |
| 模糊检索 | 0.778 | 0.493 | 0.520 | 1.000 | 0.808 |
| 语义检索 | 0.031 | 0.047 | 0.036 | 0.040 | 0.038 |
| 混合检索 | 1.000 | 0.477 | 0.646 | 1.000 | 1.000 |

## 快速开始

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

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

# 3. 生成模拟数据
python src/generate_mock_archives.py

# 4. OCR识别
python src/ocr_pipeline.py

# 5. 向量化
python src/embedding_pipeline.py

# 6. 运行检索演示
python src/search_engine.py

# 7. 端到端评估
python src/evaluate.py
```

## AI 质检分析

项目支持对档案图片进行多维度质量检测，覆盖**基础合规、著录准确、图像质量、完整性**四大类别共16个维度。

### 启动 Web 质检界面

```bash
cd web
python app.py
```

访问 http://localhost:8000 → 顶部菜单选择「AI质检分析」

### 图像质检维度测试

项目中已实现5个图像维度的真实检测算法，配套有自动生成模拟图片的测试脚本：

| 维度 | 检测内容 | 核心算法 |
|------|---------|---------|
| `slice-correctness` | 图片切片正确性 | 边缘留白对称性分析（OpenCV） |
| `duplicate-image` | 重复图像识别 | 感知哈希 aHash + 汉明距离比对 |
| `blank-page` | 空白页识别 | 内容密度 + 像素标准差 |
| `image-clarity` | 图像清晰度 | DPI/锐度/Tenengrad/摩尔纹/边缘密度 |
| `image-quality` | 图像质量综合 | 歪斜/噪点/污损/偏色四维度加权 |

**运行测试脚本：**

```bash
cd tests
python test_image_quality_checks.py
```

测试脚本会自动在 `tests/test_images/` 下生成 **22 种模拟场景**的图片并执行检测，输出每项的通过/警告结果。

**生成的模拟图片场景：**

- 正常扫描、倾斜扫描（5°/15°）、切片偏移
- 纯白空白页、有噪点空白页
- 高分辨率/低分辨率/模糊扫描/带摩尔纹
- 黄色/蓝色偏色、有污渍、高噪点

**测试输出示例：**

```
✅ [正常扫描] → pass: 切片正常
⚠️ [右偏移] → warning: 水平留白不对称(15.1%)
⚠️ [纯白空白页] → warning: 发现 1 张空白页
⚠️ [低分辨率150dpi] → warning: DPI严重不足(48)
```

## 档案图片 OCR 提取 Demo

项目提供两个基于 LLM 视觉能力的档案元数据提取 Demo，用于从 JPEG 档案图片中自动识别手写及印刷体信息。

### 前置配置

确保 `config/llm.env` 已正确配置 LLM API 密钥与端点：

```bash
# config/llm.env 示例
LLM_API_KEY=sk-xxx
LLM_BASE_URL=https://api.kimi.com/coding/v1
LLM_MODEL=kimi-for-coding
```

### 1. 基础版 Demo (`demo_ocr_extraction.py`)

功能：对单张档案图片进行视觉 OCR 提取，返回结构化 JSON。

```bash
# 使用默认图片（9cb16b76295c3a2228c9a45cf0525e81.jpg）
python demo_ocr_extraction.py

# 指定图片路径与旋转角度
python demo_ocr_extraction.py --image temp/9cb16b76295c3a2228c9a45cf0525e81.jpg --rotate 90
```

**运行结果示例**：

| 字段 | 提取结果 |
|------|----------|
| 全宗号 | 150 |
| 年度 | 2023 |
| 保存期限 | 永久 |
| 页数 | 11 |
| 机构_部门 | 办公室 |
| 责任者 | 广州市人民防空办公室 广州市住房和城乡建设局 广州市交通运输局 |
| 文号 | 穗人防办〔2023〕1号 |
| 题名 | 广州市人民防空办公室 广州市住房和城乡建设局 广州市交通运输局关于印发广州市人防工程防护设备产品和安装质量检测指引的通知 |
| 成文日期 | （空） |
| 密级 | （空） |
| 档案类别 | （空） |

提取结果自动保存至同目录下的 `.extracted.json` 文件。

### 2. 增强版 Demo (`demo_ocr_extraction_enhanced.py`)

功能：在基础版之上引入 ROI 裁剪放大、双图对照、置信度评估与规则校验，提升手写小字识别准确率。

```bash
# 使用默认图片
python demo_ocr_extraction_enhanced.py

# 指定图片与参数
python demo_ocr_extraction_enhanced.py --image 9cb16b76295c3a2228c9a45cf0525e81.jpg --rotate 90 --max-size 2048
```

**核心增强策略**：
1. **ROI 裁剪放大**：对右上角手写区域单独裁剪并放大 2.5 倍，增强手写笔迹清晰度
2. **双图对照**：同时向模型发送全局原图（上下文）与 ROI 特写（细节）
3. **Prompt 增强**：给出字段精确定义、位置描述与输出格式要求
4. **置信度评估**：每个提取值附加 `高/中/低` 三档置信度
5. **规则校验**：对全宗号、年度、页数等数字字段做后验正则校验，异常时告警

**运行结果示例**：

| 字段 | 提取结果 | 置信度 |
|------|----------|--------|
| 全宗号 | 150 | 高 |
| 年度 | 2023 | 高 |
| 保存期限 | 永久 | 高 |
| 页数 | 11 | 高 |
| 机构_部门 | 办公室 | 高 |
| 责任者 | 广州市人民防空办公室 广州市住房和城乡建设局 广州市交通运输局 | 高 |
| 文号 | 穗人防办〔2023〕1号 | 高 |
| 题名 | 关于印发广州市人防工程防护设备产品和安装质量检测指引的通知 | 高 |
| 档案类别 | 文书档案 | 高 |

提取结果自动保存至同目录下的 `.enhanced.json` 文件。

## 扩展到8000万规模

当前PoC使用轻量级方案，生产环境建议替换：

| 组件 | PoC方案 | 生产方案 |
|-----|---------|---------|
| OCR | 模拟（真实场景用PaddleOCR） | PaddleOCR / Azure Document Intelligence |
| 文本向量 | TF-IDF + SVD | BGE-M3 / Qwen3-Embedding |
| 图像向量 | 手工特征 | CLIP / SigLIP |
| 模糊检索 | BM25 in-memory | Elasticsearch / OpenSearch |
| 语义检索 | FAISS-CPU | Milvus / Qdrant |
| 精确检索 | Python dict | ClickHouse / PostgreSQL |
| 融合排序 | RRF | RRF + Cross-Encoder重排 |