이전 편까지 vector RAG와 graph RAG의 구조적 차이, 그리고 chunk 기반 검색의 한계를 다뤘다면, 이번 글은 그 graph RAG의 입력이 되는 KG를 비정형 텍스트로부터 어떻게 구축하는가에 대한 실제 파이프라인을 다룬다. 사례는 록펠러 재단(RAC) 프로젝트로, 1939년에 타이핑된 Warren Weaver의 다이어리 10,000여 페이지를 KG로 변환하는 작업이다.

1. 비정형 아카이브를 KG로 만들 때 마주치는 문제

KG 구축 파이프라인 설명에 앞서, 어떤 입력 조건에서 어떤 어려움이 발생하는지 먼저 정의한다. 이 문제들이 이후 등장하는 3-layer 설계와 entity resolution 전략의 동기다.

여기서 핵심 통찰은 "LLM era 이전이라면 traditional ML 모델 구축에 막대한 자원이 들었을 작업이, 적절한 knowledge representation + LLM + prompt engineering 조합으로 해결 가능해졌다"는 점이다.

2. 3-Layer Graph 설계

문서를 KG로 직접 변환하는 single-shot 접근은 실패한다. 중간 표현이 필요하고, 책은 이를 세 layer로 분리한다.

이 설계의 핵심은 metagraph layer를 중간 단계로 두는 것이다. LLM이 추출한 entity를 곧바로 최종 노드로 merge하지 않고, 일단 페이지에 link된 mention 단위로 저장한다. 이 구조가 주는 이점은 다음과 같다.

• 각 entity mention의 출처 페이지를 보존한다. 시각화 플랫폼에서 "이 entity는 어디서 추출되었는가"를 즉시 보여줄 수 있어 explainability가 자연스럽게 확보된다.
• entity resolution 로직을 수정하면 metagraph로부터 KG layer를 언제든 재생성할 수 있다. resolution 알고리즘은 한 번에 완성되지 않으며, 시행착오가 필수적이다.
• 페이지 간 분산된 entity 정보를 aggregate하면서도 원본 정보 손실이 없다.

3. Normalization과 Cleansing

metagraph가 만들어지면 통계 분석으로 연결성 향상 기회를 찾는다. 대표적인 정규화 작업은 다음과 같다.

• lowercasing: Occupation처럼 case가 의미 없는 entity는 소문자로 통일하면 동일 개념의 분산 저장을 막을 수 있다.
• token stripping: GPT는 prompt에서 분리하라고 지시해도 종종 person name에 title을 포함시킨다 ("Dr. Eleanor Smith"). title을 제거하지 않으면 동일 인물이 KG에 두 번 등장한다.

핵심은 정규화 결과를 원본 name 속성을 덮어쓰지 않고 name_normalized라는 새 속성에 저장한다는 것이다. 원본은 trace 용으로 유지되고, KG layer에 link할 때만 정규화된 값을 쓴다.

// title 제거 예시 (의사코드 수준)
MATCH (e:Entity)
WHERE e.name STARTS WITH "Dr. " OR e.name STARTS WITH "Prof. "
SET e.name_normalized = trim(replace(replace(e.name, "Dr. ", ""), "Prof. ", ""))

// case 정규화
MATCH (e:Entity {class: "Occupation"})
SET e.name_normalized = toLower(e.name)

4. Entity Resolution: 같은 사람을 같은 노드로

Generative LLM은 traditional NER/RE 모델과 달리 prompt가 잘 설계되었다면 entity의 full clean form만 반환한다. 이는 implicit coreference resolution이 일어난다는 뜻이고, 후처리로서의 entity resolution 부담을 줄인다. 그러나 줄인다는 것이지 없앤다는 것이 아니다. 문서 간 resolution은 여전히 별도 작업이다. 한 다이어리에서 "Eleanor Smith"가 다른 다이어리의 "E. Smith"와 같은 사람인지를 판정해야 한다.

4.1 String similarity만으로 부족하다

이름 문자열이 비슷하다는 것만으로는 신뢰도가 낮다. 사람 이름은 first / middle / surname 구조를 갖고, middle name은 축약되거나 생략된다. surname만 같으면 false positive가 폭증하고, surname + first name 일부 조합 정도에서 신뢰도가 생긴다. 또한 도메인 stopword 처리가 중요하다. 많은 재단 명칭에 "Foundation"이 포함되어 있는데, 이를 무시하지 않으면 무관한 organization들이 모조리 SIMILAR로 묶인다.

4.2 관계 그래프를 entity resolution에 활용한다

여기가 graph 기반 접근의 진가다. metagraph의 mention들은 이미 다른 mention들과 관계로 연결되어 있고, 이 관계 자체가 resolution 신호가 된다.

세 mention이 같은 인물(노벨 물리학상 수상자 Ernest Lawrence)이라는 판정 근거는 다음 신호의 결합이다.

• 이름 문자열 유사도 (rule 기반)
• 동일 organization (WORKS_FOR → University of California) 공유 → 3-hop 거리
• 의미적으로 연관된 occupation (cyclotron ↔ 100,000,000 to 200,000,000 volt cyclotron) 공유

특히 "Ernest Orlando Lawrence"와 단독 "Lawrence"는 6-hop 거리에 있다. 관계형 DB라면 이런 traversal은 매우 비싸지만, graph DB에서는 자연스러운 query다.

4.3 알고리즘 단계

resolution 파이프라인은 다음과 같다.

추가 옵션으로 다음이 거론된다.

• Community detection (Louvain 등): TALKED_ABOUT, TALKED_WITH 같은 intellectual network에 community detection을 적용하면, 동명이인을 분리할 수 있다. 남극에서 해양 연구를 하는 John Doe와 cosmology를 연구하는 John Doe는 다른 community에 속할 가능성이 높다.
• Embedding 기반 의미적 유사도: 문자열이 전혀 닮지 않았지만 개념적으로 가까운 occupation들 (fertility와 human ovulation)은 GPT embedding으로 vector화 후 agglomerative clustering으로 묶을 수 있다. 이 부분은 vector approach와 graph approach가 만나는 지점이다.

5. 완성된 KG로 무엇을 하는가: 지적 네트워크 분석

KG는 만드는 것 자체가 목적이 아니다. 주된 용도는 graph analytics다. 책에서 RAC 프로젝트가 보여주는 분석은 "과학자들의 지적 네트워크"를 추출하는 것이다. TALKED_ABOUT, TALKED_WITH, WORKS_WITH, STUDENT_OF 같은 관계로 구성된 subgraph에 Neo4j Graph Data Science library의 알고리즘을 적용한다.

betweenness centrality 시각화에서는 노드 크기가 통과하는 최단경로 수에 비례한다. 이 시각화에서 Niels Bohr나 Ernest Lawrence처럼 유명한 과학자가 부각되는 것은 예상대로지만, 덜 알려진 인물도 함께 드러난다. 이 "덜 알려진 bridge"가 도메인 분석가에게 새로운 가설의 출발점이 된다.

KG는 또한 더 좁은 질문에도 답한다. "cyclotron 연구와 그 펀딩에 핵심 역할을 한 사람은 누구인가" 같은 질문은 cyclotron을 연구한 인물에서 시작해 최대 2-hop 거리에 있는 인물로 path를 확장하면서 referral 패턴을 추적하는 query로 표현된다.

실용 시나리오 하나는 다음과 같다. project officer Warren Weaver가 자리를 떠나 후임이 들어온다. 후임은 Johns Hopkins와 Harvard 양쪽에 physics 도메인 연결이 있는 인물에게 비공식 자문을 받고 싶다. 이 질문은 KG의 영향력 네트워크에서 직접 답이 나온다. 게다가 TALKED_ABOUT relation에 sentiment 속성이 있다면, "Bernal은 Dorothy Wrinch에 부정적 태도를 보인다, Irving Langmuir는 Bernal에 부정적 태도를 보인다"처럼 정성적 정보까지 활용한 균형 잡힌 인터뷰 대상자 선정이 가능하다.

6. 한계와 트레이드오프

LLM 기반 KG 구축은 마술이 아니다. 책 본문에서 명시적으로 또는 암묵적으로 드러나는 한계는 다음과 같다.

1) RE 실패의 silent propagation. 책의 사례에서 어떤 인물이 cyclotron subgraph에 잘못 등장한 사건이 보고된다. 이는 LLM의 RE 단계 오류이며, 다운스트림 분석 결과를 오염시킨다. 분석가가 graph 내용을 검증·반려할 수 있는 feedback loop가 application에 내장되지 않으면, 잘못된 entity가 의사결정에 영향을 미친다.

2) Entity resolution은 보수적일수록 유실, 공격적일수록 오염된다. Irving Langmuir가 두 노드(Langmuir와 Irving Langmuir)로 남은 사례는 책에 직접 등장한다. 한 페이지에서 surname만 등장하면서 다른 어떤 관계도 함께 추출되지 않으면 resolution에 사용할 신호가 없어 두 mention이 분리된 채로 KG에 들어간다. resolution rule을 더 공격적으로 풀면 동명이인 false merge가 발생한다. 이 trade-off는 알고리즘 튜닝만으로 해소되지 않는다.

3) Token limit과 multi-page 처리. LLM은 한 번에 처리할 수 있는 입력·출력 토큰이 제한된다. 다이어리가 수백 페이지일 때 단순 chunking은 entry 경계를 무시하고, 그러면 entity 간 관계가 끊긴다. RAC 프로젝트는 ChatGPT-3.5-Turbo로 entry boundary detection을 별도 단계로 두는 식으로 우회했지만, 이는 추가 LLM 호출 비용과 또 다른 오류 표면을 만든다.

4) Schema 설계는 사후 변경 비용이 크다. RE schema가 너무 좁으면 유용한 관계를 놓치고, 너무 넓으면 noise가 KG를 채운다. metagraph layer 덕분에 KG layer는 재생성 가능하지만, schema 변경은 LLM 추출 단계까지 거슬러 올라가야 한다.

7. 실무 적용 고려사항

위 한계를 인지한 상태에서 production-quality KG 시스템을 구축할 때, 책이 제시하는 next steps는 다음과 같이 압축된다.

• Knowledge extraction 정확도 향상: prompt engineering 추가 iteration 또는 LLM fine-tuning. 어느 시점부터는 prompt 튜닝의 한계가 분명해지므로, 도메인 데이터로 fine-tuning이 비용 대비 효과가 더 클 수 있다.
• 외부 knowledge base 연동: WikiData 등을 활용한 entity disambiguation은 historical 도메인이 아닌 현대 도메인에서 baseline resolution을 강력하게 끌어올린다.
• Occupation entity의 hierarchical resolution: nuclear physics ⊃ isotopes ⊃ heavy nitrogen 같은 granularity 차이를 단순 cluster로 처리하지 않고, embedding (SentenceBERT, GPT) + agglomerative hierarchical clustering으로 계층을 보존한다. 이렇게 해야 "주제의 전체 역사"를 query할 수 있다.
• Conversation 노드 도입: date, interviewer, interviewee, topic을 갖는 Conversation 노드를 만들면 follow-up chain 분석과 grant 연결이 가능해진다.
• Cross-source 통합: 다이어리(diaries)와 이사회 의사록(board of directors minutes)을 같은 KG에 통합하면 "어떤 conversation이 어떤 grant로 이어졌는가" 같은 질문에 답할 수 있다.

8. 왜 LLM에 직접 묻지 않고 KG를 만드는가

이 챕터의 마지막 질문은 사실 시리즈 전체의 thesis를 압축한다. 답은 다섯 가지로 정리된다.

결론: LLM은 KG의 직접 생산자가 아니라 raw text에서 entity와 relation을 뽑는 추출기이며, KG의 가치는 추출 이후의 정규화·resolution·graph analytics 단계에서 결정된다.

참고 자료

• Knowledge Graphs and LLMs in Action. Manning, 2024 — Chapter 6: Building knowledge graphs with large language models

이전 챕터까지 다룬 KG는 테이블·관계형 DB·기존 knowledge base 같은 구조화된 데이터를 전제로 했다. 그러나 실무에서 마주하는 도메인 지식 대부분은 논문·보고서·아카이브 문서 같은 비정형 텍스트에 잠겨 있다. 이 챕터의 thesis는 다음과 같다. 비정형 데이터에서 KG를 만드는 작업은 "지식 표현(knowledge representation)"과 "지식 학습(knowledge learning)"이라는 두 축의 결합이며, LLM은 후자의 비용 구조를 근본적으로 바꾼다.

• Knowledge representation: 정보를 컴퓨터와 사람이 모두 자율적으로 접근 가능한 형태로 모델링하는 방법. 분산되고 고립된 정보를 정렬되고 연결된 형태로 만드는 것이 KG의 본질이다.
• Knowledge learning: NLP·LLM 같은 프레임워크와 기술의 조합으로 비정형 문서에서 insight를 채굴하는 과정이다.

전체 파이프라인은 digitization → NER → RE → custom knowledge extraction의 순서로 흐른다.

NER과 RE 단계에 전통적 NLP 모델 또는 LLM이 투입된다. 강조된 두 노드가 이 챕터의 핵심 결정 지점이다.

2. NER과 RE: KG 구축의 최소 단위

2.1 Named Entity Recognition

NER은 raw text에서 named entity의 mention을 식별하고 사전 정의된 카테고리로 분류하는 ML classification system으로 정의된다. 다수의 open source NLP 라이브러리는 Person, Location, Organization 같은 generic 카테고리를 즉시 제공하지만, 실제 도메인 작업에서는 거의 충분하지 않다.

예를 들어 화학 연구 아카이브에서 "Professor of Chemistry"라는 직위, 특정 연구 분야명, 화학 물질명을 식별해야 한다면 generic NER 모델로는 부족하다. 단순한 dictionary 기반 시스템도 도메인 어휘 커버리지가 낮다. 따라서 custom entity-extraction system이 필요하며, 이는 custom NER 모델 학습 또는 LLM 활용 두 경로로 해결된다.

2.2 Relation Extraction

RE는 텍스트 내 entity pair 사이의 semantic relation을 식별하는 작업이다. 다음 문장을 보자.

"Jane Austen, Victorian era writer, is currently employed by Google."

이 문장은 PERSON("Jane Austen")과 ORGANIZATION("Google")이라는 두 named entity를 포함하며, 둘은 employment 관계로 묶인다. 이 relatedness를 포착하는 것이 진짜 KG를 만드는 작업이다. 단순히 entity 목록만 추출하면 그래프가 아니라 리스트일 뿐이다.

3. 전통적 NLP에서 LLM으로: 패러다임 전환

3.1 모델 중심에서 데이터 중심으로

전통적 NLP는 task-specific training dataset 구축, 최적 model architecture 탐색, hyperparameter fine-tuning 같은 model-centric 접근을 취해왔다. 이 접근의 극단적 형태는 데이터 품질 문제를 무시하는데, faulty data를 넣으면 faulty prediction이 나온다는 단순한 사실을 간과한다.

시간이 지나면서 data-centric paradigm이 주목받기 시작했다. 고복잡도 ML 모델을 학습시키기 위한 데이터의 품질과 양을 개선하는 데이터 엔지니어링이 핵심으로 자리 잡았다.

3.2 LLM의 등장이 바꾼 것

2022년 말 OpenAI의 GPT-3.5 시리즈와 ChatGPT 공개 이후, Transformer 아키텍처 기반 generative model이 NLP 작업의 표준 옵션이 되었다. LLM의 핵심 가치는 다음 두 가지다.

• Transfer learning: 방대한 데이터셋으로 학습된 weight를 재사용하므로, 동일한 정확도를 더 적은 human-labeled data로 달성한다. 모델을 from scratch로 학습할 필요가 없다.
• Prompt engineering으로 충분: 자연어로 task를 기술(prompt engineering)하면 모델이 답을 생성한다. Model engineering이 필요 없다.

3.3 LLM의 한계: hallucination

LLM의 강력함에도 시스템 설계 시 반드시 고려할 한계가 있다. 가장 중요한 것은 hallucination, 즉 학습 데이터에 근거가 없는 경우에도 "사실"을 만들어내고 잘못된 추론을 수행하는 경향이다. 이 때문에 LLM을 KG 구축 도구로 사용할 때는 LLM이 직접 사실을 단정하게 하기보다, 고품질의 named entity·관계·속성을 추출하도록 유도하는 방식이 권장된다.

4. LLM 기반 KG 구축 워크플로우

LLM을 활용한 KG 구축은 prompt-based inference로 즉시 시작하거나, 도메인 특화 정확도를 위해 fine-tuning으로 확장할 수 있다.

각 단계의 역할은 다음과 같다.

• Data exploration: 도메인의 복잡도와 합리적 기대치를 파악하는 초기 단계. 데이터 이해 없이는 의미 있는 prompt를 작성할 수 없다.
• Prompt engineering: 가장 효과적인 prompt를 찾기 위한 반복 과정. 단어 몇 개를 바꾸는 것만으로도 성능에 큰 차이가 발생한다.
• Pre-annotation + Fine-tuning: prompt-based 접근이 한계에 부딪히면 진입한다. 비용과 시간이 들지만, 도메인에 specialized된 더 안정적이고 정확한 모델을 얻는다.

5. Prompt Engineering의 실제: 세 번의 반복

generic prompt("모든 entity와 관계를 식별하라")만으로 KG를 만들면 다음과 같은 문제가 드러난다.

• 공지칭 해결과 약어 복원의 자연스러운 처리: LLM의 generative 특성 덕분에 coreference resolution이 implicit하게 수행된다. 예를 들어 "Prof. Chem."이나 "Assoc. in Chem." 같은 축약 직위가 "Professor of Chemistry", "Associate in Chemistry"로 복원된다. 전통적 NER 모델이 할 수 없는 작업이다.
• 과도한 관계 세분화: specializes in, is measuring, is interested in, demonstrates처럼 모두 정확하지만 KG 관점에서 같은 개념을 표현하는 관계들이 분리된다.
• 비일관된 노드 라벨: 같은 단락의 네 가지 연구 주제에 field, research, theory 세 가지 다른 라벨이 부여된다.
• 예측 불안정성: 동일한 prompt를 동일 텍스트에 반복 실행해도 결과가 달라진다.

이러한 문제는 prompt를 점진적으로 정교화하면서 해결된다.

세 번째 버전에서 원하는 모든 결과를 달성한다. 핵심 교훈은 모델 자체의 선택보다 근본 원리, 즉 task 명확성·도메인 노트·다양한 예시가 더 결정적이라는 점이다. 이 챕터의 prompt는 ChatGPT 계열 모델용으로 설계되어 GPT-4o mini에서 테스트되었으나, 새로운 모델이 등장해도 동일한 원칙이 적용된다.

Prompt 설계 일반 원칙

6. 전통적 NLP vs LLM: 선택의 기준

LLM이 모든 상황에서 우월한 것은 아니다. 도메인·비용·운영 제약에 따라 선택이 달라진다.

선택은 이분법적이지 않다. 두 접근은 공존 가능하며, LLM을 활용해 전통적 NLP 모델 학습용 데이터를 빠르게 pre-annotation하는 하이브리드 전략도 유효하다.

7. 한계와 트레이드오프

LLM 기반 KG 구축이 실무에서 직면하는 한계는 다음 세 가지로 정리된다.

• Hallucination 리스크: LLM이 근거 없는 entity나 관계를 생성할 수 있다. KG는 downstream 추론에 사용되므로, 잘못된 사실 하나가 multi-hop traversal을 통해 확산될 위험이 있다. 따라서 LLM 출력을 그대로 신뢰하기보다 high-quality entity·relation·property 추출에 활용하고, 사실 단정은 원본 문서나 신뢰 가능한 source로 우회하는 설계가 안전하다.
• 출력 안정성과 정규화 비용의 trade-off: temperature를 낮추면 안정성은 확보되지만, 미묘한 도메인 변형에 대한 적응력이 떨어진다. 반대로 prompt를 정교화해 entity/relation class를 강하게 명시하면 안정성은 높아지나 prompt 자체가 길어져 token 비용과 유지보수 부담이 늘어난다. 제3의 옵션인 fine-tuning은 이 trade-off를 우회하지만 초기 비용을 다시 부과한다.
• 대규모 데이터셋에서의 비용 역전: 소~중규모 데이터셋에서는 LLM이 전통적 NLP 파이프라인 대비 초기 투자가 적어 유리하지만, 데이터 규모가 커질수록 GPU 추론 비용이 누적되어 경제성이 역전될 수 있다. streaming 시나리오나 실시간 추론 요구가 있는 환경에서는 더욱 그렇다.

8. 실무 적용 시 고려사항

LLM으로 KG를 구축할 때 production 단계에서 자주 간과되는 지점이 있다. 첫째, prompt engineering은 코드와 동일하게 버전 관리되어야 한다. 단어 하나의 변경이 출력 품질에 비대칭적 영향을 미치므로, prompt와 기대 출력을 unit test 형태로 묶고 회귀 테스트를 자동화하는 것이 안전하다. 둘째, eyeballing a mini-KG 단계를 생략하지 않아야 한다. 정량 지표만으로는 잡히지 않는 노드 라벨 비일관성·관계 세분화 문제가 그래프 시각화에서 즉시 드러난다. KG는 결국 그래프로 사용되므로, 그래프 형태로 점검하지 않으면 downstream에서야 문제가 발견된다.

셋째, 보안 요구가 강한 도메인이라면 LLM 직접 사용 대신 LLM을 데이터 어노테이션 가속기로 활용하는 우회 경로를 검토한다. LLM으로 pre-annotation한 데이터를 사람이 검수해 전통적 NLP 모델 학습에 사용하면, on-premise 배포 가능한 모델과 LLM의 transfer learning 이점을 동시에 얻을 수 있다. Hyperscaler(AWS, Azure, GCP)를 통한 LLM 호출이 가능한 환경이라면 일부 인프라 부담이 완화된다.

결론: 비정형 텍스트에서 KG를 구축하는 작업의 본질은 모델 선택이 아니라 task 정의의 명확성이다. LLM은 진입 비용을 낮췄지만, 도메인 클래스 목록·정밀한 task 기술·대표 예시라는 세 축은 여전히 사람의 몫으로 남는다.

참고 자료

• Knowledge Graphs and LLMs in Action. Manning, 2024 — Chapter 5: Extracting domain-specific knowledge from unstructured data

단일 출처 그래프는 정보를 저장하지만, 다중 소스 통합 KG는 정보를 연결한다.

1. 챕터의 위치와 thesis

이전까지의 논의가 단일 도메인·단일 출처에서 knowledge graph(KG)를 구축하는 방법에 머물렀다면, 이 챕터는 이질적인 데이터셋을 하나의 동질 그래프(homogeneous graph)로 통합하고, 그 위에서 LLM 기반 intelligent advisor system(IAS)을 운용하기 위한 분석 기법을 다룬다. 핵심 thesis는 다음과 같다. 다중 소스 KG의 가치는 그래프를 키우는 데 있지 않고, 서로 다른 출처의 entity와 relationship을 일관된 의미 단위로 정렬(align)하는 데 있다.

이전 편에서 vector retrieval이 chunk 간 유사도에 머무는 한계를 보였다면, multisource KG는 출처 간 cross-reference를 명시적 edge로 보존한다는 점에서 본질적으로 다르다. 즉, retrieval의 단위가 "비슷한 텍스트"에서 "검증된 관계"로 옮겨간다.

2. 다중 소스 통합 파이프라인

구조화·반구조화 데이터를 하나의 그래프로 합치는 과정은 단순 merge가 아니라 다단계 파이프라인이다. 이 파이프라인의 각 단계는 직렬로 의존하므로, 어느 한 단계의 품질 저하가 후속 분석 전체로 전파된다.

각 단계의 역할은 다음과 같이 정리된다.

entity resolution은 단순 문자열 매칭을 넘어 식별자(identifier) 수준의 reconciliation을 요구한다. 같은 단백질이 데이터셋마다 다른 ID로 등록되어 있는 경우, ID 매핑 테이블 없이는 두 노드가 별개로 남는다.

3. 분석 기법: 클러스터링과 subgraph 지표

통합된 KG의 품질은 시각 점검만으로 판단되지 않는다. 정량적 분석 지표가 그래프의 구조와 완성도를 평가하는 도구가 된다.

3.1 클러스터링 알고리즘

전역 구조와 커뮤니티 조직을 파악하기 위해 두 가지 알고리즘이 사용된다.

WCC는 "그래프가 얼마나 연결되어 있는가"라는 거시적 질문에, Louvain은 "연결된 그래프 내부에 어떤 응집 구조가 있는가"라는 미시적 질문에 답한다. 두 결과는 상호보완적이며, 다중 소스 통합의 성공 여부를 판단하는 1차 지표 역할을 한다.

3.2 Subgraph 품질 지표

def evaluate_subgraph(G, subgraph_nodes):
    sub = G.subgraph(subgraph_nodes)
    n = sub.number_of_nodes()
    m = sub.number_of_edges()

    # density: 밀도
    density = (2 * m) / (n * (n - 1)) if n > 1 else 0

    # conductance: 외부와의 연결 비율
    boundary_edges = sum(
        1 for u, v in G.edges()
        if (u in subgraph_nodes) ^ (v in subgraph_nodes)
    )
    internal_edges = m
    conductance = boundary_edges / (2 * internal_edges + boundary_edges) \
                  if (internal_edges + boundary_edges) > 0 else 0

    # 최대 연결 컴포넌트의 상대 크기
    largest_cc = max(nx.connected_components(sub), key=len, default=set())
    relative_lcc = len(largest_cc) / n if n > 0 else 0

    return density, conductance, relative_lcc

• density: subgraph 내부 연결의 조밀함. 너무 낮으면 entity resolution 누락 가능성을 시사한다.
• conductance: subgraph가 외부와 얼마나 연결되어 있는지. 낮을수록 자기 완결적 community다.
• largest connected component의 상대 크기: 1에 가까울수록 단일 거대 연결 구조. 이 값이 작으면 그래프가 파편화되어 있다.

3.3 경로 기반 고급 지표: DWPC

Degree-Weighted Path Count(DWPC)는 단순 경로 개수 계산의 한계를 보완한다. 단순 path counting은 hub 노드(연결이 매우 많은 노드)를 거치는 경로를 과대평가한다. DWPC는 경로상의 각 노드 degree에 가중치를 부여해 hub 효과를 감쇠시킨다.

def dwpc(paths, degrees, w=0.4):
    # w: damping exponent. 일반적으로 0.3~0.5
    score = 0.0
    for path in paths:
        path_weight = 1.0
        for node in path[1:-1]:  # 중간 노드만 가중
            path_weight *= degrees[node] ** (-w)
        score += path_weight
    return score

w 값이 클수록 hub 페널티가 강해진다. 이 지표는 entity 간 관련성(relevance)을 평가할 때 단순 도달 가능성보다 훨씬 풍부한 신호를 제공한다.

4. 대표 KG 사례

다중 소스 통합 기법의 실증 사례로 다음 KG들이 testbed 역할을 한다.

이들 KG는 entity resolution, schema alignment, 분석 지표 적용을 모두 요구하는 복잡도를 가지므로 통합 기법의 검증 대상으로 적합하다.

5. LLM 기반 결과 해석

KG 분석은 정량 지표를 산출하지만, 그 자체로는 도메인 의미가 뚜렷하지 않다. density 0.12, conductance 0.31 같은 숫자가 어떤 임상적·연구적 함의를 갖는지는 별도의 해석 단계가 필요하다.

LLM은 이 단계에서 정량 지표를 도메인 가설로 번역하는 역할을 한다. "이 community는 평균 대비 density가 높고 특정 단백질 cluster를 공유한다"는 분석 결과를 "공통 신호 경로의 후보군"이라는 연구 가설로 변환하는 식이다.

6. 한계와 트레이드오프

다중 소스 통합 KG는 표현력 측면에서 강력하지만, 다음 한계가 따른다.

1. Entity resolution의 정확도 천장: 동일 실체를 식별하는 작업은 본질적으로 휴리스틱·확률적 추론에 의존한다. 식별자가 없는 경우 문자열·맥락 기반 매칭이 사용되며, false merge(다른 실체를 합치는 오류)와 false split(같은 실체를 분리하는 오류)이 동시에 발생한다. 두 오류는 trade-off 관계에 있어 한쪽을 줄이면 다른 쪽이 늘어난다.

2. 지표의 도메인 의존성: density·conductance·DWPC 같은 지표는 그래프 구조의 통계적 속성일 뿐, 도메인 의미를 보장하지 않는다. 같은 density 값이 임상 KG와 소셜 네트워크에서 전혀 다른 의미를 갖는다. 지표 임계값을 일반화하려는 시도는 실패하기 쉽다.

3. 확장성 비용: 출처가 늘어날수록 schema alignment·entity resolution의 조합 폭발이 발생한다. n개 출처 통합 시 매핑 작업은 단순히 n에 비례하지 않고, 출처 간 페어와이즈 충돌 해소를 포함하면 빠르게 가중된다. 또한 후처리 병합 단계의 재계산 비용이 그래프 크기에 비선형적으로 증가한다.

7. 실무 적용 시 고려사항

실제 시스템에서 다중 소스 KG를 운용할 때 가장 먼저 결정해야 할 것은 entity resolution의 신뢰 임계값이다. 자동 병합 임계를 높게 잡으면 분리된 중복 entity가 남고, 낮게 잡으면 의미가 다른 노드가 합쳐져 분석 결과를 오염시킨다. 도메인 전문가의 검증 루프를 단계적으로 삽입하는 hybrid 방식이 안정적이다.

또한 KG는 일회성 산출물이 아니라 유지보수 대상이다. 출처 데이터의 스키마 변경, 신규 출처 추가, 기존 매핑 규칙의 수정이 누적되면서 그래프 일관성이 흔들린다. WCC·Louvain 결과를 정기적으로 비교해 구조적 drift를 감지하는 모니터링 체계가 필요하다. LLM 기반 해석 모듈을 운용할 경우, 정량 지표와 도메인 어휘 사이의 매핑 규칙을 명시적으로 두지 않으면 해석이 hallucination에 취약해진다.

결론: 다중 소스 KG의 품질은 그래프 크기가 아니라 entity resolution과 정량 지표 검증 루프의 정밀도로 결정된다.

참고 자료

• Knowledge Graphs and LLMs in Action. Manning, 2024 — Chapter 4: From simple networks to multisource integration

Knowledge Graph 구축의 본질적 난점은 단순한 포맷 변환이 아니라 의미(semantics)의 통합에 있다. 책에서는 이 난점을 네 층위로 분해한다.

• 포맷 차이: XML, CSV, JSON 등 직렬화 형식이 제각각이다.
• 저장 기술 차이: 관계형 DB와 문서지향 DB의 모델이 다르다.
• 구문(syntax) 차이: 같은 날짜를 2022-08-09로 쓰기도, 9 August 2022로 쓰기도 한다.
• 의미(semantics) 차이: 가장 까다로운 층위다. 헬스케어 도메인의 예가 분명하다. type 2 diabetes와 ketosis resistant diabetes는 다른 표현이지만 동일 개념이며, 반대로 PE라는 동일 약어는 physical examination일 수도 pulmonary embolism일 수도 있다. 거기에 necrosis와 lobular necrosis처럼 정보의 granularity 차이까지 더해진다.

이 네 층위 중 앞의 셋은 ETL 도구로 흡수 가능하지만, 의미 차이는 별도의 reference schema 없이는 풀리지 않는다. 그 reference 역할을 하는 것이 ontology다.

2. Ontology: heterogeneous 정보의 중재자

Ontology는 데이터에 등장하는 entity의 formal name, property, category, relationship을 표준 vocabulary로 모델링한 것이다. 책에서 ontology는 "semantically heterogeneous information의 intermediary"로 정의된다. 즉 각 데이터 소스의 local schema를 ontology의 reference schema로 mapping하는 구조다.

이 mapping 구조를 도식화하면 다음과 같다.

KG의 목표는 이렇게 단일 view로 융합된, unified·well-grounded·meaningful한 표현을 얻는 것이다. 개별 데이터 조각이 일관된 view 안에서 의미를 갖게 되어야 한다.

3. KG 구축 프로세스: CRISP-DM의 변형

책은 데이터 마이닝 표준 방법론인 CRISP-DM을 KG 구축용으로 각색해 제시한다. 단계별 책임이 명확히 분리된다.

이 절차는 일회성 빌드가 아니라 순환 구조라는 점이 중요하다. 도메인 이해가 깊어지거나 데이터 소스가 추가될 때마다 ontology 자체가 진화하고, 그에 따라 후속 phase가 다시 돌아간다.

4. 사례: HPO 기반 희귀질환 진단 지원

책의 실제 use case는 임상 현장이다. 임상의가 진단을 내리는 과정에는 명확한 검사 결과뿐 아니라 gray area가 포함된다. 이 불확실성을 다루기 위해 두 속성을 가진 structured knowledge base가 필요하다.

• phenotype 도메인의 contextual description: 같은 장기·계통과 관련된 phenotypic anomaly가 명시적으로 연결되어 있어야 한다.
• phenotypic anomaly와 disease 간 관계 추적성: 임상의가 연결의 근거 출처에 도달할 수 있어야 한다.

이 요구를 만족시키는 것이 HPO (Human Phenotype Ontology) 와 그 annotation 데이터다. HPO는 phenotype 계층을 제공하고, annotation 파일은 phenotypic abnormality와 disease를 연결한다.

5. RDF vs LPG: 두 갈래 기술 선택

KG를 구축하는 가장 대표적 두 모델이 RDF (Resource Description Framework) 와 LPG (Labeled Property Graph) 다. 둘은 같은 그래프를 표현하지만 설계 철학이 갈린다.

RDF의 구조

RDF는 W3C가 정의·관리하는 web 기반 데이터 교환 표준이다. 모든 statement가 subject–predicate–object의 triple로 구성된다. Subject는 노드, predicate은 edge, object는 또 다른 노드다. KG 전체가 이런 statement의 집합으로 모델링된다. 도메인 ontology 작성에 특히 적합하다.

LPG의 구조

LPG는 노드와 relationship에 key–value pair를 직접 붙일 수 있는 모델이다. 그래프 traversal과 path 분석에 최적화되어 있고, 저장·접근 효율이 강점이다.

핵심 차이: 메타데이터의 부착 위치

RDF에서 relationship(triple)은 전역적으로 정의된다. 즉 어떤 predicate에 메타데이터를 붙이면 그래프 전체에서 해당 relationship의 모든 instance에 영향이 간다. LPG는 반대로 edge별 unique 속성을 허용하므로 개별 relationship에 따로 메타데이터를 부여할 수 있다.

이 차이를 보완하기 위해 양쪽 모두 진화 중이다. RDF 측은 named graph로 triple 묶음에 컨텍스트를 부여하고, RDF-star로 edge에 property를 붙이는 길을 열고 있다. LPG 측은 Neo4j의 Neosemantics 플러그인으로 OWL·RDFS·SKOS 같은 RDF vocabulary를 LPG 위에서 활용 가능하게 하며, Amazon Neptune은 RDF 데이터에 Cypher를 실행하는 우회 경로를 제공한다.

RDF 내부의 세 가지 모델링 전략

RDF가 edge에 속성을 붙이지 못한다는 한계를 우회하기 위해 세 가지 패턴이 통용된다.

• N-ary relations: 데이터를 연결하는 새로운 concept을 만든다. 보통 _:Annotation 같은 blank node로 표현되는데, 이는 전역 식별자 없이 관련 정보를 묶기 위한 unnamed resource다. ontology 진화에 따른 backward compatibility가 약점이 될 수 있다.
• Named graphs: triple에 네 번째 요소를 추가해 statement가 어느 sub-graph에 속하는지 명시한다. provenance·context 표현에 강력하지만, named graph 수가 많아지면 저장·교환 효율이 떨어지고 fine-grained update가 어려워진다.
• RDF-star: triple 자체에 property를 붙일 수 있게 한 RDF 확장이다. 더 읽기 쉬운 SPARQL 쿼리가 가능하지만, query 성능이 아직 부족하고 새 syntax 확장이라는 특성상 RDF 엔진별 구현이 필요해 채택이 제한적이다.

이 외에 reification이나 singleton property 같은 방법도 존재하지만, 실무에서는 named graph와 n-ary relation이 더 자주 선택된다.

6. Neo4j로 HPO KG 만들기: 구축 단계

책은 LPG 진영의 Neo4j와 Neosemantics 플러그인을 사용해 HPO KG를 실제로 구축한다. 절차는 두 단계다.

1. Ontology 로딩: HPO vocabulary 자체를 그래프에 적재
2. Annotation 데이터 ingest: ontology를 reference로 삼아 disease–phenotype 연결을 채워 넣기

전체 파이프라인을 정리하면 다음과 같다.

특히 HAS_PHENOTYPIC_FEATURE relationship에 속성을 붙이는 단계는 LPG의 강점을 잘 보여준다. 다음 의사코드는 TSV의 각 row에서 값이 존재하는 경우에만 property를 부여하는 패턴이다.

LOAD CSV WITH HEADERS FROM 'file:///annotations.tsv' AS row
FIELDTERMINATOR '\t'
MATCH (d:HpoDisease {id: row.disease_id})
MATCH (p:HpoPhenotype {id: row.phenotype_id})
MATCH (d)-[r:HAS_PHENOTYPIC_FEATURE]->(p)
FOREACH (_ IN CASE WHEN row.frequency IS NOT NULL THEN [1] ELSE [] END |
  SET r.frequency = row.frequency
)
FOREACH (_ IN CASE WHEN row.onset IS NOT NULL THEN [1] ELSE [] END |
  SET r.onset = row.onset
)

FOREACH 블록은 해당 column 값이 null이 아닐 때만 property를 set하는 가드다. 결과적으로 missing data에 resilient하면서 기존 값을 null로 덮어쓰지 않는다. RDF의 전역 predicate 모델에서는 이런 per-edge 부분 갱신이 부자연스럽다.

7. Inference: KG의 진짜 가치

KG의 가장 강력한 활용은 저장된 정보를 그대로 조회하는 것이 아니라, logical rule 기반의 deductive reasoning으로 implicit 정보를 끌어내는 것이다.

예를 들어 "내분비계 이상(HP:0000818)을 동반하는 disease는 무엇인가"라는 질의를 생각해보자. 이 phenotype에 직접 annotation된 disease만 반환하면 답이 충분치 않다. 임상의는 갑상선 등 더 구체적인 hierarchy 하위의 phenotype까지 묶어 보고 싶어한다. HPO의 계층 구조가 ontology 안에 박혀 있기 때문에, subclass를 따라 traversal하는 단일 query로 implicit한 연결까지 회수할 수 있다.

이 지점이 단순 검색·문서 retrieval과 KG가 갈리는 지점이다. 계층·관계가 schema에 명시적으로 표현되어 있기 때문에, 질의 시점에 추론이 가능해진다.

참고 자료

• Knowledge Graphs and LLMs in Action. Manning, 2024 — Chapter 3: Create your first knowledge graph from ontologies

임베딩은 의미를 고차원 공간에 새기고, 그래프는 그 사이를 잇는다. Neo4j Vector Index는 두 검색 방식을 한 데이터베이스 안에서 결합한다.

Neo4j Vector Index는 vector 기반 유사도 검색과 graph traversal을 하나의 storage 계층에서 통합 운용할 수 있게 만든 indexing 구조다.

1. Vector Index가 필요한 이유

전통적인 데이터베이스의 index는 key·attribute 기반으로 탐색을 가속한다. 그러나 데이터가 고차원 vector로 표현되는 순간, 이러한 색인 방식은 적합하지 않다. 임베딩 공간에서 의미가 가까운 항목을 찾으려면 "정확히 일치하는 key"가 아니라 "공간상 가까운 좌표"를 질의해야 한다.

Vector index는 고차원 공간에서의 공간적 근접성(spatial proximity) 을 효율적으로 탐색하도록 설계된 특수 index다. 일반 index가 정렬된 key를 따라 트리 구조로 좁혀가는 것과 달리, vector index는 임베딩 벡터 사이의 거리 또는 각도를 기준으로 유사 항목을 회수한다.

이 구조의 실질적 이점은 두 가지다. 첫째, 대규모 임베딩을 메모리에 모두 적재하지 않고 데이터베이스에 위임할 수 있다. 둘째, Neo4j의 경우 vector 질의를 graph 질의와 동일한 storage 계층에서 처리하므로, 유사 문서 회수 후 그 문서가 속한 entity의 관계망을 곧바로 traversal 할 수 있다.

2. Neo4j Vector Index 생성

Neo4j에서 vector index는 Cypher의 procedure 호출로 생성된다. 다음은 Tesla 관련 텍스트를 위한 index 정의 예시다.

CALL db.index.vector.createNodeIndex(
    'TeslaEmbeddings',   // index 이름
    'Chunk',             // node label
    'tesla_embedding',   // property 이름
    1536,                // vector 차원 수
    'cosine'             // similarity metric
)

각 parameter의 역할은 다음과 같이 정리된다.

vector 차원은 임의로 정할 수 없다. 임베딩 모델이 출력하는 차원과 정확히 일치해야 하며, 모델을 교체하면 index도 재생성해야 한다.

3. Cosine Similarity와 거리 척도

NLP 임베딩 분석에서 cosine similarity가 표준에 가까운 이유는 벡터의 크기(magnitude)가 아니라 방향(direction) 만으로 의미적 유사성을 판정하기 때문이다. 두 벡터를 고차원 공간에 투영했을 때 사잇각이 작을수록 유사하다고 본다.

cosine similarity 외에도 Euclidean distance, dot product 등이 사용 가능하지만, 텍스트 임베딩은 일반적으로 정규화되어 있어 cosine이 가장 안정적인 결과를 보인다. 문서의 길이가 임베딩 norm에 영향을 주는 경우, 크기 정보를 무시하는 cosine이 노이즈에 덜 민감하다.

4. Chunking과 Overlap

LLM과 임베딩 모델은 입력 길이에 한계를 가진다. 따라서 긴 문서는 작은 단위로 분할해 각각 임베딩한다. 이때 두 가지 parameter가 결정적이다.

• chunk_size: 한 chunk에 포함되는 token 길이. 너무 작으면 의미 단위가 끊기고, 너무 크면 임베딩이 평균화되어 검색 정밀도가 떨어진다.
• chunk_overlap: 인접한 chunk 사이에서 겹치는 token 수. 문장 경계에서 끊긴 context를 보존하기 위한 장치다.

chunking은 단순한 전처리 단계로 보이지만, RAG 품질의 상한을 결정짓는 변수다. chunk가 의미 단위와 어긋나면, 아무리 좋은 retrieval 알고리즘도 잘못된 단위로 검색하게 된다.

5. Embedding 생성과 저장

Cypher로 index를 만든 뒤, 실제 embedding 적재는 LangChain의 Neo4jVector와 같은 wrapper로 처리할 수 있다.

hybrid_db = Neo4jVector.from_documents(
    docs,
    OpenAIEmbeddings(),
    url=url,
    username=username,
    password=password,
    index_name="TeslaEmbeddings",
    search_type="hybrid"
)

여기서 search_type="hybrid"는 vector 유사도와 keyword 검색(전문 검색)을 결합하는 옵션이다. 임베딩 검색은 의미적으로 가까운 항목을 잘 찾지만, 고유명사나 정확한 ID 매칭에는 약하다. hybrid 모드는 두 약점을 상호 보완한다.

6. Vector 검색과 Graph Traversal의 결합

Neo4j Vector Index의 진짜 가치는 vector 검색 결과를 곧바로 graph 질의와 이어 붙일 수 있다는 점이다. 일반적인 vector store는 유사 chunk를 반환하면 거기서 끝나지만, Neo4j는 회수된 Chunk node가 어떤 Document, Entity, Topic 등과 연결되어 있는지 같은 질의 안에서 추적할 수 있다.

비슷한 문서를 찾는 작업은 vector가 강점을, 그 문서를 둘러싼 관계를 따라가는 작업은 graph가 강점을 가진다. Neo4j Vector Index는 이 둘을 단일 backend에서 묶어 결과를 풍부하게 만든다.

7. 한계와 트레이드오프

vector index를 graph 데이터베이스 안에 통합하는 설계는 여러 장점을 제공하지만, 다음과 같은 비용을 동반한다.

첫째, 임베딩 모델 종속성. index 차원은 모델에 묶여 있다. embedding 모델을 1536차원에서 3072차원으로 교체하려면 index를 재생성하고 전체 chunk를 다시 임베딩해야 한다. 모델 ABI가 깨지는 셈이다.

둘째, chunking 전략의 비가역성. 한 번 chunk_size·overlap을 정해 임베딩을 만들고 나면, 이를 변경하려면 전체 데이터를 재처리해야 한다. 운영 중인 시스템에서 chunking 정책을 바꾸는 것은 단순한 hyperparameter 튜닝이 아니라 데이터 마이그레이션 작업이 된다.

셋째, vector 검색과 graph 검색의 인지 부담. 두 검색 방식을 결합하면 시스템은 강력해지지만, 질의를 설계하는 쪽의 책임도 커진다. 어느 단계까지를 vector로 회수하고, 어디서부터 graph traversal로 정밀도를 높일 것인가는 도메인별로 답이 다르다. 이 결정이 잘못되면 두 방식 모두의 장점을 잃는다.

8. 실무 적용 시 고려사항

운영 환경에서 Neo4j Vector Index를 도입할 때 우선 점검할 항목은 데이터 volume과 갱신 주기다. 임베딩 생성 비용은 token 수에 비례하므로, 정적 corpus에서는 한 번 적재하고 끝나지만 매일 수만 건의 문서가 추가되는 환경에서는 embedding API 호출 비용이 빠르게 누적된다. 이 경우 변경분만 재임베딩하는 incremental indexing 전략이 필수다.

또한 hybrid search를 활성화할 때는 keyword index와 vector index 중 어느 쪽 결과를 우선할지 가중치 조정이 필요하다. 두 결과의 점수 척도가 다르기 때문에, 단순 합산은 한쪽 신호를 압도하기 쉽다. 정규화 또는 reciprocal rank fusion 같은 결합 방식을 검토해야 한다.

참고 자료

• Graph Data Science with Python and Neo4j. Chapter 7: Neo4j Vector Index and Retrieval-Augmented Generation (RAG).

Neo4j 기반 그래프 분석 환경은 네 가지 축으로 구성된다. 데이터베이스 엔진, 플러그인 라이브러리, 클라이언트 인터페이스, 언어 바인딩이 그것이다.

각 구성 요소는 독립적으로 교체 가능하다. 실행 환경(Desktop vs Aura), 플러그인의 활성화 여부, 접근 인터페이스(Browser vs Python)는 분석 목적에 따라 조합된다.

2. Cypher Query Language

Neo4j의 질의 언어는 Cypher이다. SQL이 테이블 기반 관계 대수를 표현하기 위해 설계된 것처럼, Cypher는 그래프 패턴 매칭을 표현하기 위해 설계되었다. 핵심 문법은 ASCII art 형태의 패턴 표현으로, 노드는 (), relationship은 -[]->로 표기한다.

// 노드 생성
CREATE (alice:Person {name: 'Alice', age: 30})

// 관계 패턴 매칭
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
WHERE m.released > 2000
RETURN p.name, m.title

// 다단계 traversal
MATCH (p:Person)-[:FRIEND]->(:Person)-[:FRIEND]->(fof:Person)
WHERE p.name = 'Alice'
RETURN DISTINCT fof.name

세 번째 예시는 그래프 DB의 강점을 단적으로 드러낸다. "친구의 친구"를 찾는 질의가 RDB에서는 self-join 두 번을 요구하지만, Cypher에서는 패턴 자체로 자연스럽게 표현된다. 이 표현력 차이가 multi-hop traversal이 빈번한 도메인에서 그래프 DB를 선택하게 만드는 핵심 근거이다.

3. GDS와 APOC: 두 가지 핵심 플러그인

기본 Neo4j 엔진은 그래프 저장과 Cypher 질의 실행을 담당한다. 그 위에서 데이터 분석과 운영 편의를 제공하는 두 라이브러리가 있다.

GDS는 분석가·데이터 과학자의 도구이고, APOC는 데이터 엔지니어의 도구라는 단순화된 구분이 가능하다. 다만 실무에서는 두 라이브러리를 함께 활성화하는 것이 일반적이다. 외부 데이터 소스로부터 그래프를 적재할 때 APOC가, 적재된 그래프 위에서 분석을 수행할 때 GDS가 동원되기 때문이다.

GraphRAG 맥락에서는 GDS의 임베딩 알고리즘(node2vec, FastRP)이 특히 중요하다. 그래프 구조를 벡터 공간으로 사용하여 vector similarity search와 결합하는 기반을 제공한다.

4. 실행 환경 선택: Desktop vs Aura

Neo4j는 두 가지 주된 실행 환경을 제공한다. 선택 기준은 학습 목적, 데이터 민감도, 운영 부담 수용 의지에 따라 갈린다.

학습 단계에서는 Desktop이 자유도가 높다. Cypher 콘솔에서 :play movies를 실행하면 People과 Movie를 node로, ACTED_IN·PRODUCED·DIRECTED를 relationship으로 가지는 예제 그래프가 생성되어 즉시 시각적 탐색이 가능하다. 반면 Aura는 환경 구성 부담 없이 바로 시작하려는 경우, 또는 노트북 자원이 제한된 경우 적합하다.

5. Python-Neo4j 연결과 Bolt Protocol

Python에서 Neo4j에 접근할 때는 graphdatascience 라이브러리를 통한 API 연결이 표준이다.

from graphdatascience import GraphDataScience

# Desktop 로컬 연결
URI = "bolt://localhost:7687"
AUTH = ("neo4j", "your_password")

gds = GraphDataScience(URI, auth=AUTH)

# 연결 확인 및 Cypher 실행
result = gds.run_cypher("""
    MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
    RETURN p.name AS actor, count(m) AS movie_count
    ORDER BY movie_count DESC
    LIMIT 5
""")
print(result)

URI에 사용된 Bolt protocol은 Neo4j 전용 binary protocol이다. HTTP/HTTPS 대비 두 가지 차별점이 있다. 첫째, 그래프 데이터 전송에 최적화된 binary 직렬화로 전송 효율이 높다. 둘째, TLS 암호화를 기본 지원하여 별도 설정 없이 보안 통신이 성립한다. Aura 환경에서는 neo4j+s:// 스키마가 사용되며 +s는 암호화 활성화를 의미한다.

연결이 성립하면 Python 측에서는 Neo4j를 사실상 원격 그래프 분석 엔진으로 활용할 수 있다. node·relationship의 CRUD, Cypher 질의 실행, GDS 알고리즘 호출이 모두 가능하다.

6. 한계와 트레이드오프

본 챕터의 환경 구성 자체에서 도출되는 한계는 다음과 같다.

Desktop 환경의 확장성 제약. 로컬 머신 자원에 직접적으로 종속된다. 수백만 노드 규모를 넘어서면 메모리·디스크 I/O 병목이 발생하며, 학습 목적을 넘어선 분석에는 부적합하다. 본 챕터에서도 on-premise·cloud 클러스터 구성은 책의 범위 밖으로 명시되어 있다.

Aura 무료 티어의 운영 한계. 관리형 환경의 편의성은 데이터 크기·연결 수·플러그인 가용성에 대한 제약과 교환된다. 특히 GDS의 일부 고급 알고리즘은 유료 티어에서만 활성화되는 경우가 있어, 분석 깊이를 추구하는 단계에서는 검토가 필요하다.

플러그인 의존성. GDS와 APOC는 사실상 필수에 가깝지만, Neo4j 코어와 분리된 라이브러리이다. Neo4j 버전 업그레이드 시 플러그인 호환성을 별도로 확인해야 하며, 클라우드와 로컬에서 사용 가능한 함수 집합이 미묘하게 다를 수 있다.

Bolt protocol의 락인. Bolt는 Neo4j 생태계에 특화된 protocol이다. 표준 SQL/HTTP 기반 도구체인과의 통합이 직접적이지 않으며, BI 도구나 오케스트레이션 시스템과 연결할 때 별도의 어댑터·드라이버가 요구된다.

7. 실무 적용 시 고려사항

환경 구성 단계에서 결정되는 사항이 이후 분석 흐름 전체에 영향을 미친다.

첫째, 학습과 운영 환경을 일찍부터 분리한다. Desktop에서 작성한 Cypher와 Python 스크립트가 Aura에서도 동작하는지를 초기에 검증해두면, 이후 운영 환경으로의 이행이 매끄럽다. URI 문자열만 환경 변수로 분리하는 것이 일반적인 패턴이다.

둘째, GDS·APOC를 처음부터 함께 활성화한다. 학습 단계에서는 코어 Cypher만으로 충분해 보이지만, GraphRAG로 진입하는 순간 임베딩 생성·외부 데이터 통합·배치 처리가 필요해진다. 사후에 플러그인을 추가하면 기존 데이터 구조를 재검토해야 하는 경우가 발생한다.

셋째, 자격 증명 관리를 코드 외부로 분리한다. URI·사용자명·비밀번호를 스크립트에 직접 작성하는 패턴은 학습용으로만 허용된다. .env 파일 또는 시크릿 매니저를 사용하는 습관이 운영 단계에서 필수가 된다.

결론: Desktop은 학습의 자유도, Aura는 운영의 편의를 제공하며 — 어느 쪽을 선택하든 GDS·APOC·Bolt라는 세 축이 이후 GraphRAG 실습의 공통 기반이 된다.

참고 자료

• Graph Data Science with Python and Neo4j. Chapter 2: Getting Started with Python and Neo4j.

그래프 기반 시스템을 다루기에 앞서, 그래프 자료구조의 정의를 명확히 할 필요가 있다. 관계 자체를 일급 객체로 취급하는 데이터 모델이 그래프이다.

이산수학과 그래프 이론에서 그래프는 객체(node)와 그 객체들 사이의 연결(relationship)로 구성된 구조로 정의된다. 객체는 vertex, node, point 등으로 불리며, 객체 사이의 연결은 edge, relationship, link로 불린다. 본 글에서는 객체를 node, 연결을 relationship으로 통일한다.

가장 직관적인 예시는 사회 관계망이다. 한 사람을 node로, 두 사람 사이의 친구 관계를 relationship으로 표현하면 social graph가 만들어지며, 이를 통해 사람들이 어떻게 상호 연결되어 있고 정보가 어떻게 흐르는지 분석할 수 있다.

Neo4j 같은 그래프 데이터베이스에서는 node뿐 아니라 relationship에도 데이터를 저장할 수 있고, 이를 property라고 부른다. 즉 "Alice와 Bob이 친구다"라는 사실 위에 "2019년부터 친구이며 신뢰도 0.8" 같은 속성을 relationship 자체에 부여할 수 있다. 관계형 DB가 join table에 별도 컬럼을 두어 흉내내는 것과 달리, 그래프 DB는 이를 구조적으로 자연스럽게 표현한다.

2. Neo4j: native graph database

Neo4j는 native graph database로 분류된다. 여기서 native라는 표현이 핵심이다. 그래프 자료구조와 그 위에서 수행되는 알고리즘·연산을 처리하기 위해 처음부터 설계되었다는 의미이며, 이는 다른 데이터베이스들이 그래프 모델을 "지원"하는 방식과 구별된다.

저장소 종류를 정리하면 다음과 같다.

Neo4j는 vector database가 아니다. 다만 vector를 저장하고 similarity search를 수행하는 기능을 제공하므로, 그래프 구조와 벡터 검색을 한 시스템에서 결합하려는 경우 선택지가 된다. 이 결합 가능성이 GraphRAG 아키텍처의 기술적 토대가 된다.

Neo4j가 널리 채택되는 이유는 세 가지로 요약된다. 그래프 자료구조에 대한 native 처리, 확장성, 그리고 오픈소스 기반의 활발한 커뮤니티이다. 데이터 포인트 간 연결이 많고 그 연결의 구조 자체를 분석해야 하는 도메인 — 추천, 사기 탐지, 지식 그래프, 네트워크 분석 — 에서 특히 적합하다.

3. 데이터베이스 선택의 의사결정 흐름

저장소 선택은 단일 기준으로 결정되지 않는다. 데이터의 형태와 질의 패턴이 함께 고려되어야 한다.

이 흐름도는 본 챕터에서 다룬 데이터베이스 분류에 기반한 의사결정 보조 도구로 이해하면 된다. 실제 시스템 설계에서는 단일 저장소를 선택하기보다, 그래프 DB와 벡터 DB를 병행 운용하거나 한 시스템 안에서 통합하는 polyglot persistence 전략이 일반적이다.

4. 그래프 시각화 도구 생태계

그래프 데이터의 가치는 시각화를 통해 직관적으로 드러나는 경우가 많다. 본 챕터에서 언급된 주요 도구들은 다음과 같다.

선택 기준은 사용 환경(웹/데스크톱/노트북), 인터랙티브 요구 수준, 그리고 분석 파이프라인과의 통합 여부에 따라 갈린다. 탐색적 분석에는 Gephi, 운영 환경의 대시보드 임베딩에는 D3.js, Neo4j 데이터의 즉시 시각화에는 Hume이 자연스러운 선택이 된다.

5. 한계와 트레이드오프

그래프 데이터베이스가 모든 문제의 해답은 아니다. 본 챕터의 개념에서 도출 가능한 한계는 다음과 같다.

관계가 희박한 데이터에서의 오버헤드. 그래프 DB의 강점은 relationship traversal에 있다. 데이터 포인트 간 연결이 적거나, 분석이 단순 lookup·aggregation 중심이라면 RDB나 document DB 대비 얻는 이점이 작다. 오히려 graph 모델링과 운영 비용이 부담으로 작용할 수 있다.

대규모 분석 워크로드의 한계. Neo4j는 OLTP 성격의 그래프 traversal에 강하지만, 수십억 노드 규모의 그래프 알고리즘 일괄 실행은 별도의 분산 처리 엔진(Spark GraphX, Pregel 계열) 또는 Neo4j Graph Data Science 라이브러리의 클러스터 구성을 요구한다.

의미 기반 검색의 부재. 그래프 traversal은 명시적으로 정의된 relationship을 따라 이동한다. "비슷한 문서 찾기"처럼 의미적 유사도가 핵심인 질의는 vector DB의 영역이다. 이 차이가 vector RAG와 graph RAG를 구분하는 근본 지점이며, 두 접근의 결합이 GraphRAG의 동기가 된다.

6. 실무 적용 시 고려사항

그래프 DB 도입을 검토하는 실무 관점에서 몇 가지 고려사항을 정리한다.

첫째, 도메인의 질의 패턴을 먼저 분석한다. "고객 A와 연결된 모든 거래의 2단계 거래 상대를 찾으라"처럼 multi-hop traversal이 반복된다면 그래프 DB가 적합하다. 반면 "지난달 매출 합계"처럼 집계가 주된 질의라면 데이터 웨어하우스가 우선이다.

둘째, 단일 저장소 선택을 강제할 필요가 없다. 운영 데이터는 RDB에 두고, 그래프 분석용 view를 Neo4j에 별도 구축하거나, similarity search를 위해 vector DB를 병행하는 구성이 일반적이다. 본 시리즈 후속편에서 다룰 GraphRAG는 이 polyglot 전략의 구체적인 한 형태이다.

셋째, 그래프 모델링은 스키마 설계 단계에서 결정된다. 무엇을 node로 두고 무엇을 relationship으로 둘지, 어떤 property를 어디에 부여할지는 이후 질의 성능과 분석 가능성을 좌우한다. 관계형 모델링과 사고방식이 다르므로 초기 학습 비용이 발생한다.

결론: 그래프 데이터베이스는 "연결 그 자체가 데이터인 도메인"에서 가장 큰 가치를 만들어내며, vector·관계형 저장소와 경쟁하기보다 보완하는 위치에 놓일 때 GraphRAG로 이어지는 자연스러운 토대가 된다.

참고 자료

• Graph Data Science with Python and Neo4j. Chapter 1: Introduction to Graph Data Science.

이 문제, 사실 AI가 멍청해서가 아닙니다. AI가 우리 자료를 어떻게 읽어야 할지 모르기 때문입니다. 오늘은 이 문제를 정공법으로 풀어보려는 오픈소스 프로젝트, SEOCHO(서초)를 함께 살펴보겠습니다.

한 줄 요약: 흩어진 문서를 '연결된 지식'으로 만들고, AI 에이전트가 안전하게 꺼내 쓰게 도와주는 미들웨어.

1. 📚 SEOCHO가 뭐하는 애야?

SEOCHO는 한마디로 "도서관 사서" 같은 존재입니다.

도서관에 책이 수만 권 있어도, 사서가 분류하지 않으면 그냥 종이 더미일 뿐이지요. 사서는 책마다 "이건 소설, 저건 역사책, 이 작가는 저 작가의 제자"라는 식으로 기준에 맞춰 정리해둡니다. 그래야 누군가 와서 "조선시대 여성 작가 책 보여주세요"라고 했을 때 정확히 꺼내올 수 있습니다.

SEOCHO가 하는 일도 똑같습니다. 다만 정리 대상이 책이 아니라 회사 문서·계약서·보고서고, 손님이 사람이 아니라 AI 에이전트(=시키는 일을 알아서 처리해주는 AI 일꾼)라는 점이 다를 뿐입니다.

여기서 핵심 단어 두 개만 짚고 가겠습니다.

• 온톨로지(Ontology): 우리 분야에서 무엇을 무엇이라고 부를지 미리 정해둔 사전입니다. 예를 들어 "직원은 회사에 소속되고, 회사는 제품을 판매한다" 같은 규칙을 적어둔 약속집이죠.
• 그래프 데이터베이스: 정보를 점(=대상)과 선(=관계)으로 연결해서 저장하는 창고입니다. 마치 사람 관계도처럼요.

SEOCHO는 이 두 개를 묶어서, "흩어진 문서를 연결된 지식으로 만들고, AI가 안전하게 꺼내 쓰게" 도와주는 도구입니다. 만든 분은 GraphRAG 분야의 멘토 정이태(@tteon) 님이고, MIT 라이선스로 누구나 자유롭게 쓸 수 있습니다.

2. 🎯 어디에 쓰이는데?

말로만 들으면 좀 추상적이죠. 실제 시나리오 3개로 풀어보겠습니다.

(1) 💰 금융 — 계약서·채권 분석

은행에서 일한다고 상상해보겠습니다. 채권 계약서 수백 장에서 "이 채권의 발행자가 누구고, 만기는 언제고, 담보는 뭐고…" 같은 정보를 뽑아야 합니다. 그런데 금융 업계에는 이미 FIBO라는 국제 표준 사전(=Financial Industry Business Ontology)이 있습니다. SEOCHO는 이 FIBO를 그대로 가져다 적용할 수 있습니다. "처음부터 우리 회사 사전을 만드세요"가 아니라, 이미 검증된 업계 표준을 바로 쓸 수 있다는 점이 강점입니다.

(2) 🏢 사내 지식 관리 — 부서 자동 연결

"마케팅팀이 작년에 진행한 캠페인 중에 법무팀 검토를 받은 게 뭐였지?" 이런 질문, 사람이 답하려면 메일 뒤지고 슬랙 검색하고 난리도 아닙니다. SEOCHO는 문서들을 미리 그래프로 엮어두기 때문에 "마케팅팀 → 캠페인 → 법무 검토" 라는 관계를 따라가서 답을 찾아줍니다. 부서 간 협업 흔적이 자동으로 연결되는 셈입니다.

(3) 🔬 연구·컴플라이언스 — 출처 추적

논문이나 규제 문서를 다룰 땐 "그래서 그 주장이 어느 문서 몇 페이지에 나왔어?"가 정말 중요합니다. SEOCHO는 답변마다 출처를 추적할 수 있도록 흔적(trace)을 남깁니다. AI가 그럴듯하게 지어내는 것이 아니라, "이 답은 이 문서에서 나왔습니다"라고 보여줄 수 있는 구조입니다.

3. 🗺️ VectorRAG vs GraphRAG — 왜 그래프인가?

여기서 잠깐, 비슷한 기술인 VectorRAG와 비교해보겠습니다. 둘 다 "AI에게 우리 자료 알려주기" 기술이지만 접근 방식이 다릅니다.

VectorRAG는 카드 더미를 빠르게 뒤지는 방식입니다. "계약"이라는 단어와 비슷한 문장을 휙 찾아주는 데는 강합니다. 하지만 "A 회사가 B를 인수했고, B는 C를 인수했는데 그럼 A가 결국 가진 자회사는?" 같이 관계를 따라가야 답이 나오는 질문에서는 헷갈리기 시작합니다.

GraphRAG는 지하철 노선도처럼 점과 선을 따라갑니다. 강남역에서 시청역 가는 길이 노선도에 그려져 있듯, 회사·인물·계약 사이의 관계를 따라 답을 추론할 수 있습니다. SEOCHO는 이 그래프 방식을 채택해서, 단순 검색을 넘어 "이어진 지식"을 다룰 수 있게 만들어줍니다.

4. ⚙️ SEOCHO의 작동 방식 4단계

저장소에 있는 흐름도를 일상 언어로 풀어보겠습니다. 이번에도 도서관 사서 비유를 그대로 가져갈게요.

📄 (1) 내 문서 입력 → 사서에게 책 한 박스를 통째로 가져다주는 단계입니다. PDF든 마크다운이든 CSV든, "이거 정리해주세요" 하고 던져주면 됩니다.

🔍 (2) 추출 → 사서가 책을 한 권씩 펼쳐서 "저자는 누구, 주제는 뭐, 등장인물은 누구"를 메모하는 단계입니다. SEOCHO에서는 LLM(=대형 언어 모델, 즉 GPT 같은 AI)이 이 일을 합니다. 문서에서 핵심 정보를 자동으로 뽑아내죠.

✅ (3) 검증 → "이 책은 분명 소설이라고 했는데 왜 저자 자리에 출판사 이름이 적혀 있지?" 같은 오류를 잡아내는 단계입니다. 미리 정해둔 온톨로지(=사전)와 어긋나는 정보가 들어오면 걸러줍니다. 잘못된 정보가 그대로 저장되는 사고를 막아주는 안전장치입니다.

🗄️ (4) 그래프 DB에 저장 → 💬 (5) 질문하면 답변 → 검증을 통과한 정보만 그래프 데이터베이스에 차곡차곡 쌓입니다. 그러고 나면 누군가 "올해 우리가 인수한 회사 알려줘"라고 물었을 때, 사서(=SEOCHO)가 정리된 노선도를 따라 정합성이 보장된 답을 가져다줍니다.

5. 💻 실제 코드는 얼마나 간단한가?

여기서 짧게 코드 한 토막만 보고 가겠습니다. 비개발자라면 "아 이 정도면 개발자 한 명한테 부탁해서 며칠 안에 시도해볼 수 있겠구나" 정도로만 느끼시면 됩니다. 저장소 README의 hello world 예제를 그대로 가져왔습니다.

ontology = Ontology(...)              # 1. 우리 도메인의 '단어장'을 만들고
s = Seocho.local(ontology)            # 2. SEOCHO에 넘겨주고
s.add("마리 퀴리는 파리 대학교에서 일했다.")  # 3. 문장 하나 던져주면
print(s.ask("마리 퀴리는 어디서 일했나요?"))   # 4. 자연스럽게 답해줍니다

핵심은 정말 4줄이라는 점입니다. 사전을 정의하고, 도구에 넘기고, 문서를 넣고, 질문하면 끝. 별도의 서버 설치도 필요 없습니다. 내 노트북 안에서 그대로 돌아갑니다.

6. ⭐ 무엇이 차별점인가?

비슷한 도구가 많은데 SEOCHO만의 차별점은 뭘까요? 세 가지로 정리해보겠습니다.

(1) 온톨로지 우선(Ontology-first) — 일반 RAG는 즉흥적입니다. AI가 그때그때 알아서 해석합니다. SEOCHO는 다릅니다. 먼저 약속을 정합니다. "우리 회사에서 '고객'은 이런 뜻이고, '계약'은 이런 속성을 가진다"라고 사전에 합의해두기 때문에, 부서마다 다른 해석으로 헷갈릴 일이 줄어듭니다.

(2) 검증 가능(Verifiable) — 모든 답변에 출처와 흔적이 남습니다. AI가 "이 답은 어디서 나왔어?"라는 질문에 "이 문서 이 위치에서 나왔습니다"라고 답할 수 있다는 뜻입니다. 컴플라이언스가 중요한 회사일수록 이 점이 결정적입니다.

(3) 로컬 우선(Local-first) — 데이터를 외부 클라우드로 보내지 않고 내 컴퓨터 안에서 그대로 돌릴 수 있습니다. 회사 기밀 문서를 외부 서비스에 올리기 부담스러운 환경에서 특히 매력적인 부분입니다.

7. 🌱 마무리 — 누가 써보면 좋을까?

다음과 같은 분이라면 한번 살펴볼 만합니다.

• 사내에 흩어진 문서를 AI로 연결해보고 싶은 기획자·PM
• 출처가 명확해야 하는 영역에서 일하는 금융·법무·연구 직군
• VectorRAG는 써봤는데 "관계 질문"에 약해서 답답했던 개발자

흩어진 문서가 '연결된 지식'으로 변하는 순간, AI는 비로소 우리 회사를 이해하기 시작합니다.

저장소: https://github.com/tteon/seocho

Prompt Engineering과 Fine-tuning을 두 축으로 LLM 기반 Text-to-SQL의 전체 파이프라인을 체계화한 ACM Computing Surveys 서베이

0. 논문 개요

0.1 한눈에 보기

0.2 사전 지식

이 서베이를 효과적으로 읽기 위해 필요한 개념을 정리한다.

• Prompt Engineering: 모델 파라미터를 갱신하지 않고 입력 프롬프트만 설계해 LLM 행동을 제어하는 기법.
• Fine-tuning: 사전학습된 LLM을 특정 도메인(여기선 Text-to-SQL)의 데이터로 추가 학습.
• In-Context Learning (ICL): 프롬프트 안에 제공된 예시만으로 새 과제를 학습하는 LLM의 emergent ability.
• Chain-of-Thought (CoT): 추론 과정을 명시적으로 단계별로 풀어내는 프롬프트 패턴.
• Least-to-Most: 복잡한 문제를 더 쉬운 서브문제로 환원해 푸는 프롬프트 전략.
• Self-Consistency / Cross-Consistency: 같은 모델이나 여러 모델이 만든 다수 답안을 투표로 종합.
• LoRA / QLoRA: 일부 파라미터만 학습해 fine-tuning 비용을 줄이는 PEFT 기법.
• Spider, BIRD, Spider 2.0: 각 시대를 대표하는 Text-to-SQL 벤치마크.
• Schema Linking: NL의 표현을 DB의 테이블·컬럼으로 매핑하는 핵심 단계.

0.3 논문 구조

1. Abstract & Introduction

1.1 논문이 풀고자 하는 문제

이 서베이가 답하려는 질문은 한 줄로 요약할 수 있다.

LLM 시대에 Text-to-SQL을 푸는 방법은 어떻게 분류·이해해야 하며, 각 방법은 언제 어떻게 써야 하는가?

저자들은 LLM 활용을 프롬프트 엔지니어링과 파인튜닝 두 갈래로 명확히 가르고, 각 갈래의 전체 파이프라인을 체계화한다. 이는 두 갈래가 단순한 alternative가 아니라 trade-off 관계임을 부각한다.

1.2 기존 접근의 한계

전통적 Text-to-SQL은 두 흐름이 있었다.

저자들은 전통적 방법과 LLM 기반 방법의 차이를 두 가지로 압축한다.

특히 "학습 없이도 가능"은 LLM의 instruction-following 능력에서 나오는 본질적 변화다. 데이터 라벨링 비용·재학습 비용을 거의 0으로 만들 수 있다는 의미다.

1.3 이 논문의 기여

저자들이 명시한 기여는 다음과 같다.

1. 체계적 분류 체계 제시: Prompt Engineering의 3단계(pre/inference/post)와 Fine-tuning의 4축(목표·방법·데이터·평가)을 격자로 정리.
2. 각 절 끝의 Key Takeaways: 단순 정리가 아닌 실무 적용 가능한 요약을 명시. 각 섹션의 마지막에 "이것만은 챙겨라"를 박스로 제시한다.
3. 모델 사용 트렌드 분석: 28개 LLM의 사용 빈도와 시간에 따른 변화를 정량 분석. 클로즈드와 오픈소스의 비중 변화가 두드러진다.
4. 세 벤치마크 비교 분석: Spider 1.0, BIRD, Spider 2.0의 리더보드 데이터를 직접 비교하며 트렌드를 도출.
5. 실용적 미래 방향: 프라이버시, 복잡 스키마, 도메인 지식, 자율 에이전트, 데이터 거버넌스의 5가지 축으로 미래 도전 정리.

1.4 논문의 위치

이 서베이는 같은 시기 발표된 다른 LLM Text-to-SQL 서베이들[43, 68, 139, 147]과 차별화된다. 특히 Liu et al.의 HKUST 서베이(2024)가 모듈러 시스템 관점이라면, 이 서베이는 Prompt Engineering vs Fine-tuning의 이항 대립을 강하게 밀고 나간다. 모듈을 잘게 쪼개기보다는, 실무자가 어느 갈래로 갈지 의사결정하는 데 도움을 주는 구조다.

2. Overview: LLM과 LLM 기반 Text-to-SQL

2.1 LLM의 두 emergent ability

LLM은 PLM의 단순 확장이 아니라 emergent abilities를 갖춘 새로운 패러다임이다. 본 논문은 두 가지를 강조한다.

• Few-shot learning: 프롬프트에 몇 개 예시만 주면 새 과제를 수행
• Instruction following: 자연어 지시만으로 unseen task에 적응

이 두 능력이 Text-to-SQL에서 특히 강력하다. 왜냐하면 Text-to-SQL은 (a) 도메인마다 스키마가 달라 학습 데이터가 부족하고 (b) 자연어 지시로 SQL 작성 규칙을 알려주기 쉬운 과제이기 때문이다.

2.2 자기회귀 디코딩 관점

논문은 LLM의 작동을 다음 수식으로 형식화한다.

$$ y_t = \arg\max P(y_t \mid y_{1:t-1}, x) $$

여기서 $x$는 프롬프트, $y_t$는 다음 토큰. 이 수식의 함의는 프롬프트 설계가 곧 출력 분포 설계라는 점이다. 즉 프롬프트 엔지니어링은 단순한 트릭이 아니라 분포를 형성하는 행위다.

2.3 왜 LLM 기반 Text-to-SQL인가

저자들은 세 가지 이유를 든다.

특히 일반화 능력이 결정적이다. 새 도메인마다 학습할 필요 없이 프롬프트만 바꾸면 된다는 점은 산업적으로 매우 큰 가치다.

2.4 전체 파이프라인

논문은 LLM 기반 Text-to-SQL을 두 갈래로 분리한다.

이 분기는 단순한 기술 선택이 아니라 데이터·자원·프라이버시 제약에 따른 의사결정이라는 시각이 깔려 있다.

3. 벤치마크와 평가 지표

3.1 벤치마크 분류

논문은 벤치마크를 LLM 등장 이전과 이후로 가른다.

LLM 시대 벤치마크는 다음 새 도전에 초점을 맞춘다.

• 도메인 특화 지식: ScienceBenchmark는 천체물리학, 암 연구, 정책 결정 같은 실제 도메인에서 SQL 전문가와 협업해 만들었다. 기존 데이터셋의 한계, 즉 일반 도메인에서 학습한 시스템이 특수 도메인에서 곧바로 무너진다는 문제를 정면으로 본다.
• 더티 데이터·도메인 지식·SQL 효율: BIRD는 33.4GB 규모, 95개 DB, 37개 도메인. GPT-4가 54.89%인 반면 인간은 92.96%로, 격차가 여전히 크다.
• 17종 견고성 perturbation: Dr.Spider는 가장 강한 모델조차 평균 14% 성능 하락, 가장 어려운 perturbation에선 50.7% 하락을 보인다.
• 엔터프라이즈 워크플로우: Spider 2.0은 BigQuery, Snowflake, PostgreSQL 같은 실제 클라우드 DB. 1,000개 이상 컬럼을 가진 DB도 포함.
• 오류 진단: BIRD-Critic 1.0은 SQL 생성을 넘어 SQL 디버깅 능력을 평가. 가장 강한 o1-preview조차 38.5% pass rate로, 이 새 axis는 모델들에게 어렵다.

3.2 평가 지표

논문은 다섯 지표를 다룬다.

Exact Set Match Accuracy (EM): SQL 절 단위 문자열 일치. 같은 의미를 다른 표현으로 쓴 SQL을 모두 틀렸다고 처리해 과소평가 위험이 있다.

Execution Accuracy (EX): 실행 결과 비교. 의미가 다른데 우연히 같은 결과를 내는 경우 과대평가 위험이 있다.

Test-suite Accuracy (TS): 무작위 생성된 다수 DB 중 코드 커버리지 높은 작은 테스트 스위트로 평가. 의미적 정확도의 strict upper bound를 측정한다.

Valid Efficiency Score (VES): BIRD에서 도입한 효율 지표.

$$ \text{VES} = \frac{\sum_{n=1}^{N} \mathbf{1}(V_n, \hat{V}_n) \cdot R(Y_n, \hat{Y}_n)}{N}, \quad R(Y_n, \hat{Y}_n) = \sqrt{\frac{E(Y_n)}{E(\hat{Y}_n)}} $$

여기서 $\mathbf{1}$은 정답일 때만 1을 반환하고, $R$은 실행 시간 비율의 제곱근이다. 정확하면서도 빠른 SQL을 보상한다.

ESM+: EM의 개선판. LEFT/RIGHT JOIN, OUTER/INNER JOIN, DISTINCT, LIMIT, IN, foreign key, schema check, alias 등에 대한 새 규칙을 추가해 false positive와 false negative를 줄인다.

지표들의 trade-off를 정리하면 다음과 같다.

3.3 벤치마킹 연구

저자들은 서베이 외 벤치마킹 연구들도 정리한다.

• Rajkumar et al.(2022): Codex와 GPT-3로 프롬프트 구성 비교
• DAIL-SQL의 모태가 된 비교 연구: question representation, example selection, organization
• Zhang et al.(2024): Text-to-SQL, SQL Debugging, SQL Optimization, Schema Linking, SQL-to-Text 5종 과제
• DB-GPT-Hub: 오픈소스 모델 fine-tuning에 특화된 모듈러 코드베이스

저자들은 빠른 모델·기법 변화 때문에 수치 비교는 빠르게 낡는다고 경고한다. 이 경고는 모든 LLM 서베이의 본질적 한계이기도 하다.

4. Prompt Engineering: 3단계 파이프라인

4.1 전체 구조

논문의 핵심 분류다. 전체 파이프라인을 다음과 같이 형식화한다.

$$ \text{pred_SQL} = \text{Post_process}(\text{LLM}(\text{QuestionRep}, \text{Demonstration}, \text{Reasoning})) $$

세 단계를 차례로 풀어본다.

4.2 Pre-processing

4.2.1 Question Representation

질문 자체와 DB 정보를 어떻게 프롬프트로 표현할지 결정하는 단계다. 세 요소로 분해된다.

(a) Layouts: 두 가지가 표준이다.

• OpenAI Template: SQLite 주석 형태로 Table(Column1, Column2, ...) 줄을 나열하고 마지막에 SELECT로 시작
• CREATE TABLE Layout: 실제 DDL인 CREATE TABLE 문으로 데이터 타입과 PK/FK까지 명시

(b) Sample Data: 실제 DB 콘텐츠 몇 행을 함께 제공. SELECT * FROM Table LIMIT 3 같은 형식. 데이터의 형식과 분포를 모델이 이해하게 만든다.

(c) Knowledge: 두 종류다.

• SQL Knowledge: SQL 키워드·문법·작성 관습. 예: C3는 "COUNT(*)는 특정 경우만, LEFT JOIN/IN/OR 피하고 JOIN/INTERSECT 사용, DISTINCT/LIMIT 권장" 같은 명시적 가이드를 프롬프트에 포함
• External Knowledge: 도메인 용어·약어·은어. BIRD의 evidence가 대표적이고, CHESS는 컨텍스트 검색으로 DB 카탈로그·테이블·컬럼의 설명·약어를 가져온다

4.2.2 분석: Layout 선택의 의미

논문이 정리한 실험 결과를 종합하면 다음과 같다.

핵심 통찰은 layout 자체보다 그 안에 든 정보(PK/FK, sample data, knowledge)가 결정적이라는 점이다.

4.2.3 Schema Linking

Pre-processing의 또 다른 핵심 모듈이다. 큰 DB에서 모든 테이블을 프롬프트에 넣을 수 없기 때문에 관련 부분만 추려야 한다.

LLM 기반 접근의 세 갈래:

(1) 단계별 프롬프트: 직접 시키되 효율을 위해 분할

• C3, MCS-SQL: 테이블 → 컬럼 두 단계
• DEA-SQL: 질문 요소 식별 → 스키마 필터링
• CHESS: 컬럼 필터링 → 테이블 선택 → 최종 컬럼 필터링의 3단계
• PET-SQL: 흥미로운 역접근 - 먼저 SQL을 그려보고 그 SQL에서 테이블·컬럼 추출. LLM이 SQL 작성을 schema linking보다 잘한다는 통찰이다
• RSL-SQL: bidirectional, 전체 스키마와 LLM이 만든 SQL 모두 고려
• E-SQL: pre-generated SQL을 NL에 직접 통합

(2) 일반 LLM 기법 활용: few-shot, CoT, self-consistency, fine-tuning

• DIN-SQL: random examples + "Let's think step by step"
• C3, MCS-SQL: self-consistency 투표
• ACT-SQL: 임베딩 모델로 phrase-schema 관계를 식별, CoT 형식의 예시 구성
• SQLfuse: schema linking을 직접 fine-tuning

(3) 전통적 방법과 결합:

• CRUSH4SQL: LLM이 hallucinate한 schema를 기준 삼아 유사도 기반 검색
• OpenSearch-SQL: LLM이 선택한 schema에 vector retrieval로 보완

전통적 접근의 두 갈래:

(a) 유사도 기반: BERT, RoBERTa 같은 PLM으로 query와 schema를 임베딩해 유사도 비교. De-semanticization은 직접 매칭 + DB 값 매칭을 결합

(b) 연결성 기반:

• DBCopilot: DB·테이블 그래프 + Seq2Seq 라우터
• PURPLE: PK-FK 그래프
• SGU-SQL: query-schema 통합 그래프

4.2.4 Distillery의 통찰

흥미로운 반론이 있다. Distillery는 모델의 SQL 생성 능력이 향상될수록 무관한 컬럼이 컨텍스트에 있어도 영향이 줄어든다고 보여준다. 즉 컨텍스트 윈도우가 커지고 모델이 강해질수록 schema linking의 비용 대비 가치가 떨어진다는 것이다. 그럼에도 실서비스 DB는 컨텍스트 한계를 초과하기 때문에 여전히 필요하다.

Key Takeaways

• 대부분의 시스템은 CoT 또는 decomposition을 기본 워크플로우로 채택
• LLM 기반 schema linking의 주류는 단계별 프롬프트와 일반 LLM 기법 활용
• 유사도와 연결성 모두 고려할 가치가 있음

4.3 Inference

4.3.1 Workflow

복잡한 Text-to-SQL을 단발 LLM 호출로 푸는 것은 무리다. 따라서 워크플로우 설계가 중요하다. 네 종류로 분류된다.

(1) Chain-of-Thought (CoT)

전통적 CoT는 "Let's think step by step"으로 추론을 유도한다. Text-to-SQL에 응용된 변형들은 다음과 같다.

• DIN-SQL: 복잡 질의에 대해 인간이 설계한 CoT 단계
• Divide-and-Prompt: 절(clause) 단위 SQL 생성
• CoE-SQL: Chain-of-Edition. 14개 SQL 편집 규칙(SELECT 항목 편집, WHERE 논리 연산자 편집 등)
• ACT-SQL: Auto-CoT - CoT 예시를 자동 생성해 라벨링 비용 감소
• Open-SQL: skeleton 기반 query framework를 중간 표현으로 사용

(2) Least-to-Most

서브문제로의 환원이 핵심이다. CoT가 SQL 자체를 단계화한다면, Least-to-Most는 NL 질문을 더 단순한 질문으로 환원한다. LTMP-DA-GP가 대표 사례로, NL을 분해하고 NatSQL에 매핑한 뒤 SQL로 변환한다.

(3) Decomposition

작업 자체를 여러 LLM 상호작용으로 분해한다. 병렬과 순차 두 형태가 있다.

• DIN-SQL (병렬 분해): SQL을 Easy/Nested Complex/Non-Nested Complex로 분류해 각각 다른 처리
• MAC-SQL (순차 분해): Selector → Decomposer → Refiner 3-agent. Decomposer가 sub-question과 sub-SQL을 만들고 최종 SQL로 통합
• DEA-SQL: Information determination → Classification & Hint → SQL generation → Self-correction → Active learning
• OpenSearch-SQL: Preprocessing → Extraction → Generation → Refinement → Alignment 5모듈
• R³: SQL Writer + 여러 Reviewer의 negotiation 기반 합의

(4) Autonomous Agents

ReAct 프레임워크에 기반한 자율 에이전트. 다른 워크플로우와 차별화되는 핵심은 다음과 같다.

• 다중 턴 상호작용
• 긴 추론 시간
• 장기 기억
• 조건부 종료

대표 사례:

• Spider-Agent (Spider 2.0): 커맨드라인 인터페이스로 DB와 다중 턴 상호작용. 같은 결과를 3번 출력하거나 timeout이면 자동 종료
• REFORCE: self-refinement + 도메인 특화 기법(table compression, format restriction). self-consistency, max iterations, empty result로 종료

4.3.2 워크플로우 비교

4.3.3 Demonstrations

워크플로우와 함께 시연(예시)도 핵심이다. Zero-shot vs Few-shot 분류 위에서 demonstration의 역할은 두 가지다.

(a) 작업 설명 대체: DIN-SQL의 fine-designed 단계처럼 인간 언어로 설명하기 어려운 워크플로우를 예시로 보여준다. BINDER도 SQL+API 호출이라는 확장 언어를 예시로 가르친다.

(b) SQL 코딩 능력 증대: 적절한 예시 선택이 핵심이다. 단순 질문 유사도만으론 부족하다. 같은 의도라도 스키마가 다르면 SQL이 크게 다르기 때문이다.

대표 전략들:

• De-semanticization, Retrieval & Revision, DAIL-SQL, DEA-SQL, PURPLE: 도메인 특화 단어를 마스킹한 skeleton으로 검색. PURPLE은 4단계 SQL skeleton 추상화
• Retrieval & Revision: 원래 질문 + LLM이 단순화한 질문 모두 사용
• DAIL-SQL: 질문 + SQL 모두로 검색. 토큰 비용을 위해 (질문, SQL)만 포함하는 압축 형식 채택
• Open-SQL: 질문 + 스키마 + SQL 모두 사용
• OpenSearch-SQL: mask question similarity
• MCS-SQL: 질문 유사도 + masked 질문 유사도 두 전략 결합
• ACT-SQL: 무작위 + 유사 예시 혼합으로 다양성 확보

Key Takeaways

• 복잡한 워크플로우를 가진 시스템은 demonstration을 task description의 일부로 활용
• Question skeleton이 원본 질문보다 의도를 더 잘 잡음
• 정확도와 토큰 비용 사이의 trade-off는 항상 고려

4.4 Post-processing

4.4.1 Self-Correction

생성된 SQL을 다시 검토해 수정하는 단계다.

• 공백 처리: Generic은 테이블 값의 잉여 공백을 다시 확인
• 재시도: RSL-SQL, OpenSearch-SQL은 빈 결과나 max round까지 재생성
• 스키마 확장 후 재시도: Retrieval 계열은 부분 schema가 실패하면 전체 schema로 재생성
• 에러 로그 활용: DIN-SQL, CHESS, MAC-SQL은 incorrect SQL과 실행 에러 정보를 프롬프트로 주고 재생성
• DEA-SQL: 필드 매칭과 SQL 문법의 오류 포인트별 특화 프롬프트
• SQLfuse SQL Critic: 외부 SQL 지식 베이스 + few-shot ICL로 hindsight feedback

4.4.2 Consistency Methods

Self-Consistency: 같은 LLM이 다양한 SQL을 생성하고 다수결.

• 직접 다수결: Open-SQL, BINDER, C3, DAIL-SQL, CHESS, OpenSearch-SQL 등 다수
• 실행 결과 기반 다수결: PURPLE
• Confidence + 실행 시간으로 선택: MCS-SQL

Cross-Consistency: 서로 다른 LLM/agent가 답을 만들고 비교.

• PET-SQL: 여러 LLM이 낮은 temperature로 SQL 생성 후 실행 결과로 투표
• R³: 다중 agent의 negotiation. Cross-Consistency + Self-Correction의 결합
• CHESS: Self-Correction과 Self-Consistency를 순차 적용

4.4.3 분석

각 방법의 trade-off는 다음과 같다.

Key Takeaways

• Self-Correction은 'refine'(수정)에 강하지만 'critic'(판단)은 탐색 여지
• Self-Consistency는 비용↑이지만 안정적 성능 향상
• Cross-Consistency는 단일 LLM 편향 완화
• 두 가지를 결합하는 것이 promising

5. Fine-tuning

5.1 왜 Fine-tuning인가

저자들은 Fine-tuning이 필요한 이유를 두 가지로 본다.

1. 프라이버시: GPT-4 API는 데이터 유출 위험. 오픈소스를 로컬에서 fine-tuning하면 해결.
2. 성능 보강: 오픈소스 LLM은 SQL 관련 corpus가 적어 그대로는 약하다. Fine-tuning으로 보완.

수식으로 정리하면 다음과 같다.

$$ \min_M \sum_{i=0}^{|\tau|} \text{Loss}(M(q_i, d_i), gt_i) $$

여기서 $\tau = {(q_i, d_i, gt_i)}$는 (질문, DB 정보, 정답 SQL) 데이터셋이다.

5.2 Fine-tuning Objectives

대부분 SQL generation을 직접 fine-tuning한다. 그러나 흥미로운 변형들이 있다.

특히 DELLM은 흥미롭다. SQL을 직접 만드는 게 아니라 질문과 DB 정보로부터 도메인 지식을 생성하는 LLM을 fine-tuning한다. 그리고 그 지식을 다른 SQL 생성 LLM의 프롬프트에 주입한다. 즉 fine-tuning 대상이 SQL이 아닌 외부 지식 생산자가 되는 사례다.

5.3 Training Methods

두 흐름이 있다.

(a) Full Fine-Tuning (FFT): 모든 파라미터를 학습. 자원 많이 필요. MAC-SQL, CodeS, SQL-Palm.

(b) Parameter-Efficient Fine-Tuning (PEFT): 일부 파라미터만 학습.

• LoRA: Transformer 각 층에 trainable rank decomposition matrix 주입. 사전학습 가중치는 frozen
• QLoRA: LoRA + 4-bit NormalFloat + double quantization + Paged Optimizers. 메모리 사용량 감소

PEFT의 장점은 학습 효율, 비용, 그리고 catastrophic forgetting 저항성이다. 후자는 특히 중요하다. FFT는 LLM의 일반 능력을 잊을 위험이 있는데 PEFT는 덜하다.

5.4 Training Data

대부분 Spider/BIRD 학습셋을 그대로 쓴다. 그러나 두 가지 흥미로운 사례가 있다.

(a) FinSQL: 금융 도메인 특화 BULL 벤치마크 구축. Hundsun Technologies의 실제 펀드·주식·거시경제 분석 업무에서 수집. 공개 벤치마크가 산업 특성을 반영하지 못한다는 문제 제기.

(b) CodeS의 두 흐름:

• 일반 능력 강화: 21.5GB(SQL 11GB + NL-to-code 6GB + NL 4.5GB) 수집
• 도메인 적응: 소수의 실제 사용자 질의 + GPT-3.5로 few-shot 합성, SQL 템플릿에 새 도메인 데이터 plug-in

후자는 prompt engineering으로 fine-tuning 데이터를 만든다는 점에서 흥미롭다. 두 갈래가 서로 보완하는 사례다.

5.5 Model Evaluation

평가는 단순한 EX/EM 측정을 넘어서 다음을 다룬다.

• 난이도별 분류 (Spider의 4단계)
• 도메인별 분류 (BIRD의 37개 도메인)
• Perturbation 유형별 (Dr.Spider의 17종)
• 오류 유형별 분석 (schema-linking, JOIN, nested, group by)
• LLM Comparator 같은 모델 간 차이 시각화 도구

5.6 현황과 한계

저자들은 fine-tuning 연구가 prompt engineering보다 적은 이유를 두 가지 든다.

1. API 비용이 낮은 closed-source 모델의 강력한 성능 때문에 prompt engineering이 우세
2. Fine-tuning은 알고리즘적 혁신 포인트가 적음. 학습 기법, base 모델, 데이터 품질이 결정적인데 이는 점진적 발전이다

이 진단은 본 서베이의 prompt engineering 섹션이 fine-tuning보다 훨씬 긴 이유를 설명해준다.

Key Takeaways

• Fine-tuning은 SQL 생성뿐 아니라 워크플로우 각 단계의 성능 강화에 사용 가능
• PEFT(LoRA/QLoRA)가 FFT보다 선호됨
• 공개 벤치마크는 산업 DB 특성 부족
• LLM으로 데이터셋 자체를 만드는 것이 promising

6. Model

6.1 Closed-source Models

GPT-4는 가장 인기 있는 base 모델이다. ~13T 토큰으로 사전학습되었고 약 1.8T 파라미터 / 120 레이어 규모. CodeX는 14K 이상의 Python 코드를 메모리에 갖고 있어 코드 생성에 특화된다.

저자들의 흥미로운 관찰: "As of the time of writing, there is no closed-source LLM specifically for SQL code generation." 두 가지 추측 이유는 다음과 같다.

1. SQL은 비즈니스 데이터의 프라이버시와 얽혀 있어 학습 데이터 확보가 어렵다
2. SQL 전용 모델은 일반화 능력이 떨어질 수 있다

6.2 Open-source Models

오픈소스 모델은 다양한 크기로 제공된다.

• Llama 3: 8B, 70B
• Code Llama: 7B, 13B, 34B, 70B
• DeepSeek: 다양한 버전
• Qwen: 다양한 버전
• SQLCoder: Text-to-SQL 전용. 70B는 GPT-4를, 15B는 GPT-3.5-turbo를 능가하는 새 데이터셋 결과

특히 SQLCoder는 closed-source가 채우지 못한 "Text-to-SQL 전용 모델" 빈 칸을 채우려는 시도다.

6.3 사용 트렌드

논문 Figure 7이 보여주는 흐름을 정리하면 다음과 같다.

저자들은 이를 오픈소스 모델의 파라미터 규모 증가와 fine-tuning을 통한 도메인 적응 가능성이 결합된 결과로 본다. 미래 전망은 가장 강한 closed-source와 가장 강한 open-source가 양강 구도를 형성하리라는 것이다.

Key Takeaways

• Closed-source: 사용 편의성 + 강력한 코드 생성. 하드웨어 부족 사용자에게 적합
• Open-source: 독립 배포 + 프라이버시 + 도메인 fine-tuning 가능
• 선호 시리즈: Closed는 GPT, Open은 DeepSeek/Llama/Code Llama/Qwen
• 오픈소스 사용 빈도가 점차 closed-source와 비등해짐

7. 분석: 세 벤치마크 비교

7.1 평가 방법론

저자들은 Spider 1.0, BIRD, Spider 2.0의 공식 리더보드를 비교 기준으로 삼는다. 다음 5가지 선택 기준을 적용한다.

1. LLM 활용 방법만
2. 방법당 최대 2개 LLM
3. 2022년 이전 모델 제외 (pre-ChatGPT)
4. 비공개 모델 제외
5. 비재현 가능 방법 제외

7.2 Spider 1.0 결과

대부분의 LLM 방법이 EX 80% 이상을 달성. 결론은 명확하다. Spider 1.0의 기본 Text-to-SQL은 이미 LLM에 의해 풀린 문제다. 더 어려운 벤치마크가 필요한 이유다.

7.3 BIRD 결과 분석

여기가 가장 흥미로운 부분이다. 저자들은 두 차원으로 분석한다.

(a) 모델 차원: closed-source와 open-source의 격차가 좁혀짐. Compact + fine-tuning 모델이 거대 LLM에 견줄 만함.

(b) 방법 차원: 같은 LLM 위에서 비교했을 때 상위 시스템들의 공통점은 다음 두 가지다.

Characteristic 1: Inference-time Scaling

• OpenSearch-SQL: 다중 SQL 생성 + correction + self-consistency
• Distillery: iterative correction + self-consistency
• MCS-SQL: schema linking과 SQL 생성 모두에 다중 프롬프트

vs 베이스라인 (DIN-SQL은 단일 step correction, DAIL-SQL은 correction과 consistency 자체가 없음)

Characteristic 2: Enhanced Schema Linking

• Distillery: 모던 LLM이 무관한 컬럼에 관용적이라는 발견 → 컨텍스트가 허용되면 가능한 많은 컬럼 포함 권장
• MCS-SQL: inference-time scaling 자체가 schema linking 탐색 공간 확장

이 두 특성은 "답을 한 번에 잘 맞추려 하기보다, 여러 후보를 만들고 잘 고른다"는 공통 철학을 드러낸다.

7.4 Spider 2.0 결과 분석

Spider 2.0은 현실 엔터프라이즈 워크플로우를 측정한다. 주요 관찰점은 다음과 같다.

• 오픈소스가 여전히 closed-source에 못 미침: 다양한 SQL 방언, 복잡 문법, nested 컬럼 등 실제 엔터프라이즈 복잡성이 작용
• Reasoning-enhanced 모델 우세: o1-preview 같은 추론 강화 모델이 좋은 성과
• Non-agent vs Agent 격차: agent 기반이 큰 차이로 우세

대표 사례는 REFORCE다. 표준 Spider Agent를 다음으로 개선한다.

• table compression (컨텍스트 최적화)
• structured output formatting
• iterative column exploration (스키마 이해 향상)
• parallelized voting + CTE-based resolution의 self-refinement

그러나 SOTA가 31.26%에 그친다. 학술 진보와 실서비스 배포 사이의 큰 격차를 보여준다.

Key Takeaways

• Spider 1.0: 기본 Text-to-SQL은 LLM에 의해 거의 해결
• BIRD: inference-time scaling과 enhanced schema linking이 결정적
• Spider 2.0: agent 기반이 우세, 그러나 절대 성능은 아직 낮음

8. 미래 방향

8.1 오류 분석 정리

기존 연구들의 오류 분류는 다음 5범주로 수렴한다.

평균 비율을 정리하면:

• Schema Linking 29-49%: 가장 큰 오류 원인. 여전히 핵심 개선 대상
• JOIN 21-26%: 멀티테이블 처리의 어려움
• GROUP BY, Nested 각 20% 이하: 상대적으로 작은 비중

각 카테고리 안에서도 wrong column, wrong table, wrong condition 등 세부 분류가 가능하다. DIN-SQL의 경우 SELECT/FROM/WHERE/ORDER BY/GROUP BY 키워드별로 error/redundancy/insufficiency 같은 더 세밀한 분류를 한다.

충격적인 관찰: MAC-SQL이 SPIDER와 BIRD의 정답 자체에 20-30% 오류가 있다고 발견한 점이다. 이는 데이터 클리닝의 필요성을 직접 보여준다.

8.2 다섯 가지 도전과 방향

8.2.1 프라이버시

API 호출 시 프롬프트가 외부 서버로 전송되는 위험. 해결책은 오픈소스 LLM의 사설 배포 + fine-tuning이지만, 다음 문제가 있다.

• 더티 데이터
• LLM의 일반 능력 손상 가능
• catastrophic forgetting

핵심은 고품질 학습 데이터 추출 기법이다.

8.2.2 복잡 스키마와 부족한 벤치마크

저자들이 인용한 Microsoft 사례가 인상적이다. 내부 금융 데이터 웨어하우스는 632개 테이블 + 4,000개 이상 컬럼 + 200개 뷰 + 7,400개 이상 컬럼을 포함한다. 이런 규모에서는 다음 문제가 발생한다.

• Schema linking의 어려움
• LLM 주의력 분산 (토큰 폭증)
• 긴 추론 시간

해결 방향:

• Agent 기반 동적 탐색 (REFORCE, Spider 2.0)
• Self-consistency로 schema linking 오류 감소 (MCS-SQL)
• Dynamic graph attention 같은 새 메커니즘으로 적응형 그래프 표현

기존 벤치마크의 한계도 명확하다. Spider는 너무 단순하고, BIRD조차 실제 규모엔 못 미친다. Spider 2.0이 BigQuery·Snowflake 같은 실제 시스템을 도입해 좋은 방향을 제시한다.

8.2.3 도메인 지식

LLM의 일반 지식만으론 산업 용어·약어·은어를 처리하기 어렵다. 두 갈래가 있고 각각 한계가 있다.

8.2.4 자율 에이전트

ReAct 프레임워크에 기반한 autonomous agent의 부상. 인간이 SQL을 작성하는 방식 자체가 trial-and-error의 반복인데, 이는 agent 모델링에 잘 맞는다.

REFORCE와 Spider 2.0의 Spider-Agent가 첫 사례다. Spider 2.0 리더보드에서 non-agent가 agent 기반보다 현저히 떨어진다는 결과는 이 방향의 잠재력을 보여준다.

8.2.5 데이터 거버넌스

현 데이터셋의 두 한계가 강조된다.

• Ambiguity: 의미적으로 다른 여러 SQL이 같은 NL의 답이 될 수 있음
• Semantic Mismatch: NL이 표현하는 의도를 DB가 (부분적으로) 답할 수 없음

데이터 거버넌스의 세 효익:

1. 도메인 지식 구조화 → RAG 효율 ↑, 모호성 ↓
2. 학습 데이터 품질 향상 → fine-tuning 강화
3. 벤치마크 정제 → 평가 신뢰성 ↑

9. 정리

9.1 핵심 한 줄

LLM 시대 Text-to-SQL은 Prompt Engineering(저데이터·빠름)과 Fine-tuning(프라이버시·도메인) 두 갈래로 나뉘며, 각 갈래는 pre/inference/post 또는 목표/방법/데이터/평가의 서브모듈로 더 분해된다.

9.2 의의

이 서베이의 의의는 실무 의사결정을 지원하는 분류 체계를 제공한 점이다. "어느 갈래를 택할까", "그 안에서 어느 워크플로우를 쓸까", "어떤 LLM을 base로 삼을까" 같은 질문에 명확한 가이드를 준다. 각 섹션 끝의 Key Takeaways는 그 자체로 압축된 의사결정 트리다.

Prompt Engineering 의사결정 트리

Fine-tuning 의사결정 트리

Text-to-SQL의 전 생애주기(모델·데이터·평가·오류분석)를 LLM 관점에서 체계적으로 재정리한 서베이

0. 논문 개요

0.1 한눈에 보기

0.2 사전 지식

이 서베이를 효과적으로 읽기 위해 알아두면 좋은 개념들이다.

• Text-to-SQL (NL2SQL): 자연어 질의를 실행 가능한 SQL로 변환하는 과제. 데이터베이스 접근 장벽을 낮추는 핵심 기술이다.
• 스키마 링킹(schema linking): 자연어 질의에서 언급된 개체·속성을 데이터베이스의 어떤 테이블·컬럼에 매핑할지 판단하는 단계.
• PLM(Pre-trained Language Model): BERT, T5와 같이 대규모 코퍼스에서 사전학습된 인코더/디코더 모델. 일반적으로 추가 파인튜닝이 필요하다.
• LLM(Large Language Model): GPT-4, DeepSeek과 같이 emergent capabilities를 갖춘 대규모 모델. in-context learning만으로도 Text-to-SQL을 수행할 수 있다.
• In-Context Learning (ICL): 모델 파라미터를 갱신하지 않고 프롬프트 내 예시·지시문만으로 새로운 과제를 수행하게 하는 기법.
• Spider / BIRD: Text-to-SQL의 양대 벤치마크. Spider는 cross-domain 일반화에, BIRD는 대규모 더티 데이터·도메인 지식 활용에 초점을 둔다.
• Execution Accuracy(EX): 예측 SQL과 정답 SQL의 실행 결과가 같은지로 평가하는 지표. 현재 가장 널리 쓰이는 메인 지표다.

0.3 논문 구조

1. Abstract & Introduction

1.1 논문이 풀고자 하는 문제

LLM 시대에 들어서면서 Text-to-SQL은 단일 모델이 한 번에 SQL을 뽑아내는 end-to-end 과제가 아니라, 여러 모듈이 협업하는 모듈러 시스템으로 진화했다. 이 서베이는 그 변화를 다음 네 축으로 종합한다.

1. Model: 자연어의 모호성과 underspecification, 그리고 스키마·인스턴스 매핑까지 다루는 번역 기법
2. Data: 학습 데이터 수집·합성·벤치마크
3. Evaluation: 다각도 지표와 시나리오 기반 평가
4. Error Analysis: 오류 분류와 근본 원인 추적

저자들은 단순한 정리에 그치지 않고 "어떻게 LLM을 Text-to-SQL에 최적화할 것인가"에 대한 실무적 로드맵까지 제시한다.

1.2 기존 접근의 한계

이전 서베이들은 주로 PLM 시대까지의 기법을 다루거나, LLM 시대를 다루더라도 모듈 단위 분해가 부족했다. 저자들은 LLM 시대 Text-to-SQL 시스템이 갖는 모듈러 구조를 본격적으로 분해해 보여주는 첫 서베이임을 강조한다.

1.3 이 논문의 기여

저자가 명시하는 기여를 정리하면 다음과 같다.

1. 생애주기 관점의 종합 리뷰: 문제 정의부터 평가, 오류분석, 실무 가이드까지 한 번에 다룬다. Text-to-SQL을 단발성 모델이 아닌 시스템 엔지니어링 과제로 다루는 시각이다.
2. 모듈 단위 분해: Schema Linking, DB Content Retrieval, Encoding/Decoding, IR, Self-correction 등을 독립 모듈로 분리해 비교한다. 이는 다음 절(Table I)에서 39개 시스템의 모듈 선택을 한 눈에 볼 수 있게 한다.
3. 2단계 오류 분류 체계: "오류 위치(SELECT/WHERE/...)"와 "원인(스키마 링킹 실패, 값 매칭 실패 등)"의 두 축을 제안한다. 1.8%만 Others로 분류된다는 점에서 분류의 실용성을 검증한다.
4. 실무 의사결정 흐름 제공: 데이터 프라이버시·볼륨·하드웨어 자원에 따른 LLM 최적화 로드맵, 시나리오별 모듈 선택 가이드를 제시한다.

1.4 논문의 위치

이 서베이는 Katsogiannis-Meimarakis & Koutrika의 VLDB Journal 서베이(2023), Deng et al.의 COLING 서베이(2022) 등을 잇는 흐름에 있다. 다만 LLM 시대 모듈러 시스템의 첫 종합 분해라는 점에서 차별화된다. 구체적으로는 DAIL-SQL(2023)·DIN-SQL(2023)·CHESS(2024)·CHASE-SQL(2025)·Alpha-SQL(2025) 등 최신 시스템을 동일한 모듈 격자에 정렬해 비교 가능하게 만든다는 점이 핵심 가치다.

2. Text-to-SQL 문제 정의와 도전 과제

2.1 문제 정의

Text-to-SQL is the task of converting natural language queries into corresponding SQL queries that can be executed on a relational database.

수식으로 표현하면 다음과 같다.

$$ F(\text{NL}, \text{DB}, K) \rightarrow \text{SQL} $$

여기서 $K$는 도메인 지식·추가 정보(예: BIRD 벤치마크의 evidence). 핵심은 단순한 일대일 매핑이 아니라는 점이다. 저자들은 다음 두 가지 다대일/일대다 관계를 강조한다.

• 동일한 NL이 모호성으로 인해 여러 SQL에 대응될 수 있다.
• NL·DB가 명확해도 의미적으로 동치인 SQL이 여럿 존재할 수 있다.

이 점은 평가 지표 설계(특히 Execution Accuracy 대 Exact Match)에 직접적인 영향을 준다.

2.2 인간 워크플로우

논문은 DBA가 "Find the names of all customers who checked out books on exactly 3 different genres on Labor Day in 2023"이라는 질의를 처리하는 과정을 3단계로 분해한다.

흥미로운 지점은 "Labor Day in 2023"이 미국에서는 9월 4일, 중국에서는 5월 1일을 가리킨다는 사례다. 이는 외부 도메인 지식 없이는 정확한 SQL을 만들 수 없음을 보여주며, 후술할 Additional Information Acquisition 모듈의 존재 이유가 된다.

2.3 세 가지 본질적 도전 과제

C1. 자연어의 불확실성(Uncertain NL)

• 어휘 중의성(lexical ambiguity): "bat"이 동물인지 야구방망이인지
• 통사 중의성(syntactic ambiguity): "Mary saw the man with the telescope"
• Underspecification: "Labor Day"가 어느 나라 기준인지

C2. 복잡한 DB와 더티 데이터

• 수백 개의 테이블, 복잡한 외래키 관계
• 컬럼명·값의 모호성(LiteraryGenre vs SubjectGenre)
• 도메인 특화 스키마 패턴
• 결측·중복·일관성 결여

C3. NL→SQL 번역 그 자체

• 자유 형식 vs 엄격한 문법
• 같은 NL에 대한 복수의 정답 SQL
• 스키마 의존성: 같은 NL이 스키마가 바뀌면 다른 SQL이 됨

이 세 도전 과제는 단순한 분류가 아니라, 후속 모듈(Pre-processing, Translation, Post-processing)이 각각 어느 도전 과제를 겨냥하는지 추적하는 격자 역할을 한다.

2.4 Text-to-SQL 솔루션의 진화

저자들은 Text-to-SQL의 발전을 4단계로 정리한다.

각 단계에서 풀린 도전 과제와 타깃 사용자가 달라진다.

저자들은 다섯 번째 단계(향후 5년)로 "오픈 도메인 Text-to-SQL"을 제시한다. 즉 단일 DB가 아니라 여러 DB를 가로질러 질의·집계하는 시나리오다. 이는 마지막 X장에서 본격적으로 다뤄진다.

2.5 LLM 시대의 두 갈래

LLM을 Text-to-SQL에 활용하는 방법은 크게 둘로 나뉜다.

(1) In-Context Learning — LLM 파라미터를 건드리지 않고 프롬프트만 설계한다.

$$ F_{\text{LLM}}(P \mid \text{NL}, \text{DB}, K) \rightarrow \text{SQL} $$

여기서 $P$는 프롬프트 함수다. DAIL-SQL, DIN-SQL이 대표적이다.

(2) Pre-train & Fine-tune — LLM 자체를 Text-to-SQL에 특화시킨다.

$$ \text{LLM}^{*} = F_{\text{fine-tune}}(F_{\text{pre-train}}(\text{LLM}, D_p), D_f) $$

$D_p$는 일반 코퍼스, $D_f$는 Text-to-SQL 특화 데이터셋이다. CodeS가 StarCoder 기반으로 이 경로를 택한 대표 사례다.

이 두 갈래의 구분은 IX장 실무 가이드의 핵심 분기 조건이 된다.

3. LM 기반 Text-to-SQL 모듈 개관

3.1 3단계 모듈러 구조

LLM 시대 Text-to-SQL의 표준 아키텍처는 다음 3단계로 정리된다.

이 구조는 두 가지 의미를 갖는다. 첫째, 각 단계가 서로 다른 도전 과제를 겨냥한다(Pre-processing은 C2, Translation은 C3, Post-processing은 C1·C3 모두). 둘째, 각 모듈은 선택적이다. 단순한 시스템은 Translation만 쓰고, 강력한 시스템은 세 단계 모두에 모듈을 둔다.

3.2 멀티 에이전트 협업으로의 진화

최근 트렌드는 단일 모놀리식 시스템이 아닌 멀티 에이전트 협업으로 가고 있다. 저자들이 강조하는 사례는 다음과 같다.

• MAC-SQL (3-agent): Selector(스키마 링킹), Decomposer(질의 분해·생성), Refiner(실행 기반 정정)
• CHASE-SQL (divide-and-conquer): 다중 CoT 경로로 후보 SQL을 만들고 self-correction과 ranking으로 정제
• Alpha-SQL: Monte Carlo Tree Search 기반 자율 에이전트가 모듈을 동적으로 선택·활성화

특히 Alpha-SQL의 MCTS 접근은 파이프라인의 경직성을 깨고 컨텍스트 추론과 실행 피드백에 따라 다음 모듈을 선택한다는 점에서 의미가 크다. 즉 "어떤 순서로, 어떤 모듈을 쓸 것인가"마저 학습/탐색의 대상이 된다.

3.3 Table I이 보여주는 트렌드

논문의 Table I은 39개 대표 시스템을 모듈 선택의 격자로 정렬한 표다. 이를 읽고 나면 몇 가지 트렌드가 드러난다.

• Schema Linking은 거의 표준: 39개 중 30개 이상이 사용. PLM 시대(Encoder-Decoder)부터 LLM 시대(Decoder-Only)까지 일관된다.
• Encoding은 Sequential로 수렴: 2022년 이전엔 Graph-based가 강했지만, LLM 시대에 와선 거의 모두 Sequential. LLM이 self-attention으로 관계를 암묵적으로 처리하기 때문이다.
• Decoding은 Greedy가 우세: GPT 계열이 기본 greedy인 영향. PLM 시대의 Beam Search나 Constraint-aware Incremental은 점차 줄어드는 추세다.
• CoT/Decomposition은 LLM에서만 등장: PLM 시대에는 거의 없던 모듈로, LLM의 추론 능력에 의존한다.
• Post-processing은 다양화: Correction, Consistency, Execution-Guided가 결합되어 사용된다.

이는 LLM 시대로 오면서 인코더의 부담은 줄고, 디코더 후처리의 다양성이 늘어난다는 큰 흐름을 말해준다.

4. Pre-Processing 전략

4.1 스키마 링킹

스키마 링킹은 NL과 관련된 테이블·컬럼을 식별하는 단계다. LLM의 컨텍스트 길이 한계 때문에 LLM 시대에는 더욱 중요해졌다.

4.1.1 세 갈래 접근

(1) String Matching 기반: IRNet은 정확 매칭, ValueNet은 Damerau-Levenshtein 거리 기반 근사 매칭을 쓴다. 단순하고 빠르지만 동의어와 어휘 변이에 약하다.

(2) Neural Network 기반: RESDSQL은 cross-encoder로 테이블·컬럼을 분류 확률에 따라 정렬한다. FinSQL은 parallel cross-encoder로 시간 비용을 줄인다. SLSQL은 Spider에 스키마 링킹 어노테이션을 추가해 데이터 기반 연구를 가능하게 했다. 의미 관계는 잘 잡지만 도메인 일반화가 어렵다.

(3) In-Context Learning 기반: GPT-4 시대의 표준이 되어가는 방식이다.

• C3-SQL: zero-shot 프롬프트 + self-consistency. 테이블 정렬 후 컬럼을 사전 형태로 출력
• MAC-SQL: 멀티에이전트의 Selector 에이전트가 담당하며, 스키마가 길 때만 활성화
• CHESS: GPT-4로 NL과 evidence에서 키워드 추출 후 3단계 스키마 프루닝

4.1.2 분석

스키마 링킹 모듈은 본질적으로 "검색 정확도"와 "컨텍스트 절약" 사이의 trade-off다. 너무 적게 가져오면 정답에 필요한 컬럼을 놓치고, 너무 많이 가져오면 LLM이 노이즈에 흔들린다. 최근 연구가 ICL 기반으로 수렴하는 이유는 단순 문자열 매칭이 가진 동의어·표현 변이 약점을 LLM의 의미 이해로 보완하면서, 신경망 학습보다 도메인 적응이 쉽기 때문이다.

4.2 데이터베이스 콘텐츠 검색

WHERE 절 등에 들어갈 셀 값을 어떻게 찾을 것인가의 문제다.

(1) String Matching: BRIDGE는 anchor text matching으로 NL에서 셀 값을 자동 추출한다. 휴리스틱으로 최대 시퀀스 매치를 계산해 매칭 경계를 정한다. 동의어 처리가 약점.

(2) Neural Network: TaBERT는 "database content snapshots"를 어텐션으로 인코딩한다. IRNet은 ConceptNet 같은 지식 그래프를 활용한다. 학습 비용이 크다.

(3) Index 전략: 대규모 DB에서 결정적으로 중요한 접근.

• CHESS: Locality-Sensitive Hashing(LSH)으로 유니크 셀 값을 인덱싱하고 근사 최근접 검색을 수행. 편집 거리·시맨틱 임베딩 비교를 가속.
• CodeS: Coarse-to-fine 매칭. BM25로 후보를 좁힌 뒤 Longest Common Substring으로 재순위.

인덱스는 검색을 빠르게 하지만 빌드 비용과 콘텐츠 변경 시 재구축 부담이 있다. 그래서 대규모 분석 DB에서 매력적이고, 빈번히 변경되는 OLTP DB에서는 부담스럽다.

4.3 추가 정보 수집

도메인 지식, 시연 예제, 공식 증거 등을 프롬프트에 주입하는 모듈이다.

Sample-based: DIN-SQL이 few-shot 예시를 단계별로 삽입. BIRD의 도메인 지식(evidence)을 프롬프트에 포함하는 방식이 대표적.

Retrieval-based: 효율을 위해 유사도 기반 검색을 한다.

• PET-SQL: question frame 풀에서 가장 유사한 k개 예시를 선택
• REGROUP: 도메인별 공식 지식 베이스를 만들고 Dense Passage Retriever로 검색
• ReBoost: Explain-Squeeze 2단계 스키마 링킹

핵심 통찰은 BIRD 같은 현실적 벤치마크에서는 도메인 지식 없이는 성능이 안 나온다는 점이다. 즉 추가 정보 수집은 선택 모듈이 아니라 사실상 필수 모듈로 자리잡고 있다.

5. Translation 모듈

5.1 인코딩 전략

5.1.1 Sequential Encoding

NL과 스키마를 하나의 토큰 시퀀스로 처리한다. T5 기반 모델, 그리고 모든 LLM 기반 시스템이 이 방식을 쓴다(LLM은 명시적으로 인코딩 전략을 정의하지 않지만, NL+스키마를 concatenate하는 순간 암묵적으로 sequential).

• BRIDGE: 매칭된 셀 값(anchor text)을 해당 필드 옆에 삽입해 정렬을 강화
• RESDSQL: rank-enhanced encoder로 스키마 항목을 정렬·필터링

장점은 유연성, 단점은 깊게 중첩된 SQL의 관계 구조를 잡기 어렵다는 점.

5.1.2 Graph-based Encoding

NL과 스키마를 그래프로 표현해 관계 구조를 보존한다.

• RAT-SQL: relation-aware self-attention으로 질문과 스키마를 함께 인코딩
• S²SQL: ELECTRA 기반에 syntactic structure를 주입
• G³R: LGESQL + GAT(Graph Attention Network)
• Graphix-T5: 그래프 인식 레이어를 직접 인코딩 과정에 추가

복잡한 그래프 구성·처리 알고리즘이 필요하고 대규모 학습 데이터를 요구한다. LLM 시대에 이 흐름이 사라진 이유는 LLM의 self-attention이 충분히 강력해서 명시적 그래프 인코딩의 이득이 크지 않기 때문으로 해석할 수 있다.

5.1.3 Separate Encoding

NL과 스키마를 분리 인코딩하거나, 작업을 서브태스크로 나눠 각각 인코딩.

• TKK: 작업 분해 + 멀티태스크 학습
• SC-Prompt: 텍스트 인코딩을 structure(구조)와 content(내용) 두 단계로 분리

연산 오버헤드는 늘지만 모듈성·해석성을 얻는다.

5.2 디코딩 전략

Greedy Search: GPT 계열의 기본. 단순·빠르지만 long-term 의존성을 놓치고 초기 오류가 전파된다.

Beam Search: top-k 빔을 유지해 더 넓은 탐색.

• RAT-SQL은 그래프 구조 + beam search로 후보 SQL을 만들고 재랭킹
• SmBoP은 semi-autoregressive bottom-up 디코딩으로 sub-tree를 병렬 구축(로그 시간 복잡도)
• ZeroNL2SQL은 sketch 단계에서 top-k 가설을 유지

Constraint-aware Incremental: SQL 문법을 디코딩 루프에 삽입해 매 토큰의 문법 적합성을 검증.

• PICARD: 가장 유명한 구현. 매 스텝마다 부분 SQL의 문법 유효성을 검사
• BRIDGE: schema-consistency guided decoding으로 스키마 정렬도 강제

문법 위반은 거의 0%로 만들 수 있지만 토큰별 검증이 추가 비용을 만든다.

5.3 Task-specific Prompt 전략

LLM 시대의 핵심 모듈이다. 두 갈래가 있다.

Chain-of-Thought (CoT): 추론 과정을 노출시켜 정확도와 해석성을 동시에 잡는다.

• CHESS는 entity/context retrieval → schema selection → SQL generation → revision의 파이프라인 전체에 CoT 적용
• ACT-SQL, COE-SQL은 CoT + ICL 결합
• C3-SQL, G³R은 CoT + 힌트 calibration

Decomposition: 작업을 서브태스크로 분해.

• TKK: SELECT/FROM/WHERE 절 단위로 분해
• MAC-SQL: Decomposer 에이전트가 사용자 질의를 서브 문제로 쪼갬
• DEA-SQL, G³R도 비슷한 전략

CoT와 Decomposition은 종종 결합된다. 차이는 CoT가 "한 모델 안의 reasoning trace"라면 Decomposition은 "여러 모듈/호출 간의 작업 분할"이라는 점이다.

5.4 Intermediate Representation (IR)

NL과 SQL의 간극을 메우기 위한 중간 표현이다.

5.4.1 SQL-like Syntax Language

SQL을 단순화한 언어다. 발전 흐름은 단순화의 단계를 보여준다.

NatSQL은 RESDSQL과 결합해 강한 성능을 보인다. 한계는 큰 스키마와 도메인 특화 SQL을 모두 커버하기 어렵다는 점, 수동 설계 비용이 있다는 점이다.

5.4.2 SQL-like Sketch Structure

SQL의 구조를 슬롯이 있는 템플릿으로 표현한다.

SELECT [column]
FROM [table]
JOIN [table] ON [table].[column] = [table].[column]
GROUP BY [column]
HAVING count([column]) > [n]

LLM의 cloze(빈칸 채우기) 능력을 활용해 슬롯을 채우는 전략이다.

• CatSQL: 일반 템플릿 sketch + 슬롯 채우기
• RESDSQL: skeleton-aware decoding으로 SQL skeleton 먼저 생성, 그다음 실제 SQL로 변환
• ZeroNL2SQL, SC-Prompt, TA-SQL도 sketch 활용

장점은 LLM 의존이 줄고 다른 전략(decomposition, syntax language)과 결합이 쉽다는 점.

5.4.3 IR의 의미

IR은 본질적으로 SQL의 표현력을 일부 포기하는 대신 NL→SQL 매핑을 단순화하는 trade-off다. 모든 SQL을 표현하지 못해도, 자주 등장하는 패턴을 깔끔히 잡을 수 있으면 정확도가 올라간다. LLM 시대에 IR의 비중이 줄어든 것은 LLM이 이미 SQL을 직접 잘 생성하기 때문이지만, 복잡한 nested query에서 IR은 여전히 유효한 도구다.

6. Post-Processing 전략

6.1 SQL 교정

DIN-SQL의 self-correction 모듈이 대표적이다. 두 종류 프롬프트를 쓴다.

• General prompt (CodeX용): 직접 오류 식별·수정 요청
• Mild prompt (GPT-4용): 오류가 있다고 가정하지 않고 잠재 이슈만 탐색

ZeroNL2SQL은 predicate 오류(컬럼·값 오인식)에 대한 multi-level matching을 제안. 컬럼→테이블→DB로 매칭 범위를 점진 확장한다.

한계는 대부분 syntax 오류 교정에 집중되어 있고, semantic 오류(잘못된 join, 조건 불일치, 집계 오류)는 잘 다루지 못한다는 점. NL2SQL-BUGs(2025)가 이 빈틈을 본격적으로 다루는 후속 연구다.

6.2 출력 일관성

self-consistency 아이디어를 차용한다. 여러 추론 경로를 샘플링한 뒤 다수결로 답을 고른다.

• DAIL-SQL: self-consistency로 0.4%p 개선
• FinSQL: n개 후보를 병렬 생성, 키워드 일관성 클러스터링 후 최대 클러스터에서 선택
• PET-SQL: cross-consistency. 여러 LLM이 낮은 temperature로 SQL을 만들고 실행 결과로 투표

단점은 추론 비용이 N배가 된다는 것. 그리고 단일 모델 샘플링은 다양성이 한정적이라는 최근 연구도 있다.

6.3 실행 가이드 전략

생성된 SQL을 실제 실행해 결과를 보고 다시 수정하는 전략.

• CHESS: 초안 SQL → 실행 결과 → syntax 오류 수정 → 반복
• CodeS: beam search로 4개 후보를 만들고 첫 번째 실행 가능한 것을 선택

장점은 실행 결과로 검증이 되니 신뢰도가 높다는 것. 단점은 대형 DB에서는 실행 자체가 느려 latency가 폭증한다는 점.

6.4 N-best 재랭킹

PLM 기반 시스템에서 활발하게 쓰인 전략이다. 모델이 생성한 top-N 후보를 다른 (더 큰) 모델로 재정렬한다.

• Bertrand-dr: BERT 기반 reranker. 효과가 임계값에 민감해 부정적 효과도 발생
• G³R: feature-enhanced reranker, hybrid prompt tuning + contrastive learning
• ReFSQL: retriever와 generator의 결과를 결합

LLM 기반 시스템에서는 LLM 자체의 추론력이 강해서 재랭킹이 덜 쓰인다. 다만 다중 후보 + voting/ranking은 CHASE-SQL에서 다시 부상하는 패턴이다.

7. 벤치마크

7.1 데이터셋 분류

논문은 벤치마크를 8가지 시나리오로 분류한다.

대표 흐름은 다음과 같다.

• 단일 도메인 → 크로스 도메인: ATIS, GeoQuery에서 시작해 WikiSQL, Spider로 일반화 능력을 측정.
• Spider → BIRD: BIRD는 더 큰 DB(평균 4.5M 레코드/DB), 도메인 지식, scalar function/수학 연산을 포함.
• Robustness 강조: Spider-Syn(동의어), Dr.Spider(17가지 perturbation), AmbiQT(모호성).
• 현실 시나리오: BookSQL(회계), FinSQL/BULL(금융), Archer(추론), Spider2-Lite(엔터프라이즈).

7.2 통계 분석으로 본 트렌드

논문 Table II의 통계에서 의미 있는 수치를 골라 해석한다.

관찰점: Spider→BIRD→Spider2-Lite로 갈수록 DB 크기와 SQL 복잡도가 모두 증가. 특히 Spider2-Lite는 평균 23개 테이블/DB, 평균 5개 SELECT로 현실 엔터프라이즈에 가깝다.

저자들이 강조하는 "현재 데이터셋의 한계"는 다음과 같다.

• 중첩 쿼리(nested SELECT)와 복잡 set operation 부족
• Scalar function·수학 연산이 적게 포함됨
• Open-domain(다수 DB 가로지르는) 시나리오 거의 없음

이는 X장의 open problem과 직접 연결된다.

7.3 데이터 합성

학습 데이터 부족은 본질적 문제다. 합성 방법은 시간순으로 다음과 같이 진화했다.

• Human annotation: Spider, ATIS. 품질은 높지만 비싸다.
• Rule-based synthesis: MIMICSQL은 템플릿 기반 SQL 생성 후 NL 작성.
• LLM-based synthesis: ScienceBenchmark는 SQL을 템플릿으로 만들고 GPT-3로 NL을 역생성.

LLM 기반 합성의 가능성은 크지만, 합성 데이터의 다양성·정확성·도메인 적합성을 어떻게 보장할 것인가가 X장의 "Adaptive Training Data Synthesis" 문제로 이어진다.

8. 평가와 오류 분석

8.1 평가 지표

논문은 6가지 지표를 정의한다.

Execution Accuracy (EX): 가장 널리 쓰이는 메인 지표.

$$ \text{EX} = \frac{\sum_{i=1}^{N} \mathbf{1}(V_i = \hat{V_i})}{N} $$

$V_i$는 정답 SQL의 실행 결과 집합, $\hat{V_i}$는 예측 SQL의 결과 집합. 의미적으로 다른 SQL이 우연히 같은 결과를 낼 수 있다는 false positive 가능성이 한계다.

String-Match Accuracy (SM): 문자열 정확 일치. 의미적으로 같은 SQL을 다르게 작성한 경우(예: WHERE 절 순서 변경)를 모두 틀렸다고 처리하는 약점.

Component-Match Accuracy (CM): SELECT, WHERE 등 컴포넌트 단위 정확도.

$$ \text{CM}C = \frac{\sum{i=1}^{N} \mathbf{1}(Y_i^C = \hat{Y_i}^C)}{N} $$

WHERE 절 같은 일부 컴포넌트는 순서를 무시하고 매칭한다.

Exact-Match Accuracy (EM): CM의 모든 컴포넌트가 일치할 때만 정답.

$$ \text{EM} = \frac{\sum_{i=1}^{N} \mathbf{1}(\bigwedge_{C_k \in C} Y_i^{C_k} = \hat{Y_i}^{C_k})}{N} $$

Valid Efficiency Score (VES): BIRD가 도입한 실행 효율 평가.

$$ \text{VES} = \frac{\sum_{i=1}^{N} \mathbf{1}(V_i = \hat{V_i}) \cdot R(Y_i, \hat{Y_i})}{N}, \quad R(Y_i, \hat{Y_i}) = \sqrt{\frac{E(Y_i)}{E(\hat{Y_i})}} $$

$E(\cdot)$는 SQL의 효율(실행 시간 등). 정확하지만 느린 SQL이 패널티를 받는다.

Query Variance Testing (QVT): 같은 SQL에 대응되는 여러 NL 변형에 대한 모델의 일관성을 측정.

$$ \text{QVT} = \frac{1}{N}\sum_{i=1}^{N}\left(\frac{\sum_{j=1}^{m_i} \mathbf{1}(F(Q_{ij}) = Y_i)}{m_i}\right) $$

이 지표들의 의미를 정리하면 다음과 같다.

8.2 평가 툴킷

MT-TEQL: 메타모픽 테스팅. NL 변형(prefix insertion 등) 4종, 스키마 변형(table shuffle 등) 8종을 자동 생성해 견고성을 평가.

NL2SQL360: 다각도 평가 프레임워크. 6개 컴포넌트(Dataset, Model Zoo, Metrics, Filter, Evaluator, Analysis)로 구성. SQL 특성(집계 함수, 중첩 쿼리, top-k)별로 데이터셋을 필터링해 시나리오별 성능을 측정.

이 툴킷들의 의미는 "단일 벤치마크의 단일 점수"로는 실서비스 성능을 알 수 없다는 인식이다. BI 시나리오는 집계·top-k 쿼리가 많고, 정형 보고는 join이 깊다. 각각의 부분집합에서 성능을 따로 봐야 한다.

8.3 오류 분류 체계

8.3.1 기존 분류 체계 정리

• Ning et al.: Syntactic 차원(SQL 키워드별)과 Semantic 차원(NL 해석 오류) 두 축.
• SQL-PaLM: Schema Linking, Database Content, Knowledge Evidence, Reasoning, Syntax 5종.
• NL2SQL-BUGs: semantic 오류에 집중. 9개 메인 카테고리, 31개 서브카테고리.

이들은 데이터셋·모델 의존적이라는 한계가 있다.

8.3.2 저자의 2단계 분류 원칙

저자들은 분류 체계가 갖춰야 할 4원칙을 제시한다.

1. Comprehensiveness: 모든 오류 타입 포괄
2. Mutual Exclusivity: 분류 모호성 제거
3. Extensibility: 새 오류 유형 수용
4. Practicality: 실제 디버깅에 활용 가능

이 원칙으로 만든 2단계 분류는 다음과 같다.

Level 1 (위치): 어느 SQL 절에서 오류가 발생했는가 Level 2 (원인): 왜 그 오류가 발생했는가

8.3.3 적용 결과 분석

DIN-SQL을 Spider에 적용한 오류 분포(Figure 1d)를 정리하면 다음과 같다.

흥미로운 관찰점은 다음과 같다.

• SELECT 오류가 25.5%로 가장 큼: 어떤 컬럼을 출력할지 결정하는 단계가 의외로 약하다. 스키마 링킹의 한계.
• GROUP BY 16.6%: 집계의 핵심 절. 누락·중복·서브쿼리화 오류가 섞여 있음.
• Equality 15.9%, WHERE 15.2%: 조건절의 값 매칭이 여전히 큰 골칫거리. DB content retrieval 모듈의 중요성을 뒷받침.
• FROM 15.3%: JOIN 결정과 테이블 선택. 복잡 스키마의 본질적 어려움.
• Other가 1.8%: 분류 체계의 실용성 검증.

각 위치 안에서 원인은 더 세분된다. WHERE 절 오류(15.2%) 내부를 들여다보면 Value 매칭이 11.6%로 압도적이다. 즉 WHERE의 어려움 대부분은 "어떤 값으로 필터링할지"를 못 맞추는 것이라는 진단이다. 이는 indexed retrieval(LSH, BM25)이 왜 중요한지를 정량적으로 뒷받침한다.

9. 실무 가이드

9.1 데이터 기반 LLM 최적화 로드맵

저자들은 두 조건(데이터 프라이버시, 데이터 볼륨)에 따른 의사결정 흐름을 제안한다.

핵심 원칙은 다음과 같다.

• 프라이버시가 민감하면 무조건 오픈소스 LLM: 외부 API는 데이터 유출 위험.
• 오픈소스는 학습+추론 모두 최적화 가능, 클로즈드는 추론만 가능.
• 하드웨어 vs API 비용: 오픈소스는 GPU 자원을, 클로즈드는 API 예산을 요구.
• 저데이터 환경에선 few-shot, zero-shot 우선: 작은 라벨링 데이터로 fine-tuning을 시도하는 건 종종 손해.

9.2 모듈 선택 의사결정 흐름

저자들은 시나리오별 모듈 추천을 표로 정리했는데, 핵심을 다음과 같이 재구성할 수 있다.

이 표의 핵심은 모든 모듈이 시간/토큰 비용 증가를 동반한다는 점이다. 모듈 선택은 항상 trade-off이고, 시나리오에 맞춰 선택해야 한다.

9.3 자원 비용 비교

논문 Table III는 Spider에서의 자원 사용을 비교한다.

관찰: DIN-SQL은 RESDSQL보다 5배 이상 느리고 토큰 소비도 거의 10배다. 정확도는 더 높지만 운영 비용 차이가 크다. 실무에서는 PLM과 LLM을 혼합하거나 복잡도에 따라 라우팅(EllieSQL의 접근)이 합리적인 선택이 될 수 있다.

10. 한계와 열린 문제

10.1 현재 LLM 기반 방법의 한계

저자들이 정리한 한계는 다음과 같다.

1. 단일 DB 가정: 학습·추론 모두 단일 DB 위에서 이뤄짐. cross-DB 시나리오 미지원.
2. 추론 비용: 강력한 NLU에도 불구하고 토큰 소비가 크다.
3. 해석성·디버그 부재: 사용자가 SQL 생성 과정을 이해·검증할 수단이 부족.
4. 도메인 적응 약함: 새 도메인마다 고품질 데이터가 필요하지만 자동 합성 메커니즘이 미숙.

10.2 Open-Domain Text-to-SQL

가장 큰 미해결 과제다. 정부 오픈데이터 같은 환경에서는 한 NL이 여러 DB(세금기록, 처리로그, 통계보고서 등)에 걸쳐 있다.

이 시나리오의 도전 과제는 다음과 같다.

• DB 검색: 거대한 데이터 소스 풀에서 관련 DB를 찾는 검색 단계
• 이질적 스키마: 서로 다른 명명·구조 통합
• 답 집계: 여러 SQL 결과를 종합해 최종 답 도출
• 도메인 적응: 도메인별 용어·구조 차이
• 확장성·효율: 대규모 데이터 처리
• 평가: 현실 복잡도를 반영하는 메트릭·데이터셋 필요

10.3 Cost-Effective Text-to-SQL

LLM 단독 사용은 비용이 너무 크다. 저자들이 제시하는 방향은 다음과 같다.

• PLM + LLM 하이브리드: 단순 쿼리는 PLM, 복잡 쿼리는 LLM
• EllieSQL 같은 complexity-aware routing: 쿼리 복잡도에 따라 적합한 생성기로 분배

이는 실서비스 관점에서 매우 현실적인 방향이다. 모든 쿼리에 GPT-4를 쓰는 것은 비용·latency 모두 부담스럽고, 실제로 대부분의 쿼리는 단순하기 때문이다.

10.4 Trustworthy Text-to-SQL

신뢰성을 위한 4가지 방향이 제시된다.

(a) 해석 가능성: surrogate model, saliency map 등 XAI 기법의 Text-to-SQL 적용. 멀티 에이전트 LLM이 자연스럽게 각 단계의 출력을 보여주므로 일부 해석성을 제공.

(b) 디버깅 도구: 컴파일러처럼 SQL 오류를 잡되, syntax뿐 아니라 semantic 오류까지 검증. NL2SQL-BUGs가 이 방향의 시작.

(c) 인터랙티브 도구: DBA가 50줄 이상의 복잡 쿼리를 작성할 때, 모델이 분해하고 사용자가 부분별로 정정·확인하는 워크플로우. bottom-up과 top-down 모두 지원.

(d) 적응형 데이터 합성: 모델 약점을 평가 결과에서 식별하고, LLM으로 해당 약점을 보완하는 (NL, SQL) 쌍을 자동 생성하는 피드백 루프.

11. 정리

11.1 핵심 한 줄

LLM 시대의 Text-to-SQL은 단일 모델이 SQL을 한 번에 뱉는 게 아니라, Pre/Translation/Post의 모듈러 시스템이며, 각 모듈은 시나리오별 비용·정확도 trade-off의 산물이다.

11.2 의의

이 서베이의 의의는 두 가지다. 학술적으로는 LLM 시대 Text-to-SQL을 "에이전트·모듈러 시스템"으로 정식화한 첫 종합 정리다. 실무적으로는 어떤 모듈을 언제 쓸지에 대한 의사결정 프레임을 제공해, 시스템 설계자가 길을 잃지 않게 돕는다.

1편에서 Harmony 응답 포맷의 구조를 정리했다. assistant 메시지가 analysis, commentary, final 세 채널로 분리되고, analysis 채널에 모델의 원본 chain-of-thought(CoT) 가 흘러나온다는 것까지 다뤘다.

이번 편의 출발점은 그 다음 질문이다. 그래서 그 원본 CoT를 API 응답에 어떻게 담고, UI에는 무엇을 노출할 것인가? 이 질문이 까다로운 이유는 CoT가 본질적으로 충돌하는 두 가지 성격을 동시에 가지기 때문이다.

한쪽에서 CoT는 모델 성능에 필요하다. 도구 호출이 CoT 안에서 이뤄지므로, 다음 턴 입력에서 CoT를 빼면 추론 흐름이 끊긴다. 반대쪽에서 CoT는 사용자에게 위험하다. 안전성 학습이 final 채널에만 적용되었고, developer 메시지의 내부 지시까지 새어 나갈 수 있다.

이 비대칭이 모든 구현 결정의 출발점이다. 원칙은 한 줄로 요약된다. 모델 컨텍스트에는 보존하되, 사용자 화면에는 노출하지 않는다.

2. 핵심 개념 1 — CoT가 모델 성능에 필요한 이유

2-1. 도구 호출은 CoT 안에서 일어난다

gpt-oss의 도구 호출은 응답이 끝난 뒤에 별도로 일어나는 절차가 아니다. 모델이 analysis 채널에서 추론하다가, "여기서 도구를 부르자"는 결정을 내린 뒤 commentary 채널로 호출 메시지를 흘리는 흐름이다. 즉 CoT와 도구 호출은 같은 추론 줄기에 매달려 있다.

다음 턴에 도구 결과를 모델에 돌려줄 때 직전 CoT를 함께 넣지 않으면, 모델은 "내가 왜 이 도구를 호출했는지"의 맥락을 잃는다. 도구를 두 번 부르거나, 결과를 잘못 해석하거나, 추론을 처음부터 다시 시작하는 비효율이 발생한다.

2-2. 후속 샘플링 시 CoT 보존/폐기 규칙

1편에서 다룬 비대칭 규칙을 다시 정리한다. 이번 편의 모든 API 구현은 결국 이 규칙을 충족하는지로 평가된다.

"마지막이 final이었으면 버리고, 도구 호출 진행 중이면 유지한다"는 한 문장으로 외워도 된다.

2-3. 💡 참고 — 함수 호출과 CoT 의존성의 비대칭

함수 도구(commentary 채널)와 내장 도구(browser/python, analysis 채널) 모두 같은 보존 규칙을 따른다. 다만 commentary 채널의 함수 호출 메시지는 final 메시지가 나온 이후에도 컨텍스트에 남길 수 있다. 즉, 폐기 대상은 analysis 채널의 CoT지 commentary 채널의 도구 호출 기록이 아니다. 두 채널을 같은 "추론 부산물"로 묶어서 처리하면 함수 호출 이력이 함께 사라지는 버그가 난다.

3. 핵심 개념 2 — CoT를 사용자에게 노출하면 안 되는 이유

3-1. 안전성 학습이 final 채널에만 적용된다

원문이 반복해서 강조하는 이유다. 모델이 학습 단계에서 유해 콘텐츠 필터링과 안전 정렬(safety alignment)을 학습한 출력은 final 채널에 한정된다. analysis 채널의 출력은 동일한 기준으로 학습되지 않았다.

실무적 결과는 이렇다. CoT에는 사용자에게 그대로 보여주면 안 되는 표현, 정책 위반 시도의 흔적, 미가공 의견이 섞일 수 있다. 모델이 의도적으로 그렇게 한다는 뜻이 아니라, 거를 장치가 final 채널만큼 촘촘하지 않다는 뜻이다.

3-2. developer 메시지의 내부 지시가 새어 나갈 수 있다

두 번째 위험은 안전성과는 결이 다르다. CoT 안에서 모델은 자기에게 주어진 지시를 그대로 인용하거나 풀어 설명하는 경향이 있다. 그 지시에 영업 비밀, 시스템 동작 방식, 우회 방지 규칙 같은 것이 포함되어 있다면, 사용자에게 CoT를 노출하는 순간 그것이 그대로 노출된다.

예를 들어 developer 메시지에 "사용자가 가격 인하를 요구하면 절대 응하지 말 것"이라는 지시가 있고 사용자가 가격 인하를 요청하면, CoT에는 "사용자가 가격 인하를 요청했지만 지시상 거절해야 함"이라는 줄이 그대로 찍힐 수 있다. final 채널에는 정중한 거절만 나가지만, 원본 CoT를 그대로 보여주면 그 뒷규칙이 통째로 드러난다.

3-3. 그렇다면 사용자에게 추론 과정을 전혀 못 보여주는가

아니다. 요약된 CoT는 보여줘도 된다. ChatGPT와 OpenAI API의 production이 실제로 동작하는 방식이 이것이다. 별도의 요약 모델(summarizer)이 원본 CoT를 검토하고 유해 콘텐츠와 내부 지시를 차단한 결과만 사용자에게 노출한다. 7장과 8장에서 이 패턴을 자세히 다룬다.

4. 핵심 개념 3 — 두 API의 비대칭 설계

OpenAI는 호스팅 모델에서 원본 CoT 노출 기능을 당분간 제공하지 않는다. 그래서 두 API에서의 처리 방식은 출발점이 다르다.

4-1. Chat Completions: 외부 컨벤션 차용

Chat Completions API는 OpenAI의 공식 스펙에 CoT 처리 규약이 없다. 대신 OpenAI는 OpenRouter의 reasoning tokens 컨벤션을 따르라고 안내한다. 이미 여러 오픈 모델 추론 프로바이더가 이 컨벤션을 채택했기 때문에, 새로운 표준을 만들기보다 사실상의 표준을 채용한 것이다.

4-2. Responses API: 자체 스펙 확장

Responses API는 OpenAI가 직접 정의한 스펙이므로 자체적으로 확장했다. 기존 ReasoningItem에 새로운 content 필드를 추가했고, reasoning_text라는 콘텐츠 타입과 두 개의 새 스트리밍 이벤트(response.reasoning_text.delta/.done)를 신설했다.

4-3. 왜 한쪽은 차용하고 다른 쪽은 확장했는가

설계 철학의 차이다. Chat Completions는 사실상 업계 표준 인터페이스가 되어버려 OpenAI 단독으로 스펙을 흔들기 어렵다. 반면 Responses API는 OpenAI가 처음부터 추론·도구·멀티턴을 일급 시민으로 두려고 만든 새 인터페이스다. 따라서 추론 관련 확장이 자연스럽게 들어갈 자리가 있다.

이 차이를 머리에 두고 5장과 6장을 본다.

5. Chat Completions API 구현

5-1. 응답 형태 — message.reasoning 속성

OpenRouter 컨벤션에서 원본 CoT는 응답 메시지의 reasoning 속성에 담긴다. 일반 응답 텍스트는 기존처럼 content에 들어간다.

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "2 + 2는 4입니다.",
        "reasoning": "사용자가 단순한 산술을 물었다. 2 + 2 = 4."
      }
    }
  ]
}

content는 사용자에게 보여줘도 되고, reasoning은 보여주면 안 된다. 같은 응답 객체 안에 들어 있다고 해서 같은 처리 정책을 적용해선 안 된다.

5-2. 스트리밍 — delta.reasoning 속성

스트리밍 모드에서도 같은 분리가 유지된다. 일반 텍스트 델타는 delta.content로, CoT 델타는 delta.reasoning으로 흘러온다.

# 스트리밍 응답을 받을 때 두 필드를 분리해 처리
for chunk in stream:
    delta = chunk.choices[0].delta

    if delta.reasoning:
        # CoT 델타 — 로깅 또는 요약 모델에 흘려보냄, 사용자 화면에는 미노출
        log_cot(delta.reasoning)

    if delta.content:
        # 사용자 응답 델타 — 화면에 흘려보냄
        print(delta.content, end="", flush=True)

핵심은 두 필드를 같은 출력 스트림에 합치지 않는 것이다. 한 번 합쳐진 스트림은 분리가 어렵고, 실수로 사용자에게 CoT가 흘러갈 위험이 생긴다.

5-3. 요청 단계에서 CoT 제외하기 — reasoning.exclude

CoT가 아예 필요 없는 경우 요청 단에서 제외할 수 있다. 응답 페이로드 크기와 처리 비용을 줄인다.

{
  "model": "gpt-oss-...",
  "messages": [...],
  "reasoning": { "exclude": true }
}

다만 도구 호출이 포함된 시나리오에서는 제외하면 안 된다. 다음 턴에 모델이 추론을 이어갈 컨텍스트가 사라지기 때문이다(2-2 규칙 참고). 디버깅 목적이거나, 도구 호출이 없는 단발성 질의응답일 때만 안전하게 사용한다.

5-4. 다음 턴에 CoT 다시 넣어주기

다중 턴 대화에서 모델이 도구 호출을 진행 중이라면, 다음 요청의 메시지 배열에 직전 CoT를 다시 넣어야 한다. OpenRouter 컨벤션은 메시지 객체의 reasoning 속성을 그대로 다시 보내는 방식을 권장한다.

# 직전 응답에서 받은 reasoning을 다음 요청 메시지에 포함
next_messages = [
    *previous_messages,
    {
        "role": "assistant",
        "content": None,
        "reasoning": previous_response.choices[0].message.reasoning,
        "tool_calls": previous_response.choices[0].message.tool_calls,
    },
    # 이어서 tool 메시지 (도구 실행 결과)
    {"role": "tool", "tool_call_id": "...", "content": tool_result_json},
]

6. Responses API 구현

6-1. ReasoningItem 타입 확장 — summary와 content

Responses API에는 원래 ReasoningItem에 사용자 노출용 요약(summary)이 있었다. 이번 확장으로 원본 CoT를 담는 content 필드가 추가되었다.

type ReasoningItem = {
  id: string;
  type: "reasoning";
  summary: SummaryContent[];
  // 신설 — 원본 CoT
  content: ReasoningTextContent[];
};

type ReasoningTextContent = {
  type: "reasoning_text";
  text: string;
};

핵심은 두 필드의 노출 정책이 정반대라는 점이다. summary는 안전 검수를 거친 사용자 노출용, content는 원본이라 사용자 미노출용이다. 7장에서 자세히 다룬다.

6-2. 새 콘텐츠 타입 — reasoning_text

ReasoningItem.content 배열은 reasoning_text 타입의 객체들로 채워진다. 콘텐츠 타입을 별도로 둔 이유는 향후 다른 종류의 reasoning 출력(예: 추론 그래프, 인용 등)이 추가될 여지를 남기기 위함이다.

6-3. 새 스트리밍 이벤트 — reasoning_text.delta / .done

스트리밍에서는 두 개의 새 이벤트가 흘러온다.

type ReasoningTextDeltaEvent = {
  type: "response.reasoning_text.delta";
  sequence_number: number;
  item_id: string;
  output_index: number;
  content_index: number;
  delta: string;
};

type ReasoningTextDoneEvent = {
  type: "response.reasoning_text.done";
  sequence_number: number;
  item_id: string;
  output_index: number;
  content_index: number;
  text: string;
};

delta 이벤트로 CoT 토큰이 조각조각 흘러오고, done 이벤트로 한 턴의 CoT가 끝났음을 알린다. done의 text 필드에는 그 턴의 전체 CoT가 합쳐진 형태로 들어 있어, delta를 따로 누적할 필요가 없다.

6-4. 응답 객체 전체 예시

output 배열에 ReasoningItem이 어떻게 자리 잡는지 한눈에 보면 다음과 같다.

"output": [
  {
    "type": "reasoning",
    "id": "rs_67f47a642e788191aec9b5c1a35ab3c3016f2c95937d6e91",
    "summary": [
      {
        "type": "summary_text",
        "text": "**부피 계산**\n\n근사값으로 시작..."
      }
    ],
    "content": [
      {
        "type": "reasoning_text",
        "text": "사용자가 생각해 보라고 요청했다..."
      }
    ]
  }
]

같은 아이템 안에 summary와 content가 나란히 들어 있다. 클라이언트는 둘을 명확히 다른 정책으로 다뤄야 한다.

7. summary와 content의 결정적 차이

7-1. summary는 어떻게 만들어지는가

OpenAI 공식 문서가 명시하는 방식은 한 줄이다. 별도의 요약 모델(summarizer)이 원본 CoT를 검토하고 유해 콘텐츠를 차단한 결과를 보여준다. 즉 summary는 모델이 직접 생성한 것이 아니라, 원본 CoT를 입력으로 받는 후처리 단계의 산출물이다.

이 패턴은 ChatGPT와 OpenAI API의 production 구현에서 그대로 동작하고 있다. 사용자가 추론 모델 응답에서 보는 "생각하는 중..." 영역의 텍스트는 원본 CoT가 아니라 이 요약 결과다.

7-2. content를 사용자에게 보내면 안 되는 이유 재확인

3장에서 다룬 두 위험(안전성 학습 미적용, 내부 지시 노출)이 그대로 적용된다. 추가로 한 가지 더, 원본 CoT는 형식이 들쭉날쭉하다. 모델 내부의 사고 과정이라 문장이 끊기거나 이상한 약어가 등장하기도 한다. 사용자 경험 관점에서도 그대로 보여주는 것은 부적절하다.

7-3. 자체 요약 파이프라인을 구축할 때의 고려사항

Responses API를 쓰지 않거나, OpenAI의 요약과 다른 정책이 필요한 경우 직접 파이프라인을 구축해야 한다. 원문이 직접 추천하는 도구는 없으므로 추상적 수준에서 정리한다.

• 요약 모델 선택: 원본 CoT보다 가볍고 빠른 모델을 사용해 지연 비용을 낮춘다.
• 안전 필터 분리: 요약 모델 자체에 안전 검수를 의존하지 말고, 별도 분류기로 정책 위반 콘텐츠를 차단한다.
• fail-closed 원칙: 요약/필터 단계에서 오류가 나면 빈 요약을 노출하거나 "추론 과정 표시 불가"로 폴백한다. 절대 원본을 폴백으로 쓰지 않는다.
• 로그 분리 저장: 원본 CoT를 디버깅·이슈 분석용으로 저장하더라도, 사용자 응답 로그와는 다른 권한 체계로 관리한다.

8. 사용자에게 추론 과정을 보여주는 권장 방식

8-1. ChatGPT/OpenAI API의 production 패턴

production에서 검증된 패턴은 다음 흐름이다.

1. 모델이 원본 CoT를 analysis 채널 / content[].text에 생성한다.
2. 별도 요약 모델이 원본을 받아 사용자용 요약을 만든다.
3. 안전 분류기가 요약을 검사해 정책 위반 콘텐츠를 차단한다.
4. 통과한 요약만 UI에 표시한다.
5. 원본 CoT는 모델 컨텍스트(다음 턴 입력)와 내부 로그에만 보존한다.

8-2. 직접 구축 시 최소 요구사항

자체 시스템에서 이 패턴을 구현할 때 빠지면 안 되는 항목은 다음 네 가지다.

• 원본 CoT와 사용자 노출 텍스트의 저장 경로 분리
• 요약 단계와 안전 필터 단계의 독립 구현 (한 모델이 두 역할을 다 하지 않는다)
• 요약/필터 실패 시 원본 폴백 금지
• 다음 턴 입력 구성 시 원본 CoT를 사용 (요약본을 다시 넣지 않는다 — 모델 추론 줄기가 끊긴다)

마지막 항목이 자주 실수가 난다. UI에 보여줄 것은 요약, 모델에 다시 넣을 것은 원본이라는 분리를 명확히 둔다.

8-3. 💡 참고 — 요약을 건너뛸 수 있는 예외 상황

다음 경우에는 원본 CoT를 그대로 활용해도 된다.

• 개발자/내부 도구: 디버깅 콘솔, 평가 대시보드처럼 노출 대상이 모델 운영자 본인일 때
• 연구 분석: CoT 분석을 위한 오프라인 파이프라인
• 로그 시스템: 권한 분리된 내부 로그

요지는 "노출 대상이 신뢰할 수 있는 내부 사용자인가" 다. 이 조건이 깨지면 그 순간 다시 요약+필터 파이프라인이 필요하다.

9. 시리즈 1편과의 연결 — 한눈에 보기

1편에서 다룬 Harmony 채널이 두 API에서 어떤 필드로 옮겨지는지 한 표로 정리한다. 추상 수준이 다른 두 레이어(토큰 포맷 ↔ HTTP API)를 매핑해 두면 디버깅 시 도움이 된다.

마지막 행이 두 API의 가장 큰 실용 차이다. Chat Completions로 추론 과정을 사용자에게 보여주려면 요약 파이프라인을 직접 만들어야 하지만, Responses API는 summary가 응답에 함께 온다.

10. 참고 자료

• How to handle the raw chain of thought in gpt-oss (원문)
• OpenAI Harmony Response Format (시리즈 1편 원문)
• OpenRouter Reasoning Tokens 문서 — Chat Completions 컨벤션 출처
• OpenAI Responses API 레퍼런스 — 확장된 ReasoningItem 스펙
• gpt-oss 모델 카드 — 안전성 학습 범위 확인용

원본 CoT는 모델 컨텍스트에 보존하되 사용자 화면에는 절대 그대로 노출하지 않는다. 보여주고 싶다면 요약 파이프라인을 거쳐야 한다.

gpt-oss는 Harmony 포맷 없이는 동작하지 않는다. 역할·채널·특수 토큰을 한 번에 정리한다.

1. Harmony 포맷이 왜 필요한가

gpt-oss 모델은 Harmony 응답 포맷으로 학습되었다. 즉, 이 포맷은 "권장 사항"이 아니라 모델이 정상 동작하기 위한 전제 조건이다. 다른 포맷으로 입력을 구성하면 추론 결과가 어긋나거나 도구 호출이 깨진다.

다행히 모든 상황에서 직접 신경 쓸 필요는 없다. Ollama, vLLM, OpenAI 호환 API 같은 추론 프로바이더를 경유한다면 포맷 변환은 내부에서 처리된다. 반대로 직접 추론 서버를 구축하거나 토큰 단위로 입출력을 다뤄야 한다면, 모든 메시지를 Harmony 규칙에 맞춰 직렬화해야 한다.

이 포맷은 OpenAI Responses API를 모사하도록 설계되었기 때문에, Responses API에 익숙한 개발자라면 구조 자체는 낯설지 않다. 다만 토큰 레벨까지 내려가면 새로운 약속들이 추가로 등장한다.

2. 핵심 개념 1 — 역할(Role)과 정보 계층

Harmony에서 모든 메시지는 역할(role)을 갖는다. 역할은 단순한 라벨이 아니라 명령 충돌 시 우선순위를 결정하는 정보 계층이다.

2-1. 5가지 역할의 의미

모델이 인식하는 역할은 다섯 가지다.

• system: 모델 정체성, 지식 컷오프, 현재 날짜, 추론 강도(reasoning effort), 사용 가능한 채널, 내장 도구를 선언한다. 일반적인 채팅 API의 "system prompt"와는 다른 개념이다.
• developer: 다른 포맷에서 흔히 "시스템 프롬프트"라 부르는 것, 즉 모델에게 주는 지시문과 함수 도구 목록이 들어간다.
• user: 모델에 대한 입력. 일반적인 의미와 동일하다.
• assistant: 모델의 출력. 도구 호출 메시지일 수도 있고 사용자에게 보여줄 응답일 수도 있다. 어느 쪽인지는 채널이 결정한다.
• tool: 도구 호출 결과를 모델에게 돌려줄 때 사용한다. 이때 역할 자리에는 tool이 아니라 구체적인 도구 이름(예: functions.get_current_weather)을 넣는다.

2-2. 역할 간 우선순위

지시가 충돌하면 모델은 다음 순서로 우선한다.

system > developer > user > assistant > tool

예를 들어 developer 메시지가 "항상 영어로 답하라"고 지시했는데 user가 "한국어로 답해"라고 요청하면, 모델은 developer의 지시를 우선한다. 이 규칙은 프롬프트 인젝션 방어의 기본 골격이기도 하다.

2-3. system과 developer의 차이

이 부분이 가장 헷갈리는 지점이다. 다른 LLM 포맷에서 "system prompt"라고 부르던 것이 Harmony에서는 developer 메시지에 해당한다. Harmony의 system 메시지는 모델 메타정보 전용 슬롯이다.

3. 핵심 개념 2 — 채널(Channel)과 메시지 의도

assistant 메시지는 항상 셋 중 하나의 채널을 갖는다. 채널은 메시지의 의도를 분류하는 직교축이다. 같은 assistant 역할이라도 채널이 다르면 처리 방식이 완전히 달라진다.

3-1. 3가지 채널의 역할 분담

• final: 사용자에게 보여줄 최종 응답.
• analysis: 모델의 추론 과정(chain-of-thought, CoT). 모델 내부용이다.
• commentary: 함수 도구 호출, 그리고 사용자에게 보여줄 행동 계획(프리앰블)이 들어간다.

3-2. analysis 채널을 사용자에게 노출하면 안 되는 이유

원문이 강조하는 가장 중요한 안전 규칙이다. analysis 채널의 출력은 final 채널과 같은 안전성 기준으로 학습되지 않았다. 따라서 CoT에는 유해 콘텐츠가 섞일 수 있고, 이를 그대로 노출하면 사용자 안전과 제품 신뢰도 양쪽이 무너진다. CoT는 디버깅이나 모델 개선에 활용하되, 최종 사용자에게는 final 채널만 보여주는 것이 원칙이다.

3-3. commentary는 어디에 쓰이는가

commentary는 두 가지 용도로 쓰인다. 첫째, 함수 도구 호출은 보통 commentary 채널로 나간다(반면 내장 도구 호출은 analysis 채널을 쓴다). 둘째, 모델이 여러 도구를 연달아 호출하기 전에 행동 계획을 사용자에게 알리는 프리앰블도 commentary 채널로 출력된다. 이 프리앰블은 CoT와 달리 사용자에게 보여줘도 안전하다.

4. 핵심 개념 3 — 특수 토큰과 메시지 포맷

직접 렌더러를 만든다면 특수 토큰을 정확히 알아야 한다. 특수 토큰은 모두 <|type|> 형식이며, tiktoken의 o200k_harmony 인코딩에 정의되어 있다.

4-1. 메시지의 일반 구조

모든 메시지는 다음 골격을 따른다.

<|start|>{header}<|message|>{content}<|end|>

{header}에는 역할과 (필요하면) 채널·수신자(recipient)·제약 타입이 들어간다. <|message|>는 헤더와 본문의 경계를 표시한다. <|end|>는 완성된 메시지의 종료를 의미한다.

4-2. 7가지 특수 토큰과 토큰 ID

4-3. 정지 토큰(<|return|>, <|call|>)의 의미

추론 루프는 정지 토큰을 만나면 멈춰야 한다.

• <|return|>이 나오면 모델은 최종 답변을 final 채널에 다 적었다는 뜻이다. 추론을 멈추고 결과를 사용자에게 반환한다.
• <|call|>이 나오면 도구 호출이 필요하다는 뜻이다. 추론을 멈추고 호출된 도구를 실행한 뒤, 결과를 tool 메시지로 다시 모델에 넣어 추론을 재개한다.

4-4. 💡 참고 — <|return|>을 <|end|>로 정규화하라

여기서 실수가 자주 난다. <|return|>은 디코딩 시점의 정지 토큰일 뿐, 영속적인 메시지 종결자가 아니다. 모델이 방금 생성한 응답을 다음 턴의 대화 기록으로 저장할 때는 끝의 <|return|>을 <|end|>로 바꿔야 한다.

# ❌ 잘못된 저장
<|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|return|>

# ✅ 올바른 저장
<|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|end|>

다음 턴 입력에 사용하는 모든 과거 메시지는 <|end|>로 끝나야 한다. 반대로 학습 데이터의 정답(target)은 <|return|>으로 끝나는 것이 맞다. 정지 토큰은 학습용, <|end|>는 보관용이라고 기억하면 된다.

5. 메시지 작성 실전 — 시스템 / 개발자 / 대화

5-1. system 메시지 — 모델 메타 설정

가장 기본적인 system 메시지의 형태는 다음과 같다.

<|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.
Knowledge cutoff: 2024-06
Current date: 2025-06-28

Reasoning: high

# Valid channels: analysis, commentary, final. Channel must be included for every message.<|end|>

핵심은 네 가지다. 첫 줄의 정체성 문구(You are ChatGPT...)는 그대로 두는 것이 안전하다. 모델 페르소나를 바꾸고 싶다면 system이 아니라 developer 메시지에서 지시한다. Reasoning: high로 추론 강도를 지정하고, # Valid channels: 줄에서 사용 가능한 채널을 선언한다.

함수 도구를 정의할 예정이라면 마지막에 한 줄을 더 추가한다.

Calls to these tools must go to the commentary channel: 'functions'.

5-2. developer 메시지 — 통상의 시스템 프롬프트

함수가 없을 때는 단순하다.

<|start|>developer<|message|># Instructions

{여기에 지시문}<|end|>

# Instructions 헤더 아래에 자연어로 지시를 적는다. 함수 도구나 응답 포맷을 정의할 때는 이 메시지에 추가 섹션이 붙는다(7장, 9장 참고).

5-3. 가장 단순한 대화 예제

다음은 user → assistant 한 턴의 입력/출력 흐름이다.

입력 (모델에 넣는 토큰):

<|start|>user<|message|>What is 2 + 2?<|end|>
<|start|>assistant

<|start|>assistant까지만 넣고 멈추면 모델이 그 다음을 이어서 생성한다.

출력 (모델이 생성한 토큰):

<|channel|>analysis<|message|>User asks: "What is 2 + 2?" Simple arithmetic. Provide answer.<|end|>
<|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|return|>

모델은 먼저 analysis 채널에 CoT를 쓰고, 그 다음 final 채널에 최종 답을 쓴 뒤 <|return|>으로 종료했다. 사용자에게는 2 + 2 = 4.만 노출한다.

6. 추론(Reasoning) 처리 규칙

gpt-oss는 추론 모델이다. 기본값은 medium이며, system 메시지에서 강도를 조절할 수 있다.

6-1. 추론 강도 설정

Reasoning: high

세 단계(low, medium, high) 중 하나를 고른다. 강도가 높을수록 analysis 채널에 더 긴 CoT가 생성되며, 응답 지연과 토큰 비용이 늘어난다.

6-2. CoT가 출력되는 위치

CoT는 항상 assistant 메시지의 analysis 채널로 나온다. 최종 답변은 final 채널이다. 둘은 같은 turn 안에서 연달아 생성된다.

6-3. 후속 샘플링 시 CoT 처리 규칙 — 핵심 비대칭

대화가 여러 턴 이어질 때 이전 턴의 CoT를 어떻게 다룰지가 가장 헷갈리는 지점이다. 규칙은 비대칭이다.

• 이전 턴이 final로 끝났다면: 다음 입력에서 그 턴의 analysis CoT는 버린다. final 메시지만 대화 기록에 남긴다.
• 이전 턴이 도구 호출로 이어진다면: CoT를 유지한다. 모델이 도구 결과를 받아 추론을 이어가려면 직전 CoT가 컨텍스트에 있어야 하기 때문이다.

예를 들어 첫 턴이 다음과 같이 끝났다면,

<|start|>user<|message|>What is 2 + 2?<|end|>
<|start|>assistant<|channel|>analysis<|message|>User asks...<|end|>
<|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|return|>

두 번째 턴 입력은 CoT를 빼고 다음처럼 구성한다.

<|start|>user<|message|>What is 2 + 2?<|end|>
<|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|end|>
<|start|>user<|message|>What about 9 / 2?<|end|>
<|start|>assistant

<|return|>이 <|end|>로 정규화된 점에 주목하라(4-4 참고).

7. 함수 호출(Function Calling)

7-1. TypeScript-like 문법으로 함수 정의하기

함수 도구는 developer 메시지의 # Tools 섹션 아래 ## functions 하위에 정의한다. 형식은 TypeScript 타입 선언과 비슷하다.

# Tools

## functions

namespace functions {

// Gets the current weather in the provided location.
type get_current_weather = (_: {
// The city and state, e.g. San Francisco, CA
location: string,
format?: "celsius" | "fahrenheit", // default: celsius
}) => any;

} // namespace functions

규칙은 다음과 같다.

• 인자가 없는 함수는 type fn = () => any 형태로 선언한다.
• 인자가 있으면 첫 번째 매개변수 이름을 _로 두고 객체 타입을 인라인으로 정의한다.
• 필드 설명은 해당 필드 위 줄에 // 주석으로 적는다.
• 반환 타입은 항상 any로 둔다.
• 함수 정의 사이에 빈 줄을 둔다.
• 모든 함수는 namespace functions 안에 묶는다(다른 학습된 도구 이름과 충돌을 피하기 위함).

JSON Schema를 직접 작성하기보다 openai_harmony 라이브러리의 ToolDescription을 사용하면 위 형식이 자동 생성된다.

7-2. 도구 호출 메시지 받기

모델이 함수를 호출하기로 결정하면 다음과 같은 메시지를 commentary 채널로 출력한다.

<|channel|>analysis<|message|>Need to use function get_current_weather.<|end|><|start|>assistant<|channel|>commentary to=functions.get_current_weather <|constrain|>json<|message|>{"location":"San Francisco"}<|call|>

세 가지 표시에 주목한다.

• 헤더에 to=functions.get_current_weather로 수신자(recipient) 가 명시된다.
• <|constrain|>json 토큰으로 본문이 JSON 타입임을 표시한다.
• 메시지가 <|end|>가 아니라 <|call|>로 끝난다. 추론을 멈추고 도구를 실행하라는 신호다.

7-3. 도구 결과 돌려주기

도구를 실행한 뒤 결과를 모델에 다시 넣을 때는 tool 메시지를 다음 형식으로 만든다.

<|start|>{toolname} to=assistant<|channel|>commentary<|message|>{output}<|end|>

역할 자리에 도구 이름을 직접 넣는 것에 주의한다. 위 예제의 결과를 돌려주는 메시지는 다음과 같다.

<|start|>functions.get_current_weather to=assistant<|channel|>commentary<|message|>{"sunny": true, "temperature": 20}<|end|>

이후 <|start|>assistant를 붙여 모델이 응답 생성을 재개하도록 한다. 이때 이전 turn의 analysis CoT를 함께 보존해야 한다(6-3 비대칭 규칙).

7-4. 프리앰블 — 사용자에게 보여줄 행동 계획

모델이 여러 도구를 연달아 호출할 계획이라면, 사용자에게 무엇을 할지 미리 알리는 메시지를 commentary 채널에 출력하기도 한다.

<|start|>assistant<|channel|>commentary<|message|>**Action plan**:
1. Generate an HTML file
2. Generate a JavaScript for the Node.js server
3. Start the server
---
Will start executing the plan step by step<|end|>

이 메시지는 CoT와 달리 사용자에게 노출해도 된다. 같은 commentary 채널이지만 수신자(to=)가 없으면 사용자 대상 메시지, 있으면 도구 호출 메시지로 구분한다.

8. 내장 도구(browser, python)

gpt-oss는 학습 단계에서 browser(웹 검색)와 python(코드 실행) 두 가지 내장 도구에 노출되었다. 이 둘을 그대로 활용하려면 정해진 시그니처를 따르는 것이 정확도를 높인다.

8-1. 내장 도구는 system 메시지에 정의한다

함수 도구가 developer 메시지에 정의되는 것과 달리, 내장 도구는 system 메시지의 # Tools 섹션에 들어간다. 이 차이가 채널 분기에도 영향을 준다.

8-2. browser 도구의 인터페이스

browser 도구는 search, open, find 세 가지 액션을 제공한다.

# Tools

## browser

// Tool for browsing.
// Cite information from the tool using the following format:
// `【{cursor}†L{line_start}(-L{line_end})?】`, for example: `【6†L9-L11】` or `【8†L3】`.
// Do not quote more than 10 words directly from the tool output.
namespace browser {

type search = (_: {
query: string,
topn?: number, // default: 10
source?: string,
}) => any;

type open = (_: {
id?: number | string, // default: -1
cursor?: number, // default: -1
loc?: number, // default: -1
num_lines?: number, // default: -1
view_source?: boolean, // default: false
source?: string,
}) => any;

type find = (_: {
pattern: string,
cursor?: number, // default: -1
}) => any;

} // namespace browser

인용 포맷(【cursor†L시작-L끝】)과 직접 인용 10단어 제한은 모델 학습 단계에서 강제된 규약이다. 자체 검색 도구를 만들 때 같은 형식을 따르면 모델이 자연스럽게 인용을 생성한다.

8-3. python 도구의 인터페이스

python 도구는 별도 타입 선언 없이 자연어 설명만 둔다.

# Tools

## python

Use this tool to execute Python code in your chain of thought. The code will not be shown to the user. This tool should be used for internal reasoning, but not for code that is intended to be visible to the user (e.g. when creating plots, tables, or files).

When you send a message containing Python code to python, it will be executed in a stateful Jupyter notebook environment. python will respond with the output of the execution or time out after 120.0 seconds. The drive at '/mnt/data' can be used to save and persist user files. Internet access for this session is UNKNOWN. Depends on the cluster.

stateful Jupyter 환경, 120초 타임아웃, /mnt/data 영속 디렉터리 같은 약속이 모델 안에 박혀 있다. 자체 코드 실행기를 만든다면 이 사양을 흉내 내는 것이 호환성에 유리하다.

8-4. 채널 차이 — analysis vs commentary

내장 도구와 사용자 정의 함수의 가장 큰 차이는 호출 채널이다.

내장 도구가 analysis로 가는 이유는 모델 입장에서 이들을 "추론을 위한 보조 수단"으로 학습했기 때문이다. 단, 실무에서는 가끔 commentary로 출력되는 경우도 있으므로 두 채널 모두 처리할 수 있도록 파서를 만든다.

9. 구조화된 출력(Structured Output)

응답을 정해진 JSON 스키마에 맞추고 싶다면 developer 메시지 끝에 # Response Formats 섹션을 추가한다.

# Response Formats

## shopping_list

{"properties":{"items":{"type":"array","description":"entries on the shopping list","items":{"type":"string"}}},"type":"object"}

## {format name} 아래에 JSON Schema를 한 줄로 적는다. 이 이름은 OpenAI Responses API에서 스키마에 부여하는 name과 동일한 역할이다.

다만 이 프롬프트만으로는 스키마 준수가 보장되지 않는다. 모델의 출력 경향만 유도할 뿐, 토큰 단위 강제는 별도 grammar/sampling 제약이 필요하다. outlines, lm-format-enforcer, xgrammar 같은 라이브러리로 디코딩 단계에서 스키마를 강제해야 완전한 보장이 된다.

10. 직접 구현 vs Harmony 라이브러리

직접 토큰을 조립하는 대신 openai_harmony 공식 라이브러리를 쓰는 편이 일반적으로 안전하다.

10-1. openai_harmony 라이브러리로 메시지 만들기

다음은 시스템·개발자·사용자·CoT·함수 호출·도구 결과까지 한 번에 구성하는 예제다.

from openai_harmony import (
    Author,
    Conversation,
    DeveloperContent,
    HarmonyEncodingName,
    Message,
    Role,
    SystemContent,
    ToolDescription,
    load_harmony_encoding,
    ReasoningEffort,
)

# Harmony 인코딩 로드 (gpt-oss 전용)
encoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)

# system 메시지: 추론 강도와 현재 날짜 설정
system_message = (
    SystemContent.new()
    .with_reasoning_effort(ReasoningEffort.HIGH)
    .with_conversation_start_date("2025-06-28")
)

# developer 메시지: 지시문과 함수 도구 정의
developer_message = (
    DeveloperContent.new()
    .with_instructions("Always respond in riddles")
    .with_function_tools([
        ToolDescription.new(
            "get_current_weather",
            "Gets the current weather in the provided location.",
            parameters={
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"},
                    "format": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"},
                },
                "required": ["location"],
            },
        ),
    ])
)

convo = Conversation.from_messages([
    Message.from_role_and_content(Role.SYSTEM, system_message),
    Message.from_role_and_content(Role.DEVELOPER, developer_message),
    Message.from_role_and_content(Role.USER, "What is the weather in Tokyo?"),
    # 이전 턴의 CoT (analysis 채널)
    Message.from_role_and_content(
        Role.ASSISTANT,
        'User asks: "What is the weather in Tokyo?" We need to use get_current_weather tool.',
    ).with_channel("analysis"),
    # 함수 호출 메시지 (commentary 채널, recipient 지정)
    Message.from_role_and_content(Role.ASSISTANT, '{"location": "Tokyo"}')
        .with_channel("commentary")
        .with_recipient("functions.get_current_weather")
        .with_content_type("<|constrain|> json"),
    # 도구 실행 결과 (tool 역할에 도구 이름 지정)
    Message.from_author_and_content(
        Author.new(Role.TOOL, "functions.get_current_weather"),
        '{ "temperature": 20, "sunny": true }',
    ).with_channel("commentary"),
])

# 다음 응답 생성을 위한 토큰 시퀀스 생성
tokens = encoding.render_conversation_for_completion(convo, Role.ASSISTANT)

# 모델이 토큰을 반환한 뒤, 정지 토큰을 제외하고 파싱
parsed_response = encoding.parse_messages_from_completion_tokens(new_tokens, Role.ASSISTANT)

라이브러리가 채널·수신자·<|constrain|> 토큰을 모두 알아서 직렬화한다. 직접 문자열을 만들 때 흔히 빠지는 공백·줄바꿈 실수를 피할 수 있다.

10-2. StreamableParser로 토큰 스트리밍 파싱하기

스트리밍 응답을 받을 때는 StreamableParser로 토큰을 하나씩 흘려넣으면서 현재 채널·역할·콘텐츠를 추적할 수 있다.

from openai_harmony import (
    HarmonyEncodingName,
    Role,
    StreamableParser,
    load_harmony_encoding,
)

encoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)
stream = StreamableParser(encoding, role=Role.ASSISTANT)

# 모델이 흘려보내는 토큰을 한 개씩 process()에 전달
for token in incoming_tokens:
    stream.process(token)

    # 현재 어느 채널의 무슨 내용을 받고 있는지 실시간 확인 가능
    if stream.current_channel == "final":
        # 사용자에게 흘려보낼 텍스트
        print(stream.last_content_delta, end="", flush=True)

current_channel이 final일 때만 사용자 화면에 출력하고, analysis일 때는 로그로만 남기는 식으로 안전하게 분기할 수 있다. 유니코드 문자가 토큰 경계에서 잘리는 문제도 파서가 처리해 준다.

10-3. 어떤 경우에 직접 렌더러를 만들어야 하나

직접 만든다면 4장의 특수 토큰 표와 본 문서 곳곳의 메시지 예시를 골든 샘플로 두고, 라이브러리 출력과 바이트 단위로 비교하며 검증하는 것이 안전하다.

11. 참고 자료

• OpenAI Harmony Response Format 공식 문서 — 본 글의 원문
• openai-harmony PyPI 패키지 — Python 렌더러
• openai-harmony crates.io 패키지 — Rust 렌더러
• openai/harmony GitHub 저장소 — 소스 코드와 추가 예제
• gpt-oss 모델 카드 — 안전성 기준과 학습 정보
• tiktoken o200k_harmony 인코딩 — 특수 토큰 ID 확인용

Harmony 포맷의 핵심은 역할(role)과 채널(channel)을 분리해 추론 과정과 최종 답변을 명확히 구분하는 데 있다.

vector RAG는 의미가 비슷한 chunk를 모아오고, graph RAG는 관계를 따라 추론한다. 두 retrieval은 서로 다른 질문에 답한다.

1. AI Agent와 LLM의 한계

LLM 기반 챗봇은 단순 질의응답을 넘어 AI agent 형태로 진화하고 있다. AI agent는 환경과 상호작용하면서 자율적으로 판단·행동하는 시스템으로 정의된다. 사전에 정해진 명령만 따르는 전통적 프로그램과 달리, agent는 사용 가능한 tool을 스스로 선택하고 결과를 평가해 다음 행동을 결정한다.

이전 편들에서 다룬 내용 — 비정형 문서로부터 entity·relationship을 추출해 KG로 모델링하는 과정 — 은 결국 이 agent가 활용할 외부 지식 소스를 만드는 작업이다. 본 편은 그렇게 구축된 KG를 retrieval 백엔드로 사용하는 RAG 구조를 다룬다.

production 환경에서 LLM 단독 사용이 어려운 이유는 다음과 같이 정리된다.

LLM은 본질적으로 다음 token의 확률을 예측하는 모델이다. 학습 분포를 벗어난 질문에도 모델은 "가장 그럴듯한 출력"을 생성하므로, 응답이 틀려도 표면적으로는 일관되게 보인다. RAG는 이 구조적 한계를 외부 context 주입으로 보완하기 위한 접근이다.

2. Vector RAG의 동작과 한계

RAG는 사전학습된 LLM의 언어 이해력에 외부 데이터로부터 retrieval한 context를 결합하는 grounding 기법이다. 초기 RAG 구현은 거의 전적으로 텍스트 문서를 chunk 단위로 쪼개고 embedding으로 변환해 vector database에 색인하는 방식이었다.

질문이 들어오면 동일한 embedding 모델로 질문을 vector로 변환하고, vector database에서 의미적으로 가장 가까운 chunk들을 retrieve한다. retrieved chunk들은 prompt context로 주입되어 LLM이 최종 답변을 생성한다. Neo4j는 graph 구조를 가진 데이터베이스이지만 Neo4jVector 같은 인터페이스를 통해 vector index도 제공한다.

# 문서 chunk를 embedding으로 변환하고 vector index 생성
vector_index = Neo4jVector.from_existing_graph(
    embedding=OpenAIEmbeddings(),
    url=NEO4J_URL,
    username=NEO4J_USER,
    password=NEO4J_PWD,
    database=NEO4J_DB,
)

이 구조는 단순하고 강력하지만 다음과 같은 한계를 가진다.

• Context fragmentation으로 인한 추론 제약: chunk 단위로 독립 retrieve되므로 여러 문서·entity를 가로지르는 multi-hop 관계 추론이 어렵다. 정답에 필요한 정보가 두 chunk에 걸쳐 있고 그중 하나만 retrieve되면 답변은 부정확해진다.
• Scalability: corpus 규모가 커질수록 정확한 nearest neighbor search 비용이 급증해 approximate search로 후퇴할 수밖에 없다.
• Embedding의 표현 한계: 문서 전체 의미를 단일 dense vector로 압축하는 과정에서 fine-grained semantic·도메인 특화 뉘앙스가 손실된다. embedding 모델 학습 데이터에서 sparse하게 등장한 용어는 더 부정확하게 표현된다.
• Retrieval noise: vector similarity가 높지만 실제로는 무관한 문서가 섞여 LLM의 distraction을 유발한다. 긴 context에서는 noise 증가가 출력 품질을 악화시킨다.
• Retrieval miss: "이 데이터셋의 핵심 연구 주제는?" 같은 집계형 질문은 의미 유사도와 정답 적합도가 일치하지 않아 vector search 자체로는 답할 수 없다.

요약하면 vector RAG는 "의미적으로 비슷한 텍스트"를 잘 찾지만, "관계를 따라간 결과로서의 사실"을 답하는 데는 약하다.

3. Graph RAG: KG를 retrieval 백엔드로

위 한계의 해법으로 등장한 것이 Graph RAG이다. KG는 단순 텍스트가 아닌 entity·relationship과 메타데이터, 구조화된 데이터(table, ontology 등)를 한 곳에 통합한 central knowledge repository로 작동한다. 도메인 전문가가 직접 검증·수정할 수 있어 transparency가 높고, 사실의 추가·갱신이 쉬워 freshness 문제도 완화된다.

Graph RAG agent는 KG를 활용하는 방식에 따라 여러 retriever tool을 가진다.

각 tool의 역할은 다음과 같이 구분된다.

KG retriever는 사용자 질문과 KG schema를 LLM에 제공해 Cypher query를 생성하게 한다. 또는 질문에 등장한 entity들을 받아 그 사이의 shortest path subgraph를 반환하고, 어떤 부분을 답변에 사용할지는 LLM이 결정하게 한다.

KG-enhanced document retriever는 KG가 text-paired graph일 때 가능한 방식이다. node·relationship이 원본 문서까지 추적 가능하므로, "사용자가 언급한 모든 entity를 포함하는 문서만" 같은 정밀 필터링이 가능하다. vector search의 retrieval miss를 직접 해소한다.

Combined retrieval은 질문이 여러 소스에 걸칠 때 사용된다. 예를 들어 "범죄조직 X의 두목의 올해 거래 내역은?"이라는 질문은 법 집행 기관 KG에서 두목의 실명을 추출한 뒤, 그 이름으로 금융 문서 DB를 검색하는 두 단계로 분해된다.

4. Text-attributed graph와 Text-paired graph

Graph RAG의 retrieval 정밀도는 KG 설계에 직접적으로 좌우된다. 가장 유용한 설계는 두 종류의 graph 구조를 결합하는 형태이다.

• Text-attributed graph: node와 relationship이 텍스트 속성을 가진다. entity 자체에 description, type 등이 붙어 LLM이 직접 활용할 수 있다.
• Text-paired graph: node와 relationship이 출처 문서로 추적 가능하다. KG로 좁힌 결과를 문서 retrieval로 연결할 수 있다.

이 둘이 결합되면 정형화된 지식과 원문 문서를 함께 활용할 수 있어 metadata 기반 community 식별, 최신 버전 문서 우선 retrieval 등 다양한 전략이 가능해진다. 답변 예시로 "Harvard와 Johns Hopkins의 공통 연구 주제는?"이라는 질문에 KG의 university-topic 관계를 traversal 해 "astronomy, climatology"라는 정확한 사실을 반환할 수 있다.

5. 한계와 트레이드오프

Graph RAG가 vector RAG의 약점을 상쇄한다고 해서 만능은 아니다. 본 챕터의 개념에서 도출되는 한계는 다음과 같이 정리된다.

• KG 구축 비용이 선행 부담으로 전이된다: vector RAG는 chunking·embedding으로 인덱스가 빠르게 구축되지만, KG는 entity·relationship 추출과 ontology 설계에 사람의 손이 필요하다. retrieval 단계의 정확도를 얻는 대가로 ETL 비용이 앞단에 집중된다.
• Cypher query 생성 자체가 또 다른 hallucination 지점: KG retriever는 LLM이 schema를 보고 Cypher를 생성하게 한다. schema가 복잡하거나 질문이 모호하면 잘못된 query가 생성되어 빈 결과·오답으로 이어진다. retrieval의 정확성을 확보하려면 schema 설계 자체가 자기 설명적이어야 한다.
• Entity coverage의 함정: KG에 존재하지 않는 entity·관계는 graph traversal로는 절대 도달할 수 없다. text-paired graph가 없는 환경에서는 "KG에 없는 사실을 묻는 질문"이 silent failure를 일으킨다. 이 때문에 vector retriever와 fallback 구조가 여전히 필요하다.
• 확률적 모델의 한계는 잔존: RAG는 hallucination 확률을 낮출 뿐 제거하지 못한다. context가 정확해도 LLM은 여전히 가장 그럴듯한 token을 생성하는 모델이며, 시스템은 사람을 대체하기보다 augment하는 방향으로 설계되어야 한다. feedback·검증 루프 없이는 production 도입이 어렵다.

6. 실무 적용 시 고려사항

Graph RAG를 실제 시스템에 도입할 때 결정적인 설계 포인트는 어떤 retriever를 어떤 질문에 어떻게 라우팅할 것인가이다. 모든 질문을 KG retriever로 보내면 단순한 의미 검색에서 오히려 비효율적이고, 모든 질문을 vector retriever로 보내면 multi-hop 추론이 끊긴다. agent의 tool 선택 prompt와 fallback 정책 설계가 시스템 품질을 좌우한다.

또한 KG는 살아있는 자산이다. 도메인 전문가가 검증·수정 가능한 인터페이스를 제공해 출력 품질을 직접 개선할 수 있게 만들면 transparency와 user confidence가 함께 올라간다. 반대로 한 번 구축하고 방치된 KG는 stale knowledge로 변해 freshness 문제를 다시 끌어들인다. KG의 운영 거버넌스 — 누가, 어떤 주기로, 어떤 검증을 거쳐 갱신하는가 — 가 retrieval 알고리즘만큼 중요하다.

7. 정리

두 방식은 대체재가 아니라 보완재이다. production 시스템은 보통 두 retriever를 함께 두고 질문 유형에 따라 라우팅하거나 결과를 병합한다.

결론: Graph RAG는 vector RAG의 "비슷한 chunk 모으기"가 놓치는 관계·집계·multi-hop 질문을 풀기 위한 구조이며, 두 retrieval은 경쟁이 아니라 역할 분담 관계로 설계되어야 한다.

참고 자료

• Knowledge Graphs and LLMs in Action. Manning Publications, 2025. Chapter 13: Knowledge graph-powered retrieval-augmented generation.

지능형 시스템(intelligent system)은 사용자를 AI/ML과 연결해 의미 있는 목적을 달성하는 시스템으로 정의된다. 핵심 속성은 사용자와의 상호작용을 관찰하며 시간에 따라 지능이 진화한다는 점이다. 외부에서 보면 복잡한 작업을 수행하는 black box이지만, 이를 이해하기 위한 첫 단계는 기능 단위로 분해하는 것이다.

지능형 에이전트는 두 개의 핵심 컴포넌트로 분해된다. knowledge representation은 AI 시스템이 도메인 정보를 구조화·인코딩·전달하기 위해 사용하는 "언어"이며, AI가 추론하고 예측하기 위한 전제이자 그 결과를 해석하는 수단이다. 어떤 표현을 선택하느냐가 시스템의 능력과 한계를 결정한다. reasoning은 정보를 분석하고 규칙을 적용해 결론을 도출하는 인지 과정으로, deductive·inductive 등 여러 형태가 있다. KG와 LLM을 결합한 시스템은 이 reasoning 능력을 확장하는 방향으로 발전하고 있다.

2. Autonomous System vs Advisor System

지능형 시스템은 사용자를 대신해 행동하는가, 아니면 지원하는가에 따라 두 범주로 나뉜다. intelligent autonomous system은 사용자를 대체해 의사결정과 실행을 수행하고, intelligent advisory system(IAS)은 정보와 추천을 제공하되 실행 권한은 사용자에게 남긴다.

두 경우 모두 사용자를 대체하는 것이 아니라 사용자를 지원·보조한다는 점이 핵심이다. 책에서 채택하는 설계 방향은 autonomous advisor 쪽이다. 즉, 행동이 아닌 제안을 생성하되, 일반 지식이 아니라 도메인 전문가가 정제한 established knowledge base 위에서 동작하고, 제안 결과의 피드백으로 지식 베이스를 확장한다.

3. 지능형 시스템의 네 가지 설계 축

설계와 구현을 동시에 견인하는 네 가지 특성이 존재한다. meaningful objective는 시스템이 존재하는 구체적이고 달성 가능한 목적이며, 전체 개발 과정을 끌고 가는 축이다. intelligent experience는 예측 결과를 사용자에게 어떻게 제시하느냐의 문제로, 예측이 맞을 때 가치를 극대화하고 틀렸을 때 비용을 최소화하는 인터페이스를 요구한다. 동시에 implicit/explicit 피드백을 수집할 수 있어야 한다. knowledge creation and update는 변화하는 지식과 사용자 피드백을 지속적으로 반영하는 능력이며, LLM과 KG의 결합이 이 지점을 보강한다. orchestration은 다수의 알고리즘과 도구가 서로의 출력을 입력으로 삼아 협업하도록 조율하는 일을 가리킨다.

4. Knowledge Acquisition: KG와 LLM의 비대칭

knowledge acquisition은 원천 데이터를 reasoning engine이 사용할 수 있는 형태로 변환하는 단계다. KG와 LLM은 이 단계에서 근본적으로 다른 경로를 밟는다.

KG의 acquisition은 entity·relationship·property 단위로 데이터를 명시적 구조에 매핑하는 작업이며, 도메인 전문가가 데이터 소스 선정·스키마 설계·결과 검증 전 단계에 개입할 수 있다. LLM의 acquisition은 주로 unsupervised 학습으로 텍스트를 통계적 파라미터에 흡수하는 과정이며, 도메인 전문가의 개입은 데이터 선택과 결과 평가에 제한된다. 모델 내부 표현을 직접 보거나 수정할 수 없고, 커스텀 fine-tuning이 거의 유일한 보강 수단이다.

이 비대칭은 세 가지 설계 차이로 귀결된다.

5. Reasoning과 하이브리드 IAS의 근거

reasoning은 acquisition된 knowledge 위에서 수행되며, 새로운 지식을 생성하거나 답·제안·자율 행동을 만들어낸다. KG는 정밀한 rule-based 추론과 explicit 표현이 필요한 작업에 강하고, LLM은 패턴 인식·맥락 이해·모호하거나 불완전한 정보 처리에 강하다. 두 접근 모두 인간 수준의 common-sense reasoning은 본질적으로 갖추지 못하며, 직관적 비약이나 암묵적 맥락 파악에서 한계를 드러낸다. 이 한계가 역설적으로 hybrid IAS의 설계 근거가 된다.

ML이 KG에 기여하는 두 가지 경로가 있다. 첫째, 관련 ontology와 relationship을 학습·구축해 knowledge base의 커버리지를 확장한다. 둘째, 불확실성 하의 inference를 제공해 데이터가 불완전한 경우에도 예측을 가능하게 한다. 반대 방향에서, KG는 generative AI의 hallucination을 완화하고 최신 데이터를 공급하는 grounding 장치로 기능한다.

6. KG 구축 방식: Top-down vs Bottom-up

KG를 어떤 순서로 구축하느냐에 따라 프로젝트 성공률이 달라진다. bottom-up은 가용한 모든 데이터를 먼저 적재하고 그래프로 변환한 뒤, 어떤 task에 활용할지 사후에 고민하는 방식이다. 데이터가 이미 다 들어가 있어 스키마 변경이 어렵고, 결과적으로 functional task와 무관하게 비대해진 그래프가 나오기 쉽다. top-down은 비즈니스 목표와 functional task에서 출발해 필요한 데이터·스키마·모델을 역으로 정의하는 CRISP-DM 유형의 사이클을 따른다.

책은 top-down 방식을 권고한다. 명확한 목적이 없는 데이터 통합은 프로젝트 실패의 주요 원인이기 때문이다.

7. 한계와 트레이드오프

하이브리드 접근은 강력하지만 무비용은 아니다. 본문 개념에서 도출되는 트레이드오프는 다음과 같다.

첫째, 운영 복잡도의 증가. KG와 LLM을 동시에 관리한다는 것은 두 개의 서로 다른 lifecycle을 다룬다는 의미다. KG는 스키마 변경·데이터 일관성·전문가 검증 주기를 가지며, LLM은 재학습·fine-tuning·평가 셋 관리 주기를 가진다. orchestration 레이어가 늘어날수록 디버깅 지점도 늘어난다.

둘째, 업데이트 비대칭의 비용. KG는 노드/엣지 단위로 즉시 갱신할 수 있지만, LLM의 implicit 지식은 재학습 없이는 갱신되지 않는다. 따라서 "최신성"이 중요한 도메인일수록 사실 정보는 KG로 외부화하고 LLM은 언어 처리 계층으로 좁혀 사용하는 분업이 합리적이다. 이는 GraphRAG 계열 아키텍처가 일관되게 따르는 설계 원칙이기도 하다.

셋째, common-sense의 빈자리. 두 접근 모두 인간의 직관적 추론은 갖추지 못한다. 시스템이 "당연한" 맥락을 놓쳐 잘못된 제안을 내놓을 수 있으므로, autonomous 모드보다 advisory 모드가 안전하다는 결론은 단순한 보수적 선택이 아니라 기술적 한계에 근거한 설계 결정이다.

8. 실무 적용 시 고려사항

production 환경에서 하이브리드 IAS를 도입할 때 가장 먼저 결정할 것은 autonomous와 advisory 사이의 위치다. 의료·금융·법률처럼 실패 비용이 큰 도메인일수록 advisory 쪽으로 무게중심을 이동시키고, intelligent experience 단계에서 신뢰도와 근거를 함께 제시하는 인터페이스를 설계해야 한다. 사용자의 implicit/explicit 피드백을 KG로 환류시키는 경로를 처음부터 확보하지 않으면, 시스템은 시간이 지나도 진화하지 않는다.

다음으로 KG의 scope를 task에 맞춰 좁게 시작해야 한다. bottom-up으로 시작한 프로젝트가 실패하는 흔한 이유는 그래프가 충분히 풍부해도 그것을 활용할 reasoning task가 정의되어 있지 않기 때문이다. top-down 방식으로 단일 functional task를 먼저 해결하고, 거기서 검증된 스키마를 옆으로 확장하는 incremental 전략이 안전하다.

참고 자료

• Knowledge Graphs and LLMs in Action, Manning Publications, 2024 — Chapter 2: Intelligent systems: A hybrid approach

RAG(Retrieval-Augmented Generation)는 외부 지식을 LLM에 주입해 hallucination을 줄이는 기법이다. 그러나 "외부 지식을 어떻게 표현하고 검색하는가"에 따라 두 갈래로 나뉜다.

• Vector RAG: 텍스트를 chunk로 쪼개 embedding한 뒤 의미 유사성으로 검색
• Graph RAG: 텍스트에서 entity와 relationship을 추출해 knowledge graph로 구성한 뒤 관계망을 따라 검색

질문의 성격이 검색 방식을 결정한다. "비슷한 문서 찾기"는 vector, "관계 따라 추론하기"는 graph다.

2. Vector RAG: 평면 표현의 강점과 한계

2.1 동작 구조

표준 파이프라인은 다음과 같다.

ANN 인덱스 위에서 단일 단위인 chunk를 빠르게 돌려주는 단순한 구조다. 긴 문서 하나를 통째로 embedding하면 여러 주제가 섞여 정보성이 희석되므로, 작게 쪼개야 의미 포착이 살아난다.

2.2 강점이 드러나는 영역

Vector RAG가 잘 작동하는 자리는 명확하다.

• 문서 QA: long-form 문서에서 답이 있는 문단 찾기
• Technical support: Jira, Slack, 콜센터 로그 검색
• 사내 문서·FAQ: 근무 규정, 온보딩, 제품 매뉴얼
• Code/doc search: 함수명·설명·주석을 넘나드는 검색

2.3 한계가 드러나는 지점

Vector RAG는 본질적으로 평면 표현이다. chunk A와 B의 관계, entity 간 참여·소유·계층, 시간적 선후 관계는 embedding 안에 암묵적으로만 들어간다. 질문이 "비슷한 문서 찾기"에서 "관계 따라 추론하기"로 바뀌는 순간 이 한계가 표면화된다.

3. Graph RAG: 개체와 관계의 저장소

3.1 핵심 발상

Graph RAG는 문서가 아니라 개체와 관계를 저장한다. unstructured 텍스트에서 entity와 relationship을 추출해 knowledge graph 또는 property graph로 구성하는 방식이다.

Microsoft GraphRAG의 사례에서, source document로부터 entity graph를 만든 뒤 인접 entity group에 대해 community summary를 미리 생성하고, query 시점에 partial response를 합성한다. "데이터셋 전체의 주요 테마는 무엇인가"와 같은 global question에서 naive RAG 대비 comprehensiveness와 diversity가 개선된다고 보고되었다.

3.2 구축·검색 파이프라인

검색 대상이 chunk 한 단위가 아니라 구조 전체라는 점이 vector RAG와의 결정적 차이다.

4. 네 가지 Graph 패턴

"Graph RAG"라는 이름 안에는 최소 네 가지 서로 다른 graph 구성 방식이 존재한다. 답해야 할 질문 유형에 따라 선택이 달라진다.

4.1 Lexical Graph

가장 단순한 형태다. Document 노드는 문서명·출처를 갖고, Chunk 노드는 human-readable text와 vector embedding을 가지며, 두 노드는 PART_OF 관계로 연결된다. 질문 embedding과 chunk embedding 간 vector similarity로 top-k를 찾는 Basic Retriever의 그래프 기반이 된다.

4.2 Hierarchical Lexical Graph

문서 구조를 그대로 계승한다. HAS_CHAPTER, HAS_SECTION, HAS_SUBSECTION, PART_OF 등의 edge로 계층을 구성한다. 두 가지 retrieval 모드가 가능하다.

• Bottom-up: leaf에서 similarity search 후 상위 chunk로 확장
• Top-down: 상위 노드에서 subtree 선택 후 좁혀가며 탐색

4.3 Domain Graph

실세계 entity와 그 사이 관계를 담는 그래프다. Movie graph, Northwind schema가 대표적이다. 도메인마다 모양이 다르기 때문에 일반 blueprint를 제공하기 어렵지만, schema에 따르는 structured data라는 공통점을 갖는다. 자연어 질문이 deterministic한 구조적 조회로 풀릴 때 유용하며, Text2Cypher나 Pattern Matching의 기반이 된다.

4.4 Lexical + Entities + Communities

세 층의 그래프를 결합한 가장 풍부한 형태다.

• Chunk에서 entity와 relationship 추출
• Domain Graph 위에서 Leiden 알고리즘으로 계층 커뮤니티 형성
• 각 커뮤니티에 대해 LLM이 community summary 생성

Community 노드는 level, name, summary, weight 속성을 갖는다. "데이터셋 전체 테마는 무엇인가"와 같은 global 질문에서 특히 강하다.

5. KG와 LLM의 상호 보완

책에서는 두 기술의 결합을 단순한 조합이 아닌 패러다임 전환으로 본다. KG는 명시적·검증 가능·갱신 가능한 지식 표현을 제공하고, LLM은 자연어 이해·생성 능력을 제공한다.

LLM은 unstructured 텍스트에서 entity와 relationship을 추출해 KG 구축을 자동화하고, KG는 신뢰할 수 있는 도메인 지식으로 LLM 응답을 grounding한다. 구체적으로는 다음 세 문제를 해결한다.

• Hallucination: KG의 verified knowledge가 사실 기반을 제공한다. text-to-cypher 변환은 자연어 질문을 정확한 graph query로 바꿔 신뢰 가능한 정보를 직접 추출한다.
• Stale information: LLM은 상시 재학습이 어렵지만 KG는 지속 갱신이 가능하다. GraphRAG는 community summary를 통해 최신 정보를 LLM에 주입한다.
• Explainability: KG는 추론 경로를 추적·검증 가능하게 만든다. LLM의 자연어 처리와 결합되어 결과가 사람이 읽을 수 있는 형태로 정리된다.

6. KG의 네 기둥

KG를 다음과 같이 정의할 수 있다. Knowledge graph는 typed entity, 속성, 의미 있는 named relationship으로 구성된 지속적으로 진화하는 graph data structure이며, 특정 도메인을 위해 structured·unstructured 데이터를 통합한다. 이 정의는 네 가지 축으로 정리된다.

7. 한계와 주의사항

Graph RAG가 만능은 아니다. 다음 난제가 존재한다.

• Graph construction의 품질·비용 trade-off: LLM 기반 추출은 recall이 높지만 hallucinated edge를 만든다. rule-based는 precision이 좋지만 recall이 낮다. ontology를 정교하게 설계할수록 비싸고, 느슨할수록 결과가 지저분해진다.
• 튜닝 포인트의 차이: vector RAG가 chunk 크기·embedding 모델 중심이라면, graph RAG는 ontology, entity canonicalization, relation type 설계, source provenance, graph update 전략, confidence score, temporal validity 등 지식 모델링의 축을 다뤄야 한다.
• 평가 지표의 부재: "정답 맞췄나"만 측정하면 graph RAG의 가치를 제대로 보지 못한다. global sensemaking, explainability, multi-hop reasoning을 평가할 별도 지표가 필요하다.
• KG 자체의 채택 장벽: 책은 KG가 널리 보급되지 못한 이유로 구축·유지비용, 다중 hop을 요구하는 복잡한 access pattern, 다수 노드·관계에 분산된 결과를 든다.

결론: Vector RAG는 의미 유사성에 강하고 Graph RAG는 관계 추론에 강하다. 둘은 선택의 문제가 아니라 조합의 문제이며, KG와 LLM의 결합은 hallucination·stale information·explainability라는 LLM의 구조적 한계를 보완하는 패러다임 전환이다.

참고 자료

• Knowledge Graphs and LLMs in Action, Chapter 1: Knowledge graphs and LLMs: A killer combination

파이썬의 슬라이싱(list[start:end:step])은 강력합니다. 리스트, 문자열, 튜플, bytes 등 시퀀스 타입이면 다 통하죠. 그런데 다른 언어에서 배열을 다루던 습관이 남아 있으면 필요 없는 0이나 len()을 끝까지 꾸역꾸역 쓰는 코드가 나옵니다. 틀린 건 아니지만, 파이썬다운 코드는 아니에요.

또 슬라이싱이 "원본의 일부를 참조하는 건지, 복사본을 만드는 건지" 헷갈려서 이상한 버그를 만드는 경우도 자주 봅니다. 리스트 슬라이싱은 새로운 리스트를 반환한다는 점, 이걸 꼭 기억해야 해요.

💣 흔한 실수

numbers = [10, 20, 30, 40, 50, 60, 70, 80]

# 처음부터 / 끝까지인데도 굳이 0과 len() 써주기
first_three = numbers[0:3]        # ❌ 0은 생략 가능
last_two = numbers[len(numbers)-2:len(numbers)]  # ❌ 장황함

# 음수 인덱스 활용 못 하고 복잡하게
last = numbers[len(numbers)-1]    # ❌

# 슬라이스가 "뷰"인 줄 알고 원본 수정된다고 착각
copy = numbers[:]
copy.append(999)
print(numbers)  # 원본은 그대로 (새 리스트이기 때문)

numbers[0:3]은 numbers[:3]과 완전히 같고, numbers[len(numbers)-2:]은 그냥 numbers[-2:]로 쓰면 됩니다. len()을 슬라이싱 안에서 쓰는 순간 코드에 냄새가 난다고 봐도 돼요.

✅ 파이썬다운 방법

numbers = [10, 20, 30, 40, 50, 60, 70, 80]

# 처음부터 → start 생략
first_three = numbers[:3]         # [10, 20, 30]

# 끝까지 → end 생략
from_fourth = numbers[3:]         # [40, 50, 60, 70, 80]

# 끝에서 몇 개 → 음수 인덱스
last_two = numbers[-2:]           # [70, 80]
except_last = numbers[:-1]        # 마지막 하나만 빼고

# 전체 복사 (얕은 복사)
copy = numbers[:]                 # 원본 그대로 새 리스트

# step 활용
every_other = numbers[::2]        # [10, 30, 50, 70]
reversed_nums = numbers[::-1]     # 뒤집기

슬라이싱은 범위를 벗어나도 에러 없이 조용히 처리한다는 특징도 있어요. numbers[:100]은 IndexError가 아니라 그냥 전체 리스트를 돌려줍니다. 반면 numbers[100]처럼 단일 인덱스로 접근하면 에러가 나요. 이 차이 때문에 방어적 코드를 덜 쓸 수 있습니다.

그리고 슬라이스 대입(slice assignment)도 알아두면 좋습니다. numbers[2:5] = [99]처럼 쓰면 리스트 일부를 다른 길이의 시퀀스로 바꿀 수 있어요. del numbers[2:5]로 일부만 삭제할 수도 있고요.

nums = [1, 2, 3, 4, 5]
nums[1:3] = [20, 30, 40]          # 길이가 달라도 됨
print(nums)                        # [1, 20, 30, 40, 4, 5]

슬라이싱이 새 리스트를 만든다는 건 꼭 기억하세요. 원본을 수정하지 않는 안전한 연산이라는 뜻입니다. 단, 원소가 객체(딕셔너리·리스트 같은 가변 객체)라면 얕은 복사라서 내부 객체는 공유한다는 점만 주의하면 돼요.

📎 기억할 것

• 처음이나 끝을 가리키는 0, len(x)는 생략하세요. x[:3], x[-2:]가 파이썬다운 방식입니다.
• 끝에서부터 셀 땐 음수 인덱스(-1, -2)를 적극 활용하세요.
• 슬라이싱은 새로운 리스트를 반환합니다(얕은 복사). x[:]이 전체 복사 관용구예요.
• 범위를 벗어난 슬라이싱은 에러 없이 처리되지만, 단일 인덱스(x[100])는 IndexError를 냅니다.
• x[a:b] = [...], del x[a:b] 같은 슬라이스 대입·삭제도 강력한 기능입니다.

🛠 실무에서 어디 쓸까

데이터 처리에서 거의 매일 씁니다. 대용량 CSV에서 헤더만 떼어내기(header, *rows = lines 언패킹과 조합), 로그 파일의 최근 N줄만 보기(lines[-100:]), 페이지네이션(items[offset:offset+page_size])이 전형적인 예시예요. 특히 문자열도 시퀀스라서 슬라이싱이 그대로 통합니다. URL에서 쿼리스트링 떼어내기(url[:url.index('?')]), 파일 확장자 제거(name[:-4]) 같은 상황에서 유용하죠.

성능이 중요한 상황에서는 한 가지 주의점이 있어요. 매우 큰 리스트에서 슬라이싱은 새 리스트를 만들기 때문에 메모리와 시간을 씁니다. 이런 경우에는 itertools.islice()나 제너레이터를 고려하는 게 낫습니다. 평범한 상황에서는 신경 쓸 필요 없지만, GB 단위 데이터에서는 체감이 달라집니다.

파이썬에는 C에서 물려받은 이상한 기능이 하나 있습니다. 문자열 리터럴 두 개가 나란히 붙어 있으면 자동으로 하나로 합쳐지는 것. "hello" "world"라고 쓰면 + 없이도 "helloworld"가 됩니다. 얼핏 보면 편리해 보이지만, 이게 리스트 안에서 쉼표 하나를 빼먹는 실수와 만나면 조용한 대참사가 벌어져요.

타입 에러도 없고, 문법 에러도 없고, 그냥 원소 개수가 슬쩍 줄어서 돌아갑니다. 찾기도 힘들어요.

💣 흔한 실수

# 리스트에 쉼표 하나 빼먹었을 뿐인데…
users = [
    "alice",
    "bob",
    "charlie"    # ← 쉼표 빠짐
    "david",
    "eve",
]

print(len(users))  # 4 (5가 아님!)
print(users)       # ['alice', 'bob', 'charliedavid', 'eve'] 😱

"charlie"와 "david" 사이에 쉼표가 없어서 암시적으로 연결됐고, 결국 "charliedavid"라는 이상한 원소가 태어났습니다. 리스트 길이는 5가 아니라 4. 이걸 DB에 넣거나 API에 보내면 charliedavid라는 유령 사용자가 생기는 거예요. 에러도 없이 조용히.

# 여러 줄 문자열을 암시적으로 이어 쓰기
message = (
    "안녕하세요, "
    "오늘 날씨가 "
    "정말 좋네요."
)
# 동작은 함. 하지만 의도가 명확하지 않음 — 한 줄이어야 했나? 실수인가?

이 예는 "합쳐지길 원해서 그렇게 쓴 것"이지만, 보는 사람은 의도인지 실수인지 구분하기 어렵습니다. 코드 리뷰할 때 매번 멈칫하게 만들죠.

✅ 파이썬다운 방법

# 리스트는 끝 원소에도 쉼표를 찍는 습관(trailing comma)
users = [
    "alice",
    "bob",
    "charlie",    # ← 쉼표! 줄 추가/삭제할 때도 diff가 깔끔
    "david",
    "eve",
]


# 긴 문자열을 잇고 싶으면 + 로 명시적으로
message = (
    "안녕하세요, "
    + "오늘 날씨가 "
    + "정말 좋네요."
)


# 여러 조각을 조립한다면 join이 가장 파이썬답고 빠름
parts = ["안녕하세요", "오늘 날씨가", "정말 좋네요"]
message = " ".join(parts)

명시적 + 연산자를 쓰면 "이건 의도적으로 합친 거야"가 드러나고, 리스트에서는 마지막 원소 뒤에도 쉼표를 찍어두는 trailing comma 스타일이 쉼표 실수를 원천 차단합니다. 여기에 더해, 문자열 조각을 여러 개 합칠 일이 있으면 +보다 " ".join()이 훨씬 효율적이에요. +는 매번 새 문자열을 만들지만 join은 한 번에 처리하거든요.

린터(ruff, pylint)들도 이 암시적 연결 패턴을 감지하는 규칙을 제공합니다. ruff의 ISC001, ISC002 같은 규칙을 켜두면 실수가 생기자마자 에디터에 빨간 줄이 뜹니다.

📎 기억할 것

• "foo" "bar"처럼 문자열 리터럴이 나란히 있으면 파이썬이 자동으로 합쳐줍니다(암시적 연결).
• 리스트에서 쉼표 하나를 빼먹으면 두 원소가 조용히 합쳐져서 길이가 줄고 원소 내용도 망가지는 버그가 생깁니다.
• 의도적으로 합치려는 거라면 +를 명시적으로 쓰거나, 조각이 여럿이면 " ".join(parts)를 쓰세요.
• 리스트·딕셔너리의 마지막 원소 뒤에도 쉼표를 찍는 습관(trailing comma)이 이런 실수를 예방합니다.
• ruff 같은 린터가 이 패턴을 잡아주니 규칙을 켜두면 사람 실수를 기계가 막아줍니다.

🛠 실무에서 어디 쓸까

설정 파일이나 상수 목록에서 특히 조심해야 합니다. 허용된 도메인 리스트, 이메일 수신자 리스트, CSV 컬럼 헤더처럼 문자열이 나열된 리스트가 가장 위험해요. 여기서 쉼표 하나 빠지면 "admin@company.com"과 "user@company.com"이 "admin@company.comuser@company.com"이라는 존재하지 않는 주소로 합쳐져서, 메일 발송 코드가 조용히 실패합니다. 에러 로그에도 "주소 형식 오류"라고만 뜨고, 원인을 찾는 데 몇 시간을 쓰게 돼요.

팀 프로젝트에서는 ruff에 ISC 규칙을 활성화하고 trailing comma를 강제하는 포매터(black, ruff format) 설정을 pyproject.toml에 박아두세요. 사람이 주의하는 것보다 도구가 자동으로 잡아주는 게 훨씬 안전합니다.

디버깅하려고 print(some_value)를 찍었는데, 숫자 5와 문자열 "5"가 똑같이 5로 출력돼서 타입 때문에 벌어진 버그를 놓친 경험, 한 번쯤 있으실 거예요. 아니면 내가 만든 클래스를 print했더니 <__main__.User object at 0x7f...> 같은 우주 주소만 나와서 당황했거나요.

이건 파이썬이 객체를 문자열로 바꾸는 두 가지 방식을 가지고 있기 때문입니다. 하나는 str() — 사람이 읽기 좋은 형태, 다른 하나는 repr() — 개발자가 디버깅하기 좋은 형태. 이 둘의 차이를 알면 디버깅 속도가 확 올라가고, 내 클래스도 더 친절하게 만들 수 있습니다.

💣 흔한 실수

# print는 내부적으로 str()을 호출 → 타입 정보가 사라짐
print(5)       # 5
print('5')     # 5 — 어라, 똑같이 나오네?
print([1, '2', 3])  # [1, '2', 3] — 리스트 안에서는 repr이 쓰여서 다행히 구분됨


# 내 클래스를 그냥 print하면 쓸모없는 출력
class User:
    def __init__(self, name, age):
        self.name = name
        self.age = age

u = User("지훈", 30)
print(u)  # <__main__.User object at 0x7f8b1c0e3a90>  😵

숫자 5와 문자열 '5'가 겉보기엔 똑같이 찍혀서 타입 버그의 온상이 됩니다. 내 클래스도 print해봐야 메모리 주소만 보여서 안의 값이 뭔지 알 수가 없어요.

✅ 파이썬다운 방법

디버깅할 때는 repr()을 쓰거나 f-string의 !r 플래그를 활용하세요. 내 클래스에는 __repr__을 직접 정의해주는 게 기본입니다.

# repr은 타입을 구분해준다
print(repr(5))     # 5
print(repr('5'))   # '5' — 따옴표가 붙어서 문자열임이 드러남

# f-string에서 !r 플래그로 간편하게
x = '5'
print(f"{x!r}")    # '5'
print(f"{x=}")     # x='5'  ← !r이 기본 적용됨, 디버깅 최강


# 내 클래스에 __repr__과 __str__ 직접 정의
class User:
    def __init__(self, name, age):
        self.name = name
        self.age = age

    def __repr__(self):
        # 개발자용: 객체를 재구성할 수 있을 정도로 상세하게
        return f"User(name={self.name!r}, age={self.age!r})"

    def __str__(self):
        # 사람용: 읽기 좋게
        return f"{self.name}({self.age}세)"


u = User("지훈", 30)
print(u)          # 지훈(30세)              ← __str__
print(repr(u))    # User(name='지훈', age=30) ← __repr__
print(f"{u!r}")   # User(name='지훈', age=30)
[u]               # [User(name='지훈', age=30)] ← 컨테이너 안에선 항상 __repr__

핵심 규칙 세 가지입니다. 첫째, str()은 사람을 위한 표현, repr()은 개발자를 위한 표현. 둘째, 리스트·딕셔너리 같은 컨테이너는 내부 원소를 출력할 때 항상 repr()을 사용합니다. 그래서 [1, '2', 3]에서 '2'에 따옴표가 붙는 거예요. 셋째, __str__을 따로 정의하지 않으면 print()는 __repr__로 폴백합니다. 그러니 __repr__만 잘 정의해도 절반은 성공이에요.

한 가지 관례가 있는데, __repr__이 반환하는 문자열은 그 값을 다시 만들 수 있는 파이썬 식처럼 쓰는 게 이상적입니다. User(name='지훈', age=30)처럼요. 가능하면 eval()해서 원본이 복원될 정도로 상세하게.

📎 기억할 것

• str()은 사람이 읽기 위한 것, repr()은 개발자가 디버깅하기 위한 것입니다.
• print()는 기본적으로 str()을 호출하지만, 리스트·딕셔너리 내부 원소는 repr()로 출력됩니다.
• f-string에서 !r을 붙이면 repr 형태로, f"{x=}"는 변수명+repr 자동 출력이라 디버깅에 최고입니다.
• 내 클래스를 만들 때는 __repr__은 거의 필수, __str__은 사용자에게 직접 노출할 때만 추가로 정의하세요.
• __repr__은 이상적으로 "그 값을 재구성할 수 있는 파이썬 식"처럼 생겨야 합니다.

🛠 실무에서 어디 쓸까

도메인 클래스를 만들 때마다 __repr__을 정의해두는 습관이 생산성에 큰 차이를 만듭니다. 예를 들어 주문, 결제, 사용자 같은 핵심 엔티티에 __repr__이 없으면 print(order) 한 줄로 디버깅하려 할 때마다 객체 내부를 까봐야 해요. 반대로 __repr__을 잘 정의해두면 logger.debug(f"처리 중: {order!r}") 같은 로그 한 줄이 진짜 쓸 만한 정보가 됩니다.

참고로 dataclasses.dataclass나 Pydantic 모델, SQLAlchemy의 일부 설정은 __repr__을 자동으로 생성해줍니다. 그래서 요즘 실무에서는 @dataclass로 만들고 거기서 나오는 기본 __repr__에 만족하다가, 필요할 때만 오버라이드하는 패턴이 흔해요. 커스텀할 때는 민감 정보(비밀번호, API 키 등)를 __repr__에 노출하지 않도록만 주의하면 됩니다.

파이썬에는 문자열에 변수를 끼워 넣는 방법이 4가지나 있습니다. % 연산자(C 스타일), str.format(), f-string, 그리고 최근에 추가된 t-string까지. 옛날 코드베이스에서는 %s, %d를 자주 볼 수 있고, 중간 세대 코드에서는 "{name}".format(name=...)이 흔해요. 문제는 앞의 두 방식이 읽기도 어렵고, 수정하기도 번거롭고, 버그도 만들기 쉽다는 겁니다.

Python 3.6부터 들어온 f-string은 사실상 이 모든 문제를 한 방에 정리한 문법이에요. 이제 새로 작성하는 코드에서 %나 .format()을 쓸 이유는 거의 없습니다.

💣 흔한 실수

name = "지훈"
age = 30
city = "서울"

# ① C 스타일 — 순서 맞추기 고역, 값 바뀌면 다시 맞춰야 함
msg = "%s(%d세)은 %s에 삽니다" % (name, age, city)

# 값 하나 더 넣고 싶을 때 튜플 순서 다 맞춰야 함
msg = "%s(%d세, %s 거주)님 환영합니다. %s님!" % (name, age, city, name)  # name 두 번 중복

# ② 딕셔너리로 풀면 덜 아프지만 번잡함
msg = "%(name)s은 %(age)d세입니다" % {"name": name, "age": age}

# ③ str.format — 좀 낫지만 여전히 두 번 쓰는 느낌
msg = "{name}은 {age}세입니다".format(name=name, age=age)

% 방식은 좌우 순서·개수·타입이 모두 일치해야 하고, 값 하나만 살짝 바꾸려 해도 튜플 전체를 다시 조립해야 합니다. 같은 값을 여러 번 쓰면 튜플에 중복으로 넣어야 하고요. str.format은 키워드 인자로 가독성이 좀 나아지지만, 변수명을 두 번 쓰는 중복({name}과 name=name)이 여전히 거슬립니다.

✅ 파이썬다운 방법

name = "지훈"
age = 30
city = "서울"

# f-string: 변수 이름을 그대로 문자열 안에 쓴다
msg = f"{name}({age}세)은 {city}에 삽니다"

# 식(expression)도 그대로 들어간다
msg = f"{name}님은 내년에 {age + 1}세가 됩니다"

# 포매팅 스펙도 동일하게 지원
pi = 3.141592
msg = f"파이는 {pi:.2f}입니다"              # 3.14
msg = f"가격: {1234567:,}원"                 # 1,234,567원
msg = f"{0.85:.1%}"                          # 85.0%

# 디버깅용 = 표기 (Python 3.8+) — 변수명과 값을 한꺼번에
x, y = 10, 20
print(f"{x=}, {y=}")                         # x=10, y=20

f-string의 핵심은 변수 이름을 문자열 안에 바로 쓴다는 점입니다. 중복이 사라지고, {age + 1}처럼 식도 그대로 평가돼요. :.2f, :,, :% 같은 포매팅 스펙도 기존 방식과 똑같이 쓸 수 있어서 손해 보는 것도 없습니다.

디버깅할 때 유용한 f"{x=}" 표기법도 꼭 기억하세요. print(f"{user=}") 한 줄이면 user=<User object>처럼 변수명과 값을 같이 찍어주니까, 찍어볼 변수가 많을 때 엄청 편합니다.

📎 기억할 것

• % 스타일, str.format(), f-string 중에서 새 코드는 무조건 f-string이 정답입니다.
• f-string 안에는 변수뿐 아니라 임의의 파이썬 식을 넣을 수 있습니다({a + b}, {user.name.upper()}).
• 기존 포매팅 스펙(:.2f, :,, :>10, :% 등)이 f-string에서도 그대로 동작합니다.
• f"{x=}" 형태는 디버깅 로그 찍을 때 특히 유용합니다(Python 3.8+).
• 중괄호를 문자 그대로 쓰려면 {{, }}로 이스케이프하세요.

🛠 실무에서 어디 쓸까

사실상 모든 곳입니다. 로깅 메시지, 사용자에게 보여줄 에러 메시지, SQL 쿼리 생성(단, 사용자 입력으로 쿼리 만들 땐 f-string 대신 파라미터 바인딩 쓰세요 — SQL 인젝션 위험), API 응답 포매팅, CLI 출력 등. 특히 데이터 분석 리포트나 Slack 알림봇 만들 때 f"오늘 신규 가입 {new_users:,}명 (전일 대비 {growth:+.1%})" 같은 한 줄이면 깔끔한 출력이 완성됩니다.

한 가지 유의점은 로깅 라이브러리에서는 f-string이 항상 최선은 아니라는 점이에요. logger.info(f"user={user.name}")보다 logger.info("user=%s", user.name) 쪽이 로그 레벨에 따라 문자열 포매팅 자체를 건너뛸 수 있어 성능상 유리합니다. 고빈도 로그에서만 신경 쓰면 되고, 평범한 애플리케이션에서는 f-string이 가독성 면에서 압도적이니 편하게 쓰세요.

파일에서 데이터를 읽다가 TypeError: a bytes-like object is required, not 'str' 에러를 만난 적 있나요? 아니면 HTTP 응답을 파싱하는데 b'...' 형태로 나와서 .replace()가 먹히지 않아 당황했던 적은요? 파이썬의 bytes와 str은 겉보기엔 비슷하지만 완전히 다른 타입이고, 이 차이를 모르면 한글 깨짐, 파일 읽기 오류, 네트워크 통신 버그로 끝없이 시달리게 됩니다.

핵심 차이는 간단합니다. bytes는 0~255 정수의 나열(raw 바이트)이고, str은 사람이 읽는 문자(유니코드 코드 포인트)의 나열입니다. 디스크나 네트워크는 바이트만 알고, 사람은 글자로 보고 싶어 하죠. 이 둘 사이의 변환이 인코딩/디코딩입니다.

💣 흔한 실수

# 파일을 바이너리로 열고 문자열처럼 다루기
with open('log.txt', 'rb') as f:
    data = f.read()
    if 'error' in data:  # 💥 TypeError: a bytes-like object is required
        print("에러 발견")


# bytes와 str을 그냥 합치려 하기
greeting = b'hello, '
name = '세계'
print(greeting + name)  # 💥 TypeError


# 한글을 인코딩 안 하고 바이트 취급
data = '안녕'
with open('out.bin', 'wb') as f:
    f.write(data)  # 💥 TypeError: a bytes-like object is required

'rb'로 연 파일은 bytes를 반환하는데 'error'(문자열)로 검색하려니 타입이 안 맞습니다. bytes와 str은 더하기도, 비교도, 포함 검사도 안 돼요. 파이썬이 "비슷하니까 알아서 해주겠지"를 거부하는 몇 안 되는 영역입니다.

✅ 파이썬다운 방법

"유니코드 샌드위치" 패턴이 정답입니다. 입구에서 바로 str로 디코딩, 내부에선 str로만 처리, 나갈 때 다시 bytes로 인코딩하는 구조예요.

# 입구: 바이트를 문자열로 디코딩
with open('log.txt', 'rb') as f:
    raw = f.read()                  # bytes
    text = raw.decode('utf-8')      # str

# 내부: str로만 처리
if 'error' in text:
    print("에러 발견")

# 출구: 다시 바이트로 인코딩
with open('out.bin', 'wb') as f:
    f.write('안녕'.encode('utf-8'))  # str → bytes


# 타입이 헷갈릴 때 쓸 수 있는 도우미 함수
def to_str(value) -> str:
    if isinstance(value, bytes):
        return value.decode('utf-8')
    return value  # 이미 str

def to_bytes(value) -> bytes:
    if isinstance(value, str):
        return value.encode('utf-8')
    return value  # 이미 bytes

변환의 핵심은 인코딩 이름을 명시하는 것입니다. UTF-8이 사실상의 표준이지만, 레거시 시스템에서는 cp949, euc-kr, latin-1 같은 걸 만날 수도 있어요. 디코딩할 때 인코딩이 다르면 UnicodeDecodeError가 나거나, 최악의 경우 조용히 글자가 깨집니다.

파일을 텍스트 모드('r', 'w')로 열면 파이썬이 자동으로 인코딩/디코딩을 해주니까, 한글 텍스트 파일 다룰 땐 그냥 open('file.txt', 'r', encoding='utf-8')을 쓰는 게 마음 편합니다. 바이너리 모드('rb', 'wb')는 이미지/오디오/네트워크 패킷처럼 진짜 바이트 단위가 필요할 때만 쓰세요.

📎 기억할 것

• bytes는 0~255 정수의 시퀀스(raw 데이터), str은 유니코드 문자의 시퀀스입니다.
• bytes + str, bytes == str, 'x' in bytes_value 같은 혼용은 전부 에러입니다.
• bytes.decode('utf-8')으로 문자열화, str.encode('utf-8')으로 바이트화합니다.
• 유니코드 샌드위치: 입력받자마자 str로 디코딩, 처리는 str로, 출력 직전에 bytes로 인코딩.
• 파일은 기본적으로 텍스트 모드('r', 'w')로 열고 encoding='utf-8'을 명시하세요. 바이너리 모드는 진짜 바이트 단위가 필요할 때만.

🛠 실무에서 어디 쓸까

웹 서버/클라이언트가 대표적입니다. requests.get(url).content는 bytes를, .text는 자동 디코딩된 str을 반환해요. 한글 페이지 크롤링할 때 .text가 깨지면 대부분 인코딩을 잘못 추측한 경우라, response.encoding = 'utf-8'로 지정하거나 .content.decode('euc-kr')로 직접 풀어줘야 합니다. 또 AWS S3, Redis, 카프카 같은 서비스의 파이썬 클라이언트는 대부분 bytes를 주고받기 때문에, 애플리케이션 경계에서 반드시 인코딩/디코딩을 거쳐야 해요. 암호화(hashlib, hmac), 해시(sha256), JWT 서명 같은 보안 관련 API도 bytes를 요구하는 경우가 많아서, "비밀번호".encode('utf-8')을 습관적으로 붙이는 게 실수를 줄입니다.