Skip to main content

​
rag-dev

인덱싱, 검색, 재순위화, 평가까지 포함한 RAG 개발 환경입니다.

​
문서 기준

  • 기준일: 2026-02-23
  • Python: 3.12
  • 운영체제: macOS, Ubuntu, Windows
  • 동기화 명령: uv sync

​
호환성 메모

환경faiss-cpu벡터 DB 클라이언트설명
Ubuntu / macOS설치됨전체 사용 가능로컬 FAISS + 외부 DB 모두 지원
Windows제외됨전체 사용 가능FAISS 대신 ChromaDB 또는 외부 DB 사용
faiss-cpu는 Windows에서 빌드 이슈가 있어 환경 마커로 제외됩니다. Windows 사용자는 ChromaDB, Qdrant, Milvus 등 다른 벡터 스토어를 사용하세요.

​
RAG 파이프라인에서 패키지 역할

패키지파이프라인 단계역할
langchain / langchain-community전체 오케스트레이션문서 로더, 체인, 프롬프트 구성
langchain-openai생성(Generation)OpenAI LLM/임베딩 연동
sentence-transformers임베딩(Embedding)로컬 임베딩 모델 (HuggingFace 기반)
tiktoken청킹(Chunking)토큰 기반 텍스트 분할
chromadb벡터 저장/검색경량 로컬 벡터 DB
faiss-cpu벡터 저장/검색대규모 유사도 검색 (Meta)
qdrant-client벡터 저장/검색Qdrant 서버 연동 클라이언트
pymilvus / milvus-lite벡터 저장/검색Milvus 연동 (lite: 로컬 임베디드 모드)
rank-bm25검색(Retrieval)키워드 기반 BM25 재순위화
ragas평가(Evaluation)RAG 품질 평가 (faithfulness, relevancy 등)

​
pyproject.toml

[project]
name = "rag-dev"
version = "0.1.0"
description = "RAG development environment"
requires-python = "==3.12.*"
dependencies = [
  "torch==2.10.0",
  "torchvision==0.25.0",
  "torchaudio==2.10.0",
  "langchain==1.2.10",
  "langchain-community==0.4.1",
  "langchain-openai==1.1.10",
  "sentence-transformers==5.2.3",
  "chromadb==1.5.1",
  "faiss-cpu==1.13.2; platform_system != 'Windows'",
  "qdrant-client==1.17.0",
  "pymilvus==2.6.9",
  "milvus-lite==2.5.1",
  "rank-bm25==0.2.2",
  "ragas==0.4.3",
  "tiktoken==0.12.0",
  "openai==2.21.0",
  "ipykernel==7.2.0",
  "pytest==9.0.2",
  "ruff==0.15.2",
]

[tool.uv]
package = false

​
설치

1

프로젝트 생성

uv init rag-dev
cd rag-dev
2

의존성 락 및 동기화

uv lock
uv sync
3

Jupyter 커널 등록

uv run python -m ipykernel install --user --name rag-dev --display-name "UV rag-dev"

​
설치 확인

모든 OS 공통 확인: 
uv run python -c "import torch, langchain, chromadb, ragas; print('torch', torch.__version__); print('langchain', langchain.__version__); print('chromadb', chromadb.__version__); print('ragas', ragas.__version__)"
macOS/Ubuntu에서 faiss 확인: 
uv run python -c "import faiss; print('faiss', faiss.__version__)"

​
기본 사용 예시

문서 로드부터 벡터 검색, 답변 생성까지의 기본 RAG 파이프라인입니다. 
from langchain_community.document_loaders import TextLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_community.vectorstores import Chroma
from langchain.chains import RetrievalQA

# 1) 문서 로드
loader = TextLoader("docs/guide.txt")
documents = loader.load()

# 2) 청킹
splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
chunks = splitter.split_documents(documents)

# 3) 임베딩 + 벡터 저장
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
vectorstore = Chroma.from_documents(chunks, embeddings, persist_directory="./chroma_db")

# 4) 검색 + 생성
retriever = vectorstore.as_retriever(search_kwargs={"k": 3})
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
qa_chain = RetrievalQA.from_chain_type(llm=llm, retriever=retriever)

# 5) 질의
result = qa_chain.invoke({"query": "프로젝트 설치 방법을 알려주세요."})
print(result["result"])
OPENAI_API_KEY 환경변수를 설정해야 OpenAI 임베딩과 LLM을 사용할 수 있습니다. 로컬 임베딩만 사용하려면 sentence-transformers로 대체하세요.

​
트러블슈팅

증상원인해결
Windows에서 faiss-cpu 미설치환경 마커로 의도적 제외ChromaDB 또는 Qdrant 사용
Qdrant 연결 실패QDRANT_URL 미설정 또는 서버 미실행환경변수 확인, docker run qdrant/qdrant
Milvus 연결 실패Milvus 서버 미실행milvus-lite 로컬 모드 사용 또는 서버 시작
chromadb 초기화 느림최초 컬렉션 생성 시 인덱스 빌드정상 동작, 두 번째 실행부터 빨라짐
tiktoken 인코딩 오류네트워크 차단으로 토크나이저 다운로드 실패오프라인 캐시 설정 또는 네트워크 확인
RAGAS 평가 시 API 오류OpenAI API 키 미설정 또는 할당량 초과OPENAI_API_KEY 확인, 사용량 점검