This page shows you how to use integrated inference to upsert and search without extra steps for embedding data and reranking results.

​
1. Install dependencies

Install the latest Pinecone Python SDK as follows:

pip install --upgrade pinecone

​
2. Create or configure an index

Integrated inference requires a serverless index configured for a specific embedding model. You can either create a new index for a model or configure an existing index for a model.

To create an index that accepts source text and converts it to vectors automatically using an embedding model hosted by Pinecone, use the create_for_model operation as follows:

  • Provide a name for the index.
  • Set embed.model to one of Pinecone’s hosted embedding models.
  • Set spec.cloud and spec.region to the cloud and region where the index should be deployed.
  • Set embed.field_map to the name of the field in your source document that contains the data for embedding.

Other parameters are optional. See the API reference for details.

# pip install --upgrade pinecone
from pinecone import Pinecone
import time

pc = Pinecone(api_key="YOUR_API_KEY")

index_name = "example-index"

if not pc.has_index(index_name):
    index_model = pc.create_index_for_model(
        name=index_name,
        cloud="aws",
        region="us-east-1",
        embed={
            "model":"multilingual-e5-large",
            "field_map":{"text": "chunk_text"}
        }
    )

print(index_model)

The response will look like this:

{'deletion_protection': 'disabled',
 'dimension': 1024,
 'embed': {'dimension': 1024,
           'field_map': {'text': 'chunk_text'},
           'metric': 'cosine',
           'model': 'multilingual-e5-large',
           'read_parameters': {'input_type': 'query', 'truncate': 'END'},
           'write_parameters': {'input_type': 'passage', 'truncate': 'END'},
           'vector_type': 'dense'},
 'host': 'example-index-govk0nt.svc.aped-4627-b74a.pinecone.io',
 'id': '9e8b39c5-a142-4776-9609-e8612ad03d92',
 'metric': 'cosine',
 'name': 'example-index',
 'spec': {'serverless': {'cloud': 'aws', 'region': 'us-east-1'}},
 'status': {'ready': True, 'state': 'Ready'},
 'tags': None}

​
3. Upsert data

Once you have an index configured for a specific embedding model, use the /records/upsert operation to convert your source data to embeddings and upsert them into a namespace in the index.

Note the following requirements for each document in the request body:

  • Each document must contain a unique _id, which will serve as the unique record identifier in the index namespace.
  • Each document must contain a field with the data for embedding. This field must match the field_map specified when creating the index.
  • Any additional fields in the document will be stored in the index and can be returned in search results or used to filter search results.
  • When using the API directly, documents are specified using the NDJSON format, also known as line-delimited JSON or JSONL, with one document per line. The Python SDK transforms the list of dictionary entries into the correct NDJSON format for you.
# Target the created index for upsert and search
index = pc.Index(index_name)

index.upsert_records(
  "example-namespace",
  [
      {
          "_id": "rec1", 
          "chunk_text": "Apple's first product, the Apple I, was released in 1976 and was hand-built by co-founder Steve Wozniak.",
          "category": "product", 
      },
      {
          "_id": "rec2",
          "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.",
          "category": "nutrition", 
      },
      {
          "_id": "rec3",
          "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.",
          "category": "cultivation",
      },
      {
          "_id": "rec4",
          "chunk_text": "In 2001, Apple released the iPod, which transformed the music industry by making portable music widely accessible.",
          "category": "product", 
      },
      {
          "_id": "rec5",
          "chunk_text": "Apple went public in 1980, making history with one of the largest IPOs at that time.",
          "category": "milestone", 
      },
      {
          "_id": "rec6",
          "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.",
          "category": "nutrition",
      },
      {
          "_id": "rec7",
          "chunk_text": "Known for its design-forward products, Apple's branding and market strategy have greatly influenced the technology sector and popularized minimalist design worldwide.",
          "category": "influence",
      },
      {
          "_id": "rec8",
          "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.",
          "category": "nutrition",
      },
  ],
)

time.sleep(10) # Wait for the upserted vectors to be indexed

​
4. Search the index

Use the /records/search operation to convert a query to a vector embedding and then search your namespace for the most semantically similar records, along with their similarity scores.

Note the following:

  • The inputs field must be text.
  • The top_k parameter must specify the number of similar records to return.
  • Optionally, you can specify:
    • The fields to return. If not specified, the response will include all fields.
    • A filter to narrow down the search results.
    • rerank parameters to rerank the initial search results based on relevance to the query.

In the previous step, you upserted 8 documents, some about Apple, the technology company, and some about apple, the fruit.

First, search for the 4 documents most semantically related to the query, “Disease prevention”:

results = index.search_records(
    namespace="example-namespace", 
    query={
        "inputs": {"text": "Disease prevention"}, 
        "top_k": 4
    },
    fields=["category", "chunk_text"]
)

print(results)

Notice that the response includes only documents about the fruit, not the tech company:

{'result': {'hits': [{'_id': 'rec6',
                      '_score': 0.8197098970413208,
                      'fields': {'category': 'nutrition',
                                 'chunk_text': 'Rich in vitamin C and other '
                                               'antioxidants, apples '
                                               'contribute to immune health '
                                               'and may reduce the risk of '
                                               'chronic diseases.'}},
                     {'_id': 'rec2',
                      '_score': 0.7929002642631531,
                      'fields': {'category': 'nutrition',
                                 'chunk_text': 'Apples are a great source of '
                                               'dietary fiber, which supports '
                                               'digestion and helps maintain a '
                                               'healthy gut.'}},
                     {'_id': 'rec8',
                      '_score': 0.7800688147544861,
                      'fields': {'category': 'nutrition',
                                 'chunk_text': 'The high fiber content in '
                                               'apples can also help regulate '
                                               'blood sugar levels, making '
                                               'them a favorable snack for '
                                               'people with diabetes.'}},
                     {'_id': 'rec3',
                      '_score': 0.7553971409797668,
                      'fields': {'category': 'cultivation',
                                 'chunk_text': 'Apples originated in Central '
                                               'Asia and have been cultivated '
                                               'for thousands of years, with '
                                               'over 7,500 varieties available '
                                               'today.'}}]},
 'usage': {'embed_total_tokens': 8, 'read_units': 6}}

​
Search with reranking

To rerank initial search results based on relevance to the query, add the rerank parameter, including the reranking model you want to use, the number of reranked results to return, and the fields to use for reranking, if different than the main query.

For example, repeat the search for the 4 documents most semantically related to the query, “Disease prevention”, but this time rerank the results and return only the 2 most relevant documents:

ranked_results = index.search_records(
    namespace="example-namespace", 
    query={
        "inputs": {"text": "Disease prevention"}, 
        "top_k": 4
    },
    rerank={
        "model": "bge-reranker-v2-m3",
        "top_n": 2,
        "rank_fields": ["chunk_text"]
    },
    fields=["category", "chunk_text"]
)

print(ranked_results)

Notice that the 2 returned documents are the most relevant for the query, the first relating to reducing chronic diseases, the second relating to preventing diabetes:

{'result': {'hits': [{'_id': 'rec6',
                      '_score': 0.004433765076100826,
                      'fields': {'category': 'nutrition',
                                 'chunk_text': 'Rich in vitamin C and other '
                                               'antioxidants, apples '
                                               'contribute to immune health '
                                               'and may reduce the risk of '
                                               'chronic diseases.'}},
                     {'_id': 'rec8',
                      '_score': 0.0029121784027665854,
                      'fields': {'category': 'nutrition',
                                 'chunk_text': 'The high fiber content in '
                                               'apples can also help regulate '
                                               'blood sugar levels, making '
                                               'them a favorable snack for '
                                               'people with diabetes.'}}]},
 'usage': {'embed_total_tokens': 8, 'read_units': 6, 'rerank_units': 1}}

​
Search with filtering

Your upserted documents also contain a category field. Now use that field as a filter to search for the 2 documents related to Apple, the tech company, that are in the “product” category:

filtered_results = index.search_records(
    namespace="example-namespace", 
    query={
        "inputs": {"text": "Apple tech company"}, 
        "top_k": 2,
        "filter": {"category": "product"}
    },
    fields=["category", "chunk_text"]
)

print(filtered_results)

Notice that the response includes only documents about Apple, the tech company, that are in the “product” category:

{'result': {'hits': [{'_id': 'rec1',
                      '_score': 0.8127778768539429,
                      'fields': {'category': 'product',
                                 'chunk_text': "Apple's first product, the "
                                               'Apple I, was released in 1976 '
                                               'and was hand-built by '
                                               'co-founder Steve Wozniak.'}},
                     {'_id': 'rec4',
                      '_score': 0.7763848900794983,
                      'fields': {'category': 'product',
                                 'chunk_text': 'In 2001, Apple released the '
                                               'iPod, which transformed the '
                                               'music industry by making '
                                               'portable music widely '
                                               'accessible.'}}]},
 'usage': {'embed_total_tokens': 8, 'read_units': 6}}

Was this page helpful?

Rerank documentsUnderstanding Pinecone Assistant