Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Pinecone Python SDK는 벡터 데이터베이스 관리를 위한 클라이언트를 제공하며, 인덱스 생성, 레코드 upsert 및 쿼리 기능을 지원합니다. 이 SDK를 사용하면 파이썬 환경에서 추론 작업을 실행할 수 있으며, 비동기(asyncio) 사용을 위한 기능도 갖추고 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기The Pinecone Python SDK는 Pinecone 벡터 데이터베이스용 클라이언트를 제공합니다. 이를 사용하여 인덱스를 생성하고 관리하며, 레코드를 upsert 및 쿼리하고, 파이썬에서 추론(inference) 작업을 실행할 수 있습니다.
Python 3.10 이상 필요.
9.x 버전에서 업그레이드하는 경우? create와 configure는 spec=/dimension=에서 schema=/deployment=로 이동했습니다. 필드별 매핑은 v10 마이그레이션 가이드를 참조하세요.
pip install pinecone
인덱스는 스키마로 필드를 선언합니다. 스키마를 선언하면 문서 인덱스(document index)가 되며, index.documents를 통해 읽고 쓰게 되고, 각 레코드는 사용자가 직접 이름을 지정한 필드를 가진 JSON 문서입니다.
from pinecone import DenseVectorQuery, Pinecone
pc = Pinecone(api_key="your-api-key") # 또는 생략하고 PINECONE_API_KEY 설정
...
Upsert는 비동기적으로 적용되므로, 문서가 다음 검색에서 즉시 보이지 않을 수 있습니다.
두 가지 다른 데이터 평면 인터페이스(data-plane interfaces)가 존재하며, 인덱스가 생성된 방식에 따라 어떤 것이 적용되는지가 결정됩니다. 사용 중단된 최상위 벡터 인수(top-level vector arguments)로 생성된 인덱스는 index.upsert / index.query를 통해 응답하고, pc.indexes.create_for_model(...)로 생성된 레거시 통합 인덱스(legacy integrated index)는 레거시 Records API: index.upsert_records / index.search가 필요합니다. 텍스트를 임베딩하도록 해야 하는 새 인덱스의 경우, 문서 인덱스에 통합 임베딩(integrated embedding)을 가진 필드를 제공하세요. 전체 그림은 빠른 시작과 문서화의 나머지 부분을 참조하세요.
SDK는 asyncio와 함께 사용할 수 있는 비동기 클라이언트를 제공합니다. 이의 index()는 코루틴(coroutine)이며, 반환되는 핸들(handle)은 컨텍스트 매니저(context manager)입니다:
import asyncio
from pinecone import AsyncPinecone, DenseVectorQuery
...
API 키를 직접 전달하거나 PINECONE_API_KEY 환경 변수를 설정하세요:
특정 제어 평면(control plane) 호스트에 연결하려면:
pc = Pinecone(api_key="your-api-key", host="https://api.pinecone.io")
요청 타임아웃을 초 단위로 설정합니다:
pc = Pinecone(api_key="your-api-key", timeout=30)
PINECONE_DEBUG 환경 변수를 설정하여 디버그 로깅을 활성화합니다:
export PINECONE_DEBUG=1
저장소(repository)를 클론하고, CI에서 사용하는 uv를 사용하여 dev 의존성 그룹을 설치합니다:
uv sync --group dev
uv run pytest tests/unit/ -x -v # 테스트 (tests)
uv run mypy --strict pinecone/ # 타입 검사 (type checking)
uv run ruff check --fix # 린팅 (linting)
...
단위 테스트 스위트(unit suite)는 작업 트리(working tree)를 깨끗하게 유지해야 합니다: git status를 실행했을 때 아무런 변경 사항이 없어야 합니다. 테스트가 실제로 디스크에 파일을 필요로 하는 경우 tmp_path / tmp_path_factory를 사용하십시오.
일부 스위트는 실제 백엔드와 접촉하여 비용이 발생하기 때문에 선택적(opt-in)입니다. tests/integration/test_retry_smoke.py에 있는 라이브 재시도/스로틀 스모크 테스트(live retry/throttle smoke tests)는 PINECONE_API_KEY 외에도 PINECONE_RETRY_SMOKE=1이 필요합니다. 이 테스트들은 재시도 로직, HTTP 전송 계층(HTTP transport), AIMD 적응형 동시성 제한기(AIMD adaptive-concurrency limiter), 또는 배치 업서트 경로(batch-upsert path)를 건드리는 모든 릴리스 전에 실행해야 합니다. 각 모듈은 자체 게이트와 비용을 문서화하고 있습니다.
Apache-2.0. 자세한 내용은 LICENSE를 참조하십시오.