Build a semantic search with AI Endpoints and Public Cloud Databases for PostgreSQL
Find out how to turn your texts into vectors with AI Endpoints, store them in a managed PostgreSQL service with pgvector, and search them by meaning
Objective
A semantic search finds texts by their meaning rather than by their exact words. Each text is turned into a vector, called an embedding, by an embedding model. Texts with similar meanings get similar vectors, so a question can be matched with the passages that answer it, even when they share no words.
This tutorial builds such a search end to end, entirely on OVHcloud:
- AI Endpoints turns your texts and your questions into vectors;
- a Public Cloud Databases for PostgreSQL service stores them with the
vectorextension (pgvector) and finds the closest ones with an HNSW index.
It also covers what you need to know before you start: the rights needed in PostgreSQL, the number of texts per request, and the column type to choose according to the model.
OVHcloud provides services for which you are responsible for their configuration and management. You are therefore responsible for their proper functioning.
This tutorial is designed to help you as much as possible with common tasks. If you are having difficulty performing these actions, please contact a specialised service provider and/or discuss it with our community of users on https://community.ovhcloud.com/. OVHcloud can't provide you with technical support in this regard.
Requirements
- A Public Cloud project in your OVHcloud account.
- A Public Cloud Databases for PostgreSQL service, version 15 or later, that accepts connections from your machine (the Configure incoming connections guide explains how to authorise your IP address).
- Command-line access to your service with the
avnadminuser (the Connect using the CLI guide can help you to meet this requirement). - An AI Endpoints API key (see Getting started with AI Endpoints).
- A Python 3 environment with the
psycopg2-binarypackage.
On a project shared through IAM, only users with administrator rights can create an AI Endpoints API key. If you cannot create one, ask your project administrator.
Without a key, AI Endpoints accepts 2 requests per minute per model: enough to try the examples below, not to process a corpus. Beyond that, calls fail with API rate limit exceeded (HTTP 429).
OVHcloud Console Access
- Direct link:
- Navigation path:
Public Cloud> Select your project >Databases
Instructions
Step 1 - Preparing the database
Installing the extension
Connect as avnadmin to the database you will use, for example defaultdb, and install the extension. Its name in SQL is vector:
Creating an application user with its own schema
Do not use avnadmin in your application: create a dedicated user in SQL, as avnadmin, and give it its own schema:
On PostgreSQL 15, CREATE SCHEMA fails with must be member of role "rag_app". Make avnadmin a member of the role for the time of the command:
From PostgreSQL 16, avnadmin is a member of the roles it creates, so this step is not needed.
Then set its password with psql's \password meta-command:
A user created from the Users tab of the OVHcloud Console or with the API cannot create tables: it gets permission denied for schema public, including in a database created from the OVHcloud Console. The schema owned by rag_app above solves this. For more ways to grant privileges, see Manage users, roles and privileges.
Step 2 - Choosing the model and the column type
AI Endpoints offers several embedding models. The size of their vectors, called the dimension, determines which column type you can index:
The HNSW index of pgvector accepts:
- up to 2,000 dimensions on a
vectorcolumn. Beyond that, index creation fails withcolumn cannot have more than 2000 dimensions for hnsw index; - up to 4,000 dimensions on a
halfveccolumn, which stores each value on 2 bytes instead of 4.
A vector(d) value takes 4 × d + 8 bytes and a halfvec(d) value 2 × d + 8 bytes. In our test with 2,000 rows of 1,024 dimensions, the table took 11 MB as vector and 5.6 MB as halfvec, and the HNSW index 5.6 MB and 4.3 MB.
Choose the column type before loading your data. The dimension limit only shows when you create the index, after the vectors are stored.
Qwen3-Embedding-8B returns 4,096 dimensions by default, above both limits. Add the dimensions parameter to the request, for example "dimensions": 1024, to receive shorter vectors that fit a vector column. It accepts a value from 32 to 4,096.
Fewer dimensions mean a smaller table and index, at the cost of some precision. In our test with three passages and three questions, each question still found the right passage at 1,024 and at 256 dimensions, with a smaller lead over the next passage at 256. Compare a few values on your own data before choosing: up to 2,000 dimensions in a vector column, up to 4,000 in a halfvec column.
This tutorial uses bge-m3, which is multilingual and the fastest of the three.
Creating the table
Connect as rag_app and create the table in its schema (for bge-multilingual-gemma2, declare emb halfvec(3584) instead of emb vector(1024)):
Step 3 - Turning your texts into vectors
AI Endpoints exposes an OpenAI-compatible embeddings route. Send at most 25 texts per request: beyond that, the request is rejected with an HTTP 400 error, given batch size overflow maximal one.
With an API key, AI Endpoints accepts 400 requests per minute per model. To embed a large corpus faster, send several batches in parallel within this limit.
Step 4 - Loading the vectors into PostgreSQL
Replace <service-host> and the port with the values shown in the Connection information section of your service.
Once the data is loaded, create the HNSW index for the cosine distance (for a halfvec column, use halfvec_cosine_ops):
Building the index after loading is faster than updating it row by row. Rows inserted later are added to the index automatically.
Step 5 - Searching by meaning
Turn the question into a vector with the same model, then sort the rows by cosine distance (<=>):
The passage about children comes first, even though it shares no words with the question.
To check that the index is used, prefix the query with EXPLAIN ANALYZE. On a table of a few rows, as here, PostgreSQL prefers to read the whole table and the plan shows a Seq Scan followed by a Sort. On a real corpus, or after SET enable_seqscan = off; in your session, the plan shows an Index Scan on the HNSW index, here docs_emb_idx.
Always use the same model, and the same dimensions value for Qwen3-Embedding-8B, for your texts and for your questions. Vectors from two different models cannot be compared.
Troubleshooting
Go further
Available extensions on Public Cloud Databases for PostgreSQL
Manage users, roles and privileges
Getting started with AI Endpoints
For training or technical assistance implementing our solutions, contact your sales representative or visit our Professional Services page to request a quote and have your project analysed by our experts.
We want your feedback!
We would love to help answer questions and appreciate any feedback you may have.
Are you on Discord? Connect to our channel at https://discord.gg/ovhcloud and interact directly with the team that builds our databases service!
Join our community of users.