Tutorial for e-commerce

Learn how to build an e-commerce retail search in minutes

Furniture Discovery

In this tutorial, you'll step into familiar territory, building a search index to enable semantic search for a set of furniture products. Specifically, we will be loading and searching furniture listings crawled from various sellers on Etsy.

By the end of this tutorial, you will have a furniture collection available via an API, using semantic search to enhance the discovery experience in your application.

You will:

  1. Configure your OpenAI key in the Vantage platform to allow the platform to embed the furniture data.
  2. Create a collection to store the data, making it available for search.
  3. Upload a furniture dataset.
  4. Search the collection from the console.
  5. (Optional) Search the collection using Python.

Steps

Prerequisites

Before you begin, you will need:

  1. Vantage Account:
    Sign up for a Vantage account through our console.
  2. OpenAI Account and API Key:
    Generate or retrieve your OpenAI keys on the API Keys page on the OpenAI platform.
  3. Furniture Sample Data File:
    Download the data file, which contains approximately 5k listings with images and descriptions.

Step 1: Configure Your LLM Provider API Key

Step 1

Skip this step if you already have a key.

Log in to the console and navigate to API Keys.

  1. Click + Add new Model API Key to create a new Model API Key.
  2. Input the key from OpenAI.
  3. Click Add Key.

Create LLM API Key

Step 2: Create a New Collection

Step 2

  1. In the console, navigate to the collections page.
  2. Create a new Collection.
  3. Name your new collection "Furniture Tutorial".
  4. Ensure to set the Collection ID to furniture-tutorial. We will use this when we search.
  5. For Model, select text-embedding-ada-002.
  6. Ensure the Model API Key from the previous step is selected.
  7. Click on Create Collection.

Create Collection

Step 3: Upload Furniture Dataset

Step 3

  1. Ensure you're on the Upload Data page and that the collection you just created, "Furniture Tutorial," is selected.
  2. Click the + or drag and drop the provided furniture data file to upload it.
  3. Click Upload.

Upload Data

The upload may take a minute. Once complete you should see a success screen.

Upload Data Sucess

🚧

Don't re-upload!

If the collection details screen appears empty, do not re-upload! It might take up to 5 minutes for your file to appear in the file status, but it's usually quicker.

Empty Collection

Wait until you see the file processed.

  1. Refresh the Collection Files section.
  2. Review the log once the file has been processed. Your data is now indexed and included in the Vantage platform search!
  3. Wait for the collection to be online, meaning your data is ready for search.
  4. When the collection is online, proceed to Test Collection to search your data.

File Processed

πŸ‘

Ensure your collection status indicates Online before proceeding.

Step 4: Search the Collection

Step 4

Time to search your collection!

  1. Enter modern sleek armchair for a small space into the text box.
  2. Execute your first Vantage semantic query. You are about to search via AI embeddings for the most relevant semantic results based on your query's intent and understanding.
  3. Review the results.

Search Collection

The IDs for the furniture dataset don't really provide much context about the result. You may want to copy and paste the ID into a web browser to evaluate the results. Data about each product, supporting a different tutorial, is located at https://furniture-json.demo.vanta.ge/<<<<id>>>>.json.

To get the top result, 50777d55cfc98140744d0caea184d594, visit 50777d55cfc98140744d0caea184d594.json

Step 5: Search the Collection from Python

Step 5

To call the Search API from Python/cURL, you'll need two pieces of information:

  1. Your account_id, found in the URL of the test collection or collection details page.
    Find account_id
  2. Your Vantage API Key for inclusion in the request.
    Find API Key

In the code below, replace <<YOUR ACCOUNT_ID GOES HERE>> and <<YOUR VANTAGE API KEY GOES HERE>> with your actual account_id and API Key.

# Python example
import requests

url = "https://api.vanta.ge/v1/search/semantic"

payload = {
    "filter": {"boolean_filter": ""},
    "pagination": {"page": 0, "count": 5},
    "collection": {
        "account_id": "<<YOUR ACCOUNT_ID GOES HERE>>",
        "collection_id": "furniture-tutorial",
        "accuracy": 1
    },
    "text": "comfy traditional"
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer <<YOUR VANTAGE API KEY GOES HERE>>"
}

response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
curl --request POST \
     --url https://api.vanta.ge/v1/search/semantic \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<YOUR VANTAGE API KEY GOES HERE>>' \
     --header 'content-type: application/json' \
     --data '
{
  "filter": {
    "boolean_filter": ""
  },
  "pagination": {
    "page": 0,
    "count": 5
  },
  "collection": {
    "account_id": "<<YOUR ACCOUNT_ID GOES HERE>>",
    "collection_id": "furniture-tutorial",
    "accuracy": 1
  },
  "text": "comfy traditional"
}'
{
  "status": 200,
  "message": "Success.",
  "results": [
    {
      "id": "2dc2e0e63332be07fe7d9146fd86c40e",
      "score": 0.9057452082633972
    },
    {
      "id": "17b8c8bdcd8bf9eec0bc042aec338799",
      "score": 0.9022208452224731
    },
    {
      "id": "f456cda0d0b7ddf5f14461fbe7fe4df9",
      "score": 0.9020905494689941
    },
    {
      "id": "f6e051e2c3e589953e3d837c48b5ee85",
      "score": 0.9018914699554443
    },
    {
      "id": "cfcfc3037bf836567344bf532383aafa",
      "score": 0.9018372297286987
    }
  ],
  "request_id": 1707415977381,
  "execution_time": 13
}

To finish up, run your Python script or cURL command to see the results.

πŸ‘

Search API Reference

We encourage you to explore the Reference Documentation

Congratulations!

You have completed the Furniture Discovery tutorial. You're now prepared to enrich your e-commerce experience with semantic search capabilities, powered by Vantage.