Python 클라이언트

Python 클라이언트

Weaviate Python 클라이언트의 공식 문서예요. 현재 최신 Python 클라이언트 버전은 v4.23.0이고, 저장소는 weaviate/weaviate-python-client, 레퍼런스 매뉴얼은 docstrings에서 볼 수 있어요. 이 페이지는 Python 클라이언트 v4 릴리스를 폭넓게 다뤄요.

출처: 공식문서

설치

Python 클라이언트는 Python 3.8+에서 개발·테스트되며 PyPI에서 설치할 수 있어요.

pip install -U weaviate-client

베타 버전을 설치하려면:

pip install --pre -U "weaviate-client==4.*"

Weaviate 버전 호환성

v4 Python 클라이언트는 Weaviate v1.23.7 이상을 요구해요. 일반적으로 최신 Python 클라이언트와 최신 Weaviate Database 버전을 함께 쓰는 걸 권장해요. 클라이언트는 gRPC를 사용하므로 노출된 포트에 50051이 포함되어야 해요 (8080:8080, 50051:50051).

Query Agent

Query Agent를 쓰려면 agents 추가 옵션이 포함된 클라이언트를 설치하면 돼요.

pip install -U "weaviate-client[agents]"

동기·비동기 API

Python 클라이언트는 기본적으로 WeaviateClient 클래스를 통한 동기 API를 제공해요. weaviate-client v4.7.0부터는 WeaviateAsyncClient 클래스를 통한 비동기 API도 쓸 수 있어요. 자세한 내용은 비동기 클라이언트 API 페이지를 참고하세요.

import weaviate
from weaviate.classes.config import Configure

client = weaviate.connect_to_local()

Vectorizer API 변경 사항 (v4.16.0)

v4.16.0부터 컬렉션 생성 시 벡터라이저 구성 API에 몇 가지 변경이 있어요. 특히 AutoSchema와 함께 쓸 때 .Vectors.text2vec_xxx 동작이 영향을 받을 수 있어요. Configure.NamedVectors는 Configure.Vectors·Configure.MultiVectors로, Configure.NamedVectors.none·Configure.Vectorizer.none은 Configure.Vectors.self_provided·Configure.MultiVectors.self_provided로 대체됐어요.

진행 중인 client.batch 관련해서는 client.batch.dynamic(), client.batch.fixed_size(), client.batch.rate_limit() 세 가지 배칭 스타일의 알고리즘이 도입됐어요. client.batch.dynamic()이 기존 client.batch의 드롭인 대체품이며, 기존 방식은 deprecated되어 이후 릴리스에서 제거될 예정이에요.

v3 클라이언트 지원 종료

Weaviate Python 클라이언트 v3는 deprecated되어 더 이상 쓰지 않아야 해요. v3 문서가 필요하다면 문서 아카이브를, v3에서 v4로 마이그레이션한다면 관련 마이그레이션 문서를 확인하세요.

릴리스

릴리스는 위 표와 같이 Weaviate Database 버전과 함께 매핑돼요. 예를 들어 Weaviate Database 1.39.x(2026-08-04 출시)에는 Python 4.23.x가 대응돼요. 각 언어 클라이언트의 최신 릴리스는 GitHub 저장소(위 링크)에서 확인할 수 있어요.

더 알아보기 (Learn more)