Ataque Black-Hole en la recuperación de bases de datos vectoriales

Este repositorio contiene la implementación que acompaña al artículo Black-Hole Attack from Embedding Space Defects. El Ataque Black-Hole explota un defecto geométrico en los espacios de embeddings de alta dimensión —la hubness impulsada por la centralidad— para envenenar bases de datos vectoriales: un pequeño número de vectores maliciosos inyectados cerca de los centroides de los clústeres se convierten en los vecinos más cercanos para una gran fracción de las consultas de los usuarios, sin requerir ningún conocimiento de dichas consultas.

Requisitos

• Python ≥ 3.10
• FAISS (se recomienda GPU: faiss-gpu; CPU: faiss-cpu)
• NumPy, Pandas, PyArrow (para E/S de parquet)
• scikit-learn, tqdm
• PyTorch y Transformers (solo necesarios para scripts/encode_*.py; el propio pipeline del ataque no importa torch)

Instalar las dependencias principales:

pip install numpy pandas pyarrow scikit-learn tqdm faiss-gpu

Inicio rápido

1. Descargar y preparar los datos

# Download BEIR datasets
bash scripts/download_data.sh

# Encode to vectors + build FAISS indexes
bash scripts/process_data.sh

Edita los arrays MODELS y DATASETS en cada script para seleccionar modelos o conjuntos de datos específicos.

2. Ejecutar un ataque básico

# Full-Export Attack on HotpotQA with Contriever
python run.py --model contriever --src hotpotqa

Esto ejecuta el pipeline completo: cargar vectores → agrupar → generar vectores adversarios → inyectar → construir índice envenenado → evaluar MO@10, ASR, FPR.

3. Argumentos clave

Flag	Predeterminado	Descripción
--model / --src	contriever / hotpotqa	Modelo de embedding y conjunto de datos de origen
--mode	default	default (mismo conjunto de datos) o transfer (entre conjuntos de datos)
--preprocess	default	default, query_trans o multi_query_transfer
--cluster	kmeans	kmeans, minibatch_kmeans, faiss_gpu
--num-copies / --epsilon	10 / 0.001	Número de copias perturbadas por centroide; magnitud de la perturbación
--eval-k / --sample-queries	10 / 3000	Evaluación top‑k; número de consultas muestreadas
--eval-index-types	FlatIP	Tipos de índice a evaluar: FlatIP, HNSW, IVF, IVFPQ
--eval-runners	evaluate	Pasos de evaluación: evaluate, evaluate_recall, evaluate_defense, evaluate_defense_performance_loss, evaluate_mitigation_defense, evaluate_mitigation_performance_loss
--result-subdir	auto	Subdirectorio bajo data/result/ para el JSON de salida

Rutas de ataque

Las cuatro rutas de ataque descritas en el artículo corresponden a las siguientes invocaciones:

Ruta	Comando
(1) Exportación completa de la base de datos	python run.py --mode default --preprocess default
(2) Exportación parcial de la base de datos	Exportar externamente una fracción de los vectores antes del agrupamiento; el resto del pipeline es idéntico a (1)
(3) Ataque con conjunto de datos sustituto	python run.py --mode transfer --preprocess multi_query_transfer --victim <dataset>
(4) Envenenamiento de conjuntos de datos públicos pre‑embebidos	Modificar los archivos .npy de un conjunto de datos pre‑embebido y volver a subirlo a HuggingFace

Para (3), el atacante construye vectores maliciosos a partir de consultas de todos los demás conjuntos de datos y los inyecta en la víctima. Los archivos .npy de consultas para los conjuntos de datos de origen sustitutos deben estar presentes en data/vector/.

Evaluación de defensa

Para ejecutar la defensa basada en detección:

python run.py --model contriever --src hotpotqa \
    --eval-runners evaluate_defense evaluate_defense_performance_loss

Para la defensa basada en mitigación (uno o más métodos):

python run.py --model contriever --src hotpotqa \
    --eval-runners evaluate_mitigation_defense evaluate_mitigation_performance_loss \
    --mitigation-methods cl2 zn nohub

Demostración

demo/ contiene un ejemplo mínimo autocontenido que construye una pequeña base de conocimiento a partir de un conjunto de datos BEIR, la codifica, inyecta vectores maliciosos y mide el impacto a nivel de recuperación. Utiliza su propio requirements.txt y no depende de src/. Consulte demo/src/main.py para obtener detalles sobre la CLI.

Conjuntos de datos y modelos

config.json define los modelos compatibles (contriever, bge, gte) y los conjuntos de datos (14 benchmarks BEIR). Para añadir un nuevo modelo, amplíe config.json y asegúrese de que los archivos de vectores .npy existan en data/vector/<model>_<dataset>.npy.

Citación

@misc{li2026trustvectorsvectordatabase,
      title={Can You Trust the Vectors in Your Vector Database? Black-Hole Attack from Embedding Space Defects}, 
      author={Hanxi Li and Jianan Zhou and Jiale Lao and Yibo Wang and Zhengmao Ye and Yang Cao and Junfen Wang and Mingjie Tang},
      year={2026},
      eprint={2604.05480},
      archivePrefix={arXiv},
      primaryClass={cs.CR},
      url={https://arxiv.org/abs/2604.05480}, 
}