O Custo Oculto dos Pipelines de Embeddings

Todo agente de conhecimento começa do mesmo jeito: escolher um banco vetorial, construir um pipeline de chunking, selecionar um modelo de embedding e ajustar parâmetros de recuperação. Semanas depois, seu agente responde uma pergunta errada e você não tem ideia do porquê. O modo de falha é silencioso.

Observamos esse padrão repetidamente, tanto internamente quanto em equipes construindo agentes na Vercel. A stack de embeddings funciona para similaridade semântica, mas falha quando você precisa de um valor específico de dados estruturados. Você acaba depurando um pipeline, não uma pergunta.

Por isso adotamos uma abordagem diferente: substituir o pipeline vetorial por um sistema de arquivos e dar bash ao agente. Nosso agente de sumarização de chamadas de vendas foi de ~$1,00 para ~$0,25 por chamada, e a qualidade da saída melhorou. O agente estava fazendo o que já sabia: ler arquivos, executar grep e navegar por diretórios.

Disponibilizamos o resultado como o Knowledge Agent Template, uma arquitetura pronta para produção construída sobre Vercel Sandbox, AI SDK e Chat SDK.

Developer using AI agent with filesystem search interface on terminal Dev Environment Setup

Como Funciona a Busca por Sistema de Arquivos

Sem banco vetorial. Sem pipeline de chunking. Sem modelo de embedding. Seu agente usa grep, find e cat dentro de Sandboxes Vercel isoladas.

O Fluxo

  1. Você adiciona fontes pela interface administrativa, armazenadas em Postgres.
  2. O conteúdo é sincronizado com um repositório de snapshots via Vercel Workflow.
  3. Quando o agente precisa pesquisar, uma Sandbox Vercel carrega o snapshot.
  4. As ferramentas bash e bash_batch do agente executam comandos no sistema de arquivos.
  5. O agente retorna uma resposta com referências opcionais.

Os resultados são determinísticos, explicáveis e rápidos. Quando o agente dá uma resposta errada, você abre o trace e vê: ele executou grep -r "preço" docs/, leu docs/planos/enterprise.md e puxou a seção errada. Você corrige o arquivo ou ajusta a estratégia. O loop de depuração leva minutos.

Compare com vetores: se o agente retorna um chunk ruim, você precisa determinar qual chunk foi recuperado e depois descobrir por que ele obteve 0,82 e o correto 0,79. O problema pode ser os limites do chunk, o modelo de embedding ou o limiar de similaridade. Com a busca por sistema de arquivos, não há adivinhação.

LLMs já entendem sistemas de arquivos. Eles foram treinados em enormes quantidades de código: navegar por diretórios, fazer grep em arquivos, gerenciar estado em bases de código complexas. Se os agentes são excelentes em operações de sistema de arquivos para código, eles são excelentes para qualquer coisa.

Exemplo: Usando o SDK

// Importe as ferramentas e conecte-se à sua base de conhecimento
import { generateText } from 'ai';
import { createSavoir } from '@savoir/sdk';

const savoir = createSavoir({
  apiUrl: process.env.SAVOIR_API_URL!,
  apiKey: process.env.SAVOIR_API_KEY,
});

const { text } = await generateText({
  model: yourModel, // qualquer modelo compatível com AI SDK
  tools: savoir.tools, // ferramentas bash e bash_batch
  maxSteps: 10,
  prompt: 'Como configurar a autenticação?',
});

console.log(text);

Vercel Sandbox architecture diagram showing filesystem and bash tools for agent search System Abstract Visual

Implantação Multiplataforma com Chat SDK

Seu agente tem uma base de conhecimento, uma base de código e uma única fonte de verdade. No entanto, seus engenheiros estão espalhados pelo Slack, sua comunidade pelo Discord, seus relatórios de bugs enterrados no GitHub. O Chat SDK conecta seu agente a todas as plataformas.

Um Único Agente, Em Todo Lugar

import { Chat } from "chat";
import { createSlackAdapter } from "@chat-adapter/slack";
import { createDiscordAdapter } from "@chat-adapter/discord";
import { createRedisState } from "@chat-adapter/state-redis";

const bot = new Chat({
  userName: "knowledge-agent",
  adapters: {
    slack: createSlackAdapter(),
    discord: createDiscordAdapter(),
  },
  state: createRedisState(),
});

bot.onNewMention(async (thread, message) => {
  await thread.subscribe();
  const result = await agent.stream({ prompt: message.text });
  await thread.post(result);
});

Cada adaptador lida com questões específicas da plataforma (autenticação, formatos de evento, mensagens) enquanto o agente permanece inalterado. onNewMention dispara sempre que o bot é mencionado, independentemente da plataforma.

Ferramentas Administrativas Integradas

O template inclui uma interface administrativa completa: estatísticas de uso, logs de erros, gerenciamento de usuários, configuração de fontes e controles de sincronização de conteúdo. Há também um agente administrativo com IA que você pode perguntar coisas como "quais erros ocorreram nas últimas 24 horas" ou "quais são as perguntas comuns dos usuários". Ele usa ferramentas internas (query_stats, query_errors, run_sql, chart) para fornecer respostas diretamente. Você depura seu agente com um agente.

Limitações e Cuidados

  • Não é ideal para busca semântica não estruturada: Se seu caso de uso exige encontrar conteúdo por significado em vez de palavras-chave exatas (ex.: "encontre documentos parecidos com este"), uma abordagem vetorial ainda pode ser necessária.
  • Tamanho do snapshot importa: Bases de código ou repositórios de documentos muito grandes podem exigir gerenciamento cuidadoso de snapshots para manter o desempenho da sandbox.
  • Dependência de bash: A abordagem assume que o agente pode executar comandos bash com segurança. Embora as Sandboxes Vercel forneçam forte isolamento, você deve auditar os comandos que seu agente usa.

Próximos Passos

Conclusão: Você não precisa de um banco de dados vetorial para construir um agente de conhecimento funcional. Você precisa de um sistema de arquivos, bash e uma maneira de colocar seu agente onde seus usuários já estão. Esses são os primitivos.

Multi-platform chat agent deployed on Slack, Discord, and GitHub with unified knowledge base Coding Session Visual

Conclusão

A abordagem de sistema de arquivos e bash para agentes de conhecimento é uma mudança de paradigma. É mais simples, mais barata e mais depurável do que o pipeline tradicional de embeddings. Ao aproveitar o que os LLMs já fazem bem—navegar por diretórios e processar texto—você pode construir agentes que são ao mesmo tempo mais confiáveis e mais sustentáveis.

Principais conclusões:

  • Busca determinística elimina o problema da "caixa preta" da similaridade vetorial.
  • Redução de custo de até 75% por consulta (de $1,00 para $0,25 no nosso caso).
  • Base de conhecimento única implantada em Slack, Discord, GitHub e muito mais.
  • Ferramentas administrativas integradas e agente de depuração com IA.

Leitura adicional: Para mais sobre como a IA está evoluindo os paradigmas de busca, veja nosso artigo relacionado sobre busca por linguagem natural da Netflix.

Este conteúdo foi elaborado com o auxílio de ferramentas de IA, com base em fontes confiáveis, e revisado pela nossa equipe editorial antes da publicação. Não substitui o aconselhamento de um profissional especializado.