RAG na prática: busca vetorial com PHP, PostgreSQL e pgvector

create extension if not exists vector;

use Illuminate\Database\Migrations\Migration;
use Illuminate\Support\Facades\DB;

return new class extends Migration
{
    public function up(): void
    {
        DB::statement('create extension if not exists vector');

        DB::statement(<<<'SQL'
            create table trechos (
                id bigserial primary key,
                documento_id bigint not null references documentos(id) on delete cascade,
                conteudo text not null,
                -- 1536 é a dimensão do text-embedding-3-small.
                -- Precisa bater exatamente com o modelo escolhido.
                embedding vector(1536) not null,
                metadados jsonb not null default '{}',
                criado_em timestamptz not null default now()
            )
        SQL);

        DB::statement('create index on trechos using gin (metadados)');
        DB::statement('create index on trechos (documento_id)');
    }

    public function down(): void
    {
        DB::statement('drop table if exists trechos');
    }
};

<?php

declare(strict_types=1);

namespace App\Services\Rag;

final class Fatiador
{
    public function __construct(
        private int $tamanho = 800,
        private int $sobreposicao = 120,
    ) {}

    /** @return list<string> */
    public function fatiar(string $texto): array
    {
        // Quebra em parágrafos primeiro: respeitar a estrutura do texto
        // rende muito mais que cortar a cada N caracteres.
        $paragrafos = preg_split('/\n\s*\n/', trim($texto)) ?: [];

        $trechos = [];
        $atual = '';

        foreach ($paragrafos as $paragrafo) {
            $paragrafo = trim($paragrafo);

            if ($paragrafo === '') {
                continue;
            }

            // Parágrafo sozinho já estoura o limite: quebra por frase.
            if (mb_strlen($paragrafo) > $this->tamanho) {
                if ($atual !== '') {
                    $trechos[] = $atual;
                    $atual = '';
                }

                foreach ($this->quebrarPorFrase($paragrafo) as $pedaco) {
                    $trechos[] = $pedaco;
                }

                continue;
            }

            if (mb_strlen($atual) + mb_strlen($paragrafo) + 2 > $this->tamanho) {
                $trechos[] = $atual;
                $atual = $this->cauda($atual);
            }

            $atual = $atual === '' ? $paragrafo : "{$atual}\n\n{$paragrafo}";
        }

        if (trim($atual) !== '') {
            $trechos[] = $atual;
        }

        return $trechos;
    }

    /** Últimos N caracteres, para servir de sobreposição no próximo trecho. */
    private function cauda(string $texto): string
    {
        return mb_strlen($texto) <= $this->sobreposicao
            ? $texto
            : mb_substr($texto, -$this->sobreposicao);
    }

    /** @return list<string> */
    private function quebrarPorFrase(string $paragrafo): array
    {
        $frases = preg_split('/(?<=[.!?])\s+/', $paragrafo) ?: [];

        $saida = [];
        $buffer = '';

        foreach ($frases as $frase) {
            if (mb_strlen($buffer) + mb_strlen($frase) > $this->tamanho && $buffer !== '') {
                $saida[] = $buffer;
                $buffer = $this->cauda($buffer);
            }

            $buffer = trim("{$buffer} {$frase}");
        }

        if ($buffer !== '') {
            $saida[] = $buffer;
        }

        return $saida;
    }
}

<?php

declare(strict_types=1);

namespace App\Services\Rag;

use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Http;

final class GeradorDeEmbeddings
{
    private const MODELO = 'text-embedding-3-small';
    private const LOTE = 100;

    /**
     * @param  list<string>  $textos
     * @return list<list<float>>
     */
    public function gerar(array $textos): array
    {
        $saida = [];

        foreach (array_chunk($textos, self::LOTE) as $lote) {
            $pendentes = [];

            // Cache por hash: reindexar um documento em que só um parágrafo
            // mudou não deve pagar pelos outros de novo.
            foreach ($lote as $i => $texto) {
                $chave = 'emb:' . self::MODELO . ':' . hash('xxh128', $texto);
                $cacheado = Cache::get($chave);

                if ($cacheado !== null) {
                    $saida[] = $cacheado;
                    continue;
                }

                $pendentes[$i] = $texto;
            }

            if ($pendentes === []) {
                continue;
            }

            $resposta = Http::withToken(config('services.openai.key'))
                ->timeout(60)
                ->retry(3, 1000, throw: false)
                ->post('https://api.openai.com/v1/embeddings', [
                    'model' => self::MODELO,
                    'input' => array_values($pendentes),
                ])
                ->throw()
                ->json('data');

            foreach ($resposta as $posicao => $item) {
                $texto = array_values($pendentes)[$posicao];
                $chave = 'emb:' . self::MODELO . ':' . hash('xxh128', $texto);

                Cache::forever($chave, $item['embedding']);
                $saida[] = $item['embedding'];
            }
        }

        return $saida;
    }
}

use Illuminate\Support\Facades\DB;

public function indexar(Documento $documento): void
{
    $trechos = $this->fatiador->fatiar($documento->conteudo);
    $vetores = $this->embeddings->gerar($trechos);

    DB::transaction(function () use ($documento, $trechos, $vetores) {
        DB::table('trechos')->where('documento_id', $documento->id)->delete();

        $linhas = [];

        foreach ($trechos as $i => $trecho) {
            $linhas[] = [
                'documento_id' => $documento->id,
                'conteudo' => $trecho,
                'embedding' => '[' . implode(',', $vetores[$i]) . ']',
                'metadados' => json_encode([
                    'titulo' => $documento->titulo,
                    'posicao' => $i,
                    'modelo' => 'text-embedding-3-small',
                ]),
            ];
        }

        foreach (array_chunk($linhas, 500) as $bloco) {
            DB::table('trechos')->insert($bloco);
        }
    });
}

public function buscar(string $pergunta, int $quantidade = 5): array
{
    [$vetor] = $this->embeddings->gerar([$pergunta]);
    $consulta = '[' . implode(',', $vetor) . ']';

    return DB::select(<<<'SQL'
        select
            t.id,
            t.conteudo,
            t.metadados,
            1 - (t.embedding <=> ?::vector) as similaridade
        from trechos t
        join documentos d on d.id = t.documento_id
        where d.empresa_id = ?
          and d.publicado = true
        order by t.embedding <=> ?::vector
        limit ?
    SQL, [$consulta, $empresaId, $consulta, $quantidade]);
}

-- HNSW: melhor recall, busca mais rápida, construção mais lenta
create index on trechos
using hnsw (embedding vector_cosine_ops)
with (m = 16, ef_construction = 64);

-- IVFFlat: construção rápida, memória menor, recall um pouco pior
-- lists ≈ raiz quadrada do número de linhas
create index on trechos
using ivfflat (embedding vector_cosine_ops)
with (lists = 1000);

with vetorial as (
    select id, row_number() over (order by embedding <=> $1::vector) as posicao
    from trechos
    where documento_id in (select id from documentos where empresa_id = $2)
    order by embedding <=> $1::vector
    limit 50
),
textual as (
    select id, row_number() over (
        order by ts_rank_cd(to_tsvector('portuguese', conteudo),
                            plainto_tsquery('portuguese', $3)) desc
    ) as posicao
    from trechos
    where to_tsvector('portuguese', conteudo) @@ plainto_tsquery('portuguese', $3)
      and documento_id in (select id from documentos where empresa_id = $2)
    limit 50
)
select
    t.id,
    t.conteudo,
    coalesce(1.0 / (60 + v.posicao), 0) + coalesce(1.0 / (60 + x.posicao), 0) as pontos
from trechos t
left join vetorial v on v.id = t.id
left join textual x on x.id = t.id
where v.id is not null or x.id is not null
order by pontos desc
limit 8;

public function responder(string $pergunta): array
{
    $trechos = $this->buscar($pergunta, quantidade: 8);

    if ($trechos === []) {
        return [
            'resposta' => 'Não encontrei nada sobre isso na base de conhecimento.',
            'fontes' => [],
        ];
    }

    $contexto = collect($trechos)
        ->map(fn ($t, $i) => "[{$i}] {$t->conteudo}")
        ->implode("\n\n---\n\n");

    $sistema = <<<TXT
    Você responde perguntas usando EXCLUSIVAMENTE os trechos fornecidos.

    Regras:
    - Se a resposta não estiver nos trechos, diga que não encontrou. Não deduza.
    - Cite a fonte com o número entre colchetes, ex.: [2].
    - Responda em português do Brasil, de forma direta.
    TXT;

    $resposta = $this->llm->completar(
        sistema: $sistema,
        usuario: "Trechos:\n\n{$contexto}\n\nPergunta: {$pergunta}",
        temperatura: 0.1,
    );

    return [
        'resposta' => $resposta,
        'fontes' => collect($trechos)->map(fn ($t) => [
            'titulo' => json_decode($t->metadados)->titulo,
            'similaridade' => round($t->similaridade, 3),
        ])->all(),
    ];
}