Weaviate Cloud에 연결

Weaviate Cloud에 연결 (Connect to a cluster)

Weaviate Cloud(WCD) 클러스터에 연결하는 방법은 크게 둘로 나뉘어요. API로 프로그래매틱하게 연결하거나, 웹 콘솔에 로그인해 내장 도구로 데이터를 다루는 방식이에요. 아래는 RBAC(Role-Based Access Control)가 활성화된 클러스터 기준의 안내예요. v1.30 이상 신규 클러스터는 RBAC가 기본 활성화돼요.

출처: Weaviate Cloud에 연결

API 키와 REST 엔드포인트 가져오기

WCD 클러스터에 연결하려면 인증에 API 키와 REST 엔드포인트 URL이 필요해요. 기존 키가 없다면 만들어야 하는데, 콘솔의 API keys 섹션에서 새 키를 생성하면 돼요.

REST vs gRPC 엔드포인트: 공식 Weaviate 클라이언트 라이브러리를 쓰면 REST Endpoint와 API 키로 인증하고, 클라이언트가 gRPC 엔드포인트를 자동으로 추론해 더 빠른 gRPC 프로토콜을 사용할 수 있을 때 써요. gRPC-Web 인터페이스에 접근할 땐 gRPC Endpoint가 아니라 REST Endpoint URL을 써야 해요 — gRPC-Web이 REST 포트에서 서빙되기 때문이에요.

환경 변수

API 키와 Weaviate URL을 클라이언트 코드에 하드코딩하지 말고 환경 변수나 유사한 보안 기법으로 전달하세요.

export WEAVIATE_URL="replaceThisWithYourRESTEndpointURL"
export WEAVIATE_API_KEY="replaceThisWithYourAPIKey"

연결 예제

REST Endpoint URL과 Admin API 키로 연결하는 Python 예제예요.

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

Weaviate Cloud 콘솔 열기

WCD 콘솔은 이메일 주소와 비밀번호로 인증해요(계정 생성 시 비밀번호를 만듦). 로그인 후에는 데이터를 다룰 내장 도구가 있어요.

  • Explorer tool: 쿼리를 작성하지 않고 컬렉션을 탐색하고 키워드·의미·하이브리드·집계 검색 실행
  • Collections tool: 컬렉션 생성·구성·삭제
  • Query Agent: 데이터에 대해 자연어 질문에 답변

문제 해결

비밀번호 재설정

WCD 로그인 페이지에서 로그인 버튼 → Forgot Password → 이메일의 재설정 메일 확인 → 링크 클릭해 재설정. 링크는 5분간만 유효해요.

연결 타임아웃

새 Python 클라이언트는 Weaviate Cloud에 연결할 때 gRPC 프로토콜을 사용해요. 성능은 좋지만 네트워크 속도에 민감해서, 타임아웃 에러가 나면 연결 코드의 타임아웃 값을 늘려보세요.

from weaviate.classes.init import AdditionalConfig, Timeout, Auth
import weaviate

# Set these environment variables
URL = os.getenv("WEAVIATE_URL")
APIKEY = os.getenv("WEAVIATE_API_KEY")

# Connect to Weaviate Cloud
client = weaviate.connect_to_weaviate_cloud(
    cluster_url=URL,
    auth_credentials=Auth.api_key(APIKEY),
    additional_config=AdditionalConfig(timeout=Timeout(init=10)),
)

# Check connection
client.is_ready()

또는 초기 연결 확인을 건너뛰는 방법도 있어요.

import weaviate
from weaviate.classes.init import Auth

# Set these environment variables
URL = os.getenv("WEAVIATE_URL")
APIKEY = os.getenv("WEAVIATE_API_KEY")

# Connect to Weaviate Cloud
client = weaviate.connect_to_weaviate_cloud(
    cluster_url=URL,
    auth_credentials=Auth.api_key(APIKEY),
    skip_init_checks=True,
)

# Check connection
client.is_ready()

gRPC health check 오류

증상: Shared Cloud 클러스터 업데이트 후 gRPC가 health check 오류를 반환해요.

weaviate.exceptions.WeaviateGRPCUnavailableError: gRPC health check could not be completed.

해결: 클러스터 URL이 올바른지 확인하고 필요하면 갱신해요. Shared Cloud 클러스터가 업데이트되면 클러스터 URL이 약간 바뀔 수 있어요. WCD가 옛 URL을 계속 라우팅해서 일부 연결은 동작하지만, 새 gRPC URL과 옛 HTTP URL이 달라 gRPC를 요구하는 연결은 실패해요. 콘솔의 세부 패널에서 클러스터 URL을 확인하세요. Cluster URL에 grpc- 프리픽스를 붙이면 Cluster URL과 Cluster gRPC URL이 일치해야 해요. 앱의 연결 주소와 비교해보고, 새 URL에 .c0.region 같은 추가 서브도메인이 있으면 앱 연결 코드를 새 Cluster URL로 갱신하세요.

더 알아보기 (Learn more)