CricketStats: Qwen AI와 MongoDB를 활용하여 일상 언어로 크리켓 역사를 질문하기

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle.

제가 만든 것 (What I Built)

크리켓 질문은 속임수처럼 어렵습니다.

“가바스카르(Gavaskar)를 가장 많이 아웃시킨 사람은 누구인가?”라는 질문은 단순한 조회 이상의 것을 요구합니다. 시스템은 가바스카르가 아웃된 배터임을 이해하고, 일반 이름을 SM Gavaskar로 해결하며, 이닝 단위의 아웃 데이터를 선택하고, 볼러별로 그룹화하여 검증 가능한 증거를 반환해야 합니다. 기술적으로는 유효한 쿼리라도 크리켓에 대해서는 완전히 틀릴 수 있습니다.

저는 일상 언어로 크리켓 질문을 할 수 있는 로컬 AI 연구 비서인 CricketStats를 만들었습니다. 오픈 웨이트(open-weight) 모델인 Qwen 2.5 Coder 14B가 질문을 MongoDB 집계 계획(aggregation plan)으로 변환하고, 애플리케이션이 그 계획을 검증하며, 통계적 결과는 모델이 아닌 MongoDB가 생성합니다.

해커톤 버전에는 다음 내용들이 포함되어 있습니다:

7개의 데이터 컬렉션과 2,861,363개의 문서를 가진 일반 크리켓 데이터베이스;
17개의 데이터 컬렉션과 416,416개의 문서를 가진 IPL(Indian Premier League) 데이터베이스;
총 3,277,779개의 마이그레이션된 문서;
경기(match), 이닝(innings), 선수(player), 경력(career), 상대 팀(opposition), 경기 장소(venue), 아웃 유형(dismissal), 필딩 통계;
295,732개의 IPL 볼별 투구 기록(ball-by-ball delivery records);
Orange Cap 및 Purple Cap 우승자, 햇 트릭(hat tricks), 팀 시즌을 위한 IPL 전용 컬렉션;
일반 크리켓과 IPL 모두를 위한 자연어 비서(natural-language assistants);
테스트/IPL 선택, 추천 질문, 사람이 읽기 쉬운 답변, 선택적 집계 세부 정보를 제공하는 브라우저 인터페이스;
재개 가능한 마이그레이션(resumable migration), 복합 인덱스(compound indexes), 소스 메타데이터, 및 카운트 검증 기능;
질문, 모델 프롬프트, 생성된 계획, 검증된 파이프라인, 결과에 대한 JSONL 추적.

누가 비용을 지불할까요? (Who would pay for it?)

대상 사용자는 크리켓 작가, 팟캐스터, 해설자, 판타지 크리켓 분석가, 그리고 진지한 팬 커뮤니티입니다. 이들의 현재 작업 흐름은 종종 반복적인 웹 검색, 스코어카드 수동 확인, 또는 일회성 스프레드시트 공식 작성으로 이루어져 있습니다.

부업(side-hustle) 제안은 두 가지 가능한 형태를 가지고 있습니다:

자체 서비스 크리켓 연구 어시스턴트를 원하는 사람들을 위한 개인 설치 및 데이터셋 설정; 그리고
경기 프리뷰, 기사, 방송, 팟캐스트, 소셜 게시물 등을 위한 맞춤형의 근거 기반 통계 보고서.

이 제품은 단순히 "크리켓을 안다"고 주장하는 또 다른 챗봇이 아닙니다. 이 제품의 가치는 검토 가능한 생성된 MongoDB 집계(aggregation)를 통해 더 빠른 연구가 가능하며, 데이터베이스 자체가 사실적 진실의 원천(factual source of truth) 역할을 한다는 점입니다.

이는 제품-시장 적합성(product-market fit)에 대한 주장이 아니라 비즈니스 가설입니다. 저는 아직 유료 고객이나 검증된 지불 의사를 가지고 있지 않습니다. 현재 제공 가능한 결과물은 작동하는 로컬 프로토타입과 전문 사용자들이 설치, 데이터 준비, 지원 또는 위탁 보고서에 대해 비용을 지불할지 테스트할 수 있는 구체적인 방법입니다.

데모 (Demo)

비디오 데모: CricketStats MongoDB 데모 보기

이 데모는 실제 로컬 애플리케이션, Ollama를 통한 Qwen, 그리고 마이그레이션된 MongoDB 데이터베이스를 사용합니다. 브라우저 워크플로우를 보여주며, Test 데이터와 IPL 데이터를 전환하고, 자연어 질문을 던지며, 각 답변 뒤에 숨겨진 집계 파이프라인(aggregation pipeline)을 노출합니다.

로컬에서 애플리케이션 실행 방법:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
...

그런 다음 http://127.0.0.1:8765를 엽니다.

MongoDB Community는 로컬에서 실행할 수 있으며, 애플리케이션은 MONGODB_URI에 Atlas 연결 문자열을 설정하여 MongoDB Atlas를 사용할 수도 있습니다. 시연 및 검증된 마이그레이션은 localhost의 MongoDB Community 8.0을 사용했습니다.

명령줄 어시스턴트(command-line assistant)도 이용 가능합니다:

ask-cricket-mongodb --question "사친 텐둘카가 기록한 테스트 하느드는 몇 번입니까?"
ask-cricket-mongodb --ipl --question "2023년 IPL 오렌지 캡 우승팀은 어디입니까?"

프롬프트, 생성된 계획(plan), 결과를 logs/mongodb/ 아래에 기록하려면 --trace를 추가하세요.

코드 (Code)

GitHub 저장소: krishnakumar-k1/CricketStats-WithMongoDB

MongoDB 버전은 CricketStats_WithMongoDB에 있습니다. 주요 구성 요소는 다음과 같습니다:

src/cricketstats/mongodb_migrate.py — 재개 가능한 SQLite-to-MongoDB 마이그레이션 및 인덱스 생성;
src/cricketstats/mongodb_verify.py — 컬렉션별 소스 카운트 검증;
src/cricketstats/mongodb_client.py — 로컬 또는 Atlas 연결 설정;
src/cricketstats/mongodb_assistant.py — Qwen 프롬프팅, 결정론적 계획(deterministic plans), 유효성 검사, 실행 및 추적(tracing);
src/cricketstats/web_app.py — localhost 웹 애플리케이션 및 API;
src/cricketstats/web_static/ — 브라우저 인터페이스;
tests/test_mongodb_migrate.py 및 tests/test_mongodb_assistant.py — MongoDB 경계 테스트(boundary tests); 그리고
MIGRATION_REPORT.md — 마이그레이션 총계 및 검증 기록.

구축 과정 (How I Built It)

애플리케이션은 다음 파이프라인을 따릅니다:

Natural-language cricket question
              ↓
Deterministic player-name and common-query resolution
...

크리켓 데이터베이스 마이그레이션 (Migrating the cricket databases)

소스 데이터셋은 이전에 SQLite에 저장되어 있었습니다. 저는 각 테이블을 필드 이름을 유지하면서 동일한 이름의 MongoDB 컬렉션으로 복사하는 마이그레이션 레이어를 구축했습니다. SQLite의 rowid는 MongoDB의 _id가 되며, 배열이나 객체를 포함하는 JSON 문자열은 네이티브 BSON 배열 및 문서가 됩니다.

마이그레이션은 배치(batches) 단위로 실행됩니다. 각 배치가 끝난 후, _migration_state에는 컬렉션별 체크포인트가 저장되어, 중단된 수백만 문서의 마이그레이션을 재시작하는 대신 재개할 수 있습니다. _migration_metadata는 소스 및 완료 세부 정보를 기록합니다. 컬렉션 로드가 완료되면, 애플리케이션은 플레이어 + 포맷 + 날짜, 경기 + 이닝, 팀 + 이닝 총점, 아웃시키는 투수 + 종류(kind), 그리고 IPL 경기 + 이닝 + 오버 + 볼과 같은 빈번한 패턴에 대한 복합 인덱스(compound indexes)를 생성합니다.

데이터베이스	데이터 컬렉션	문서 수
`cricketstats`	7	2,861,363
...

별도의 검증 명령은 모든 MongoDB 컬렉션 수를 해당 SQLite 소스 테이블의 개수와 비교합니다. 기록된 마이그레이션에서 24개 비교 항목 모두 일치했습니다.

핵심에 오픈소스 AI를 배치하다

Qwen에게 크리켓 기록을 암기하도록 요청하지 않습니다. Qwen의 임무는 유연한 언어를 구조화되고 읽기 전용인 MongoDB 집계(aggregation) 계획으로 변환하는 것입니다:

{
  "collection": "player_career_stats",
  "pipeline": [
...

애플리케이션은 Qwen에게 실시간 MongoDB 컬렉션에서 생성된 요약, 정확한 선수 이름 후보, 집계 규칙 및 최근 세션 컨텍스트를 전송합니다. Ollama는 동일한 장치에서 모델을 구동합니다.

스키마만으로는 충분하지 않은 이유

스키마는 다음 사항들을 설명해주지 않습니다:

테스트(Test) 경기는 네 개의 팀 이닝을 포함할 수 있다는 점;
타자는 한 경기에서 두 번 배트를 칠 수 있다는 점;
"against Australia"가 상대팀을 의미하고, "in Australia"가 위치를 의미한다는 점;
"overseas"는 선수의 본국에 따라 달라진다는 점;
타율(batting average)은 볼이 아닌 출루 횟수 대비 득점이라는 점; 또는
저장된 경력 위켓 총합을 문서 개수를 세는 대신 선택해야 한다는 점.

이러한 크리켓 의미론(semantics)들은 프롬프트 규칙과 고가치 질문 유형에 대한 결정론적 계획(deterministic plans)에 인코딩되어 있습니다.

신뢰할 수 있는 답변을 위한 하이브리드 접근 방식

모든 질문이 확률적 계획(probabilistic planning)을 필요로 하는 것은 아닙니다. 일반적인 저장된 경력 총합이나 IPL 오렌지/퍼플 캡 질문은 결정론적 MongoDB 파이프라인을 사용합니다. 더 개방형인 질문들은 Qwen을 사용하여 집계를 생성합니다.

선수 이름 또한 계획 전에 해결됩니다. 팬들이 "Sachin Tendulkar"라고 입력하면, 데이터베이스는 SR Tendulkar를 저장하고; "Sunil Gavaskar"는 SM Gavaskar로 매핑됩니다. MongoDB에서 발견된 알려진 별명 및 후보들은 플래너에게 제공되어 모델이 저장된 신원을 지어내지 않도록 합니다.

이러한 역할 분담은 검색을 MongoDB에, 알려진 고가치 패턴을 결정론적 코드에, 그리고 유연한 언어 해석을 Qwen에 남겨둡니다.

읽기 전용 검증 및 경계 실행

모델 출력은 신뢰할 수 없는 입력으로 간주됩니다. 응답은 컬렉션과 파이프라인만을 포함하는 단일 JSON 객체여야 합니다. 이 검증기는 다음과 같습니다:

기존의 비(非)내부 컬렉션만 허용합니다.
정의된 읽기 전용 집계 단계만 허용합니다.
$out, $merge, $function, $accumulator, 그리고 $where를 차단합니다.
$lookup 대상을 검증합니다.
30단계가 넘는 파이프라인을 거부합니다.
결과 제한(limit)이 누락된 경우 추가합니다.
명시적인 최종 제한을 설정합니다. 그리고
60초의 시간 초과로 집계를 실행합니다.

이 인터페이스를 통해 검증된 집계 결과와 반환된 행을 보여줄 수 있으므로, 사용자는 단순히 유창한 문장만 보고 그것이 어떻게 생성되었는지 확인할 필요가 없습니다.

AskCricinfo와의 비공식 비교

MongoDB 버전을 구축하기 전에, 저는 ESPNcricinfo의 AskCricinfo와 소규모 병렬 실험을 진행했습니다.

저는 두 도구에 다음 두 가지 질문을 했습니다:

“테스트 크리켓에서 이닝당 가장 많은 6개를 친 선수는 누구입니까?”
“아쉬윈은 테스트 경기에서 몇 개의 5연타를 기록했습니까?”

이 두 가지 간단한 확인 과정에서, CricketStats는 사용 가능한 데이터 중에서 제가 더 유용하다고 판단하는 결과를 산출했습니다. 중요한 차이점은 단순히 답변 텍스트가 아니었습니다. CricketStats는 생성된 쿼리를 노출하여 그 결과를 구조화된 이닝 기록까지 추적할 수 있게 했습니다.

이는 통제된 벤치마크나 CricketStats가 AskCricinfo보다 일반적으로 더 정확하다는 주장이 아니라, 수행된 비공식적인 비교였습니다. 또한 데이터셋은 그때 이후로 계속 발전해 왔습니다. 저는 이를 포함함으로써 제품의 틈새 시장을 명확히 하는 데 도움이 되었는데, 그곳에서는 쿼리, 필터, 집계 수준, 그리고 출처 행을 검사할 수 있는 투명하고 로컬에서 운영되는 크리켓 연구가 가능하다는 점입니다.

현재 경계

CricketStats는 공식 스코어링 권위 기관이 아닌 연구 보조 도구입니다. 생성된 파이프라인은 논리적으로 틀릴 수 있고, 불완전한 소스 데이터는 불완전한 답변을 생성할 수 있으며, 역사적 이름이나 장소는 수정이 필요할 수 있습니다. 또한 로컬 설정은 140억 개 매개변수 모델(parameter)을 실행할 수 있는 컴퓨터를 전제로 합니다.

이러한 한계점들은 눈에 보입니다. 사용자는 파이프라인과 결과 행을 검사하고, 직접 MongoDB 확인을 실행하며, 답변 조사가 필요할 때 추적(tracing) 기능을 활성화할 수 있습니다. 계획이 유효성 검사에 실패하면, 애플리케이션은 답변을 임의로 생성하기보다는 오류를 보고합니다.

왜 개방형 혁신(Open Innovation)이 중요한가?

개방형 혁신은 이 프로젝트의 경제적 측면과 신뢰 모델 모두를 변화시킵니다.

첫째, 추론(inference)을 로컬에서 실행할 수 있습니다. 기자의 미발표 연구 질문이나 스토리 아이디어가 외부 모델 API로 전송될 필요가 없습니다. MongoDB Community와 Ollama 모두 localhost에 바인딩된 상태로 유지될 수 있습니다.

둘째, 질문당 모델 API 비용이 발생하지 않습니다. 이는 소규모 전문 제품에게 중요합니다. 연구원은 매번 시도를 측정 가능한 비용으로 만들지 않고도 많은 탐색적 질문을 할 수 있습니다. 사용자가 여전히 하드웨어와 전기를 제공하므로, '로컬'이라는 것이 비용이 전혀 없다는 의미는 아닙니다.

셋째, 모델을 교체할 수 있습니다. Qwen은 구조화된 계획에 잘 작동하지만, 이 애플리케이션은 하나의 호스팅 AI 제공업체에 묶여 있지 않습니다. 저는 다른 오픈 웨이트(open-weight) 모델을 비교하거나, 다른 양자화(quantization)를 사용하거나, 궁극적으로 검토된 크리켓 질문-파이프라인 예제에 대해 파인튜닝할 수 있습니다.

가장 중요한 것은 추론 경계(reasoning boundary)가 검사 가능하다는 점입니다. 소스는 프롬프트, 결정론적 규칙(deterministic rules), 유효성 검사기(validator), 집계 계획(aggregation plan), 마이그레이션 로직(migration logic), 그리고 검증 프로세스를 노출합니다. 개발자는 규칙을 변경하고, 다른 모델을 테스트하며, 애플리케이션을 로컬 MongoDB 또는 Atlas에 연결하여 데이터와 직접적으로 답변을 검증할 수 있습니다.

이러한 트레이드오프(trade-offs)도 눈에 띕니다: 로컬 추론(local inference)에는 성능 좋은 하드웨어(capable hardware)가 필요하고, 모델 다운로드 용량이 크며, 설득력 있는 집계(aggregation)라 할지라도 여전히 잘못된 크리켓 해석을 담고 있을 수 있습니다. Qwen, 결정론적 안전장치(deterministic safeguards), MongoDB, 그리고 인간의 검토(human review)가 함께 작동하며, 그 어느 것도 완벽하다고 제시되지는 않습니다.

다음 상업적 실험은 비서 기능을 크리켓 작가와 분석가들에게 제공하고, 얼마나 많은 연구 시간을 절약하는지 측정하며, 어떤 질문에서 오류를 범했는지 수집하고, 사설 설정(private setup), 지원(support) 또는 맞춤형 보고서(custom reports)가 구매할 가치가 있는지 문의하는 것입니다.