퀵스타트: 클라우드 리소스로 시작하기
퀵스타트: 클라우드 리소스로 시작하기
Weaviate는 AI 애플리케이션을 만드는 데 중심이 되는 오픈소스 벡터 데이터베이스예요. 이 퀵스타트 가이드에서는 컬렉션을 만들고, 유사도(벡터) 검색을 수행하고, **생성 모델로 RAG(검색 증강 생성)**까지 이어서 해볼게요. 마지막으로 Query Agent가 자연어 질문으로 데이터에서 답을 찾는 방법도 함께 확인해요.
출처: 공식문서
준비물: Weaviate Cloud 무료 클러스터
Weaviate Cloud 콘솔에서 무료 클러스터를 만들면 되고, 연결에 필요한 관리자 API 키와 REST 엔드포인트 URL을 발급받아요. 클러스터 준비는 보통 1~3분이 걸리고, 준비가 끝나면 클러스터 이름 옆에 체크표시(✔️)가 나타나요. 클러스터 이름에는 유일성을 위해 임의 접미사가 붙을 수 있어요.
Weaviate Cloud 배포에서는 REST 엔드포인트 URL만 제공하면 클라이언트가 gRPC를 자동으로 구성해요. 로컬 Docker로 시작하고 싶다면 로컬 퀵스타트를 확인하세요.
클라이언트 라이브러리 설치
공식 클라이언트는 Python, JavaScript/TypeScript, Go, Java를 지원해요. Python의 경우 Query Agent를 함께 쓰려면 agents 추가 옵션을 포함해 설치해요.
pip install -U "weaviate-client[agents]"
컬렉션 만들고 데이터 가져오기
Movie 컬렉션을 만들고 세 개의 영화 객체를 가져올게요. 데이터는 Weaviate Embeddings(Weaviate Cloud 사용자를 위한 관리형 임베딩 추론 서비스)로 벡터화돼요. 다른 임베딩 모델 제공자를 써도 괜찮아요.
import weaviate
from weaviate.classes.config import Configure
import os
# Best practice: credentials stored in environment variables
weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]
# Step 1.1: Connect to your Weaviate Cloud instance
with weaviate.connect_to_weaviate_cloud(
cluster_url=weaviate_url,
auth_credentials=weaviate_api_key,
) as client:
# Step 1.2: Create a collection
movies = client.collections.create(
name="Movie",
vector_config=Configure.Vectors.text2vec_weaviate(), # Configure the Weaviate Embeddings vectorizer
)
# Step 1.3: Import three objects
data_objects = [
{"title": "The Matrix", "description": "A computer hacker learns about the true nature of reality and his role in the war against its controllers.", "genre": "Science Fiction"},
{"title": "Spirited Away", "description": "A young girl becomes trapped in a mysterious world of spirits and must find a way to save her parents and return home.", "genre": "Animation"},
{"title": "The Lord of the Rings: The Fellowship of the Ring", "description": "A meek Hobbit and his companions set out on a perilous journey to destroy a powerful ring and save Middle-earth.", "genre": "Fantasy"},
]
movies = client.collections.use("Movie")
movies.data.ingest(data_objects)
print(f"Imported & vectorized {len(movies)} objects into the Movie collection")
의미 검색 (NearText)
의미 기반으로 결과를 찾는 검색을 Weaviate에서는 nearText라고 불러요. sci-fi라는 의미와 가장 가까운 객체 2개(limit)를 찾는 예시예요.
import weaviate
import os, json
weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]
with weaviate.connect_to_weaviate_cloud(
cluster_url=weaviate_url,
auth_credentials=weaviate_api_key,
) as client:
movies = client.collections.use("Movie")
response = movies.query.near_text(
query="sci-fi",
limit=2
)
for obj in response.objects:
print(json.dumps(obj.properties, indent=2)) # Inspect the results
RAG (생성형 검색)
RAG는 사용자 질의와 데이터베이스에서 검색한 데이터를 함께 LLM에 프롬프트로 주는 방식이에요. 이 단계에서는 Claude API 키가 필요하고, 다른 생성 모델 제공자를 써도 됩니다. sci-fi 검색 결과에 Anthropic 생성 모델(generative-anthropic)로 트윗을 생성하도록 요청하는 예시예요.
import os
import weaviate
from weaviate.classes.generate import GenerativeConfig
weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]
anthropic_api_key = os.environ["ANTHROPIC_API_KEY"]
with weaviate.connect_to_weaviate_cloud(
cluster_url=weaviate_url,
auth_credentials=weaviate_api_key,
headers={"X-Anthropic-Api-Key": anthropic_api_key},
) as client:
movies = client.collections.use("Movie")
response = movies.generate.near_text(
query="sci-fi",
limit=1,
grouped_task="Write a tweet with emojis about this movie.",
generative_provider=GenerativeConfig.anthropic( # Configure the Anthropic generative integration
model="claude-haiku-4-5",
),
)
print(response.generative.text) # Inspect the results
Query Agent
Weaviate Query Agent는 Weaviate Cloud에 저장된 데이터를 바탕으로 자연어 질문에 답하는 사전 구축 에이전트 서비스예요. 사용자가 자연어 질문만 던지면 나머지 중간 단계를 모두 처리해요.
import os
import weaviate
from weaviate.agents.query import QueryAgent
weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]
with weaviate.connect_to_weaviate_cloud(
cluster_url=weaviate_url,
auth_credentials=weaviate_api_key,
) as client:
qa = QueryAgent(client=client, collections=["Movie"])
response = qa.search("Find a cool sci-fi movie.", limit=1)
for obj in response.search_results.objects:
print(f"Movie: {obj.properties['title']} - {obj.properties['description']}")