Pinecone

Управляемая векторная БД для продакшн RAG и поиска.

Метаданные навыка

Справочник: полный SKILL.md

Pinecone — управляемая векторная база данных

Векторная база данных для промышленных AI-приложений.

Когда использовать Pinecone

Используйте, если:

• Нужна управляемая serverless-векторная база данных
• Продакшн-приложения на RAG
• Требуется автоскейлинг
• Критична низкая задержка (<100ms)
• Не хочется управлять инфраструктурой
• Нужен гибридный поиск (dense + sparse векторы)

Показатели:

• Полностью управляемый SaaS
• Автоматически масштабируется до миллиардов векторов
• p95 задержка <100ms
• SLA на аптайм 99,9%

Вместо этого используйте альтернативы:

• Chroma: self-hosted, open-source
• FAISS: офлайн, чистый поиск по сходству
• Weaviate: self-hosted, больше возможностей

Быстрый старт

Установка

pip install pinecone

Примечание: старый пакет pinecone-client устарел. Ставьте pinecone (v5+; актуальная версия 9.x). Импорт остаётся прежним — from pinecone import Pinecone.

Базовое использование

from pinecone import Pinecone, ServerlessSpec

# Инициализация
pc = Pinecone(api_key="your-api-key")

# Создание индекса
pc.create_index(
    name="my-index",
    dimension=1536,  # Должно совпадать с размерностью эмбеддинга
    metric="cosine",  # или "euclidean", "dotproduct"
    spec=ServerlessSpec(cloud="aws", region="us-east-1")
)

# Подключение к индексу
index = pc.Index("my-index")

# Добавление векторов (upsert)
index.upsert(vectors=[
    {"id": "vec1", "values": [0.1, 0.2, ...], "metadata": {"category": "A"}},
    {"id": "vec2", "values": [0.3, 0.4, ...], "metadata": {"category": "B"}}
])

# Запрос
results = index.query(
    vector=[0.1, 0.2, ...],
    top_k=5,
    include_metadata=True
)

print(results["matches"])

Основные операции

Создание индекса

# Serverless (рекомендуется)
pc.create_index(
    name="my-index",
    dimension=1536,
    metric="cosine",
    spec=ServerlessSpec(
        cloud="aws",         # или "gcp", "azure"
        region="us-east-1"
    )
)

# На основе подов (для стабильной производительности)
from pinecone import PodSpec

pc.create_index(
    name="my-index",
    dimension=1536,
    metric="cosine",
    spec=PodSpec(
        environment="us-east1-gcp",
        pod_type="p1.x1"
    )
)

Добавление векторов (upsert)

# Одиночное добавление
index.upsert(vectors=[
    {
        "id": "doc1",
        "values": [0.1, 0.2, ...],  # 1536 измерений
        "metadata": {
            "text": "Document content",
            "category": "tutorial",
            "timestamp": "2025-01-01"
        }
    }
])

# Пакетное добавление (рекомендуется)
vectors = [
    {"id": f"vec{i}", "values": embedding, "metadata": metadata}
    for i, (embedding, metadata) in enumerate(zip(embeddings, metadatas))
]

index.upsert(vectors=vectors, batch_size=100)

Запрос векторов

# Базовый запрос
results = index.query(
    vector=[0.1, 0.2, ...],
    top_k=10,
    include_metadata=True,
    include_values=False
)

# С фильтрацией по метаданным
results = index.query(
    vector=[0.1, 0.2, ...],
    top_k=5,
    filter={"category": {"$eq": "tutorial"}}
)

# Запрос по неймспейсу
results = index.query(
    vector=[0.1, 0.2, ...],
    top_k=5,
    namespace="production"
)

# Обработка результатов
for match in results["matches"]:
    print(f"ID: {match['id']}")
    print(f"Score: {match['score']}")
    print(f"Metadata: {match['metadata']}")

Фильтрация по метаданным

# Точное совпадение
filter = {"category": "tutorial"}

# Сравнение
filter = {"price": {"$gte": 100}}  # $gt, $gte, $lt, $lte, $ne

# Логические операторы
filter = {
    "$and": [
        {"category": "tutorial"},
        {"difficulty": {"$lte": 3}}
    ]
}  # Также: $or

# Оператор In
filter = {"tags": {"$in": ["python", "ml"]}}

Неймспейсы

# Разделение данных по неймспейсам
index.upsert(
    vectors=[{"id": "vec1", "values": [...]}],
    namespace="user-123"
)

# Запрос по конкретному неймспейсу
results = index.query(
    vector=[...],
    namespace="user-123",
    top_k=5
)

# Список неймспейсов
stats = index.describe_index_stats()
print(stats['namespaces'])

Гибридный поиск (dense + sparse)

# Добавление с sparse-векторами
index.upsert(vectors=[
    {
        "id": "doc1",
        "values": [0.1, 0.2, ...],  # Dense-вектор
        "sparse_values": {
            "indices": [10, 45, 123],  # ID токенов
            "values": [0.5, 0.3, 0.8]   # TF-IDF оценки
        },
        "metadata": {"text": "..."}
    }
])

# Гибридный запрос
# ПРИМЕЧАНИЕ: index.query() НЕ принимает параметр `alpha`. Pinecone хранит
# единый sparse-dense вектор, поэтому взвешивание нужно применять заранее —
# масштабированием векторов запроса перед отправкой. Используйте вспомогательную
# функцию hybrid_score_norm ниже (alpha * dense + (1 - alpha) * sparse; alpha=1 → чистый dense, 0 → чистый sparse).

def hybrid_score_norm(dense, sparse, alpha: float):
    """Масштабирует dense/sparse векторы запроса для взвешенного гибридного поиска."""
    if not 0 <= alpha <= 1:
        raise ValueError("alpha must be between 0 and 1")
    scaled_sparse = {
        "indices": sparse["indices"],
        "values": [v * (1 - alpha) for v in sparse["values"]],
    }
    return [v * alpha for v in dense], scaled_sparse

hdense, hsparse = hybrid_score_norm(
    dense=[0.1, 0.2, ...],
    sparse={"indices": [10, 45], "values": [0.5, 0.3]},
    alpha=0.5,  # 0=sparse, 1=dense, 0.5=баланс
)

results = index.query(
    vector=hdense,
    sparse_vector=hsparse,
    top_k=5,
)

Интеграция с LangChain

from langchain_pinecone import PineconeVectorStore
from langchain_openai import OpenAIEmbeddings

# Создание векторного хранилища
vectorstore = PineconeVectorStore.from_documents(
    documents=docs,
    embedding=OpenAIEmbeddings(),
    index_name="my-index"
)

# Запрос
results = vectorstore.similarity_search("query", k=5)

# С фильтром по метаданным
results = vectorstore.similarity_search(
    "query",
    k=5,
    filter={"category": "tutorial"}
)

# Как retriever
retriever = vectorstore.as_retriever(search_kwargs={"k": 10})

Интеграция с LlamaIndex

from llama_index.vector_stores.pinecone import PineconeVectorStore

# Подключение к Pinecone
pc = Pinecone(api_key="your-key")
pinecone_index = pc.Index("my-index")

# Создание векторного хранилища
vector_store = PineconeVectorStore(pinecone_index=pinecone_index)

# Использование в LlamaIndex
from llama_index.core import StorageContext, VectorStoreIndex

storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)

Управление индексами

# Список индексов
indexes = pc.list_indexes()

# Информация об индексе
index_info = pc.describe_index("my-index")
print(index_info)

# Статистика индекса
stats = index.describe_index_stats()
print(f"Total vectors: {stats['total_vector_count']}")
print(f"Namespaces: {stats['namespaces']}")

# Удаление индекса
pc.delete_index("my-index")

Удаление векторов

# Удаление по ID
index.delete(ids=["vec1", "vec2"])

# Удаление по фильтру
index.delete(filter={"category": "old"})

# Удаление всех векторов в неймспейсе
index.delete(delete_all=True, namespace="test")

# Удаление всего индекса
index.delete(delete_all=True)

Рекомендации

1. Используйте serverless — автоскейлинг, экономичнее
2. Пакетные upsert — эффективнее (100-200 записей за раз)
3. Добавляйте метаданные — для фильтрации
4. Используйте неймспейсы — изолируйте данные по пользователям/тенантам
5. Следите за использованием — проверяйте дашборд Pinecone
6. Оптимизируйте фильтры — индексируйте часто фильтруемые поля
7. Тестируйте на бесплатном тарифе — 1 индекс, 100K векторов бесплатно
8. Используйте гибридный поиск — качество выше
9. Задавайте правильную размерность — она должна совпадать с моделью эмбеддингов
10. Делайте регулярные бэкапы — экспортируйте важные данные

Производительность

Цены (на 2025 год)

Serverless:

• $0,096 за миллион единиц чтения
• $0,06 за миллион единиц записи
• $0,06 за ГБ хранилища в месяц

Бесплатный тариф:

• 1 serverless-индекс
• 100K векторов (1536 измерений)
• Отлично подходит для прототипирования

Ресурсы

• Сайт: https://www.pinecone.io
• Документация: https://docs.pinecone.io
• Консоль: https://app.pinecone.io
• Цены: https://www.pinecone.io/pricing