ReasoningNER: A Reasoning Paradigm for Named Entity Recognition

This repository is the official implementation of the paper "A Reasoning Paradigm for Named Entity Recognition (accepted by AAAI 2026)".

In this project, we propose a novel reasoning paradigm for Named Entity Recognition (NER) that shifts the modeling approach from traditional implicit pattern matching to an explicit, verifiable reasoning process.

Our model, ReasoningNER, is trained through three stages: Chain-of-Thought (CoT) Generation, CoT Tuning, and Reasoning Enhancement.

Experiments show that this paradigm significantly improves the model's generalization ability and data efficiency in zero-shot, few-shot, and cross-domain scenarios.

---

Table of Contents

• Model Architecture

• Performance

• How to Use

• Dataset Preparation

• Stage 1: CoT Tuning (CT)

• Stage 2: Reasoning Enhancement (RE)

Model Architecture

The core idea of ReasoningNER is to inject explicit reasoning capabilities into Large Language Models (LLMs) through a three-stage process.

1. CoT Generation: We first construct a high-quality NER-CoT dataset, where each entity annotation is accompanied by a detailed, step-by-step reasoning chain.

2. CoT Tuning: We use the NER-CoT dataset to perform Supervised Fine-Tuning (SFT) on a base language model, teaching it to generate a coherent reasoning process before predicting the final entities.

3. Reasoning Enhancement: After fine-tuning, we employ a reinforcement learning algorithm (GRPO) to further optimize the model's reasoning policy. Using a composite reward function (including F1 score and Schema compliance), we incentivize the model to generate more accurate and reliable reasoning paths.

Performance

How to Use

Requirements

The following hardware and software environment was used in our experiments. Only the key dependencies are listed.

Hardware

Component	Configuration
GPU	8 × NVIDIA A800 80GB
CPU	2 × Intel Xeon Platinum 8358 @ 2.60GHz (64 physical cores / 128 threads)
Memory	1 TiB
Architecture	x86_64
Operating system	Ubuntu 22.04
CUDA	12.4 (system environment)

Key software versions

Package	Version
Python	3.12
PyTorch	2.8.0+cu128
Transformers	4.57.1
Accelerate	1.12.0
Datasets	4.4.1
DeepSpeed	0.18.2
FlashAttention	2.8.3
Liger Kernel	0.6.4
PEFT	0.18.0
SGLang	0.5.5.post3
Triton	3.4.0
vLLM	0.9.1
verl	0.6.0

The installed PyTorch wheel is built with CUDA 12.8 (cu128), while the system CUDA toolkit used on our machine is 12.4. TRL is required for grpo.py, and verl is required only when using the alternative RE pipeline below.

Dataset Preparation

Before starting the training, please prepare the necessary datasets.

• NER-CoT Dataset: The complete dataset is available on Hugging Face at the following link: https://huggingface.co/datasets/HuiHuang/NER-CoT.

• InstructUIE: The InstructUIE dataset can be downloaded from the following address: https://github.com/BeyonderXX/InstructUIE

Stage 1: CoT Tuning (CT)

This stage corresponds to Supervised Fine-Tuning. You can start the training by running the following script (sft.py):

accelerate launch \
    --config_file config/accelerate_config/deepspeed_zero3.yaml \
    sft.py \
    --config config/sft/qwen3-8b.yaml \
    --task auto

Stage 2: Reasoning Enhancement (RE)

After completing CoT tuning, use the RE script (grpo.py) to further optimize the model through reinforcement learning:

1. Sample from the InstructUIE dataset.

python sample_grpo.py \
  --base_path IE_INSTRUCTION \
  --data_format instruct_uie \
  --task ner \
  --dataset_config config/dataset/in_domain.json \
  --output_path data/trl-grpo \
  --num_samples 5000 \
  --max_count 10000 \
  --shuffle

2. Deploy vLLM to accelerate GRPO training.

CUDA_VISIBLE_DEVICES=7 python -m trl.scripts.vllm_serve \
    --model outputs/qwen3-8b-sft \
    --tensor_parallel_size 1 \
    --data_parallel_size 1 \
    --port 5407 \
    --enable_prefix_caching

3. Start the GRPO training process.

CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6 accelerate launch \
    --config_file config/accelerate_config/deepspeed_zero3.yaml \
    --num_processes 7 \
    grpo.py \
    --config config/grpo/qwen3-8b.yaml \
    --use_soft_f1 true

---

💡 [Update] Alternative RE using verl

We later found that training for more epochs using the verl framework can further improve performance. Therefore, we have updated the code to include the usage of verl.

1. Sample verl training data:

   python sample_grpo.py \
     --base_path IE_INSTRUCTION \
     --data_format instruct_uie \
     --task ner \
     --dataset_config config/dataset/in_domain.json \
     --output_path data/verl \
     --save_to_verl \
     --soft_f1

2. verl training script:

   bash verl-grpo.sh

   You can modify the parameter configurations in verl-grpo.sh as needed.

3. Weight Conversion: To convert the verl-trained weights into Hugging Face format, you can use the official script: https://github.com/volcengine/verl/blob/main/scripts/legacy_model_merger.py

---

Evaluation

python evaluate.py \
  --model outputs/qwen3-8b-grpo \
  --base_path IE_INSTRUCTION \
  --data_format instruct_uie \
  --task ner \
  --dataset_config config/dataset/cross_ner.json \
  --result_file eval_result.json \
  --template qwen3

---

💡 [Update] Unified Information Extraction Support

We have extended ReasoningNER to support Unified Information Extraction (UIE). The updated code now supports named entity recognition (ner), relation extraction (re), event detection (ed), and event argument extraction (eae) under the same SFT and GRPO training pipeline. The original NER protocol remains compatible.

The main newly added arguments are:

• --task {ner,re,ed,eae,all} selects one task or automatically traverses all four task directories.
• --data_format {auto,instruct_uie,b2nerd} selects the dataset layout. InstructUIE uses a common root directory and appends the task directory automatically. B2NERD is NER-only and uses NER_en by default.
• --dataset_subset optionally changes the B2NERD subset, for example NER_zh.
• --soft_f1 enables Soft-F1 metadata for verl data, while use_soft_f1: true enables the Soft-F1 reward in the TRL GRPO configuration. Both paths use the same 10:1 extraction/validity reward: two empty collections receive Soft-F1 1, exactly one empty collection receives 0, and invalid structured outputs receive 0 from both components. Strict F1 remains the default evaluation metric.

For mixed UIE sampling or evaluation, pass the dataset root, --task all, and a task-keyed dataset configuration:

python sample_grpo.py \
  --base_path /path/to/IE_INSTRUCTION \
  --data_format instruct_uie \
  --task all \
  --dataset_config config/dataset/in_domain.json \
  --output_path data/trl-grpo \
  --num_samples 5769 \
  --shuffle

config/dataset/in_domain.json is task-keyed and excludes the source datasets used by the main zero-shot/OOD evaluation. Sampling is exact and deterministic for a fixed seed, and is balanced first by dataset and then by the task-specific semantic category.

python evaluate.py \
  --model outputs/qwen3-8b-grpo \
  --base_path /path/to/IE_INSTRUCTION \
  --data_format instruct_uie \
  --task all \
  --dataset_config config/dataset/instruct_uie_ood.json \
  --result_file eval_uie_result.json \
  --template qwen3

Cite

@inproceedings{huang2026reasoning,
  title={A reasoning paradigm for named entity recognition},
  author={Huang, Hui and Chen, Yanping and Huang, Ruizhang and Lin, Chuan and Qin, Yongbin},
  booktitle={Proceedings of the AAAI Conference on Artificial Intelligence},
  volume={40},
  number={37},
  pages={31140--31148},
  year={2026}
}