SearchEngine - Query Analyzer API

자연어 쿼리를 분석하여 인구통계학적 속성을 추출하고, 복잡한 질의에 대해서는 시맨틱 검색을 수행하는 AI 기반 검색 엔진입니다.

Preview

Members

LEAD/FE	FE	BE	BE/DATA	BE/AI
구혁모	김예나	이가은	조주한	천성진

Tech Stack

• Python 3.11 - 런타임
• FastAPI - 웹 프레임워크
• LangChain - LLM 프레임워크
• Anthropic Claude - LLM (claude-opus-4)
• Sentence Transformers - 임베딩 모델
• PostgreSQL - 데이터베이스
• SQLAlchemy - ORM

Getting Started

Installation

# 저장소 클론
git clone https://github.com/hansung-sw-capstone-2025-2/2025_8_I_AI.git
cd 2025_8_I_AI

# 가상환경 생성 및 활성화
python -m venv venv
source venv/bin/activate

# 의존성 설치
pip install -r requirements.txt

Environment Variables

# LLM API Keys
ANTHROPIC_API_KEY=sk-ant-api03-xxx

# Database (Optional)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=search_engine
DB_USER=postgres
DB_PASSWORD=your_password

Run

# 개발 서버 실행
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# 또는
python main.py

Project Structure

SearchEngine/
├── main.py                      # FastAPI 앱 엔트리포인트
├── src/
│   ├── dependencies.py          # 의존성 주입 컨테이너
│   ├── domain/                  # 도메인 레이어
│   │   └── interfaces.py        # 추상 인터페이스 정의
│   ├── services/                # 서비스 레이어 (비즈니스 로직)
│   │   ├── query_analyzer.py   # 쿼리 분석 서비스
│   │   ├── llm_classifier.py   # LLM 분류기 구현
│   │   └── vector_retriever.py # 벡터 검색기 구현
│   ├── chains/                  # LangChain 체인 모듈
│   │   ├── unified_classifier.py  # 쿼리 분류 및 파싱
│   │   └── retriever.py         # 시맨틱 검색
│   ├── config.py                # 설정 관리
│   ├── resources.py             # 리소스 로더
│   └── schemas.py               # 데이터 스키마
├── data/                        # 데이터 파일
└── requirements.txt

Key Features

• 자연어 쿼리 분류: 사용자 질의를 단순(simple) 또는 복잡(complex)으로 자동 분류
• 인구통계 속성 추출: 질의에서 성별, 연령, 지역, 소득 등 인구통계 정보 자동 추출
• 상위 그룹 매핑: '젊은층', '수도권' 등 추상적 표현을 구체적 값으로 자동 확장
• 시맨틱 검색: 복잡한 질의에 대해 벡터 유사도 기반 검색 수행
• 구조화된 출력: 질의 분석 결과를 JSON 형태로 구조화하여 반환

API Endpoints

Query Analysis API

POST /analyze - 자연어 쿼리 분석 및 분류

Request Body:

{
  "question": "여행 가는 것을 좋아하는 20대 남성",
  "top_k": 3
}

Response:

{
  "status": "success",
  "query": "여행 가는 것을 좋아하는 20대 남성",
  "type": "complex",
  "count": null,
  "demographic": {
    "성별": ["1"],
    "연령대": ["20대"]
  },
  "attributes": ["여행"],
  "categories": ["관심사"],
  "similarity_hits": [
    {
      "question_id": "Q123",
      "question_text": "해외여행을 자주 가시나요?",
      "score": 0.85
    }
  ]
}

Query Classification Logic

Simple Query (단순 질의)

• 인구통계 속성만 포함된 경우
• 예: "서울에 거주하는 30대 남성"
• 인구통계 필드: 성별, 연령대, 거주지역, 결혼여부, 학력, 직업, 소득 등

Complex Query (복잡 질의)

• 인구통계 + 관심사/취향/행동/경험 결합
• 예: "여행 가는 것을 좋아하는 20대 남성"
• 복잡 질의의 경우 시맨틱 검색 자동 수행

LLM Models

• claude-opus-4-20250514: 쿼리 분류 및 구조화 분석

API Documentation

서버 실행 후 다음 URL에서 Swagger UI를 통해 API 문서를 확인할 수 있습니다:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

License

이 프로젝트는 한성대학교 기업연계 SW캡스톤디자인 수업에서 진행되었습니다.