Pierwsze kroki z Pinecone
Uczestnicy utworzą indeks Pinecone, wykonają upsert wektorów z metadanymi, przeprowadzą zapytania podobieństwa z filtrami oraz będą zarządzać przestrzeniami nazw w celu rozdzielenia różnych kolekcji danych.
Pierwsze kroki z Pinecone to bezpłatna lekcja AI Engineering Academy na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej AI Engineering Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs AI Engineering Academy zawiera 4 lekcji w sumie.
Czym jest Pinecone
Pinecone to w pełni zarządzana wektorowa baza danych, która automatycznie obsługuje infrastrukturę, skalowanie i kopie zapasowe. Interakcja z nią odbywa się za pośrednictwem Python SDK, a wektory i metadane są przesyłane w wywołaniach API. Pinecone przechowuje je na swoich serwerach i odpowiada na zapytania o podobieństwo z niewielkim opóźnieniem, nawet w przypadku miliardów wektorów.
Oferuje bezpłatny poziom, który wystarcza do nauki i niewielkich obciążeń produkcyjnych.
Instalowanie Pinecone SDK
Zainstaluj klienta Pinecone i zainicjalizuj go za pomocą klucza API. Przechowuj klucz API w zmiennej środowiskowej — nigdy nie umieszczaj sekretów na stałe w plikach źródłowych. Klasa Pinecone jest głównym punktem wejścia do wszystkich operacji.
# pip install pinecone-client
import os
from pinecone import Pinecone
pc = Pinecone(api_key=os.environ['PINECONE_API_KEY'])
# List existing indexes to verify connection
existing = pc.list_indexes().names()
print('Existing indexes:', existing)Tworzenie indeksu Pinecone
Indeks Pinecone to kolekcja przechowująca wektory. Podczas tworzenia indeksu należy określić parametr dimension (musi odpowiadać modelowi embeddingów) oraz parametr metric służący do obliczania podobieństwa. W przypadku embeddingów OpenAI należy użyć wartości dimension=1536 i metric='cosine'.
Tworzenie indeksu jest idempotentne: specyfikacja serverless tworzy indeks na żądanie, bez wcześniejszej alokacji zasobów.
from pinecone import Pinecone, ServerlessSpec
import os
pc = Pinecone(api_key=os.environ['PINECONE_API_KEY'])
index_name = 'my-rag-index'
if index_name not in pc.list_indexes().names():
pc.create_index(
name=index_name,
dimension=1536, # text-embedding-3-small dimension
metric='cosine',
spec=ServerlessSpec(
cloud='aws',
region='us-east-1'
)
)
print(f'Created index: {index_name}')
else:
print(f'Index already exists: {index_name}')
index = pc.Index(index_name)Upsertowanie wektorów z metadanymi
Pinecone używa operacji upsert (wstawianie lub aktualizowanie). Każdy wektor wymaga unikatowego łańcucha id, wartości values (embeddingu w postaci listy liczb zmiennoprzecinkowych) oraz opcjonalnych metadata (słownika pól, które można filtrować). Jeśli wykonają Państwo upsert z istniejącym identyfikatorem, stary wektor zostanie zastąpiony.
from openai import OpenAI
oai = OpenAI()
documents = [
{'id': 'doc-001', 'text': 'What is RAG and how does it work?', 'category': 'faq'},
{'id': 'doc-002', 'text': 'Pinecone is a managed vector database.', 'category': 'docs'},
{'id': 'doc-003', 'text': 'OpenAI embeddings have 1536 dimensions.', 'category': 'docs'}
]
texts = [d['text'] for d in documents]
resp = oai.embeddings.create(model='text-embedding-3-small', input=texts)
vectors = [
{
'id': doc['id'],
'values': resp.data[i].embedding,
'metadata': {'text': doc['text'], 'category': doc['category']}
}
for i, doc in enumerate(documents)
]
index.upsert(vectors=vectors)
print(f'Upserted {len(vectors)} vectors')Wykonywanie zapytań do indeksu Pinecone
Aby wyszukiwać, należy utworzyć embedding zapytania i wywołać index.query() z wektorem zapytania oraz parametrem top_k określającym liczbę zwracanych wyników. Ustawienie include_metadata=True powoduje zwrócenie zapisanych metadanych wraz z identyfikatorami dopasowań i wynikami.
from openai import OpenAI
oai = OpenAI()
query = 'How many dimensions do OpenAI embeddings have?'
q_resp = oai.embeddings.create(model='text-embedding-3-small', input=query)
q_vec = q_resp.data[0].embedding
results = index.query(
vector=q_vec,
top_k=3,
include_metadata=True
)
for match in results['matches']:
score = match['score']
text = match['metadata']['text']
print(f'{score:.4f}: {text}')Filtrowanie według metadanych
Pinecone obsługuje wstępne filtrowanie — zawężanie wyszukiwania do wektorów spełniających warunek dotyczący metadanych przed uruchomieniem ANN. Należy użyć parametru filter wraz z operatorami w stylu MongoDB: $eq, $in, $gt, $lt, $and, $or.
Podczas tworzenia indeksu zawsze należy zindeksować pola metadanych, według których planują Państwo filtrować, aby zapewnić odpowiednią wydajność filtrowania.
# Filter to only 'docs' category results
results = index.query(
vector=q_vec,
top_k=5,
filter={
'category': {'$eq': 'docs'}
},
include_metadata=True
)
print(f'Filtered results: {len(results["matches"])}')
for m in results['matches']:
print(f' [{m["metadata"]["category"]}] {m["metadata"]["text"][:60]}')Przestrzenie nazw do izolacji danych
Przestrzenie nazw Pinecone dzielą pojedynczy indeks na odizolowane segmenty. Zapytania w jednej przestrzeni nazw nigdy nie zwracają wyników z innej, dzięki czemu przestrzenie nazw idealnie nadają się do wielodostępnych systemów RAG, w których każdy klient powinien przeszukiwać tylko własne dokumenty.
Zarówno upsert, jak i zapytanie przyjmują opcjonalny łańcuch namespace. Domyślna przestrzeń nazw jest oznaczona pustym łańcuchem.
# Upsert into a specific namespace
index.upsert(
vectors=[{'id': 'doc-001', 'values': q_vec, 'metadata': {'text': 'Tenant A doc'}}],
namespace='tenant-a'
)
# Query only tenant-a's documents
results = index.query(
vector=q_vec,
top_k=5,
namespace='tenant-a',
include_metadata=True
)
print(f'Tenant-A results: {len(results["matches"])}')Upsertowanie wsadowe dla dużych korpusów
Podczas indeksowania tysięcy dokumentów należy dzielić wektory na partie liczące maksymalnie 100 wektorów na jedno wywołanie upsertu (zalecany rozmiar partii w Pinecone). Większe partie mogą przekroczyć limity rozmiaru ze względu na ograniczenie rozmiaru danych wynoszące około 4 MB na żądanie.
def batch_upsert(index, vectors, batch_size=100):
total = len(vectors)
for start in range(0, total, batch_size):
batch = vectors[start:start + batch_size]
index.upsert(vectors=batch)
print(f'Upserted {min(start + batch_size, total)}/{total}')
# Usage:
# batch_upsert(index, all_vectors, batch_size=100)Sprawdzanie statystyk indeksu
Użyj index.describe_index_stats(), aby sprawdzić, ile wektorów jest przechowywanych w każdej przestrzeni nazw, a także poznać łączną liczbę wektorów. Jest to przydatne do weryfikowania, czy upsert zakończył się powodzeniem, oraz do monitorowania wzrostu indeksu w czasie.
stats = index.describe_index_stats()
print(f'Total vectors: {stats["total_vector_count"]}')
print(f'Namespaces:')
for ns, info in stats.get('namespaces', {}).items():
print(f' {ns!r}: {info["vector_count"]} vectors')Usuwanie i aktualizowanie wektorów
Użyj index.delete(ids=[...]), aby usunąć określone wektory według identyfikatora. Aby zaktualizować wektor, na przykład po zmianie dokumentu, wystarczy wykonać upsert z tym samym identyfikatorem — Pinecone zastąpi istniejący wpis.
Aby usunąć wszystkie wektory w przestrzeni nazw, na przykład w celu ponownego indeksowania po pełnym odświeżeniu, użyj index.delete(delete_all=True, namespace='...').
# Delete specific vectors by id
index.delete(ids=['doc-001', 'doc-002'])
# Update a vector (upsert overwrites by id)
index.upsert(vectors=[{
'id': 'doc-003',
'values': q_vec, # new embedding
'metadata': {'text': 'Updated content.'}
}])
# Delete all vectors in a namespace
# index.delete(delete_all=True, namespace='tenant-a')Cennik Pinecone i bezpłatny poziom
Pinecone oferuje bezpłatny poziom serverless z 2 GB pamięci masowej, co wystarcza na około 300 000 wektorów o 1536 wymiarach. Powyżej tego limitu opłaty serverless są naliczane za wykorzystane jednostki odczytu i zapisu.
W przypadku obciążeń produkcyjnych miesięczny koszt można oszacować według wzoru: (liczba zapytań dziennie × 30 × koszt zapytania) + (łączna liczba wektorów × koszt pamięci masowej). W przypadku obciążeń o zmiennym ruchu serverless jest często bardziej opłacalny niż plany oparte na podach.
Szybki sprawdzian
Sprawdź swoją wiedzę na temat koncepcji inżynierii AI z tej lekcji.
Podsumowanie lekcji
W tej lekcji nauczyli się Państwo, że: indeksy Pinecone wymagają zgodności wymiaru i metryki z używanym modelem embeddingów, operacje upsert używają unikatowego identyfikatora, dlatego aktualizacja dokumentu polega po prostu na ponownym wykonaniu upsertu z tym samym identyfikatorem, a przestrzenie nazw izolują kolekcje wektorów w ramach jednego indeksu na potrzeby zastosowań wielodostępnych. Następnie poznamy pgvector, który przenosi wyszukiwanie wektorowe bezpośrednio do PostgreSQL.
Często zadawane pytania
Czy lekcja „Pierwsze kroki z Pinecone” jest bezpłatna?
Tak — pełny tekst „Pierwsze kroki z Pinecone” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu AI Engineering Academy, przejdź na CoddyKit PRO. Kurs AI Engineering Academy zawiera 4 lekcji w sumie.
Co nauczysz się w „Pierwsze kroki z Pinecone”?
Uczestnicy utworzą indeks Pinecone, wykonają upsert wektorów z metadanymi, przeprowadzą zapytania podobieństwa z filtrami oraz będą zarządzać przestrzeniami nazw w celu rozdzielenia różnych kolekcji… Ćwiczysz AI Engineering Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.
Czy potrzebuję doświadczenia, aby zacząć AI Engineering Academy?
Nie wymagamy żadnego doświadczenia. AI Engineering Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.
Ile czasu zajmuje lekcja „Pierwsze kroki z Pinecone”?
Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.
Czy mogę pisać i uruchamiać kod w tej lekcji AI Engineering Academy?
Tak. Każda lekcja AI Engineering Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.
Wszystkie lekcje w tym kursie
- Dlaczego potrzebują Państwo wektorowej bazy danych
- Pierwsze kroki z Pinecone
- pgvector: embeddingi w PostgreSQL
- Wybór i benchmarkowanie magazynów wektorowych