Como Construí um Gerador de llms.txt que Funciona em Escala

Este é o companheiro técnico do meu Eu Construí um Gerador de llms.txt, Mostrei ao Criador do Padrão e Tive que Reescrever Tudo — o lado humano está lá, aqui está apenas a engenharia.

O objetivo: gerar automaticamente uma hierarquia adequada de llms.txt para qualquer site — não um índice plano de resumos, mas um conjunto estruturado de arquivos MD onde páginas semanticamente relacionadas são mescladas em documentos coerentes. Aqui está como cada camada funciona e o que quebrou ao longo do caminho.

A Arquitetura

Sitemap → Crawler → Embedder → Clusterer → Summarizer → llms.txt + arquivos MD

Cinco estágios. Cada um opera em uma velocidade diferente. Cada um tem seus próprios modos de falha.

Estágio 1: Rastreamento

Rastreamento padrão com extração de conteúdo. A saída por página: caminho, título, texto limpo.

Páginas que falham ao rastrear são monitoradas, mas não interrompem o pipeline — uma página ausente simplesmente não contribui para seu cluster.

Estágio 2: Embeddings + Cache

Cada página é convertida em um vetor usando o modelo gemini-embedding-001 da Gemini.

Os vetores são armazenados em cache no Redis, indexados por hostname + modelo + caminho. Ao reprocessar o mesmo site, páginas já incorporadas são servidas do cache instantaneamente — sem chamadas de API, sem custo.

const allCached = await this.cacheService.hmget(
  hashKey,
  allPaths.map((p => `vectors:${p}`)
);
// Acertos de cache pulam a incorporação completamente

Isso é importante porque as incorporações são a etapa mais paralelizável e você não quer refazê-las em tentativas ou reinicializações.

Estágio 3: Agrupamento K-Means com Similaridade Cosseno

Páginas se agrupam por significado semântico, não pela estrutura da URL. Duas páginas sobre o mesmo conceito com diferentes caminhos de URL acabam no mesmo cluster. Três páginas sob /payments/checkout/ que cobrem tópicos diferentes acabam em clusters diferentes.

K-means implementado diretamente em TypeScript — sem bibliotecas externas de ML. Similaridade cosseno como a métrica de distância, não euclidiana — a cosseno funciona muito melhor para vetores de incorporação de alta dimensão.

private kMeans(vectors: number[][], k: number, maxIterations = 100): number[] {
  const dim = vectors[0].length;
  let centroids = vectors.slice(0, k).map((v => [...v]);
  let assignments = new Array<number>(vectors.length).fill(0);

  for (let iter = 0; iter < maxIterations; iter++) {
    const newAssignments = vectors.map((v) => {
      let minDist = Infinity, nearest = 0;
      for (let c = 0; c < centroids.length; c++) {
        const dist = 1 - this.cosineSimilarity(v, centroids[c]);
        if (dist < minDist) { minDist = dist; nearest = c; }
      }
      return nearest;
    });

    const changed = newAssignments.some((a, i) => a !== assignments[i]);
    assignments = newAssignments;
    if (!changed) {