Autores: @hi_im_isaac_, @learnwdaniel, @gaozenghao
nota: la versión interactiva del blog técnico completo disponible: https://www.cerebras.ai/blog/how-we-built-our-knowledge-base
Los empleados le hacen más de 15,000 preguntas cada día a nuestra base de conocimiento interna. Se ha convertido en una de las herramientas internas más adoptadas en la empresa desde su lanzamiento hace 3 meses. Es utilizada por personas, automatizaciones y agentes.
En Cerebras, nuestros equipos trabajan en operaciones de centros de datos, diseño de chips, hardware, entrenamiento, inferencia, plataforma en la nube y más. Con cientos de nuevos empleados uniéndose cada año, nuestros canales de comunicación se llenaban con las mismas preguntas:
- “¿Dónde puedo encontrar X?”
- “¿Quién es el experto en Y?”
- “¿Qué es Z?”
Construimos Cerebras Knowledge para ayudar a conectar personas y sistemas con información útil.
Encontrando los datos donde viven
Encontrar información dentro de una organización es difícil. Los datos están dispersos en varias herramientas, y cada trimestre o así alguien propone la misma solución brillante: registrémoslo todo en una sola plataforma para que toda la información esté en un solo lugar. El sueño de una única fuente de verdad, por supuesto, rara vez funciona en la práctica.
La información se genera donde es conveniente y ergonómico: sugerencias de edición en un documento, hilos en Slack, referencias de código en GitHub y metadatos de estado en Jira. Estas plataformas están hechas a la medida para sus dominios específicos, optimizadas a través de años de ingeniería de producto y análisis. Discutir una pull request en Google Docs sería una experiencia terrible.
Por eso nos propusimos diseñar un sistema que requiriera un cambio mínimo en el comportamiento existente. En el lado de la recolección de datos, esto significó extraer datos directamente de cada plataforma.
Anatomía de una base de conocimiento
Nuestra base de conocimiento ofrece tres cosas:
- Una plataforma para recolectar y almacenar datos internos.
- Una plataforma para consultar esos datos.
- Una capa que aplica autenticación y autorización, con auditoría y análisis.
En el núcleo hay una sola tabla de Postgres que almacena embeddings, resúmenes en bruto y metadatos de muchas fuentes. El sistema ingiere datos continuamente de toda la empresa y mantiene un almacén de datos listo para consultas.
Queríamos una interfaz de datos que fuera simple pero que pudiera funcionar con la mayoría de las formas de datos. También queríamos que otros desarrolladores en Cerebras pudieran construir conectores personalizados. El resultado es deliberadamente simple: cada fuente, desde hilos de Slack hasta netlists, termina en la misma tabla de embeddings, y cualquier cosa en esa tabla es inmediatamente consultable a través de la misma interfaz:
Cada fuente de datos define qué son los datos, cómo conectarse a ellos y con qué frecuencia deben obtenerse. Cada fila de embedding resultante sigue la misma interfaz independientemente de si proviene de Slack, un repositorio de código, un sistema de documentos o una base de datos personalizada.
Cómo procesamos conversaciones no estructuradas de Slack
Slack fue la fuente de datos más importante que necesitábamos diseñar. Es donde ocurren las discusiones de ingeniería más actualizadas en toda la empresa.
Inicialmente probamos si los embeddings simples sobre texto en bruto funcionaban lo suficientemente bien. Rápidamente nos dimos cuenta de que la búsqueda vectorial por sí sola no era suficiente para encontrar todos los datos relevantes.
Los mensajes de Slack presentan varios desafíos:
- La densidad de información varía enormemente: "hey sí claro mike" y una explicación detallada del kernel son ambos mensajes.
- Las longitudes de los mensajes varían, y los mensajes más cortos frecuentemente superan a los más largos y detallados en similitud coseno.
- El significado de un mensaje a menudo depende de la conversación circundante.
Necesitábamos un enfoque híbrido. Construimos la ingesta de Slack para que cada hilo se pueda recuperar a través de varias técnicas de búsqueda a la vez, donde cada técnica compensa las debilidades de las otras:
- La búsqueda de texto completo captura los tokens exactos que los embeddings difuminan: cadenas de error, nombres de flags, nombres de host. Cuando un ingeniero pega un mensaje de error literal, una coincidencia léxica exacta es casi siempre la mejor evidencia, y ninguna cantidad de similitud semántica debería superarla.
- La búsqueda por embeddings captura paráfrasis. La persona que pregunta "restore se cuelga después de la carga de manifiesto" y la que respondió "checkpoint se atasca en el montaje NFS" pueden no compartir vocabulario. La similitud vectorial es lo que conecta una pregunta con una respuesta escrita con palabras diferentes.(1)
- La frecuencia inversa de documento separa la señal del relleno. Un mensaje corto construido alrededor de tokens raros, como un flag de configuración oscuro, merece clasificarse alto. "suena bien, ¡gracias!" está cerca de muchas consultas en el espacio de embeddings, pero puntúa cerca de cero una vez que se tiene en cuenta la rareza del término.
- La decadencia por edad codifica que las respuestas de Slack caducan. Dos hilos pueden responder la misma pregunta, y el de hace seis meses puede describir una infraestructura que ya no existe. Cuando la relevancia es igual por lo demás, el hilo más nuevo gana.
Ningún puntuador individual es confiable por sí solo. Cada técnica produce su propia vista clasificada del mismo corpus, y esas vistas se fusionan en el momento de la consulta (ver Reordenamiento).
Modo Socket
Para recolectar datos en tiempo real, instalamos un bot de Slack en nuestro espacio de trabajo y lo ejecutamos en Modo Socket. Slack nos envía cada evento de mensaje a través de un WebSocket persistente, por lo que recibimos actualizaciones en tiempo real sin tener que consultar la API Web y consumir sus límites de tasa.
Cuando llega un evento, lo reconocemos inmediatamente, lo deduplicamos usando el ID de evento estable, y marcamos el mensaje para el consumidor de ingesta.
El consumidor de ingesta no guarda un mensaje nuevo de forma aislada. Resuelve el hilo al que pertenece el mensaje y vuelve a obtener toda la conversación, incluyendo el mensaje padre y todas las respuestas, desde la API de Slack. Luego escribe todo el hilo de vuelta como una sola fila. Una respuesta a un hilo existente, por lo tanto, vuelve a extraer el padre y todos los hermanos, de modo que el contenido almacenado, la lista de participantes y la marca de tiempo de última actividad siempre reflejen la conversación completa.
Cada canal de Slack en nuestro sistema tiene su propia fuente de datos. Esto proporciona un ajuste fino para la frescura de los datos. Un equipo puede optar por ingerir un canal de incidentes ocupado con más frecuencia, por ejemplo.
Hilos y mensajes
El texto en bruto de Slack se puede buscar por palabras clave tan pronto como llega porque mantenemos un índice de texto completo (GIN) de Postgres sobre el contenido en bruto. Sin embargo, para habilitar una búsqueda vectorial útil, hacemos algo de procesamiento adicional.(8)
Durante la destilación, un LLM extrae datos estructurados del hilo completo:
- Una pregunta de una línea que un ingeniero buscaría realmente.
- Un resumen corto.
- La resolución.
- Los sistemas y referencias de código mencionados.
Embedimos estos puntos de datos y los escribimos en la tabla de embeddings compartida. La transcripción original no se embed directamente. En nuestros experimentos, la precisión aumentó significativamente cuando el hilo se normalizó en un formato consistente.(7,9) Los metadatos adicionales también le dan a la coincidencia semántica una señal más útil.
Bursting
En este punto, la búsqueda en Slack era buena, pero seguíamos encontrando el mismo problema: los mensajes importantes dentro de hilos largos no siempre estaban representados en el resumen a nivel de hilo.
Para aumentar la señal de mensajes individuales, usamos bursting. Un burst es una secuencia de mensajes consecutivos del mismo autor. Embedimos bursts individuales con el tema del hilo antepuesto como contexto(2) porque a veces la respuesta vive en un mensaje tangente cuyo vocabulario nunca llega al resumen del hilo. Los embeddings de burst hacen que ese mensaje se pueda encontrar por sí solo.
Para evitar que los datos de baja señal lleguen a la base de datos, cada burst se puntúa contra una combinación ponderada de señales y debe superar un umbral antes de ser embebido:
- Contiene un token relativamente raro en el corpus, con un IDF de al menos 4.0.
- El burst combinado tiene al menos 200 caracteres.
- Uno o más mensajes en el burst contienen reacciones, lo que proporciona un impulso social.
Después de la destilación, los bursts que califican se embeben y almacenan en la tabla de embeddings junto con el registro a nivel de hilo.
Repositorios de código
Inicialmente debatimos si era necesario embeder repositorios de código. Con el auge de Claude Code y otras herramientas de línea de comandos, crear embeddings de código parecía contradictorio cuando parecía que "grep es todo lo que necesitas". Después de hablar con otros en la industria y leer los hallazgos de Cursor sobre la búsqueda semántica en bases de código grandes, decidimos intentarlo.
Tenemos muchos repositorios internos, algunos de más de 40 GB. Nuestra principal preocupación era cómo mantenerlos actualizados de manera eficiente.
Usando @cocoindex_io para mantener los embeddings de código
Después de varios experimentos, nos decidimos por CocoIndex, un framework de código abierto para embeddings de documentos que se especializa en vectorizar bases de código.
Para cada repositorio, dividimos el código usando límites de expresiones regulares específicos del lenguaje, ordenados de grueso a fino. El divisor primero intenta límites de nivel superior, como clases. Si el fragmento resultante sigue siendo demasiado grande, recurre a límites de métodos y luego a bloques más pequeños. Embedimos los fragmentos resultantes y escribimos los vectores en Postgres. Un solo archivo puede generar múltiples embeddings a diferentes niveles de especificidad, como registros a nivel de archivo y a nivel de función.
CocoIndex rastrea metadatos de sincronización en Postgres. En cada commit, re-embede y re-exporta solo los fragmentos de código cambiados, en lugar de volver a calcular todo el repositorio. Esto funcionó especialmente bien para nosotros porque el estado de sincronización y el almacén de embeddings viven en la misma base de datos.
A medida que creció el número de bases de código, trasladamos la incorporación de repositorios a archivos de configuración que los equipos pueden enviar ellos mismos, incluyendo listas de permitidos y denegados a nivel de ruta de archivo.
Fuentes de datos personalizadas
Algunos equipos ya tenían sus propias bases de datos y no querían mover datos a Slack o a un sistema de documentos solo para participar en la base de conocimiento. Querían la misma superficie de consulta sobre sus tablas existentes.
Para admitir esto, tratamos las fuentes personalizadas como scripts de plugin. Un equipo abre una pull request con un pequeño módulo de Python que sabe cómo leer de su sistema y emitir filas con la forma de nuestra tabla de embeddings, más una entrada de fuente de datos coincidente.
Mientras el script escriba en la base de datos compartida usando el mismo esquema que cualquier otra fila de embedding, el resto del stack funciona sin cambios. Los datos se vuelven consultables junto con Slack, código y documentos, sin necesidad de manejo especial en ninguna otra parte del sistema.
Planificación y despliegue de herramientas
Para cada consulta, primero ejecutamos un breve paso de planificación donde un LLM decide qué herramientas y fuentes de datos probablemente importan. Las herramientas principales:
- subsystem_index: resúmenes de LLM por archivo.
- search: el pipeline vectorial unificado a través de Slack, wiki, código y otras fuentes indexadas, fusionado y reordenado internamente.
- search_slack: recuperación directa de Slack.
- search_code: ripgrep sobre repositorios fuente.
- recent_prs: pull requests recientes relevantes a la pregunta.
- who_knows: personas con experiencia demostrada en un tema.
El planificador trabaja sobre una descripción compacta de lo que tenemos indexado: qué proyectos existen, qué fuentes están disponibles en cada proyecto, y para qué es buena cada fuente para responder. Dada la consulta del usuario y el alcance activo, emite selecciones de herramientas que el ejecutor despliega en paralelo, normaliza en un formato de evidencia común, y pasa a un LLM de síntesis final.(4)
Reordenamiento
Un documento puede aparecer cerca de la parte superior simplemente porque comparte vocabulario con la consulta mientras responde una pregunta diferente. Antes del reordenamiento, combinamos las listas de resultados incompatibles de los recuperadores con fusión de rango recíproco, o RRF. Para cada documento, agregamos peso / (60 + rango) por cada lista en la que aparece, con un peso predeterminado de 1.0 y una constante de suavizado de 60.
La constante de suavizado hace que el consenso importe más que un solo voto fuerte: un documento que aparece cerca de la parte superior en varios recuperadores puede vencer a uno que ocupa el primer lugar en solo uno de ellos. Luego fusionamos los fragmentos duplicados de vuelta a una fuente, limitamos cuántos resultados puede contribuir cada archivo, y terminamos con un top veinte más diverso.
Enviamos la consulta original y esos candidatos a un modelo reordenador pequeño. Le da a cada documento una puntuación de cero a diez, y nos quedamos con los diez primeros.(6)
Una vez que la clasificación es final, agregamos contexto de vuelta a los ganadores. Por ejemplo, si coincidimos con una sección del wiki, incorporamos las dos secciones vecinas para que el encabezado, las condiciones previas y las advertencias que la división en fragmentos separó no se pierdan. Esto le da a los lectores un fragmento completo en lugar de un párrafo solitario que carece de contexto importante.
Entonces, el resultado de la búsqueda es un paquete rico de evidencia: resultados fusionados de diferentes recuperadores, deduplicados a nivel de fuente, reordenados contra la pregunta real, y solo entonces expandidos con contexto circundante.
MCP
En la integración MCP, exponemos los bloques de construcción de recuperación como herramientas directas en lugar de ocultarlos detrás de un único endpoint "responde esta pregunta". Estas herramientas son intencionalmente simples y lo más libres de LLM posible para que los clientes puedan consultarlas de manera rápida y económica.(5)
Cada herramienta MCP corresponde a un primitivo de recuperación subyacente, como search_slack, search_code, search o who_knows. Las entradas y salidas de las herramientas son estrechas, estructuradas y estables, lo que facilita su llamada desde cualquier cliente o agente sin necesidad de incorporar lógica de orquestación adicional dentro de la herramienta misma.
La mayoría de las herramientas ejecutan un pipeline de consulta, como búsqueda vectorial, búsqueda léxica o ripgrep, aplican heurísticas de puntuación ligeras y devuelven filas de evidencia en bruto.
Claude Code, o cualquier agente compatible con MCP, se convierte en el motor de orquestación. Decide qué herramientas llamar, en qué orden y cómo ensamblar los resultados en una respuesta final o edición de código. La capa de recuperación en sí no depende de esas decisiones del LLM para atender las solicitudes.
Interfaz web
En la interfaz web, las mismas herramientas existen, pero están conectadas a un pipeline de consulta completo que se ejecuta de principio a fin para cada pregunta del usuario. El agente de la interfaz posee los pasos de planificador y ejecutor.
- Planificador: Un paso ligero de LLM inspecciona la consulta y el proyecto activo, luego elige qué herramientas de recuperación invocar, como search, search_slack y subsystem_index.
- Ejecutor: El sistema despliega esas llamadas a herramientas en paralelo, recoge los resultados y los normaliza en un esquema de evidencia compartido con puntuaciones, actualidad y sugerencias de fuente.
- Síntesis: Un paso final de LLM toma el paquete de evidencia tipado y la pregunta original, luego produce la respuesta que se muestra en la interfaz, incluyendo citas, advertencias y síntesis entre fuentes.
Desde la perspectiva del usuario, la interfaz web es simplemente "hacer una pregunta y obtener una respuesta". Bajo el capó, ejecuta el mismo patrón de planificador → ejecutor → sintetizador que los clientes MCP pueden recrear explícitamente.
Organización
A medida que el corpus creció, "buscar en todos lados" rápidamente dejó de ser útil. Los ingenieros de equipos de compiladores no querían manuales de infraestructura en sus resultados, y viceversa. Los proyectos son cómo hacemos que la búsqueda sea relevante por defecto.
Proyectos y búsqueda con alcance
Introdujimos los proyectos como la forma principal de organizar el espacio de trabajo sobre el que se ejecuta una consulta. Un proyecto es un conjunto nombrado de fuentes de datos: canales específicos de Slack, repositorios de código, bases de datos internas y espacios de documentos relevantes para un equipo o iniciativa.
Los proyectos son intencionalmente ligeros. La misma fuente de datos, como un canal de incidentes compartido o un repositorio de plataforma central, puede ser referenciada por múltiples proyectos en lugar de ser duplicada.
Incorporación y valores predeterminados
Durante la incorporación, se solicita a los usuarios que seleccionen o creen un proyecto predeterminado que coincida con su forma de trabajar, como infraestructura de entrenamiento de ML, Compilador u Operaciones de Centro de Datos.
Ese proyecto predeterminado se almacena en el perfil del usuario y limita las consultas automáticamente. Un nuevo ingeniero obtiene respuestas de alta señal sin tener que aprender primero qué canales de Slack, repositorios o espacios de documentos son importantes.
Reflexiones finales
Al final, la base de conocimiento funciona porque encuentra a las personas donde la información ya vive, en lugar de forzar todo en un sistema rígido. Al combinar varias técnicas de búsqueda, podemos sacar a la superficie la evidencia rápidamente. El resultado es una experiencia de búsqueda que se mantiene lo suficientemente flexible para datos reales de la empresa, pero lo suficientemente estructurada para seguir siendo útil a medida que Cerebras sigue creciendo.
Si has llegado hasta aquí y esto te resulta interesante, el equipo de ai/growth está contratando. Ponte en contacto si estás interesado @learnwdaniel
Referencias
- Malkov y Yashunin, Búsqueda eficiente y robusta de vecinos más cercanos aproximados mediante grafos de mundo pequeño navegables jerárquicos, arXiv:1603.09320 / IEEE TPAMI 2018.
- Anthropic, Introducción a la Recuperación Contextual, 2024.
- Cormack, Clarke y Büttcher, La fusión de rango recíproco supera a Condorcet y a los métodos individuales de aprendizaje de clasificación, SIGIR 2009.
- Li et al., Search-o1: Modelos de Razonamiento Ampliados Mejorados con Búsqueda Agentica, arXiv:2501.05366, 2025.
- Anthropic, [*Ejecución de Código con MCP
