🧠 수이에이전틱
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
또는 도우미 스크립트를 사용합니다.
- 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 파일을 업로드하는 고급 스크립트
필수 조건
- 파이썬 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에 따라 라이센스가 부여되었습니다.