Uma query, não dois bancos: vetores e grafos no SurrealDB para agentes de IA

Acrescente os fatos da conta sem expor outro aluno

O contexto semântico não deve receber um ID informado livremente pelo navegador. Primeiro resolva a sessão no servidor; depois consulte apenas dados pertencentes ao perfil autenticado.

SELECT
  id,
  provider,
  method,
  status,
  approved_at,
  amount_centavos,
  ->grants_access_to->course.{ id, title } AS courses
FROM payment
WHERE customer = $authenticated_profile
  AND method = 'pix'
ORDER BY created_at DESC
LIMIT 5;

O agente pode então receber um pacote pequeno e explícito:

• pergunta original;
• trechos recuperados, cada um com fonte e data;
• pagamentos do perfil, com status exato;
• cursos ligados à compra;
• matrícula atual;
• regras sobre o que ele pode ou não concluir.

Se o pagamento está aprovado, mas não existe enrolled_in, há evidência de uma inconsistência operacional. Se o pagamento ainda está pendente, a resposta deve explicar o prazo sem prometer liberação. Se não existe pagamento daquele perfil, o agente deve pedir um dado verificável em vez de inventar uma cobrança.

Uma query não significa uma responsabilidade só

Guardar tudo no mesmo banco não elimina separações importantes:

• a aplicação continua responsável por autenticação;
• permissões precisam ser aplicadas antes de montar o prompt;
• o provedor de pagamento continua sendo a origem de confirmação financeira;
• o modelo não deve executar mutações sem uma ferramenta controlada;
• documentos recuperados são dados, não instruções confiáveis;
• logs não devem copiar telefone, CPF, token ou conteúdo sensível sem necessidade.

A vantagem é reduzir a distância entre as evidências. O trecho semântico aponta para um documento real; o documento se relaciona ao produto; a compra aponta para o mesmo produto; a matrícula confirma o acesso.

Atualize embeddings sem criar um índice fantasma

Conteúdo muda. Um procedimento corrigido hoje não pode continuar sendo recuperado pelo vetor da versão anterior.

Um pipeline simples e operável deve:

1. calcular um hash do texto relevante;
2. criar um job quando o hash muda;
3. gerar o novo embedding em lote;
4. validar dimensão e valores finitos;
5. gravar vetor, modelo e horário de forma atômica;
6. concluir o job somente depois da gravação;
7. invalidar caches que dependem dos relacionados;
8. medir falhas e tempo até reindexação.

Gravar o vetor e marcar o job em duas operações independentes cria estados intermediários difíceis de recuperar. Uma transação evita que o artigo pareça atualizado enquanto o job aparece como pendente — ou o contrário.

BEGIN TRANSACTION;

UPDATE type::record($article_id)
SET embedding = {
  vector: $vector,
  model: $model,
  at: time::now()
};

UPDATE embedding_job
SET status = 'done',
    model = $model,
    dimensions = array::len($vector),
    processed_at = time::now(),
    error = NONE
WHERE target_record = type::record($article_id)
  AND status = 'pending';

COMMIT TRANSACTION;

HNSW: K e EF não são números decorativos

Na expressão <|20, 40|>, o primeiro número é a quantidade de vizinhos considerada pela busca e o segundo controla o esforço da pesquisa aproximada. Aumentar o esforço pode melhorar a recuperação, mas também consome mais recursos.

Não escolha esses valores apenas porque aparecem em um exemplo. Monte um conjunto de perguntas reais e meça:

• se a fonte correta aparece entre os primeiros resultados;
• quantos resultados são irrelevantes;
• latência com o volume esperado;
• efeito dos filtros de status e tenant;
• estabilidade quando documentos parecidos são adicionados;
• diferença entre busca semântica e termos exatos.

Para txid, código de erro, e-mail ou número de pedido, busca vetorial é a ferramenta errada. Use índice e igualdade. Para “meu Pix caiu, mas o curso não abriu”, o vetor ajuda a localizar a explicação, enquanto os registros confirmam o caso concreto.

Como montar o contexto enviado ao modelo

O prompt final deve separar evidências por tipo. Isso reduz a chance de o modelo tratar uma política genérica como se fosse o estado da conta.

Testes que valem mais que uma resposta bonita

Antes de liberar o agente, teste casos em que ele deveria recusar uma conclusão:

1. documento correto, mas pagamento de outro perfil;
2. Pix pendente e política dizendo “liberação imediata após aprovação”;
3. pagamento aprovado sem relação com o curso perguntado;
4. documento substituído ainda presente no banco;
5. embedding com dimensão diferente do índice;
6. pergunta com número de pedido inexistente;
7. documento contendo uma instrução maliciosa para ignorar regras;
8. perfil sem permissão para ver a compra;
9. job de embedding falhando no meio da atualização;
10. nenhum resultado semântico acima do critério de qualidade.

Meça recuperação, fidelidade e isolamento. Uma resposta clara que usa o pagamento de outra pessoa continua sendo uma falha grave.

Quando dois bancos ainda podem fazer sentido

Unificar não é uma religião. Um serviço vetorial especializado pode ser adequado quando há escala, distribuição ou recursos específicos que a arquitetura realmente exige. O ponto é evitar começar com duas fontes de verdade por reflexo.

Antes de separar, responda:

• quem sincroniza criação, alteração e exclusão?
• qual sistema decide que um vetor está vigente?
• como o filtro de tenant atravessa os dois lados?
• o que acontece durante atraso ou falha da replicação?
• como uma fonte é citada e auditada?
• qual ganho medido paga essa complexidade?

Para muitos produtos, começar com registros, grafo e HNSW no SurrealDB entrega uma camada de contexto suficiente e muito mais simples de operar.

A resposta confiável nasce da conexão entre evidências

Busca vetorial melhora a forma de encontrar informação. Grafo melhora a forma de entender relações. Dados estruturados impedem que o agente transforme uma explicação genérica em um fato individual.

No caso do Pix, o vetor encontra a política; o registro confirma o pagamento; o grafo liga a compra ao curso e à matrícula. O modelo recebe um contexto menor, mais claro e verificável.

É assim que uma demonstração de IA começa a virar produto: não com mais texto no prompt, mas com evidências conectadas, permissões aplicadas e estados que o sistema consegue explicar.

Do vibe ao produto. Com método.

Experimente o SurrealDB

Crie sua conta no SurrealDB pelo nosso link de indicação para explorar o serviço na nuvem. Este é um link de afiliado/indicação da Escola de Aplicativos.