🧠 NeuroDoc: 망가진 프로토타입에서 프로덕션 준비가 된 비동기 AI 문서 엔진으로

이 게시물은 GitHub Finish-Up-A-Thon Challenge를 위한 제출물입니다.

저는 이 프로젝트를 포기했었습니다. 그러다 다시 부활시켰습니다. 취약한 CLI 스크립트가 어떻게 RAG 기능을 갖춘 풀스택 비동기 웹 대시보드로 변했는지 그 과정을 소개합니다.

🧨 문제점 — 왜 포기했는가

NeuroDoc은 야심 찬 아이디어로 시작되었습니다. NLP(자연어 처리)와 멀티코어 프로세싱(multi-core processing)을 활용하여 Python, scikit-learn, PyTorch, TensorFlow 전반의 문서를 가져오고(fetch), 스크래핑(scrape)하고, 처리(process)하며, 요약(summarize)하는 단일 도구를 만드는 것이었습니다.

하지만 곧 벽에 부딪혔습니다.

# 빌런: 모든 것을 얼려버리는 블로킹 동기 루프(blocking synchronous loop)
while True:
    query = input("Enter query: ")  # 🚫 메인 스레드를 차단(BLOCKS)함
...

원래의 프로토타입에는 세 가지 치명적인 결함이 있었습니다:

문제점	영향
메인 스레드의 input() 루프	모든 백그라운드 스크래핑 워커(scraping workers)를 차단함
...

오래 걸리는 문서 크롤링(doc crawls)이 중단되곤 했습니다. 단 한 번의 충돌로 전체 작업 큐(task queue)가 삭제되었습니다. 그것은 마치 사상누각 같았습니다. 멀리서 보면 인상적이었지만, 가까이서 보면 공포스러웠습니다.

그래서 저는 프로젝트를 보류했습니다.

💡 재기 — 무엇이 바뀌었는가

몇 달 후, 저는 맑은 정신과 계획을 가지고 돌아왔습니다. 재작성은 점진적인 방식이 아니라 구조적인(architectural) 방식이었습니다. 세 가지 변화가 모든 것을 맞아떨어지게 만들었습니다:

1. 🔄 asyncio + aiohttp를 이용한 완전한 비동기(Async) 재작성

블로킹 루프를 제거했습니다. 대신 스크래핑, 처리, 서비스 제공이 서로 방해하지 않고 **동시(concurrently)**에 일어날 수 있도록 하는 적절한 비동기 이벤트 루프(async event loop)를 도입했습니다.

async def fetch_documentation(url: str, session: aiohttp.ClientSession) -> DocResult:
    async with session.get(url, timeout=aiohttp.ClientTimeout(total=30)) as response:
        content = await response.text()
...

더 이상 터미널이 멈추지 않습니다. 더 이상 워커(workers)가 중단되지 않습니다.

2. 🗄️ 데이터베이스 기반 작업 큐 (휘발성 메모리 안녕)

인메모리(in-memory) 큐를 **지속 가능한 데이터베이스 기반 작업 큐(persistent, database-backed task queue)**로 교체했습니다. 이제 새벽 3시에 PyTorch 문서를 크롤링하던 중 서버가 충돌하더라도 작업이 손실되지 않습니다. 작업은 정확히 중단된 지점부터 재개됩니다.

class TaskQueue:
    async def enqueue(self, task: DocumentationTask) -> str:
        task_id = str(uuid.uuid4())
...

3. 🔍 RAG — 검색 증강 생성 (Retrieval-Augmented Generation) 레이어

이 단계에서 NeuroDoc은 단순한 "스크레이퍼 (scraper)"를 넘어 "지능형 문서 어시스턴트 (intelligent documentation assistant)"로 업그레이드됩니다.

가공되지 않은 문서를 그대로 반환하는 대신, 다음과 같은 과정을 거칩니다:

1. 청킹 (Chunks): 스크레이핑된 콘텐츠를 의미론적 세그먼트 (semantic segments)로 나눕니다.
2. 임베딩 (Embeds): 이를 벡터 스토어 (vector store)에 임베딩합니다.
3. 검색 (Retrieves): 쿼리에 대해 가장 관련성이 높은 청크를 검색합니다.
4. 생성 (Generates): 집중적이고 문맥을 인식하는 (context-aware) 요약을 생성합니다.

class RAGPipeline:
    async def query(self, user_query: str) -> RAGResponse:
        # 1단계: 쿼리 임베딩
...

🏗️ 아키텍처 개요 (Architecture Overview)

┌─────────────────────────────────────────────────────┐
│                   웹 대시보드 (Web Dashboard, FastAPI)            │
│              ┌──────────┬──────────────┐            │
...

📦 지원되는 문서 소스 (Supported Documentation Sources)

라이브러리	스크레이핑된 섹션	NLP 처리
🐍 Python	stdlib, builtins, language ref	코드 추출, 요약
...

🚀 시작하기 (Getting Started)

# 리포지토리 클론
git clone https://github.com/kaushikcoderpy1/neurodoc
cd neurodoc
...

그 다음 http://localhost:8000을 열고 쿼리를 시작하세요.

🧪 주요 기술적 결정 — 그리고 그 이유

왜 threading 대신 asyncio를 사용했는가?
문서 스크레이핑은 I/O 바운드 (I/O-bound, HTTP 대기) 작업입니다. asyncio는 단일 스레드로 수천 개의 동시 요청을 처리할 수 있으며, GIL (Global Interpreter Lock) 경합이나 레이스 컨디션 (race conditions)이 발생하지 않습니다.

왜 작업 큐(task queue)로 Redis 대신 SQLite를 사용했는가?
인프라 설정이 필요 없기 때문입니다. NeuroDoc은 개발 도구입니다. 단순히 큐를 유지하기 위해 Redis 의존성을 추가하는 것은 마찰을 일으킵니다. SQLite의 WAL (Write-Ahead Logging) 모드는 이 사용 사례에서 동시 읽기/쓰기를 깔끔하게 처리합니다.

왜 파인튜닝 (fine-tuning) 대신 RAG를 사용했는가?
문서는 끊임없이 변합니다. RAG는 실시간으로 스크레이핑된 콘텐츠에서 정보를 검색합니다. 파인튜닝된 모델은 몇 주 안에 데이터가 구식이 될 것입니다.

🤖 GitHub Copilot이 NeuroDoc을 구한 방법 — 해결하는 데 도움을 준 4가지 치명적인 버그

이 섹션은 재기 성공담의 핵심입니다. NeuroDoc은 단순히 다시 작성된 것이 아닙니다. Copilot을 진정한 페어 프로그래머 (pair programmer)로 활용하여 _심층적인 아키텍처 수준에서 디버깅 (debugged at a deep architectural level)_되었습니다. 다음은 Copilot이 해결하는 데 도움을 준, 실제 프로덕션 환경을 가로막았던 네 가지 치명적인 버그입니다.

🐛 버그 1: 멀티 코어 배치 작업 중 비동기 데이터베이스 연결 풀 누수 (Async Database Connection Pool Leaks)

장애 내용: asyncio.gather를 통한 고동시성 (high-concurrency) 부하 상황에서, 서브 코루틴 (sub-coroutines) 내부의 예외 케이스가 연결 해제 훅 (connection release hooks)을 우회했습니다. 이로 인해 asyncpg 풀 (pool) 소켓이 고갈되었고, 애플리케이션이 아무런 메시지 없이 멈춰버리는 현상이 발생했습니다.

표준적인 try/finally 정리 블록은 오래된 비동기 컨텍스트 (async contexts)를 참조했기 때문에 제대로 작동하지 않았습니다. 결국 풀 (pool)이 최대 용량에 도달하여 동결되었습니다.

Copilot의 도움:

Copilot은 로컬 트랜잭션 (transaction) 생명주기에 직접 결합되고 절대적인 타임아웃 가드 (timeout guards)를 포함하는 엄격한 연결 획득 패턴을 도입했습니다:

# Copilot이 제안한 획득 패턴
async with pool.acquire() as connection:
    async with connection.transaction():
...

또한, 원시 드라이버 (driver) 에러를 깔끔한 구조화된 응답으로 변환하는 전역 예외 래퍼 (exception wrappers)를 추가했습니다. 이를 통해 다운스트림 스크래핑 파이프라인 (downstream scraping pipeline)이 충돌하더라도 연결 정리를 보장할 수 있게 되었습니다.

🐛 버그 2: 패키징 버전 간 SpecifierSet .contains() AttributeError 발생

장애 내용: formatter.py는 DependencyAnalyzer를 통해 의존성 진단 (dependency diagnostics)을 수행합니다. 구버전의 packaging 라이브러리가 설치된 환경에서는 SpecifierSet에 대해 .contains()를 호출할 때 다음과 같은 에러가 발생했습니다:

AttributeError: 'SpecifierSet' object has no attribute 'contains'

이로 인해 진단 패널이 렌더링되기도 전에 전체 프로세스가 충돌했으며, 결과적으로 대다수의 사용자 환경에서 환경 검증 (environment validation) 기능이 조용히 작동을 멈췄습니다.

Copilot의 도움:

Copilot은 .contains()가 특정 버전에 종속적이지만, 네이티브 in 연산자는 packaging의 모든 과거 릴리스에 대해 **보편적인 하위 호환성 (backward-compatible)**을 가진다는 점을 식별해냈습니다:

# ❌ 기존의 실패하는 코드
elif not raw_spec.contains(local):

...

연산자 하나를 교체하는 것만으로, 모든 환경에서 충돌이 완전히 사라졌습니다.

🐛 버그 3: 단일 코어 CLI 디스패치(Dispatch)를 깨뜨리는 암시적 문자열 매핑

실패 원인: neurodoc.py에서 neurodoc fetch os와 같은 CLI 입력이 코어 ID `

이것들은 단순한 자동 완성 제안이 아니었습니다. Copilot은 비동기 생명주기 경계 (async lifecycle boundaries), 교차 버전 API 호환성 (cross-version API compatibility), 타입 시스템의 엣지 케이스 (type system edge cases), 그리고 **선형 대수 제약 조건 (linear algebra constraints)**에 대해 추론했습니다. 이는 수정은커녕 심지어 위치를 찾는 데만 수 시간이 걸리는 종류의 버그들입니다.

가장 큰 돌파구는 이것이 단순히 증상만을 해결하지 않았다는 점입니다. 각 버그에 대해, 왜 기존 방식이 취약했는지 설명해주었으며 프로덕션 환경에서도 견딜 수 있는 패턴을 제안했습니다.

이것이 바로 도구(tool)와 협업자(collaborator)의 차이입니다.

🔭 향후 계획

• 원클릭 문서 조회를 위한 브라우저 확장 프로그램
• WebSockets를 통한 스트리밍 응답
• Hugging Face, Pandas, NumPy 문서 지원
• 자체 호스팅 임베딩 모델 (API 키 불필요)
• 요약본을 Jupyter notebook으로 내보내기

🔗 링크

• 📁 GitHub: github.com/kaushikcoderpy1/neurodoc
• 🎬 데모 영상: YouTube Preview

DEV.to 해커톤을 위해 제작되었습니다. 고집과 비동기 Python (async Python), 그리고 너무 많은 커피의 힘으로 만들어졌습니다.