USAGE_GUIDE.md

📖 사용 가이드 (한국어)

목차

1. 설치
2. PDF 인덱싱
3. API 서버 실행
4. 질문하기
5. 고급 사용법
6. 문제 해결

---

1. 설치

1-1. Python 환경 확인

python --version  # 3.8 이상 필요

1-2. 가상환경 생성

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

# 활성화 (맥/리눅스)
source venv/bin/activate

# 활성화 (윈도우)
venv\Scripts\activate

1-3. 의존성 설치

pip install -r requirements.txt

설치되는 주요 패키지:

• FastAPI (웹 서버)
• Anthropic (Claude API)
• ChromaDB (벡터 데이터베이스)
• Sentence Transformers (임베딩)
• PyPDF2, pdfplumber (PDF 처리)

---

2. PDF 인덱싱

2-1. 환경 변수 설정

.env 파일 생성:

cp .env.example .env

.env 파일 편집:

# 필수: Anthropic API 키
ANTHROPIC_API_KEY=sk-ant-api03-xxx...

# 필수: PDF 파일 경로 (로컬 맥북)
PDF_SOURCE_PATH=/Users/seongjincho/Desktop/HYU-06-공학박사 도전기/25.8.15(펀더멘털 DB 레퍼런스)/data/

# 선택: 임베딩 모델 (기본값 사용 권장)
EMBEDDING_MODEL=sentence-transformers
EMBEDDING_MODEL_NAME=all-MiniLM-L6-v2

2-2. 인덱싱 실행

python scripts/index_pdfs.py

예상 소요 시간:

• 2,639개 PDF 파일
• 약 30-60분 (무료 모델 사용 시)
• 처음 실행 시 모델 다운로드 추가 (~90MB)

진행 과정:

[1/4] PDF 파일 처리 중...
  - 전체 문서: 2639개
  - 전체 페이지: 50000+페이지

[2/4] 텍스트 청킹 중...
  - 전체 청크: 30000+개

[3/4] 임베딩 생성 중...
  - 임베딩 개수: 30000+개
  - 임베딩 차원: 384차원

[4/4] Vector DB에 저장 중...
  - 저장 완료!

2-3. 인덱싱 확인

python scripts/check_vector_db.py

---

3. API 서버 실행

3-1. 서버 시작

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

또는 간단하게:

python app/main.py

3-2. 서버 확인

브라우저에서:

• API 문서: http://localhost:8000/docs
• 대체 문서: http://localhost:8000/redoc

터미널에서:

curl http://localhost:8000/health

---

4. 질문하기

4-1. 웹 UI로 질문 (가장 쉬움)

1. http://localhost:8000/docs 접속
2. POST /query 클릭
3. "Try it out" 클릭
4. Request body 입력:

{
  "question": "금융위기의 주요 원인은?",
  "top_k": 5,
  "enable_metacognition": true
}

5. "Execute" 클릭

4-2. 터미널에서 질문

curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{
    "question": "포트폴리오 다각화의 효과는?",
    "top_k": 5,
    "enable_metacognition": true
  }'

4-3. Python 스크립트로 질문

python scripts/test_query.py

또는 Python 코드에서:

import requests

response = requests.post(
    "http://localhost:8000/query",
    json={
        "question": "중앙은행 금리 정책의 효과는?",
        "top_k": 5,
        "enable_metacognition": True
    }
)

result = response.json()
print(result["answer"])

---

5. 고급 사용법

5-1. 메타인지 비활성화 (빠른 응답)

{
  "question": "질문",
  "top_k": 5,
  "enable_metacognition": false
}

차이점:

• 메타인지 활성화: 10-30초, 고품질
• 메타인지 비활성화: 2-5초, 일반 품질

5-2. 검색 결과 개수 조정

{
  "question": "질문",
  "top_k": 10,  // 더 많은 문서 검색
  "enable_metacognition": true
}

5-3. 메타데이터 필터링

특정 저자의 논문만 검색:

{
  "question": "질문",
  "top_k": 5,
  "filter_metadata": {
    "author": "John Doe"
  }
}

5-4. 응답 구조 이해

{
  "question": "원본 질문",
  "answer": "생성된 답변",
  "sources": [
    {
      "text": "문서 내용...",
      "source_filename": "paper123.pdf",
      "similarity": 0.89,
      "metadata": {
        "title": "논문 제목",
        "author": "저자"
      }
    }
  ],
  "metacognition": {
    "thinking_history": [...],
    "iterations": 2
  },
  "search_stats": {
    "documents_found": 5,
    "top_similarity": 0.89
  }
}

---

6. 문제 해결

문제 1: PDF 경로 오류

FileNotFoundError: Directory not found

해결:

# .env 파일에서 PDF 경로 확인
nano .env

# 경로가 정확한지 확인
ls "/Users/seongjincho/Desktop/..."

문제 2: API 키 오류

AuthenticationError: Invalid API key

해결:

# .env 파일 확인
nano .env

# ANTHROPIC_API_KEY가 올바른지 확인
# 키는 sk-ant-api03-로 시작해야 함

문제 3: Vector DB가 비어있음

total_documents: 0

해결:

# 인덱싱 먼저 실행
python scripts/index_pdfs.py

# 확인
python scripts/check_vector_db.py

문제 4: 메모리 부족

MemoryError

해결:

# scripts/index_pdfs.py 수정
# 배치 크기 줄이기
embeddings = embedder.embed_batch(texts, batch_size=16)  # 32 → 16

문제 5: 서버가 시작되지 않음

Address already in use

해결:

# 포트 변경
uvicorn app.main:app --reload --port 8001

# 또는 .env 파일에서
API_PORT=8001

문제 6: 임베딩 모델 다운로드 실패

ConnectionError

해결:

# 수동으로 모델 다운로드
python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"

---

💡 팁

성능 최적화

1. SSD 사용: Vector DB는 SSD에 저장 권장
2. 메모리: 최소 8GB RAM 권장
3. 배치 크기: GPU 없으면 batch_size=16-32

비용 절감

1. 무료 임베딩: Sentence Transformers 사용
2. 메타인지 비활성화: 빠른 테스트 시

품질 향상

1. 메타인지 활성화: 고품질 답변 필요 시
2. top_k 증가: 더 많은 문서 참고
3. 청크 크기 조정: 긴 문맥 필요 시

---

📞 지원

문제가 해결되지 않으면:

1. GitHub Issues 등록
2. 로그 파일 첨부
3. 에러 메시지 전체 복사

로그 확인:

# API 서버 로그는 터미널에 출력됨
# 필요시 파일로 저장
uvicorn app.main:app > server.log 2>&1