Ataque Black-Hole em Recuperação de Bancos de Dados Vetoriais

Este repositório contém a implementação que acompanha o artigo Black-Hole Attack from Embedding Space Defects. O Ataque Black-Hole explora um defeito geométrico em espaços de embedding de alta dimensão — a hubness impulsionada pela centralidade — para envenenar bancos de dados vetoriais: um pequeno número de vetores maliciosos injetados próximos aos centroides dos clusters torna-se os vizinhos mais próximos para uma grande fração das consultas dos usuários, sem exigir qualquer conhecimento dessas consultas.

Requisitos

• Python ≥ 3.10
• FAISS (GPU recomendado: faiss-gpu; CPU: faiss-cpu)
• NumPy, Pandas, PyArrow (para I/O de parquet)
• scikit-learn, tqdm
• PyTorch e Transformers (necessários apenas para scripts/encode_*.py; o próprio pipeline de ataque não importa torch)

Instale as dependências principais:

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

Início rápido

1. Baixar e preparar os dados

# Download BEIR datasets
bash scripts/download_data.sh

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

Edite os arrays MODELS e DATASETS em cada script para selecionar modelos ou conjuntos de dados específicos.

2. Executar um ataque básico

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

Isso executa o pipeline completo: carregar vetores → agrupar → gerar vetores adversariais → injetar → construir índice envenenado → avaliar MO@10, ASR, FPR.

3. Argumentos principais

Flag	Padrão	Descrição
--model / --src	contriever / hotpotqa	Modelo de embedding e conjunto de dados de origem
--mode	default	default (mesmo conjunto de dados) ou transfer (entre conjuntos de dados)
--preprocess	default	default, query_trans ou multi_query_transfer
--cluster	kmeans	kmeans, minibatch_kmeans, faiss_gpu
--num-copies / --epsilon	10 / 0.001	Número de cópias perturbadas por centroide; magnitude da perturbação
--eval-k / --sample-queries	10 / 3000	Avaliação top‑k; número de consultas amostradas
--eval-index-types	FlatIP	Tipos de índice a avaliar: FlatIP, HNSW, IVF, IVFPQ
--eval-runners	evaluate	Etapas de avaliação: evaluate, evaluate_recall, evaluate_defense, evaluate_defense_performance_loss, evaluate_mitigation_defense, evaluate_mitigation_performance_loss
--result-subdir	auto	Subdiretório sob data/result/ para o JSON de saída

Caminhos de ataque

Os quatro caminhos de ataque descritos no artigo correspondem às seguintes invocações:

Caminho	Comando
(1) Exportação Completa do Banco de Dados	python run.py --mode default --preprocess default
(2) Exportação Parcial do Banco de Dados	Exportar uma fração dos vetores externamente antes do agrupamento; o restante do pipeline é idêntico ao (1)
(3) Ataque com Conjunto de Dados Substituto	python run.py --mode transfer --preprocess multi_query_transfer --victim <dataset>
(4) Envenenamento de Conjuntos de Dados Públicos Pré‑Embedded	Modificar os arquivos .npy de um conjunto de dados pré‑embedded e reenviar para o HuggingFace

Para (3), o atacante constrói vetores maliciosos a partir de consultas de todos os outros conjuntos de dados e os injeta na vítima. Os arquivos .npy de consulta para os conjuntos de dados de origem substitutos devem estar presentes em data/vector/.

Avaliação de defesa

Para executar a defesa baseada em detecção:

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

Para a defesa baseada em mitigação (um ou mais métodos):

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

Demonstração

demo/ contém um exemplo mínimo autocontido que constrói uma pequena base de conhecimento a partir de um conjunto de dados BEIR, codifica-a, injeta vetores maliciosos e mede o impacto ao nível da recuperação. Utiliza o seu próprio requirements.txt e não depende de src/. Consulte demo/src/main.py para obter detalhes sobre a CLI.

Conjuntos de dados e modelos

config.json define os modelos suportados (contriever, bge, gte) e os conjuntos de dados (14 benchmarks BEIR). Para adicionar um novo modelo, estenda config.json e certifique-se de que os ficheiros de vetores .npy existem em data/vector/<model>_<dataset>.npy.

Citação

@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}, 
}