PyTorch 문서 검색 도구(프로젝트 일시 중단)

명령줄 기능을 갖춘 PyTorch 문서에 대한 의미 검색 프로토타입입니다.

현재 상태(2025년 4월 19일)

⚠️ 이 프로젝트는 현재 상당한 재설계를 위해 일시 중단되었습니다.

이 도구는 PyTorch 문서에 대한 기본적인 명령줄 검색 인터페이스를 제공하지만, 여러 영역에서 상당한 개선이 필요합니다. 핵심 임베딩 및 검색 기능은 기본적인 수준에서 작동하지만, 관련성 품질과 MCP 통합은 추가 개발이 필요합니다.

출력 예

지엑스피1

Related MCP server: DevDocs MCP Server

무엇이 효과가 있는가

✅ 기본 의미 검색 : PyTorch 문서를 쿼리하기 위한 명령줄 인터페이스
✅ 벡터 데이터베이스 : 임베딩 저장 및 쿼리를 위한 기능적 ChromaDB 통합
✅ 콘텐츠 구분 : 코드와 텍스트 콘텐츠를 구분합니다.
✅ 대화형 모드 : 세션에서 지속적인 대화형 쿼리를 실행하는 옵션

개선이 필요한 점

❌ 관련성 품질 : 중간 유사도 점수(0.35-0.37)는 최적이 아닌 결과를 나타냅니다.
❌ 콘텐츠 범위 : 전문 주제는 데이터베이스에 표현이 부족할 수 있습니다.
❌ 청킹 전략 : 현재 접근 방식은 임의의 지점에서 문서를 끊습니다.
❌ 결과 프레젠테이션 : 스니펫이 너무 짧고 맥락이 부족합니다.
❌ MCP 통합 : 연결 시간 초과 문제로 인해 Claude Code 통합이 불가능함

시작하기

환경 설정

모든 종속성을 포함하는 conda 환경을 만듭니다.

conda env create -f environment.yml
conda activate pytorch_docs_search

API 키 설정

이 도구에는 임베딩 생성을 위한 OpenAI API 키가 필요합니다.

export OPENAI_API_KEY=your_key_here

명령줄 사용법

# Search with a direct query
python scripts/search.py "your search query here"

# Run in interactive mode
python scripts/search.py --interactive

# Additional options
python scripts/search.py "query" --results 5  # Limit to 5 results
python scripts/search.py "query" --filter code  # Only code results
python scripts/search.py "query" --json  # Output in JSON format

프로젝트 아키텍처

• ptsearch/core/ : 핵심 검색 기능(데이터베이스, 임베딩, 검색)

• ptsearch/config/ : 구성 관리

• ptsearch/utils/ : 유틸리티 함수 및 로깅

• scripts/ : 명령줄 도구

• data/ : 내장된 문서 및 데이터베이스

• ptsearch/protocol/ : MCP 프로토콜 처리(현재 사용되지 않음)

• ptsearch/transport/ : 전송 구현(STDIO, SSE)(현재 사용되지 않음)

이 프로젝트가 일시 중지된 이유

현재 구현을 평가한 결과, 상당한 재설계가 필요한 몇 가지 과제를 확인했습니다.

1. 데이터 품질 문제 : 현재 임베딩 방식은 PyTorch 개념 간의 의미적 관계를 효과적으로 포착하지 못합니다. 관련성 점수가 0.35~0.37 정도면 양질의 사용자 경험을 제공하기에는 너무 낮습니다.

2. 청킹 제한 : 현재 방법은 개념적 경계가 아닌 문자 수를 기준으로 문서를 청크로 나누기 때문에 단편적인 결과가 발생합니다.

3. MCP 통합 문제 : 다양한 구현 방식에도 불구하고 Claude Code와 통합을 시도할 때 지속적인 시간 초과 문제가 발생했습니다.

   • 연결 설정 시 STDIO 통합에 실패했습니다.

   • SSE 전송을 사용하는 Flask 서버는 안정적인 연결을 유지할 수 없습니다.

   • UVX 배포에서도 유사한 시간 초과 문제가 발생했습니다.

미래 로드맵

개발이 재개되면 다음 사항에 중점을 둘 계획입니다.

1. 개선된 청킹 전략 : 개념적 경계를 보존하는 의미적 청킹 구현

2. 향상된 결과 서식 : 더 많은 컨텍스트와 더 나은 스니펫 선택 제공

3. 확장된 문서 범위 : 모든 PyTorch 주제에 대한 포괄적인 표현을 보장합니다.

4. MCP 통합 재설계 : Claude 팀과 협력하여 시간 초과 문제 해결

개발

테스트 실행

pytest -v tests/

형식 코드

black .

특허

MIT 라이센스