@intlayer/docs 5.8.1 → 6.0.0-canary.0

package/blog/es/rag_powered_documentation_assistant.md

@@ -0,0 +1,308 @@
+---
+createdAt: 2025-09-10
+updatedAt: 2025-09-10
+title: Construyendo un Asistente de Documentación Potenciado por RAG (Fragmentación, Embeddings y Búsqueda)
+description: Construyendo un Asistente de Documentación Potenciado por RAG (Fragmentación, Embeddings y Búsqueda)
+keywords:
+  - RAG
+  - Documentación
+  - Asistente
+  - Fragmentación
+  - Embeddings
+  - Búsqueda
+slugs:
+  - blog
+  - rag-powered-documentation-assistant
+---
+
+# Construyendo un Asistente de Documentación Potenciado por RAG (Fragmentación, Embeddings y Búsqueda)
+
+## Lo que obtienes
+
+He construido un asistente de documentación potenciado por RAG y lo empaqueté en una plantilla que puedes usar de inmediato.
+
+- Viene con una aplicación lista para usar (Next.js + API de OpenAI)
+- Incluye una pipeline RAG funcional (fragmentación, embeddings, similitud coseno)
+- Proporciona una interfaz completa de chatbot construida en React
+- Todos los componentes de la interfaz de usuario son completamente editables con Tailwind CSS
+- Registra cada consulta del usuario para ayudar a identificar documentación faltante, puntos de dolor del usuario y oportunidades de producto
+
+👉 [Demostración en vivo](https://intlayer.org/doc/why) 👉 [Plantilla de código](https://github.com/aymericzip/smart_doc_RAG)
+
+## Introducción
+
+Si alguna vez te has perdido en la documentación, desplazándote sin fin en busca de una respuesta, sabes lo doloroso que puede ser. La documentación es útil, pero es estática y buscar en ella a menudo se siente torpe.
+
+Ahí es donde entra **RAG (Generación Aumentada por Recuperación)**. En lugar de obligar a los usuarios a buscar entre el texto, podemos combinar **recuperación** (encontrar las partes correctas de la documentación) con **generación** (dejar que un LLM lo explique de forma natural).
+
+En esta publicación, te guiaré a través de cómo construí un chatbot de documentación potenciado por RAG y cómo no solo ayuda a los usuarios a encontrar respuestas más rápido, sino que también ofrece a los equipos de producto una nueva forma de entender los puntos de dolor de los usuarios.
+
+## ¿Por qué usar RAG para la documentación?
+
+RAG se ha convertido en un enfoque popular por una razón: es una de las formas más prácticas de hacer que los grandes modelos de lenguaje sean realmente útiles.
+
+Para la documentación, los beneficios son claros:
+
+- Respuestas instantáneas: los usuarios preguntan en lenguaje natural y obtienen respuestas relevantes.
+- Mejor contexto: el modelo solo ve las secciones de documentación más relevantes, reduciendo las alucinaciones.
+- Búsqueda que se siente humana: más como Algolia + FAQ + chatbot, todo en uno.
+- Ciclo de retroalimentación: al almacenar las consultas, descubres con qué realmente tienen dificultades los usuarios.
+
+Ese último punto es crucial. Un sistema RAG no solo responde preguntas, sino que te dice qué es lo que la gente está preguntando. Eso significa:
+
+- Descubres información faltante en tus documentos.
+- Ves solicitudes de funciones emergentes.
+- Detectas patrones que incluso pueden guiar la estrategia del producto.
+
+Así que, RAG no es solo una herramienta de soporte. También es un **motor de descubrimiento de producto**.
+
+## Cómo funciona la canalización RAG
+
+![RAG Pipeline](https://github.com/aymericzip/intlayer/blob/main/docs/assets/rag_flow.svg)
+
+A grandes rasgos, esta es la receta que usé:
+
+1.  **Dividir la documentación en fragmentos** Los archivos grandes de Markdown se dividen en fragmentos. Dividir permite proporcionar como contexto solo las partes relevantes de la documentación.
+2.  **Generar embeddings** Cada fragmento se convierte en un vector usando la API de embeddings de OpenAI (text-embedding-3-large) o una base de datos vectorial (Chroma, Qdrant, Pinecone).
+3.  **Indexación y almacenamiento** Los embeddings se almacenan en un archivo JSON simple (para mi demo), pero en producción, probablemente usarías una base de datos vectorial.
+4.  **Recuperación (R en RAG)** Se incrusta la consulta del usuario, se calcula la similitud coseno y se recuperan los fragmentos que mejor coinciden.
+5.  **Aumento + Generación (AG en RAG)** Esos fragmentos se inyectan en el prompt para ChatGPT, de modo que el modelo responda con el contexto real de la documentación.
+6.  **Registro de consultas para retroalimentación** Cada consulta del usuario se almacena. Esto es oro para entender puntos problemáticos, documentación faltante o nuevas oportunidades.
+
+## Paso 1: Leer la documentación
+
+El primer paso fue simple: necesitaba una forma de escanear una carpeta docs/ para todos los archivos .md. Usando Node.js y glob, obtuve el contenido de cada archivo Markdown en memoria.
+
+Esto mantiene la canalización flexible: en lugar de Markdown, podrías obtener documentos de una base de datos, un CMS o incluso una API.
+
+## Paso 2: Dividir la Documentación en Fragmentos
+
+¿Por qué dividir en fragmentos? Porque los modelos de lenguaje tienen **límites de contexto**. Alimentarlos con un libro entero de documentación no funcionará.
+
+Entonces, la idea es dividir el texto en fragmentos manejables (por ejemplo, 500 tokens cada uno) con solapamiento (por ejemplo, 100 tokens). El solapamiento asegura continuidad para que no pierdas el significado en los límites de los fragmentos.
+
+**Ejemplo:**
+
+- Fragmento 1 → “…la vieja biblioteca que muchos habían olvidado. Sus estanterías imponentes estaban llenas de libros…”
+- Fragmento 2 → “…las estanterías estaban llenas de libros de todos los géneros imaginables, cada uno susurrando historias…”
+
+El solapamiento asegura que ambos fragmentos contengan contexto compartido, por lo que la recuperación permanece coherente.
+
+Este compromiso (tamaño del fragmento vs superposición) es clave para la eficiencia de RAG:
+
+- Demasiado pequeño → obtienes ruido.
+- Demasiado grande → explotas el tamaño del contexto.
+
+## Paso 3: Generación de Embeddings
+
+Una vez que los documentos están fragmentados, generamos **embeddings** — vectores de alta dimensión que representan cada fragmento.
+
+Usé el modelo text-embedding-3-large de OpenAI, pero podrías usar cualquier modelo moderno de embeddings.
+
+**Ejemplo de embedding:**
+
+```js
+[
+  -0.0002630692, -0.029749284, 0.010225477, -0.009224428, -0.0065269712,
+  -0.002665544, 0.003214777, 0.04235309, -0.033162255, -0.00080789323,
+  //...+1533 elementos
+];
+```
+
+Cada vector es una huella matemática del texto, que permite la búsqueda por similitud.
+
+## Paso 4: Indexación y Almacenamiento de Embeddings
+
+Para evitar regenerar embeddings múltiples veces, los almacené en embeddings.json.
+
+En producción, probablemente querrás una base de datos vectorial como:
+
+- Chroma
+- Qdrant
+- Pinecone
+- FAISS, Weaviate, Milvus, etc.
+
+Las bases de datos vectoriales manejan la indexación, escalabilidad y búsqueda rápida. Pero para mi prototipo, un JSON local funcionó bien.
+
+## Paso 5: Recuperación con Similitud del Coseno
+
+Cuando un usuario hace una pregunta:
+
+1. Generar un embedding para la consulta.
+2. Compararlo con todos los embeddings de los documentos usando **similitud del coseno**.
+3. Mantener solo los N fragmentos más similares.
+
+La similitud del coseno mide el ángulo entre dos vectores. Una coincidencia perfecta obtiene un puntaje de **1.0**.
+
+De esta manera, el sistema encuentra los pasajes del documento más cercanos a la consulta.
+
+## Paso 6: Aumento + Generación
+
+Ahora viene la magia. Tomamos los fragmentos principales y los inyectamos en el **prompt del sistema** para ChatGPT.
+
+Eso significa que el modelo responde como si esos fragmentos fueran parte de la conversación.
+
+El resultado: respuestas precisas y **basadas en la documentación**.
+
+## Paso 7: Registro de Consultas de Usuarios
+
+Este es el superpoder oculto.
+
+Cada pregunta realizada se almacena. Con el tiempo, construyes un conjunto de datos de:
+
+- Preguntas más frecuentes (ideal para FAQs)
+- Preguntas sin respuesta (documentación faltante o poco clara)
+- Solicitudes de funciones disfrazadas de preguntas (“¿Se integra con X?”)
+- Casos de uso emergentes que no habías previsto
+
+Esto convierte a tu asistente RAG en una **herramienta continua de investigación de usuarios**.
+
+## ¿Cuánto Cuesta?
+
+Una objeción común a RAG es el costo. En la práctica, es sorprendentemente barato:
+
+- Generar embeddings para ~200 documentos toma alrededor de **5 minutos** y cuesta **1–2 euros**.
+- La función de búsqueda en documentos es 100% gratuita.
+- Para las consultas, usamos gpt-4o-latest sin el modo de “pensamiento”. En Intlayer, vemos alrededor de **300 consultas de chat por mes**, y la factura de la API de OpenAI rara vez supera los **10 $**.
+
+Además de eso, puedes incluir el costo de alojamiento.
+
+## Detalles de Implementación
+
+Stack:
+
+- Monorepo: espacio de trabajo pnpm
+- Paquete de documentación: Node.js / TypeScript / API de OpenAI
+- Frontend: Next.js / React / Tailwind CSS
+- Backend: ruta API de Node.js / API de OpenAI
+
+El paquete `@smart-doc/docs` es un paquete TypeScript que maneja el procesamiento de la documentación. Cuando se agrega o modifica un archivo markdown, el paquete incluye un script `build` que reconstruye la lista de documentación en cada idioma, genera embeddings y los almacena en un archivo `embeddings.json`.
+
+Para el frontend, usamos una aplicación Next.js que proporciona:
+
+- Renderizado de Markdown a HTML
+- Una barra de búsqueda para encontrar documentación relevante
+- Una interfaz de chatbot para hacer preguntas sobre la documentación
+
+Para realizar una búsqueda en la documentación, la aplicación Next.js incluye una ruta API que llama a una función del paquete `@smart-doc/docs` para recuperar fragmentos de documentación que coincidan con la consulta. Usando estos fragmentos, podemos devolver una lista de páginas de documentación relevantes para la búsqueda del usuario.
+
+Para la funcionalidad del chatbot, seguimos el mismo proceso de búsqueda pero además inyectamos los fragmentos de documentación recuperados en el prompt enviado a ChatGPT.
+
+Aquí hay un ejemplo de un prompt enviado a ChatGPT:
+
+Prompt del sistema:
+
+```txt
+Eres un asistente útil que puede responder preguntas sobre la documentación de Intlayer.
+
+Fragmentos relacionados:
+
+-----
+docName: "getting-started"
+docChunk: "1/3"
+docUrl: "https://example.com/docs/es/getting-started"
+---
+
+# Cómo empezar
+
+...
+
+-----
+docName: "another-doc"
+docChunk: "1/5"
+docUrl: "https://example.com/docs/es/another-doc"
+---
+
+# Otro documento
+
+...
+```
+
+Consulta del usuario:
+
+```txt
+¿Cómo empezar?
+```
+
+Usamos SSE para transmitir la respuesta desde la ruta API.
+
+Como se mencionó, usamos gpt-4-turbo sin modo "pensando". Las respuestas son relevantes y la latencia es baja.
+Experimentamos con gpt-5, pero la latencia era demasiado alta (a veces hasta 15 segundos para una respuesta). Pero lo revisaremos en el futuro.
+
+👉 [Prueba la demo aquí](https://intlayer.org/doc/why) 👉 [Consulta la plantilla de código en GitHub](https://github.com/aymericzip/smart_doc_RAG)
+
+## Ir más allá
+
+Este proyecto es una implementación mínima. Pero puedes ampliarlo de muchas maneras:
+
+- Servidor MCP → la función de búsqueda en la documentación a un servidor MCP para conectar la documentación con cualquier asistente de IA
+
+- Bases de datos vectoriales → escalar a millones de fragmentos de documentación
+- LangChain / LlamaIndex → frameworks listos para usar para pipelines RAG
+- Paneles de análisis → visualizar consultas de usuarios y puntos problemáticos
+- Recuperación multisource → obtener no solo documentos, sino entradas de bases de datos, publicaciones de blogs, tickets, etc.
+- Mejora en el prompting → reordenamiento, filtrado y búsqueda híbrida (palabra clave + semántica)
+
+## Limitaciones que hemos encontrado
+
+- La segmentación y el solapamiento son empíricos. El equilibrio correcto (tamaño del fragmento, porcentaje de solapamiento, número de fragmentos recuperados) requiere iteración y pruebas.
+- Los embeddings no se regeneran automáticamente cuando los documentos cambian. Nuestro sistema reinicia los embeddings para un archivo solo si el número de fragmentos difiere de lo almacenado.
+- En este prototipo, los embeddings se almacenan en JSON. Esto funciona para demostraciones pero contamina Git. En producción, es mejor usar una base de datos o un almacén vectorial dedicado.
+
+## Por qué esto importa más allá de la documentación
+
+La parte interesante no es solo el chatbot. Es el **bucle de retroalimentación**.
+
+Con RAG, no solo respondes:
+
+- Aprendes qué confunde a los usuarios.
+- Descubres qué características esperan.
+- Adaptas tu estrategia de producto basándote en consultas reales.
+
+**Ejemplo:**
+
+Imagina lanzar una nueva función y ver instantáneamente:
+
+- El 50% de las preguntas son sobre el mismo paso de configuración poco claro
+- Los usuarios piden repetidamente una integración que aún no soportas
+- La gente busca términos que revelan un nuevo caso de uso
+
+Eso es **inteligencia de producto** directamente de tus usuarios.
+
+## Conclusión
+
+- En este prototipo, los embeddings se almacenan en JSON. Esto funciona para demostraciones pero contamina Git. En producción, es mejor usar una base de datos o un almacén vectorial dedicado.
+
+## Por qué esto importa más allá de la documentación
+
+La parte interesante no es solo el chatbot. Es el **ciclo de retroalimentación**.
+
+Con RAG, no solo respondes:
+
+- Aprendes qué confunde a los usuarios.
+- Descubres qué funciones esperan.
+- Adaptas tu estrategia de producto basándote en consultas reales.
+
+**Ejemplo:**
+
+Imagina lanzar una nueva función y ver instantáneamente:
+
+- El 50% de las preguntas son sobre el mismo paso de configuración poco claro
+- Los usuarios piden repetidamente una integración que aún no soportas
+- La gente busca términos que revelan un nuevo caso de uso
+
+Eso es **inteligencia de producto** directamente de tus usuarios.
+
+## Conclusión
+
+RAG es una de las formas más simples y poderosas de hacer que los LLMs sean prácticos. Al combinar **recuperación + generación**, puedes convertir documentos estáticos en un **asistente inteligente** y, al mismo tiempo, obtener un flujo continuo de información sobre el producto.
+
+Para mí, este proyecto mostró que RAG no es solo un truco técnico. Es una forma de transformar la documentación en:
+
+- un sistema de soporte interactivo
+- un canal de retroalimentación
+- una herramienta de estrategia de producto
+
+👉 [Prueba la demo aquí](https://intlayer.org/doc/why) 👉 [Consulta la plantilla de código en GitHub](https://github.com/aymericzip/smart_doc_RAG)
+
+Y si también estás experimentando con RAG, me encantaría saber cómo lo estás usando.

package/blog/fr/rag_powered_documentation_assistant.md

@@ -0,0 +1,308 @@
+---
+createdAt: 2025-09-10
+updatedAt: 2025-09-10
+title: Création d’un assistant de documentation propulsé par RAG (Segmentation, Embeddings et Recherche)
+description: Création d’un assistant de documentation propulsé par RAG (Segmentation, Embeddings et Recherche)
+keywords:
+  - RAG
+  - Documentation
+  - Assistant
+  - Segmentation
+  - Embeddings
+  - Recherche
+slugs:
+  - blog
+  - rag-powered-documentation-assistant
+---
+
+# Création d’un assistant de documentation propulsé par RAG (Segmentation, Embeddings et Recherche)
+
+## Ce que vous obtenez
+
+J’ai créé un assistant de documentation propulsé par RAG et l’ai emballé dans un boilerplate que vous pouvez utiliser immédiatement.
+
+- Livré avec une application prête à l’emploi (Next.js + API OpenAI)
+- Comprend une pipeline RAG fonctionnelle (segmentation, embeddings, similarité cosinus)
+- Fournit une interface complète de chatbot construite en React
+- Tous les composants UI sont entièrement modifiables avec Tailwind CSS
+- Enregistre chaque requête utilisateur pour aider à identifier les documents manquants, les points de douleur des utilisateurs et les opportunités produit
+
+👉 [Démo en direct](https://intlayer.org/doc/why) 👉 [Boilerplate de code](https://github.com/aymericzip/smart_doc_RAG)
+
+## Introduction
+
+Si vous vous êtes déjà perdu dans une documentation, à faire défiler sans fin pour trouver une réponse, vous savez à quel point cela peut être pénible. Les docs sont utiles, mais elles sont statiques et leur recherche est souvent maladroite.
+
+C’est là qu’intervient **RAG (Retrieval-Augmented Generation)**. Au lieu de forcer les utilisateurs à fouiller dans le texte, nous pouvons combiner la **récupération** (trouver les bonnes parties de la doc) avec la **génération** (laisser un LLM l’expliquer naturellement).
+
+Dans cet article, je vais vous expliquer comment j’ai construit un chatbot de documentation alimenté par RAG et comment il ne se contente pas d’aider les utilisateurs à trouver des réponses plus rapidement, mais offre également aux équipes produit une nouvelle manière de comprendre les points de douleur des utilisateurs.
+
+## Pourquoi utiliser RAG pour la documentation ?
+
+RAG est devenu une approche populaire pour une raison : c’est l’une des façons les plus pratiques de rendre les grands modèles de langage réellement utiles.
+
+Pour la documentation, les avantages sont clairs :
+
+- Réponses instantanées : les utilisateurs posent des questions en langage naturel et obtiennent des réponses pertinentes.
+- Meilleur contexte : le modèle ne voit que les sections de documentation les plus pertinentes, réduisant ainsi les hallucinations.
+- Recherche qui semble humaine : un mélange d’Algolia + FAQ + chatbot, tout en un.
+- Boucle de rétroaction : en stockant les requêtes, vous découvrez ce avec quoi les utilisateurs ont vraiment du mal.
+
+Ce dernier point est crucial. Un système RAG ne se contente pas de répondre aux questions, il vous indique ce que les gens demandent. Cela signifie :
+
+- Vous découvrez des informations manquantes dans votre documentation.
+- Vous voyez apparaître des demandes de fonctionnalités.
+- Vous repérez des tendances qui peuvent même orienter la stratégie produit.
+
+Ainsi, RAG n’est pas seulement un outil de support. C’est aussi un **moteur de découverte produit**.
+
+## Comment fonctionne le pipeline RAG
+
+![RAG Pipeline](https://github.com/aymericzip/intlayer/blob/main/docs/assets/rag_flow.svg)
+
+À un niveau élevé, voici la recette que j’ai utilisée :
+
+1.  **Découpage de la documentation** De gros fichiers Markdown sont divisés en morceaux. Le découpage permet de fournir comme contexte uniquement les parties pertinentes de la documentation.
+2.  **Génération des embeddings** Chaque morceau est transformé en vecteur en utilisant l’API d’embeddings d’OpenAI (text-embedding-3-large) ou une base de données vectorielle (Chroma, Qdrant, Pinecone).
+3.  **Indexation et stockage** Les embeddings sont stockés dans un simple fichier JSON (pour ma démo), mais en production, vous utiliseriez probablement une base de données vectorielle.
+4.  **Récupération (R dans RAG)** Une requête utilisateur est transformée en embedding, la similarité cosinus est calculée, et les chunks les plus pertinents sont récupérés.
+5.  **Augmentation + Génération (AG dans RAG)** Ces chunks sont injectés dans le prompt pour ChatGPT, afin que le modèle réponde avec le contexte réel de la documentation.
+6.  **Enregistrement des requêtes pour feedback** Chaque requête utilisateur est stockée. C’est une mine d’or pour comprendre les points de douleur, les documents manquants ou les nouvelles opportunités.
+
+## Étape 1 : Lecture des Docs
+
+La première étape était simple : j’avais besoin d’un moyen pour scanner un dossier docs/ à la recherche de tous les fichiers .md. En utilisant Node.js et glob, j’ai récupéré le contenu de chaque fichier Markdown en mémoire.
+
+Cela maintient la flexibilité du pipeline : au lieu de Markdown, vous pourriez récupérer les documents depuis une base de données, un CMS, ou même une API.
+
+## Étape 2 : Découpage de la documentation
+
+Pourquoi découper ? Parce que les modèles de langage ont des **limites de contexte**. Leur fournir un livre entier de documentation ne fonctionnera pas.
+
+L’idée est donc de diviser le texte en morceaux gérables (par exemple 500 tokens chacun) avec un chevauchement (par exemple 100 tokens). Le chevauchement assure la continuité pour ne pas perdre le sens aux frontières des morceaux.
+
+**Exemple :**
+
+- Morceau 1 → « …la vieille bibliothèque que beaucoup avaient oubliée. Ses étagères imposantes étaient remplies de livres… »
+- Morceau 2 → « …les étagères étaient remplies de livres de tous genres imaginables, chacun murmurant des histoires… »
+
+Le chevauchement garantit que les deux morceaux contiennent un contexte partagé, ce qui rend la récupération cohérente.
+
+Ce compromis (taille des chunks vs chevauchement) est essentiel pour l'efficacité du RAG :
+
+- Trop petit → vous obtenez du bruit.
+- Trop grand → vous explosez la taille du contexte.
+
+## Étape 3 : Génération des embeddings
+
+Une fois les documents découpés en chunks, nous générons des **embeddings** — des vecteurs de haute dimension représentant chaque chunk.
+
+J'ai utilisé le modèle text-embedding-3-large d'OpenAI, mais vous pouvez utiliser n'importe quel modèle d'embedding moderne.
+
+**Exemple d'embedding :**
+
+```js
+[
+  -0.0002630692, -0.029749284, 0.010225477, -0.009224428, -0.0065269712,
+  -0.002665544, 0.003214777, 0.04235309, -0.033162255, -0.00080789323,
+  //...+1533 éléments
+];
+```
+
+Chaque vecteur est une empreinte mathématique du texte, permettant la recherche de similarité.
+
+## Étape 4 : Indexation et stockage des embeddings
+
+Pour éviter de régénérer les embeddings plusieurs fois, je les ai stockés dans embeddings.json.
+
+En production, vous voudriez probablement une base de données vectorielle telle que :
+
+- Chroma
+- Qdrant
+- Pinecone
+- FAISS, Weaviate, Milvus, etc.
+
+Les bases de données vectorielles gèrent l’indexation, la scalabilité et la recherche rapide. Mais pour mon prototype, un JSON local a très bien fonctionné.
+
+## Étape 5 : Recherche avec similarité cosinus
+
+Lorsqu’un utilisateur pose une question :
+
+1. Générer un embedding pour la requête.
+2. Le comparer à tous les embeddings des documents en utilisant la **similarité cosinus**.
+3. Ne garder que les N chunks les plus similaires.
+
+La similarité cosinus mesure l’angle entre deux vecteurs. Une correspondance parfaite obtient un score de **1.0**.
+
+Ainsi, le système trouve les passages de documents les plus proches de la requête.
+
+## Étape 6 : Augmentation + Génération
+
+Voici la magie. Nous prenons les meilleurs chunks et les injectons dans le **prompt système** pour ChatGPT.
+
+Cela signifie que le modèle répond comme si ces extraits faisaient partie de la conversation.
+
+Le résultat : des réponses précises, **fondées sur la documentation**.
+
+## Étape 7 : Enregistrement des requêtes utilisateur
+
+C’est la superpuissance cachée.
+
+Chaque question posée est stockée. Au fil du temps, vous constituez un ensemble de données comprenant :
+
+- Les questions les plus fréquentes (idéal pour les FAQ)
+- Les questions sans réponse (documentation manquante ou peu claire)
+- Les demandes de fonctionnalités déguisées en questions (« Est-ce que cela s’intègre avec X ? »)
+- Les cas d’utilisation émergents auxquels vous n’aviez pas pensé
+
+Cela transforme votre assistant RAG en un **outil continu de recherche utilisateur**.
+
+## Quel est le coût ?
+
+Une objection courante au RAG est le coût. En pratique, c’est étonnamment peu cher :
+
+- Générer des embeddings pour environ 200 documents prend environ **5 minutes** et coûte **1 à 2 euros**.
+- La fonctionnalité de recherche dans la documentation est 100 % gratuite.
+- Pour les requêtes, nous utilisons gpt-4o-latest sans le mode « réflexion ». Sur Intlayer, nous observons environ **300 requêtes de chat par mois**, et la facture de l’API OpenAI dépasse rarement **10 $**.
+
+En plus de cela, vous pouvez inclure le coût d’hébergement.
+
+## Détails de l’implémentation
+
+Stack :
+
+- Monorepo : espace de travail pnpm
+- Package doc : Node.js / TypeScript / API OpenAI
+- Frontend : Next.js / React / Tailwind CSS
+- Backend : route API Node.js / API OpenAI
+
+Le package `@smart-doc/docs` est un package TypeScript qui gère le traitement de la documentation. Lorsqu’un fichier markdown est ajouté ou modifié, le package inclut un script `build` qui reconstruit la liste de documentation dans chaque langue, génère des embeddings, et les stocke dans un fichier `embeddings.json`.
+
+Pour le frontend, nous utilisons une application Next.js qui fournit :
+
+- Rendu Markdown vers HTML
+- Une barre de recherche pour trouver la documentation pertinente
+- Une interface de chatbot pour poser des questions sur la documentation
+
+Pour effectuer une recherche dans la documentation, l’application Next.js inclut une route API qui appelle une fonction du package `@smart-doc/docs` pour récupérer les segments de documentation correspondant à la requête. En utilisant ces segments, nous pouvons retourner une liste de pages de documentation pertinentes pour la recherche de l’utilisateur.
+
+Pour la fonctionnalité de chatbot, nous suivons le même processus de recherche mais injectons en plus les segments de documentation récupérés dans le prompt envoyé à ChatGPT.
+
+Voici un exemple de prompt envoyé à ChatGPT :
+
+Prompt système :
+
+```txt
+Vous êtes un assistant utile capable de répondre aux questions concernant la documentation Intlayer.
+
+Segments liés :
+
+-----
+docName: "getting-started"
+docChunk: "1/3"
+docUrl: "https://example.com/docs/fr/getting-started"
+---
+
+# Comment démarrer
+
+...
+
+-----
+docName: "another-doc"
+docChunk: "1/5"
+docUrl: "https://example.com/docs/fr/another-doc"
+---
+
+# Un autre document
+
+...
+```
+
+Requête utilisateur :
+
+```txt
+Comment démarrer ?
+```
+
+Nous utilisons SSE pour diffuser la réponse depuis la route API.
+
+Comme mentionné, nous utilisons gpt-4-turbo sans mode "réflexion". Les réponses sont pertinentes et la latence est faible.
+Nous avons expérimenté avec gpt-5, mais la latence était trop élevée (parfois jusqu'à 15 secondes pour une réponse). Nous y reviendrons à l'avenir.
+
+👉 [Essayez la démo ici](https://intlayer.org/doc/why) 👉 [Consultez le modèle de code sur GitHub](https://github.com/aymericzip/smart_doc_RAG)
+
+## Aller plus loin
+
+Ce projet est une implémentation minimale. Mais vous pouvez l'étendre de nombreuses façons :
+
+- Serveur MCP → la fonction de recherche dans la documentation vers un serveur MCP pour connecter la documentation à n'importe quel assistant IA
+
+- Bases de données vectorielles → évoluer jusqu'à des millions de fragments de documentation
+- LangChain / LlamaIndex → frameworks prêts à l'emploi pour les pipelines RAG
+- Tableaux de bord analytiques → visualiser les requêtes des utilisateurs et les points de douleur
+- Recherche multi-source → extraire non seulement des documents, mais aussi des entrées de base de données, articles de blog, tickets, etc.
+- Amélioration des prompts → reranking, filtrage, et recherche hybride (mot-clé + sémantique)
+
+## Limitations rencontrées
+
+- Le découpage en fragments et le chevauchement sont empiriques. Le bon équilibre (taille des fragments, pourcentage de chevauchement, nombre de fragments récupérés) nécessite des itérations et des tests.
+- Les embeddings ne sont pas régénérés automatiquement lorsque les documents changent. Notre système réinitialise les embeddings d'un fichier uniquement si le nombre de fragments diffère de ce qui est stocké.
+- Dans ce prototype, les embeddings sont stockés en JSON. Cela fonctionne pour des démonstrations mais pollue Git. En production, une base de données ou un magasin vectoriel dédié est préférable.
+
+## Pourquoi c’est important au-delà de la documentation
+
+La partie intéressante n’est pas seulement le chatbot. C’est la **boucle de rétroaction**.
+
+Avec RAG, vous ne vous contentez pas de répondre :
+
+- Vous apprenez ce qui embrouille les utilisateurs.
+- Vous découvrez quelles fonctionnalités ils attendent.
+- Vous adaptez votre stratégie produit en fonction des requêtes réelles.
+
+**Exemple :**
+
+Imaginez lancer une nouvelle fonctionnalité et voir instantanément :
+
+- 50 % des questions portent sur la même étape de configuration peu claire
+- Les utilisateurs demandent à plusieurs reprises une intégration que vous ne supportez pas encore
+- Les gens recherchent des termes qui révèlent un nouveau cas d’usage
+
+C’est de **l’intelligence produit** directement issue de vos utilisateurs.
+
+## Conclusion
+
+- Dans ce prototype, les embeddings sont stockés en JSON. Cela fonctionne pour des démonstrations mais pollue Git. En production, une base de données ou un magasin vectoriel dédié est préférable.
+
+## Pourquoi c’est important au-delà de la documentation
+
+L’aspect intéressant ne se limite pas au chatbot. C’est la **boucle de rétroaction**.
+
+Avec RAG, vous ne faites pas que répondre :
+
+- Vous apprenez ce qui embrouille les utilisateurs.
+- Vous découvrez quelles fonctionnalités ils attendent.
+- Vous adaptez votre stratégie produit en fonction des requêtes réelles.
+
+**Exemple :**
+
+Imaginez lancer une nouvelle fonctionnalité et voir instantanément :
+
+- 50 % des questions portent sur la même étape de configuration peu claire
+- Les utilisateurs demandent à plusieurs reprises une intégration que vous ne supportez pas encore
+- Les gens recherchent des termes qui révèlent un nouveau cas d’usage
+
+C’est de **l’intelligence produit** directement issue de vos utilisateurs.
+
+## Conclusion
+
+RAG est l’une des manières les plus simples et puissantes de rendre les LLM pratiques. En combinant **récupération + génération**, vous pouvez transformer des docs statiques en un **assistant intelligent** et, en même temps, obtenir un flux continu d’informations produit.
+
+Pour moi, ce projet a montré que RAG n’est pas qu’un simple tour technique. C’est une façon de transformer la documentation en :
+
+- un système de support interactif
+- un canal de retour d’expérience
+- un outil de stratégie produit
+
+👉 [Essayez la démo ici](https://intlayer.org/doc/why) 👉 [Consultez le modèle de code sur GitHub](https://github.com/aymericzip/smart_doc_RAG)
+
+Et si vous expérimentez aussi avec RAG, j’aimerais beaucoup savoir comment vous l’utilisez.