Pinecone

Pinecone Vector Database Skill

Overview

Expert skill for using Pinecone - the leading vector database for AI applications, semantic search, and RAG systems.

API Key

# ~/.claude/.credentials.master.env — впиши САМ КЛЮЧ, не код на Python
PINECONE_API_KEY=ВСТАВЬ_СЮДА_СВОЙ_КЛЮЧ   # https://app.pinecone.io/ → API Keys

Строка PINECONE_API_KEY=os.getenv('PINECONE_API_KEY') ключ НЕ настраивает: это непустое значение, любая проверка if not key сочтёт ключ заданным, запрос уйдёт с этим текстом и вернётся 401 без объяснения. В коде читай ключ через os.getenv('PINECONE_API_KEY'), а в файле должен лежать сам ключ. Файл не подгружается сам: load_dotenv(Path.home()/'.claude'/'.credentials.master.env').

Ключа нет — что тогда

Pinecone — облачный сервис, локального режима у него нет: без PINECONE_API_KEY навык не работает никак, и pinecone.Pinecone(api_key=None) падает на PineconeConfigurationError ещё до первого запроса.

Векторный поиск в паке закрывается и без него:

Раздел «Существующие индексы» ниже описывает индексы конкретного аккаунта — у тебя их не будет, это пример структуры, а не то, к чему можно подключиться.

Существующие индексы

Параметры: Dimension 3072 (OpenAI text-embedding-3-large), Metric cosine, Serverless AWS us-east-1

When to Use Pinecone

Best for:

• Semantic search
• RAG (Retrieval Augmented Generation)
• Recommendation systems
• Similarity matching
• Knowledge base indexing
• Document search
• Image/audio similarity

Advantages:

• Serverless infrastructure
• Integrated embedding models
• Real-time updates
• Metadata filtering
• Hybrid search (semantic + keyword)
• Scales to billions of vectors

Dependencies

pip install pinecone

Basic Usage

Setup Client

from pinecone import Pinecone
import os

pc = Pinecone(api_key=os.getenv('PINECONE_API_KEY'))

Create Serverless Index

def create_index(name: str, dimension: int = 3072, metric: str = "cosine"):
    """
    Create a new serverless index.

    Args:
        name: Index name
        dimension: Vector dimension (3072 — канон живых индексов, text-embedding-3-large;
                   1536 для text-embedding-3-small, 768 for many others)
        metric: "cosine", "euclidean", or "dotproduct"
    """
    from pinecone import ServerlessSpec

    pc.create_index(
        name=name,
        dimension=dimension,
        metric=metric,
        spec=ServerlessSpec(
            cloud="aws",
            region="us-east-1"
        )
    )

    return pc.Index(name)

# Usage (3072 = канон живых индексов проекта)
index = create_index("my-knowledge-base", dimension=3072)

Create Index with Integrated Embeddings

def create_index_with_embeddings(name: str, embed_model: str = "multilingual-e5-large"):
    """
    Create index with integrated embedding model.

    Models:
        - multilingual-e5-large (1024 dim, 100+ languages)
        - llama-text-embed-v2 (1024 dim)
        - pinecone-sparse-english-v0 (sparse)
    """
    from pinecone import ServerlessSpec

    pc.create_index(
        name=name,
        dimension=1024,
        metric="cosine",
        spec=ServerlessSpec(cloud="aws", region="us-east-1"),
        embedding={
            "model": embed_model,
            "field_map": {"text": "text"}
        }
    )

    return pc.Index(name)

Upsert Vectors

def upsert_vectors(index_name: str, vectors: list):
    """
    Upsert vectors with metadata.

    vectors format:
        [{"id": "doc1", "values": [...], "metadata": {...}}, ...]
    """
    index = pc.Index(index_name)

    index.upsert(
        vectors=vectors,
        namespace="default"
    )

    return len(vectors)

# Example with embeddings
import openai

def embed_and_upsert(index_name: str, texts: list, ids: list, metadata: list = None):
    """Embed texts and upsert to Pinecone."""

    # Get embeddings from OpenAI
    client = openai.OpenAI()
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=texts
    )

    vectors = []
    for i, embedding in enumerate(response.data):
        vectors.append({
            "id": ids[i],
            "values": embedding.embedding,
            "metadata": metadata[i] if metadata else {"text": texts[i]}
        })

    index = pc.Index(index_name)
    index.upsert(vectors=vectors)

    return len(vectors)

Query (Semantic Search)

def query_index(index_name: str, query_vector: list, top_k: int = 10,
                filter: dict = None, include_metadata: bool = True):
    """
    Query index for similar vectors.

    Args:
        query_vector: Query embedding
        top_k: Number of results
        filter: Metadata filter
        include_metadata: Include metadata in results
    """
    index = pc.Index(index_name)

    results = index.query(
        vector=query_vector,
        top_k=top_k,
        filter=filter,
        include_metadata=include_metadata,
        namespace="default"
    )

    return results.matches

# Example with text query
def search_similar(index_name: str, query_text: str, top_k: int = 10):
    """Search for similar documents by text."""

    # Get query embedding
    client = openai.OpenAI()
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=[query_text]
    )
    query_vector = response.data[0].embedding

    return query_index(index_name, query_vector, top_k)

Query with Integrated Embeddings

def search_text(index_name: str, query: str, top_k: int = 10):
    """
    Search using integrated embeddings (no external embedding needed).

    Works with indexes created with embedding parameter.
    """
    index = pc.Index(index_name)

    results = index.query(
        data=query,  # Text query, not vector
        top_k=top_k,
        include_metadata=True
    )

    return results.matches

Metadata Filtering

def search_with_filter(index_name: str, query_vector: list, filters: dict):
    """
    Search with metadata filters.

    Filter examples:
        {"category": "tech"}
        {"price": {"$lt": 100}}
        {"tags": {"$in": ["python", "ai"]}}
        {"$and": [{"category": "tech"}, {"status": "active"}]}
    """
    index = pc.Index(index_name)

    results = index.query(
        vector=query_vector,
        top_k=10,
        filter=filters,
        include_metadata=True
    )

    return results.matches

# Filter operators:
# $eq - equal
# $ne - not equal
# $gt, $gte - greater than
# $lt, $lte - less than
# $in, $nin - in/not in array
# $and, $or - logical operators

Hybrid Search (Semantic + Keyword)

def hybrid_search(index_name: str, query: str, top_k: int = 10, alpha: float = 0.5):
    """
    Hybrid search combining semantic and keyword search.

    alpha: Weight for semantic (1.0 = all semantic, 0.0 = all keyword)
    """
    index = pc.Index(index_name)

    # Requires index with both dense and sparse embeddings
    results = index.query(
        data=query,
        top_k=top_k,
        include_metadata=True,
        sparse_vector=True  # Enable sparse matching
    )

    return results.matches

Fetch Vectors by ID

def fetch_by_ids(index_name: str, ids: list):
    """Fetch specific vectors by IDs."""

    index = pc.Index(index_name)

    results = index.fetch(ids=ids, namespace="default")

    return results.vectors

Update Metadata

def update_metadata(index_name: str, id: str, metadata: dict):
    """Update metadata for a vector."""

    index = pc.Index(index_name)

    index.update(
        id=id,
        set_metadata=metadata,
        namespace="default"
    )

Delete Vectors

def delete_vectors(index_name: str, ids: list = None, filter: dict = None,
                   delete_all: bool = False):
    """
    Delete vectors.

    Can delete by:
        - IDs
        - Metadata filter
        - All (delete_all=True)
    """
    index = pc.Index(index_name)

    if delete_all:
        index.delete(delete_all=True, namespace="default")
    elif filter:
        index.delete(filter=filter, namespace="default")
    elif ids:
        index.delete(ids=ids, namespace="default")

Index Statistics

def get_stats(index_name: str):
    """Get index statistics."""

    index = pc.Index(index_name)
    stats = index.describe_index_stats()

    return {
        "total_vector_count": stats.total_vector_count,
        "dimension": stats.dimension,
        "namespaces": stats.namespaces
    }

List Indexes

def list_indexes():
    """List all indexes."""

    return [index.name for index in pc.list_indexes()]

Namespaces

Namespaces allow partitioning data within an index:

# Upsert to specific namespace
index.upsert(vectors=vectors, namespace="documents")
index.upsert(vectors=vectors, namespace="images")

# Query specific namespace
results = index.query(vector=query, namespace="documents")

# Delete from namespace
index.delete(ids=ids, namespace="documents")

Embedding Models

API Pricing

Quick Reference

Tips

1. Dimension - должен совпадать с моделью embeddings
2. Namespaces - для разделения данных в одном индексе
3. Metadata - храни текст для retrieval
4. Batch upsert - до 100 векторов за раз
5. Integrated embeddings - не нужен внешний API
6. Hybrid search - лучше для text retrieval
7. Cosine - лучший metric для normalized embeddings