Weaviate Cloud Quickstart

Weaviate Cloud Quickstart

이 퀵스타트는 Weaviate Cloud와 Weaviate Embeddings를 조합해 Weaviate 인스턴스 구성 → 데이터 추가·벡터화 → 의미 검색과 RAG까지 약 30분 만에 해보는 실습이에요. 코드 예제는 자기 완결적이라 그대로 복사해 붙여 넣고 실행하면 돼요.

출처: Weaviate Cloud Quickstart

요구 사항

  • Weaviate Cloud 계정
  • 마지막 RAG 단계를 위해 OpenAI 계정과 OpenAI API 키. 다른 모델 제공자도 사용할 수 있어요.

Step 1: Weaviate Cloud 설정

1.1 클러스터 생성

Weaviate는 두 가지 클러스터 옵션을 제공해요.

  • Free 클러스터: 영구 무료, 학습·소규모 프로젝트에 적합
  • Shared Cloud 클러스터: 영구 프로덕션 환경

Weaviate Cloud 콘솔에서 무료 클러스터를 생성해요.

참고: 프로비저닝은 보통 1~3분 걸려요. 준비되면 클러스터 이름 옆에 체크표시(✔️)가 표시돼요. 고유성을 위해 클러스터 이름에 임의 접미사가 붙을 수 있어요.

팁 — 최신 Weaviate 버전 사용하기: 가능하면 최신 버전을 쓰세요. 신규 릴리스에는 최신 기능, 성능 개선, 보안 업데이트가 포함돼요.

1.2 클라이언트 라이브러리 설치

클라우드 콘솔에도 질의 인터페이스가 있지만 대부분의 상호작용은 Weaviate 클라이언트를 통해 이루어져요. Python, JavaScript/TypeScript, Go, Java, C# 클라이언트가 제공돼요.

Python v4 클라이언트 설치는 pip로:

pip install -U weaviate-client

1.3 Weaviate Cloud 인스턴스에 연결

연결에는 REST Endpoint URL과 Administrator API Key가 필요해요. 둘 다 WCD 콘솔에서 확인할 수 있어요.

참고: Weaviate v1.30 이상으로 생성한 신규 클러스터는 RBAC(Role-Based Access Control)가 기본 활성화돼요. 이 클러스터에는 API 키가 미리 없고, 직접 키를 만들어 역할(admin, viewer 또는 커스텀 역할)을 할당해야 해요.

REST vs gRPC 엔드포인트: Weaviate는 REST와 gRPC 프로토콜을 모두 지원해요. Weaviate Cloud 배포에서는 REST 엔드포인트 URL만 제공하면 되고, 클라이언트가 gRPC를 자동 구성해요.

연결 예제 — 클러스터 상태(준비 여부)를 확인하는 기본 연산:

import weaviate
from weaviate.classes.init import Auth
import os

# Best practice: store your credentials in environment variables
weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,
    auth_credentials=Auth.api_key(weaviate_api_key),
)

print(client.is_ready())  # Should print: `True`
client.close()  # Free up resources

Step 2: 데이터베이스 채우기

2.1 컬렉션 정의

아래 예제는 Question이라는 컬렉션을 만들되, 수집·질의 시 벡터를 생성하도록 Weaviate Embeddings 모델 통합을 구성해요.

import weaviate
from weaviate.classes.init import Auth
from weaviate.classes.config import Configure
import os

weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,  # Replace with your Weaviate Cloud URL
    auth_credentials=Auth.api_key(weaviate_api_key),  # Replace with your Weaviate Cloud key
)

questions = client.collections.create(
    name="Question",
    vector_config=Configure.Vectors.text2vec_weaviate(),  # Configure the Weaviate Embeddings integration
)

client.close()  # Free up resources

참고 — 벡터라이저 설정 API 변경: Weaviate Python 클라이언트 v4.16.0, JS/TS 클라이언트 v3.8.0부터 벡터라이저 설정 API가 바뀌었어요. 최신 클라이언트로 업데이트하고 새 API로 코드를 마이그레이션해야 해요. 또한 Python 클라이언트 4.16.0~4.16.3에서 Configure.Vectors.text2vec_xxx()는 프로퍼티 없이 vectorize_collection_name=True도 아니면 에러를 내므로 4.16.4+로 올려야 해요.

2.2 데이터 로드

이제 컬렉션에 데이터를 추가해요. 객체를 로드해 배치 임포트로 Question 컬렉션에 넣는 예제예요.

배치 임포트: 객체를 요청당 하나씩 보내는 대신 그룹으로 보내므로 대량 데이터에 가장 효율적이에요. 서버가 다음에 보낼 데이터 양을 알려주는 서버 측 배칭을 포함한 방법은 Batch import 가이드에서 확인할 수 있어요. 임포트는 실패한 객체가 있으면 보고하므로, 잘못된 데이터나 잘못 구성된 모델 제공자를 잡으려면 코드에서 실패를 확인하는 걸 권장해요.

import weaviate
from weaviate.classes.init import Auth
import requests, json, os

weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,                                    # Replace with your Weaviate Cloud URL
    auth_credentials=Auth.api_key(weaviate_api_key),             # Replace with your Weaviate Cloud key
)

resp = requests.get(
    "https://raw.githubusercontent.com/weaviate-tutorials/quickstart/main/data/jeopardy_tiny.json"
)
data = json.loads(resp.text)

questions = client.collections.use("Question")

result = questions.data.ingest(
    [
        {
            "answer": d["Answer"],
            "question": d["Question"],
            "category": d["Category"],
        }
        for d in data
    ]
)

# `errors` holds one entry per failed object, keyed by its position in the input
if result.errors:
    print(f"Number of failed imports: {len(result.errors)}")
    for index, error in result.errors.items():
        print(f"Failed object at index {index}: {error.message}")

client.close()  # Free up resources

data.ingest()는 BatchObjectReturn을 반환해요. 실패 확인은 result.errors를 읽으면 되고, 입력에서 실패한 객체 위치를 키로 갖고 있어요.

Step 3: 데이터 질의

의미 검색은 단어 자체가 아니라 의미가 가장 유사한 결과를 찾아요. Weaviate에서는 이를 nearText라고 불러요. 아래 예제는 biology와 의미가 가장 유사한 객체 2개를 찾아요.

import weaviate
from weaviate.classes.init import Auth
import os, json

weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,                                    # Replace with your Weaviate Cloud URL
    auth_credentials=Auth.api_key(weaviate_api_key),             # Replace with your Weaviate Cloud key
)

questions = client.collections.use("Question")

response = questions.query.near_text(
    query="biology",
    limit=2
)

for obj in response.objects:
    print(json.dumps(obj.properties, indent=2))

client.close()  # Free up resources

응답을 자세히 보면 biology라는 단어가 어디에도 없다는 걸 알 수 있어요. 그런데도 생물학 관련 항목이 반환돼요. 이건 의미를 포착하는 벡터 임베딩 덕분이에요. 의미 검색은 내부적으로 벡터(임베딩)로 구동되죠.

벡터는 어디서 왔을까?: Weaviate Embeddings 서비스가 임포트 시 각 객체의 임베딩을 생성했어요. 질의 시에도 biology를 벡터로 변환했어요. 참고로 직접 벡터를 제공하는 것도 가능해요(Bring Your Own Vectors).

3.2 검색 증강 생성 (RAG)

검색 증강 생성(RAG)은 생성형 AI 모델(LLM)의 힘과 데이터베이스의 최신 사실성(truthfulness)을 결합해요. RAG는 사용자 질의 + 데이터베이스에서 검색한 데이터를 LLM 프롬프트로 조합해 동작해요.

아래 예제는 앞선 검색(biology)에 트윗 생성 프롬프트를 결합해요.

import os
import weaviate
from weaviate.classes.init import Auth
from weaviate.classes.generate import GenerativeConfig

weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]
openai_api_key = os.environ["OPENAI_API_KEY"]

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,  # Replace with your Weaviate Cloud URL
    auth_credentials=Auth.api_key(
        weaviate_api_key
    ),  # Replace with your Weaviate Cloud key
    headers={"X-OpenAI-Api-Key": openai_api_key},  # Replace with your OpenAI API key
)

questions = client.collections.use("Question")

response = questions.generate.near_text(
    query="biology",
    limit=2,
    grouped_task="Write a tweet with emojis about these facts.",
    generative_provider=GenerativeConfig.openai(),  # Configure the OpenAI generative integration for RAG
)

print(response.generative.text)  # Inspect the generated text

client.close()  # Free up resources

헤더의 OpenAI API 키: 이 코드는 OpenAI API 키를 위한 추가 헤더를 포함해요. Weaviate는 이 키로 OpenAI 생성형 모델에 접근해 RAG를 수행해요.

생성된 응답은 "새롭지만 친숙해요" — 앞서 의미 검색에서 본 DNA·species 항목을 활용한 결과죠. RAG의 힘은 내 데이터를 변형하는 데 있어요. Weaviate는 몇 줄의 코드로 검색과 생성을 결합하게 해줘요.

다음 단계

  • 클러스터 생성: 프로덕션용 영구 인스턴스가 필요하면 Shared Cloud 클러스터 생성
  • Weaviate Database 문서: AI 프로젝트 구축에 관한 Weaviate 문서 확인

더 알아보기 (Learn more)