GITBOOK-30: Django app

Lev Kokotov · gitbook-bot · commit cfccedb05d48 · 2024-02-15T21:26:00.000Z
diff --git a/pgml-cms/blog/SUMMARY.md b/pgml-cms/blog/SUMMARY.md
@@ -1,6 +1,7 @@
 # Table of contents
 
 * [Home](README.md)
+* [Using PostgresML with Django and embedding search](using-postgresml-with-django-and-embedding-search.md)
 * [PostgresML is going multicloud](postgresml-is-going-multicloud.md)
 * [Introducing the OpenAI Switch Kit: Move from closed to open-source AI in minutes](introducing-the-openai-switch-kit-move-from-closed-to-open-source-ai-in-minutes.md)
 * [Speeding up vector recall 5x with HNSW](speeding-up-vector-recall-5x-with-hnsw.md)
diff --git a/pgml-cms/blog/announcing-gptq-and-ggml-quantized-llm-support-for-huggingface-transformers.md b/pgml-cms/blog/announcing-gptq-and-ggml-quantized-llm-support-for-huggingface-transformers.md
@@ -3,9 +3,6 @@ description: >-
   GPTQ & GGML allow PostgresML to fit larger models in less RAM. These
   algorithms perform inference significantly faster on NVIDIA, Apple and Intel
   hardware.
-featured: false
-tags: [engineering]
-image: ".gitbook/assets/image (14).png"
 ---
 
 # Announcing GPTQ & GGML Quantized LLM support for Huggingface Transformers
diff --git a/pgml-cms/blog/announcing-support-for-aws-us-east-1-region.md b/pgml-cms/blog/announcing-support-for-aws-us-east-1-region.md
@@ -1,9 +1,3 @@
----
-description: >-
-  We added aws us east 1 to our list of support aws regions.
-featured: false
-tags: [product]
----
 # Announcing Support for AWS us-east-1 Region
 
 <div align="left">
diff --git a/pgml-cms/blog/backwards-compatible-or-bust-python-inside-rust-inside-postgres.md b/pgml-cms/blog/backwards-compatible-or-bust-python-inside-rust-inside-postgres.md
@@ -2,8 +2,6 @@
 description: >-
   A story about including Scikit-learn into our Rust extension and preserving
   backwards compatibility in the process.
-tags: [engineering]
-featured: false
 ---
 
 # Backwards Compatible or Bust: Python Inside Rust Inside Postgres
diff --git a/pgml-cms/blog/data-is-living-and-relational.md b/pgml-cms/blog/data-is-living-and-relational.md
@@ -3,8 +3,6 @@ description: >-
   A common problem with data science and machine learning tutorials is the
   published and studied datasets are often nothing like what you’ll find in
   industry.
-featured: false
-tags: [engineering]
 ---
 
 # Data is Living and Relational
diff --git a/pgml-cms/blog/generating-llm-embeddings-with-open-source-models-in-postgresml.md b/pgml-cms/blog/generating-llm-embeddings-with-open-source-models-in-postgresml.md
@@ -2,8 +2,6 @@
 description: >-
   How to use the pgml.embed(...) function to generate embeddings with free and
   open source models in your own database.
-image: ".gitbook/assets/blog_image_generating_llm_embeddings.png"
-features: true
 ---
 
 # Generating LLM embeddings with open source models in PostgresML
diff --git a/pgml-cms/blog/how-to-improve-search-results-with-machine-learning.md b/pgml-cms/blog/how-to-improve-search-results-with-machine-learning.md
@@ -3,9 +3,6 @@ description: >-
   PostgresML makes it easy to use machine learning on your data and scale
   workloads horizontally in our cloud. One of the most common use cases is to
   improve search results.
-featured: true
-image: ".gitbook/assets/image (2) (2).png"
-tags: ["Engineering"]
 ---
 
 # How-to Improve Search Results with Machine Learning
diff --git a/pgml-cms/blog/introducing-the-openai-switch-kit-move-from-closed-to-open-source-ai-in-minutes.md b/pgml-cms/blog/introducing-the-openai-switch-kit-move-from-closed-to-open-source-ai-in-minutes.md
@@ -1,10 +1,8 @@
 ---
-featured: true
-tags: [engineering, product]
+image: https://postgresml.org/dashboard/static/images/open_source_ai_social_share.png
 description: >-
   Quickly and easily transition from the confines of the OpenAI APIs to higher
   quality embeddings and unrestricted text generation models.
-image: ".gitbook/assets/blog_image_switch_kit.png"
 ---
 
 # Introducing the OpenAI Switch Kit: Move from closed to open-source AI in minutes
diff --git a/pgml-cms/blog/mindsdb-vs-postgresml.md b/pgml-cms/blog/mindsdb-vs-postgresml.md
@@ -2,7 +2,6 @@
 description: >-
   PostgresML is more opinionated, more scalable, more capable and several times
   faster than MindsDB.
-image: ".gitbook/assets/image (17).png"
 ---
 
 # MindsDB vs PostgresML
diff --git a/pgml-cms/blog/postgres-full-text-search-is-awesome.md b/pgml-cms/blog/postgres-full-text-search-is-awesome.md
@@ -2,7 +2,6 @@
 description: >-
   If you want to improve your search results, don't rely on expensive O(n*m)
   word frequency statistics. Get new sources of data instead.
-image: ".gitbook/assets/image (53).png"
 ---
 
 # Postgres Full Text Search is Awesome!
diff --git a/pgml-cms/blog/postgresml-is-going-multicloud.md b/pgml-cms/blog/postgresml-is-going-multicloud.md
@@ -1,15 +1,5 @@
 # PostgresML is going multicloud
 
-<div align="left">
-
-<figure><img src=".gitbook/assets/lev.jpg" alt="Author" width="100"><figcaption></figcaption></figure>
-
-</div>
-
-Lev Kokotov
-
-Jan 18, 2024
-
 We started PostgresML two years ago with the goal of making machine learning and AI accessible and easy for everyone.  To make this a reality, we needed to deploy PostgresML as closely as possible to our end users. With that goal mind, today we're proud to announce support for a new cloud provider: Azure.
 
 ### How we got here
diff --git a/pgml-cms/blog/speeding-up-vector-recall-5x-with-hnsw.md b/pgml-cms/blog/speeding-up-vector-recall-5x-with-hnsw.md
@@ -3,9 +3,6 @@ description: >-
   HNSW indexing is the latest upgrade in vector recall performance. In this post
   we announce our updated SDK that utilizes HNSW indexing to give world class
   performance in vector search.
-tags: [engineering]
-featured: true
-image: ".gitbook/assets/blog_image_hnsw.png"
 ---
 
 # Speeding up vector recall 5x with HNSW
diff --git a/pgml-cms/blog/using-postgresml-with-django-and-embedding-search.md b/pgml-cms/blog/using-postgresml-with-django-and-embedding-search.md
@@ -0,0 +1,129 @@
+# Using PostgresML with Django and embedding search
+
+Building web apps on top of PostgresML allows anyone to integrate advanced machine learning and AI features into their products without much work or needing to understand how it really works. In this blog post, we'll talk about building a classic to-do Django app, with the spicy addition of semantic search powered by embedding models running inside your PostgreSQL database.
+
+### Getting the code
+
+Our example application is on GitHub:[ https://github.com/postgresml/example-django](https://github.com/postgresml/example-django). You can fork it, clone it and run the app locally on your machine, or on any hosting platform of your choice. See the `README` for instructions on how to set it up.
+
+### The basics
+
+PostgresML allows anyone to integrate advanced AI capabilities into their application using only SQL. In this app, we're demonstrating embedding search: the ability to search and rank documents using their semantic meaning.
+
+Advanced search engines like Google use this technique to extract the meaning of search queries and rank the results based on what the user actually _wants_, unlike simple keyword matches which can easily give irrelevant results.
+
+To accomplish this, for each document in our app, we include an embedding column stored as a vector. A vector is just an array of floating point numbers. For each item in our to-do list, we automatically generate the embedding using the PostgresML [`pgml.embed()`](https://postgresml.org/docs/introduction/apis/sql-extensions/pgml.embed) function. This function runs inside the database and doesn't require the Django app to install the model locally.
+
+An embedding model running inside PostgresML is able to extract the meaning of search queries & compare it to the meaning of the documents it stores, just like a human being would if they were able to search millions of documents in just a few milliseconds.
+
+### The app
+
+Our Django application has only one model, the `TodoItem`. It comes with a description, a due date, a completed flag, and the embedding column. The embedding column is using `pgvector`, another great PostgreSQL extension, which provides vector storage and nearest neighbor search. `pgvector` comes with a Django plugin so we had to do very little to get it working out of the box:
+
+```python
+embedding = models.GeneratedField(
+    expression=EmbedSmallExpression("description"),
+    output_field=VectorField(dimensions=384),
+    db_persist=True,
+)    
+```
+
+This little code snippet contains quite a bit of functionality. First, we use a `GeneratedField` which is a database column that's automatically populated with data from the database. The application doesn't need to input anything when a model instance is created. This is a very powerful technique to ensure data durability and accuracy.
+
+Secondly, the generated column is using a `VectorField`. This comes from the `pgvector.django` package and defines a `vector(384)` column: a vector with 384 dimensions.
+
+Lastly, the `expression` argument tells Django how to generate this field inside the database. Since PostgresML doesn't (yet) come with a Django plugin, we had to write the expression class ourselves. Thankfully, Django makes this very easy:
+
+```python
+class EmbedSmallExpression(models.Expression):
+    output_field = VectorField(null=False, blank=False, dimensions=384)
+
+    def __init__(self, field):
+        self.embedding_field = field
+
+    def as_sql(self, compiler, connection, template=None):
+        return f"pgml.embed('intfloat/e5-small', {self.embedding_field})", None
+```
+
+And that's it! In just a few lines of code, we're generating and storing high quality embeddings automatically in our database. No additional setup is required, and all the AI complexity is taken care of by PostgresML.
+
+#### API
+
+Djago Rest Framework provides the bulk of the implementation. We just added a `ModelViewSet` for the `TodoItem` model, with just one addition: a search endpoint. The search endpoint required us to write a bit of SQL to embed the search query and accept a few filters, but the core of it can be summarized in a single annotation on the query set:
+
+<pre class="language-python"><code class="lang-python"><strong>results = TodoItem.objects.annotate(
+</strong>    similarity=RawSQL(
+        "pgml.embed('intfloat/e5-small', %s)::vector(384) &#x3C;=> embedding",
+        [query],
+    )
+).order_by("similarity")
+</code></pre>
+
+This single line of SQL does quite a bit:
+
+1. It embeds the input query using the same model as we used to embed the description column in the model
+2. It performs a cosine similarity search on the generated embedding and the embeddings of all other descriptions stored in the database
+3. It ranks the result by similarity, returning the results in order of relevance, starting at the most relevant
+
+All of this happens inside PostgresML. Our Django app doesn't need to implement any of this functionality beyond just a bit of raw SQL.
+
+### Creating to-dos
+
+Before going forward, make sure you have the app running either locally or in a cloud provider of your choice. If hosting it somewhere, replace `localhost:8000` with the URL and port of your service.
+
+The simplest way to interact with it is to use cURL or an HTTP client of your preference. If running in debug mode locally, the Rest Framework provides a nice web UI which you can access on [http://localhost:8000/api/todos/](http://localhost:8000/api/todo/) using a browser.
+
+To create a to-do item with cURL, you can just run this:
+
+```bash
+curl \
+    --silent \
+    -X POST \
+    -d '{"description": "Make a New Year resolution list", "due_date": "2025-01-01"}' \
+    -H 'Content-Type: application/json' \
+    http://localhost:8000/api/todo/
+```
+
+In return, you'll get your to-do item alongside the embedding of the `description` column generated by PostgresML:
+
+```json
+{
+  "id": 5,
+  "description": "Make a New Year resolution",
+  "due_date": "2025-01-01",
+  "completed": false
+  "embedding": "[-2.60886201e-03 -6.66755587e-02 -9.28235054e-02  [...]]"
+}
+```
+
+The embedding contains 384 floating point numbers; we removed most of them in this blog post to make sure it fits on the page.
+
+You can try creating multiple to-do items for fun and profit. If the description is changed, so will the embedding, demonstrating how the `intfloat/e5-small` model is understanding the semantic meaning of your text.
+
+### Searching
+
+Once you have a few embeddings and to-dos stored in your database, the fun part of searching can begin. In a typical search example with PostgreSQL, you'd now be using `tsvector` to keyword match your to-dos to the search query with term frequency. That's a good technique, but semantic search is better.
+
+We've created a simple search endpoint that accepts a query, a completed to-do filter, and a limit. To use it, you can just do this:
+
+```bash
+curl \
+    --silent \
+    -H "Content-Type: application/json" \
+    'http://localhost:8000/api/todo/search/?q=resolution&limit=1' | \
+     jq ".[0].description"
+```
+
+If you've created a bunch of different to-do items, you should get only one search result back, and exactly the one you were expecting:
+
+```json
+"Make a New Year resolution list"
+```
+
+You can increase the `limit` to something larger and you should get more documents, in decreasing order of relevance.
+
+And that's it! In just a few lines of code, we built an advanced semantic search engine, previously only available to large enterprises and teams with dedicated machine learning experts. While it may not stop us from procrastinating our chores, it will definitely help us find the to-dos we really _want_ to do.
+
+The code is available on [GitHub.](https://github.com/postgresml/example-django)
+
+As always, if you have any feedback or thoughts, reach out to us on Discord or by email. We're always happy to talk about the cool things we can build with PostgresML!
