AdaCoAgentEA

November 10, 2025 ยท View on GitHub

language-python3 made-with-Pytorch Contributions Welcome

English | ็ฎ€ไฝ“ไธญๆ–‡

๐Ÿš€ Welcome to the repo of AdaCoAgentEA! ๐ŸŽ‰๐ŸŽ‰๐ŸŽ‰

The source code for the ICDE 2025 paper: Towards Unsupervised Entity Alignment for Highly Heterogeneous Knowledge Graphs.

๐Ÿ  Overview

Highly Heterogeneous Entity Alignment (HHEA) represents a realistic yet challenging scenario of Entity Alignment (EA), aiming to align equivalent entities between Highly Heterogeneous Knowledge Graphs (HHKGs) with significant differences in structure, scale, and overlap. In practice, the scarcity of labeled data necessitates research into unsupervised HHEA, which faces critical challenges:

  • Difficulty in capturing structural/semantic associations between HHKGs
  • Absence of explicit alignment paradigms for HHEA
  • High computational and time costs

To bridge the gap, AdaCoAgentEA proposes the first unsupervised solution for HHEA through multi-agent collaboration:

โœจ Core Innovations

  1. Pioneering Unsupervised HHEA Research

    • First formal analysis and solution for unsupervised HHEA, establishing foundational methodologies for this emerging field.

  2. Novel and Effective Unsupervised HHEA Framework๏ผš Multi-Agent Adaptive Framework

    • Novel collaboration architecture with 3 functional areas combining LLMs and small models
    • Eliminates labeled data dependency while capturing cross-HHKG structural/semantic correlations

  3. Unsupervised HHEA Optimization Techniques๏ผš Meta-Alignment & Communication Protocols

    • Meta-expert role-playing: Enhances background knowledge specialization
    • Multi-granularity meta-logic symbol rules: Abstracts complex HHEA scenarios into executable paradigms
    • Efficient protocols: Improve agent interaction efficiency, reducing computational overhead

โšก Key Advantages

  • Breakthrough Performance: Achieves up to 62.3% relative Hits@1 gains across 5 benchmarks, surpassing supervised SOTA models (98%+ Hits@1 on ICEWS-WIKI)
  • Task-Generalized Design: Validated on both HHEA and classic EA tasks with consistent superiority
  • Resource-Efficient: Reduces time and token costs by up to 94.5% compared to baseline methods
  • Plug-and-Play Architecture: Enables rapid replacement of LLM/small-model agents with minimal code adjustments

๐Ÿ“ˆ Validated through extensive experiments, AdaCoAgentEA establishes new state-of-the-art performance in both unsupervised HHEA and classic EA tasks, offering a practical paradigm for applications with HHKGs.

๐Ÿ— Architecture

(The complete architectural diagrams and interaction details are presented in Section III of the paper.)

๐Ÿ“บ Demo Video

Official Demo Video1
(Baidu Netdisk, 720p, Extraction Code: 64rk)

Official Demo Video2
(OneDrive)

๐Ÿ”จ Main Dependencies

  • Python>=3.7 (tested on Python=3.8.10)
  • Pytorch
  • Transformers
  • Scipy
  • Pandas
  • Tqdm
  • Numpy

๐Ÿ“ฆ Installation

It's compatible with python 3.

  1. Create a virtualenv (optional)
conda create -n AdaCoAgentEA python=3.8.10
conda activate AdaCoAgentEA
  1. Install the dependencies
pip install 'Main Dependencies'

โœจ Datasets

The datasets are from Dual-AMN, JAPE, GCN-Align, Simple-HHEA and BETA.

Take the dataset icews_wiki (HHEA) as an example, the folder "data/icews_wiki" contains:

  • ent_ids_1: ids for entities in source KG;
  • ent_ids_2: ids for entities in target KG;
  • triples_1: relation triples encoded by ids in source KG;
  • triples_2: relation triples encoded by ids in target KG;
  • rel_ids_1: relation ids in the source KG;
  • rel_ids_2: relation ids in the target KG;
  • time_id: time ids in the source KG and the target KG;
  • ref_ent_ids: all aligned entity pairs, list of pairs like (e_s \t e_t);

๐Ÿ”ฅ One-Click Launch

  1. Clone the repository
git clone https://github.com/eduzrh/AdaCoAgentEA.git
cd AdaCoAgentEA
  1. Run the main experiment (without ablation)

The retriever_document_path refers to the KG2 which has deleted part of the information of the URL, leaving only the name.

python main.py --data DATASET

DATASET can be icews_wiki, icews_yago, BETA or any dataset you place in the directory data.

Note that the training set in the dataset is not used, i.e., no labelled data is used.

๐Ÿงช Ablation Experiments

We provide various ablation settings to analyze the contribution of different components in our framework.

Ablation Categories

1๏ธโƒฃ Ablation 1: Single Small Model-based Agent

Tests the combination of LLM Agents with a single small model-based Agent.

ParameterDescription
S1Use only LLM Agents with small model-based Agent 1
S2*Use only LLM Agents with small model-based Agent 2
S3*Use only LLM Agents with small model-based Agent 3
S4*Use only LLM Agents with small model-based Agent 4

*Note: Options S2, S3, and S4 will cause the framework to fail because they lack necessary preconditions.

2๏ธโƒฃ Ablation 2: LLM + Small Model-based Agent Combinations

Tests the combination of a single LLM with a single small model-based Agent.

ParameterDescription
LLM1_S1Use only LLM1 and small model-based Agent 1
LLM2_S1Use only LLM2 and small model-based Agent 1
LLM3_S1Use only LLM3 and small model-based Agent 1
DomainExperts_S1Use only Domain Experts (LLM4) and small model-based Agent 1
and other combinationsSee code for complete list

*Note: Combinations without S1 will cause the framework to fail because they lack necessary preconditions.

3๏ธโƒฃ Ablation 3: Component Removal Analysis

Evaluates the importance of specific agents by removing them from the framework.

ParameterDescription
no_LLM1Remove LLM1 agent
no_LLM2Remove LLM2 agent
no_LLM3Remove LLM3 agent
no_DomainExpertsRemove Domain Expert agents
no_S1*Remove small model-based agent 1
no_S2Remove small model-based agent 2
no_S3Remove small model-based agent 3
no_S4Remove small model-based agent 4

*Note: The no_S1 option will cause the framework to fail because small model-based agent 1 is a necessary precondition.

Example Commands

# Run Ablation 1 (using only S1)
python main.py --data icews_wiki --ablation1 S1

# Run Ablation 2 (using only LLM1 and Stage 1)
python main.py --data icews_wiki --ablation2 LLM1_S1

# Run Ablation 3 (remove LLM3)
python main.py --data icews_wiki --ablation3 no_LLM3

Important Notes

  1. Only one ablation category can be run at a time.
  2. Certain configurations will cause the framework to fail as noted above.

Troubleshooting

If you encounter errors:

  • "Error: Only one ablation category can be selected at a time."
    Solution: Ensure you specify only one ablation experiment category parameter.

  • Data path errors
    Solution: Ensure data is placed in the correct location: ./AdaCoAgent/data/[data_name].

๐ŸŒ Contact Information

๐Ÿ“ข If you have any questions or feedback about this project, please feel free to contact us. We highly appreciate your suggestions!

We will respond to all questions within 2-3 business days.

๐Ÿ“œ License

GPL-3.0

๐Ÿ”— References

Acknowledgement
The following open source projects were partially referenced in this work. We sincerely appreciate their contributions:
Dual-AMN, JAPE, GCN-Align, Simple-HHEA, BETA, Dual-Match, Faiss, NetworkX

Happy Coding ๐ŸŒž๏ธ