SQL Query Engine: 자연어에서 PostgreSQL 로의 자동 번역을 위한 자기 치유형 LLM 파이프라인 기술 보고서 요약

이 기술 보고서는 SQL Query Engine이라는 오픈소스 자체 호스팅 서비스를 소개합니다. 이 시스템은 대규모 언어 모델 (LLM) 을 기반으로 한 2 단계 파이프라인을 통해 자연어 질문을 검증된 PostgreSQL 쿼리로 변환하며, 실행 오류 발생 시 자동으로 수정하는 자기 치유 (Self-Healing) 메커니즘을 핵심으로 합니다.

1. 문제 정의 (Problem)

자연어에서 SQL 로의 변환 (Text-to-SQL) 은 오랫동안 연구되어 왔으나, 실제 생산 환경에서는 다음과 같은 한계가 존재합니다.

• 복잡하고 동적인 스키마: 실제 데이터베이스는 크기가 크고 문서화가 부족하며 끊임없이 변화합니다.
• 단일 패스 (Single-pass) 접근법의 실패: 기존 시스템은 LLM 이 생성한 쿼리가 실행 오류 (잘못된 컬럼명, 타입 캐스팅 오류, 과도한 필터 등) 를 일으키면 사용자에게 원시 오류를 반환하거나 단순히 포기하는 경우가 많습니다.
• 회복 불가능성: 많은 실패 사례는 적절한 진단 정보 (PostgreSQL 의 SQLSTATE 코드 및 디버깅 메시지) 를 제공하면 LLM 이 스스로 수정할 수 있음에도 불구하고, 이를 활용하지 못해 발생합니다.

2. 방법론 (Methodology)

SQL Query Engine 은 실행 기반의 자기 치유 루프를 도입하여 위 문제를 해결합니다. 시스템은 크게 두 단계로 구성되며, Redis 를 활용한 세션 관리와 실시간 스트리밍을 지원합니다.

2.1 2 단계 파이프라인

1. 1 단계: 스키마 탐색 및 SQL 생성 (QueryGenerator)

   • PostgreSQL 의 information_schema 를 동적으로 탐색하여 테이블, 컬럼, 관계, JSONB 구조 등을 마크다운 형식으로 추출합니다.
   • 이 스키마 정보를 LLM 에게 전달하여 자연어 질문을 SQL 쿼리로 변환합니다.
   • 다중 전략 응답 파서 (Multi-strategy Response Parser): LLM 의 출력 형식 (JSON, 코드 블록, 원시 텍스트 등) 에 상관없이 SQL 을 추출합니다. 구조화된 출력 API 나 함수 호출을 요구하지 않아 모든 LLM 과 호환됩니다.
   • 생성된 스키마 설명과 대화 이력을 Redis에 캐싱하여 동일 세션 내의 후속 요청 시 불필요한 스키마 탐색과 LLM 호출을 생략합니다.

2. 2 단계: 실행 및 자기 치유 (QueryEvaluator)

   • 생성된 쿼리를 실제 PostgreSQL 인스턴스 (읽기 전용) 에서 실행합니다.
   • 자기 치유 루프: 쿼리가 실패하거나 결과가 비어있으면, PostgreSQL 이 반환한 SQLSTATE 코드, 진단 메시지, 힌트, Python 트레이스백 등을 포함하여 LLM 에게 피드백합니다. LLM 은 이 정보를 바탕으로 쿼리를 수정하고 다시 실행합니다.
   • 안전 장치 (Safety Mechanisms):
     • Early-Accept (조기 수용): 쿼리가 오류 없이 실행되어 결과가 반환되면 즉시 성공으로 간주하고 LLM 재평가 없이 반환합니다. 이는 "올바른 쿼리를 LLM 이 실수로 고쳐서 틀리게 만드는" 회귀 (Regression) 를 방지합니다.
     • Best-Result Tracking: 재시도 횟수가 소진되더라도, 그동안 발견된 가장 좋은 부분적 결과를 반환하여 완전히 실패하는 것을 방지합니다.
     • LLM 자기 평가 무시: LLM 이 "쿼리가 유효하다"고 스스로 판단하는 필드는 무시하고, 오직 실제 실행 결과 (오류 없음 + 결과 존재) 만을 성공 기준으로 삼습니다.

2.2 아키텍처 및 인터페이스

• LLM 중립성: OpenAI 호환 엔드포인트 (Ollama, vLLM, OpenAI 등) 와 통신하므로 로컬 모델과 클라우드 API 간 전환이 코드 수정 없이 가능합니다.
• 듀얼 API: 네이티브 REST API 와 OpenAI 호환 /v1/chat/completions 엔드포인트를 모두 제공하여 Open WebUI 나 Python SDK 와 같은 기존 도구들과 즉시 연동 가능합니다.
• 실시간 스트리밍: Redis Pub/Sub 과 Server-Sent Events (SSE) 를 통해 쿼리 생성, 진단, 수정 과정의 진행 상황을 실시간으로 클라이언트에 전달합니다.
• 보안: 드라이버 레벨에서 PostgreSQL 연결을 **읽기 전용 (Read-only)**으로 강제하여 데이터 손실이나 변조를 원천 차단합니다.

3. 주요 기여 (Key Contributions)

1. 실행 기반 자기 치유 루프: PostgreSQL 의 상세한 진단 정보를 활용하여 LLM 이 오류를 스스로 수정하도록 유도하는 반복적 프로세스를 구현했습니다.
2. 회귀 방지 메커니즘: 'Early-Accept'와 'Best-Result Tracking'을 통해 자기 치유 과정에서 오히려 정확도가 떨어지는 현상을 방지했습니다.
3. 범용 응답 파서: 구조화된 출력 API 없이도 다양한 LLM 출력 형식에서 SQL 을 안정적으로 추출하는 5 단계 파싱 전략을 제시했습니다.
4. 실시간 가시성: 쿼리 수정 과정을 실시간으로 스트리밍하여 사용자와 개발자가 디버깅 과정을 투명하게 관찰할 수 있게 했습니다.
5. 오픈소스 및 배포 용이성: Docker Compose 를 통한 단일 명령어 배포와 Python 모듈 직접 임포트 기능을 제공합니다.

4. 실험 결과 (Results)

보고서는 합성 벤치마크와 실제 세계 벤치마크인 BIRD를 통해 시스템을 평가했습니다.

4.1 합성 벤치마크 (Synthetic Benchmark)

• 3 개의 목적별 PostgreSQL 데이터베이스와 75 개의 질문으로 구성되었습니다.
• 성능 향상: 자기 치유 루프를 적용한 결과, 모델에 따라 정확도가 최대 +9.3% (Llama 4 Scout 17B 기준, 48.0% → 57.3%) 향상되었습니다.
• 회귀 방지: 최상위 모델 (Llama 4 Scout, GPT-OSS-20B) 은 0 건의 회귀를 기록하며, 초기에 성공한 쿼리가 치유 과정에서 망가뜨려지지 않음을 입증했습니다.
• 모델 크기 vs 성능: 17B 파라미터의 Llama 4 Scout 가 120B 파라미터 모델보다 더 높은 정확도를 보이며, 모델 크기보다는 오류 진단을 활용한 자기 수정 능력이 중요함을 시사했습니다.

4.2 BIRD 벤치마크 (실제 세계 데이터)

• 11 개의 실제 도메인 데이터베이스 (SQLite → PostgreSQL 마이그레이션) 와 437 개의 질문으로 평가되었습니다.
• 성능 향상: GPT-OSS-120B 모델을 기준으로 자기 치유를 통해 정확도가 **44.4% 에서 49.0%**로 +4.6% 향상되었습니다.
• 비교: 기존 ChatGPT (39.3%) 나 Claude 2 (42.7%) 보다 높은 실행 정확도를 달성했습니다. (CHASE-SQL 등 파인튜닝 기반 시스템보다는 낮으나, 일반 목적 LLM 만으로 달성한 성과입니다.)
• 한계: 실제 데이터에서는 빈 결과 집합 (Empty Result) 이 정답인 경우가 많아, 자기 치유 루프가 불필요하게 발동되어 회귀가 발생할 확률이 합성 벤치마크보다 높았습니다.

4.3 지연 시간 (Latency)

• 자기 치유 과정은 추가적인 LLM 호출로 인해 지연 시간을 증가시킵니다. 합성 데이터 기준 평균 1.67 초에서 4.19 초로 약 2.5 배 증가했으나, 정확도 향상과 트레이드오프 관계가 명확했습니다.

5. 의의 및 결론 (Significance & Conclusion)

SQL Query Engine 은 Text-to-SQL 기술이 실험실 단계를 넘어 실제 생산 환경에서 신뢰할 수 있게 작동하기 위한 핵심 과제를 해결했습니다.

• 실용성: 단순한 정확도 향상을 넘어, 오류 발생 시 시스템이 스스로 복구하는 **내결함성 (Fault Tolerance)**을 제공하여 실제 비즈니스 환경에서의 적용 가능성을 높였습니다.
• 안전성: 읽기 전용 강제 및 회귀 방지 메커니즘을 통해 LLM 이 생성한 쿼리를 안전하게 실행할 수 있는 환경을 조성했습니다.
• 접근성: 오픈소스 제공과 다양한 LLM 백엔드 지원, 기존 도구와의 호환성을 통해 누구나 쉽게 도입하고 확장할 수 있는 기반을 마련했습니다.

이 시스템은 LLM 이 단순히 코드를 생성하는 것을 넘어, 실행 피드백을 통해 지속적으로 학습하고 수정하는 자기 치유형 에이전트로서의 가능성을 보여주었으며, 향후 다른 SQL dialect 지원 및 자동 스키마 변경 감지 등으로 확장될 수 있음을 시사합니다.