Skip to content

feat: Qdrant로 질문에 관련된 테이블 검색 (#204) - #265

Open
seyoung4503 wants to merge 2 commits into
masterfrom
feat/qdrant-schema-search
Open

seyoung4503 wants to merge 2 commits into
masterfrom
feat/qdrant-schema-search

Conversation

@seyoung4503

@seyoung4503 seyoung4503 commented Nov 22, 2026 •

Copy link
Copy Markdown
Collaborator

#️⃣ Issue Number

관련 이슈 #204 · 스키마 탐색 평가 #263

📝 요약

  • 운영자가 lang2sql-tools … index-schema를 실행하면 현재 DB의 테이블·컬럼명·타입·설명을 임베딩하고, 조직·연결·임베딩 설정별 Qdrant 별칭을 새 색인으로 교체합니다. 스키마가 비어 있는 경우에도 이전 테이블을 제거합니다.
  • 내장 에이전트와 직접 도구 CLI·MCP에서 search_schema(query)로 최대 5개의 테이블 후보를 조회합니다. 에이전트는 explore_schema(table)로 실제 컬럼을 확인합니다. 검색을 설정하지 않은 환경은 기존 도구와 스키마 프롬프트를 사용합니다.
  • 로컬 Compose와 OpenAI 호환 임베딩 API 설정을 추가했습니다. 실행 예시는 사용 가이드에 있습니다. 용어·예제 SQL 검색과 UI 갱신은 후속 범위입니다.

💬 To Reviewers

실패한 색인 갱신이 기존 검색 결과를 덮지 않도록 별도 컬렉션을 완성한 뒤 게시합니다. 별칭 교체 중 연결이 끊기면 활성 색인은 온전히 유지되며, 운영자가 고아 컬렉션을 정리해야 할 수 있습니다. 자격 증명·임베딩 모델·연결 설정을 변경하면 새 범위로 다시 색인해야 합니다.

PR Checklist

  • 전체 테스트 175개, 변경 Python 파일 Black 검사, 신규 모듈 mypy, lock 및 diff 검사 통과.
  • 변경 Python 파일 Ruff 검사 통과. 기존 system_prompt.py의 광범위 예외 처리(BLE001) 한 곳은 기존 코드와 동일해 검사에서 제외.
  • 실제 Qdrant v1.18.3 + 로컬 Ollama BGE-M3에서 CLI 색인·한국어 검색·조직 격리·삭제 테이블 및 빈 DB 갱신 확인.
  • Qdrant Compose 구성 및 운영 가이드 추가.

Spider2 SQLite 10문항 비교

#263에서 고정한 기존 오답 10개에 대해 두 OpenAI 스냅샷을 검색 설정별로 한 번씩 재실행했습니다. 각 실행은 문항당 16회 모델 호출, 동일한 스키마 탐색 지시와 읽기 전용 최종 SQL 검증·수정 기회를 사용했습니다. 활성 조건에서는 테이블 전체 목록을 미리 주입하지 않고 검색 도구와 사용 지시를 제공합니다. 아래 수치는 공식 채점 결과이며, 모델 호출 수에는 로컬 임베딩 요청이 포함되지 않습니다.

모델 검색 설정 공식 정답 / 10 실행 결과 생성 / 10 search_schema explore_schema 모델 호출
GPT-4.1 mini 끔 4 10 0 30 40
GPT-4.1 mini 켬 3 7 4 50 60
GPT-4.1 끔 2 8 0 40 47
GPT-4.1 켬 3 8 11 44 74

10문항 ID는 local019, local026, local034, local073, local098, local133, local170, local273, local301, local310입니다. 검색 활성 조건에서 mini는 local019·310·133을, GPT-4.1은 local310·026·133을 맞혔습니다. 중간 실험에서 전체 목록을 계속 보여주고 도구만 추가하거나 사용 지시도 추가한 경우 두 모델 모두 검색을 호출하지 않았습니다. 최종 설정에서는 두 모델 모두 검색했지만 합산 정답은 6/20으로 같고 모델 호출은 87회에서 134회로 증가했습니다. 모델당 단일 실행이며 같은 표본을 설계 점검에도 사용했습니다.

이 표본에서 upstream 정답 SQL이 있는 local019와 local301은 질문 원문으로 상위 5개를 직접 검색해 사용 테이블을 대조했습니다. 각각 5/7, 1/1을 찾았습니다. local019에서는 Locations와 Promotions가 후보에서 빠졌습니다. 이 결과는 아직 검색 설정을 기본 활성화하거나 전체 벤치마크에서 성능이 개선됐다고 판단할 근거가 되지 않습니다.

구현 원칙 확인

항목 판정 근거
1 재사용 O ExplorerPort, ToolRegistry, ContextConcierge, CLI·MCP 런타임 및 기존 Compose 서비스 구성 재사용. 테스트·문서 포함 순증 466줄
2 범위 O 스키마 색인·조회 및 검증에 한정
3 로깅 O 색인 시작·게시·실패와 검색 건수 기록
4 오류 처리 O 게시 전 실패 시 기존 별칭 보존, 정리 실패 경고
5 환경 설정 O 조립 시 서비스와 자격 증명 주입
6 주석 O 코드 주석에 이슈 번호 없음
7 검증 O 전체 175 tests, Python 3.10·3.13 CI 통과. 저장소에 CODE MAP 생성기 없음
8 승인 O 기능 브랜치와 PR
9 호출 흐름 O 운영자 색인 → 질문 검색 → 실제 스키마 확인 문서화
10 비동기 O 색인과 검색은 async HTTP, DB 탐색은 기존 어댑터 사용
11 설정·배포 O 서버·모델·키 5개 환경 설정과 Compose, 사용 예시 반영

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant