Weaviate 실무 스터디 가이드

1. Weaviate란?

Weaviate는 오픈소스 벡터 데이터베이스로, AI 네이티브 애플리케이션을 위해 설계되었습니다. 벡터 임베딩과 객체 스토리지를 통합하고, GraphQL 및 REST API를 기본 제공합니다. 특히 RAG, 멀티모달 검색, 에이전트 워크플로우에 최적화되어 있습니다.

🔢 벡터 검색

고차원 임베딩 기반 유사도 검색 (cosine, dot, hamming).

🧠 하이브리드 검색

벡터 + 키워드 (BM25) 결합, ranking fusion.

📦 멀티모달

텍스트, 이미지, 오디오 등 다양한 모달리티 통합.

⚙️ 모듈식

OpenAI, Cohere, Hugging Face 등 임베딩/생성 모듈 플러그인.

2. 왜 써야 하는가?

전통적 벡터 DB(Pinecone, Milvus)와 비교한 Weaviate의 차별점:

기능	Weaviate	Pinecone	Milvus
오픈소스	✅ BSD-3	❌ Proprietary	✅ Apache 2.0
GraphQL 네이티브	✅ 기본	❌ REST only	❌ REST/gRPC
하이브리드 검색	✅ 내장	❌ 별도	✅ (부분)
멀티모달	✅ 모듈 지원	❌	❌
임베딩 파이프라인	✅ 내장	❌	❌
RAG 최적화	✅ 생성 모듈	❌	❌

💡 실무 포인트 — Weaviate는 벡터 DB + 임베딩 + 생성 모듈을 하나로 묶어 인프라 복잡도를 낮춥니다. MLOps 파이프라인 통합이 용이합니다.

3. 핵심 개념

Class, Object, Vector Index, Property, Module — Weaviate의 데이터 모델은 스키마 기반이며, 각 Class는 벡터 인덱스와 연결됩니다.

┌─────────────────────────────────────────────────────┐ │ Weaviate Core │ │ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │ │ │ GraphQL │ │ REST │ │ Modules │ │ │ │ API │ │ API │ │ (OpenAI, etc) │ │ │ └────┬─────┘ └────┬─────┘ └───────┬────────┘ │ │ └──────────────┼─────────────────┘ │ │ ▼ │ │ ┌──────────────────────────────────────────────┐ │ │ │ Object Store + Vector Index (HNSW) │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ Class A │ │ Class B │ │ Class C │ │ │ │ │ │ vectors │ │ vectors │ │ vectors │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ │ │ │ └──────────────────────────────────────────────┘ │ │ Storage: RocksDB (objects) + custom vector store │ └─────────────────────────────────────────────────────┘

핵심 용어 — Class (스키마), Object (데이터 인스턴스), Vector Index (HNSW, flat), Property (필드), Module (임베딩/생성).

4. 퀵스타트

🐳 Docker 설치 (로컬)

# docker-compose.yml (최소 설정)
version: '3.4'
services:
  weaviate:
    image: semitechnologies/weaviate:1.28.0
    ports:
      - "8080:8080"
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      DEFAULT_VECTORIZER_MODULE: 'text2vec-openai'
      OPENAI_APIKEY: 'YOUR_OPENAI_KEY'

# CLI 실행
docker compose up -d

🐍 Python 클라이언트 예제

import weaviate
import weaviate.classes as wvc

client = weaviate.connect_to_local()

# 스키마 생성 (Class)
client.collections.create(
    name="Document",
    vectorizer_config=wvc.config.Configure.Vectorizer.text2vec_openai(),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="content", data_type=wvc.config.DataType.TEXT),
    ]
)

# 객체 삽입
docs = client.collections.get("Document")
docs.insert({
    "title": "Weaviate 개요",
    "content": "벡터 데이터베이스의 미래"
})

# 유사도 검색
response = docs.query.near_text(query="벡터 DB", limit=3)
for obj in response.objects:
    print(obj.properties["title"], obj.properties["content"])

client.close()

⚠️ 주의 — text2vec-openai 모듈을 사용하려면 OPENAI_APIKEY 환경변수가 필요합니다. 로컬 테스트 시 text2vec-transformers로 대체 가능.

5. 핵심 설정 레퍼런스

환경변수 / 설정	값 예시	설명
`PERSISTENCE_DATA_PATH`	`/var/lib/weaviate`	데이터 영구 저장 경로
`DEFAULT_VECTORIZER_MODULE`	`text2vec-openai`	기본 임베딩 모듈
`QUERY_DEFAULTS_LIMIT`	`25`	쿼리 기본 limit
`AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED`	`true`	익명 접근 허용 (개발)
`CLUSTER_HOSTNAME`	`node1`	클러스터 노드 이름
`LIMIT_RESOURCES`	`false`	리소스 제한 해제

자세한 옵션은 공식 문서 weaviate.io/developers/weaviate/config-ref 참고.

6. 실무 팁 & 트러블슈팅

🔥 자주 겪는 문제 1 — 벡터 검색 결과가 비어 있음
원인: 임베딩 모듈이 로드되지 않았거나 API 키 누락.
해결: docker logs weaviate 확인, 모듈이 활성화되었는지 /v1/modules 엔드포인트 호출.

🔥 자주 겪는 문제 2 — 메모리 부족 (OOM)
원인: HNSW 인덱스가 너무 큰 efConstruction.
해결: Class 생성 시 vectorIndexConfig: { efConstruction: 128 } 낮추기.

✅ 실무 팁 — 하이브리드 검색 활용
query.hybrid(query="검색어", alpha=0.5) 로 벡터 + 키워드 가중치 조절. RAG 파이프라인에서 재현율 향상.

✅ 실무 팁 — 멀티모달 인덱싱
multi2vec-clip 모듈로 이미지+텍스트 결합. nearImage 쿼리로 유사 이미지 검색 가능.

7. 참고 자료

📘 공식 문서 — 개념, 튜토리얼, API 레퍼런스
📘 Weaviate 블로그 — RAG, 멀티모달 사례
📘 GitHub 저장소 — 오픈소스 코드, 이슈
📘 퀵스타트 — Docker, Python, JavaScript

⚡ Weaviate 실무 스터디 가이드

📋 목차

1. Weaviate란?

🔢 벡터 검색

🧠 하이브리드 검색

📦 멀티모달

⚙️ 모듈식

2. 왜 써야 하는가?

3. 핵심 개념

4. 퀵스타트

🐳 Docker 설치 (로컬)

🐍 Python 클라이언트 예제

5. 핵심 설정 레퍼런스

6. 실무 팁 & 트러블슈팅

7. 참고 자료