GraphRAG 기반 화장품 성분 추천 파이프라인

화장품 성분별 논문 근거를 수집·정제하고, Graph RAG 추천 시스템에 활용할 수 있는 Claim Graph 엣지를 자동으로 생성하는 파이프라인입니다.

프로젝트 목적

단순 키워드 검색이 아닌 논문 근거 기반 화장품 성분 추천을 위해 다음 흐름을 구현합니다.

PubMed에서 타겟 성분별 논문 자동 수집 (Bronze)
Abstract Chunking 및 구조화 (Silver)
LLM 기반 Claim 추출 → 정책 기반 Graph/Recommendation 분류 (Gold)
Graph DB 적재 및 GraphRAG Retrieval (향후)

전체 파이프라인

config/target_ingredients.csv   ← 타겟 성분 28개 정의
          ↓
[Bronze]  PubMed 논문 수집
          ↓
[Silver]  Abstract Chunking
          ↓
[Gold]    LLM Claim 추출 + 정책 분류 (strict_graph / soft_graph / recommendation_only)
          ↓
[Graph]   Neo4j 적재 (예정)
          ↓
[Retrieval] GraphRAG 기반 추천 (예정)

디렉토리 구조

GraphRAG_Pipeline/
├── config/
│   └── target_ingredients.csv       # 타겟 성분 목록 (28개, 버전 관리)
│
├── db/
│   ├── schema/schema_graph_rag.sql  # PostgreSQL DDL
│   ├── seed/                        # 택소노미 초기 데이터 (effect/concern)
│   └── valid/                       # 검증 쿼리
│
├── pipeline/
│   ├── bronze/pubmed/
│   │   └── run_bronze.py            # PubMed 논문 수집 실행
│   ├── silver/paper/
│   │   └── run_silver.py            # Abstract Chunking 실행
│   ├── gold/claim/
│   │   ├── run_gold.py              # Claim 추출 · Gold 레이어 실행
│   │   └── evidence_scoring.py     # 정책 엔진 (tier / attribution / weight)
│   ├── claim/services/
│   │   ├── claim_extractor.py       # 성분 인식 · 택소노미 매핑
│   │   ├── llm_claim_extractor.py   # OpenAI API 호출 (GPT-4.1-mini)
│   │   ├── claim_validator.py       # Claim 후처리 · 필터
│   │   └── claim_filter.py          # 문장 후보 필터
│   ├── metadata/services/
│   │   ├── pubmed_client.py         # PubMed E-utilities 클라이언트
│   │   ├── pubmed_parser.py         # XML 파싱
│   │   └── query_builder.py         # PubMed 쿼리 생성
│   └── common/
│       ├── config/settings.py       # 환경 변수
│       ├── io/                      # bronze/silver/gold CSV·JSON 출력
│       ├── models/                  # 데이터 모델
│       ├── loaders/                 # 성분 CSV 로더
│       └── repositories/           # PostgreSQL 레포지토리
│
├── bronze/pubmed/batch=<id>/        # Bronze 출력 (논문 원본)
│   ├── paper_raw.csv
│   ├── search_log.csv
│   └── metadata.json
│
├── silver/paper/batch=<id>/         # Silver 출력 (청크)
│   ├── paper_chunk.csv
│   └── metadata.json
│
└── gold/claim/batch=<id>/           # Gold 출력 (클레임)
    ├── gold_claim_all.csv           # 전체 클레임 감사 로그
    ├── graph_claim.csv              # 그래프 엣지 후보 (strict/soft)
    ├── recommendation_claim.csv     # 추천 후보 (graph 포함)
    ├── gold_canonical_claim.csv     # 중복 제거 후 canonical 클레임
    ├── gold_excluded_claims.csv     # 제외된 evidence_only 클레임
    ├── gold_unmapped_targets.csv    # 택소노미 매핑 실패
    ├── claim_effect_map.csv         # 클레임 ↔ effect 매핑
    ├── claim_concern_map.csv        # 클레임 ↔ concern 매핑
    └── metadata.json                # 배치 통계

설치 및 환경 설정

1. 가상환경 생성 및 패키지 설치

python -m venv mvenv
source mvenv/bin/activate
pip install -r requirements.txt

2. `.env` 파일 생성

DATABASE_URL=postgresql://user:password@localhost:5432/inci_db
NCBI_EMAIL=your_email@example.com
NCBI_API_KEY=                       # 없어도 동작 (초당 3 req 제한)
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4.1-mini

TARGET_CSV_PATH=config/target_ingredients.csv
SEARCH_LIMIT=50                     # 성분당 PubMed 수집 논문 수

ENABLE_DB_UPSERT=false              # PostgreSQL 적재 여부

자세한 전체 항목은 .env.example을 참고하세요.

3. DB 스키마 초기화 (PostgreSQL 사용 시)

psql -U user -d inci_db -f db/schema/schema_graph_rag.sql
psql -U user -d inci_db -f db/seed/seed_effect_taxonomy.sql
psql -U user -d inci_db -f db/seed/seed_concern_taxonomy.sql
psql -U user -d inci_db -f db/seed/seed_concern_effect_map.sql

타겟 성분 관리

논문 검색·클레임 추출 대상 성분은 config/target_ingredients.csv에서 관리합니다 (TARGET_CSV_PATH로 경로 변경 가능).

ingredient_code,category,canonical_name,query_name,alias_list,concern_keywords,exclude_if_contains,is_target
1,barrier_hydration,Ceramide,Ceramide,Ceramide NP|...,barrier|hydration|TEWL,,true

컬럼	설명
`category`	성분 군 (barrier_hydration / brightening / acne_keratolytic / soothing / antiaging / antioxidant / peptide)
`canonical_name`	성분 표준명
`query_name`	PubMed 검색어
`alias_list`	동의어 (파이프 구분)
`concern_keywords`	피부 고민 키워드 (쿼리 보강용)
`exclude_if_contains`	이 단어 포함 시 클레임 제외
`is_target`	`true`만 수집·추출 대상

현재 기본 목록: 28개 성분 (Ceramide, Panthenol, Hyaluronic acid, Tranexamic acid, Niacinamide, Ascorbic acid, Salicylic acid, Azelaic acid, Zinc PCA, Centella asiatica, Madecassoside, Retinol, Bakuchiol 등)

파이프라인 실행

격리된 PMC 원문 PoC (운영 파이프라인에 미연결)

python -m scripts.run_pmc_fulltext_poc는 CC BY 논문 3건만 공식 PMC BioC 및 NCBI E-utilities API에서 확인하고, poc_output/pmc_fulltext/의 로컬 SQLite에 논문 버전·라이선스·본문 문단 관계를 저장합니다. 원문 데이터와 평가 결과는 Git에서 제외됩니다. PMID를 바꾸려면 --pmid 123 --pmid 456처럼 최대 5건을 지정합니다. 별도 테스트 Neo4j를 127.0.0.1:17687에 준비했다면 python -m scripts.load_pmc_poc_neo4j --load-local-neo4j로 동일 문단과 출처 관계를 적재할 수 있습니다. 이 로더는 원격 URI를 받지 않습니다. 답변 A/B는 사용자 승인 후에만 python -m scripts.compare_pmc_answer_quality --allow-openai-send로 실행합니다. 결과를 기존 로컬 MLflow에 기록할 때는 별도의 graphrag-pmc-fulltext-poc 실험으로 분리하며, 운영 평가와 비교 가능한 점수로 취급하지 않습니다.

이 실험은 원문 접근과 출처 추적 가능성을 검증할 뿐, Gold claim 생성이나 운영 Neo4j 적재, 추천 응답 변경을 수행하지 않습니다. CC BY-NC 등 비상업적 이용 조건, 버전/ID 불일치, 본문 또는 라이선스 누락은 자동으로 제외합니다. 논문 문단을 근거로 사용하려면 별도의 claim 추출·귀속 검증과 기존 평가셋의 A/B 품질 검증이 필요합니다.

Step 1. Bronze — PubMed 논문 수집

python -m pipeline.bronze.pubmed.run_bronze

성분당 최대 SEARCH_LIMIT(기본 50)편 수집
출력: bronze/pubmed/batch=<id>/paper_raw.csv

Step 2. Silver — Abstract Chunking

python -m pipeline.silver.paper.run_silver

최신 Bronze 배치를 자동 선택 (또는 --bronze-batch-id 지정)
Abstract를 문자 단위 슬라이딩 윈도우로 chunking
출력: silver/paper/batch=<id>/paper_chunk.csv

Step 3. Gold — Claim 추출 및 분류

python -m pipeline.gold.claim.run_gold

최신 Silver 배치를 자동 선택
GPT-4.1-mini로 문장 단위 Claim 추출
정책 엔진으로 strict_graph / soft_graph / recommendation_only / evidence_only 분류
출력: gold/claim/batch=<id>/ 하위 CSV 파일들

전체 corpus Gold 재생성

PostgreSQL paper_metadata가 원본 corpus인 경우 Silver부터 재구성하고 Neo4j CSV를 빌드합니다. LLM 응답은 gold/cache/llm_claims.sqlite3에 캐시되어 실패 후 재실행 시 재사용됩니다.

python -m pipeline.silver.paper.run_silver --batch-id <silver-batch-id>
GOLD_TEST_CHUNK_LIMIT=0 python -m pipeline.gold.claim.run_gold \
  --silver-batch-id <silver-batch-id>
python scripts/build_gold_csvs.py --no-upload

builder는 로컬 Gold evidence를 현재 eligibility 정책으로 재평가하고, 기존 운영 graph에서 유효한 node/edge만 보존해 회귀와 dangling edge를 함께 방지합니다. 단일 Gold 배치만 격리 검증할 때는 --claim-batch-id <gold-batch-id>를 사용합니다.

Gold 정책 (Eligibility Tier)

Tier	설명	Graph RAG 활용
`strict_graph`	단일 성분 · moderate/strong 근거 · 리스트 패턴 없음	그래프 엣지 (고신뢰)
`soft_graph`	moderate/strong 복합 성분·제형·리뷰 근거	그래프 엣지 (중신뢰)
`recommendation_only`	병용 시술 · weak 근거	추천 보조
`evidence_only`	비유의 · 매핑 실패 · 비코스메틱 타겟	제외

Attribution 분류 기준

Attribution	의미
`single_active`	단일 성분 단독 근거
`single_formulation`	단일 성분 제형(크림/마스크 등)
`multi_active_combination`	다성분 혼합 문장
`procedure_adjunct_combination`	마이크로니들링 등 시술 병용
`post_procedure_recovery_formulation`	레이저 후 회복 + 제형 맥락

피부 근거 검증 gate (오프라인 파일럿)

새 근거 gate의 정책, 검토 계약과 격리 감사 실행법은 피부 근거 gate 설계를 참고하세요. 현재는 보습 3개 효능에 대한 shadow 검증이며, 기존 Gold 생성·Neo4j·추천에는 적용하지 않습니다. 피부 모델 연구는 설명용으로 보존하고 임상 추천 점수에서 제외합니다. 출처와 적용 조건을 검토하지 않은 기존 근거는 자동 승인하지 않습니다.

데이터베이스 테이블

테이블	설명
`ingredient_master`	성분 마스터
`paper_metadata`	PubMed 논문 메타데이터
`effect_taxonomy`	효능 분류 (BARRIER_REPAIR / HYDRATING / DEPIGMENTING 등)
`concern_taxonomy`	피부 고민 분류 (DRY_SKIN / HYPERPIGMENTATION / ACNE 등)
`concern_effect_map`	피부 고민 ↔ 효능 매핑
`extracted_claim`	추출된 Claim

최근 배치 결과 예시

단계	배치	주요 수치
Bronze	`2026-04-04T09-36-48`	28개 성분, 논문 539편 수집
Silver	`2026-04-04T09-38-58`	1,180 chunks / 6,625 문장
Gold	`2026-04-04T09-51-56`	클레임 64건, graph 엣지 7건 (strict 2 / soft 5), 17개 성분

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
config		config
db		db
docs		docs
oliveyoung_common @ bafe06c		oliveyoung_common @ bafe06c
pipeline		pipeline
scripts		scripts
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
README.md		README.md
requirements.txt		requirements.txt

Navigation Menu

Repository files navigation

GraphRAG 기반 화장품 성분 추천 파이프라인

프로젝트 목적

전체 파이프라인

디렉토리 구조

설치 및 환경 설정

1. 가상환경 생성 및 패키지 설치

2. `.env` 파일 생성

3. DB 스키마 초기화 (PostgreSQL 사용 시)

타겟 성분 관리

파이프라인 실행

격리된 PMC 원문 PoC (운영 파이프라인에 미연결)

Step 1. Bronze — PubMed 논문 수집

Step 2. Silver — Abstract Chunking

Step 3. Gold — Claim 추출 및 분류

전체 corpus Gold 재생성

Gold 정책 (Eligibility Tier)

피부 근거 검증 gate (오프라인 파일럿)

데이터베이스 테이블

최근 배치 결과 예시

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

GraphRAG 기반 화장품 성분 추천 파이프라인

프로젝트 목적

전체 파이프라인

디렉토리 구조

설치 및 환경 설정

1. 가상환경 생성 및 패키지 설치

2. .env 파일 생성

3. DB 스키마 초기화 (PostgreSQL 사용 시)

타겟 성분 관리

파이프라인 실행

격리된 PMC 원문 PoC (운영 파이프라인에 미연결)

Step 1. Bronze — PubMed 논문 수집

Step 2. Silver — Abstract Chunking

Step 3. Gold — Claim 추출 및 분류

전체 corpus Gold 재생성

Gold 정책 (Eligibility Tier)

피부 근거 검증 gate (오프라인 파일럿)

데이터베이스 테이블

최근 배치 결과 예시

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

2. `.env` 파일 생성