QuCo-RAG: 사전 학습 코퍼스에서 불확실성 정량화 기반 동적 검색 증강 생성

논문 공식 구현 (ACL Findings 2026 채택 🎉):

QuCo-RAG: Quantifying Uncertainty from the Pre-training Corpus for Dynamic Retrieval-Augmented Generation
Dehai Min, Kailin Zhang, Tongtong Wu, Lu Cheng

Findings of the Association for Computational Linguistics: ACL 2026

QuCo-RAG는 모델 내부 신호(예: logits, entropy)에 의존하기보다 사전 학습 데이터의 객관적 통계에 기반하여 언제 검색할지를 결정하는 동적 Retrieval-Augmented Generation 방법입니다. 이러한 모델 내부 신호는 LLM miscalibration으로 인해 종종 신뢰성이 떨어집니다.

• 🎯
  코퍼스 기반 불확실성 정량화 (Corpus-Grounded Uncertainty Quantification): Infini-gram을 사용하여 4조 토큰 코퍼스 내의 개체 빈도 및 동시 발생(co-occurrences)을 질의합니다 - ⚡
  2단계 검색 트리거링 (Two-Stage Retrieval Triggering):
  생성 전 (Before generation): 장기 꼬리 지식 격차를 나타내는 저빈도 개체를 식별합니다.
  생성 중 (During generation): 환각 위험을 감지하기 위해 개체 동시 발생 여부를 검증합니다.

• 🔄
  모델 비종속적 (Model-Agnostic): OLMo, Llama, Qwen뿐만 아니라 GPT 모델에서도 작동합니다 - 📈
  강력한 성능: 다단계 QA(multi-hop QA) 벤치마크에서 SOTA 기준선 대비 EM 점수 512점 향상을 달성했습니다 - 🚀
  사전 계산된 캐시 제공 (Pre-computed Cache Available): 캐시 파일을 다운로드하여 실험 속도를 25배 높일 수 있습니다 (아래 Quick Start Tip 참조)

• 설치 (Installation)

• 데이터 준비 (Data Preparation)

• 실험 실행 (Running Experiments)

• 평가 (Evaluation)

• 사용 가능한 설정 (Available Configurations)

• 중요 참고 사항 (Important Notes)

• 인용 (Citation)

• 감사의 글 (Acknowledgements)

💡 실험을 크게 가속화하려면 사전 계산된 캐시 파일 다운로드를 강력히 권장합니다!

저희의 캐시에는 2WikiMultihopQA 및 HotpotQA 데이터셋에 대한 Infini-gram과 검색 결과가 포함되어 있습니다. 캐시를 활성화하면 설정에 따라 실험 시간을 2~5배 단축할 수 있습니다.

# Quick setup
cd QuCo-RAG/data
mkdir -p cache && cd cache
...

그리고 config 파일(예: QuCo-RAG-cache.json)에 `

중요: 이 섹션의 모든 명령은 사용자가 QuCo-RAG 프로젝트 루트 디렉토리에 있다고 가정합니다. 아직 수행하지 않았다면 먼저 cd QuCo-RAG를 실행하십시오.

BM25 인덱스 (index)를 설정하기 전에 두 가지를 다운로드해야 합니다:

1. Elasticsearch 7.17.9 다운로드

# QuCo-RAG 디렉토리에 있는지 확인하십시오
cd QuCo-RAG # 이미 프로젝트 루트에 있다면 이 단계는 건너뜁니다
# data 디렉토리를 생성하고 Elasticsearch를 다운로드합니다
...

2. Wikipedia Dump 다운로드

DPR 리포지토리에서 Wikipedia dump를 다운로드하십시오:

# QuCo-RAG 디렉토리에 있는지 확인하십시오
mkdir -p data/dpr
wget -O data/dpr/psgs_w100.tsv.gz https://dl.fbaipublicfiles.com/dpr/wikipedia_split/psgs_w100.tsv.gz
...

BM25 인덱스를 설정하기 위해 다음 옵션 중 하나를 선택하십시오. 이 작업은 단 한 번만 수행하면 됩니다.

옵션 1: 처음부터 인덱스 구축 (Build index from scratch) (~2-3시간 소요)

# 먼저 QuCo-RAG 디렉토리에 있는지 확인하십시오!
cd QuCo-RAG # 이미 프로젝트 루트에 있다면 이 단계는 건너뜁니다
# Elasticsearch를 시작합니다
...

Elasticsearch가 성공적으로 실행되면 다음과 유사한 출력이 나타납니다:

{
"name" : "your-node-name",
"cluster_name" : "elasticsearch",
...

Elasticsearch가 실행된 후 다음 명령을 실행하여 인덱스를 구축하십시오.

# 인덱스를 구축합니다 (2-3시간 소요)
python tools/prep_elastic_index_with_progress.py --data_path data/dpr/psgs_w100.tsv --index_name wiki

옵션 2: 사전 구축된 인덱스 다운로드 (권장)

빠른 설정을 위해 HuggingFace에서 사전 구축된 BM25 인덱스 (~10GB)를 제공합니다:

bash Start_Elasticsearch_from_hf.sh

이 스크립트는 다음을 수행합니다:

• 구성(configuration) 확인 요청 (ES 디렉토리 및 URL)
• 인덱스가 이미 존재하는지 확인 (존재할 경우 다운로드 건너뜀)
• 🤗 ZhishanQ/QuCo-RAG-es-data-archive 에서 사전 구축된 인덱스 다운로드
• Elasticsearch를 시작하고 인덱스 검증

HPC 사용자의 경우: 로컬 SSD 저장소를 사용하여 더 나은 I/O 성능을 얻으려면 bash Start_Elasticsearch_from_hf_HPC.sh를 사용하십시오.

⚠️ 경고: HPC 모드는 데이터를 /tmp에 저장합니다.

이는 작업이 종료될 때 삭제됩니다. 새로운 작업마다 다시 다운로드해야 할 수도 있습니다.

워크플로우 이해하기:

┌─────────────────────────────────────────────────────────────────┐
│ 최초 설정 (1회 수행) │
│ ───────────────────────────── │
│ ...

사용 가능한 스크립트:

스크립트	목적	사용 시점
Start_Elasticsearch_from_hf.sh	빌드된 인덱스 다운로드 + ES 시작	최초 설정 (인덱스를 1회 다운로드)
Start_Elasticsearch_from_hf_HPC.sh	위와 동일하지만 로컬 SSD 사용	HPC에서의 첫 사용 (매 작업마다 재다운로드)
start_es.sh	기존 인덱스로 ES 시작	ES가 중단되었거나 재부팅 후 실험 시작 전

실험이 완료되면 Elasticsearch를 중지하십시오:

# Elasticsearch는 유휴 상태일 때도 메모리를 소비합니다
pkill -f elasticsearch

참고: 이 명령어들은 QuCo-RAG 프로젝트 루트 디렉토리에서 실행하십시오.

2WikiMultihopQA

Dropbox에서 다운로드하여 압축을 풀고 data/2wikimultihopqa로 이동하십시오. (두 파일인 dev.json과 id_aliases.json만 유지해도 됩니다.)

HotpotQA

# QuCo-RAG 디렉토리에 있는지 확인하십시오
mkdir -p data/hotpotqa
wget -O data/hotpotqa/hotpotqa-dev.json http://curtis.ml.cmu.edu/datasets/hotpot/hotpot_dev_distractor_v1.json

🚨 RAG 실험을 실행하기 전에 반드시 Elasticsearch가 실행 중인지 확인하십시오.

# 스크립트가 ES 실행 여부를 자동으로 확인하고 필요 시 시작합니다
bash start_es.sh

스크립트는 자동으로 다음을 수행합니다:

• Elasticsearch가 이미 실행 중인지 확인
• 실행 중인 경우: 상태를 표시하고 종료
• 실행 중이 아닌 경우: Elasticsearch를 시작하고 인덱스를 검증

상태를 수동으로 확인할 수도 있습니다:

# Elasticsearch가 실행 중인지 확인
curl -X GET "localhost:9200/"
# 클러스터 상태 확인
...

Elasticsearch가 성공적으로 실행되었을 때의 예상 출력:

# 클러스터 상태(Cluster health)가 "green" 상태여야 합니다
{
"cluster_name" : "elasticsearch",
...

Elasticsearch가 올바르게 실행 중이라면, 클러스터 상태(Cluster status)가 "green" 또는 "yellow"로 표시되어야 하며, wiki 인덱스에는 약 2,100만 개의 문서가 포함되어 있어야 합니다.

우리 실험의 모든 설정 파일(Configuration files)은 config 폴더에 있습니다. 이 파일들을 사용하여 QuCo-RAG를 즉시 실행할 수 있습니다.

로컬 모델(Local models)의 경우:

cd src
# 표준 설정 (Standard configuration)
python main_quco.py -c ../config/OLMo-2-1124-7B-Instruct/2WikiMultihopQA/QuCo-RAG.json
...

로컬에 모델 가중치(Model weights)가 없는 경우, 위의 명령어를 실행하면 먼저 Hugging Face Hub에서 가중치를 다운로드합니다.

API 모델(예: GPT-4.1/GPT-5-chat)의 경우:

# 먼저, OpenAI API 키를 설정하세요
export OPENAI_API_KEY="your-api-key-here"
# 그 다음 API 모델 설정으로 실행하세요
...

아래와 같은 로그 메시지가 보인다면, QuCo-RAG가 성공적으로 실행되고 있음을 의미합니다:

2025-12-24 00:01:55 - __main__ - INFO - Namespace(model_name_or_path='allenai/OLMo-2-1124-7B-Instruct', method='QuCo-RAG', dataset='2wikimultihopqa', ...)
2025-12-24 00:01:55 - __main__ - INFO - ==================== config ********************
2025-12-24 00:01:55 - __main__ - INFO - config path: ../config/OLMo-2-1124-7B-Instruct/2WikiMultihopQA/QuCo-RAG.json
...

출력 결과는 result/ 폴더에 저장됩니다. 설정 파일에서 output_dir 파라미터를 수정하여 출력 폴더를 변경할 수 있습니다.

또한 비교를 위한 베이스라인 방법(Baseline methods)의 구현체도 제공합니다. 해당 설정 파일들을 사용하여 실행할 수 있습니다:

로컬 모델(Local models)의 경우:

cd src
# 단일 검색 RAG (Single Retrieval RAG, SR-RAG)
python main_baseline.py -c ../config/OLMo-2-1124-7B-Instruct/2WikiMultihopQA/SR-RAG.json
...

API 모델(예: GPT-4.1)의 경우:

# 먼저, OpenAI API 키를 설정하세요
export OPENAI_API_KEY="your-api-key-here"
cd src
...

프로그램이 완료되면, 지정된 출력 디렉토리 내에 숫자 식별자로 명명된 폴더를 찾을 수 있습니다. 이 식별자는 해당 폴더 내 실행의 순차적 순서에 해당하며, 이를 통해 여러 번의 실행 결과를 쉽게 정리할 수 있습니다.

결과를 평가하려면 src 폴더에 있는 evaluate.py 스크립트를 사용할 수 있습니다. 출력 폴더가 result/QuCo-RAG_OLMo-2-1124-7B-Instruct_2wikimultihopqa/1이라고 가정하면, 다음과 같이 실행할 수 있습니다:

python evaluate.py --dir ../result/QuCo-RAG_OLMo-2-1124-7B-Instruct_2wikimultihopqa/1

평가가 완료되면 프로그램 출력과 출력 디렉토리에서 평가 결과를 확인할 수 있습니다:

result/QuCo-RAG_OLMo-2-1124-7B-Instruct_2wikimultihopqa/1/
├── config.json # 이 실행에 사용된 설정 (Configuration)
├── output.txt # 통계가 포함된 원시 예측값 (Raw predictions)
...

저희는 다음 모델 및 데이터셋에 대한 설정 파일 (Configuration files)을 제공합니다:

모델 (Models):

로컬 모델 (Local Models):

OLMo-2-1124-7B-Instruct

OLMo-2-1124-13B-Instruct

OLMo-2-0325-32B-Instruct

Meta-Llama-3-8B-Instruct

Qwen2.5-7B-Instruct

Qwen2.5-32B-Instruct

API 모델 (API Models):

gpt-4.1

gpt-4o

gpt-5-chat-latest

데이터셋 (Datasets):

2WikiMultihopQA

HotpotQA

모든 설정은 config/ 폴더에 있습니다.

또한 OpenAI GPT 모델을 위한 설정 파일도 제공합니다. 이 모델들을 사용하려면 OpenAI API 키를 설정해야 합니다:

# 환경 변수 설정 (API 모델을 실행하기 전에 필수)
export OPENAI_API_KEY="your-api-key-here"

API 모델에서 사용 가능한 방법 (Available methods):

QuCo-RAG.json

• QuCo-RAG 방법

wo-RAG.json

• 검색 없는 베이스라인 (Without retrieval baseline)

SR-RAG.json

• 단일 검색 베이스라인 (Single retrieval baseline)

FS-RAG.json

• 문장 고정 검색 베이스라인 (Fix-sentence retrieval baseline)

FL-RAG.json

• 길이 고정 검색 베이스라인 (Fix-length retrieval baseline)

Web-Tool.json

• 웹 검색 도구 베이스라인 (OpenAI의 웹 검색 기능 사용)

gpt-4.1/gpt-4o 모델의 경우, OpenAI API는 생성된 토큰의 로그 확률 (log-probability)을 제공하며, 이는 FLARE 방법론에 사용될 수 있습니다. FLARE의 공식 구현체는 FLARE에서 사용할 수 있습니다.

영구 설정 (선택 사항):

# 셸 설정 파일(~/.bashrc 또는 ~/.zshrc)에 추가
echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

참고: API 모델은 로컬 GPU 리소스를 필요로 하지 않지만, API 호출 시 OpenAI의 가격 정책에 따라 비용이 발생합니다. GPT 모델의 경우, 토큰 계산 (token counting)을 위해 llama2의 토크나이저 (tokenizer)를 사용합니다.

다음 표는 QuCo-RAG 설정 파일에서 사용할 수 있는 모든 파라미터 (parameter)를 설명합니다:

파라미터 (Parameter)	유형 (Type)	설명 (Description)	예시 값 (Example Values)
model_name_or_path	string	Hugging Face 모델 ID 또는 LLM의 로컬 경로	"allenai/OLMo-2-1124-7B-Instruct"
method	string	RAG 방법론 식별자 (identifier)	"QuCo-RAG", "flare" 등
dataset	string	데이터셋 (dataset) 이름	"2wikimultihopqa", "hotpotqa"
data_path	string	데이터셋 디렉토리 경로	"../data/2wikimultihopqa"
fewshot	int	프롬프트 (prompt) 내 퓨샷 (few-shot) 예시 수	6, 8
sample	int	평가할 샘플 수 (-1은 전체)	1000, -1
shuffle	bool	데이터셋 셔플 (shuffle) 여부	true, false
generate_max_length	int	토큰 단위의 최대 생성 길이 (maximum generation length)	128 등

| query_formulation | string | 질의 공식화 전략 (Query formulation strategy) | `