Tutorial: Criar uma pesquisa semântica com o Banco de Dados do Azure para PostgreSQL e Azure OpenAI

2025-06-27

APLICA-SE A: Banco de Dados do Azure para PostgreSQL - Servidor Flexível

Este tutorial prático mostra como criar um aplicativo de pesquisa semântica usando o Banco de Dados do Azure para PostgreSQL e Azure OpenAI.

A pesquisa semântica faz pesquisas baseadas na semântica. A pesquisa lexical padrão faz pesquisas com base em palavras-chave fornecidas numa consulta. Por exemplo, seu conjunto de dados de receita pode não conter rótulos como sem glúten, vegano, sem laticínios, sem frutas ou sobremesa, mas essas características podem ser deduzidas dos ingredientes. A ideia é emitir essas consultas semânticas e obter resultados de pesquisa relevantes.

Neste tutorial, você:

Identifique os cenários de pesquisa e os campos de dados que estarão envolvidos em uma pesquisa.
Para cada campo de dados envolvido em uma pesquisa, crie um campo de vetor correspondente para armazenar as incorporações do valor armazenado no campo de dados.
Gere incorporações para os dados nos campos de dados selecionados e armazene as incorporações em seus campos vetoriais correspondentes.
Gere a incorporação para qualquer consulta de pesquisa de entrada.
Procure o campo de dados vetoriais e liste os vizinhos mais próximos.
Execute os resultados através de modelos apropriados de relevância, classificação e personalização para produzir a classificação final. Na ausência de tais modelos, classifique os resultados em ordem decrescente de ponto-produto.
Monitore o modelo, a qualidade dos resultados e as métricas de negócios, como taxa de cliques e tempo de permanência. Incorpore mecanismos de feedback para depurar e melhorar a pilha de pesquisa, desde a qualidade dos dados, atualização e personalização dos dados até a experiência do usuário.

Pré-requisitos

Crie uma conta OpenAI e solicite acesso ao Azure OpenAI.
Conceda acesso ao Azure OpenAI na assinatura desejada.
Conceda permissões para criar recursos do Azure OpenAI e implantar modelos.
Crie e implante um recurso e um modelo do Azure OpenAI. Implante o modelo de incorporação text-embedding-ada-002. Copie o nome da implementação, pois precisas dele para criar embeddings.

Habilite as extensões azure_ai e pgvector

Antes de habilitar azure_ai e pgvector em seu servidor flexível do Banco de Dados do Azure para PostgreSQL, você precisa adicioná-los à sua lista de permissões. Certifique-se de que eles foram adicionados corretamente executando SHOW azure.extensions;.

Em seguida, você pode instalar a extensão conectando-se ao seu banco de dados de destino e executando o comando CREATE EXTENSION . Você precisa repetir o comando separadamente para cada banco de dados onde deseja que a extensão esteja disponível.

CREATE EXTENSION azure_ai;
CREATE EXTENSION vector;

Configurar um endpoint e uma chave OpenAI

Nos serviços de IA do Azure, sob Gestão de Recursos>Chaves e Pontos de Extremidade, pode encontrar o ponto de extremidade e as chaves do seu recurso de IA do Azure. Use o endpoint e uma das chaves para ativar a azure_ai extensão para invocar a implantação do modelo.

select azure_ai.set_setting('azure_openai.endpoint','https://<endpoint>.openai.azure.com');
select azure_ai.set_setting('azure_openai.subscription_key', '<API Key>');

Faça o download dos dados

Faça o download dos dados do Kaggle.

Criar a tabela

Conecte-se ao seu servidor e crie um test banco de dados. Nesse banco de dados, use o seguinte comando para criar uma tabela na qual você importará dados:

CREATE TABLE public.recipes(
    rid integer NOT NULL,
    recipe_name text,
    prep_time text,
    cook_time text,
    total_time text,
    servings integer,
    yield text,
    ingredients text,
    directions text,
    rating real,
    url text,
    cuisine_path text,
    nutrition text,
    timing text,
    img_src text,
    PRIMARY KEY (rid)
);

Importar os dados

Defina a seguinte variável de ambiente na janela do cliente para definir a codificação como UTF-8. Esta etapa é necessária porque esse conjunto de dados específico usa a codificação do Windows-1252.

Rem on Windows
Set PGCLIENTENCODING=utf-8;

# on Unix based operating systems
export PGCLIENTENCODING=utf-8

Importe os dados para a tabela que você criou. Observe que esse conjunto de dados contém uma linha de cabeçalho.

psql -d <database> -h <host> -U <user> -c "\copy recipes FROM <local recipe data file> DELIMITER ',' CSV HEADER"

Adicionar uma coluna para armazenar as incorporações

Adicione uma coluna de incorporação à tabela:

ALTER TABLE recipes ADD COLUMN embedding vector(1536);

Gerar incorporações

Gere incorporações para seus dados usando a azure_ai extensão. O exemplo a seguir vetoriza alguns campos, que são então concatenados.

WITH ro AS (
    SELECT ro.rid
    FROM
        recipes ro
    WHERE
        ro.embedding is null
        LIMIT 500
)
UPDATE
    recipes r
SET
    embedding = azure_openai.create_embeddings('text-embedding-ada-002', r.recipe_name||' '||r.cuisine_path||' '||r.ingredients||' '||r.nutrition||' '||r.directions)
FROM
    ro
WHERE
    r.rid = ro.rid;

Repita o comando até que não haja mais linhas para processar.

Gorjeta

Brinque com o LIMIT valor. Com um valor alto, a instrução pode falhar no meio do caminho devido à limitação que o Azure OpenAI impõe. Se a instrução falhar, aguarde pelo menos um minuto e execute o comando novamente.

Pesquisar

Crie uma função de pesquisa na sua base de dados para conveniência:

create function
    recipe_search(searchQuery text, numResults int)
returns table(
            recipeId int,
            recipe_name text,
            nutrition text,
            score real)
as $$
declare
    query_embedding vector(1536);
begin
    query_embedding := (azure_openai.create_embeddings('text-embedding-ada-002', searchQuery));
    return query
    select
        r.rid,
        r.recipe_name,
        r.nutrition,
        (r.embedding <=> query_embedding)::real as score
    from
        recipes r
    order by score asc limit numResults; -- cosine distance
end $$
language plpgsql;

Agora é só invocar a função para pesquisar:

select recipeid, recipe_name, score from recipe_search('vegan recipes', 10);

E explore os resultados:

 recipeid |                         recipe_name                          |   score
----------+--------------------------------------------------------------+------------
      829 | Avocado Toast (Vegan)                                        | 0.15672222
      836 | Vegetarian Tortilla Soup                                     | 0.17583494
      922 | Vegan Overnight Oats with Chia Seeds and Fruit               | 0.17668104
      600 | Spinach and Banana Power Smoothie                            |  0.1773768
      519 | Smokey Butternut Squash Soup                                 | 0.18031077
      604 | Vegan Banana Muffins                                         | 0.18287598
      832 | Kale, Quinoa, and Avocado Salad with Lemon Dijon Vinaigrette | 0.18368931
      617 | Hearty Breakfast Muffins                                     | 0.18737361
      946 | Chia Coconut Pudding with Coconut Milk                       |  0.1884186
      468 | Spicy Oven-Roasted Plums                                     | 0.18994217
(10 rows)

Partilhar via