Glancer — 자연어로 Rails 데이터베이스와 대화하기

RAG와 LLM을 사용하여 코드를 작성할 필요 없이 자연어로 데이터베이스를 조회할 수 있게 해주는 Rails 엔진입니다.

모든 Rails 프로젝트는 팀원 중 누군가(제품, 지원, 관리 등)가 데이터가 필요하지만, 아무도 그 요구사항을 이해하고 쿼리(Query)를 작성하기 위해 시간을 낼 여유가 없는 지점에 도달합니다. Slack 메시지, 열려 있는 카드, 백로그 속으로 사라지는 CSV 요청 등. 누구나 한 번쯤 겪어본 일입니다.

이것이 바로 제가 Glancer를 생각하게 된 계기였습니다.

무엇인가

Glancer는 애플리케이션 내의 /glancer 경로에 채팅 인터페이스를 구축하는 Ruby on Rails 엔진입니다. 자연어로 질문을 입력하면, 시스템에서 관련 컨텍스트(Context)를 검색하고, SELECT 문(또는 ActiveRecord 표현식)을 생성하며, 이를 검증 및 안전하게 실행한 후 결과를 반환합니다.

"최근 30일 동안 생성된 주문 수는 얼마이며, 상태별로 그룹화해줘?"
→ SELECT 실행됨, 결과 표시됨, 포르투갈어로 답변 작성됨.

직접적인 영감은 제가 많이 사용해 본 gem인 Blazer에서 얻었습니다. 여기서의 아이디어는 한 단계 더 나아가는 것입니다. SQL을 작성하는 대신, 그저 질문만 하면 됩니다.

시작하는 방법

Gemfile에 다음을 추가하세요:

gem "glancer"

제너레이터(Generator)를 실행하세요:

rails generate glancer:install
rails db:migrate
rails glancer:index:all

/glancer에 접속하여 질문을 시작하세요.

제너레이터는 LLM 프로바이더(Provider)를 설정할 수 있는 이니셜라이저(Initializer)를 생성합니다. Gemini를 사용한 최소 설정 예시는 다음과 같습니다:

Glancer.configure do |config|
  config.llm_provider   = :gemini
  config.llm_model      = "gemini-2.0-flash"
...

OpenAI와 OpenRouter도 지원됩니다. 이 엔진은 RubyLLM 위에서 작동하므로, RubyLLM이 지원하는 모델이라면 Glancer도 지원합니다. 역할에 따라 다른 모델을 사용할 수 있습니다. 예를 들어, 쿼리 생성에는 더 유능한 모델을 사용하고, 답변 작성에는 더 저렴한 모델을 사용하는 식입니다.

주요 기능

알아두면 좋은 몇 가지 사항은 다음과:

기본 보안 (Segurança por padrão): 모든 쿼리는 항상 롤백 (rollback)되는 트랜잭션 (transaction) 내에서 실행됩니다. 단어 블랙리스트 (blocklist)가 실행기에 도달하기 전에 DELETE, UPDATE, INSERT, DROP 및 유사한 명령어를 거부합니다. 또한 읽기 복제본 (read replica)을 가리키도록 설정할 수도 있습니다.

추가 인프라 불필요: 임베딩 (embeddings)은 기존 데이터베이스의 JSON 컬럼에 저장됩니다. Pinecone, Weaviate 또는 별도로 구축해야 할 추가적인 요소가 전혀 없습니다. 데이터 양이 아주 많아지는 경우는 드물기 때문에 이러한 접근 방식을 채택했습니다.

비즈니스 컨텍스트 학습: config/glancer/llm_context.glancer.md 파일에 Markdown 파일을 배치하여 도메인 규칙을 설명할 수 있습니다. 예를 들어 status 값의 의미, 매출 계산 방식, 무시해야 할 컬럼/테이블/모델 등을 정의합니다:

- `orders.status`: "pending" | "paid" | "shipped" | "refunded"
- 월 매출 = SUM(orders.total) WHERE status = "paid"
- "churn"에 관한 질문은 `subscriptions` 테이블의 `churned_at` 컬럼을 사용함

더 동적인 추가 정보는 설정의 텍스트 필드에 추가할 수 있습니다. 다만, 이는 기본 모델 (base model)의 컨텍스트 (context)로 사용되므로 임베딩 (embedding)이 생성되지는 않습니다.

인터페이스의 멋진 디테일들: 결과는 테이블 형태로 나타나며 클릭 한 번으로 CSV 내보내기가 가능합니다. 의미가 있는 경우 그래프가 자동으로 생성됩니다. 실행 프로세스는 애플리케이션의 메인 스레드 (main thread)를 차단하지 않도록 설계되었습니다. @테이블_이름을 입력하여 특정 테이블을 고정함으로써 질문을 더 정확하게 할 수 있고, 생성된 SQL을 편집하여 재실행하거나, 마이크로 질문을 말할 수도 있습니다. 또한 /glancer/db-schema에서 스키마 (schema) 뷰어를 제공합니다.

Blazer와의 통합: 이미 Blazer를 사용 중이라면, Glancer에서 생성된 SQL을 Blazer에서 바로 열 수 있는 버튼을 보여줍니다.

그 뒤에 숨겨진 이야기

저는 이것을 개인적인 학습 프로젝트로 시작했습니다. 지난 한 해 동안 RAG (Retrieval-Augmented Generation)와 LLM (Large Language Models)에 대해 많이 공부했고, 아이디어가 떠올랐을 때 저는 이전에 gem을 한 번도 배포해 본 적이 없었기에 engine부터 gemspec, CI (Continuous Integration)에 이르기까지 전체 프로세스를 경험해 보고 싶었습니다. 이를 통해 유익한 학습과 즐거운 경험을 동시에 얻을 수 있었습니다. 몇몇 동료들에게 보여주었을 때 그들이 유용하다고 생각했기에, 커뮤니티에 공개하기로 결정했습니다.

현재 버전은 1.0.0입니다.

직접 테스트해 보신다면, 코드나 아이디어에 대해 어떻게 생각하시는지 정말 알고 싶습니다. Issue와 Pull Request는 언제든 환영합니다.

프로젝트가 마음에 드신다면, 저장소(repository)에 Star를 눌러주시는 것이 더 많은 커뮤니티 사람들에게 알리는 데 큰 도움이 됩니다.

GitHub: https://github.com/ErnaneJ/glancer
RubyGems: https://rubygems.org/gems/glancer