Fix paddlepaddle version to 2.6.2

.dockerignore

@@ -0,0 +1,8 @@
+__pycache__
+*.pyc
+*.pyo
+.git
+.gitignore
+qdrant_data/
+Logs/
+*.log

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,4 @@
+qdrant_data/
+Logs/
+__pycache__/
+*.pyc

Dockerfile

@@ -0,0 +1,44 @@
+# ============================================
+# HF Spaces Dockerfile — 场景一致性检测 (CPU)
+# ============================================
+FROM python:3.10-slim
+
+# 系统依赖（OpenCV 运行时 + 文件处理）
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgl1 \
+    libglib2.0-0 \
+    libsm6 \
+    libxext6 \
+    libxrender1 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# 1. 先安装 PyTorch CPU 版（与 paddlepaddle 分开安装避免冲突）
+RUN pip install --no-cache-dir torch torchvision --index-url https://download.pytorch.org/whl/cpu
+
+# 2. 安装其余 Python 依赖
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 3. 预下载 DINOv2 reg4 模型权重（约 85MB，构建时下载到镜像中）
+RUN python -c "import timm; timm.create_model('vit_small_patch14_reg4_dinov2', pretrained=True)" || echo "DINOv2 pre-download warning"
+
+# 4. 预下载 BGE-small-zh 模型权重（约 100MB）
+RUN python -c "from transformers import AutoTokenizer, BertModel; AutoTokenizer.from_pretrained('BAAI/bge-small-zh-v1.5'); BertModel.from_pretrained('BAAI/bge-small-zh-v1.5')" || echo "BGE pre-download warning"
+
+# 5. 预下载 PaddleOCR 模型（约 50MB，通过运行一次 OCR 触发下载）
+RUN python -c "from paddleocr import PaddleOCR; from PIL import Image; ocr=PaddleOCR(use_angle_cls=True, lang='ch'); img=Image.new('RGB',(100,100),'white'); img.save('/tmp/d.png'); ocr.ocr('/tmp/d.png', cls=True)" || echo "PaddleOCR pre-download warning"
+
+# 6. 复制应用代码
+COPY . .
+
+# 7. 创建运行时目录
+RUN mkdir -p /app/History_imgs /app/qdrant_data /app/Logs
+
+# HF Spaces Docker 默认端口 7860
+EXPOSE 7860
+ENV PORT=7860
+
+# 启动服务
+CMD ["python", "-m", "uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,30 @@
+---
+title: Scene Consistency Detection
+emoji: 📷
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+---
+
+# 场景一致性检测系统 (CPU)
+
+基于 **DINOv2 reg4 + BGE-small-zh + PaddleOCR** 的多角度场景一致性检测，部署在 Hugging Face Spaces (CPU)。
+
+## 功能
+
+- 上传图片，自动与历史图片库比对是否为同一场景
+- **文本场景**（合同/证书等文档）：PaddleOCR + BGE 语义相似度 (≥0.85)
+- **复杂场景**（实景照片）：DINOv2 reg4 全局特征余弦相似度 (≥0.55)
+
+## 技术栈
+
+| 组件 | 说明 |
+|------|------|
+| DINOv2 | vit_small_patch14_reg4_dinov2 (384维, timm) |
+| BGE | bge-small-zh-v1.5 (512维, transformers) |
+| OCR | PaddleOCR 2.x (CPU) |
+| 向量库 | Qdrant 嵌入式本地模式 |
+| Web | FastAPI + 原生 HTML |

app.py

@@ -0,0 +1,399 @@
+"""FastAPI 主服务 — HF Spaces CPU 部署版
+
+改动点（相比原项目）：
+1. 端口改为 7860（HF Spaces Docker 默认端口）
+2. MASt3R 模型加载返回 None，SceneMatcher 使用 DINOv2-only 模式
+3. Qdrant 使用嵌入式本地文件模式
+"""
+import os
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import asynccontextmanager
+import time
+
+from fastapi import FastAPI, UploadFile, File, Form, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse
+
+from module.model_loader import load_model, load_dinov2, load_ocr, load_bge
+from module.scene_matcher import SceneMatcher
+from module.file_manager import (
+    validate_username, get_user_dir, get_history_images,
+    save_uploaded_file, delete_file
+)
+from module.evaluator import (
+    evaluate_scene_consistency, evaluate_scene_consistency_cached, update_metadata
+)
+from module.system_monitor import _snapshot, ResourceMonitor, write_session_log
+from module.qdrant_manager import (
+    build_user_cache, qdrant_query_scene, has_qdrant_cache,
+    add_to_qdrant, remove_from_qdrant,
+)
+from module.qdrant_manager import qdrant_search_similar, pt_id
+from module.text_classifier import classify_scene
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+FRONTEND_PATH = os.path.join(BASE_DIR, 'index.html')
+HISTORY_BASE = os.path.join(BASE_DIR, 'History_imgs')
+
+matcher = None
+dinov2_extractor = None
+ocr_engine = None
+bge_tokenizer = None
+bge_model = None
+executor = ThreadPoolExecutor(max_workers=1)
+
+session_data = {
+    'startup_stats': None,
+    'model_loaded_stats': None,
+    'detections': [],
+}
+
+resource_monitor = ResourceMonitor(sample_interval=0.5)
+
+# 用户 Qdrant 缓存: {username: {scene_type: {pid: entry}}}
+_qd_caches = {}
+
+
+@asynccontextmanager
+async def lifespan(app):
+    """FastAPI 生命周期管理：启动时加载模型，关闭时写入日志"""
+    global matcher, dinov2_extractor, ocr_engine, bge_tokenizer, bge_model, session_data
+
+    startup_t0 = time.perf_counter()
+    session_data['startup_stats'] = _snapshot()
+
+    # MASt3R 返回 None（CPU 部署已禁用）
+    model = load_model()
+    dinov2_extractor = load_dinov2()
+    matcher = SceneMatcher(model, dinov2_extractor=dinov2_extractor)
+
+    ocr_engine = load_ocr()
+    bge_tokenizer, bge_model = load_bge()
+
+    session_data['model_loaded_stats'] = _snapshot()
+    model_load_time = time.perf_counter() - startup_t0
+    print(f'[启动] 模型加载完成: {model_load_time:.1f}s')
+
+    # 启动时预加载所有用户 Qdrant 缓存
+    qdrant_t0 = time.perf_counter()
+    if os.path.isdir(HISTORY_BASE):
+        for uname in os.listdir(HISTORY_BASE):
+            udir = os.path.join(HISTORY_BASE, uname)
+            if not os.path.isdir(udir):
+                continue
+            imgs = get_history_images(udir)
+            if not imgs:
+                continue
+            try:
+                if not has_qdrant_cache(uname):
+                    print(f"[qdrant] 启动预构建: 用户 [{uname}]")
+                    build_user_cache(uname, udir, ocr_engine, dinov2_extractor,
+                                     bge_tokenizer, bge_model)
+                _qd_caches[uname] = {
+                    'text': qdrant_query_scene(uname, 'text'),
+                    'complex': qdrant_query_scene(uname, 'complex'),
+                }
+                _t_n = len(_qd_caches[uname]['text'])
+                _c_n = len(_qd_caches[uname]['complex'])
+                print(f"  [{uname}] 缓存已就绪 (text={_t_n}, complex={_c_n})")
+            except Exception as e:
+                print(f"  [{uname}] 缓存加载失败: {e}")
+    qdrant_load_time = time.perf_counter() - qdrant_t0
+    print(f"[qdrant] 缓存检查完成: {len(_qd_caches)} 个用户 ({qdrant_load_time:.1f}s)")
+    total_startup = time.perf_counter() - startup_t0
+    print(f"[启动] 总启动时间: {total_startup:.1f}s")
+
+    yield
+
+    session_data['shutdown_stats'] = _snapshot()
+    try:
+        log_path = write_session_log(session_data)
+        print(f"日志已写入: {log_path}")
+    except Exception as e:
+        print(f"日志写入失败: {e}")
+
+
+app = FastAPI(lifespan=lifespan)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/")
+async def serve_frontend():
+    return FileResponse(FRONTEND_PATH)
+
+
+@app.post("/api/login")
+async def login(username: str = Form(...)):
+    try:
+        uname = validate_username(username)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    user_dir = get_user_dir(uname)
+    history = get_history_images(user_dir)
+
+    cached = uname in _qd_caches
+    if not cached and history and has_qdrant_cache(uname):
+        _qd_caches[uname] = {
+            'text': qdrant_query_scene(uname, 'text'),
+            'complex': qdrant_query_scene(uname, 'complex'),
+        }
+        cached = True
+
+    return {
+        "username": uname,
+        "history_count": len(history),
+        "cached": cached,
+    }
+
+
+def _run_detect_pipeline(uploaded_paths, uname, ocr_engine, bge_tokenizer,
+                         bge_model, dinov2_extractor, matcher, history_before):
+    scene_type_q = 'complex'
+    ocr_result_q = None
+    precomputed_text = None
+    precomputed_bge = None
+    precomputed_dinov2 = None
+
+    _t0 = time.perf_counter()
+    if ocr_engine is not None and uploaded_paths:
+        scene_type_q, _, _, ocr_result_q = classify_scene(uploaded_paths[0], ocr_engine)
+        _t1 = time.perf_counter()
+        print(f'  [TIME] classify_scene: {_t1-_t0:.3f}s')
+        if ocr_result_q is not None and ocr_result_q and ocr_result_q[0]:
+            precomputed_text = ' '.join(line[1][0] for line in ocr_result_q[0])
+        if precomputed_text and precomputed_text.strip():
+            from module.qdrant_manager import _bge_encode
+            precomputed_bge = _bge_encode(precomputed_text, bge_tokenizer, bge_model)
+            _t2 = time.perf_counter()
+            print(f'  [TIME] bge_encode: {_t2-_t1:.3f}s')
+
+    user_qd = _qd_caches.get(uname, {})
+    has_cache = isinstance(user_qd, dict) and bool(user_qd)
+
+    cache_used = False
+    final_result = True
+    evaluation_logs = []
+    best_match = None
+
+    if has_cache:
+        cache_used = True
+        print(f"[qdrant] 使用 ANN 搜索管线 (用户 [{uname}], 场景={scene_type_q})")
+        final_result, evaluation_logs, best_match = evaluate_scene_consistency_cached(
+            matcher, uploaded_paths, uname,
+            ocr_engine, bge_tokenizer, bge_model,
+            scene_type_q, qdrant_search_similar, dinov2_extractor,
+            precomputed_ocr_result=ocr_result_q,
+            precomputed_bge_vec=precomputed_bge,
+            qd_cache=user_qd,
+        )
+
+    if not cache_used:
+        print(f"[qdrant] 缓存不可用，回退到原始管线 (用户 [{uname}])")
+        final_result, evaluation_logs, best_match = evaluate_scene_consistency(
+            matcher, uploaded_paths, history_before,
+            ocr_engine, bge_tokenizer, bge_model,
+        )
+
+    same_scene_paths = set()
+    for log in evaluation_logs:
+        if log['is_same_scene'] and log['query_path'] in uploaded_paths:
+            same_scene_paths.add(log['query_path'])
+
+    for path in same_scene_paths:
+        delete_file(path)
+
+    per_image_results = {}
+    for orig, path in [(os.path.basename(p), p) for p in uploaded_paths]:
+        if path in same_scene_paths:
+            per_image_results[path] = '未通过（同一场景，已删除）'
+        else:
+            per_image_results[path] = '通过' if final_result else '未通过'
+
+    return final_result, evaluation_logs, best_match, scene_type_q, same_scene_paths, per_image_results, cache_used, precomputed_text, precomputed_bge, precomputed_dinov2
+
+
+@app.post("/api/detect")
+async def detect(
+    username: str = Form(...),
+    images: list[UploadFile] = File(default=[]),
+):
+    global session_data, _qd_caches
+
+    try:
+        uname = validate_username(username)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    user_dir = get_user_dir(uname)
+
+    if len(images) == 0:
+        raise HTTPException(status_code=400, detail="请上传至少一张图片")
+
+    history_before = get_history_images(user_dir)
+
+    saved_info = []
+    for f in images:
+        data = await f.read()
+        if not data:
+            continue
+        path = save_uploaded_file(data, f.filename, user_dir)
+        saved_info.append((f.filename, path))
+
+    if not saved_info:
+        raise HTTPException(status_code=400, detail="没有有效的上传图片")
+
+    uploaded_paths = [p for _, p in saved_info]
+
+    if len(history_before) == 0:
+        per_image_results = {p: '通过（首次上传，跳过比对）' for _, p in saved_info}
+        update_metadata(user_dir, saved_info, per_image_results)
+        try:
+            for _, p in saved_info:
+                add_to_qdrant(uname, p, ocr_engine, dinov2_extractor,
+                              bge_tokenizer, bge_model)
+            _qd_caches[uname] = {
+                'text': qdrant_query_scene(uname, 'text'),
+                'complex': qdrant_query_scene(uname, 'complex'),
+            }
+        except Exception:
+            pass
+        return {
+            "result": "pass",
+            "reason": "first_upload",
+            "saved_files": [
+                {"filename": os.path.basename(p), "original_name": orig, "deleted": False}
+                for orig, p in saved_info
+            ],
+            "evaluation_logs": [],
+            "best_match": None,
+            "gamma_warnings": [],
+        }
+
+    pre_stats = _snapshot()
+    detect_start_time = asyncio.get_event_loop().time()
+    resource_monitor.start_monitoring()
+
+    loop = asyncio.get_event_loop()
+    final_result, evaluation_logs, best_match, scene_type_q, same_scene_paths, per_image_results, cache_used, precomp_text, precomp_bge, precomp_dino = \
+        await loop.run_in_executor(
+            executor, _run_detect_pipeline,
+            uploaded_paths, uname, ocr_engine, bge_tokenizer,
+            bge_model, dinov2_extractor, matcher, history_before,
+        )
+
+    peak = resource_monitor.stop_monitoring()
+    detect_duration = asyncio.get_event_loop().time() - detect_start_time
+
+    n_query = len(uploaded_paths)
+    n_pairs = len(evaluation_logs)
+    if peak:
+        print(f"检测完成 | 耗时: {detect_duration:.1f}s | 查询图: {n_query} | 比对数: {n_pairs} | 缓存: {'ON' if cache_used else 'OFF'}")
+
+    detection_record = {
+        'pre_stats': pre_stats,
+        'peak': peak,
+        'duration_sec': round(detect_duration, 1),
+        'cache_used': cache_used,
+    }
+    session_data['detections'].append(detection_record)
+
+    kept_saved_info = [(orig, p) for orig, p in saved_info if p not in same_scene_paths]
+    update_metadata(user_dir, kept_saved_info, per_image_results)
+
+    kept_paths_qd = [p for _, p in kept_saved_info]
+    removed_paths_qd = list(same_scene_paths)
+    st_q = scene_type_q
+
+    def _post_update_qdrant():
+        for path in kept_paths_qd:
+            try:
+                add_to_qdrant(uname, path, ocr_engine, dinov2_extractor,
+                              bge_tokenizer, bge_model, scene_type=st_q,
+                              precomputed_text=precomp_text,
+                              precomputed_bge=precomp_bge,
+                              precomputed_dinov2=precomp_dino)
+                _qd_caches[uname] = {
+                    'text': qdrant_query_scene(uname, 'text'),
+                    'complex': qdrant_query_scene(uname, 'complex'),
+                }
+            except Exception:
+                pass
+        for path in removed_paths_qd:
+            try:
+                remove_from_qdrant(uname, path, scene_type=None)
+            except Exception:
+                pass
+
+    loop.run_in_executor(executor, _post_update_qdrant)
+
+    gamma_warnings = []
+
+    best_match_response = None
+    if best_match:
+        best_match_response = {
+            'query_image': best_match['query_image'],
+            'history_image': best_match['history_image'],
+            'similarity_score': best_match['similarity_score'],
+            'match_count': best_match['match_count'],
+            'inlier_ratio': best_match['inlier_ratio'],
+            'avg_confidence': best_match['avg_confidence'],
+            'gamma_info': best_match.get('gamma_info', []),
+        }
+
+    return {
+        "result": "pass" if final_result else "fail",
+        "saved_files": [
+            {"filename": os.path.basename(p), "original_name": orig, "deleted": p in same_scene_paths}
+            for orig, p in saved_info
+        ],
+        "evaluation_logs": [
+            {
+                "query_image": log['query_image'],
+                "history_image": log['history_image'],
+                "scene_type": log.get('scene_type', 'complex'),
+                "doc_score1": log.get('doc_score1', 0),
+                "doc_score2": log.get('doc_score2', 0),
+                "similarity_score": log['similarity_score'],
+                "match_count": log['match_count'],
+                "raw_match_count": log.get('raw_match_count', 0),
+                "inlier_ratio": log['inlier_ratio'],
+                "avg_confidence": log['avg_confidence'],
+                "mast3r_is_same": log.get('mast3r_is_same'),
+                "dinov2_is_same": log.get('dinov2_is_same'),
+                "dinov2_similarity": log.get('dinov2_similarity'),
+                "text_similarity": log.get('text_similarity'),
+                "bge_search_score": log.get('bge_search_score'),
+                "is_same_scene": log['is_same_scene'],
+                "error": log.get('error'),
+            }
+            for log in evaluation_logs
+        ],
+        "best_match": best_match_response,
+        "gamma_warnings": gamma_warnings,
+    }
+
+
+@app.get("/api/status")
+async def status():
+    return {
+        "model_loaded": matcher is not None,
+        "device": matcher.device if matcher else None,
+        "ocr_available": ocr_engine is not None,
+        "bge_available": bge_tokenizer is not None,
+        "qdrant_cached_users": len(_qd_caches),
+    }
+
+
+if __name__ == "__main__":
+    import uvicorn
+    # HF Spaces Docker 默认端口 7860
+    port = int(os.environ.get("PORT", 7860))
+    uvicorn.run("app:app", host="0.0.0.0", port=port, reload=False)

index.html

@@ -0,0 +1,279 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>场景一致性检测系统 (DINOv2 + BGE)</title>
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+body{font-family:'Segoe UI','Microsoft YaHei',sans-serif;background:#f0f2f5;min-height:100vh;color:#333}
+.container{max-width:960px;margin:0 auto;padding:20px}
+
+.header{background:linear-gradient(135deg,#667eea,#764ba2);color:#fff;padding:20px 30px;border-radius:12px;margin-bottom:20px;text-align:center}
+.header h1{font-size:22px;margin-bottom:4px}
+.header p{font-size:13px;opacity:.85}
+
+.status-bar{background:#fff;border-radius:10px;padding:14px 20px;margin-bottom:16px;display:flex;align-items:center;justify-content:space-between;box-shadow:0 2px 8px rgba(0,0,0,.06);flex-wrap:wrap;gap:10px}
+.status-info{display:flex;gap:20px;flex-wrap:wrap;font-size:14px}
+.status-info span{display:flex;align-items:center;gap:4px}
+.status-actions{display:flex;gap:8px}
+
+.card{background:#fff;border-radius:10px;padding:20px;margin-bottom:16px;box-shadow:0 2px 8px rgba(0,0,0,.06)}
+.card h3{font-size:15px;margin-bottom:12px;color:#555}
+
+.upload-zone{border:2px dashed #d9d9d9;border-radius:8px;padding:24px;text-align:center;cursor:pointer;transition:all .2s;position:relative}
+.upload-zone:hover{border-color:#667eea;background:#f8f8ff}
+.upload-zone input{position:absolute;inset:0;opacity:0;cursor:pointer}
+.upload-zone .icon{font-size:32px;margin-bottom:8px}
+.upload-zone .hint{font-size:13px;color:#999}
+
+.file-list{margin-top:10px;font-size:13px;color:#666}
+.file-list div{padding:3px 0}
+
+.btn{padding:10px 20px;border:none;border-radius:8px;font-size:14px;cursor:pointer;transition:all .15s;font-weight:500}
+.btn:disabled{opacity:.5;cursor:not-allowed}
+.btn-primary{background:linear-gradient(135deg,#667eea,#764ba2);color:#fff}
+.btn-primary:hover:not(:disabled){transform:translateY(-1px);box-shadow:0 4px 12px rgba(102,126,234,.4)}
+.btn-info{background:#17a2b8;color:#fff}
+.btn-info:hover:not(:disabled){background:#138496}
+.btn-danger{background:#dc3545;color:#fff}
+.btn-danger:hover:not(:disabled){background:#c82333}
+
+.result-pass{background:#d4edda;border:2px solid #28a745;border-radius:10px;padding:20px;text-align:center;margin-bottom:16px}
+.result-pass h2{color:#155724;font-size:20px}
+.result-pass p{color:#155724;font-size:14px;margin-top:4px}
+
+.result-fail{background:#f8d7da;border:2px solid #dc3545;border-radius:10px;padding:20px;text-align:center;margin-bottom:16px}
+.result-fail h2{color:#721c24;font-size:20px}
+.result-fail p{color:#721c24;font-size:14px;margin-top:4px}
+
+table{width:100%;border-collapse:collapse;font-size:13px;margin-top:12px}
+th{background:#343a40;color:#fff;padding:10px 8px;text-align:center;font-weight:500}
+td{padding:8px;text-align:center;border-bottom:1px solid #eee}
+tr.row-fail{background:#fff5f5}
+tr.row-fail td{color:#721c24}
+
+.deleted-info{background:#fff5f5;border:1px solid #dc3545;border-radius:8px;padding:10px 16px;margin-bottom:12px;font-size:13px;color:#721c24}
+
+.loading-overlay{position:fixed;inset:0;background:rgba(0,0,0,.45);display:flex;align-items:center;justify-content:center;z-index:999}
+.loading-box{background:#fff;border-radius:12px;padding:30px 40px;text-align:center;box-shadow:0 8px 30px rgba(0,0,0,.2)}
+.spinner{width:40px;height:40px;border:4px solid #e0e0e0;border-top-color:#667eea;border-radius:50%;animation:spin .8s linear infinite;margin:0 auto 12px}
+@keyframes spin{to{transform:rotate(360deg)}}
+
+.login-card{background:#fff;border-radius:12px;padding:40px;max-width:400px;margin:80px auto;box-shadow:0 4px 20px rgba(0,0,0,.1);text-align:center}
+.login-card h2{margin-bottom:20px;color:#333}
+.login-card input{width:100%;padding:12px 16px;border:2px solid #e0e0e0;border-radius:8px;font-size:15px;margin-bottom:16px;outline:none;transition:border-color .2s}
+.login-card input:focus{border-color:#667eea}
+
+.error-msg{color:#dc3545;font-size:13px;margin-top:4px;min-height:18px}
+
+.hidden{display:none!important}
+</style>
+</head>
+<body>
+
+<div id="loginView" class="container">
+  <div class="login-card">
+    <div style="font-size:48px;margin-bottom:12px">🚀</div>
+    <h2>场景一致性检测系统</h2>
+    <p style="color:#999;font-size:13px;margin-bottom:16px">DINOv2 reg4 + BGE + PaddleOCR (CPU)</p>
+    <input type="text" id="usernameInput" placeholder="请输入用户名" maxlength="50">
+    <div id="loginError" class="error-msg"></div>
+    <button class="btn btn-primary" style="width:100%;margin-top:8px" onclick="doLogin()">确认登录</button>
+  </div>
+</div>
+
+<div id="mainView" class="container hidden">
+  <div class="header">
+    <h1>场景一致性检测系统</h1>
+    <p>基于 DINOv2 reg4 + BGE 的多角度场景一致性评估</p>
+  </div>
+
+  <div class="status-bar">
+    <div class="status-info">
+      <span>👤 用户: <b id="dispUser">-</b></span>
+      <span>📁 历史图片: <b id="dispCount">0</b> 张</span>
+    </div>
+    <div class="status-actions">
+      <button class="btn btn-info" onclick="switchUser()">🔄 更换用户</button>
+    </div>
+  </div>
+
+  <div class="card">
+    <h3>📷 上传待检测图片 <span style="color:#666">(支持多选)</span></h3>
+    <div class="upload-zone" id="queryZone">
+      <input type="file" accept="image/*" multiple id="queryInput" onchange="onQueryChange()">
+      <div class="icon">🖼️</div>
+      <div class="hint">点击选择待检测图片（可多选）</div>
+    </div>
+    <div id="queryFileList" class="file-list"></div>
+  </div>
+
+  <div style="text-align:center;margin:20px 0">
+    <button class="btn btn-primary" style="padding:12px 40px;font-size:16px" id="detectBtn" onclick="doDetect()">🚀 开始检测</button>
+  </div>
+
+  <div id="resultArea"></div>
+</div>
+
+<div id="loadingOverlay" class="loading-overlay hidden">
+  <div class="loading-box">
+    <div class="spinner"></div>
+    <div id="loadingText">正在检测中，请稍候...</div>
+  </div>
+</div>
+
+<script>
+let currentUser = '';
+
+document.getElementById('usernameInput').addEventListener('keydown', e => {
+  if (e.key === 'Enter') doLogin();
+});
+
+async function doLogin() {
+  const name = document.getElementById('usernameInput').value.trim();
+  const errEl = document.getElementById('loginError');
+  errEl.textContent = '';
+  if (!name) { errEl.textContent = '用户名不能为空'; return; }
+
+  try {
+    const fd = new FormData();
+    fd.append('username', name);
+    const res = await fetch('/api/login', { method: 'POST', body: fd });
+    if (!res.ok) {
+      const d = await res.json();
+      errEl.textContent = d.detail || '登录失败';
+      return;
+    }
+    const data = await res.json();
+    currentUser = data.username;
+    showMain(data);
+  } catch (e) {
+    errEl.textContent = '网络错误: ' + e.message;
+  }
+}
+
+function showMain(data) {
+  document.getElementById('loginView').classList.add('hidden');
+  document.getElementById('mainView').classList.remove('hidden');
+  document.getElementById('dispUser').textContent = data.username;
+  document.getElementById('dispCount').textContent = data.history_count;
+  clearUploads();
+  document.getElementById('resultArea').innerHTML = '';
+}
+
+function clearUploads() {
+  document.getElementById('queryInput').value = '';
+  document.getElementById('queryFileList').innerHTML = '';
+}
+
+function onQueryChange() {
+  const files = document.getElementById('queryInput').files;
+  const list = document.getElementById('queryFileList');
+  list.innerHTML = '';
+  for (const f of files) {
+    list.innerHTML += `<div>📄 ${f.name} (${(f.size/1024).toFixed(1)} KB)</div>`;
+  }
+}
+
+async function doDetect() {
+  const queryFiles = document.getElementById('queryInput').files;
+  if (queryFiles.length === 0) {
+    alert('请上传至少一张图片！');
+    return;
+  }
+
+  const fd = new FormData();
+  fd.append('username', currentUser);
+  for (const f of queryFiles) fd.append('images', f);
+
+  showLoading('正在进行场景比对，请稍候...');
+  document.getElementById('detectBtn').disabled = true;
+
+  try {
+    const res = await fetch('/api/detect', { method: 'POST', body: fd });
+    if (!res.ok) {
+      const d = await res.json();
+      alert('检测失败: ' + (d.detail || '未知错误'));
+      return;
+    }
+    const data = await res.json();
+    renderResult(data);
+  } catch (e) {
+    alert('网络错误: ' + e.message);
+  } finally {
+    hideLoading();
+    document.getElementById('detectBtn').disabled = false;
+  }
+}
+
+function renderResult(data) {
+  const area = document.getElementById('resultArea');
+  let html = '';
+
+  if (data.result === 'pass') {
+    if (data.reason === 'first_upload') {
+      html += `<div class="result-pass"><h2>✅ 评估通过</h2><p>首次上传图片已保存，跳过比对</p></div>`;
+    } else {
+      html += `<div class="result-pass"><h2>✅ 评估通过</h2><p>所有上传图片与历史图片均不构成同一场景</p></div>`;
+    }
+  } else {
+    html += `<div class="result-fail"><h2>❌ 评估未通过</h2><p>存在上传图片与历史图片被判定为同一场景</p></div>`;
+  }
+
+  const deletedFiles = (data.saved_files || []).filter(f => f.deleted);
+  if (deletedFiles.length > 0) {
+    html += `<div class="deleted-info">🗑️ <b>已删除同一场景图片:</b> ${deletedFiles.map(f => f.original_name).join('、')}</div>`;
+  }
+
+  if (data.evaluation_logs && data.evaluation_logs.length > 0) {
+    html += `<div class="card"><h3>📋 比对详情日志</h3><table>`;
+    html += `<thead><tr><th>待检测</th><th>历史</th><th>场景</th><th>DINOv2相似度</th><th>文本相似</th><th>BGE搜索</th><th>最终判定</th></tr></thead><tbody>`;
+
+    for (const log of data.evaluation_logs) {
+      const rowClass = log.is_same_scene ? ' class="row-fail"' : '';
+      const truncName = (n, max=14) => n.length > max ? n.substring(0, max-2) + '..' : n;
+      const qName = truncName(log.query_image);
+      const hName = truncName(log.history_image);
+      const sceneLabel = log.scene_type === 'text' ? '📄 文本' : '🖼️ 复杂';
+      const dinov2Val = log.dinov2_similarity != null ? log.dinov2_similarity.toFixed(3) : '-';
+      const textSim = log.text_similarity != null ? log.text_similarity.toFixed(3) : '-';
+      const bgeSearchVal = log.bge_search_score != null ? log.bge_search_score.toFixed(4) : '-';
+      const finalStatus = log.is_same_scene ? '❌ 同一' : '✅ 不同';
+      const errNote = log.error ? ` <span style="color:red;font-size:11px">(${log.error.substring(0,30)})</span>` : '';
+      html += `<tr${rowClass}>`;
+      html += `<td title="${log.query_image}">${qName}</td>`;
+      html += `<td title="${log.history_image}">${hName}</td>`;
+      html += `<td style="font-size:12px">${sceneLabel}</td>`;
+      html += `<td>${dinov2Val}</td>`;
+      html += `<td>${textSim}</td>`;
+      html += `<td>${bgeSearchVal}</td>`;
+      html += `<td>${finalStatus}${errNote}</td>`;
+      html += `</tr>`;
+    }
+    html += `</tbody></table></div>`;
+  }
+
+  area.innerHTML = html;
+}
+
+function switchUser() {
+  currentUser = '';
+  document.getElementById('mainView').classList.add('hidden');
+  document.getElementById('loginView').classList.remove('hidden');
+  document.getElementById('usernameInput').value = '';
+  document.getElementById('loginError').textContent = '';
+  document.getElementById('usernameInput').focus();
+}
+
+function showLoading(text) {
+  document.getElementById('loadingText').textContent = text || '处理中...';
+  document.getElementById('loadingOverlay').classList.remove('hidden');
+}
+
+function hideLoading() {
+  document.getElementById('loadingOverlay').classList.add('hidden');
+}
+</script>
+</body>
+</html>

module/config.py

@@ -0,0 +1,56 @@
+"""HF Spaces CPU 部署配置 — 无 MASt3R，DINOv2 reg4 模型，Qdrant 嵌入式"""
+import os
+import torch
+
+PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+# 强制 CPU 模式
+DEVICE = "cpu"
+USE_HALF = False
+IMAGE_SIZE = 512
+
+# MASt3R 已禁用（CPU 部署，耗时过长）
+MAST3R_ROOT = None
+LOCAL_WEIGHTS = None
+
+# 历史图片存储
+HISTORY_BASE_DIR = os.path.join(PROJECT_ROOT, 'History_imgs')
+SUPPORTED_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.tiff', '.tif', '.webp', '.jfif'}
+
+# Qdrant 嵌入式模式（无需独立服务进程）
+QDRANT_PATH = os.path.join(PROJECT_ROOT, 'qdrant_data')
+
+# --- DINOv2 阈值（保留兼容性） ---
+MIN_MATCHES = 20
+MIN_INLIER_RATIO = 0.15
+EDGE_MARGIN = 3
+DINOV2_SIM_THRESHOLD = 0.5
+DINOV2_HIGH_CONF_THRESHOLD = 0.7
+STRICT_MIN_MATCHES = 100
+STRICT_MIN_INLIER_RATIO = 0.50
+MODERATE_MIN_MATCHES = 350
+MODERATE_MIN_INLIER_RATIO = 0.55
+
+# DINOv2-only 模式阈值（无 MASt3R）：相似度 ≥ 此值 → 判定为同一场景
+# reg4 模型的 CLS 特征质量更好，0.55 为推荐起始值，可按业务调优
+DINOV2_ONLY_SAME_THRESHOLD = 0.55
+
+# 日志目录
+LOGS_DIR = os.path.join(PROJECT_ROOT, 'Logs')
+
+# --- 场景分类器 ---
+TEXT_AREA_WEIGHT = 0.15
+WHITENESS_WEIGHT = 0.50
+LOW_VARIANCE_WEIGHT = 0.25
+LINE_DENSITY_WEIGHT = 0.10
+DOC_SCORE_THRESHOLD = 0.45
+
+# --- 文本场景比对 ---
+TEXT_SIM_WEIGHT = 0.6
+SSIM_WEIGHT = 0.3
+SEAL_WEIGHT = 0.1
+TEXT_SCENE_THRESHOLD = 0.7
+TEXT_SCENE_BGE_THRESHOLD = 0.85
+
+# BGE 模型：使用 HuggingFace Hub 在线加载（Dockerfile 中预下载）
+BGE_MODEL_PATH = 'BAAI/bge-small-zh-v1.5'

module/dinov2_utils.py

@@ -0,0 +1,83 @@
+"""DINOv2 特征提取器 — vit_small_patch14_reg4_dinov2 (带寄存器令牌)"""
+import torch
+import torch.nn.functional as F
+from torchvision import transforms
+from PIL import Image
+
+from module.config import DEVICE
+
+
+class DINOv2Extractor:
+    """DINOv2 全局语义特征提取器
+
+    使用 vit_small_patch14_reg4_dinov2 模型（4个寄存器令牌），
+    相比无寄存器版本，CLS token 特征质量更高，对背景噪声更鲁棒。
+    输出 384 维归一化特征向量。
+    """
+
+    TIMM_MODEL_NAME = 'vit_small_patch14_reg4_dinov2'
+
+    def __init__(self, device=None):
+        self.device = device or DEVICE
+        self.model = None
+        self._use_timm = False
+        # DINOv2 标准预处理：518x518，ImageNet 归一化
+        self.transform = transforms.Compose([
+            transforms.Resize(518, interpolation=transforms.InterpolationMode.BICUBIC),
+            transforms.CenterCrop(518),
+            transforms.ToTensor(),
+            transforms.Normalize(mean=[0.485, 0.456, 0.406],
+                                 std=[0.229, 0.224, 0.225]),
+        ])
+
+        try:
+            import timm
+            print(f"通过 timm 加载 DINOv2 (reg4): {self.TIMM_MODEL_NAME}")
+            self.model = timm.create_model(self.TIMM_MODEL_NAME, pretrained=True)
+            self._use_timm = True
+            self.model = self.model.to(self.device).eval()
+            print("DINOv2 reg4 模型加载完成")
+        except Exception as e:
+            print(f"timm 加载 DINOv2 失败: {e}")
+            self.model = None
+
+    @property
+    def is_available(self):
+        return self.model is not None
+
+    @torch.no_grad()
+    def _get_cls_feature(self, img_tensor):
+        """从 forward_features 提取 CLS token，适配 timm 的 dict 返回格式"""
+        features = self.model.forward_features(img_tensor)
+        # timm 0.9+ 返回 dict
+        if isinstance(features, dict):
+            if 'x_norm_clstoken' in features:
+                return features['x_norm_clstoken']
+            # 兜底：取第一个值的 CLS 位置
+            for v in features.values():
+                if isinstance(v, torch.Tensor) and v.dim() >= 2:
+                    return v[:, 0]
+        # 旧版 timm 返回 tensor (B, N, C)
+        if isinstance(features, torch.Tensor):
+            return features[:, 0]
+        raise ValueError(f"无法从 forward_features 提取 CLS token: {type(features)}")
+
+    @torch.no_grad()
+    def extract_feature(self, img_path):
+        """提取单张图片的 DINOv2 CLS 全局特征向量（384维，已归一化）"""
+        if self.model is None:
+            return None
+        img = Image.open(img_path).convert('RGB')
+        tensor = self.transform(img).unsqueeze(0).to(self.device)
+        cls_token = self._get_cls_feature(tensor)
+        return F.normalize(cls_token, dim=-1).squeeze(0)
+
+    @torch.no_grad()
+    def compute_similarity(self, img_path1, img_path2):
+        """计算两张图片的 DINOv2 CLS 特征余弦相似度（返回 0~1）"""
+        feat1 = self.extract_feature(img_path1)
+        feat2 = self.extract_feature(img_path2)
+        if feat1 is None or feat2 is None:
+            return None
+        sim = F.cosine_similarity(feat1.unsqueeze(0), feat2.unsqueeze(0))
+        return float(sim.item())

module/evaluator.py

@@ -0,0 +1,338 @@
+import os
+import traceback
+import numpy as np
+from datetime import datetime
+
+from module.file_manager import get_history_images, load_metadata, save_metadata
+from module.text_classifier import classify_scene
+from module.text_matcher import compare_text_scene, compare_text_scene_cached, compare_text_scene_pure_bge
+
+
+DINO_PRESCREEN_THRESHOLD = 0.3
+
+
+def evaluate_scene_consistency_cached(matcher, query_paths, username,
+                                       ocr_engine=None, bge_tokenizer=None,
+                                       bge_model=None, scene_type_q='complex',
+                                       qd_search_fn=None, dinov2_extractor=None,
+                                       precomputed_ocr_result=None,
+                                      precomputed_bge_vec=None,
+                                      qd_cache=None):
+    """Qdrant ANN 搜索管线: DINOv2/BGE 预筛 + MASt3R 精确判定 + 早停
+
+    流程 (与 test_5.ipynb 一致):
+    文本场景:
+      1. 提取查询图 OCR 文本 -> BGE 编码
+      2. Qdrant ANN 搜索 (BGE 向量) -> top-K 候选
+      3. 对候选逐一 compare_text_scene_pure_bge (纯BGE语义向量)
+      4. 早停: 匹配到同场景即跳过剩余
+    复杂场景:
+      1. 提取查询图 DINOv2 特征
+      2. Qdrant ANN 搜索 (DINOv2 向量) -> top-K 候选
+      3. DINOv2 预筛: 相似度 < 0.3 直接跳过 MASt3R
+      4. 通过预筛的候选 -> matcher.compare() (MASt3R 联合推理)
+      5. 早停: 匹配到同场景即跳过剩余
+    """
+    evaluation_logs = []
+    best_match_result = None
+    best_match_score = -1
+
+    import time as _t
+    for q_path in query_paths:
+        if scene_type_q == 'text' and bge_tokenizer is not None:
+            _et0 = _t.perf_counter()
+            if precomputed_ocr_result is not None:
+                full_text = ' '.join(line[1][0] for line in precomputed_ocr_result[0]) if (precomputed_ocr_result and precomputed_ocr_result[0]) else ''
+            else:
+                from module.text_matcher import extract_text
+                full_text, _ = extract_text(q_path, ocr_engine)
+            _et1 = _t.perf_counter()
+            if precomputed_bge_vec is not None:
+                q_vec = precomputed_bge_vec
+            else:
+                from module.qdrant_manager import _bge_encode
+                q_vec = _bge_encode(full_text, bge_tokenizer, bge_model)
+            _et2 = _t.perf_counter()
+            _qd_cache = qd_cache.get('text', {}) if (qd_cache and isinstance(qd_cache, dict)) else {}
+            if not _qd_cache:
+                from module.qdrant_manager import qdrant_query_scene
+                _qd_cache = qdrant_query_scene(username, 'text')
+            _et3 = _t.perf_counter()
+            hits = []
+            for _pid, _entry in _qd_cache.items():
+                _h_path = _entry.get('path', '')
+                if os.path.abspath(q_path) == os.path.abspath(_h_path):
+                    continue
+                if not os.path.exists(_h_path):
+                    continue
+                _h_vec = _entry.get('_vector', _entry.get('bge_vector', np.zeros(512, dtype=np.float32)))
+                _sim = float(np.dot(q_vec, _h_vec))
+                if _sim >= 0.3:
+                    hits.append((_sim, _pid, _entry))
+            hits.sort(key=lambda x: x[0], reverse=True)
+            hits = hits[:3]
+            print(f'  [TIME-EVAL] text_extract: {_et1-_et0:.3f}s  bge_encode: {_et2-_et1:.3f}s  qdrant_scroll: {_et3-_et2:.3f}s  python_search: {_t.perf_counter()-_et3:.3f}s  n_hits: {len(hits)}')
+
+            for score, pid, entry in hits:
+                h_path = entry.get('path', '')
+                if os.path.abspath(q_path) == os.path.abspath(h_path):
+                    continue
+                try:
+                    result = compare_text_scene_pure_bge(
+                        q_path, entry, ocr_engine, bge_tokenizer, bge_model,
+                        precomputed_text=full_text, precomputed_bge=q_vec
+                    )
+                    log_entry = {
+                        'query_image': os.path.basename(q_path),
+                        'history_image': entry.get('filename', ''),
+                        'query_path': q_path,
+                        'history_path': h_path,
+                        'scene_type': 'text',
+                        'doc_score1': 0.0,
+                        'doc_score2': 0.0,
+                        'similarity_score': result['similarity_score'],
+                        'match_count': result.get('match_count', 0),
+                        'raw_match_count': 0,
+                        'inlier_ratio': result.get('inlier_ratio', 0.0),
+                        'avg_confidence': result.get('avg_confidence', 0.0),
+                        'text_similarity': result.get('text_similarity'),
+                        'ssim_score': result.get('ssim_score'),
+                        'seal_bonus': result.get('seal_bonus'),
+                        'is_same_scene': result['is_same_scene'],
+                        'gamma_info': [],
+                        'bge_search_score': round(score, 4),
+                    }
+                except Exception as e:
+                    log_entry = {
+                        'query_image': os.path.basename(q_path),
+                        'history_image': entry.get('filename', ''),
+                        'query_path': q_path,
+                        'history_path': h_path,
+                        'scene_type': 'text',
+                        'doc_score1': 0.0, 'doc_score2': 0.0,
+                        'similarity_score': 0.0,
+                        'match_count': 0, 'raw_match_count': 0,
+                        'inlier_ratio': 0.0, 'avg_confidence': 0.0,
+                        'is_same_scene': False, 'gamma_info': [],
+                        'error': str(e),
+                    }
+                evaluation_logs.append(log_entry)
+
+                if log_entry['is_same_scene']:
+                    if log_entry['similarity_score'] > best_match_score:
+                        best_match_score = log_entry['similarity_score']
+                        best_match_result = log_entry.copy()
+                    print(f"  [早停] {os.path.basename(q_path)} 与 {log_entry['history_image']} 匹配为同场景, 跳过剩余比对")
+                    break
+                elif log_entry['similarity_score'] > best_match_score:
+                    best_match_score = log_entry['similarity_score']
+                    best_match_result = log_entry.copy()
+
+        elif scene_type_q == 'complex' and dinov2_extractor is not None:
+            from module.qdrant_manager import _dinov2_encode
+            q_vec = _dinov2_encode(q_path, dinov2_extractor)
+            if not isinstance(q_vec, np.ndarray):
+                q_vec = q_vec.cpu().numpy() if hasattr(q_vec, 'cpu') else np.array(q_vec, dtype=np.float32)
+            _qd_cache_c = qd_cache.get('complex', {}) if (qd_cache and isinstance(qd_cache, dict)) else {}
+            if not _qd_cache_c:
+                from module.qdrant_manager import qdrant_query_scene
+                _qd_cache_c = qdrant_query_scene(username, 'complex')
+            hits = []
+            for _pid, _entry in _qd_cache_c.items():
+                _h_path = _entry.get('path', '')
+                if os.path.abspath(q_path) == os.path.abspath(_h_path):
+                    continue
+                if not os.path.exists(_h_path):
+                    continue
+                _h_vec = _entry.get('_vector', np.zeros(384, dtype=np.float32))
+                _sim = float(np.dot(q_vec, _h_vec))
+                if _sim >= DINO_PRESCREEN_THRESHOLD:
+                    hits.append((_sim, _pid, _entry))
+            hits.sort(key=lambda x: x[0], reverse=True)
+            hits = hits[:3]
+
+            for score, pid, entry in hits:
+                h_path = entry.get('path', '')
+                if os.path.abspath(q_path) == os.path.abspath(h_path):
+                    continue
+                dino_sim = score
+
+                if dino_sim < DINO_PRESCREEN_THRESHOLD:
+                    log_entry = {
+                        'query_image': os.path.basename(q_path),
+                        'history_image': entry.get('filename', ''),
+                        'query_path': q_path,
+                        'history_path': h_path,
+                        'scene_type': 'complex',
+                        'doc_score1': 0.0, 'doc_score2': 0.0,
+                        'similarity_score': round(dino_sim, 4),
+                        'match_count': 0, 'raw_match_count': 0,
+                        'inlier_ratio': 0.0, 'avg_confidence': 0.0,
+                        'dinov2_similarity': round(dino_sim, 4),
+                        'is_same_scene': False, 'gamma_info': [],
+                        'mast3r_skipped': True,
+                        'dino_search_score': round(dino_sim, 4),
+                    }
+                else:
+                    try:
+                        result = matcher.compare(q_path, h_path, dinov2_sim_override=dino_sim)
+                        log_entry = {
+                            'query_image': os.path.basename(q_path),
+                            'history_image': entry.get('filename', ''),
+                            'query_path': q_path,
+                            'history_path': h_path,
+                            'scene_type': 'complex',
+                            'doc_score1': 0.0, 'doc_score2': 0.0,
+                            'similarity_score': result['similarity_score'],
+                            'match_count': result['match_count'],
+                            'raw_match_count': result['raw_match_count'],
+                            'inlier_ratio': result['inlier_ratio'],
+                            'avg_confidence': result['avg_confidence'],
+                            'mast3r_is_same': result.get('mast3r_is_same'),
+                            'dinov2_is_same': result.get('dinov2_is_same'),
+                            'dinov2_similarity': result.get('dinov2_similarity'),
+                            'is_same_scene': result['is_same_scene'],
+                            'gamma_info': result.get('gamma_info', []),
+                            'mast3r_skipped': False,
+                            'dino_search_score': round(dino_sim, 4),
+                        }
+                    except Exception as e:
+                        log_entry = {
+                            'query_image': os.path.basename(q_path),
+                            'history_image': entry.get('filename', ''),
+                            'query_path': q_path,
+                            'history_path': h_path,
+                            'scene_type': 'complex',
+                            'doc_score1': 0.0, 'doc_score2': 0.0,
+                            'similarity_score': 0.0,
+                            'match_count': 0, 'raw_match_count': 0,
+                            'inlier_ratio': 0.0, 'avg_confidence': 0.0,
+                            'is_same_scene': False, 'gamma_info': [],
+                            'error': str(e),
+                        }
+                evaluation_logs.append(log_entry)
+
+                if log_entry['is_same_scene']:
+                    if log_entry['similarity_score'] > best_match_score:
+                        best_match_score = log_entry['similarity_score']
+                        best_match_result = log_entry.copy()
+                    print(f"  [早停] {os.path.basename(q_path)} 与 {log_entry['history_image']} 匹配为同场景, 跳过剩余比对")
+                    break
+                elif log_entry['similarity_score'] > best_match_score:
+                    best_match_score = log_entry['similarity_score']
+                    best_match_result = log_entry.copy()
+
+    any_same = any(log['is_same_scene'] for log in evaluation_logs)
+    final_result = not any_same
+
+    return final_result, evaluation_logs, best_match_result
+
+
+def evaluate_scene_consistency(matcher, query_paths, history_paths,
+                               ocr_engine=None, bge_tokenizer=None, bge_model=None):
+    evaluation_logs = []
+    best_match_result = None
+    best_match_score = -1
+
+    for q_path in query_paths:
+        for h_path in history_paths:
+            if os.path.abspath(q_path) == os.path.abspath(h_path):
+                continue
+
+            try:
+                scene_type1, doc_score1, detail1 = 'complex', 0.0, {}
+                scene_type2, doc_score2, detail2 = 'complex', 0.0, {}
+                if ocr_engine is not None:
+                    scene_type1, doc_score1, detail1, _ = classify_scene(q_path, ocr_engine)
+                    scene_type2, doc_score2, detail2, _ = classify_scene(h_path, ocr_engine)
+
+                if scene_type1 == 'text' and scene_type2 == 'text' and bge_tokenizer is not None:
+                    result = compare_text_scene(
+                        q_path, h_path, ocr_engine, bge_tokenizer, bge_model
+                    )
+                    log_entry = {
+                        'query_image': os.path.basename(q_path),
+                        'history_image': os.path.basename(h_path),
+                        'query_path': q_path,
+                        'history_path': h_path,
+                        'scene_type': 'text',
+                        'doc_score1': doc_score1,
+                        'doc_score2': doc_score2,
+                        'similarity_score': result['similarity_score'],
+                        'match_count': result.get('match_count', 0),
+                        'raw_match_count': 0,
+                        'inlier_ratio': result.get('inlier_ratio', 0.0),
+                        'avg_confidence': result.get('avg_confidence', 0.0),
+                        'text_similarity': result.get('text_similarity'),
+                        'ssim_score': result.get('ssim_score'),
+                        'seal_bonus': result.get('seal_bonus'),
+                        'is_same_scene': result['is_same_scene'],
+                        'gamma_info': [],
+                    }
+                else:
+                    result = matcher.compare(q_path, h_path)
+                    log_entry = {
+                        'query_image': os.path.basename(q_path),
+                        'history_image': os.path.basename(h_path),
+                        'query_path': q_path,
+                        'history_path': h_path,
+                        'scene_type': 'complex',
+                        'doc_score1': doc_score1,
+                        'doc_score2': doc_score2,
+                        'similarity_score': result['similarity_score'],
+                        'match_count': result['match_count'],
+                        'raw_match_count': result['raw_match_count'],
+                        'inlier_ratio': result['inlier_ratio'],
+                        'avg_confidence': result['avg_confidence'],
+                        'mast3r_is_same': result.get('mast3r_is_same'),
+                        'dinov2_is_same': result.get('dinov2_is_same'),
+                        'dinov2_similarity': result.get('dinov2_similarity'),
+                        'is_same_scene': result['is_same_scene'],
+                        'gamma_info': result.get('gamma_info', []),
+                    }
+            except Exception as e:
+                log_entry = {
+                    'query_image': os.path.basename(q_path),
+                    'history_image': os.path.basename(h_path),
+                    'query_path': q_path,
+                    'history_path': h_path,
+                    'scene_type': 'unknown',
+                    'doc_score1': 0.0, 'doc_score2': 0.0,
+                    'similarity_score': 0.0,
+                    'match_count': 0, 'raw_match_count': 0,
+                    'inlier_ratio': 0.0, 'avg_confidence': 0.0,
+                    'is_same_scene': False, 'gamma_info': [],
+                    'error': str(e),
+                    'traceback': traceback.format_exc(),
+                }
+            evaluation_logs.append(log_entry)
+
+            if log_entry['is_same_scene']:
+                if log_entry['similarity_score'] > best_match_score:
+                    best_match_score = log_entry['similarity_score']
+                    best_match_result = log_entry.copy()
+                print(f"  [早停] {os.path.basename(q_path)} 与 {log_entry['history_image']} 匹配为同场景, 跳过剩余比对")
+                break
+            elif log_entry['similarity_score'] > best_match_score:
+                best_match_score = log_entry['similarity_score']
+                best_match_result = log_entry.copy()
+
+    any_same = any(log['is_same_scene'] for log in evaluation_logs)
+    final_result = not any_same
+
+    return final_result, evaluation_logs, best_match_result
+
+
+def update_metadata(user_dir, saved_info, per_image_results):
+    metadata = load_metadata(user_dir)
+    for original_name, save_path in saved_info:
+        img_result = per_image_results.get(save_path, '未知')
+        img_meta = {
+            'filename': os.path.basename(save_path),
+            'path': os.path.abspath(save_path),
+            'upload_time': datetime.now().strftime('%Y-%m-%d %H:%M:%S'),
+            'original_name': original_name,
+            'evaluation_result': img_result,
+        }
+        metadata['images'].append(img_meta)
+    save_metadata(user_dir, metadata)

module/file_manager.py

@@ -0,0 +1,81 @@
+import os
+import json
+from datetime import datetime
+
+from module.config import HISTORY_BASE_DIR, SUPPORTED_EXTENSIONS
+
+
+def validate_username(username):
+    """验证用户名合法性（非空、无非法字符、长度限制）"""
+    if not username or not username.strip():
+        raise ValueError('用户名不能为空')
+    username = username.strip()
+    invalid_chars = '<>:"/\\|?*'
+    for char in invalid_chars:
+        if char in username:
+            raise ValueError(f"用户名包含非法字符: '{char}'")
+    if len(username) > 50:
+        raise ValueError('用户名长度不能超过50个字符')
+    return username
+
+
+def get_user_dir(username):
+    """获取用户目录路径，若不存在则自动创建"""
+    user_dir = os.path.join(HISTORY_BASE_DIR, username)
+    os.makedirs(user_dir, exist_ok=True)
+    return user_dir
+
+
+def load_metadata(user_dir):
+    """从用户目录加载元数据JSON，文件不存在或损坏时返回空结构"""
+    metadata_path = os.path.join(user_dir, 'metadata.json')
+    if os.path.exists(metadata_path):
+        try:
+            with open(metadata_path, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            pass
+    return {'images': []}
+
+
+def save_metadata(user_dir, metadata):
+    """将元数据JSON写入用户目录"""
+    metadata_path = os.path.join(user_dir, 'metadata.json')
+    with open(metadata_path, 'w', encoding='utf-8') as f:
+        json.dump(metadata, f, ensure_ascii=False, indent=2)
+
+
+def generate_image_filename(original_name):
+    """生成带时间戳的唯一文件名，格式：时间戳_原始文件名"""
+    timestamp = datetime.now().strftime('%Y%m%d_%H%M%S_%f')
+    name, ext = os.path.splitext(original_name)
+    if ext.lower() not in SUPPORTED_EXTENSIONS:
+        ext = '.jpg'
+    return f'{timestamp}_{name}{ext}'
+
+
+def save_uploaded_file(file_data, original_name, user_dir):
+    """将上传的文件数据保存到用户目录，返回保存路径"""
+    filename = generate_image_filename(original_name)
+    save_path = os.path.join(user_dir, filename)
+    with open(save_path, 'wb') as f:
+        f.write(file_data)
+    return save_path
+
+
+def delete_file(path):
+    """删除指定路径的文件"""
+    if os.path.exists(path):
+        os.remove(path)
+
+
+def get_history_images(user_dir):
+    """扫描用户目录下所有支持格式的图片，返回按文件名排序的路径列表"""
+    images = []
+    if not os.path.exists(user_dir):
+        return images
+    for fname in sorted(os.listdir(user_dir)):
+        ext = os.path.splitext(fname)[1].lower()
+        if ext in SUPPORTED_EXTENSIONS:
+            images.append(os.path.join(user_dir, fname))
+    return images

module/image_utils.py

@@ -0,0 +1,22 @@
+import numpy as np
+import torch
+
+
+def apply_gamma_tensor(img_tensor, low=0.15, high=0.85, target=0.5):
+    """对图像张量进行Gamma校正，当亮度超出[low, high]范围时自动调整到target亮度"""
+    arr = img_tensor.detach().cpu().numpy()
+    arr = (arr * 0.5) + 0.5
+    arr = np.clip(arr.squeeze(0).transpose(1, 2, 0), 0.0, 1.0)
+
+    lum = float(np.dot(arr[..., :3], [0.299, 0.587, 0.114]).mean())
+
+    if low <= lum <= high:
+        return img_tensor, lum, False, 1.0
+
+    eps = 1e-6
+    gamma = np.log(target + eps) / np.log(lum + eps)
+    gamma = float(np.clip(gamma, 0.5, 2.5))
+
+    arr = np.clip(arr ** gamma, 0.0, 1.0)
+    tensor = torch.from_numpy(((arr - 0.5) / 0.5).transpose(2, 0, 1)).unsqueeze(0).float()
+    return tensor, lum, True, gamma

module/model_loader.py

@@ -0,0 +1,138 @@
+"""模型加载器 — CPU 部署版（无 MASt3R）
+
+保留 DINOv2 / PaddleOCR / BGE 加载逻辑，
+移除 MASt3R 加载（load_model 返回 None）。
+"""
+import os
+import sys
+import importlib
+import importlib.util
+
+# 屏蔽 tensorflow/jax 导入（transformers 间接依赖，与 numpy 1.x 不兼容）
+_original_find_spec = importlib.util.find_spec
+
+
+def _patched_find_spec(name, package=None):
+    _blocked = ('tensorflow', 'jax', 'jaxlib')
+    if name in _blocked or any(name.startswith(b + '.') for b in _blocked):
+        return None
+    return _original_find_spec(name, package)
+
+
+importlib.util.find_spec = _patched_find_spec
+
+import numpy as np
+
+# numpy 2.x 兼容补丁（imgaug 依赖 np.sctypes）
+if not hasattr(np, 'sctypes'):
+    np.sctypes = {
+        'int': [np.int8, np.int16, np.int32, np.int64],
+        'uint': [np.uint8, np.uint16, np.uint32, np.uint64],
+        'float': [np.float16, np.float32, np.float64],
+        'complex': [np.complex64, np.complex128],
+        'others': [bool, object, bytes, str, np.void],
+    }
+
+from module.config import DEVICE, BGE_MODEL_PATH
+
+_model = None
+_dinov2_extractor = None
+_ocr_engine = None
+_bge_tokenizer = None
+_bge_model = None
+
+
+def get_model():
+    return _model
+
+
+def get_dinov2():
+    global _dinov2_extractor
+    if _dinov2_extractor is None:
+        load_dinov2()
+    return _dinov2_extractor
+
+
+def get_ocr():
+    global _ocr_engine
+    if _ocr_engine is None:
+        load_ocr()
+    return _ocr_engine
+
+
+def get_bge():
+    global _bge_tokenizer, _bge_model
+    if _bge_tokenizer is None or _bge_model is None:
+        load_bge()
+    return _bge_tokenizer, _bge_model
+
+
+def load_model():
+    """MASt3R 已禁用（CPU 部署模式）"""
+    global _model
+    print("[INFO] MASt3R 已禁用（CPU 部署，使用 DINOv2-only 模式）")
+    _model = None
+    return _model
+
+
+def load_dinov2():
+    """加载 DINOv2 模型（vit_small_patch14_reg4_dinov2）"""
+    global _dinov2_extractor
+    if _dinov2_extractor is not None:
+        return _dinov2_extractor
+
+    from module.dinov2_utils import DINOv2Extractor
+    print("加载 DINOv2 模型...")
+    try:
+        _dinov2_extractor = DINOv2Extractor()
+        if not _dinov2_extractor.is_available:
+            _dinov2_extractor = None
+            print("DINOv2 不可用，复杂场景检测将无法工作")
+    except Exception as e:
+        _dinov2_extractor = None
+        print(f"DINOv2 加载异常: {e}")
+    return _dinov2_extractor
+
+
+def load_ocr():
+    """加载 PaddleOCR 引擎（CPU 模式）"""
+    global _ocr_engine
+    if _ocr_engine is not None:
+        return _ocr_engine
+
+    print("加载 PaddleOCR...")
+    try:
+        from paddleocr import PaddleOCR
+        _ocr_engine = PaddleOCR(
+            use_angle_cls=True,
+            lang='ch',
+        )
+        print("PaddleOCR 加载完成")
+    except Exception as e:
+        _ocr_engine = None
+        print(f"PaddleOCR 加载异常: {e}")
+        print("文本场景检测将不可用")
+    return _ocr_engine
+
+
+def load_bge():
+    """加载 BGE-small-zh 语义嵌入模型（从 HuggingFace Hub 下载）"""
+    global _bge_tokenizer, _bge_model
+    if _bge_tokenizer is not None and _bge_model is not None:
+        return _bge_tokenizer, _bge_model
+
+    print("加载 BGE-small-zh 模型...")
+    try:
+        from transformers import AutoTokenizer
+        from transformers.models.bert.modeling_bert import BertModel
+
+        _bge_tokenizer = AutoTokenizer.from_pretrained(BGE_MODEL_PATH)
+        _bge_model = BertModel.from_pretrained(BGE_MODEL_PATH)
+        _bge_model.eval()
+        print("BGE-small-zh 加载完成")
+    except Exception as e:
+        _bge_tokenizer = None
+        _bge_model = None
+        print(f"BGE-small-zh 加载异常: {e}")
+        print("文本语义比对将不可用")
+    return _bge_tokenizer, _bge_model

module/qdrant_manager.py

@@ -0,0 +1,240 @@
+"""Qdrant 向量数据库管理器 — 嵌入式模式（无需独立服务进程）
+
+使用 QdrantClient(path=...) 在本地文件系统中运行 Qdrant，
+适合 HF Spaces 单容器部署，无需额外启动 Qdrant 服务。
+"""
+import os
+import hashlib
+import uuid
+
+import numpy as np
+import torch
+from qdrant_client import QdrantClient
+from qdrant_client.models import (
+    Distance, VectorParams, PointStruct,
+    OptimizersConfigDiff, HnswConfigDiff,
+)
+
+from module.config import QDRANT_PATH
+from module.text_classifier import classify_scene
+
+COLL_PREFIX = 'user_'
+
+_client_instance = None
+
+
+def _get_client():
+    """获取 Qdrant 客户端单例（嵌入式本地文件模式）"""
+    global _client_instance
+    if _client_instance is None:
+        os.makedirs(QDRANT_PATH, exist_ok=True)
+        _client_instance = QdrantClient(path=QDRANT_PATH)
+    return _client_instance
+
+
+def pt_id(img_path):
+    """根据图片绝对路径生成确定性 UUID"""
+    return str(uuid.UUID(hex=hashlib.md5(os.path.abspath(img_path).encode()).hexdigest()))
+
+
+def _collection_name(username, scene_type):
+    return f'{COLL_PREFIX}{username}_{scene_type}'
+
+
+def _bge_encode(text, bge_tokenizer, bge_model):
+    """编码文本为 numpy float32[512]"""
+    if not text.strip():
+        return np.zeros(512, dtype=np.float32)
+    encoded = bge_tokenizer(text, padding=True, truncation=True, return_tensors='pt', max_length=512)
+    # CPU 模式：不调用 .cuda()
+    with torch.no_grad():
+        outputs = bge_model(**encoded)
+    emb = outputs.last_hidden_state[:, 0]
+    emb = torch.nn.functional.normalize(emb, p=2, dim=1)
+    return emb.cpu().numpy()[0]
+
+
+def _dinov2_encode(img_path, dinov2_extractor):
+    """提取 DINOv2 特征向量（384维）"""
+    if dinov2_extractor is None or not dinov2_extractor.is_available:
+        return np.zeros(384, dtype=np.float32)
+    feat = dinov2_extractor.extract_feature(img_path)
+    if feat is None:
+        return np.zeros(384, dtype=np.float32)
+    return feat.cpu().numpy()
+
+
+# ==================== 预存储: 构建用户缓存 ====================
+
+def build_user_cache(username, user_dir, ocr_engine, dinov2_extractor,
+                     bge_tokenizer, bge_model):
+    """为用户目录下所有历史图片构建 Qdrant 缓存"""
+    from module.file_manager import get_history_images
+    client = _get_client()
+    images = get_history_images(user_dir)
+    if not images:
+        return 0, 0
+
+    text_pts, complex_pts = [], []
+
+    for img_path in images:
+        try:
+            scene_type, doc_score, detail, ocr_result = classify_scene(img_path, ocr_engine)
+            pid = pt_id(img_path)
+            payload = {'path': img_path, 'filename': os.path.basename(img_path)}
+
+            if scene_type == 'text':
+                full_text = detail.get('full_text', '') if detail else ''
+                payload['ocr_text'] = full_text
+                vector = _bge_encode(full_text, bge_tokenizer, bge_model)
+                text_pts.append(PointStruct(id=pid, vector=vector.tolist(), payload=payload))
+            else:
+                vector = _dinov2_encode(img_path, dinov2_extractor)
+                complex_pts.append(PointStruct(id=pid, vector=vector.tolist(), payload=payload))
+
+            print(f"  [qdrant] {os.path.basename(img_path):<30s} {scene_type}")
+        except Exception as e:
+            print(f"  [qdrant] {os.path.basename(img_path)} ERROR: {e}")
+
+    for suffix, pts, dim in [('text', text_pts, 512), ('complex', complex_pts, 384)]:
+        if not pts:
+            continue
+        cname = _collection_name(username, suffix)
+        if client.collection_exists(cname):
+            client.delete_collection(cname)
+        client.create_collection(
+            cname,
+            vectors_config=VectorParams(size=dim, distance=Distance.COSINE),
+            optimizers_config=OptimizersConfigDiff(indexing_threshold=0),
+        )
+        client.upsert(cname, points=pts, wait=True)
+
+    for suffix in ['text', 'complex']:
+        cname = _collection_name(username, suffix)
+        if client.collection_exists(cname):
+            client.update_collection(cname, hnsw_config=HnswConfigDiff(m=16, ef_construct=100))
+
+    return len(text_pts), len(complex_pts)
+
+
+# ==================== 查询: 从 Qdrant 拉取缓存 ====================
+
+def qdrant_query_scene(username, scene_type):
+    """从 Qdrant 拉取指定场景类型的用户缓存（scroll 一次，返回 dict）"""
+    client = _get_client()
+    cache = {}
+    cname = _collection_name(username, scene_type)
+    if not client.collection_exists(cname):
+        return cache
+    records, _ = client.scroll(cname, limit=1000, with_payload=True, with_vectors=True)
+    for rec in records:
+        entry = dict(rec.payload)
+        entry['_vector'] = np.array(rec.vector, dtype=np.float32)
+        if scene_type == 'text':
+            entry['bge_vector'] = entry['_vector']
+        cache[rec.id] = entry
+    return cache
+
+
+# ==================== 向量相似度搜索 ====================
+
+def qdrant_search_similar(username, scene_type, query_vector, top_k=3, score_threshold=0.0):
+    client = _get_client()
+    cname = _collection_name(username, scene_type)
+    if not client.collection_exists(cname):
+        return []
+    response = client.query_points(
+        collection_name=cname,
+        query=query_vector.tolist(),
+        limit=top_k,
+        score_threshold=score_threshold,
+        with_payload=True,
+        with_vectors=True,
+    )
+    results = []
+    for hit in response.points:
+        entry = dict(hit.payload)
+        entry['_vector'] = np.array(hit.vector, dtype=np.float32)
+        if scene_type == 'text':
+            entry['bge_vector'] = entry['_vector']
+        results.append((hit.score, hit.id, entry))
+    return results
+
+
+# ==================== 增量更新 ====================
+
+def add_to_qdrant(username, img_path, ocr_engine, dinov2_extractor,
+                  bge_tokenizer, bge_model, scene_type=None,
+                  precomputed_text=None, precomputed_bge=None,
+                  precomputed_dinov2=None):
+    """将新图片添加到 Qdrant（增量插入）"""
+    client = _get_client()
+    if scene_type is None:
+        scene_type, _, _, _ = classify_scene(img_path, ocr_engine)
+    pid = pt_id(img_path)
+    payload = {'path': img_path, 'filename': os.path.basename(img_path)}
+
+    if scene_type == 'text':
+        if precomputed_text is not None:
+            full_text = precomputed_text
+        else:
+            from module.text_matcher import extract_text
+            full_text, _ = extract_text(img_path, ocr_engine)
+        payload['ocr_text'] = full_text
+        if precomputed_bge is not None:
+            vector = precomputed_bge
+        else:
+            vector = _bge_encode(full_text, bge_tokenizer, bge_model)
+        dim = 512
+    else:
+        if precomputed_dinov2 is not None:
+            vector = precomputed_dinov2
+        else:
+            vector = _dinov2_encode(img_path, dinov2_extractor)
+        dim = 384
+
+    cname = _collection_name(username, scene_type)
+    if not client.collection_exists(cname):
+        client.create_collection(
+            cname,
+            vectors_config=VectorParams(size=dim, distance=Distance.COSINE),
+            optimizers_config=OptimizersConfigDiff(indexing_threshold=0),
+        )
+        client.update_collection(cname, hnsw_config=HnswConfigDiff(m=16, ef_construct=100))
+
+    client.upsert(cname, points=[PointStruct(id=pid, vector=vector.tolist(), payload=payload)], wait=True)
+    return scene_type
+
+
+def remove_from_qdrant(username, img_path, scene_type=None):
+    """从 Qdrant 中移除指定图片"""
+    client = _get_client()
+    pid = pt_id(img_path)
+
+    if scene_type:
+        cname = _collection_name(username, scene_type)
+        if client.collection_exists(cname):
+            try:
+                client.delete(cname, points=[pid])
+            except Exception:
+                pass
+    else:
+        for st in ['text', 'complex']:
+            cname = _collection_name(username, st)
+            if client.collection_exists(cname):
+                try:
+                    client.delete(cname, points=[pid])
+                except Exception:
+                    pass
+
+
+def has_qdrant_cache(username):
+    """检查用户是否有 Qdrant 缓存"""
+    client = _get_client()
+    for st in ['text', 'complex']:
+        cname = _collection_name(username, st)
+        if client.collection_exists(cname):
+            count = client.count(cname).count
+            if count > 0:
+                return True
+    return False

module/scene_matcher.py

@@ -0,0 +1,64 @@
+"""场景匹配器 — DINOv2-only 模式（无 MASt3R）
+
+复杂场景判定改为纯 DINOv2 余弦相似度，不调用 MASt3R 3D 几何匹配。
+阈值由 config.DINOV2_ONLY_SAME_THRESHOLD 控制。
+"""
+import torch
+
+from module.config import DEVICE, DINOV2_ONLY_SAME_THRESHOLD
+
+
+class SceneMatcher:
+    """DINOv2-only 场景匹配器"""
+
+    def __init__(self, model=None, dinov2_extractor=None, device=None):
+        """初始化匹配器
+
+        Args:
+            model: 兼容参数，CPU 部署中始终为 None（无 MASt3R）
+            dinov2_extractor: DINOv2 特征提取器实例
+            device: 计算设备
+        """
+        self.model = model  # None（MASt3R 已禁用）
+        self.dinov2_extractor = dinov2_extractor
+        self.device = device or DEVICE
+
+    def compare(self, img_path1, img_path2, dinov2_sim_override=None):
+        """比对两张图片是否为同一场景（DINOv2-only）
+
+        Args:
+            img_path1: 查询图片路径
+            img_path2: 历史图片路径
+            dinov2_sim_override: 预计算的 DINOv2 相似度（避免重复提取）
+
+        Returns:
+            dict: 与原始 SceneMatcher.compare() 兼容的结果格式
+        """
+        # 获取 DINOv2 相似度
+        if dinov2_sim_override is not None:
+            dinov2_sim = float(dinov2_sim_override)
+        elif self.dinov2_extractor is not None:
+            try:
+                dinov2_sim = self.dinov2_extractor.compute_similarity(img_path1, img_path2)
+                if dinov2_sim is None:
+                    dinov2_sim = 0.0
+            except Exception:
+                dinov2_sim = 0.0
+        else:
+            dinov2_sim = 0.0
+
+        # DINOv2-only 判定
+        is_same = dinov2_sim >= DINOV2_ONLY_SAME_THRESHOLD
+
+        return {
+            'is_same_scene': bool(is_same),
+            'mast3r_is_same': None,  # MASt3R 已禁用
+            'dinov2_is_same': bool(is_same),
+            'similarity_score': round(float(dinov2_sim), 4),
+            'match_count': 0,
+            'raw_match_count': 0,
+            'inlier_ratio': 0.0,
+            'avg_confidence': 0.0,
+            'dinov2_similarity': round(float(dinov2_sim), 4),
+            'gamma_info': [],  # 无 Gamma 校正（MASt3R 专用）
+        }

module/system_monitor.py

@@ -0,0 +1,294 @@
+import os
+import threading
+import time
+import warnings
+import psutil
+import torch
+from datetime import datetime
+
+from module.config import LOGS_DIR
+
+
+def _snapshot():
+    """采集当前时刻的CPU、内存和GPU占用率"""
+    stats = {
+        'timestamp': datetime.now().strftime('%Y-%m-%d %H:%M:%S.%f')[:-3],
+        'cpu_percent': psutil.cpu_percent(interval=0),
+        'memory_percent': psutil.virtual_memory().percent,
+        'memory_used_gb': round(psutil.virtual_memory().used / (1024**3), 2),
+        'memory_total_gb': round(psutil.virtual_memory().total / (1024**3), 2),
+    }
+    if torch.cuda.is_available():
+        stats['gpu_memory_used_gb'] = round(torch.cuda.memory_allocated() / (1024**3), 2)
+        stats['gpu_memory_reserved_gb'] = round(torch.cuda.memory_reserved() / (1024**3), 2)
+        stats['gpu_memory_total_gb'] = round(torch.cuda.get_device_properties(0).total_memory / (1024**3), 2)
+        stats['gpu_memory_percent'] = round(
+            stats['gpu_memory_used_gb'] / stats['gpu_memory_total_gb'] * 100, 1
+        )
+        stats['gpu_util_percent'] = _get_gpu_util()
+    else:
+        stats['gpu_memory_percent'] = 0
+        stats['gpu_memory_used_gb'] = 0
+        stats['gpu_memory_reserved_gb'] = 0
+        stats['gpu_memory_total_gb'] = 0
+        stats['gpu_util_percent'] = 0
+    return stats
+
+
+def _get_gpu_util():
+    """获取GPU计算利用率（非显存占用），单例模式避免反复init/shutdown"""
+    if not _get_gpu_util._initialized:
+        try:
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore")
+                import pynvml as nvml_mod
+            nvml_mod.nvmlInit()
+            _get_gpu_util._nvml = nvml_mod
+            _get_gpu_util._handle = nvml_mod.nvmlDeviceGetHandleByIndex(0)
+            _get_gpu_util._initialized = True
+        except Exception:
+            return -1
+    try:
+        nvml_mod = _get_gpu_util._nvml
+        handle = _get_gpu_util._handle
+        util = nvml_mod.nvmlDeviceGetUtilizationRates(handle)
+        return util.gpu
+    except Exception:
+        return -1
+
+_get_gpu_util._initialized = False
+_get_gpu_util._nvml = None
+_get_gpu_util._handle = None
+
+
+class ResourceMonitor:
+    """后台资源监控器：在检测期间持续采样，追踪峰值"""
+
+    def __init__(self, sample_interval=0.5):
+        """初始化监控器"""
+        self.sample_interval = sample_interval
+        self._thread = None
+        self._stop_event = threading.Event()
+        self._samples = []
+        self._lock = threading.Lock()
+        self._peak = None  # 检测期间的峰值
+        self._monitoring = False
+
+    def start_monitoring(self):
+        """开始后台采样（检测开始前调用）"""
+        self._samples = []
+        self._peak = None
+        self._stop_event.clear()
+        self._monitoring = True
+        self._thread = threading.Thread(target=self._sample_loop, daemon=True)
+        self._thread.start()
+
+    def stop_monitoring(self):
+        """停止后台采样（检测结束后调用），返回检测期间的峰值统计"""
+        self._stop_event.set()
+        if self._thread:
+            self._thread.join(timeout=3)
+        self._monitoring = False
+
+        with self._lock:
+            if not self._samples:
+                return None
+            peak = self._compute_peak(self._samples)
+            self._peak = peak
+            return peak
+
+    @property
+    def is_monitoring(self):
+        return self._monitoring
+
+    def _sample_loop(self):
+        """后台采样循环"""
+        # 先做一次有interval的CPU采样来初始化psutil的基准值
+        psutil.cpu_percent(interval=0)
+        time.sleep(0.1)
+
+        while not self._stop_event.is_set():
+            sample = _snapshot()
+            with self._lock:
+                self._samples.append(sample)
+            self._stop_event.wait(self.sample_interval)
+
+    def _compute_peak(self, samples):
+        """从采样列表中计算峰值统计"""
+        if not samples:
+            return None
+
+        peak = {
+            'timestamp_start': samples[0]['timestamp'],
+            'timestamp_end': samples[-1]['timestamp'],
+            'sample_count': len(samples),
+            'duration_sec': round(len(samples) * self.sample_interval, 1),
+            'cpu_peak': max(s['cpu_percent'] for s in samples),
+            'cpu_avg': round(sum(s['cpu_percent'] for s in samples) / len(samples), 1),
+            'memory_peak_percent': max(s['memory_percent'] for s in samples),
+            'memory_peak_gb': max(s['memory_used_gb'] for s in samples),
+            'memory_avg_percent': round(sum(s['memory_percent'] for s in samples) / len(samples), 1),
+            'gpu_memory_peak_gb': max(s['gpu_memory_used_gb'] for s in samples),
+            'gpu_memory_peak_percent': max(s['gpu_memory_percent'] for s in samples),
+            'gpu_memory_avg_gb': round(sum(s['gpu_memory_used_gb'] for s in samples) / len(samples), 2),
+            'gpu_util_peak': max(s['gpu_util_percent'] for s in samples),
+            'gpu_util_avg': round(
+                sum(s['gpu_util_percent'] for s in samples if s['gpu_util_percent'] >= 0)
+                / max(1, sum(1 for s in samples if s['gpu_util_percent'] >= 0)),
+                1
+            ),
+        }
+        return peak
+
+
+def _compute_delta(before, after, label=""):
+    """计算两个快照之间的变化量"""
+    delta = {
+        'label': label,
+        'cpu_delta': round(after['cpu_percent'] - before['cpu_percent'], 1),
+        'memory_delta_gb': round(after['memory_used_gb'] - before['memory_used_gb'], 2),
+        'memory_delta_percent': round(after['memory_percent'] - before['memory_percent'], 1),
+        'gpu_memory_delta_gb': round(after['gpu_memory_used_gb'] - before['gpu_memory_used_gb'], 2),
+        'gpu_memory_delta_percent': round(after['gpu_memory_percent'] - before['gpu_memory_percent'], 1),
+    }
+    return delta
+
+
+def _compute_delta_pre_peak(pre_stats, peak, label=""):
+    """计算检测前快照与检测中峰值之间的变化量（展示检测的实际资源需求）"""
+    delta = {
+        'label': label,
+        'cpu_delta': round(peak['cpu_peak'] - pre_stats['cpu_percent'], 1),
+        'memory_delta_gb': round(peak['memory_peak_gb'] - pre_stats['memory_used_gb'], 2),
+        'memory_delta_percent': round(peak['memory_peak_percent'] - pre_stats['memory_percent'], 1),
+        'gpu_memory_delta_gb': round(peak['gpu_memory_peak_gb'] - pre_stats['gpu_memory_used_gb'], 2),
+        'gpu_memory_delta_percent': round(peak['gpu_memory_peak_percent'] - pre_stats['gpu_memory_percent'], 1),
+    }
+    return delta
+
+
+def format_stats_line(stats, label=""):
+    """将系统状态格式化为一行日志文本"""
+    parts = [
+        f"[{stats['timestamp']}]",
+        f"CPU: {stats['cpu_percent']}%",
+        f"内存: {stats['memory_used_gb']}/{stats['memory_total_gb']}GB ({stats['memory_percent']}%)",
+        f"GPU显存: {stats['gpu_memory_used_gb']}/{stats['gpu_memory_total_gb']}GB ({stats['gpu_memory_percent']}%)",
+    ]
+    if label:
+        parts.insert(1, f"[{label}]")
+    return " | ".join(parts)
+
+
+def format_peak_line(peak, label=""):
+    """将峰值统计格式化为日志文本"""
+    gpu_util_str = f"{peak['gpu_util_peak']}%" if peak['gpu_util_peak'] >= 0 else "N/A"
+    gpu_util_avg_str = f"{peak['gpu_util_avg']}%" if peak['gpu_util_avg'] >= 0 else "N/A"
+    lines = [
+        f"  采样数: {peak['sample_count']}, 时长: {peak['duration_sec']}s",
+        f"  CPU  峰值: {peak['cpu_peak']}%  均值: {peak['cpu_avg']}%",
+        f"  内存 峰值: {peak['memory_peak_gb']}GB ({peak['memory_peak_percent']}%)  均值: {peak['memory_avg_percent']}%",
+        f"  显存 峰值: {peak['gpu_memory_peak_gb']}GB ({peak['gpu_memory_peak_percent']}%)  均值: {peak['gpu_memory_avg_gb']}GB",
+        f"  GPU利用率 峰值: {gpu_util_str}  均值: {gpu_util_avg_str}",
+    ]
+    if label:
+        lines.insert(0, f"  [{label}]")
+    return "\n".join(lines)
+
+
+def format_delta_line(delta):
+    """将变化量格式化为日志文本"""
+    sign = lambda v: f"+{v}" if v > 0 else f"{v}"
+    lines = [
+        f"  [{delta['label']}]",
+        f"  CPU: {sign(delta['cpu_delta'])}%  "
+        f"内存: {sign(delta['memory_delta_gb'])}GB ({sign(delta['memory_delta_percent'])}%)  "
+        f"显存: {sign(delta['gpu_memory_delta_gb'])}GB ({sign(delta['gpu_memory_delta_percent'])}%)",
+    ]
+    return "\n".join(lines)
+
+
+def write_session_log(session_data):
+    """将会话日志写入Logs目录下的txt文件
+
+    session_data 结构:
+        startup_stats: 启动时快照
+        model_loaded_stats: 模型加载后快照
+        detections: 列表，每项包含:
+            pre_stats: 检测前快照
+            peak: 检测期间峰值
+            post_stats: 检测后快照
+            delta_pre_post: 检测前后变化量
+        shutdown_stats: 关闭时快照
+        delta_startup_shutdown: 启动到关闭总变化量
+    """
+    os.makedirs(LOGS_DIR, exist_ok=True)
+    timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
+    log_path = os.path.join(LOGS_DIR, f'session_{timestamp}.txt')
+
+    with open(log_path, 'w', encoding='utf-8') as f:
+        f.write("=" * 70 + "\n")
+        f.write("  MASt3R 场景一致性检测系统 - 运行日志\n")
+        f.write("=" * 70 + "\n\n")
+
+        # 1. 启动时资源
+        startup = session_data.get('startup_stats')
+        if startup:
+            f.write("--- ① 服务启动时 ---\n")
+            f.write(format_stats_line(startup, "启动") + "\n\n")
+
+        # 2. 模型加载后
+        model_loaded = session_data.get('model_loaded_stats')
+        if model_loaded and startup:
+            f.write("--- ② 模型加载后 ---\n")
+            f.write(format_stats_line(model_loaded, "加载后") + "\n")
+            delta = _compute_delta(startup, model_loaded, "模型加载增量")
+            f.write(format_delta_line(delta) + "\n\n")
+        elif model_loaded:
+            f.write("--- ② 模型加载后 ---\n")
+            f.write(format_stats_line(model_loaded, "加载后") + "\n\n")
+
+        # 3. 每次检测的详细记录
+        detections = session_data.get('detections', [])
+        if detections:
+            f.write("--- ③ 检测过程资源变化 ---\n")
+            for i, det in enumerate(detections, 1):
+                f.write(f"\n  ── 检测 #{i} ──\n")
+
+                pre = det.get('pre_stats')
+                peak = det.get('peak')
+                duration = det.get('duration_sec')
+
+                if duration is not None:
+                    f.write(f"  耗时: {duration:.1f}s\n")
+
+                if pre:
+                    f.write(f"  检测前: {format_stats_line(pre, '检测前').split('|', 1)[1].strip()}\n")
+
+                if peak:
+                    f.write(format_peak_line(peak, "检测中峰值") + "\n")
+
+                if pre and peak:
+                    delta = _compute_delta_pre_peak(pre, peak, f"检测#{i} 资源需求（前→峰值）")
+                    f.write(format_delta_line(delta) + "\n")
+
+            f.write("\n")
+
+        # 4. 服务关闭时
+        shutdown = session_data.get('shutdown_stats')
+        if shutdown:
+            f.write("--- ④ 服务关闭时 ---\n")
+            f.write(format_stats_line(shutdown, "关闭") + "\n")
+
+            if startup:
+                delta = _compute_delta(startup, shutdown, "全程总变化")
+                f.write(format_delta_line(delta) + "\n\n")
+
+        f.write("=" * 70 + "\n")
+        f.write(f"  日志生成时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
+        f.write("=" * 70 + "\n")
+
+        f.flush()
+        os.fsync(f.fileno())
+
+    return log_path

module/text_classifier.py

@@ -0,0 +1,158 @@
+"""场景分类器：多信号加权评分判断图片属于文本场景还是复杂场景
+
+综合以下4个信号：
+1. 文本面积占比（权重0.15）——OCR检测到的文本区域面积
+2. 背景白度占比（权重0.50）——浅色像素比例
+3. 颜色方差倒数（权重0.25）——颜色变化越小越可能是文档
+4. 文本行密度（权重0.10）——单位面积内文本行数
+"""
+
+import cv2
+import numpy as np
+
+from module.config import (
+    TEXT_AREA_WEIGHT, WHITENESS_WEIGHT, LOW_VARIANCE_WEIGHT,
+    LINE_DENSITY_WEIGHT, DOC_SCORE_THRESHOLD,
+)
+
+
+def _cv_imread(path, flags=cv2.IMREAD_COLOR):
+    """支持中文路径的cv2.imread"""
+    return cv2.imdecode(np.fromfile(path, dtype=np.uint8), flags)
+
+
+def _compute_whiteness(img, brightness_threshold=200):
+    """计算图片背景白度占比
+
+    白底文档的浅色像素（亮度>200）占比通常>60%
+
+    Args:
+        img: BGR格式的numpy数组
+        brightness_threshold: 亮度阈值，高于此值视为'白'
+    Returns:
+        whiteness: 白色像素占比，范围[0,1]
+    """
+    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    white_pixels = np.sum(gray >= brightness_threshold)
+    total_pixels = gray.shape[0] * gray.shape[1]
+    return white_pixels / total_pixels if total_pixels > 0 else 0.0
+
+
+def _compute_color_variance_norm(img):
+    """计算图片颜色方差的归一化值
+
+    文档图片（白底黑字）颜色方差低，场景照片颜色方差高
+    归一化到[0,1]，值越大表示颜色越丰富（越不像文档）
+
+    Args:
+        img: BGR格式的numpy数组
+    Returns:
+        variance_norm: 归一化颜色方差，范围[0,1]
+    """
+    variances = [np.var(img[:, :, c]) for c in range(3)]
+    avg_var = np.mean(variances)
+    # sigmoid归一化：方差2000约为0.5（经验值）
+    # 文档方差通常<500，场景照片方差通常>3000
+    variance_norm = 1.0 / (1.0 + np.exp(-(avg_var - 2000) / 800))
+    return float(variance_norm)
+
+
+def _compute_line_density(text_boxes, img_shape):
+    """计算文本行密度
+
+    即使文字分散，如果行数多，行密度仍然高
+    营业执照虽然文字分散，但行数多（10+行），密度不会太低
+
+    Args:
+        text_boxes: OCR检测到的文本框列表
+        img_shape: (h, w) 图片尺寸
+    Returns:
+        line_density: 归一化行密度，范围[0,1]
+    """
+    h, w = img_shape[:2]
+    if not text_boxes or h == 0 or w == 0:
+        return 0.0
+
+    # 行数 / 图片面积（以1000*1000为参考）
+    area_factor = (h * w) / (1000 * 1000)
+    if area_factor == 0:
+        return 0.0
+
+    raw_density = len(text_boxes) / area_factor
+    # sigmoid归一化：10行/百万像素约为0.5
+    density_norm = 1.0 / (1.0 + np.exp(-(raw_density - 10) / 5))
+    return float(density_norm)
+
+
+def classify_scene(image_path, ocr_engine, doc_score_threshold=DOC_SCORE_THRESHOLD,
+                   precomputed_ocr_result=None):
+    """多信号加权评分判断图片属于文本场景还是复杂场景
+
+    Args:
+        image_path: 图片路径
+        ocr_engine: PaddleOCR引擎实例
+        doc_score_threshold: 文档场景判定阈值，默认0.55
+        precomputed_ocr_result: 预计算的OCR结果，避免重复OCR
+
+    Returns:
+        scene_type: 'text'(文本场景) 或 'complex'(复杂场景)
+        doc_score: 文档评分
+        detail: 各信号的详细分数字典
+        ocr_result: OCR原始结果（可复用给下游）
+    """
+    img = _cv_imread(image_path)
+    if img is None:
+        return 'complex', 0.0, {}, None
+
+    h, w = img.shape[:2]
+
+    if precomputed_ocr_result is not None:
+        result = precomputed_ocr_result
+    else:
+        result = ocr_engine.ocr(image_path, cls=True)
+
+    text_area = 0
+    text_boxes = []
+    full_text = ''
+    if result and result[0]:
+        for line in result[0]:
+            box = line[0]
+            text_boxes.append(box)
+            n = len(box)
+            area = 0
+            for i in range(n):
+                j = (i + 1) % n
+                area += box[i][0] * box[j][1]
+                area -= box[j][0] * box[i][1]
+            text_area += abs(area) / 2
+        full_text = ' '.join(line[1][0] for line in result[0])
+
+    total_area = h * w
+    text_area_ratio = text_area / total_area if total_area > 0 else 0
+
+    whiteness = _compute_whiteness(img)
+
+    variance_norm = _compute_color_variance_norm(img)
+    low_variance = 1.0 - variance_norm
+
+    line_density = _compute_line_density(text_boxes, img.shape)
+
+    doc_score = (
+        TEXT_AREA_WEIGHT * text_area_ratio
+        + WHITENESS_WEIGHT * whiteness
+        + LOW_VARIANCE_WEIGHT * low_variance
+        + LINE_DENSITY_WEIGHT * line_density
+    )
+
+    scene_type = 'text' if doc_score >= doc_score_threshold else 'complex'
+
+    detail = {
+        'text_area_ratio': round(text_area_ratio, 4),
+        'whiteness': round(whiteness, 4),
+        'low_variance': round(low_variance, 4),
+        'line_density': round(line_density, 4),
+        'text_box_count': len(text_boxes),
+        'full_text': full_text,
+    }
+
+    return scene_type, round(doc_score, 4), detail, result

module/text_matcher.py

@@ -0,0 +1,458 @@
+"""文本场景比对管线：OCR提取 + 语义嵌入 + SSIM结构比对 + 印章/手写检测"""
+
+import time
+import cv2
+import numpy as np
+import torch
+from skimage.metrics import structural_similarity as ssim
+
+from module.config import (
+    TEXT_SIM_WEIGHT, SSIM_WEIGHT, SEAL_WEIGHT, TEXT_SCENE_THRESHOLD,
+    TEXT_SCENE_BGE_THRESHOLD,
+)
+
+
+def _cv_imread(path, flags=cv2.IMREAD_COLOR):
+    """支持中文路径的cv2.imread"""
+    return cv2.imdecode(np.fromfile(path, dtype=np.uint8), flags)
+
+
+# ==================== OCR文字提取 ====================
+
+def extract_text(image_path, ocr_engine):
+    """使用PaddleOCR提取图片中的全部文字
+
+    Args:
+        image_path: 图片路径
+        ocr_engine: PaddleOCR引擎实例
+
+    Returns:
+        full_text: 拼接后的完整文本
+        text_lines: 每行文字的列表（含置信度）
+    """
+    result = ocr_engine.ocr(image_path, cls=True)
+
+    text_lines = []
+    if result and result[0]:
+        for line in result[0]:
+            text = line[1][0]
+            conf = line[1][1]
+            text_lines.append({'text': text, 'confidence': float(conf)})
+
+    full_text = ' '.join([t['text'] for t in text_lines])
+    return full_text, text_lines
+
+
+# ==================== 语义嵌入比对 ====================
+
+def compute_text_similarity(text1, text2, bge_tokenizer, bge_model):
+    """使用BGE-small-zh计算两段文本的语义相似度
+
+    Args:
+        text1, text2: 待比较的两段文本
+        bge_tokenizer: BGE分词器实例
+        bge_model: BGE模型实例
+
+    Returns:
+        similarity: 余弦相似度，范围[0,1]
+    """
+    if not text1.strip() or not text2.strip():
+        return 0.0
+
+    def _encode(text):
+        """编码单段文本为归一化向量"""
+        encoded = bge_tokenizer(text, padding=True, truncation=True, return_tensors='pt', max_length=512)
+        if torch.cuda.is_available():
+            encoded = {k: v.cuda() for k, v in encoded.items()}
+        with torch.no_grad():
+            outputs = bge_model(**encoded)
+        cls_embedding = outputs.last_hidden_state[:, 0]
+        cls_embedding = torch.nn.functional.normalize(cls_embedding, p=2, dim=1)
+        return cls_embedding.cpu().numpy()
+
+    emb1 = _encode(text1)
+    emb2 = _encode(text2)
+
+    sim = float(np.dot(emb1[0], emb2[0]))
+    return sim
+
+
+# ==================== SSIM结构比对 ====================
+
+def compute_ssim(image_path1, image_path2):
+    """计算两张图片的SSIM结构相似度
+
+    将图片缩放到相同尺寸后转为灰度计算SSIM
+
+    Returns:
+        ssim_score: SSIM值，范围[0,1]
+    """
+    img1 = _cv_imread(image_path1)
+    img2 = _cv_imread(image_path2)
+
+    if img1 is None or img2 is None:
+        return 0.0
+
+    h = min(img1.shape[0], img2.shape[0])
+    w = min(img1.shape[1], img2.shape[1])
+    img1 = cv2.resize(img1, (w, h))
+    img2 = cv2.resize(img2, (w, h))
+
+    gray1 = cv2.cvtColor(img1, cv2.COLOR_BGR2GRAY)
+    gray2 = cv2.cvtColor(img2, cv2.COLOR_BGR2GRAY)
+
+    score, _ = ssim(gray1, gray2, full=True)
+    return float(score)
+
+
+# ==================== 印章/手写检测 ====================
+
+def detect_seals_and_handwriting(image_path, min_area_ratio=0.001):
+    """检测图片中的红色印章和手写笔迹区域
+
+    印章检测原理：HSV颜色空间中提取红色区域
+
+    Args:
+        image_path: 图片路径
+        min_area_ratio: 最小区域面积占比，过滤噪声
+
+    Returns:
+        seals: 印章区域列表，每项含 {'bbox', 'area', 'area_ratio'}
+        seal_total_ratio: 印章总面积占比
+    """
+    img = _cv_imread(image_path)
+    if img is None:
+        return [], 0.0
+
+    h, w = img.shape[:2]
+    total_area = h * w
+
+    # --- 印章检测：HSV红色区域 ---
+    hsv = cv2.cvtColor(img, cv2.COLOR_BGR2HSV)
+
+    # 红色在HSV中有两段：0-10 和 160-180
+    mask1 = cv2.inRange(hsv, np.array([0, 70, 50]), np.array([10, 255, 255]))
+    mask2 = cv2.inRange(hsv, np.array([160, 70, 50]), np.array([180, 255, 255]))
+    red_mask = cv2.bitwise_or(mask1, mask2)
+
+    # 形态学操作去噪
+    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
+    red_mask = cv2.morphologyEx(red_mask, cv2.MORPH_CLOSE, kernel, iterations=2)
+    red_mask = cv2.morphologyEx(red_mask, cv2.MORPH_OPEN, kernel, iterations=1)
+
+    # 查找轮廓
+    contours, _ = cv2.findContours(red_mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+
+    seals = []
+    min_area = total_area * min_area_ratio
+    for cnt in contours:
+        area = cv2.contourArea(cnt)
+        if area >= min_area:
+            x, y, bw, bh = cv2.boundingRect(cnt)
+            seals.append({
+                'bbox': (x, y, bw, bh),
+                'area': int(area),
+                'area_ratio': round(area / total_area, 4),
+            })
+
+    seal_total_ratio = sum(s['area_ratio'] for s in seals)
+    return seals, round(seal_total_ratio, 4)
+
+
+def compare_seals(seals1, seals2):
+    """比对两张图的印章区域
+
+    比较逻辑：
+    - 两张图都有印章 → 比较数量和面积占比差异
+    - 一张有一张无 → 印章不匹配
+    - 两张都无 → 印章项跳过
+
+    Returns:
+        match: bool或None，印章是否匹配（None表示两张都无印章）
+        detail: 详细信息字典
+    """
+    has_seal1 = len(seals1) > 0
+    has_seal2 = len(seals2) > 0
+    ratio1 = sum(s['area_ratio'] for s in seals1)
+    ratio2 = sum(s['area_ratio'] for s in seals2)
+
+    detail = {
+        'img1_seal_count': len(seals1),
+        'img2_seal_count': len(seals2),
+        'img1_seal_ratio': round(ratio1, 4),
+        'img2_seal_ratio': round(ratio2, 4),
+    }
+
+    if not has_seal1 and not has_seal2:
+        return None, detail
+
+    if has_seal1 != has_seal2:
+        detail['reason'] = '一张有印章一张无'
+        return False, detail
+
+    # 两张都有印章：比较数量和面积
+    count_match = len(seals1) == len(seals2)
+    ratio_diff = abs(ratio1 - ratio2)
+    area_match = ratio_diff < 0.02
+
+    match = count_match and area_match
+    detail['count_match'] = count_match
+    detail['area_diff'] = round(ratio_diff, 4)
+    detail['area_match'] = area_match
+
+    return match, detail
+
+
+def compare_text_scene_cached(image_path, cached_h, ocr_engine,
+                               bge_tokenizer, bge_model,
+                               precomputed_text=None, precomputed_bge=None):
+    """文本场景缓存比对: 仅实时 OCR/BGE/Seal 查询图，历史图从缓存读取
+
+    Args:
+        image_path: 查询图片路径
+        cached_h: 预存储的历史图缓存 dict (ocr_text, bge_vector, seal_count, seal_ratio)
+        ocr_engine: PaddleOCR引擎
+        bge_tokenizer: BGE分词器
+        bge_model: BGE模型
+
+    Returns:
+        result dict (与 compare_text_scene() 兼容的格式)
+    """
+    start_time = time.time()
+
+    # 1. OCR 仅查询图 (优先使用预计算结果)
+    if precomputed_text is not None:
+        text1 = precomputed_text
+        lines1 = []
+        ocr_time = 0.0
+    else:
+        text1, lines1 = extract_text(image_path, ocr_engine)
+        ocr_time = time.time() - start_time
+    text2 = cached_h.get('ocr_text', '')
+
+    # 2. 语义嵌入 (优先使用预计算向量)
+    if precomputed_bge is not None:
+        emb_q = precomputed_bge
+        emb_h = cached_h.get('bge_vector', np.zeros(512, dtype=np.float32))
+        text_sim = float(np.dot(emb_q, emb_h)) if text1.strip() else 0.0
+        embed_time = 0.0
+    elif not text1.strip():
+        text_sim = 0.0
+        embed_time = 0.0
+    else:
+        t_embed = time.time()
+        def _encode_q(text):
+            encoded = bge_tokenizer(text, padding=True, truncation=True,
+                                     return_tensors='pt', max_length=512)
+            if torch.cuda.is_available():
+                encoded = {k: v.cuda() for k, v in encoded.items()}
+            with torch.no_grad():
+                outputs = bge_model(**encoded)
+            cls_embedding = outputs.last_hidden_state[:, 0]
+            cls_embedding = torch.nn.functional.normalize(cls_embedding, p=2, dim=1)
+            return cls_embedding.cpu().numpy()[0]
+
+        emb_q = _encode_q(text1)
+        emb_h = cached_h.get('bge_vector', np.zeros(512, dtype=np.float32))
+        text_sim = float(np.dot(emb_q, emb_h))
+        embed_time = time.time() - t_embed
+
+    # 3. SSIM 仍需两张图
+    t_ssim = time.time()
+    ssim_score = compute_ssim(image_path, cached_h['path'])
+    ssim_time = time.time() - t_ssim
+
+    # 4. 印章：仅查询图（历史图用缓存）
+    t_seal = time.time()
+    seals_q, ratio_q = detect_seals_and_handwriting(image_path)
+    cnt_h = cached_h.get('seal_count', 0)
+    ratio_h = cached_h.get('seal_ratio', 0.0)
+
+    has_q, has_h = len(seals_q) > 0, cnt_h > 0
+    if not has_q and not has_h:
+        seal_bonus = 0.5
+    elif has_q != has_h:
+        seal_bonus = 0.0
+    else:
+        count_match = len(seals_q) == cnt_h
+        area_match = abs(ratio_q - ratio_h) < 0.02
+        seal_bonus = 1.0 if (count_match and area_match) else 0.0
+    seal_time = time.time() - t_seal
+
+    # 5. 综合判定
+    final_score = text_sim * TEXT_SIM_WEIGHT + ssim_score * SSIM_WEIGHT + seal_bonus * SEAL_WEIGHT
+    is_same = final_score >= TEXT_SCENE_THRESHOLD
+
+    total_time = time.time() - start_time
+
+    result = {
+        'is_same_scene': bool(is_same),
+        'scene_type': 'text',
+        'final_score': round(final_score, 4),
+        'text_similarity': round(text_sim, 4),
+        'ssim_score': round(ssim_score, 4),
+        'seal_bonus': seal_bonus,
+        'seal_match': None if (not has_q and not has_h) else (has_q and has_h),
+        'seal_detail': {
+            'img1_seal_count': len(seals_q), 'img2_seal_count': cnt_h,
+            'img1_seal_ratio': ratio_q, 'img2_seal_ratio': ratio_h,
+        },
+        'img1_text_length': len(text1), 'img2_text_length': len(text2),
+        'img1_seal_count': len(seals_q), 'img2_seal_count': cnt_h,
+        'img1_seal_ratio': ratio_q, 'img2_seal_ratio': ratio_h,
+        'similarity_score': round(final_score, 4),
+        'match_count': len(seals_q) + cnt_h,
+        'inlier_ratio': round(text_sim, 4),
+        'avg_confidence': round(ssim_score, 4),
+        'time_breakdown': {
+            'ocr': round(ocr_time, 2), 'embedding': round(embed_time, 2),
+            'ssim': round(ssim_time, 2), 'seal': round(seal_time, 2),
+            'total': round(total_time, 2),
+        },
+    }
+
+    return result
+
+
+
+
+
+def compare_text_scene_pure_bge(image_path, cached_h, ocr_engine,
+                                 bge_tokenizer, bge_model,
+                                 precomputed_text=None, precomputed_bge=None):
+    """Pure BGE: only OCR->BGE cosine similarity, no SSIM/seal"""
+    start_time = time.time()
+    print(f'  [TIME-PURE-BGE] enter, precomputed_text={precomputed_text is not None}, precomputed_bge={precomputed_bge is not None}')
+
+    if precomputed_text is not None:
+        text1 = precomputed_text
+        ocr_time = 0.0
+    else:
+        text1, _ = extract_text(image_path, ocr_engine)
+        ocr_time = time.time() - start_time
+
+    if precomputed_bge is not None:
+        emb_q = precomputed_bge
+        emb_h = cached_h.get('_vector', cached_h.get('bge_vector', np.zeros(512, dtype=np.float32)))
+        text_sim = float(np.dot(emb_q, emb_h)) if text1.strip() else 0.0
+        embed_time = 0.0
+    elif not text1.strip():
+        text_sim = 0.0
+        embed_time = 0.0
+    else:
+        t_embed = time.time()
+        def _encode_q(text):
+            encoded = bge_tokenizer(text, padding=True, truncation=True,
+                                     return_tensors='pt', max_length=512)
+            if torch.cuda.is_available():
+                encoded = {k: v.cuda() for k, v in encoded.items()}
+            with torch.no_grad():
+                outputs = bge_model(**encoded)
+            cls_embedding = outputs.last_hidden_state[:, 0]
+            cls_embedding = torch.nn.functional.normalize(cls_embedding, p=2, dim=1)
+            return cls_embedding.cpu().numpy()[0]
+        emb_q = _encode_q(text1)
+        emb_h = cached_h.get('_vector', cached_h.get('bge_vector', np.zeros(512, dtype=np.float32)))
+        text_sim = float(np.dot(emb_q, emb_h))
+        embed_time = time.time() - t_embed
+
+    is_same = text_sim >= TEXT_SCENE_BGE_THRESHOLD
+    total_time = time.time() - start_time
+    print(f'  [TIME-PURE-BGE] text_sim={text_sim:.4f} is_same={is_same} total={total_time:.3f}s')
+
+    result = {
+        'is_same_scene': bool(is_same),
+        'scene_type': 'text',
+        'final_score': round(text_sim, 4),
+        'text_similarity': round(text_sim, 4),
+        'ssim_score': 0.0,
+        'seal_bonus': 0.0,
+        'similarity_score': round(text_sim, 4),
+        'match_count': 0,
+        'inlier_ratio': round(text_sim, 4),
+        'avg_confidence': 0.0,
+        'time_breakdown': {
+            'ocr': round(ocr_time, 2), 'embedding': round(embed_time, 2),
+            'ssim': 0.0, 'seal': 0.0, 'total': round(total_time, 2),
+        },
+    }
+    return result
+
+# ==================== 综合判定 ====================
+
+def compare_text_scene(image_path1, image_path2, ocr_engine, bge_tokenizer, bge_model):
+    """文本场景比对主函数
+
+    Args:
+        image_path1: 第一张图片路径
+        image_path2: 第二张图片路径
+        ocr_engine: PaddleOCR引擎实例
+        bge_tokenizer: BGE分词器实例
+        bge_model: BGE模型实例
+
+    Returns:
+        result: dict，含各项分数和最终判定
+    """
+    start_time = time.time()
+
+    # 1. OCR文字提取
+    text1, lines1 = extract_text(image_path1, ocr_engine)
+    text2, lines2 = extract_text(image_path2, ocr_engine)
+    ocr_time = time.time() - start_time
+
+    # 2. 语义嵌入比对
+    text_sim = compute_text_similarity(text1, text2, bge_tokenizer, bge_model)
+    embed_time = time.time() - start_time - ocr_time
+
+    # 3. SSIM结构比对
+    ssim_score = compute_ssim(image_path1, image_path2)
+    ssim_time = time.time() - start_time - ocr_time - embed_time
+
+    # 4. 印章检测与比对
+    seals1, seal_ratio1 = detect_seals_and_handwriting(image_path1)
+    seals2, seal_ratio2 = detect_seals_and_handwriting(image_path2)
+    seal_match, seal_detail = compare_seals(seals1, seals2)
+    seal_time = time.time() - start_time - ocr_time - embed_time - ssim_time
+
+    # 5. 综合判定
+    if seal_match is True:
+        seal_bonus = 1.0
+    elif seal_match is False:
+        seal_bonus = 0.0
+    else:
+        seal_bonus = 0.5  # 两张图都没有印章，中性
+
+    final_score = text_sim * TEXT_SIM_WEIGHT + ssim_score * SSIM_WEIGHT + seal_bonus * SEAL_WEIGHT
+    is_same = final_score >= TEXT_SCENE_THRESHOLD
+
+    total_time = time.time() - start_time
+
+    result = {
+        'is_same_scene': bool(is_same),
+        'scene_type': 'text',
+        'final_score': round(final_score, 4),
+        'text_similarity': round(text_sim, 4),
+        'ssim_score': round(ssim_score, 4),
+        'seal_bonus': seal_bonus,
+        'seal_match': seal_match,
+        'seal_detail': seal_detail,
+        'img1_text_length': len(text1),
+        'img2_text_length': len(text2),
+        'img1_seal_count': len(seals1),
+        'img2_seal_count': len(seals2),
+        'img1_seal_ratio': seal_ratio1,
+        'img2_seal_ratio': seal_ratio2,
+        'similarity_score': round(final_score, 4),
+        'match_count': len(seals1) + len(seals2),  # 文本场景用印章数代替
+        'inlier_ratio': round(text_sim, 4),
+        'avg_confidence': round(ssim_score, 4),
+        'time_breakdown': {
+            'ocr': round(ocr_time, 2),
+            'embedding': round(embed_time, 2),
+            'ssim': round(ssim_time, 2),
+            'seal': round(seal_time, 2),
+            'total': round(total_time, 2),
+        },
+    }
+
+    return result

requirements.txt

@@ -0,0 +1,30 @@
+# ============================================
+# HF Spaces CPU 部署依赖（无 MASt3R）
+# ============================================
+
+# Web 服务
+fastapi
+uvicorn
+python-multipart
+
+# 向量数据库（嵌入式模式）
+qdrant-client
+
+# 图像处理
+opencv-python-headless
+Pillow
+scikit-image
+
+# DINOv2 (vit_small_patch14_reg4_dinov2)
+timm
+
+# OCR + 语义嵌入（CPU 版 paddlepaddle）
+paddlepaddle==2.6.2
+paddleocr<3
+transformers
+
+# 系统监控
+psutil
+
+# 数据处理（锁定 1.x 避免 2.x 兼容问题）
+numpy<2