AI Engineering Academy · درس

البدء باستخدام Pinecone

أنشئوا فهرسًا في Pinecone، وأضيفوا المتجهات مع البيانات الوصفية باستخدام upsert، ونفّذوا استعلامات تشابه مع مرشحات، وأديروا namespaces لفصل مجموعات البيانات المختلفة.

البدء باستخدام Pinecone درس مجاني في AI Engineering Academy على CoddyKit. هذا هو الدرس 2 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في AI Engineering Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة AI Engineering Academy 4 دروس في المجموع.

بعض أجزاء هذا الدرس لم تُترجم بعد وتظهر باللغة الإنجليزية.

What Is Pinecone?

Pinecone is a fully managed vector database that handles infrastructure, scaling, and backups automatically. You interact with it through a Python SDK, sending vectors and metadata via API calls. Pinecone stores them on its servers and answers similarity queries at low latency, even at billions of vectors.

It offers a free tier that is sufficient for learning and small production workloads.

Installing the Pinecone SDK

Install the Pinecone client and initialize it with your API key. Store the API key in an environment variable — never hardcode secrets in source files. The Pinecone class is the main entry point for all operations.

# 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)

Creating a Pinecone Index

A Pinecone index is the collection that stores your vectors. When creating an index you must specify the dimension (must match your embedding model) and the metric for similarity calculation. For OpenAI embeddings, use dimension=1536 and metric='cosine'.

Index creation is idempotent: the serverless spec creates the index on-demand without pre-allocating capacity.

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)

Upserting Vectors with Metadata

Pinecone uses upsert (insert or update) operations. Each vector requires a unique id string, the values (the embedding as a list of floats), and optional metadata (a dict of filterable fields). If you upsert with an existing id, the old vector is replaced.

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')

Querying the Pinecone Index

To search, embed your query and call index.query() with the query vector and top_k for how many results to return. Set include_metadata=True to get the stored metadata back alongside the match ids and scores.

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}')

Filtering by Metadata

Pinecone supports pre-filtering — narrowing the search to vectors that match a metadata condition before running ANN. Use the filter parameter with MongoDB-style operators: $eq, $in, $gt, $lt, $and, $or.

Always index the metadata fields you plan to filter on when creating the index to ensure filter performance.

# 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]}')

Namespaces for Data Isolation

Pinecone namespaces partition a single index into isolated segments. Queries in one namespace never return results from another, making namespaces ideal for multi-tenant RAG systems where each customer should only search their own documents.

Both upsert and query accept an optional namespace string. The default namespace is an empty string.

# 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"])}')

Batch Upserting for Large Corpora

When indexing thousands of documents, split your vectors into batches of up to 100 vectors per upsert call (Pinecone's recommended batch size). Larger batches may hit size limits due to the payload size constraint of ~4MB per request.

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)

Checking Index Statistics

Use index.describe_index_stats() to check how many vectors are stored in each namespace and the total vector count. This is useful for verifying that an upsert completed successfully and for monitoring index growth over time.

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')

Deleting and Updating Vectors

Use index.delete(ids=[...]) to remove specific vectors by id. To update a vector (for example when a document is revised), simply upsert with the same id — Pinecone will overwrite the existing entry.

To delete all vectors in a namespace (for example to re-index after a full refresh), use 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')

Pinecone Pricing and Free Tier

Pinecone offers a free serverless tier with 2GB of storage, enough for roughly 300,000 vectors at 1536 dimensions. Beyond that, serverless pricing charges per read unit and write unit consumed.

For production workloads, estimate your monthly cost by calculating: (queries per day × 30 × cost per query) + (total vectors × storage cost). Serverless is often more cost-effective than pod-based plans for variable-traffic workloads.

Quick Check

Test your understanding of AI Engineering concepts from this lesson.

Lesson Recap

In this lesson you learned: Pinecone indexes require matching dimension and metric to your embedding model, upsert operations use a unique id so updating a document simply re-upserts with the same id, and namespaces isolate vector collections within a single index for multi-tenant use cases. Next up we explore pgvector, which brings vector search directly into PostgreSQL.

الأسئلة الشائعة

هل درس «البدء باستخدام Pinecone» مجاني؟

نعم — نص درس «البدء باستخدام Pinecone» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة AI Engineering Academy، انتقل إلى CoddyKit PRO. تتضمن دورة AI Engineering Academy 4 دروس في المجموع.

ماذا ستتعلم في «البدء باستخدام Pinecone»؟

أنشئوا فهرسًا في Pinecone، وأضيفوا المتجهات مع البيانات الوصفية باستخدام upsert، ونفّذوا استعلامات تشابه مع مرشحات، وأديروا namespaces لفصل مجموعات البيانات المختلفة. تتمرن على AI Engineering Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ AI Engineering Academy؟

لا تُشترط خبرة سابقة. AI Engineering Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 4.

كم من الوقت يستغرق درس «البدء باستخدام Pinecone»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس AI Engineering Academy هذا؟

نعم. كل درس في AI Engineering Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى AI Engineering Academy