Come Cerebras ha costruito la sua base di conoscenza interna

Autori: @hi_im_isaac_, @learnwdaniel, @gaozenghao

nota: la versione interattiva del blog tecnico completo è disponibile: https://www.cerebras.ai/blog/how-we-built-our-knowledge-base

I dipendenti pongono oltre 15.000 domande al giorno alla nostra knowledge base interna. È diventato uno degli strumenti interni più utilizzati in azienda dal suo lancio, 3 mesi fa. Utilizzato da persone, automazioni e agenti.

In Cerebras, i nostri team lavorano su operazioni dei data center, progettazione di chip, hardware, training, inferenza, piattaforma cloud e molto altro. Con centinaia di nuovi dipendenti che si uniscono ogni anno, i nostri canali di comunicazione si riempivano delle stesse domande:

• "Dove posso trovare X?"
• "Chi è l'esperto di Y?"
• "Cos'è Z?"

Abbiamo creato Cerebras Knowledge per aiutare le persone a mettere in contatto persone e sistemi con informazioni utili.

Incontrare i dati dove vivono

Trovare informazioni all'interno di un'organizzazione è difficile. I dati sono sparsi tra gli strumenti, e ogni trimestre circa qualcuno propone la stessa brillante soluzione: registriamo tutto in un'unica piattaforma in modo che tutte le informazioni siano in un unico posto. Il sogno di un'unica fonte di verità, ovviamente, raramente funziona nella pratica.

Le informazioni vengono generate dove è più comodo ed ergonomico: modifiche suggerite in un documento, thread in Slack, riferimenti a codice in GitHub e metadati di stato in Jira. Queste piattaforme sono su misura per i loro domini specifici, ottimizzate attraverso anni di ingegneria del prodotto e analisi. Discutere di una pull request in Google Docs sarebbe un'esperienza terribile.

Quindi abbiamo progettato un sistema che richiedesse modifiche minime al comportamento esistente. Sul lato della raccolta dati, ciò significava estrarre i dati direttamente da ciascuna piattaforma.

Anatomia di una knowledge base

La nostra knowledge base fornisce tre cose:

• Una piattaforma per raccogliere e archiviare dati interni.
• Una piattaforma per interrogare tali dati.
• Un livello che applica autenticazione e autorizzazione, con audit e analisi.

Al centro c'è una singola tabella Postgres che contiene embeddings, riepiloghi grezzi e metadati da molte fonti. Il sistema acquisisce continuamente dati da tutta l'azienda e mantiene un datastore pronto per le query.

Volevamo un'interfaccia dati semplice ma in grado di funzionare con la maggior parte delle forme di dati. Volevamo anche che altri sviluppatori in Cerebras potessero creare connettori personalizzati. Il risultato è volutamente semplice: ogni fonte, dai thread Slack ai netlist, finisce nella stessa tabella degli embeddings, e qualsiasi cosa in quella tabella è immediatamente interrogabile attraverso la stessa interfaccia:

Ogni fonte di dati definisce cosa sono i dati, come connettersi ad essi e con quale frequenza devono essere recuperati. Ogni riga di embedding risultante segue la stessa interfaccia, indipendentemente dal fatto che provenga da Slack, un repository di codice, un sistema di documenti o un database personalizzato.

Come elaboriamo le conversazioni non strutturate di Slack

Slack era la fonte di dati più importante per cui dovevamo progettare. È dove avvengono le discussioni di ingegneria più aggiornate in tutta l'azienda.

Inizialmente abbiamo testato se semplici embeddings sul testo grezzo funzionassero abbastanza bene. Ci siamo resi conto rapidamente che la sola ricerca vettoriale non era sufficiente per abbinare tutti i dati rilevanti.

I messaggi di Slack presentano diverse sfide:

• La densità delle informazioni varia enormemente: "ehi sì certo mike" e una spiegazione dettagliata del kernel sono entrambi messaggi.
• La lunghezza dei messaggi varia, e i messaggi più brevi spesso battono quelli più lunghi e dettagliati nella similarità del coseno.
• Il significato di un messaggio spesso dipende dalla conversazione circostante.

Avevamo bisogno di un approccio ibrido. Abbiamo costruito l'ingestion di Slack in modo che ogni thread sia recuperabile attraverso diverse tecniche di ricerca contemporaneamente, dove ogni tecnica compensa i punti deboli delle altre:

• La ricerca full-text cattura i token esatti che gli embeddings sfumano: stringhe di errore, nomi di flag, nomi host. Quando un ingegnere incolla un messaggio di errore letterale, una corrispondenza lessicale esatta è quasi sempre la prova migliore, e nessuna quantità di similarità semantica dovrebbe superarla.

• La ricerca per embedding cattura la parafrasi. La persona che chiede "ripristino si blocca dopo il caricamento del manifest" e la persona che ha risposto "il checkpoint si blocca sul mount NFS" potrebbero non condividere mai il vocabolario. La similarità vettoriale è ciò che collega una domanda a una risposta scritta con parole diverse.(1)

• La frequenza inversa del documento separa il segnale dal rumore. Un messaggio breve costruito attorno a token rari, come un flag di configurazione oscuro, merita di essere classificato. "suona bene, grazie!" è vicino a molte query nello spazio di embedding ma ottiene un punteggio vicino allo zero una volta che la rarità del termine viene presa in considerazione.

• Il decadimento temporale codifica che le risposte di Slack scadono. Due thread possono rispondere alla stessa domanda, e quello di sei mesi fa potrebbe descrivere un'infrastruttura che non esiste più. Quando la pertinenza è altrimenti uguale, vince il thread più recente.

Nessun singolo scorer è considerato affidabile da solo. Ogni tecnica produce la propria visione classificata dello stesso corpus, e queste visioni vengono fuse al momento della query (vedi Reranking).

Socket Mode

Per raccogliere dati in tempo reale, abbiamo installato un bot Slack nel nostro workspace e lo abbiamo eseguito in Socket Mode. Slack invia ogni evento di messaggio tramite un WebSocket persistente, quindi riceviamo aggiornamenti in tempo reale senza dover interrogare l'API Web e consumare i suoi limiti di frequenza.

Quando arriva un evento, lo riconosciamo immediatamente, lo deduplichiamo utilizzando l'ID evento stabile e contrassegniamo il messaggio per il consumatore di ingest.

Il consumatore di ingest non salva un nuovo messaggio in isolamento. Risolve il thread a cui appartiene il messaggio e recupera nuovamente l'intera conversazione, inclusi il genitore e ogni risposta, dall'API di Slack. Quindi scrive l'intero thread come una singola riga. Una risposta a un thread esistente quindi recupera nuovamente il genitore e tutti i fratelli, in modo che il contenuto memorizzato, l'elenco dei partecipanti e il timestamp dell'ultima attività riflettano sempre la conversazione completa.

Ogni canale Slack nel nostro sistema ha la propria fonte di dati. Ciò fornisce una messa a punto granulare per la freschezza dei dati. Un team può scegliere di acquisire un canale di incidenti molto trafficato più frequentemente, per esempio.

Thread e messaggi

Il testo grezzo di Slack è ricercabile per parole chiave non appena arriva perché manteniamo un indice full-text (GIN) Postgres sul contenuto grezzo. Per abilitare una ricerca vettoriale utile, tuttavia, eseguiamo un'elaborazione aggiuntiva.(8)

Durante la distillazione, un LLM estrae dati strutturati dal thread completo:

• Una domanda in una riga che un ingegnere cercherebbe effettivamente.
• Un breve riepilogo.
• La risoluzione.
• I sistemi e i riferimenti al codice menzionati.

Incorporiamo questi punti dati e li scriviamo nella tabella degli embeddings condivisa. La trascrizione originale non viene incorporata direttamente. Nei nostri esperimenti, la precisione è aumentata in modo significativo quando il thread è stato normalizzato in un formato coerente.(7,9) I metadati aggiuntivi danno anche alla corrispondenza semantica un segnale più utile.

Bursting

A questo punto la ricerca di Slack era buona, ma continuavamo a incontrare lo stesso problema: i messaggi importanti all'interno di thread lunghi non erano sempre rappresentati nel riepilogo a livello di thread.

Per aumentare il segnale dei singoli messaggi, utilizziamo il bursting. Un burst è una sequenza di messaggi consecutivi dello stesso autore. Incorporiamo i singoli burst con l'argomento del thread preposto come contesto(2) perché a volte la risposta vive in un messaggio tangente il cui vocabolario non arriva mai nel riepilogo del thread. Gli embedding dei burst rendono quel messaggio trovabile da solo.

Per evitare che dati a basso segnale raggiungano il database, ogni burst viene valutato rispetto a una combinazione ponderata di segnali e deve superare una soglia prima di essere incorporato:

• Contiene un token relativamente raro nel corpus, con IDF di almeno 4.0.
• Il burst combinato è di almeno 200 caratteri.
• Uno o più messaggi nel burst contengono reazioni, fornendo un boost sociale.

Dopo la distillazione, i burst qualificanti vengono incorporati e archiviati nella tabella degli embeddings insieme al record a livello di thread.

Repository di codice

Inizialmente abbiamo discusso se fosse necessario incorporare i repository di codice. Con l'ascesa di Claude Code e altri strumenti da riga di comando, creare embedding di codice sembrava controintuitivo quando sembrava che "grep sia tutto ciò di cui hai bisogno". Dopo aver parlato con altri nel settore e aver letto i risultati di Cursor sulla ricerca semantica in grandi codebase, abbiamo deciso di provare.

Abbiamo molti repository interni, alcuni più grandi di 40 GB. La nostra preoccupazione principale era come mantenerli aggiornati in modo efficiente.

Utilizzo di @cocoindex_io per mantenere gli embedding del codice

Dopo diversi esperimenti, abbiamo optato per CocoIndex, un framework open-source per l'embedding di documenti specializzato nella vettorizzazione di codebase.

Per ogni repository, suddividiamo il codice utilizzando confini regex specifici del linguaggio ordinati dal grossolano al fine. Lo splitter prova prima i confini di livello superiore, come le classi. Se un pezzo risultante è ancora troppo grande, passa ai confini dei metodi e poi a blocchi più piccoli. Incorporiamo i pezzi risultanti e scriviamo i vettori in Postgres. Un singolo file può generare più embedding a diversi livelli di specificità, come record a livello di file e a livello di funzione.

CocoIndex tiene traccia dei metadati di sincronizzazione in Postgres. Ad ogni commit, re-incorpora e riesporta solo i pezzi di codice modificati invece di ricalcolare l'intero repository. Questo ha funzionato particolarmente bene per noi perché lo stato di sincronizzazione e l'archivio degli embedding vivono nello stesso database.

Con la crescita del numero di codebase, abbiamo spostato l'onboarding dei repository in file di configurazione che i team possono inviare da soli, incluse liste di consentiti e bloccati a livello di percorso file.

Fonti di dati personalizzate

Alcuni team avevano già i propri database e non volevano spostare i dati in Slack o in un sistema di documenti solo per partecipare alla knowledge base. Volevano la stessa superficie di query sulle loro tabelle esistenti.

Per supportare questo, trattiamo le fonti personalizzate come script plugin. Un team apre una pull request con un piccolo modulo Python che sa come leggere dal suo sistema ed emettere righe modellate come la nostra tabella degli embeddings, più una voce di fonte dati corrispondente.

Finché lo script scrive nel database condiviso utilizzando lo stesso schema di ogni altra riga di embedding, il resto dello stack funziona invariato. I dati diventano interrogabili insieme a Slack, codice e documenti, senza alcuna gestione speciale altrove nel sistema.

Pianificazione e fan-out degli strumenti

Per ogni query, eseguiamo prima un breve passaggio di pianificazione in cui un LLM decide quali strumenti e fonti di dati sono probabilmente rilevanti. Gli strumenti principali:

• subsystem_index: riepiloghi LLM per file.
• search: la pipeline vettoriale unificata attraverso Slack, wiki, codice e altre fonti indicizzate, unite e riordinate internamente.
• search_slack: recupero diretto da Slack.
• search_code: ripgrep sui repository sorgente.
• recent_prs: pull request recenti pertinenti alla domanda.
• who_knows: persone con comprovata esperienza su un argomento.

Il pianificatore lavora su una descrizione compatta di ciò che abbiamo indicizzato: quali progetti esistono, quali fonti sono disponibili in ogni progetto e per cosa è brava a rispondere ogni fonte. Data la query dell'utente e l'ambito attivo, emette selezioni di strumenti che l'esecutore distribuisce in parallelo, normalizza in un formato di evidenza comune e passa a un LLM di sintesi finale.(4)

Reranking

Un documento può apparire in cima semplicemente perché condivide il vocabolario con la query mentre risponde a una domanda diversa. Prima del reranking, combiniamo le liste di risultati incompatibili dei recuperatori con la fusione del rango reciproco, o RRF. Per ogni documento, aggiungiamo peso / (60 + rango) per ogni lista in cui appare, con un peso predefinito di 1.0 e una costante di smoothing di 60.

La costante di smoothing fa sì che il consenso conti più di un singolo voto forte: un documento che appare vicino alla cima in diversi recuperatori può batterne uno che è primo in uno solo di essi. Quindi uniamo i pezzi duplicati in un'unica fonte, limitiamo quanti risultati ogni file può contribuire e finiamo con una top twenty più diversificata.

Inviiamo la query originale e quei candidati a un piccolo modello di reranking. Assegna a ogni documento un punteggio da zero a dieci e manteniamo i primi dieci.(6)

Una volta che la classifica è finale, aggiungiamo il contesto ai vincitori. Ad esempio, se corrispondiamo a una sezione wiki, tiriamo dentro le due sezioni vicine in modo che l'intestazione, le precondizioni e le avvertenze che lo chunking ha separato non vadano perse. Questo dà ai lettori un frammento completo invece di un paragrafo solitario a cui manca un contesto importante.

Quindi l'output della ricerca è un ricco pacchetto di evidenze: risultati fusi da diversi recuperatori, deduplicati a livello di fonte, riordinati rispetto alla domanda effettiva e solo allora espansi con il contesto circostante.

MCP

Nell'integrazione MCP, esponiamo i blocchi costitutivi del recupero come strumenti diretti invece di nasconderli dietro un endpoint "rispondi a questa domanda". Questi strumenti sono intenzionalmente semplici e il più possibile privi di LLM in modo che i client possano interrogarli rapidamente ed economicamente.(5)

Ogni strumento MCP corrisponde a un primitivo di recupero sottostante, come search_slack, search_code, search o who_knows. Gli input e gli output dello strumento sono stretti, strutturati e stabili, rendendoli facili da chiamare da qualsiasi client o agente senza incorporare logica di orchestrazione aggiuntiva all'interno dello strumento stesso.

La maggior parte degli strumenti esegue una pipeline di query, come ricerca vettoriale, ricerca lessicale o ripgrep, applica euristiche di punteggio leggere e restituisce righe di evidenza grezze.

Claude Code, o qualsiasi agente compatibile con MCP, diventa il motore di orchestrazione. Decide quali strumenti chiamare, in quale ordine e come assemblare i risultati in una risposta finale o modifica del codice. Il livello di recupero stesso non dipende da quelle decisioni LLM per servire le richieste.

Interfaccia Web

Nell'interfaccia web, gli stessi strumenti esistono, ma sono collegati a una pipeline di query completa che viene eseguita end-to-end per ogni domanda dell'utente. L'agente dell'interfaccia possiede i passaggi del pianificatore e dell'esecutore.

• Pianificatore: Un passaggio LLM leggero ispeziona la query e il progetto attivo, quindi sceglie quali strumenti di recupero invocare, come search, search_slack e subsystem_index.

• Esecutore: Il sistema distribuisce queste chiamate agli strumenti in parallelo, raccoglie i risultati e li normalizza in uno schema di evidenza condiviso con punteggi, recency e suggerimenti sulla fonte.

• Sintesi: Un passaggio LLM finale prende il pacchetto di evidenze tipizzate e la domanda originale, quindi produce la risposta mostrata nell'interfaccia, incluse citazioni, avvertenze e sintesi tra fonti.

Dal punto di vista dell'utente, l'interfaccia web è semplicemente "fai una domanda e ottieni una risposta". Sotto il cofano, esegue lo stesso schema pianificatore → esecutore → sintetizzatore che i client MCP possono ricreare esplicitamente.

Organizzazione

Con la crescita del corpus, "cerca tutto ovunque" ha rapidamente smesso di essere utile. Gli ingegneri dei team del compilatore non volevano manuali di infrastruttura nei loro risultati, e viceversa. I progetti sono il modo in cui rendiamo la ricerca pertinente per impostazione predefinita.

Progetti e ricerca con ambito

Abbiamo introdotto i progetti come il modo principale per organizzare lo spazio di lavoro su cui viene eseguita una query. Un progetto è un insieme denominato di fonti di dati: canali Slack specifici, repository di codice, database interni e spazi di documenti pertinenti a un team o iniziativa.

I progetti sono intenzionalmente leggeri. La stessa fonte di dati, come un canale di incidenti condiviso o un repository di piattaforma centrale, può essere referenziata da più progetti invece di essere duplicata.

Onboarding e impostazioni predefinite

Durante l'onboarding, agli utenti viene chiesto di selezionare o creare un progetto predefinito che corrisponda al loro modo di lavorare, come infrastruttura di training ML, Compiler o Operazioni del Data Center.

Quel progetto predefinito viene memorizzato sul profilo utente e limita automaticamente le query. Un nuovo ingegnere ottiene risposte ad alto segnale senza prima dover imparare quali canali Slack, repository o spazi di documenti sono importanti.

Considerazioni finali

Alla fine, la knowledge base funziona perché incontra le persone dove le informazioni già vivono, invece di forzare tutto in un unico sistema rigido. Combinando varie tecniche di ricerca, possiamo far emergere rapidamente le evidenze. Il risultato è un'esperienza di ricerca che rimane abbastanza flessibile per i dati aziendali reali, ma abbastanza strutturata da rimanere utile mentre Cerebras continua a crescere.

Se hai letto fin qui e questo ti interessa, il team ai/growth sta assumendo, contattaci se sei interessato @learnwdaniel

Riferimenti

1. Malkov e Yashunin, Efficient and Robust Approximate Nearest Neighbor Search Using Hierarchical Navigable Small World Graphs, arXiv:1603.09320 / IEEE TPAMI 2018.

1. Anthropic, Introducing Contextual Retrieval, 2024.

1. Cormack, Clarke e Büttcher, Reciprocal Rank Fusion Outperforms Condorcet and Individual Rank Learning Methods, SIGIR 2009.

1. Li et al., Search-o1: Agentic Search-Enhanced Large Reasoning Models, arXiv:2501.05366, 2025.

1. Anthropic, Code Execution with MCP, 2025.

1. Liu et al., Lost in the Middle: How Language Models Use Long Contexts, arXiv:2307.03172, 2023.

1. Anthropic, Use XML Tags.

1. Salesforce/Slack Engineering, How Slack AI Processes Billions of Messages.

1. Improving Agents, Best Nested Data Format.

1. Cursor, Improving Agent with Semantic Search, 2025.