Add Cloud version of the "Build a Semantic Search Engine in 5 Minutes" tutorial (#2127)

* Add Cloud version of Semantic Search 101 tutorial * Add Colab notebook * Make Python snippets testable * Clean up and add descriptions * Review feedback
2026-10-06 11:28:31 +02:00 · 2026-02-11 14:48:33 +01:00
parent c2350136e1
commit 63337422da
23 changed files with 683 additions and 184 deletions
@@ -0,0 +1 @@
+This code snippet shows how to create a client connection to Qdrant Cloud, with the cluster URL and API key, and enables cloud inference for automatic embedding generation.
@@ -0,0 +1,9 @@
+```python
+from qdrant_client import QdrantClient, models
+
+client = QdrantClient(
+    url=QDRANT_URL,
+    api_key=QDRANT_API_KEY,
+    cloud_inference=True
+)
+```
@@ -0,0 +1,12 @@
+# @hide-start
+QDRANT_URL=""
+QDRANT_API_KEY=""
+# @hide-end
+
+from qdrant_client import QdrantClient, models
+
+client = QdrantClient(
+    url=QDRANT_URL,
+    api_key=QDRANT_API_KEY,
+    cloud_inference=True
+)
@@ -0,0 +1 @@
+This code snippet shows how to create a collection in Qdrant. The example creates a collection named `my_books` configured to store 384-dimensional vectors with cosine distance metric.
@@ -0,0 +1,11 @@
+```python
+COLLECTION_NAME="my_books"
+
+client.create_collection(
+    collection_name=COLLECTION_NAME,
+    vectors_config=models.VectorParams(
+        size=384,  # Vector size is defined by the model
+        distance=models.Distance.COSINE,
+    ),
+)
+```
@@ -0,0 +1,19 @@
+# @hide-start
+from qdrant_client import QdrantClient, models
+
+client = QdrantClient(
+    url="",
+    api_key="",
+    cloud_inference=True
+)
+# @hide-end
+
+COLLECTION_NAME="my_books"
+
+client.create_collection(
+    collection_name=COLLECTION_NAME,
+    vectors_config=models.VectorParams(
+        size=384,  # Vector size is defined by the model
+        distance=models.Distance.COSINE,
+    ),
+)
@@ -0,0 +1 @@
+This code snippet shows how to create a payload index on a specific field. The example creates an index on the `year` field of type integer, which enables efficient filtering on this field in subsequent queries.
@@ -0,0 +1,7 @@
+```python
+client.create_payload_index(
+    collection_name=COLLECTION_NAME,
+    field_name="year",
+    field_schema="integer",
+)
+```
@@ -0,0 +1,17 @@
+# @hide-start
+from qdrant_client import QdrantClient, models
+
+client = QdrantClient(
+    url="",
+    api_key="",
+    cloud_inference=True
+)
+
+COLLECTION_NAME="my_books"
+# @hide-end
+
+client.create_payload_index(
+    collection_name=COLLECTION_NAME,
+    field_name="year",
+    field_schema="integer",
+)
@@ -0,0 +1 @@
+This code snippet shows how to query a collection using inference at query time. Instead of providing an explicit query vector, the example uses a `Document` object with query text and a model name. Qdrant generates embeddings from the text and performs a semantic search to find the three most similar books, returning their payloads and similarity scores.
@@ -0,0 +1,13 @@
+```python
+hits = client.query_points(
+    collection_name=COLLECTION_NAME,
+    query=models.Document(
+        text="alien invasion",
+        model=EMBEDDING_MODEL
+    ),
+    limit=3,
+).points
+
+for hit in hits:
+    print(hit.payload, "score:", hit.score)
+```
@@ -0,0 +1,24 @@
+# @hide-start
+from qdrant_client import QdrantClient, models
+
+client = QdrantClient(
+    url="",
+    api_key="",
+    cloud_inference=True
+)
+
+COLLECTION_NAME=""
+EMBEDDING_MODEL=""
+# @hide-end
+
+hits = client.query_points(
+    collection_name=COLLECTION_NAME,
+    query=models.Document(
+        text="alien invasion",
+        model=EMBEDDING_MODEL
+    ),
+    limit=3,
+).points
+
+for hit in hits:
+    print(hit.payload, "score:", hit.score)
@@ -0,0 +1 @@
+This code snippet demonstrates how to query a collection with a filter. The example uses inference to generate query embeddings and applies a filter to return only books published after the year 2000, limiting the results to the single most relevant match.
@@ -0,0 +1,16 @@
+```python
+hits = client.query_points(
+    collection_name=COLLECTION_NAME,
+    query=models.Document(
+        text="alien invasion",
+        model=EMBEDDING_MODEL
+    ),
+    query_filter=models.Filter(
+        must=[models.FieldCondition(key="year", range=models.Range(gte=2000))]
+    ),
+    limit=1,
+).points
+
+for hit in hits:
+    print(hit.payload, "score:", hit.score)
+```
@@ -0,0 +1,27 @@
+# @hide-start
+from qdrant_client import QdrantClient, models
+
+client = QdrantClient(
+    url="",
+    api_key="",
+    cloud_inference=True
+)
+
+COLLECTION_NAME=""
+EMBEDDING_MODEL=""
+# @hide-end
+
+hits = client.query_points(
+    collection_name=COLLECTION_NAME,
+    query=models.Document(
+        text="alien invasion",
+        model=EMBEDDING_MODEL
+    ),
+    query_filter=models.Filter(
+        must=[models.FieldCondition(key="year", range=models.Range(gte=2000))]
+    ),
+    limit=1,
+).points
+
+for hit in hits:
+    print(hit.payload, "score:", hit.score)
@@ -0,0 +1 @@
+This code snippet defines a dataset of science fiction books. Each book entry contains a name, description, author, and publication year. This dataset will be uploaded to the Qdrant collection for semantic search.
@@ -0,0 +1,82 @@
+```python
+documents = [
+    {
+        "name": "The Time Machine",
+        "description": "A man travels through time and witnesses the evolution of humanity.",
+        "author": "H.G. Wells",
+        "year": 1895,
+    },
+    {
+        "name": "Ender's Game",
+        "description": "A young boy is trained to become a military leader in a war against an alien race.",
+        "author": "Orson Scott Card",
+        "year": 1985,
+    },
+    {
+        "name": "Brave New World",
+        "description": "A dystopian society where people are genetically engineered and conditioned to conform to a strict social hierarchy.",
+        "author": "Aldous Huxley",
+        "year": 1932,
+    },
+    {
+        "name": "The Hitchhiker's Guide to the Galaxy",
+        "description": "A comedic science fiction series following the misadventures of an unwitting human and his alien friend.",
+        "author": "Douglas Adams",
+        "year": 1979,
+    },
+    {
+        "name": "Dune",
+        "description": "A desert planet is the site of political intrigue and power struggles.",
+        "author": "Frank Herbert",
+        "year": 1965,
+    },
+    {
+        "name": "Foundation",
+        "description": "A mathematician develops a science to predict the future of humanity and works to save civilization from collapse.",
+        "author": "Isaac Asimov",
+        "year": 1951,
+    },
+    {
+        "name": "Snow Crash",
+        "description": "A futuristic world where the internet has evolved into a virtual reality metaverse.",
+        "author": "Neal Stephenson",
+        "year": 1992,
+    },
+    {
+        "name": "Neuromancer",
+        "description": "A hacker is hired to pull off a near-impossible hack and gets pulled into a web of intrigue.",
+        "author": "William Gibson",
+        "year": 1984,
+    },
+    {
+        "name": "The War of the Worlds",
+        "description": "A Martian invasion of Earth throws humanity into chaos.",
+        "author": "H.G. Wells",
+        "year": 1898,
+    },
+    {
+        "name": "The Hunger Games",
+        "description": "A dystopian society where teenagers are forced to fight to the death in a televised spectacle.",
+        "author": "Suzanne Collins",
+        "year": 2008,
+    },
+    {
+        "name": "The Andromeda Strain",
+        "description": "A deadly virus from outer space threatens to wipe out humanity.",
+        "author": "Michael Crichton",
+        "year": 1969,
+    },
+    {
+        "name": "The Left Hand of Darkness",
+        "description": "A human ambassador is sent to a planet where the inhabitants are genderless and can change gender at will.",
+        "author": "Ursula K. Le Guin",
+        "year": 1969,
+    },
+    {
+        "name": "The Three-Body Problem",
+        "description": "Humans encounter an alien civilization that lives in a dying system.",
+        "author": "Liu Cixin",
+        "year": 2008,
+    },
+]
+```
@@ -0,0 +1,80 @@
+documents = [
+    {
+        "name": "The Time Machine",
+        "description": "A man travels through time and witnesses the evolution of humanity.",
+        "author": "H.G. Wells",
+        "year": 1895,
+    },
+    {
+        "name": "Ender's Game",
+        "description": "A young boy is trained to become a military leader in a war against an alien race.",
+        "author": "Orson Scott Card",
+        "year": 1985,
+    },
+    {
+        "name": "Brave New World",
+        "description": "A dystopian society where people are genetically engineered and conditioned to conform to a strict social hierarchy.",
+        "author": "Aldous Huxley",
+        "year": 1932,
+    },
+    {
+        "name": "The Hitchhiker's Guide to the Galaxy",
+        "description": "A comedic science fiction series following the misadventures of an unwitting human and his alien friend.",
+        "author": "Douglas Adams",
+        "year": 1979,
+    },
+    {
+        "name": "Dune",
+        "description": "A desert planet is the site of political intrigue and power struggles.",
+        "author": "Frank Herbert",
+        "year": 1965,
+    },
+    {
+        "name": "Foundation",
+        "description": "A mathematician develops a science to predict the future of humanity and works to save civilization from collapse.",
+        "author": "Isaac Asimov",
+        "year": 1951,
+    },
+    {
+        "name": "Snow Crash",
+        "description": "A futuristic world where the internet has evolved into a virtual reality metaverse.",
+        "author": "Neal Stephenson",
+        "year": 1992,
+    },
+    {
+        "name": "Neuromancer",
+        "description": "A hacker is hired to pull off a near-impossible hack and gets pulled into a web of intrigue.",
+        "author": "William Gibson",
+        "year": 1984,
+    },
+    {
+        "name": "The War of the Worlds",
+        "description": "A Martian invasion of Earth throws humanity into chaos.",
+        "author": "H.G. Wells",
+        "year": 1898,
+    },
+    {
+        "name": "The Hunger Games",
+        "description": "A dystopian society where teenagers are forced to fight to the death in a televised spectacle.",
+        "author": "Suzanne Collins",
+        "year": 2008,
+    },
+    {
+        "name": "The Andromeda Strain",
+        "description": "A deadly virus from outer space threatens to wipe out humanity.",
+        "author": "Michael Crichton",
+        "year": 1969,
+    },
+    {
+        "name": "The Left Hand of Darkness",
+        "description": "A human ambassador is sent to a planet where the inhabitants are genderless and can change gender at will.",
+        "author": "Ursula K. Le Guin",
+        "year": 1969,
+    },
+    {
+        "name": "The Three-Body Problem",
+        "description": "Humans encounter an alien civilization that lives in a dying system.",
+        "author": "Liu Cixin",
+        "year": 2008,
+    },
+]
@@ -0,0 +1 @@
+This code snippet demonstrates how to upload points to a collection using inference at ingest time. Instead of providing explicit vectors, the example uses a `Document` object with the book description and a model name. Qdrant generates embeddings from the text using the specified model and stores the resulting vectors along with the book's metadata as payload.
@@ -0,0 +1,19 @@
+```python
+# Define the embedding model used by Cloud Inference
+EMBEDDING_MODEL="sentence-transformers/all-minilm-l6-v2"
+
+client.upload_points(
+    collection_name=COLLECTION_NAME,
+    points=[
+        models.PointStruct(
+            id=idx,
+            vector=models.Document(
+                text=doc["description"],
+                model=EMBEDDING_MODEL # Cloud Inference generates embeddings with this model
+            ),
+            payload=doc
+        )
+        for idx, doc in enumerate(documents)
+    ],
+)
+```
@@ -0,0 +1,37 @@
+# @hide-start
+# mypy: disable-error-code="arg-type"
+from qdrant_client import QdrantClient, models
+
+client = QdrantClient(
+    url="",
+    api_key="",
+    cloud_inference=True
+)
+
+COLLECTION_NAME=""
+documents = documents = [
+    {
+        "name": "",
+        "description": "",
+        "author": "",
+        "year": 1895,
+    }]
+# @hide-end
+
+# Define the embedding model used by Cloud Inference
+EMBEDDING_MODEL="sentence-transformers/all-minilm-l6-v2"
+
+client.upload_points(
+    collection_name=COLLECTION_NAME,
+    points=[
+        models.PointStruct(
+            id=idx,
+            vector=models.Document(
+                text=doc["description"],
+                model=EMBEDDING_MODEL # Cloud Inference generates embeddings with this model
+            ),
+            payload=doc
+        )
+        for idx, doc in enumerate(documents)
+    ],
+)
				`@@ -0,0 +1 @@`
				`This code snippet shows how to create a client connection to Qdrant Cloud, with the cluster URL and API key, and enables cloud inference for automatic embedding generation.`
				`@@ -0,0 +1 @@`
				This code snippet shows how to create a collection in Qdrant. The example creates a collection named `my_books` configured to store 384-dimensional vectors with cosine distance metric.
				`@@ -0,0 +1 @@`
				This code snippet shows how to query a collection using inference at query time. Instead of providing an explicit query vector, the example uses a `Document` object with query text and a model name. Qdrant generates embeddings from the text and performs a semantic search to find the three most similar books, returning their payloads and similarity scores.
				`@@ -0,0 +1 @@`
				`This code snippet demonstrates how to query a collection with a filter. The example uses inference to generate query embeddings and applies a filter to return only books published after the year 2000, limiting the results to the single most relevant match.`
				`@@ -0,0 +1 @@`
				`This code snippet defines a dataset of science fiction books. Each book entry contains a name, description, author, and publication year. This dataset will be uploaded to the Qdrant collection for semantic search.`
				`@@ -0,0 +1 @@`
				This code snippet demonstrates how to upload points to a collection using inference at ingest time. Instead of providing explicit vectors, the example uses a `Document` object with the book description and a model name. Qdrant generates embeddings from the text using the specified model and stores the resulting vectors along with the book's metadata as payload.