> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 사용 |

<Note>
  `faiss-cpu`는 Windows에서 빌드 이슈가 있어 환경 마커로 제외됩니다. Windows 사용자는 ChromaDB, Qdrant, Milvus 등 다른 벡터 스토어를 사용합니다.
</Note>

## 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

```toml theme={null}
[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
```

## 설치

<Steps>
  <Step title="프로젝트 생성">
    ```bash theme={null}
    uv init rag-dev
    cd rag-dev
    ```
  </Step>

  <Step title="의존성 락 및 동기화">
    ```bash theme={null}
    uv lock
    uv sync
    ```
  </Step>

  <Step title="Jupyter 커널 등록">
    ```bash theme={null}
    uv run python -m ipykernel install --user --name rag-dev --display-name "UV rag-dev"
    ```
  </Step>
</Steps>

## 설치 확인

모든 OS 공통 확인:

```bash theme={null}
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` 확인:

```bash theme={null}
uv run python -c "import faiss; print('faiss', faiss.__version__)"
```

## 기본 사용 예시

문서 로드부터 벡터 검색, 답변 생성까지의 기본 RAG 파이프라인입니다.

```python theme={null}
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"])
```

<Tip>
  `OPENAI_API_KEY` 환경변수를 설정해야 OpenAI 임베딩과 LLM을 사용할 수 있습니다. 로컬 임베딩만 사용하려면 `sentence-transformers`로 대체합니다.
</Tip>

## 트러블슈팅

| 증상                        | 원인                         | 해결                                  |
| ------------------------- | -------------------------- | ----------------------------------- |
| 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` 확인, 사용량 점검         |

## 설치 점검 목록

* 관리자 권한/필수 도구 등 사전 요구사항을 먼저 확인했습니다.
* 설치 후 버전 확인 명령어(`--version`)를 실행해 정상 설치를 검증했습니다.
* PATH/환경변수 변경이 필요한 경우 터미널을 다시 열어 적용 여부를 확인했습니다.
* 문제가 생겼을 때를 대비해 설치 로그 또는 스크린샷을 남겼습니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Setup 홈" icon="house" href="/setup/index">
    운영체제별 설치 흐름을 다시 확인합니다.
  </Card>

  <Card title="다음: agent-dev" icon="arrow-right" href="/setup/uv-env/agent-dev">
    다음 설치 단계를 이어서 진행합니다.
  </Card>
</CardGroup>