pinecone

Pinecone Python SDK

95 个版本 Python >=3.10

安装

pip install pinecone

poetry add pinecone

pipenv install pinecone

conda install pinecone

描述

Pinecone Python SDK

The Pinecone Python SDK provides a client for the Pinecone vector database. Use it to create and manage indexes, upsert and query vectors, and run inference operations from Python.

Requires Python 3.10+.

Installation

pip install pinecone

For development dependencies (testing, type checking, linting):

pip install pinecone[dev]

Quick start

from pinecone import Pinecone, ServerlessSpec

# Initialize the client
pc = Pinecone(api_key="your-api-key")

# Create a serverless index
pc.indexes.create(
    name="movie-recommendations",
    dimension=1536,
    metric="cosine",
    spec=ServerlessSpec(cloud="aws", region="us-east-1"),
)

# Connect to the index
index = pc.index("movie-recommendations")

# Upsert vectors
index.upsert(
    vectors=[
        ("movie-42", [0.012, -0.087, 0.153]),  # 1536-dim embedding
        ("movie-87", [0.045, 0.021, -0.064]),  # 1536-dim embedding
    ],
    namespace="movies-en",
    batch_size=100,  # split larger inputs into parallel batches automatically
)

# Query for similar vectors
results = index.query(
    vector=[0.012, -0.087, 0.153],  # 1536-dim embedding
    top_k=10,
    namespace="movies-en",
)

for match in results.matches:
    print(f"{match.id}: {match.score:.4f}")

Async usage

The SDK provides an async client for use with asyncio:

import asyncio
from pinecone import AsyncPinecone

async def main():
    async with AsyncPinecone(api_key="your-api-key") as pc:
        desc = await pc.indexes.describe("movie-recommendations")
        index = await pc.index(host=desc.host)
        async with index:
            results = await index.query(
                vector=[0.012, -0.087, 0.153],  # 1536-dim vector
                top_k=10,
                namespace="movies-en",
            )
            for match in results.matches:
                print(f"{match.id}: {match.score:.4f}")

asyncio.run(main())

Configuration

API key

Pass the API key directly or set the PINECONE_API_KEY environment variable:

from pinecone import Pinecone

# Explicit API key
pc = Pinecone(api_key="your-api-key")

# From environment variable (PINECONE_API_KEY)
pc = Pinecone()

Custom host

Connect to a specific control plane host:

pc = Pinecone(api_key="your-api-key", host="https://api.pinecone.io")

Timeout

Configure request timeouts in seconds:

pc = Pinecone(api_key="your-api-key", timeout=30)

Debug logging

Enable debug logging by setting the PINECONE_DEBUG environment variable:

export PINECONE_DEBUG=1

Development

Setup

Clone the repository and install dependencies with uv:

uv sync

Tests

uv run pytest tests/unit/ -x -v

Retry/throttle smoke tests (opt-in)

A suite of live-API smoke tests verifies that the retry stack and AIMD adaptive concurrency hold up against real Pinecone rate limits. These are not run in normal CI because they require real credentials, create a live serverless index, and take 1–3 minutes per run.

Required environment variables:

Variable	Description
`PINECONE_API_KEY`	A valid Pinecone API key
`PINECONE_RETRY_SMOKE`	Set to `1` to enable the smoke tests

Running the smoke tests:

PINECONE_API_KEY=your-api-key PINECONE_RETRY_SMOKE=1 \
  uv run pytest tests/integration/test_retry_smoke.py -x -v -s

Cost: Each run creates three serverless indexes, upserts ~100K vectors per index, then deletes all indexes. Total cost is under $3 per run.

When to run: Before any release that touches retry logic, HTTP transport, the AIMD adaptive-concurrency limiter (pinecone._internal.adaptive), or the batch-upsert path. The unit tests mock HTTP responses; this test catches divergence between the synthetic model and real API behavior (e.g., 503 instead of 429).

Type checking

uv run mypy --strict pinecone/

Linting and formatting

uv run ruff check --fix
uv run ruff format

License

Apache-2.0. See LICENSE for details.

分类

Development Status :: 5 - Production/Stable Intended Audience :: Developers Intended Audience :: Information Technology Intended Audience :: Science/Research Intended Audience :: System Administrators Operating System :: OS Independent Programming Language :: Python :: 3.10 Programming Language :: Python :: 3.11 Programming Language :: Python :: 3.12 Programming Language :: Python :: 3.13 Topic :: Database Topic :: Software Development Topic :: Software Development :: Libraries Topic :: Software Development :: Libraries :: Application Frameworks Topic :: Software Development :: Libraries :: Python Modules

版本列表

9.1.0 2026-06-03

9.0.1 2026-05-19

9.0.0 2026-05-04

9.0.1rc1 2026-05-18

9.0.0rc2 2026-05-04

9.0.0rc1 2026-05-04

8.2.0rc2 2026-05-04

8.2.0rc1 2026-05-04

8.1.2 2026-04-08

8.1.1 2026-04-02

8.1.0 2026-02-19

8.1.0rc1 2026-02-17

8.0.1 2026-02-11

8.0.0 2025-11-18

7.3.1.dev8 2025-10-01

7.3.1.dev7 2025-10-01

7.3.1.dev6 2025-10-01

7.3.1.dev5 2025-10-01

7.3.1.dev4 2025-09-30

7.3.1.dev3 2025-09-25

7.3.1.dev2 2025-09-24

7.3.1.dev1 2025-09-24

7.3.0 2025-06-27

7.3.1a1 2025-10-03

7.2.0 2025-06-18

7.1.0 2025-06-16

7.1.0rc1 2025-06-16

7.0.2 2025-05-28

7.0.2.dev1 2025-05-27

7.0.1 2025-05-21

7.0.1.dev1 2025-05-21

7.0.0 2025-05-20

7.0.0.dev3 2025-05-16

7.0.0.dev2 2025-05-15

7.0.0.dev1 2025-05-15

6.0.3.dev1 2025-05-21

6.0.2 2025-03-13

6.0.2.dev1 2025-03-13

6.0.1 2025-02-10

6.0.1.dev1 2025-02-10

6.0.0 2025-02-07

6.0.0.dev9 2025-02-03

6.0.0.dev8 2025-01-31

6.0.0.dev7 2025-01-30

6.0.0.dev6 2024-12-17

6.0.0.dev5 2024-12-17

6.0.0.dev4 2024-12-13

6.0.0.dev3 2024-10-25

6.0.0.dev2 2024-10-25

6.0.0.dev1 2024-10-18

6.0.0rc2 2024-10-22

6.0.0rc1 2024-10-21

5.4.2 2024-12-09

5.4.1 2024-11-26

5.4.0 2024-11-13

5.4.0.dev5 2024-11-13

5.4.0.dev4 2024-10-25

5.4.0.dev3 2024-10-25

5.4.0.dev2 2024-10-25

5.4.0.dev1 2024-10-22

5.3.1 2024-09-19

5.3.0 2024-09-18

5.2.0 2024-09-17

5.2.0.dev9 2024-09-17

5.2.0.dev8 2024-09-17

5.2.0.dev7 2024-09-09

5.2.0.dev6 2024-09-06

5.2.0.dev5 2024-09-05

5.2.0.dev4 2024-09-05

5.2.0.dev3 2024-09-05

5.2.0.dev2 2024-08-30

5.2.0.dev10 2024-09-17

5.2.0.dev1 2024-08-30

5.2.0.dev0 2024-08-30

5.1.0 2024-08-29

5.1.0.dev1 2024-08-29

5.1.0rc1 2024-08-28

5.0.1 2024-08-12

5.0.0 2024-07-31

4.1.2 2024-07-31

4.1.1 2024-07-31

4.1.0 2024-07-31

4.0.0 2024-05-03

3.2.2 2024-07-31

3.2.1 2024-07-31

3.2.0 2024-07-31

3.1.0 2024-07-31

3.0.3 2024-07-31

3.0.2 2024-07-31

3.0.1 2024-07-31

3.0.0 2024-07-31

2.2.4 2024-07-31

2.2.3 2024-07-31

2.2.2 2024-07-31

0.1.0