Skip to content
GY-JeongPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

Repository files navigation

STEAM: A Semantic-Level Knowledge Editing Framework for Large Language Models

Official repository for STEAM, accepted at Findings of EMNLP 2025. [Paper] [arXiv]

Locate-and-edit methods tend to store an edited fact as an isolated residual stream that is disconnected from the knowledge the model already has about the new object. STEAM collects reference triples of the new object from Wikidata, uses their representations as semantic anchors, and adds an alignment loss that pulls the representation of the edited fact toward the anchors while the edit is optimized. STEAM is a plug-in for existing editors; this repository applies it to ROME and R-ROME (single editing) and PMET (batch editing).

Repository structure

STEAM/
├── data/
│   ├── counterfact_plus.json          # CounterFact+ (edit requests + portability questions)
│   ├── counterfact_1000.json          # 1,000 CounterFact edits used for the latent-space analysis
│   └── reference_triples/             # Wikidata reference triples (semantic anchors), per model
├── data_construction/                 # Wikidata pipeline that builds data/reference_triples
├── editing/                           # Editing + evaluation code (based on the PMET / MEMIT code base)
│   ├── rome_original/ r_rome/ pmet/   # Baseline editors
│   ├── steam_rome/ steam_r_rome/ steam_pmet/   # STEAM applied to each editor
│   ├── hparams/                       # Hyperparameters per editor and model
│   ├── evaluate.py  summarize.py
│   └── scripts/                       # Scripts for the main experiments
└── visualization/                     # Latent-space analysis (PCA of residual streams, cosine similarity)

Setup

conda create -n steam python=3.10
conda activate steam
pip install -r requirements.txt

Llama 3 is a gated model; set HF_TOKEN in the environment to download it.

1. Reference triples (semantic anchors)

The reference triples used in the paper are included in data/reference_triples/ (counterfact_plus_{gpt-j-6b,llama3-8b,qwen2-7b}.json.gz, counterfact_1000_{gpt-j-6b,gpt2-xl}.json.gz). Each file is a list with one entry per new object entity:

{"object": "Adobe", "object_id": "Q11463", "survival_rate": 38.1, "recalled_fact_cnt": 336,
 "recalled_fact": [{"subject": "...", "subject_id": "...", "relation": "developer", "relation_id": "P178",
                    "prediction_prob": 0.93, "prompt": "... is a product of"}, ...]}

To rebuild them (or build them for another dataset / model):

cd data_construction

# Step 1. Query Wikidata for triples (s, r, o*) whose object o* is a new target of the dataset.
#         Relations and their prompt templates are listed in relation_dict.json.
python collect_wikidata_triples.py \
    --input ../data/counterfact_plus.json \
    --output outputs/counterfact_plus_triples.json \
    --limit 500

# Step 2. Keep the triples the unedited model already knows: a triple is kept if greedy
#         decoding from one of its prompts reproduces o*.
python filter_recalled_triples.py \
    --model_name EleutherAI/gpt-j-6B \
    --input outputs/counterfact_plus_triples.json \
    --output outputs/counterfact_plus_gpt-j-6b.json

# Step 3. Compress it into the data directory read by the editing / visualization code.
gzip -c outputs/counterfact_plus_gpt-j-6b.json > ../data/reference_triples/counterfact_plus_gpt-j-6b.json.gz

Wikidata changes over time, so newly collected triples may differ slightly from the released files.

2. Knowledge editing

All commands are run from editing/. Results are written to editing/results/<ALG>/trial_<k>/run_batch_<num_edits>_..., one JSON file per edit.

cd editing

# Single editing: ROME + STEAM on GPT-J
python evaluate.py --alg_name STEAM_ROME --model_name EleutherAI/gpt-j-6B \
    --hparams_fname gpt-j-6b.json --ds_name cf-plus --num_edits 1 \
    --lambda_weight 5 --knowledge_cnt 64 --alignment_start 13 --alignment_end 18

# Batch editing: PMET + STEAM on GPT-J, 100 edits at once
python evaluate.py --alg_name STEAM_PMET --model_name EleutherAI/gpt-j-6B \
    --hparams_fname gpt-j-6b.json --ds_name cf-plus --num_edits 100
Argument Description
--alg_name ROME, R-ROME, PMET, STEAM_ROME, STEAM_R_ROME, STEAM_PMET
--model_name EleutherAI/gpt-j-6B, meta-llama/Meta-Llama-3-8B, Qwen/Qwen2-7B
--hparams_fname File in hparams/<alg_name>/ (gpt-j-6b.json, meta-llama_Llama-3-8B.json, Qwen_Qwen2-7B.json)
--lambda_weight Weight λ of the alignment loss (paper: 5)
--knowledge_cnt Max. number of anchors per edit, sampled stratified by relation (paper: 64)
--alignment_start, --alignment_end Hidden states [start, end) used by the alignment loss (paper: 13–17)
--num_edits Number of edits applied at once (batch editing)
--trial Results of each trial are stored separately (the paper averages three runs)

Edits whose new object has fewer than 32 anchors are skipped, which leaves 816 (GPT-J), 931 (Qwen2) and 937 (Llama 3) CounterFact+ edits. scripts/run_single_editing.sh and scripts/run_batch_editing.sh run the full single and batch editing experiments.

ROME, R-ROME and PMET need second-moment statistics of the edited layers (editing/data/stats). The statistics for GPT-J are downloaded automatically from the MEMIT server; for the other models they are computed from Wikipedia on the first run, which takes several hours.

Summarizing results

python summarize.py --dir_name STEAM_ROME/trial_1 --model_name gpt-j

This reports Efficacy (post_rewrite_success), Paraphrase (post_paraphrase_success), Neighborhood (post_neighborhood_success), Portability (port_acc), the Edit score (edit_score, harmonic mean of the four), Fluency (post_ngram_entropy) and Consistency (post_reference_score).

3. Latent-space analysis

visualization/ reproduces the analysis of how edited knowledge is placed relative to the model's existing knowledge (Figures 1, 4, 5 and 6). It reuses the editors in editing/.

cd visualization

# Figure 4 from the precomputed similarities (ROME or STEAM, GPT-J or GPT-2 XL)
python plot_cosine_similarity.py --sim_dir precomputed/rome/gpt-j-6B --model_name gpt-j-6B
python plot_cosine_similarity.py --sim_dir precomputed/steam_rome/gpt-j-6B --model_name gpt-j-6B

# Recompute the similarities on counterfact_1000 and draw the 3D PCA plots of the edits in case_ids.json
python latent_analysis.py --alg_name ROME --model_name EleutherAI/gpt-j-6B --plot_3d
python latent_analysis.py --alg_name STEAM_ROME --model_name EleutherAI/gpt-j-6B --plot_3d
python plot_cosine_similarity.py --sim_dir outputs/steam_rome/gpt-j-6B --model_name gpt-j-6B

For each edit, latent_analysis.py takes the mean residual stream of the anchors of the new object and computes its layer-wise cosine similarity with the residual stream of the edit prompt before and after editing. With --plot_3d, it also writes an interactive 3D PCA plot (pca.html) of the anchors, the edited fact and the original fact across layers. For GPT-2 XL, --alignment_start 25 --alignment_end 35 --lambda_weight 3 were used.

Acknowledgement

The editing code is based on PMET, MEMIT, ROME and R-ROME. CounterFact+ is taken from EasyEdit, and the reference triples are collected from Wikidata.

Citation

@inproceedings{jeong-etal-2025-steam,
    title = "{STEAM}: A Semantic-Level Knowledge Editing Framework for Large Language Models",
    author = "Jeong, Geunyeong and Sun, Juoh and Lee, Seonghee and Kim, Harksoo",
    booktitle = "Findings of the Association for Computational Linguistics: EMNLP 2025",
    year = "2025",
    pages = "11008--11023",
    url = "https://aclanthology.org/2025.findings-emnlp.585/"
}

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages