🧠 수이에이전틱

SuiAgentic은 Qdrant 벡터 데이터베이스를 기반으로 하는 문서 임베딩 및 시맨틱 검색을 위한 FastAPI 기반 애플리케이션입니다. URL 또는 로컬 파일의 문서를 임베딩으로 변환하고, 효율적으로 저장하고, 자연어 쿼리를 사용하여 관련 콘텐츠를 검색할 수 있습니다. Cursor, Copilot, Claude 및 기타 MCP 호환 클라이언트와 같은 AI 기반 도구를 지원하도록 설계되었습니다.

💡 왜 SuiAgentic인가요? 많은 조직에서 내부 문서(예: PRD, 디자인 사양, 위키)의 맥락을 개발자와 지식 근로자가 사용하는 도구에 통합해야 합니다. 하지만 다양한 출처의 문서를 검색 가능한 중앙화된 지식 베이스로 통합하는 것은 복잡하고 단편적입니다.

SuiAgentic은 콘텐츠를 수집, 청크, 임베드 및 인덱싱하는 중앙 집중식 컨텍스트 서버를 제공하여 이 문제를 해결합니다. 이를 통해 간편한 REST API와 웹 인터페이스를 통해 콘텐츠를 이용할 수 있습니다. 또한 AI 에이전트를 위한 MCP 서버로도 사용할 수 있습니다.

🚀 주요 기능 문서 임베딩: URL에서 콘텐츠를 추출하고(인증 여부와 관계없이), 이를 청크로 분할하고, 임베딩을 생성하여 Qdrant에 저장합니다.

의미 검색: 자연어로 지식 기반을 쿼리하고 관련 덩어리나 문서를 검색합니다.

웹 UI: 삽입 및 검색을 위한 사용하기 쉬운 웹 인터페이스입니다.

REST API: 자동화 또는 통합을 위해 HTTP 엔드포인트를 통해 완벽하게 접근 가능합니다.

MCP 서버 지원: Cursor, Copilot, Claude 등 MCP 호환 클라이언트와 함께 사용하세요.

인증 지원: 보호된 문서에 대한 기본 인증 및 전달자 토큰을 지원합니다.

⚙️ 빠른 시작

저장소 복제

지엑스피1

Python 환경 설정

python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate

종속성 설치

pip install -r requirements.txt

.env 파일을 만듭니다(또는 제공된 .env.example을 사용합니다)

QDRANT_URL=localhost QDRANT_PORT=6333 QDRANT_COLLECTION_NAME=documents

Qdrant(벡터 DB) 시작

Docker 사용:

docker run -p 6333:6333 qdrant/qdrant

또는 도우미 스크립트를 사용합니다.

./runqdrant.sh

Agentic 앱을 실행하세요

uvicorn app.main:app --reload # or: python run.py

http://localhost:8000을 방문하세요

🌐 웹 인터페이스 및 API

웹 UI:

/ - 집
/embed — UI를 통해 문서 삽입
/retrieve — 의미 검색 UI

🔍 POST / 검색

{ "query": "What is the architecture of Sui?", "top_k": 5, "group_by_doc": true }

🌍 URL에서 임베드

공개 URL:

API나 UI를 통해 URL만 제공하면 됩니다. 인증은 필요 없습니다.

🤖 MCP 서버로 사용

sui를 MCP 서버로 사용하려면:

{ "mcpServers": { "suiAgentic": { "url": "http://localhost:8000/mcp" } } }

문서 업로드 도구

이 디렉토리에는 SuiAgentic Qdrant 데이터베이스에 문서를 대량으로 업로드하는 도구가 들어 있습니다.

사용 가능한 도구

upload_folder.py - 폴더에서 PDF 파일을 업로드하는 간단한 스크립트
upload_documents.py - 더 많은 옵션을 사용하여 PDF, DOCX 및 TXT 파일을 업로드하는 고급 스크립트

Related MCP server: RagDocs MCP Server

필수 조건

파이썬 3.8 이상
SuiAgentic 애플리케이션 설치 및 구성
로컬로 실행되거나 네트워크를 통해 접근 가능한 Qdrant 서버
필수 종속성 설치됨(PyPDF2, python-docx)

기본 사용법

폴더에서 PDF 파일 업로드

# Upload all PDFs from a folder python upload_folder.py /path/to/pdf/folder # Upload with a prefix (useful for categorizing documents) python upload_folder.py /path/to/pdf/folder --prefix "Research Papers"

고급 문서 업로드

# Upload all supported documents from a folder and subfolders python upload_documents.py /path/to/documents --recursive # Add metadata tags to all documents python upload_documents.py /path/to/documents --tag category=research --tag project=alpha # Specify collection name (if not using default) python upload_documents.py /path/to/documents --collection my_collection # Complete example with all options python upload_documents.py /path/to/documents --recursive --prefix "Project X" --tag department=marketing --tag status=final

이 도구의 기능

지정된 폴더에서 지원되는 문서 찾기
각 문서에서 텍스트 콘텐츠 추출
텍스트를 관리하기 쉬운 덩어리로 분할
각 청크에 대해 3072차원 임베딩을 생성합니다.
Qdrant에 청크와 임베딩을 저장합니다.
각 문서의 메타데이터 추적

명령줄 인수

upload_folder.py

folder - PDF 파일이 포함된 폴더의 경로
--prefix - 문서 이름에 추가할 접두사

업로드_문서.py

folder - 문서가 포함된 폴더의 경로
--prefix - 문서 이름에 추가할 접두사
--recursive - 하위 폴더에서 재귀적으로 파일을 검색합니다.
--collection - 사용할 Qdrant 컬렉션의 이름
--tag - 문서에 메타데이터 태그를 추가합니다(여러 번 사용 가능: --tag key=value )

예시

프로젝트별로 문서 정리

python upload_documents.py /path/to/projects/project1 --recursive --prefix "Project 1" --tag project=alpha python upload_documents.py /path/to/projects/project2 --recursive --prefix "Project 2" --tag project=beta

문서 분류

python upload_documents.py /path/to/contracts --prefix "Legal" --tag department=legal --tag confidential=true python upload_documents.py /path/to/manuals --prefix "Technical" --tag department=engineering

문제 해결

대용량 문서에서 메모리 오류가 발생하면 문서를 더 작은 파일로 나누어 보세요.
대량의 문서 컬렉션의 경우 더 작은 배치로 처리하는 것을 고려하세요.
처리 중 오류가 있는지 로그 출력을 확인하세요.

🪪 라이센스

Apache License 2.0에 따라 라이센스가 부여되었습니다.

SuiAgentic