환경 설정 가이드

환경 설정 가이드

1. 사전 요구사항

1.1 시스템 요구사항

항목	요구사항
Python	3.10 이상
DDEV	si-data 프로젝트 환경
Elasticsearch	7.x (DDEV 컨테이너)

1.2 API 키

서비스	발급 방법
OpenAI	https://platform.openai.com → API keys → Create new secret key

---

2. 설치 절차

2.1 브랜치 체크아웃

cd /path/to/si-data
git checkout feature/openai-search-poc

2.2 가상환경 생성 및 활성화

cd services/llm-search

# 가상환경 생성
python3 -m venv venv

# 활성화 (macOS/Linux)
source venv/bin/activate

# 활성화 (Windows)
.\venv\Scripts\activate

2.3 의존성 설치

pip install --upgrade pip
pip install -r requirements.txt

2.4 환경변수 설정

# .env.example 복사
cp .env.example .env

# .env 파일 편집하여 API 키 설정
nano .env  # 또는 선호하는 에디터 사용

---

3. 환경변수 상세

3.1 필수 환경변수

변수명	설명	예시
OPENAI_API_KEY	OpenAI API 키	sk-proj-...
LLM_PROVIDER	기본 LLM 제공자	openai 또는 ollama

3.2 선택적 환경변수

변수명	기본값	설명
OPENAI_MODEL	gpt-4o	사용할 OpenAI 모델
OPENAI_TIMEOUT	30	API 타임아웃 (초)
OPENAI_MAX_RETRIES	3	최대 재시도 횟수
OLLAMA_HOST	http://localhost:11434	Ollama 서버 주소
OLLAMA_MODEL	qwen3:8b	Ollama 모델명
ES_HOST	elasticsearch	Elasticsearch 호스트
ES_PORT	9200	Elasticsearch 포트
PAGEINDEX_ENABLED	true	PageIndex 기능 활성화
DEBUG	false	디버그 모드
LOG_LEVEL	INFO	로그 레벨

3.3 환경변수 파일 예시 (.env)

# LLM Provider
LLM_PROVIDER=openai

# OpenAI
OPENAI_API_KEY=sk-proj-your-api-key-here
OPENAI_MODEL=gpt-4o
OPENAI_TIMEOUT=30

# Ollama (로컬 테스트용)
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=qwen3:8b

# Elasticsearch
ES_HOST=elasticsearch
ES_PORT=9200

# PageIndex
PAGEINDEX_ENABLED=true

# Debug
DEBUG=true
LOG_LEVEL=DEBUG

---

4. 서비스 실행

4.1 개발 모드 실행

cd services/llm-search
source venv/bin/activate

# uvicorn으로 실행 (hot reload)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

4.2 서비스 확인

# 헬스체크
curl http://localhost:8000/health

# API 문서
open http://localhost:8000/docs

4.3 DDEV 환경에서 Elasticsearch 접근

# DDEV 내부에서 ES 확인
ddev exec curl -s "elasticsearch:9200/_cat/indices?v"

# 로컬에서 ES 접근 (DDEV 포트포워딩 필요시)
ddev describe  # ES 포트 확인

---

5. 디렉토리 구조

services/llm-search/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI 애플리케이션
│   ├── config.py            # 환경변수 설정
│   ├── services/            # 비즈니스 로직
│   │   ├── __init__.py
│   │   ├── llm_client.py    # Ollama 클라이언트
│   │   ├── openai_client.py # OpenAI 클라이언트
│   │   ├── llm_factory.py   # Provider 팩토리
│   │   ├── rag_service.py   # RAG 서비스
│   │   └── pageindex_client.py
│   ├── routes/              # API 라우터
│   │   ├── __init__.py
│   │   ├── keywords.py
│   │   ├── benchmark.py
│   │   └── pageindex.py
│   └── data/                # 데이터 파일
│       ├── context/         # RAG 컨텍스트
│       └── indexes/         # PageIndex 캐시
├── tests/                   # 테스트
│   ├── benchmark.py
│   └── test_queries.json
├── venv/                    # 가상환경 (gitignore)
├── .env                     # 환경변수 (gitignore)
├── .env.example             # 환경변수 템플릿
├── requirements.txt         # 의존성
└── README.md

---

6. 문제 해결

6.1 OpenAI API 오류

증상: AuthenticationError: Invalid API key

해결:

1. .env 파일에서 OPENAI_API_KEY 확인
2. API 키가 sk-proj-... 형식인지 확인
3. OpenAI 콘솔에서 키 상태 확인

6.2 Elasticsearch 연결 실패

증상: ConnectionError: elasticsearch:9200

해결:

1. DDEV 환경이 실행 중인지 확인: ddev status
2. ES 컨테이너 상태 확인: ddev describe
3. ES 인덱스 확인: ddev exec curl elasticsearch:9200/_cat/indices

6.3 의존성 설치 오류

증상: pydantic_settings 모듈 없음

해결:

pip install pydantic-settings

---

7. 관련 문서

• 00_개요.md - 프로젝트 개요
• 02_OpenAI_클라이언트.md - OpenAI 클라이언트 상세
• 08_운영배포_가이드.md - 프로덕션 배포