출처: https://github.com/XinBow99/Local-Qdrant-RAG?tab=readme-ov-file
Local-Qdrant-RAG
Local-Qdrant-RAG is a framework designed to leverage the powerful combination of Qdrant for vector search and RAG (Retrieval-Augmented Generation) for enhanced query understanding and response generation. It uses the Qdrant service for storing and retrieving vector embeddings and the RAG model to augment query responses with information retrieved from Qdrant.
Getting Started
This guide will help you set up Local-Qdrant-RAG on your local machine for development and testing purposes.
Prerequisites
Before you begin, ensure you have the following installed:
- Python 3.8 or higher
- Docker and Docker Compose (for running Qdrant locally)
- Ollama (for running LLM locally)
- Qdrant (Vector Database)
Installation
- Clone the Repository
- $git clone <https://github.com/your-repo/local-qdrant-rag.git>
$cd local-qdrant-rag
- Install Dependencies
Install all necessary Python packages.
# $pip install -r requirements.txt
| ㅁ 가상 환경(venv) 활용하기 (RAG 프로젝트 추천) 로컬 AI나 RAG 시스템을 구축 중이시라면, 시스템 전체에 패키지를 깔기보다 가상 환경을 만들어 그 안에서 pip를 쓰는 것이 관리에 훨씬 유리합니다.
source venv/bin/activate
# sentence-transformers와 qdrant-client 등 코드 실행에 필요한 패키지를 설치해야 합니다. pip install qdrant-client sentence-transformers langchain-community pip install llama-index pip install llama-index llama-index-embeddings-huggingface llama-index-vector-stores-qdrant pip install llama-index llama-index-llms-ollama llama-index-embeddings-huggingface llama-index-vector-stores-qdrant
|
Set Up Qdrant
Follow the instructions in the Qdrant website
docker pull qdrant/qdrant
#코드의 q_client_url="http://localhost:6333/" 부분을 보면 로컬에서 Qdrant 서버가 돌아가고 있어야 합니다. Docker를 사용하는 # 것이 가장 간편합니다.
# 터미널에서 아래 명령어 실행
Follow the instructions in the Ollama website
$curl -fsSL https://ollama.com/install.sh | sh
| $ curl https://ollama.ai/install.sh $ chmod 755 install.sh >> Downloading ollama... >>> Installing ollama to /usr/local/bin... [sudo] userid 암호: >>> Adding ollama user to render group... >>> Adding current user to ollama group... >>> Creating ollama systemd service... >>> Enabling and starting ollama service... >>> NVIDIA GPU installed. $ ollama serve #설치 후 자동 실행되지만 나중에는 이렇게 실행하면 된다. Error: listen tcp 127.0.0.1:11434: bind: address already in use $ ollama run llama3.1:8b # exaone3.5:7.8b |
$ollama run <path-to-model>
Usage
- Ingest Data into Qdrant
Before using the RAG model, you need to ingest your dataset into Qdrant. The DataIngestor class in qdrant_data_helper.py can help with this task.
------------------------------------------------------------------------------------------
from utils import qdrant_data_helper
ingestor = qdrant_data_helper.DataIngestor(
q_client_url="http://localhost:6333/",
q_api_key="test", # you can change this to your own qdrant api key if you have set it, otherwise, using None
data_path="./data/",
collection_name="dcard_collection",
embedder_name="sentence-transformers/all-mpnet-base-v2"
)
index = ingestor.ingest()
print("Index created successfully!")
------------------------------------------------------------------------------------------
Folder structure for data_path:
data/
├── doc1.txt
├── doc2.txt
├── doc3.txt
└── ...
- Using the RAG Model
To use the RAG model for query responses, instantiate the RAG class and use the get_response method.
"""
Thie is inference code for the RAG and Qdrant with Ollama
"""
from utils.qdrant_data_helper import RAG, Query
def main():
host = "localhost"
rag = RAG(
q_client_url=f"http://{host}:6333/",
q_api_key="test", # you can change this to your own qdrant api key if you have set it, otherwise, using None
ollama_model="gemma:7b",
ollama_base_url=f"http://{host}:11434",
)
search_index = rag.qdrant_index(
collection_name="dcard_collection",
chunk_size=1024
)
query = Query(
query="高科大是什麼時候合併的？",
top_k=5
)
result = rag.get_response(
index= search_index,
query= query,
append_query="",
response_mode="tree_summarize"
)
print("Result: ", result.search_result)
print("Score: ", result.source)
if __name__ == "__main__":
main()
Follow the llamaindex library to set response_mode. llamaindex
References
To-Do
- Add support for other vector databases
- Optimize Metadata Filtering
"Command 'pip' not found, did you mean:" 해결 방법
pip 명령어를 찾을 수 없다는 메시지는 현재 사용 중인 Ubuntu(WSL2) 환경에 파이썬 패키지 관리자인 pip가 설치되어 있지 않거나, 경로(PATH)가 설정되지 않았을 때 발생합니다.
가장 빠르고 확실한 해결 방법들을 단계별로 정리해 드립니다.
1. Ubuntu 패키지 관리자로 설치 (가장 권장)
WSL2 환경에서는 시스템 자체에 pip를 설치하는 것이 가장 간편합니다. 터미널에 다음 명령어를 순서대로 입력하세요.
Bash
# 패키지 리스트 업데이트
sudo apt update
# 파이썬 3용 pip 설치
sudo apt install python3-pip
- 설치 중간에 Do you want to continue? [Y/n] 메시지가 나오면 Enter 또는 y를 입력합니다.
2. 설치 후 확인
설치가 완료되었다면 정상적으로 인식되는지 버전을 확인합니다.
Bash
pip3 --version
만약 pip3는 되는데 pip라는 명령어만 안 되는 경우라면, 아래 명령어로 별칭(alias)을 설정하거나 pip3를 그대로 사용하시면 됩니다.
3. 가상 환경(venv) 활용하기 (RAG 프로젝트 추천)
로컬 AI나 RAG 시스템을 구축 중이시라면, 시스템 전체에 패키지를 깔기보다 가상 환경을 만들어 그 안에서 pip를 쓰는 것이 관리에 훨씬 유리합니다.
- venv 모듈 설치:
Bash
sudo apt install python3-venv
- 가상 환경 생성 및 활성화:
Bash
python3 -m venv venv
source venv/bin/activate
- 결과: 활성화된 상태((venv) 표시가 뜸)에서는 pip 명령어만 입력해도 내부적으로 잘 작동합니다.
💡 팁: 'Permission Denied' 오류가 난다면?
간혹 pip install 시 권한 문제가 발생할 수 있습니다. 이때 sudo pip를 사용하는 것은 보안상 권장되지 않으므로, 가급적 위의 3번(가상 환경) 방식을 사용하시거나 아래처럼 사용자 전용으로 설치하세요.
- pip install --user <패키지명>
지금 진행 중인 local-qdrant-rag 프로젝트 폴더 안에서 가상 환경을 만들고 계신가요? 환경 구성 중에 다른 라이브러리(예: pymilvus나 qdrant-client) 설치가 필요한 단계라면 바로 말씀해 주세요!
"root@DESKTOP-FTGPEGB:/opt/Local-Qdrant-RAG# pip install -r requirements.txt
error: externally-managed-environment" 해결 방법은?
현재 사용 중인 Ubuntu 환경(WSL2)이 시스템 파이썬 환경을 보호하기 위해 패키지 설치를 제한하고 있는 상태입니다. 최신 리눅스 배포판에서 흔히 발생하는 안전장치입니다.
이 문제를 해결하고 Local-Qdrant-RAG 프로젝트를 정상적으로 실행할 수 있는 가장 깔끔한 방법 3가지를 정리해 드립니다.
방법 1: 파이썬 가상 환경(venv) 사용 (가장 추천)
시스템 환경을 건드리지 않고 프로젝트 전용 독립 공간을 만드는 방식입니다. RAG 시스템처럼 라이브러리 의존성이 복잡한 경우 이 방법이 필수입니다.
- 가상 환경 생성 도구 설치 (설치되어 있지 않은 경우):
Bash
apt update && apt install python3-venv
- 프로젝트 폴더 내에 가상 환경 생성:
Bash
python3 -m venv venv
- 가상 환경 활성화:
Bash
source venv/bin/activate
- 패키지 다시 설치:
Bash
pip install -r requirements.txt
방법 2: --break-system-packages 옵션 사용 (빠른 해결)
가상 환경을 만들기 번거롭고 즉시 설치하고 싶을 때 사용합니다. 다만 시스템 파이썬 패키지와 충돌이 발생할 위험이 있어 권장되지는 않습니다.
Bash
pip install -r requirements.txt --break-system-packages
방법 3: pipx 활용하기
만약 특정 라이브러리가 아니라 '도구(Tool)'로서의 프로그램을 설치하려는 목적이라면 pipx가 대안이 될 수 있습니다. (하지만 RAG 개발 목적이라면 방법 1이 훨씬 낫습니다.)
Bash
apt install pipx
pipx ensurepath
pipx install -r requirements.txt
⚠️ 보안 및 관리 팁
현재 root 계정으로 작업을 진행 중이신데, 실제 개발 환경에서는 가급적 일반 사용자 계정에서 가상 환경을 사용하시는 것이 권장됩니다.
- Qdrant 연동 관련: requirements.txt 설치가 끝나면 보통 qdrant-client가 포함되어 있을 겁니다. 혹시 Qdrant 서버를 Docker로 띄우실 계획인가요, 아니면 로컬 바이너리로 실행하실 계획인가요? 그 단계에서 설정 파일(config.yaml 등) 수정이 필요할 수 있으니 도움이 필요하시면 말씀해 주세요.
참고
"(venv) root@DESKTOP-FTGPEGB:/Local-Qdrant-RAG# python3 qdrant_data_helper.py Traceback (most recent call last): File "/Local-Qdrant-RAG/qdrant_data_helper.py", line 1, in <module> from utils import qdrant_data_helper File "/Local-Qdrant-RAG/utils/qdrant_data_helper.py", line 5, in <module> from .text_transformations import get_transform_pipeline File "/Local-Qdrant-RAG/utils/text_transformations.py", line 2, in <module> from llama_index.core import Document ModuleNotFoundError: No module named 'llama_index'" 해결 방법?
Edit
Copy
Share
이 오류는 llama_index 모듈이 설치되지 않았기 때문에 발생합니다. 다음 단계로 해결할 수 있습니다:
해결 방법
1. llama-index 설치
bash
Copy
pip install llama-index
또는 핵심 기능만 필요하다면:
bash
Copy
pip install llama-index-core
2. 가상환경 확인
가상환경(venv)이 활성화된 상태에서 설치했는지 확인하세요:
bash
Copy
# 가상환경 활성화 (이미 활성화된 것으로 보입니다)
source venv/bin/activate # Linux/Mac
# 또는
venv\Scripts\activate # Windows
# 설치 확인
pip list | grep llama
3. requirements.txt 확인
프로젝트에 requirements.txt 파일이 있다면:
bash
Copy
pip install -r requirements.txt
4. 설치 후 확인
bash
Copy
python -c "from llama_index.core import Document; print('OK')"
추가로 llama-index 관련 다른 패키지도 필요할 수 있습니다 (예: llama-index-embeddings-huggingface, llama-index-vector-stores-qdrant 등). 전체 의존성을 한 번에 설치하려면:
bash
Copy
pip install llama-index llama-index-embeddings-huggingface llama-index-vector-stores-qdrant
"ModuleNotFoundError: No module named 'llama_index.llms.ollama'" 해결 방법?
Edit
Copy
Share
이 오류는 llama-index의 Ollama 통합 패키지가 설치되지 않았기 때문에 발생합니다.
해결 방법
1. llama-index-llms-ollama 설치
bash
Copy
pip install llama-index-llms-ollama
2. 전체 관련 패키지 한 번에 설치
Qdrant RAG 프로젝트를 위해 일반적으로 필요한 패키지들:
bash
Copy
pip install llama-index llama-index-llms-ollama llama-index-embeddings-huggingface llama-index-vector-stores-qdrant
3. 설치 확인
bash
Copy
python -c "from llama_index.llms.ollama import Ollama; print('OK')"
llama-index 주요 통합 패키지 정리
Table
| 기능 | 설치 명령어 |
| 핵심 기능 | pip install llama-index-core |
| Ollama LLM | pip install llama-index-llms-ollama |
| OpenAI | pip install llama-index-llms-openai |
| HuggingFace 임베딩 | pip install llama-index-embeddings-huggingface |
| Qdrant 벡터 스토어 | pip install llama-index-vector-stores-qdrant |
| 전체 (추천) | pip install llama-index (대부분 포함) |
llama-index를 이미 설치했는데도 오류가 발생하면, 버전 문제일 수 있으니 업그레이드도 시도해보세요:
bash
Copy
pip install --upgrade llama-index llama-index-llms-ollama
"MPNetModel LOAD REPORT from: sentence-transformers/all-mpnet-base-v2 Key | Status | | ------------------------+------------+--+- embeddings.position_ids | UNEXPECTED | | Notes: - UNEXPECTED: can be ignored when loading from different task/architecture; not ok if you expect identical arch. /Local-Qdrant-RAG/utils/qdrant_data_helper.py:46: UserWarning: Api key is used with an insecure connection. self.client = qdrant_client.QdrantClient(url=q_client_url, api_key=q_api_key) if q_api_key else qdrant_client.QdrantClient(url=q_client_url) Traceback (most recent call last):" 해결 방법?
Edit
Copy
Share
이 메시지들은 경고(Warning)이며, 실제 오류는 마지막 Traceback 이후에 나옵니다. 하지만 각각의 의미와 해결 방법을 설명드립니다:
1. MPNetModel UNEXPECTED Warning (무시 가능)
plain
Copy
embeddings.position_ids | UNEXPECTED
원인: sentence-transformers 모델을 로드할 때 발생하는 일반적인 경고입니다. 모델 아키텍처 차이로 인한 것이며 무시해도 됩니다.
해결 (선택사항):
Python
Copy
# transformers 라이브러리 경고 숨기기
import warnings
warnings.filterwarnings("ignore", message=".*UNEXPECTED.*")
2. Api key insecure connection Warning (중요)
plain
Copy
UserWarning: Api key is used with an insecure connection.
원인: HTTP 연결(비보안)에 API 키를 사용하고 있습니다.
해결 방법
방법 A: HTTPS 사용 (권장)
Python
Copy
# URL을 https:// 로 변경
q_client_url = "https://your-qdrant-server:6333"
방법 B: 로컬 개발 환경 (경고 무시)
Python
Copy
import warnings
# 경고 숨기기 (로컬 개발 시에만)
warnings.filterwarnings("ignore", category=UserWarning)
방법 C: API 키 없이 로컬 연결
Python
Copy
# 로컬 Qdrant는 API 키 필요 없음
self.client = qdrant_client.QdrantClient(url="http://localhost:6333")
# 또는
self.client = qdrant_client.QdrantClient(path="/path/to/local/storage") # 로컬 파일 모드
3. 실제 오류 확인
마지막 Traceback 이후의 완전한 에러 메시지를 보여주시면 정확한 해결 방법을 알려드릴 수 있습니다.
bash
Copy
# 전체 에러 메시지 복사해서 공유해주세요
요약: utils/qdrant_data_helper.py 수정 예시
Python
Copy
import warnings
warnings.filterwarnings("ignore") # 또는 특정 경고만 필터링
import qdrant_client
from llama_index.vector_stores.qdrant import QdrantVectorStore
class QdrantDataHelper:
def __init__(self, q_client_url, q_api_key=None):
# 로컬 개발: API 키 없이
if not q_api_key:
self.client = qdrant_client.QdrantClient(url=q_client_url)
# 원격 서버: HTTPS 권장
elif q_client_url.startswith("https"):
self.client = qdrant_client.QdrantClient(
url=q_client_url,
api_key=q_api_key
)
# HTTP + API 키 (경고 발생)
else:
self.client = qdrant_client.QdrantClient(
url=q_client_url,
api_key=q_api_key
)
실제 Traceback 이후의 에러 내용을 공유해주시면 더 정확히 도와드릴 수 있습니다!
"MPNetModel LOAD REPORT from: sentence-transformers/all-mpnet-base-v2 Key | Status | | ------------------------+------------+--+- embeddings.position_ids | UNEXPECTED | | Notes: - UNEXPECTED: can be ignored when loading from different task/architecture; not ok if you expect identical arch. /Local-Qdrant-RAG/utils/qdrant_data_helper.py:46: UserWarning: Api key is used with an insecure connection. self.client = qdrant_client.QdrantClient(url=q_client_url, api_key=q_api_key) if q_api_key else qdrant_client.QdrantClient(url=q_client_url) Traceback (most recent call last): File "/Local-Qdrant-RAG/qdrant_data_helper.py", line 19, in index = ingestor.ingest() ^^^^^^^^^^^^^^^^^ File "/Local-Qdrant-RAG/utils/qdrant_data_helper.py", line 80, in ingest service_context = self.create_service_context() ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/Local-Qdrant-RAG/utils/qdrant_data_helper.py", line 73, in create_service_context return ServiceContext.from_defaults(llm=None, embed_model=self.embedder, chunk_size=self.chunk_size) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/root/venv/lib/python3.12/site-packages/llama_index/core/service_context.py", line 33, in from_defaults raise ValueError( ValueError: ServiceContext is deprecated. Use llama_index.settings.Settings instead, or pass in modules to local functions/methods/interfaces. See the docs for updated usage/migration: https://docs.llamaindex.ai/en/stable/module_guides/supporting_modules/service_context_migration/ "
Edit
Copy
Share
이 오류는 ServiceContext가 deprecated(폐기)되었기 때문에 발생합니다. LlamaIndex의 새로운 API 방식으로 변경해야 합니다.
해결 방법: ServiceContext → Settings 마이그레이션
수정 전 (기존 코드 - 오류 발생)
Python
Copy
# utils/qdrant_data_helper.py line 73
return ServiceContext.from_defaults(
llm=None,
embed_model=self.embedder,
chunk_size=self.chunk_size
)
수정 후 (새로운 방식)
방법 1: Settings 사용 (권장)
Python
Copy
# 파일 상단 import 변경
from llama_index.core.settings import Settings
from llama_index.core.node_parser import SentenceSplitter
# create_service_context 메서드 수정
def create_service_context(self):
# Settings에 글로벌 설정 적용
Settings.embed_model = self.embedder
Settings.llm = None # 또는 사용하는 LLM
Settings.node_parser = SentenceSplitter(chunk_size=self.chunk_size)
return Settings # 또는 None 반환 (Settings는 전역)
방법 2: 로컬 파라미터 전달 (더 현대적인 방식)
Python
Copy
# ingest 메서드에서 직접 파라미터 전달
from llama_index.core.node_parser import SentenceSplitter
def ingest(self):
# ServiceContext 없이 직접 파라미터 전달
documents = self.load_documents()
# 노드 파서 직접 생성
node_parser = SentenceSplitter(chunk_size=self.chunk_size)
nodes = node_parser.get_nodes_from_documents(documents)
# VectorStoreIndex 생성 시 embed_model 직접 전달
from llama_index.core import VectorStoreIndex
index = VectorStoreIndex(
nodes=nodes,
embed_model=self.embedder,
# llm=None # 필요시
)
return index
완전한 수정 예시: utils/qdrant_data_helper.py
Python
Copy
# 상단 import 수정
from llama_index.core import VectorStoreIndex, Document
from llama_index.core.settings import Settings # 새로운 방식
from llama_index.core.node_parser import SentenceSplitter
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
# ServiceContext import 제거
class QdrantDataHelper:
def __init__(self, ...):
# ... 기존 초기화 코드 ...
self.embedder = HuggingFaceEmbedding(
model_name="sentence-transformers/all-mpnet-base-v2"
)
def create_service_context(self):
"""Settings로 글로벌 설정"""
Settings.embed_model = self.embedder
Settings.llm = None # 임베딩만 할 경우
Settings.node_parser = SentenceSplitter(
chunk_size=self.chunk_size,
chunk_overlap=20 # 필요시 추가
)
return Settings
def ingest(self):
"""문서 인제스트"""
documents = self.load_documents()
# 방법 A: Settings 사용
self.create_service_context()
index = VectorStoreIndex.from_documents(documents)
# 방법 B: 직접 파라미터 전달 (권장)
# index = VectorStoreIndex.from_documents(
# documents,
# embed_model=self.embedder,
# node_parser=SentenceSplitter(chunk_size=self.chunk_size)
# )
return index
빠른 체크리스트
Table
| 항목 | 작업 |
| Import 제거 | from llama_index.core import ServiceContext 삭제 |
| Import 추가 | from llama_index.core.settings import Settings |
| Import 추가 | from llama_index.core.node_parser import SentenceSplitter |
| 메서드 수정 | ServiceContext.from_defaults(...) → Settings 설정 |
| 파라미터 전달 | chunk_size는 SentenceSplitter로 전달 |
참고 문서
- ServiceContext Migration Guide
- 핵심 변경: 글로벌 Settings 객체 사용 또는 함수 파라미터로 직접 전달
수정 후에도 오류가 발생하면 ingest 메서드의 전체 코드를 공유해주세요!
"Traceback (most recent call last): File "/Local-Qdrant-RAG/qdrant_data_helper.py", line 1, in <module> from utils import qdrant_data_helper File "/Local-Qdrant-RAG/utils/qdrant_data_helper.py", line 30 def __init__(self, ...): ^^^" 해결 방법
Edit
Copy
Share
이 오류는 Python 문법 오류입니다. ...는 실제 코드에서 사용할 수 없는 placeholder(자리표시자)입니다.
문제 원인
Python
Copy
def __init__(self, ...): # ❌ 잘못된 문법
Python에서는 ... (Ellipsis)를 함수 파라미터로 직접 사용할 수 없습니다.
해결 방법: 실제 파라미터로 변경
수정 전 (오류)
Python
Copy
def __init__(self, ...):
수정 후 (올바른 문법)
예시 1: QdrantDataHelper 클래스
Python
Copy
def __init__(self, q_client_url, q_api_key=None, chunk_size=512):
self.q_client_url = q_client_url
self.q_api_key = q_api_key
self.chunk_size = chunk_size
# ... 나머지 초기화 코드
예시 2: 실제 사용 중인 파라미터로 맞춰서
Python
Copy
def __init__(self, documents_path, q_client_url, q_api_key=None, chunk_size=512, collection_name="default"):
self.documents_path = documents_path
self.q_client_url = q_client_url
self.q_api_key = q_api_key
self.chunk_size = chunk_size
self.collection_name = collection_name
# Qdrant 클라이언트 초기화
import qdrant_client
if q_api_key:
self.client = qdrant_client.QdrantClient(url=q_client_url, api_key=q_api_key)
else:
self.client = qdrant_client.QdrantClient(url=q_client_url)
# 임베딩 모델 초기화
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
self.embedder = HuggingFaceEmbedding(model_name="sentence-transformers/all-mpnet-base-v2")
완전한 수정된 파일 예시
Python
Copy
# utils/qdrant_data_helper.py
import warnings
warnings.filterwarnings("ignore")
from llama_index.core import VectorStoreIndex, Document
from llama_index.core.settings import Settings
from llama_index.core.node_parser import SentenceSplitter
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.core import StorageContext
from llama_index.vector_stores.qdrant import QdrantVectorStore
import qdrant_client
import os
class QdrantDataHelper:
# ✅ 실제 파라미터로 수정
def __init__(self, documents_path, q_client_url, q_api_key=None,
chunk_size=512, collection_name="documents"):
self.documents_path = documents_path
self.q_client_url = q_client_url
self.q_api_key = q_api_key
self.chunk_size = chunk_size
self.collection_name = collection_name
# Qdrant 클라이언트
if q_api_key:
self.client = qdrant_client.QdrantClient(
url=q_client_url,
api_key=q_api_key
)
else:
self.client = qdrant_client.QdrantClient(url=q_client_url)
# 임베딩 모델
self.embedder = HuggingFaceEmbedding(
model_name="sentence-transformers/all-mpnet-base-v2"
)
# Vector Store
self.vector_store = QdrantVectorStore(
client=self.client,
collection_name=collection_name
)
def load_documents(self):
"""문서 로드"""
from llama_index.core import SimpleDirectoryReader
return SimpleDirectoryReader(self.documents_path).load_data()
def ingest(self):
"""문서 인제스트"""
# Settings 설정
Settings.embed_model = self.embedder
Settings.node_parser = SentenceSplitter(
chunk_size=self.chunk_size,
chunk_overlap=20
)
# 문서 로드 및 인덱싱
documents = self.load_documents()
storage_context = StorageContext.from_defaults(
vector_store=self.vector_store
)
index = VectorStoreIndex.from_documents(
documents,
storage_context=storage_context
)
return index
메인 파일 (qdrant_data_helper.py) 수정
Python
Copy
# qdrant_data_helper.py (루트 파일)
from utils.qdrant_data_helper import QdrantDataHelper
# ✅ 실제 값으로 인스턴스 생성
ingestor = QdrantDataHelper(
documents_path="./data", # 문서 경로
q_client_url="http://localhost:6333", # Qdrant URL
q_api_key=None, # API 키 (로컬은 None)
chunk_size=512, # 청크 크기
collection_name="my_collection" # 컬렉션 이름
)
index = ingestor.ingest()
print("Ingestion complete!")
핵심 정리
Table
| 잘못된 코드 | 올바른 코드 |
| def __init__(self, ...): | def __init__(self, param1, param2, ...): |
| ...는 placeholder | 실제 파라미터 이름과 기본값 지정 |
... (Ellipsis)는 Python에서 주로 다음 경우에 사용됩니다:
- 타입 힌트: Callable[..., int]
- pass 대체: def func(): ...
- NumPy 등에서 슬라이싱: arr[..., 0]
함수 파라미터 자리표시자로는 사용할 수 없습니다!
"Notes: - UNEXPECTED: can be ignored when loading from different task/architecture; not ok if you expect identical arch. Traceback (most recent call last): File "/Local-Qdrant-RAG/qdrant_data_helper.py", line 21, in index = ingestor.ingest() ^^^^^^^^^^^^^^^^^ File "/Local-Qdrant-RAG/utils/qdrant_data_helper.py", line 146, in ingest service_context = self.create_service_context() ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/Local-Qdrant-RAG/utils/qdrant_data_helper.py", line 139, in create_service_context return ServiceContext.from_defaults(llm=None, embed_model=self.embedder, chunk_size=self.chunk_size) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/root/venv/lib/python3.12/site-packages/llama_index/core/service_context.py", line 33, in from_defaults raise ValueError( ValueError: ServiceContext is deprecated. Use llama_index.settings.Settings instead, or pass in modules to local functions/methods/interfaces. See the docs for updated usage/migration: https://docs.llamaindex.ai/en/stable/module_guides/supporting_modules/service_context_migration/ " 해결 방법?
Edit
Copy
Share
이 오류는 ServiceContext가 deprecated(폐기)되었기 때문에 발생합니다. 이전에 설명드린 대로 Settings로 변경해야 합니다.
해결 방법
1. import 문 변경
Python
Copy
# utils/qdrant_data_helper.py 상단
# ❌ 제거
from llama_index.core import ServiceContext
# ✅ 추가
from llama_index.core.settings import Settings
from llama_index.core.node_parser import SentenceSplitter
2. create_service_context 메서드 수정
Python
Copy
# utils/qdrant_data_helper.py line 139
# ❌ 기존 코드 (오류)
def create_service_context(self):
return ServiceContext.from_defaults(
llm=None,
embed_model=self.embedder,
chunk_size=self.chunk_size
)
# ✅ 수정된 코드
def create_service_context(self):
# Settings에 글로벌 설정 적용
Settings.embed_model = self.embedder
Settings.llm = None # 임베딩만 수행하는 경우
Settings.node_parser = SentenceSplitter(
chunk_size=self.chunk_size,
chunk_overlap=20 # 필요시 추가
)
return Settings
3. ingest 메서드 수정 (선택사항 - 더 나은 방식)
Python
Copy
# utils/qdrant_data_helper.py line 146
# ❌ 기존
def ingest(self):
service_context = self.create_service_context()
# ... 나머지 코드
# ✅ 수정 - Settings는 전역이므로 반환값 불필요
def ingest(self):
# Settings 적용
self.create_service_context()
# 문서 로드
documents = self.load_documents()
# 인덱스 생성 (Settings 자동 적용)
from llama_index.core import VectorStoreIndex
index = VectorStoreIndex.from_documents(documents)
return index
완전한 수정된 create_service_context
Python
Copy
def create_service_context(self):
"""
ServiceContext 대신 Settings 사용 (LlamaIndex v0.10+)
"""
from llama_index.core.settings import Settings
from llama_index.core.node_parser import SentenceSplitter
# 글로벌 Settings 설정
Settings.embed_model = self.embedder
Settings.llm = None # 임베딩 전용
# chunk_size는 node_parser에 설정
Settings.node_parser = SentenceSplitter(
chunk_size=self.chunk_size,
chunk_overlap=getattr(self, 'chunk_overlap', 20)
)
# transformaciones도 필요시 설정
if hasattr(self, 'transformations'):
Settings.transformations = self.transformations
return Settings
가장 간단한 해결 (빠른 수정)
ServiceContext 부분만 주석 처리하고 Settings로 대체:
Python
Copy
# line 139 주변
def create_service_context(self):
# ServiceContext 제거, Settings로 대체
from llama_index.core.settings import Settings
from llama_index.core.node_parser import SentenceSplitter
Settings.embed_model = self.embedder
Settings.llm = None
Settings.node_parser = SentenceSplitter(chunk_size=self.chunk_size)
return Settings
참고: Settings vs ServiceContext 차이점
Table
| 항목 | ServiceContext (구) | Settings (신) |
| 사용 방식 | 인스턴스 생성 후 전달 | 전역 객체 직접 수정 |
| 반환 | 객체 반환 | 전역 객체 (싱글톤) |
| 유연성 | 지역적 설정 | 전역 설정 (override 가능) |
수정 후에도 오류가 지속되면 ingest 메서드의 전체 코드를 공유해주세요
'컴퓨터 활용(한글, 오피스 등) > 기타' 카테고리의 다른 글
| [Project] Spring Rag 도입 도전기(Spring AI, Qdrant DB) (0) | 2026.04.17 |
|---|---|
| 바이오 데이터 분석 도구 아카이브 연계 관리 (0) | 2026.04.15 |
| 폐쇄망 환경에서 내부 LLM 서버 구축 아키텍처 (0) | 2026.04.14 |
| 문장 부호 '/', ' ,', '·' (0) | 2026.04.14 |
| 오픈스택(OpenStack)을 설치하여 클라우드 환경을 구축 (0) | 2026.04.13 |