For AI agents: the complete documentation index is available at https://docs.ovhcloud.com/fr/llms.txt, the full documentation bundle is available at https://docs.ovhcloud.com/fr/llms-full.txt, and this page is available as Markdown at https://docs.ovhcloud.com/fr/guides/public-cloud/databases/postgresql-tuto-vector-search-ai-endpoints.md.
Aller au contenu

Créer une recherche sémantique avec AI Endpoints et Public Cloud Databases pour PostgreSQL

Voir en Markdown

Découvrez comment vectoriser vos textes avec AI Endpoints, les stocker dans un service PostgreSQL managé avec pgvector et les rechercher par le sens

Objectif

Une recherche sémantique retrouve des textes par leur sens plutôt que par leurs mots exacts. Chaque texte est transformé en vecteur, appelé embedding, par un modèle d'embedding. Deux textes de sens proche obtiennent des vecteurs proches : une question peut ainsi être rapprochée des passages qui y répondent, même s'ils n'ont aucun mot en commun.

Ce tutoriel construit une telle recherche de bout en bout, entièrement chez OVHcloud :

  • AI Endpoints transforme vos textes et vos questions en vecteurs ;
  • un service Public Cloud Databases pour PostgreSQL les stocke avec l'extension vector (pgvector) et retrouve les plus proches grâce à un index HNSW.

Il couvre aussi les points à connaître avant de commencer : les droits nécessaires dans PostgreSQL, le nombre de textes par requête et le type de colonne à choisir selon le modèle.

Warning

OVHcloud fournit des services dont vous êtes responsable de la configuration et de la gestion. Vous êtes donc responsable de leur bon fonctionnement.

Ce tutoriel est conçu pour vous aider autant que possible dans les tâches courantes. Si vous rencontrez des difficultés pour réaliser ces actions, veuillez contacter un prestataire de services spécialisé et/ou en discuter avec notre communauté d'utilisateurs. OVHcloud ne peut pas vous fournir d'assistance technique à ce sujet.

Prérequis

Info

Sur un projet partagé via IAM, seuls les utilisateurs disposant des droits administrateur peuvent créer une clé d'API AI Endpoints. Si vous ne pouvez pas en créer une, adressez-vous à l'administrateur du projet.

Sans clé, AI Endpoints accepte 2 requêtes par minute et par modèle : de quoi essayer les exemples ci-dessous, pas de traiter un corpus. Au-delà, les appels échouent avec API rate limit exceeded (HTTP 429).


Accès à la console OVHcloud

  • Lien direct :
  • Pour accéder à vos services : Public Cloud > Sélectionnez votre projet > Bases de données

En pratique

Étape 1 - Préparer la base de données

Installer l'extension

Connectez-vous en avnadmin à la base que vous allez utiliser, par exemple defaultdb, et installez l'extension. Son nom en SQL est vector :

CREATE EXTENSION IF NOT EXISTS vector;

Créer un utilisateur applicatif et son schéma

N'utilisez pas avnadmin dans votre application : créez un utilisateur dédié en SQL, en tant qu'avnadmin, et donnez-lui son propre schéma :

CREATE ROLE "rag_app" LOGIN;
CREATE SCHEMA "rag" AUTHORIZATION "rag_app";
Info

Sur PostgreSQL 15, CREATE SCHEMA échoue avec must be member of role "rag_app". Rendez avnadmin membre du rôle le temps de la commande :

GRANT "rag_app" TO avnadmin;
CREATE SCHEMA "rag" AUTHORIZATION "rag_app";
REVOKE "rag_app" FROM avnadmin;

À partir de PostgreSQL 16, avnadmin est membre des rôles qu'il crée : cette étape n'est pas nécessaire.

Définissez ensuite son mot de passe avec la méta-commande \password de psql :

defaultdb=> \password rag_app
Warning

Un utilisateur créé depuis l'onglet Utilisateurs de la console OVHcloud ou via l'API ne peut pas créer de tables : il obtient permission denied for schema public, y compris dans une base créée depuis la console OVHcloud. Le schéma appartenant à rag_app ci-dessus règle ce problème. Pour d'autres façons d'accorder des privilèges, consultez le guide « Gérer les utilisateurs, rôles et privilèges ».

Étape 2 - Choisir le modèle et le type de colonne

AI Endpoints propose plusieurs modèles d'embedding. La taille de leurs vecteurs, appelée dimension, détermine le type de colonne que vous pouvez indexer :

ModèleDimensionContexteType de colonne à indexer
bge-m31 0248 192 tokensvector(1024)
bge-multilingual-gemma23 5848 192 tokenshalfvec(3584)
Qwen3-Embedding-8B4 096, ou moins avec le paramètre dimensions32 768 tokensvector(N) avec dimensions fixé à N, 2 000 au maximum

L'index HNSW de pgvector accepte :

  • jusqu'à 2 000 dimensions sur une colonne vector. Au-delà, la création de l'index échoue avec column cannot have more than 2000 dimensions for hnsw index ;
  • jusqu'à 4 000 dimensions sur une colonne halfvec, qui stocke chaque valeur sur 2 octets au lieu de 4.

Une valeur vector(d) occupe 4 × d + 8 octets et une valeur halfvec(d) 2 × d + 8 octets. Dans notre test avec 2 000 lignes de 1 024 dimensions, la table occupait 11 Mo en vector et 5,6 Mo en halfvec, et l'index HNSW 5,6 Mo et 4,3 Mo.

Warning

Choisissez le type de colonne avant de charger vos données. La limite de dimensions n'apparaît qu'à la création de l'index, une fois les vecteurs enregistrés.

Qwen3-Embedding-8B renvoie 4 096 dimensions par défaut, au-dessus des deux limites. Ajoutez le paramètre dimensions à la requête, par exemple "dimensions": 1024, pour recevoir des vecteurs plus courts qui tiennent dans une colonne vector. Il accepte une valeur de 32 à 4 096.

Moins de dimensions donnent une table et un index plus petits, au prix d'un peu de précision. Dans notre test avec trois passages et trois questions, chaque question trouvait toujours le bon passage à 1 024 et à 256 dimensions, avec une avance plus faible sur le passage suivant à 256. Comparez quelques valeurs sur vos propres données avant de choisir : jusqu'à 2 000 dimensions dans une colonne vector, jusqu'à 4 000 dans une colonne halfvec.

Ce tutoriel utilise bge-m3, un modèle multilingue et le plus rapide des trois.

Créer la table

Connectez-vous en tant que rag_app et créez la table dans son schéma (pour bge-multilingual-gemma2, déclarez emb halfvec(3584) à la place de emb vector(1024)) :

CREATE TABLE rag.docs (
  id   int PRIMARY KEY,
  body text,
  emb  vector(1024)
);

Étape 3 - Transformer vos textes en vecteurs

AI Endpoints expose une route d'embeddings compatible OpenAI. Envoyez 25 textes au maximum par requête : au-delà, la requête est refusée avec une erreur HTTP 400, given batch size overflow maximal one.

import json
import os
import urllib.request

URL = "https://oai.endpoints.kepler.ai.cloud.ovh.net/v1/embeddings"
KEY = os.environ["AI_ENDPOINT_API_KEY"]
BATCH = 25  # nombre maximal de textes par requête


def embed(texts, model="bge-m3", dimensions=None):
    body = {"model": model, "input": texts}
    if dimensions:  # Qwen3-Embedding-8B uniquement
        body["dimensions"] = dimensions
    req = urllib.request.Request(
        URL,
        data=json.dumps(body).encode(),
        headers={"Content-Type": "application/json", "Authorization": "Bearer " + KEY},
    )
    return [e["embedding"] for e in json.load(urllib.request.urlopen(req))["data"]]


def embed_all(texts, **kwargs):
    vectors = []
    for i in range(0, len(texts), BATCH):
        vectors += embed(texts[i:i + BATCH], **kwargs)
    return vectors

Avec une clé d'API, AI Endpoints accepte 400 requêtes par minute et par modèle. Pour vectoriser un gros corpus plus vite, envoyez plusieurs lots en parallèle en respectant cette limite.

Étape 4 - Charger les vecteurs dans PostgreSQL

import psycopg2
from psycopg2.extras import execute_values

texts = [
    "The museum opens every day from 9 am to 6 pm, except on Mondays.",
    "Children under 12 enter for free when accompanied by an adult.",
    "Guided tours of the medieval wing start at 10 am and 3 pm.",
]

conn = psycopg2.connect(
    host="<service-host>", port=20184, dbname="defaultdb",
    user="rag_app", password=os.environ["PG_PASSWORD"], sslmode="require",
)
cur = conn.cursor()

vectors = embed_all(texts)
execute_values(
    cur,
    "INSERT INTO rag.docs (id, body, emb) VALUES %s",
    [(i, t, str(v)) for i, (t, v) in enumerate(zip(texts, vectors))],
)
conn.commit()

Remplacez <service-host> et le port par les valeurs affichées dans la section Informations de connexion de votre service.

Une fois les données chargées, créez l'index HNSW pour la distance cosinus (pour une colonne halfvec, utilisez halfvec_cosine_ops) :

CREATE INDEX ON rag.docs USING hnsw (emb vector_cosine_ops);
Info

Construire l'index après le chargement est plus rapide que de le mettre à jour ligne par ligne. Les lignes insérées ensuite sont ajoutées automatiquement à l'index.

Étape 5 - Rechercher par le sens

Transformez la question en vecteur avec le même modèle, puis triez les lignes par distance cosinus (<=>) :

question = "Is it free for kids?"
q = embed([question])[0]

cur.execute(
    "SELECT id, body, emb <=> %s::vector(1024) AS distance "
    "FROM rag.docs ORDER BY distance LIMIT 3",
    (str(q),),
)
for row in cur.fetchall():
    print(row)

Le passage sur les enfants arrive en premier, bien qu'il n'ait aucun mot en commun avec la question.

Pour vérifier que l'index est utilisé, préfixez la requête par EXPLAIN ANALYZE. Sur une table de quelques lignes, comme ici, PostgreSQL préfère lire toute la table et le plan affiche un Seq Scan suivi d'un Sort. Sur un vrai corpus, ou après SET enable_seqscan = off; dans votre session, le plan affiche un Index Scan sur l'index HNSW, ici docs_emb_idx.

Info

Utilisez toujours le même modèle, et la même valeur de dimensions pour Qwen3-Embedding-8B, pour vos textes et pour vos questions. Les vecteurs de deux modèles différents ne sont pas comparables.

Dépannage

ErreurCause et solution
permission denied for schema publicL'utilisateur a été créé depuis la console OVHcloud ou via l'API. Créez le rôle applicatif et son schéma en SQL avec avnadmin, comme à l'étape 1.
must be member of role "rag_app"PostgreSQL 15 uniquement. Accordez le rôle à avnadmin avant CREATE SCHEMA, puis retirez-le.
column cannot have more than 2000 dimensions for hnsw indexLes vecteurs ont plus de 2 000 dimensions. Utilisez une colonne halfvec, ou demandez moins de dimensions à Qwen3-Embedding-8B.
column cannot have more than 4000 dimensions for hnsw indexMême une colonne halfvec est limitée à 4 000 dimensions. Utilisez le paramètre dimensions de Qwen3-Embedding-8B.
HTTP 400 given batch size overflow maximal onePlus de 25 textes dans une requête. Envoyez-les par lots de 25.
HTTP 400 `dimensions` field must be between 32 and 4096La valeur de dimensions est hors de la plage acceptée par le modèle.
HTTP 403 Forbidden: authentication failedLa clé d'API est invalide, expirée ou révoquée. Générez-en une nouvelle.
HTTP 429 API rate limit exceededSans clé, 2 requêtes par minute et par modèle. Utilisez une clé d'API, ou espacez les requêtes.

Aller plus loin

Extensions disponibles sur Public Cloud Databases pour PostgreSQL

Gérer les utilisateurs, rôles et privilèges

Premiers pas avec AI Endpoints

Pour une formation ou une assistance technique sur la mise en œuvre de nos solutions, contactez votre commercial ou consultez la page Professional Services pour obtenir un devis et faire analyser votre projet par nos experts.

Votre avis nous intéresse !

Nous serions ravis de répondre à vos questions et apprécions tout retour que vous pourriez nous faire.

Vous êtes sur Discord ? Rejoignez notre chaîne via https://discord.gg/ovhcloud et interagissez directement avec l'équipe qui développe notre service de bases de données !

Échangez avec notre communauté d'utilisateurs.

Cette page vous a-t-elle aidé ?