Apresentando a pipeline e criando o script
Na segunda parte, nós vamos construir uma pipeline (fluxo de processamento) muito simples, que permitirá converter o arquivo, realizar os splits (divisões), como mencionamos, gerar os embeddings (vetores de representação) e, de fato, depois executar consultas no PostgreSQL.
Primeiro, vamos criar um script chamado conversao.py. Ele será responsável por executar essas etapas. Poderíamos escolher muitos outros nomes, mas vamos manter conversao.py.
Inicializando o projeto e instalando dependências
Vamos abrir o terminal para melhorar a visualização e aumentar a tela. Em seguida, vamos usar nosso projeto em Python e iniciar com uv init, para que possamos instalar as dependências que utilizaremos no projeto. Para conferir os arquivos, vamos executar ls.
Para iniciar o projeto com o gerenciador uv, executamos:
Vamos entrar no ambiente do projeto e usar uv add (o de adicionar). Chegamos a pensar em uv shell, mas o comando correto aqui é uv add. Quando executamos uv add, ele já cria para nós a 'env'. Vamos adicionar docling, que será utilizado na parte de conversão.
Vale mencionar que utilizaremos o projeto docling. Ele é muito eficiente porque consegue processar arquivos e realizar a conversão que queremos. Como vamos utilizar o Ollama, isso já ajuda nessa etapa. O docling traz modelos que entendem o arquivo e permitem realizar a conversão. Portanto, usaremos docling com Ollama. Também utilizaremos psycopg (binário), que será empregado na integração com PostgreSQL.
Para instalar tudo de uma vez (docling, ollama e psycopg[binary]), usamos:
uv add docling ollama psycopg[binary]
Importando bibliotecas no script
Vamos proceder com as instalações. Observe que o gerenciador já criou a 'env' e está instalando as dependências necessárias para o projeto. Enquanto isso, vamos voltar ao arquivo de conversão. No script, vamos começar importando os componentes de que precisamos: Ollama, psycopg para a parte de PostgreSQL (isto é, nossa conexão), e docling com DocumentConverter, que permitirá realizar a conversão.
Para organizar nossos imports no conversao.py:
import ollama
import psycopg
from docling.document_converter import DocumentConverter
Ativando o ambiente virtual
Assim que a instalação terminar, vamos ativar o ambiente virtual para eliminar os erros de importação. No PowerShell, utilizamos venv\Scripts\Activate.ps1. Em alguns ambientes, pode ser necessário usar source venv/bin/activate. Com o ambiente ativado (Python 3.14), vamos executar uv add novamente apenas para confirmar; tudo certo.
No Windows, por exemplo, a ativação pode ser assim:
Conectando ao PostgreSQL e criando a extensão de vetores
Agora, vamos criar a conexão com PostgreSQL. Definiremos a variável de conexão e utilizaremos psycopg para estabelecer a conexão com o host localhost, porta 5432, banco de dados ragdb, usuário rag e senha rag, conforme já havíamos definido.
conn = psycopg.connect(
host="localhost",
port=5432,
dbname="ragdb",
user="rag",
password="rag"
)
A primeira parte da conversão é criar a extensão de vetor. Para que o PostgreSQL entenda a parte de vetores, utilizaremos a extensão do projeto pgvector (no comando, a extensão é registrada como vector). Se a extensão ainda não estiver ativa, vamos criá-la.
Antes disso, abrimos um cursor para executar os comandos SQL:
Em seguida, criamos a extensão de vetores:
cursor.execute("""
CREATE EXTENSION IF NOT EXISTS vector;
""")
Criando a tabela e executando o script
Em seguida, vamos criar a tabela. Teremos, de fato, a tabela documentos, com uma chave primária id única, uma coluna conteudo do tipo texto e a coluna de vetores de embedding, onde ficará toda a vetorização ao longo do curso. Se tudo estiver correto, vamos realizar o commit (confirmação) para aplicar as mudanças no banco de dados. Com isso, teremos concluído a primeira parte necessária: as estruturas (tabelas) no banco de dados.
cursor.execute("""
CREATE TABLE IF NOT EXISTS documents (
id SERIAL PRIMARY KEY,
content TEXT,
embedding vector(768)
);
""")
conn.commit()
Podemos executar o script conversao.py.
Diagnosticando a execução e inspecionando o banco
Vamos remover a segunda conexão duplicada, pois a conexão estava repetida. Depois, vamos atualizar o cliente do banco (refresh — atualizar). A execução aparentemente ocorreu e o commit (confirmação) foi feito, mas, por alguma razão, o processo ficou parado. Vamos cancelar essa execução, desconectar do banco, verificar a conexão e conectar novamente. Aparentemente está tudo correto com a conexão e as tabelas. A seguir, vamos verificar o que aconteceu com a conversão, porque o processo não deveria ter parado nesse ponto. Pode ser que não tenha ocorrido o commit (confirmação). Seguiremos com o código e, se houver qualquer falha, faremos o ajuste no próximo vídeo.
Para inspecionar os dados, usamos algumas consultas simples no banco:
SELECT * FROM public.documents;
Extraindo e convertendo PDF em Markdown
Na sequência, vamos implementar a parte de extração do PDF, isto é, o que realmente vai extrair e converter o conteúdo. Para isso, utilizaremos docling com DocumentConverter, que converte o arquivo PDF e exporta seu conteúdo em Markdown (formatação em texto).
Aqui mostramos o resultado apenas para verificarmos o que foi feito. Agora vamos criar uma função para realizar o split (divisão) do texto. Enquanto isso, vamos retornar à conversão. Vamos verificar uma coisa: executamos o comando pwd na pasta "demo" e enviamos o comando novamente, deixando-o em execução enquanto concluímos aqui.
Primeiro, vamos converter um PDF e visualizar o Markdown gerado:
converter = DocumentConverter()
result = converter.convert("arquivo.pdf")
text = result.document.export_to_markdown()
print(text)
Explicando a estratégia de splits e definindo a função
Colocamos um print para visualizar a exportação em Markdown (sintaxe de marcação). Agora vamos criar a função que de fato realiza o split (divisão). O que isso significa? Vamos pegar as partes do nosso arquivo PDF e dividi-las em "chunkings" (fragmentações), gerando várias divisões. Em outras palavras, estamos pegando esse PDF, recortando em trechos, quase como um "slice" (fatia): tomamos um trecho aqui e outro ali e formamos um embedding (vetorização). Assim, o sistema consegue reconhecer um parágrafo, por assim dizer. Há várias questões de RAG (Geração Aumentada por Recuperação) envolvidas nesses splits (divisões) de texto, pois às vezes não se captura o trecho desejado e algo fica faltando. Essa etapa deve ser analisada com muito cuidado.
Definimos a função de splitting com tamanho de chunk e overlap:
def split_text(
text: str,
chunk_size: int = 500,
overlap: int = 100
) -> list[str]:
chunks: list[str] = []
for i in range(0, len(text), chunk_size - overlap):
chunk = text[i:i + chunk_size]
chunks.append(chunk)
return chunks
Preparando os chunks e verificando a população da tabela
Depois de gerar os "chunkings" (fragmentações), vamos realizar a geração do embedding (vetorização), isto é, indicar ao modelo que queremos transformar esses "chunkings". Aqui a execução ocorreu; demorou um pouco — provavelmente por uma questão da máquina —, deixamos rodando e a tabela já está disponível. Fizemos um SELECT * FROM para visualizar o documento, em public documents aqui. Inserimos um SELECT específico. Teoricamente estava tudo certo; se tivéssemos usado public documents, estaria bem. Talvez tenhamos digitado algo errado. Clicamos com o botão direito, pedimos para gerar um script (roteiro) e um SELECT. Em seguida, voltamos ao uso do * e conferimos. Observamos que em id, content e embedding ainda não há dados.
Por enquanto, criamos os chunks e preparamos um loop para percorrê-los:
chunks = split_text(text)
for chunk in chunks:
...
Nesse meio-tempo, o ambiente está baixando um modelo, o RapidOCR, que vai pegar o arquivo PDF e convertê-lo para a parte textual. Basicamente é isso que ele faz. Já conseguimos ver que o texto foi transformado enquanto revisávamos a conexão.
Gerando embeddings com Ollama e inserindo no Postgres
O que falta agora é solicitar que esses "chunkings" (fragmentações) sejam enviados para a base de dados. Para isso, vamos iterar em um loop (laço) e solicitar que realize os inserts (inserções) desses "chunkings". Removemos alguns trechos para facilitar a visualização; no repositório, o arquivo estará com todos os comentários nas linhas. Estamos com o "chunking" e os "chunkings" resultantes do split (divisão) do texto e estamos pedindo ao Ollama (modelo de embeddings "nomic-embed-text") que gere os embeddings (vetores). Ele transformará cada trecho em vetores matemáticos, ou seja, fará o embed (vetorização). Ao concluir, realizará os inserts (inserções) na base, o que permitirá depois fazermos a consulta. Veremos essa consulta no próximo vídeo. Colocamos um print aqui e outro ali e vamos deixar essa etapa executando.
Agora, completamos o loop com a geração de embeddings pelo Ollama e a inserção no Postgres:
for chunk in chunks:
response = ollama.embeddings(
model="nomic-embed-text",
prompt=chunk
)
embedding &
cursor.execute(
&
INSERT INTO documents (content, embedding)
VALUES (%s, %s)
&
(chunk, embedding)
)
Após processar e inserir todos os registros, emitimos uma mensagem de confirmação e, por fim, encerramos cursor e conexão:
print("Embeddings salvos com sucesso!")
cursor.close()
conn.close()
Recapitulando o pipeline e executando consultas
Relembrando o que já foi feito no código: na primeira parte, estabelecemos a conexão com a base, criamos a extensão de vetor para poder trabalhar com vetores no Postgres e criamos uma tabela de documentos bem simples, com os campos id, content e embedding. Não há nada muito complexo aqui: em essência, trabalhamos com dois itens principais — o conteúdo em texto e os embeds (vetores) — para que possamos visualizar tanto em forma textual quanto em forma vetorizada. Solicitamos ao Docling que convertesse o arquivo PDF em texto utilizável. Com o texto em mãos, realizamos o split (divisão) em partes menores, que chamamos de "chunk" (fragmento). É como aplicar um "slice" (fatia) no texto, cortando trechos que podem corresponder a um parágrafo ou a um fragmento. Essa parte do seu pipeline (fluxo de processamento) precisa ser avaliada com muito cuidado, pois é comum o RAG (Geração Aumentada por Recuperação) não funcionar bem se cortarmos um trecho importante que estava, por exemplo, no parágrafo seguinte.
Com o texto dividido, obtemos os seus "chunks" (fragmentos), e cada um deles é submetido ao embedding (vetorização), transformando-o em um vetor matemático. Depois, podemos solicitar ao Postgres uma consulta baseada nesses vetores. Quando passamos um texto para o Postgres, ele o vetoriza para a consulta, permitindo encontrar o trecho mais relevante. Cada "chunk" (fragmento) do texto é inserido na base, resultando em vários registros. Em seguida, fazemos o insert (inserção) desses "chunks", salvando o conteúdo e os embeds (vetores), registrando que o embed foi armazenado, executando o commit na base, fechando a conexão do cursor e, por fim, a conexão com o banco. Há diferenças entre esses dois: um é o cursor de execução de comandos e o outro é a conexão aberta com o banco.
Para checar o que foi inserido, podemos executar consultas como:
SELECT id, content, embedding
FROM public.documents;
Finalizando a execução e preparando os próximos passos
Neste momento, o processo está tratando cada trecho do texto. Verificamos se já inseriu; ainda não. Está finalizando a etapa de "slice" (fatia) e, na sequência, transformará em "chunk" (fragmento). Para que o vídeo não fique muito longo, vamos deixar essa execução em andamento e iniciar o próximo vídeo já com o resultado e prontos para realizar as consultas.
Para rodar novamente o script de ponta a ponta:
Eu te espero na continuação. Um grande abraço.