doc update (#105)

* add doc for self-hosted models

* docs

* diff model

* update model

* update sig on docs

* update formatting

* update table

* add docs ci

* path

* update compose

* add path

* fix install cmd

* add token

* only main

---------

Co-authored-by: Adam Hendel <[email protected]>

Author: ChuckHend

.github/workflows/docs.yml

@@ -0,0 +1,23 @@
+name: Docs CI Workflow
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.11
+      - run: curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.7.1 python3 -
+      - run: poetry install
+
+      - name: deploy docs
+        env:
+            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: poetry run mkdocs gh-deploy --force

Makefile

@@ -0,0 +1,5 @@
+.PHONY: docs
+
+docs:
+	poetry install --no-directory --no-root
+	poetry run mkdocs serve

README.md

@@ -125,12 +125,12 @@ Create a job to vectorize the products table. We'll specify the tables primary k
 
 ```sql
 SELECT vectorize.table(
-    job_name => 'product_search_hf',
-    "table" => 'products',
+    job_name    => 'product_search_hf',
+    "table"     => 'products',
     primary_key => 'product_id',
-    columns => ARRAY['product_name', 'description'],
+    columns     => ARRAY['product_name', 'description'],
     transformer => 'sentence-transformers/multi-qa-MiniLM-L6-dot-v1',
-    schedule => 'realtime'
+    schedule    => 'realtime'
 );
 ```
 
@@ -140,10 +140,10 @@ Then search,
 
 ```sql
 SELECT * FROM vectorize.search(
-    job_name => 'product_search_hf',
-    query => 'accessories for mobile devices',
-    return_columns => ARRAY['product_id', 'product_name'],
-    num_results => 3
+    job_name        => 'product_search_hf',
+    query           => 'accessories for mobile devices',
+    return_columns  => ARRAY['product_id', 'product_name'],
+    num_results     => 3
 );
 ```
 
@@ -184,6 +184,9 @@ ALTER TABLE products
 ADD COLUMN context TEXT GENERATED ALWAYS AS (product_name || ': ' || description) STORED;
 ```
 
+Initialize the RAG project.
+ We'll use the `sentence-transformers/all-MiniLM-L12-v2` model to generate embeddings on our source documents.
+
 ```sql
 SELECT vectorize.init_rag(
     agent_name          => 'product_chat',
@@ -194,17 +197,35 @@ SELECT vectorize.init_rag(
 );
 ```
 
+Now we can ask questions of the `products` table and get responses from the `product_chat` agent using the `openai/gpt-3.5-turbo` generative model.
+
 ```sql
 SELECT vectorize.rag(
     agent_name  => 'product_chat',
-    query       => 'What is a pencil?'
+    query       => 'What is a pencil?',
+    chat_model  => 'openai/gpt-3.5-turbo'
 ) -> 'chat_response';
 ```
 
 ```text
 "A pencil is an item that is commonly used for writing and is known to be most effective on paper."
 ```
 
+And to use a locally hosted Ollama service, change the `chat_model` parameter:
+
+```sql
+SELECT vectorize.rag(
+    agent_name  => 'product_chat',
+    query       => 'What is a pencil?',
+    chat_model  => 'ollama/wizardlm2:7b'
+) -> 'chat_response';
+```
+
+```text
+" A pencil is a writing instrument that consists of a solid or gelignola wood core, known as the \"lead,\" encased in a cylindrical piece of breakable material (traditionally wood or plastic), which serves as the body of the pencil. The tip of the body is tapered to a point for writing, and it can mark paper with the imprint of the lead. When used on a sheet of paper, the combination of the pencil's lead and the paper creates a visible mark that is distinct from unmarked areas of the paper. Pencils are particularly well-suited for writing on paper, as they allow for precise control over the marks made."
+```
+
+
 :bulb: Note that the `-> 'chat_response'` addition selects for that field of the JSON object output. Removing it will show the full JSON object, including information on which documents were included in the contextual prompt.
 
 ## Updating Embeddings

docker-compose.yml

@@ -17,3 +17,11 @@ services:
       - 3001:3001
     environment:
       - OLLAMA_HOST=0.0.0.0:3001
+    # deploy:
+    #   replicas: 1
+    #   resources:
+    #     reservations:
+    #       devices:
+    #         - driver: nvidia
+    #           count: 1
+    #           capabilities: [gpu]

docs/api/index.md

@@ -1,4 +1,3 @@
 # PG Vectorize API Overview
 
 pg vectorize provides tools for two closely related tasks; vector search and retrieval augmented generation (RAG), and there are APIs dedicated to both of these tasks. Vector search is an important component of RAG and the RAG APIs depend on the vector search APIs. It could be helpful to think of the vector search APIs as lower level than RAG. However, relative to Postgres's APIs, both of these vectorize APIs are very high level.
-

docs/api/rag.md

@@ -15,8 +15,8 @@ vectorize.init_rag(
     "unique_record_id" TEXT,
     "column" TEXT,
     "schema" TEXT DEFAULT 'public',
-    "transformer" TEXT DEFAULT 'text-embedding-ada-002',
-    "search_alg" vectorize.SimilarityAlg DEFAULT 'pgv_cosine_similarity',
+    "transformer" TEXT DEFAULT 'openai/text-embedding-ada-002',
+    "index_dist_type" vectorize.IndexDist DEFAULT 'pgv_hnsw_cosine',
     "table_method" vectorize.TableMethod DEFAULT 'append'
 ) RETURNS TEXT
 ```
@@ -31,18 +31,18 @@ vectorize.init_rag(
 | column | text | The name of the column that contains the content that is used for context for RAG. |
 | schema | text | The name of the schema where the table is located. Defaults to 'public'. |
 | transformer | text | The name of the transformer to use for the embeddings. Defaults to 'text-embedding-ada-002'. |
-| search_alg | SimilarityAlg | The name of the search algorithm to use. Defaults to 'pgv_cosine_similarity'. |
+| index_dist_type | IndexDist | The name of index type to build. Defaults to 'pgv_hnsw_cosine'. |
 | table_method | TableMethod | The method to use for the table. Defaults to 'append', which adds a column to the existing table. |
 
 Example:
 
 ```sql
 select vectorize.init_rag(
-    agent_name => 'tembo_chat',
-    table_name => 'tembo_docs',
-    unique_record_id => 'document_name',
-    "column" => 'content',
-    transformer => 'sentence-transformers/all-MiniLM-L12-v2'
+    agent_name        => 'tembo_chat',
+    table_name        => 'tembo_docs',
+    unique_record_id  => 'document_name',
+    "column"          => 'content',
+    transformer       => 'sentence-transformers/all-MiniLM-L12-v2'
 );
 ```
 
@@ -56,7 +56,7 @@ select vectorize.init_rag(
 vectorize."rag"(
     "agent_name" TEXT,
     "query" TEXT,
-    "chat_model" TEXT DEFAULT 'gpt-3.5-turbo',
+    "chat_model" TEXT DEFAULT 'openai/gpt-3.5-turbo',
     "task" TEXT DEFAULT 'question_answer',
     "api_key" TEXT DEFAULT NULL,
     "num_context" INT DEFAULT 2,
@@ -81,10 +81,10 @@ vectorize."rag"(
 
 ```sql
 select vectorize.rag(
-    agent_name => 'tembo_support',
-    query => 'what are the major features from the tembo kubernetes operator?',
-    chat_model => 'gpt-3.5-turbo',
-    force_trim => 'true'
+    agent_name  => 'tembo_support',
+    query       => 'what are the major features from the tembo kubernetes operator?',
+    chat_model  => 'openai/gpt-3.5-turbo',
+    force_trim  => 'true'
 );
 ```
 
@@ -112,10 +112,10 @@ Filter the results to just the `chat_response`:
 
 ```sql
 select vectorize.rag(
-    agent_name => 'tembo_support',
-    query => 'what are the major features from the tembo kubernetes operator?',
-    chat_model => 'gpt-3.5-turbo',
-    force_trim => 'true'
+    agent_name  => 'tembo_support',
+    query       => 'what are the major features from the tembo kubernetes operator?',
+    chat_model  => 'gpt-3.5-turbo',
+    force_trim  => 'true'
 ) -> 'chat_response';
 ```
 

docs/api/search.md

@@ -15,8 +15,8 @@ vectorize."table"(
     "args" json DEFAULT '{}',
     "schema" TEXT DEFAULT 'public',
     "update_col" TEXT DEFAULT 'last_updated_at',
-    "transformer" TEXT DEFAULT 'text-embedding-ada-002',
-    "search_alg" vectorize.SimilarityAlg DEFAULT 'pgv_cosine_similarity',
+    "transformer" TEXT DEFAULT 'openai/text-embedding-ada-002',
+    "index_dist_type" vectorize.IndexDist DEFAULT 'pgv_hnsw_cosine',
     "table_method" vectorize.TableMethod DEFAULT 'join',
     "schedule" TEXT DEFAULT '* * * * *'
 ) RETURNS TEXT
@@ -32,7 +32,7 @@ vectorize."table"(
 | schema | text | The name of the schema where the table is located. Defaults to 'public'. |
 | update_col | text | Column specifying the last time the record was updated. Required for cron-like schedule. Defaults to `last_updated_at` |
 | transformer | text | The name of the transformer to use for the embeddings. Defaults to 'text-embedding-ada-002'. |
-| search_alg | SimilarityAlg | The name of the search algorithm to use. Defaults to 'pgv_cosine_similarity'. |
+| index_dist_type | IndexDist | The name of index type to build. Defaults to 'pgv_hnsw_cosine'. |
 | table_method | TableMethod | `join` to store embeddings in a new table in the vectorize schema. `append` to create columns for embeddings on the source table. Defaults to `join`. |
 | schedule | text | Accepts a cron-like input for a cron based updates. Or `realtime` to set up a trigger. |
 
@@ -47,12 +47,12 @@ Pass the API key into the function call via `args`.
 
 ```sql
 select vectorize.table(
-    job_name => 'product_search',
-    "table" => 'products',
+    job_name    => 'product_search',
+    "table"     => 'products',
     primary_key => 'product_id',
-    columns => ARRAY['product_name', 'description'],
-    transformer =>  'text-embedding-ada-002',
-    args => '{"api_key": "my-openai-key"}'
+    columns     => ARRAY['product_name', 'description'],
+    transformer =>  'openai/text-embedding-ada-002',
+    args        => '{"api_key": "my-openai-key"}'
 );
 ```
 
@@ -67,11 +67,11 @@ Then call `vectorize.table()` without providing the API key.
 
 ```sql
 select vectorize.table(
-    job_name => 'product_search',
-    "table" => 'products',
+    job_name    => 'product_search',
+    "table"     => 'products',
     primary_key => 'product_id',
-    columns => ARRAY['product_name', 'description'],
-    transformer =>  'text-embedding-ada-002'
+    columns     => ARRAY['product_name', 'description'],
+    transformer =>  'openai/text-embedding-ada-002'
 );
 ```
 
@@ -106,10 +106,10 @@ vectorize."search"(
 
 ```sql
 SELECT * FROM vectorize.search(
-    job_name => 'product_search',
-    query => 'mobile electronic devices',
-    return_columns => ARRAY['product_id', 'product_name'],
-    num_results => 3
+    job_name        => 'product_search',
+    query           => 'mobile electronic devices',
+    return_columns  => ARRAY['product_id', 'product_name'],
+    num_results     => 3
 );
 ```
 

docs/api/utilities.md

@@ -4,12 +4,12 @@
 
 Transforms a block of text to embeddings using the specified transformer.
 
-Requires the `vector-serve` container to be set via `vectorize.embedding_svc_url`, or an OpenAI key to be set if using OpenAI embedding models.
+Requires the `vector-serve` container to be set via `vectorize.embedding_service_url`, or an OpenAI key to be set if using OpenAI embedding models.
 
 ```sql
 vectorize."transform_embeddings"(
     "input" TEXT,
-    "model_name" TEXT DEFAULT 'text-embedding-ada-002',
+    "model_name" TEXT DEFAULT 'openai/text-embedding-ada-002',
     "api_key" TEXT DEFAULT NULL
 ) RETURNS double precision[]
 ```
@@ -26,8 +26,8 @@ vectorize."transform_embeddings"(
 
 ```sql
 select vectorize.transform_embeddings(
-    input => 'the quick brown fox jumped over the lazy dogs',
-    model_name => 'sentence-transformers/multi-qa-MiniLM-L6-dot-v1'
+    input       => 'the quick brown fox jumped over the lazy dogs',
+    model_name  => 'sentence-transformers/multi-qa-MiniLM-L6-dot-v1'
 );
 
 {-0.2556323707103729,-0.3213586211204529 ..., -0.0951206386089325}
@@ -37,7 +37,7 @@ select vectorize.transform_embeddings(
 
 Configure `vectorize` to run on a database other than the default `postgres`.
 
-Note that when making this change, it's also required to update `pg_cron` such that its corresponding background workers also connect to the appropriate database. 
+Note that when making this change, it's also required to update `pg_cron` such that its corresponding background workers also connect to the appropriate database.
 
 ### Example
 

docs/examples/openai_embeddings.md

@@ -22,22 +22,22 @@ Then create the job.
 
 ```sql
 SELECT vectorize.table(
-    job_name => 'product_search_openai',
-    "table" => 'products',
+    job_name    => 'product_search_openai',
+    "table"     => 'products',
     primary_key => 'product_id',
-    columns => ARRAY['product_name', 'description'],
-    transformer => 'text-embedding-ada-002'
+    columns     => ARRAY['product_name', 'description'],
+    transformer => 'openai/text-embedding-ada-002'
 );
 ```
 
 To search the table, use the `vectorize.search` function.
 
 ```sql
 SELECT * FROM vectorize.search(
-    job_name => 'product_search_openai',
-    query => 'accessories for mobile devices',
-    return_columns => ARRAY['product_id', 'product_name'],
-    num_results => 3
+    job_name        => 'product_search_openai',
+    query           => 'accessories for mobile devices',
+    return_columns  => ARRAY['product_id', 'product_name'],
+    num_results     => 3
 );
 ```
 

docs/examples/sentence_transformers.md

@@ -53,12 +53,12 @@ Create a job to vectorize the products table. We'll specify the tables primary k
 
 ```sql
 SELECT vectorize.table(
-    job_name => 'product_search_hf',
-    "table" => 'products',
+    job_name    => 'product_search_hf',
+    "table"     => 'products',
     primary_key => 'product_id',
-    columns => ARRAY['product_name', 'description'],
+    columns     => ARRAY['product_name', 'description'],
     transformer => 'sentence-transformers/multi-qa-MiniLM-L6-dot-v1',
-    scheduler => 'realtime'
+    scheduler   => 'realtime'
 );
 ```
 
@@ -68,10 +68,10 @@ Then search,
 
 ```sql
 SELECT * FROM vectorize.search(
-    job_name => 'product_search_hf',
-    query => 'accessories for mobile devices',
-    return_columns => ARRAY['product_id', 'product_name'],
-    num_results => 3
+    job_name        => 'product_search_hf',
+    query           => 'accessories for mobile devices',
+    return_columns  => ARRAY['product_id', 'product_name'],
+    num_results     => 3
 );
 
                                        search_results