Семантычны пошук у PostgreSQL з pgvector і .NET: практычная налада
Захоўваем эмбедынгі побач з рэляцыйнымі данымі, будуем індэксы HNSW ці IVFFlat, фільтруем і змешваем гібрыдныя рэйтынгі і ацэньваем, калі pgvector дастаткова для праграмы.
Крыніцы: Semantic Search with PostgreSQL: Pragmatism Beats Hype – Most of the Time
Дахоўка сэмантычнага пошуку ў прыкладнай програме зазвычай прыносіць той самы скоры кантэкст: Pinecone, Weaviate, Qdrant, Milvus або іншы спецыялізаваны вектарны база дадзэння. Будзь-кой з іх можа стаць правам рашэннем. Тым не менш, багатыя прыкладнікі вядома запускаюць экземпляр PostgreSQL, і для багатых задач сэмантычнага пошуку гэтая база дадзэння можа сама сабе адмаўляць такія заведаменні.
Элемент, які дапамагае гэтаму функцыонаваць, — гэта pgvector, адкрытыя пашырэнне, якое дае Postgres вектарны тып і можлівасць пошуку за сэмабільнасцю. Эмбедынгі знаходзяцца празаўсёды з рэляцыйнымі дадзеннямі і запытваюцца за дапамогою звычайнага SQL. Па-першае, трэба запускаць менш частак, а па-другое, ёсць структурная перадчыннасць: няма нічога, што трэба сінхронізаваць, існуе толькі адна адміністрацыя, дзе зберагаецца правда, а інфраструктуру дадаюць толькі тады, калі таго выклікае навантажэнне.
Сэмантычны пошук у адной фразе
Класычный пошук падчырывае словы, а сэмантычны пошук — значэнні. Запіт на кшталт "Як мне пераясці перавал?" можа знайсці тэкст пра горны перавал, а не пра корыдор школы, таму што і запіт, і дакументы ператвараюцца ў чысловыя вектары, вядомыя як эмбеддынгі.
Працэс складаецца з чатырох крокаў:
- Ператварыць тэкст у вектар эмбеддынга.
- Зберагчы вектар у PostgreSQL.
- Ператварыць запіт на пошук у той жа вектарны прастор.
- Знайсці зберажаныя вектары, якія знаходзяцца найбліжэй да вектара запіта.
Фраза "той жа вектарны прастор" мае важлівэ значэнне. Эмбеддынгі з разных модэляў не можна свабодна сумешчаць.
Спачатку выберыце модэль эмбеддынга
Мадэль выклікаецца раней шыматлу, таму што яна вялічыню вектара, косцт выканання за адзін запіт, мовы, якія падтрымваюцца, а таксама можлівасць ўпрацоўкі яе локальна. У модэлі OpenAI text-embedding-3-small зазвычай вікорыстоўваецца столбец vector(1536). Іншыя модэлі, укладзеныя локальна чырз Ollama, можа даўаць вектары іншай вялічыны.
Гэта не дробны дэталі. PostgreSQL адмовляецца прыймаць вектары з неправільной колькасцю вялічын.
Змена модэлі пазней значыць міграцыю дадзеных. Вам даведзецца:
- дадаць новы столбец чы рэгістар з вектарамі;
- перзануроўваць кожны дакумент занова;
- перзбудаваць індэкс вектараў;
- ніколі не пораўнваць старыя і новыя вектары безпосерэдна.
Інсталяванне pgvector
Увімкніце пашырэнне аднае раз пры кожнай базе дадзеных:
CREATE EXTENSION IF NOT EXISTS vector;
У адмініструемых сервісах PostgreSQL пераканайцеся, чы рэшэнне pgvector адпавядае вашам плану і версіі Postgres. Ён падтрымліваецца ў багатых варыянтах, але спытайцеся яго перад тым, як планаваць працу з ім.
Схема: зберагчык фрагментаў
Для короткіх запісаў дастатнека аднаго вектара на рэч. Для справжніх дакументаў зазвычай лепшая вбудоўваць фрагменты, адтуды што длігі дакумент можа абходзіцца калькама тэм, а аднам вектарам для всьго гэтага часта ўскладняецца ўзаецнае адзначэнне ўсіх элементаў. Практычны падход:
CREATE TABLE documents (
id BIGSERIAL PRIMARY KEY,
title TEXT NOT NULL,
source TEXT,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE TABLE document_chunks (
id BIGSERIAL PRIMARY KEY,
document_id BIGINT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
chunk_index INTEGER NOT NULL,
content TEXT NOT NULL,
embedding vector(1536) NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
UNIQUE (document_id, chunk_index)
);
Зберагаюце vector(1536) толькі тады, калі ваша мадэль справды вяртае 1536 цяжоў, а іншым чынам зменяйце яго так, каб ён паспадзяраваў.
Ўжыце яго з .NET за дапамогою Npgsql
Дадзіце пакеты:
dotnet add package Npgsql
dotnet add package Pgvector
Корыстнікам Dapper таксама патрэбна ўсё ўсё адна рэч:
dotnet add package Pgvector.Dapper
За дапамою простага Npgsql, вызываеце UseVector() у кампаніі стварэння джэра дадзеных:
using Npgsql;
using Pgvector;
var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
dataSourceBuilder.UseVector();
await using var dataSource = dataSourceBuilder.Build();
У працуючай сістэме ствараюць расшырэнні і табелі за дапамою міграцый чыра прадстаўлення рэсурсаў. Калі расшырэнні ствараецца пад час выканання, перазавантажыце тыпы PostgreSQL для з’яноўкі пры выкарыстоўванні новага тыпу.
Атрыманне эмбедынгаў з OpenAI
SDK OpenAI .NET апускае кліента для атрымання эмбедынгаў:
using OpenAI.Embeddings;
var embeddingClient = new EmbeddingClient("text-embedding-3-small", apiKey);
async Task<float[]> GetEmbeddingAsync(string text)
{
var result = await embeddingClient.GenerateEmbeddingAsync(text);
return result.Value.ToFloats().ToArray();
}
Для локальных эмбедынгаў выкорыстоўваюце локальную мадэль праз будзь-каго з прадаўцоў, якія вам паспадабляюцца. Правілле застаецца тым жа: мадэль, якая індэксуе дакументы, і мадэль, якая стварае эмбедынгі для запытак, должны збігацца, або прынеймні быць намерна сумеснымі. Ніколі не індэксуйце з адной мадэллю і не шукаце з іншай.
Зберагчыч частку
async Task InsertChunkAsync(
long documentId,
int chunkIndex,
string content,
CancellationToken cancellationToken = default)
{
var embedding = await GetEmbeddingAsync(content);
var vector = new Vector(embedding);
await using var conn = await dataSource.OpenConnectionAsync(cancellationToken);
await using var cmd = new NpgsqlCommand("""
INSERT INTO document_chunks (document_id, chunk_index, content, embedding)
VALUES (@documentId, @chunkIndex, @content, @embedding)
ON CONFLICT (document_id, chunk_index)
DO UPDATE SET
content = EXCLUDED.content,
embedding = EXCLUDED.embedding
""", conn);
cmd.Parameters.AddWithValue("documentId", documentId);
cmd.Parameters.AddWithValue("chunkIndex", chunkIndex);
cmd.Parameters.AddWithValue("content", content);
cmd.Parameters.AddWithValue("embedding", vector);
await cmd.ExecuteNonQueryAsync(cancellationToken);
}
Шлях апдэйта ўсёга найважлівейшы. Калі змініцца тэкст часткі, яе умяшчэнне таксама павінна змяніцца, і самэ гэта прычына, чаму оператывацыя upsert адбываецца для якіх-небудзь двух разам.
Адкрыцья пошуку
Аператар <=> вычысляе косінусавы абэкт, пры чым меньшая цыфра означае болей блізкую падобнасць. Сортаванне у адрастуючым парадку вяртае спачатку найбліжэйшыя вектары.
public sealed record SearchResult(
long DocumentId,
long ChunkId,
string Title,
string Content,
double Distance);
async Task<List<SearchResult>> SearchAsync(
string query,
int limit = 5,
CancellationToken cancellationToken = default)
{
var queryEmbedding = await GetEmbeddingAsync(query);
var queryVector = new Vector(queryEmbedding);
await using var conn = await dataSource.OpenConnectionAsync(cancellationToken);
await using var cmd = new NpgsqlCommand("""
SELECT d.id,
c.id,
d.title,
c.content,
c.embedding <=> @queryVector AS distance
FROM document_chunks c
JOIN documents d ON d.id = c.document_id
ORDER BY c.embedding <=> @queryVector
LIMIT @limit
""", conn);
cmd.Parameters.AddWithValue("queryVector", queryVector);
cmd.Parameters.AddWithValue("limit", limit);
var results = new List<SearchResult>();
await using var reader = await cmd.ExecuteReaderAsync(cancellationToken);
while (await reader.ReadAsync(cancellationToken))
{
results.Add(new SearchResult(
DocumentId: reader.GetInt64(0),
ChunkId: reader.GetInt64(1),
Title: reader.GetString(2),
Content: reader.GetString(3),
Distance: reader.GetDouble(4)));
}
return results;
}
Заўважкі: запіт сортаваецца безпасульна за выразам адстані. За дапамогою індэксаў pgvector формула ORDER BY embedding <=> @query LIMIT n дазволяе планавальніку выкарыстоўваць індэкс.
Операторы адстані
pgvector прысвячае калькольнік кількох оператораў:
| Оператор | Што мерыць |
|---|---|
<-> | Евклідава (L2) адстань |
<=> | Косінава адстань |
<#> | Негатыўны внутршній добутак |
<+> | Таксікабова (L1) адстань |
Для эмбеддынгаў тэксту косінава адстань ўтварае правільны стандартны выбар.
Індэксы HNSW
Без індэкса PostgreSQL скануе весь таблыц для кожнага пошуку на адпаведнасць вектараў. Гэта проста і точна, але швынчуецца з ростам колькасці вектараў. HNSW часта являецца найлепшым першым індэксам для пошуку ў застосоўках:
CREATE INDEX document_chunks_embedding_hnsw_idx
ON document_chunks
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
Два параметра ўключаюць:
m– максымальная колькасць з’яўленняў на адны шар, якая за замовчаннем становіць 16;ef_construction– розмер спісока кандыдатаў пад час стварэння, які за замовчаннем становіць 64.
Большыя значэнні можа падняць рывень запам’ятовання, але займаць больш памяці і здымаць час стварэння.
Рывень запам’ятовання таксама можна налаштаваць пад час запіту для пэўнай сесіі:
SET hnsw.ef_search = 100;
альбо толькі ў межах адной транзакцыі:
BEGIN;
SET LOCAL hnsw.ef_search = 100;
SELECT ...
COMMIT;
Памятаце, што HNSW ўзьмашчы. Ён жэрцавае ідэальную прыгадальнасць зарады шырокія.
IVFFlat як альтэрнатыва
IVFFlat можа выкарыстоўваць менш памяці і будавацца быстрэй за HNSW, хоць яго компрэсія межы шырокія і прыгадальнасцю зазвычай горшая.
CREATE INDEX document_chunks_embedding_ivfflat_idx
ON document_chunks
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);
Не ствараце індэкс IVFFlat на порожній табліцы, адколькі ёму патрэбны існуючыя радкі для стварэння яго спісаў. Як прыбліжны пачатак для lists, табліца з 10 000 вектараў падходзіць прыблізна для 10 спісаў, а не для 100.
Пад час запыту налаштавайце пробы:
SET ivfflat.probes = 10;
Большая колька зондаў павышае точнасць выкарыстоўвання даных і спамячвае запыткі.
Фільтрацыя і гібрыдны пошук
Адной з главных прычын выбору pgvector ёст тое, што вектары знаходзяцца рэдага рэляцыйных даных. Можна спачатку фільтрацыяваць, а потым класіфікуваць:
SELECT d.id, d.title, c.content, c.embedding <=> @queryVector AS distance
FROM document_chunks c
JOIN documents d ON d.id = c.document_id
WHERE d.created_at > NOW() - INTERVAL '30 days'
AND d.source = 'documentation'
ORDER BY c.embedding <=> @queryVector
LIMIT 10;
Для справжньага гібрыднага пошуку не трэба вычысляць ранг ключавага слова, а потым ігнараваць яго. Неабяжна з’едыніць сэмантычны ранг і ранг ключавага слова. Адны з практычных падходаў — стварэнне рэйтынгу па прыему фузыі взаімных рангаў:
WITH semantic AS (
SELECT c.id,
row_number() OVER (ORDER BY c.embedding <=> @queryVector) AS semantic_rank
FROM document_chunks c
LIMIT 100
),
keyword AS (
SELECT c.id,
row_number() OVER (
ORDER BY ts_rank_cd(
to_tsvector('english', c.content),
plainto_tsquery('english', @query)
) DESC
) AS keyword_rank
FROM document_chunks c
WHERE to_tsvector('english', c.content) @@ plainto_tsquery('english', @query)
LIMIT 100
)
SELECT d.id AS document_id,
c.id AS chunk_id,
d.title,
c.content,
COALESCE(1.0 / (60 + semantic.semantic_rank), 0) +
COALESCE(1.0 / (60 + keyword.keyword_rank), 0) AS score
FROM semantic
FULL OUTER JOIN keyword ON keyword.id = semantic.id
JOIN document_chunks c ON c.id = COALESCE(semantic.id, keyword.id)
JOIN documents d ON d.id = c.document_id
ORDER BY score DESC
LIMIT 10;
Гэта не ўсё едынственны спосаб прыяўлення гэтых двух элементаў, але ён робіць логіку ранжыравання відным.
Калі падходзіць pgvector
Гэта супернагледны выбар, калі:
- PostgreSQL вялікай часткай ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ў
- Вы хачэце адмініструемую службу з спецыялізаванымі операцыямі вектарнага пошуку;
- Вам патрэбны болейшыя можлівасці з гібрыднага пошуку, перыякоравання рэзультатаў чы сортавання, чым надае Postgres;
- Ваша каманда не мае глыбокых навыкаў у вікорыстоўванні PostgreSQL;
- Ізоляцыя кількох корыстувачаў і масштабаванне ўсё час застаюцца ключовымі патрэбамі.
Гэта не стосуецца ідэялогіі. Гэта стосуецца адпаведнасці службы вашым аперацыйным задачам.
Полны канцэнтры ASP.NET Core
app.MapGet("/search", async (
string q,
NpgsqlDataSource db,
CancellationToken cancellationToken) =>
{
var queryEmbedding = await GetEmbeddingAsync(q);
var queryVector = new Vector(queryEmbedding);
await using var conn = await db.OpenConnectionAsync(cancellationToken);
await using var cmd = new NpgsqlCommand("""
SELECT d.id,
c.id,
d.title,
c.content,
c.embedding <=> @v AS distance
FROM document_chunks c
JOIN documents d ON d.id = c.document_id
ORDER BY c.embedding <=> @v
LIMIT 5
""", conn);
cmd.Parameters.AddWithValue("v", queryVector);
var results = new List<object>();
await using var reader = await cmd.ExecuteReaderAsync(cancellationToken);
while (await reader.ReadAsync(cancellationToken))
{
results.Add(new
{
documentId = reader.GetInt64(0),
chunkId = reader.GetInt64(1),
title = reader.GetString(2),
content = reader.GetString(3),
distance = reader.GetDouble(4)
});
}
return Results.Ok(results);
});
Што застаецца пасля гэтага
Семантычныя пошукі не завжды вымагаюць окалічнай базы вектараў. Калі PostgreSQL вялікі час зберагае вашы асалідныя даны, pgvector дазволяе зберагаць эмбеддынгі разам з рэляцыйнымі данымі, выконваць запыты да іх на SQL, фільтруваць іх за звычайнымі умовамі і зберагаць транзакцыі ў адной сістэме.
Калькі правілы дапамагаюць падтрымваць чыстасцю налаштавання:
- спачатку выберыце мадэль эмбеддынгу, а пасля — выразнасць вектара;
- ніколі не сумешайвайце эмбеддынгі з разных модэляў;
- раздзеліце дакументы, якія ўздовжкі або стосуюцца калькі тэм;
- дадзіце індэкс толькі тады, калі табела стане достатняя, каб ён быў неабходны;
- памятайце, што HNSW і IVFFlat ўжоўляюць расчыты;
- зміну модэля трэба спрыятаць як міграцыю даных.
Для багаторох прымэнняў у працэсе вырабаткі pgvector даводзіцца падступны прынцыпова. Але гэта не значыць, што спецыяльныя базы дадзеных для вектараў не патрэбны. Проста найпростэйшая надзеяная архітэктура часта заставляе дадзеныя застацца там, дзе яны вучыцца.
Для дальнейшага чытання паглядзіце README к пакету pgvector, яго .NET пакет, дапаможнік OpenAI .NET SDK і гід па эмбедынгах, а таксама дакументацыю Microsoft.Extensions.AI.