@intlayer/docs 5.8.1 → 6.0.0-canary.0

package/blog/hi/rag_powered_documentation_assistant.md

@@ -0,0 +1,284 @@
+---
+createdAt: 2025-09-10
+updatedAt: 2025-09-10
+title: RAG-संचालित दस्तावेज़ सहायक का निर्माण (चंकिंग, एम्बेडिंग्स, और खोज)
+description: RAG-संचालित दस्तावेज़ सहायक का निर्माण (चंकिंग, एम्बेडिंग्स, और खोज)
+keywords:
+  - RAG
+  - दस्तावेज़
+  - सहायक
+  - चंकिंग
+  - एम्बेडिंग्स
+  - खोज
+slugs:
+  - blog
+  - rag-powered-documentation-assistant
+---
+
+# RAG-संचालित दस्तावेज़ सहायक का निर्माण (चंकिंग, एम्बेडिंग्स, और खोज)
+
+## आपको क्या मिलेगा
+
+मैंने एक RAG-संचालित दस्तावेज़ सहायक बनाया है और इसे एक बॉयलरप्लेट में पैकेज किया है जिसे आप तुरंत उपयोग कर सकते हैं।
+
+- एक तैयार-से-उपयोग एप्लिकेशन के साथ आता है (Next.js + OpenAI API)
+- एक कार्यशील RAG पाइपलाइन शामिल है (चंकिंग, एम्बेडिंग्स, कोसाइन समानता)
+- React में निर्मित एक पूर्ण चैटबॉट UI प्रदान करता है
+- सभी UI घटक Tailwind CSS के साथ पूरी तरह से संपादन योग्य हैं
+- हर उपयोगकर्ता क्वेरी को लॉग करता है ताकि गायब दस्तावेज़, उपयोगकर्ता की समस्याओं, और उत्पाद के अवसरों की पहचान की जा सके
+
+👉 [लाइव डेमो](https://intlayer.org/doc/why) 👉 [कोड बॉयलरप्लेट](https://github.com/aymericzip/smart_doc_RAG)
+
+## परिचय
+
+यदि आप कभी दस्तावेज़ में खो गए हैं, एक उत्तर के लिए अंतहीन स्क्रॉलिंग करते हुए, तो आप जानते हैं कि यह कितना दर्दनाक हो सकता है। दस्तावेज़ उपयोगी होते हैं, लेकिन वे स्थिर होते हैं और उनमें खोज करना अक्सर जटिल लगता है।
+
+यहीं पर **RAG (रिट्रीवल-ऑगमेंटेड जनरेशन)** आता है। उपयोगकर्ताओं को टेक्स्ट के माध्यम से खुदाई करने के लिए मजबूर करने के बजाय, हम **रिट्रीवल** (दस्तावेज़ के सही हिस्सों को खोजने) को **जनरेशन** (एक LLM को इसे स्वाभाविक रूप से समझाने देना) के साथ जोड़ सकते हैं।
+
+इस पोस्ट में, मैं आपको बताऊंगा कि मैंने कैसे एक RAG-संचालित दस्तावेज़ चैटबोट बनाया और यह न केवल उपयोगकर्ताओं को तेज़ी से उत्तर खोजने में मदद करता है, बल्कि उत्पाद टीमों को उपयोगकर्ता की समस्याओं को समझने का एक नया तरीका भी देता है।
+
+## दस्तावेज़ के लिए RAG क्यों उपयोग करें?
+
+RAG एक लोकप्रिय दृष्टिकोण बन गया है और इसके पीछे एक कारण है: यह बड़े भाषा मॉडल को वास्तव में उपयोगी बनाने के सबसे व्यावहारिक तरीकों में से एक है।
+
+दस्तावेज़ के लिए, इसके लाभ स्पष्ट हैं:
+
+- त्वरित उत्तर: उपयोगकर्ता प्राकृतिक भाषा में पूछते हैं, और प्रासंगिक उत्तर प्राप्त करते हैं।
+- बेहतर संदर्भ: मॉडल केवल सबसे प्रासंगिक दस्तावेज़ अनुभागों को देखता है, जिससे भ्रम की संभावना कम होती है।
+- खोज जो मानव जैसी लगती है: यह अधिकतर Algolia + FAQ + चैटबोट का संयोजन है।
+- प्रतिक्रिया चक्र: क्वेरी संग्रहित करके, आप पता लगाते हैं कि उपयोगकर्ता वास्तव में किन समस्याओं का सामना कर रहे हैं।
+
+वह आखिरी बिंदु बहुत महत्वपूर्ण है। एक RAG सिस्टम केवल सवालों के जवाब नहीं देता, यह आपको बताता है कि लोग क्या पूछ रहे हैं। इसका मतलब है:
+
+- आप अपनी दस्तावेज़ में गायब जानकारी का पता लगाते हैं।
+- आप फीचर अनुरोधों को उभरते हुए देखते हैं।
+- आप ऐसे पैटर्न पहचानते हैं जो उत्पाद रणनीति को भी मार्गदर्शन कर सकते हैं।
+
+तो, RAG केवल एक सहायता उपकरण नहीं है। यह एक **उत्पाद खोज इंजन** भी है।
+
+## RAG पाइपलाइन कैसे काम करती है
+
+![RAG Pipeline](https://github.com/aymericzip/intlayer/blob/main/docs/assets/rag_flow.svg)
+
+उच्च स्तर पर, यहाँ वह विधि है जिसका मैंने उपयोग किया:
+
+1.  **दस्तावेज़ को टुकड़ों में बांटना** बड़े Markdown फ़ाइलों को टुकड़ों में विभाजित किया जाता है। टुकड़ों में बांटने से केवल प्रासंगिक दस्तावेज़ भागों को संदर्भ के रूप में प्रदान करना संभव होता है।
+2.  **एम्बेडिंग्स बनाना** प्रत्येक टुकड़े को OpenAI के एम्बेडिंग API (text-embedding-3-large) या एक वेक्टर डेटाबेस (Chroma, Qdrant, Pinecone) का उपयोग करके वेक्टर में बदला जाता है।
+3.  **इंडेक्सिंग और संग्रहण** एम्बेडिंग्स को एक सरल JSON फ़ाइल में संग्रहित किया जाता है (मेरे डेमो के लिए), लेकिन उत्पादन में, आप संभवतः एक वेक्टर DB का उपयोग करेंगे।
+4.  **रिकवरी (RAG में R)** एक उपयोगकर्ता क्वेरी को एम्बेड किया जाता है, कोसाइन समानता की गणना की जाती है, और शीर्ष मेल खाने वाले टुकड़े पुनः प्राप्त किए जाते हैं।
+5.  **ऑगमेंटेशन + जनरेशन (RAG में AG)** उन टुकड़ों को ChatGPT के प्रॉम्प्ट में डाला जाता है, ताकि मॉडल वास्तविक दस्तावेज़ संदर्भ के साथ उत्तर दे सके।
+6.  **प्रतिक्रिया के लिए क्वेरी लॉगिंग** हर उपयोगकर्ता क्वेरी को संग्रहित किया जाता है। यह दर्द बिंदुओं, गायब दस्तावेज़ों, या नए अवसरों को समझने के लिए सोना है।
+
+## चरण 1: दस्तावेज़ पढ़ना
+
+पहला चरण सरल था: मुझे docs/ फ़ोल्डर में सभी .md फ़ाइलों को स्कैन करने का एक तरीका चाहिए था। Node.js और glob का उपयोग करके, मैंने प्रत्येक Markdown फ़ाइल की सामग्री को मेमोरी में लाया।
+
+यह पाइपलाइन को लचीला बनाए रखता है: Markdown के बजाय, आप दस्तावेज़ों को डेटाबेस, CMS, या यहां तक कि API से भी प्राप्त कर सकते हैं।
+
+## चरण 2: दस्तावेज़ों को टुकड़ों में विभाजित करना
+
+टुकड़ों में क्यों बांटना? क्योंकि भाषा मॉडल के पास **संदर्भ सीमाएं** होती हैं। उन्हें पूरे दस्तावेज़ की किताब खिलाना काम नहीं करेगा।
+
+इसलिए विचार यह है कि टेक्स्ट को प्रबंधनीय टुकड़ों (जैसे प्रत्येक 500 टोकन) में विभाजित किया जाए, जिसमें ओवरलैप (जैसे 100 टोकन) हो। ओवरलैप निरंतरता सुनिश्चित करता है ताकि आप टुकड़ों की सीमाओं पर अर्थ न खोएं।
+
+**उदाहरण:**
+
+- टुकड़ा 1 → “…पुरानी लाइब्रेरी जिसे कई लोग भूल चुके थे। इसकी ऊंची शेल्फ़ किताबों से भरी हुई थीं…”
+- टुकड़ा 2 → “…शेल्फ़ हर कल्पनीय शैली की किताबों से भरे हुए थे, प्रत्येक अपनी कहानियां फुसफुसा रहा था…”
+
+ओवरलैप सुनिश्चित करता है कि दोनों टुकड़ों में साझा संदर्भ हो, जिससे पुनः प्राप्ति सुसंगत बनी रहे।
+
+यह समझौता (टुकड़े का आकार बनाम ओवरलैप) RAG की दक्षता के लिए महत्वपूर्ण है:
+
+- बहुत छोटा → आपको शोर मिलेगा।
+- बहुत बड़ा → आप संदर्भ आकार को बढ़ा देते हैं।
+
+## चरण 3: एम्बेडिंग्स जनरेट करना
+
+एक बार जब दस्तावेज़ों को टुकड़ों में बांट दिया जाता है, तो हम **एम्बेडिंग्स** बनाते हैं — उच्च-आयामी वेक्टर जो प्रत्येक टुकड़े का प्रतिनिधित्व करते हैं।
+
+मैंने OpenAI के text-embedding-3-large मॉडल का उपयोग किया, लेकिन आप कोई भी आधुनिक एम्बेडिंग मॉडल उपयोग कर सकते हैं।
+
+**उदाहरण एम्बेडिंग:**
+
+```js
+[
+  -0.0002630692, -0.029749284, 0.010225477, -0.009224428, -0.0065269712,
+  -0.002665544, 0.003214777, 0.04235309, -0.033162255, -0.00080789323,
+  //...+1533 elements
+];
+```
+
+प्रत्येक वेक्टर टेक्स्ट की एक गणितीय फिंगरप्रिंट है, जो समानता खोज को सक्षम बनाता है।
+
+## चरण 4: एम्बेडिंग्स का इंडेक्सिंग और संग्रहण
+
+बार-बार एम्बेडिंग्स को पुनः उत्पन्न करने से बचने के लिए, मैंने उन्हें embeddings.json में संग्रहित किया।
+
+उत्पादन में, आप संभवतः निम्नलिखित जैसे वेक्टर डेटाबेस चाहते होंगे:
+
+- Chroma
+- Qdrant
+- Pinecone
+- FAISS, Weaviate, Milvus, आदि।
+
+वेक्टर डेटाबेस इंडेक्सिंग, स्केलेबिलिटी, और तेज़ खोज को संभालते हैं। लेकिन मेरे प्रोटोटाइप के लिए, एक स्थानीय JSON ठीक काम करता था।
+
+## चरण 5: कोसाइन सिमिलैरिटी के साथ पुनःप्राप्ति
+
+जब कोई उपयोगकर्ता प्रश्न पूछता है:
+
+1. क्वेरी के लिए एक एम्बेडिंग जनरेट करें।
+2. इसे सभी दस्तावेज़ एम्बेडिंग्स के साथ **कोसाइन सिमिलैरिटी** का उपयोग करके तुलना करें।
+3. केवल शीर्ष N सबसे समान टुकड़ों को रखें।
+
+कोसाइन सिमिलैरिटी दो वेक्टरों के बीच कोण को मापती है। एक पूर्ण मेल का स्कोर **1.0** होता है।
+
+इस तरह, सिस्टम क्वेरी के सबसे निकट दस्तावेज़ अंश खोजता है।
+
+## चरण 6: संवर्धन + जनरेशन
+
+अब जादू आता है। हम शीर्ष टुकड़ों को लेते हैं और उन्हें ChatGPT के **सिस्टम प्रॉम्प्ट** में इंजेक्ट करते हैं।
+
+इसका मतलब है कि मॉडल ऐसे जवाब देता है जैसे वे चंक्स बातचीत का हिस्सा हों।
+
+परिणाम: सटीक, **दस्तावेज़-आधारित उत्तर**।
+
+## चरण 7: उपयोगकर्ता प्रश्नों का लॉगिंग
+
+यह छुपी हुई सुपरपावर है।
+
+पूछे गए हर प्रश्न को संग्रहीत किया जाता है। समय के साथ, आप एक डेटासेट बनाते हैं जिसमें शामिल हैं:
+
+- सबसे अधिक पूछे जाने वाले प्रश्न (FAQs के लिए बेहतरीन)
+- अनुत्तरित प्रश्न (दस्तावेज़ गायब हैं या अस्पष्ट हैं)
+- प्रश्न के रूप में छिपे फीचर अनुरोध (“क्या यह X के साथ एकीकृत होता है?”)
+- उभरते हुए उपयोग के मामले जिनकी आपने योजना नहीं बनाई थी
+
+यह आपके RAG सहायक को एक **लगातार उपयोगकर्ता अनुसंधान उपकरण** में बदल देता है।
+
+## इसकी लागत क्या है?
+
+RAG के लिए एक सामान्य आपत्ति लागत है। व्यवहार में, यह आश्चर्यजनक रूप से सस्ता है:
+
+- लगभग 200 दस्तावेज़ों के लिए एम्बेडिंग जनरेट करने में लगभग **5 मिनट** लगते हैं और इसकी लागत **1–2 यूरो** होती है।
+- दस्तावेज़ खोजने की सुविधा 100% मुफ्त है।
+- क्वेरीज़ के लिए, हम "थिंकिंग" मोड के बिना gpt-4o-latest का उपयोग करते हैं। Intlayer पर, हम प्रति माह लगभग **300 चैट क्वेरीज़** देखते हैं, और OpenAI API बिल शायद ही कभी **$10** से अधिक होता है।
+
+इसके ऊपर, आप होस्टिंग लागत भी शामिल कर सकते हैं।
+
+## कार्यान्वयन विवरण
+
+स्टैक:
+
+- मोनोरेपो: pnpm वर्कस्पेस
+- डॉक पैकेज: Node.js / TypeScript / OpenAI API
+- फ्रंटेंड: Next.js / React / Tailwind CSS
+- बैकेंड: Node.js API रूट / OpenAI API
+
+`@smart-doc/docs` पैकेज एक TypeScript पैकेज है जो दस्तावेज़ प्रसंस्करण को संभालता है। जब कोई मार्कडाउन फ़ाइल जोड़ी या संशोधित की जाती है, तो पैकेज में एक `build` स्क्रिप्ट शामिल होती है जो प्रत्येक भाषा में दस्तावेज़ सूची को पुनर्निर्मित करता है, एम्बेडिंग्स उत्पन्न करता है, और उन्हें `embeddings.json` फ़ाइल में संग्रहीत करता है।
+
+फ्रंटेंड के लिए, हम एक Next.js एप्लिकेशन का उपयोग करते हैं जो प्रदान करता है:
+
+- मार्कडाउन को HTML में रेंडर करना
+- प्रासंगिक दस्तावेज़ खोजने के लिए एक खोज बार
+- दस्तावेज़ों के बारे में प्रश्न पूछने के लिए एक चैटबॉट इंटरफ़ेस
+
+दस्तावेज़ खोज करने के लिए, Next.js एप्लिकेशन में एक API रूट शामिल है जो `@smart-doc/docs` पैकेज में एक फ़ंक्शन को कॉल करता है ताकि क्वेरी से मेल खाने वाले डॉक चंक्स प्राप्त किए जा सकें। इन चंक्स का उपयोग करके, हम उपयोगकर्ता की खोज से संबंधित दस्तावेज़ पृष्ठों की एक सूची वापस कर सकते हैं।
+
+चैटबॉट कार्यक्षमता के लिए, हम समान खोज प्रक्रिया का पालन करते हैं लेकिन अतिरिक्त रूप से प्राप्त डॉक चंक्स को ChatGPT को भेजे गए प्रॉम्प्ट में इंजेक्ट करते हैं।
+
+यहाँ ChatGPT को भेजे गए प्रॉम्प्ट का एक उदाहरण है:
+
+सिस्टम प्रॉम्प्ट :
+
+```txt
+आप एक सहायक सहायक हैं जो Intlayer दस्तावेज़ के बारे में प्रश्नों का उत्तर दे सकता है।
+
+संबंधित चंक्स :
+
+-----
+docName: "getting-started"
+docChunk: "1/3"
+docUrl: "https://example.com/docs/hi/getting-started"
+---
+
+# कैसे शुरू करें
+
+...
+
+-----
+docName: "another-doc"
+docChunk: "1/5"
+docUrl: "https://example.com/docs/hi/another-doc"
+---
+
+# एक और दस्तावेज़
+
+...
+```
+
+उपयोगकर्ता क्वेरी :
+
+```txt
+कैसे शुरू करें?
+```
+
+हम API रूट से प्रतिक्रिया को स्ट्रीम करने के लिए SSE का उपयोग करते हैं।
+
+जैसा कि उल्लेख किया गया है, हम "थिंकिंग" मोड के बिना gpt-4-turbo का उपयोग करते हैं। प्रतिक्रियाएँ प्रासंगिक होती हैं, और विलंबता कम होती है।
+हमने gpt-5 के साथ प्रयोग किया, लेकिन विलंबता बहुत अधिक थी (कभी-कभी उत्तर के लिए 15 सेकंड तक)। लेकिन हम भविष्य में इसे फिर से देखेंगे।
+
+👉 [यहाँ डेमो आज़माएँ](https://intlayer.org/doc/why) 👉 [GitHub पर कोड टेम्पलेट देखें](https://github.com/aymericzip/smart_doc_RAG)
+
+## आगे बढ़ना
+
+यह परियोजना एक न्यूनतम कार्यान्वयन है। लेकिन आप इसे कई तरीकों से बढ़ा सकते हैं:
+
+- MCP सर्वर → डॉक्यूमेंटेशन को किसी भी AI असिस्टेंट से कनेक्ट करने के लिए डॉक रिसर्च फ़ंक्शन को MCP सर्वर में बदलना
+
+- वेक्टर DBs → लाखों डॉक चंक्स तक स्केल करना
+- LangChain / LlamaIndex → RAG पाइपलाइनों के लिए रेडी-मेड फ्रेमवर्क
+- एनालिटिक्स डैशबोर्ड → उपयोगकर्ता क्वेरी और समस्याओं को विज़ुअलाइज़ करना
+- मल्टी-सोर्स रिट्रीवल → केवल डॉक नहीं, बल्कि डेटाबेस एंट्री, ब्लॉग पोस्ट, टिकट आदि भी खींचना
+- बेहतर प्रॉम्प्टिंग → रीरैंकिंग, फ़िल्टरिंग, और हाइब्रिड सर्च (कीवर्ड + सेमांटिक)
+
+## सीमाएँ जिनका सामना करना पड़ा
+
+- चंकिन्ग और ओवरलैप अनुभवजन्य हैं। सही संतुलन (चंक साइज, ओवरलैप प्रतिशत, प्राप्त किए गए चंक्स की संख्या) के लिए पुनरावृत्ति और परीक्षण आवश्यक है।
+- जब डॉक बदलते हैं तो एम्बेडिंग्स स्वचालित रूप से पुनः उत्पन्न नहीं होती हैं। हमारा सिस्टम केवल तभी फाइल के लिए एम्बेडिंग्स रीसेट करता है जब चंक्स की संख्या संग्रहीत संख्या से भिन्न होती है।
+- इस प्रोटोटाइप में, एम्बेडिंग्स JSON में संग्रहीत की जाती हैं। यह डेमो के लिए काम करता है लेकिन Git को प्रदूषित करता है। उत्पादन में, एक डेटाबेस या समर्पित वेक्टर स्टोर बेहतर होता है।
+
+## यह दस्तावेज़ों से परे क्यों महत्वपूर्ण है
+
+दिलचस्प हिस्सा केवल चैटबॉट नहीं है। यह **फीडबैक लूप** है।
+
+RAG के साथ, आप केवल उत्तर नहीं देते:
+
+- आप सीखते हैं कि उपयोगकर्ताओं को क्या भ्रमित करता है।
+- आप पता लगाते हैं कि वे कौन-से फीचर्स की उम्मीद करते हैं।
+- आप वास्तविक प्रश्नों के आधार पर अपनी उत्पाद रणनीति को अनुकूलित करते हैं।
+
+**उदाहरण:**
+
+कल्पना करें कि आप एक नया फीचर लॉन्च करते हैं और तुरंत देखते हैं:
+
+- 50% प्रश्न एक ही अस्पष्ट सेटअप चरण के बारे में हैं
+- उपयोगकर्ता बार-बार एक ऐसे इंटीग्रेशन के लिए पूछते हैं जिसे आप अभी तक सपोर्ट नहीं करते
+- लोग ऐसे शब्द खोजते हैं जो एक नए उपयोग मामले को प्रकट करते हैं
+
+यह है आपके उपयोगकर्ताओं से सीधे **उत्पाद बुद्धिमत्ता**।
+
+## निष्कर्ष
+
+RAG LLMs को व्यावहारिक बनाने के सबसे सरल और सबसे शक्तिशाली तरीकों में से एक है। **रिकवरी + जनरेशन** को मिलाकर, आप स्थिर दस्तावेज़ों को एक **स्मार्ट असिस्टेंट** में बदल सकते हैं और साथ ही, उत्पाद अंतर्दृष्टि की एक निरंतर धारा प्राप्त कर सकते हैं।
+
+मेरे लिए, इस परियोजना ने दिखाया कि RAG केवल एक तकनीकी चाल नहीं है। यह दस्तावेज़ीकरण को बदलने का एक तरीका है:
+
+- एक इंटरैक्टिव समर्थन प्रणाली
+- एक प्रतिक्रिया चैनल
+- एक उत्पाद रणनीति उपकरण
+
+👉 [यहाँ डेमो आज़माएँ](https://intlayer.org/doc/why) 👉 [GitHub पर कोड टेम्पलेट देखें](https://github.com/aymericzip/smart_doc_RAG)
+
+और यदि आप भी RAG के साथ प्रयोग कर रहे हैं, तो मैं सुनना चाहूंगा कि आप इसे कैसे उपयोग कर रहे हैं।

package/blog/it/rag_powered_documentation_assistant.md

@@ -0,0 +1,284 @@
+---
+createdAt: 2025-09-10
+updatedAt: 2025-09-10
+title: Costruire un Assistente alla Documentazione Potenziato da RAG (Chunking, Embeddings e Ricerca)
+description: Costruire un Assistente alla Documentazione Potenziato da RAG (Chunking, Embeddings e Ricerca)
+keywords:
+  - RAG
+  - Documentazione
+  - Assistente
+  - Chunking
+  - Embeddings
+  - Ricerca
+slugs:
+  - blog
+  - rag-powered-documentation-assistant
+---
+
+# Costruire un Assistente alla Documentazione Potenziato da RAG (Chunking, Embeddings e Ricerca)
+
+## Cosa ottieni
+
+Ho costruito un assistente alla documentazione potenziato da RAG e l'ho confezionato in un boilerplate che puoi usare immediatamente.
+
+- Include un'applicazione pronta all'uso (Next.js + OpenAI API)
+- Include una pipeline RAG funzionante (chunking, embeddings, similarità coseno)
+- Fornisce un'interfaccia chatbot completa costruita in React
+- Tutti i componenti UI sono completamente modificabili con Tailwind CSS
+- Registra ogni query dell'utente per aiutare a identificare documentazione mancante, punti dolenti degli utenti e opportunità di prodotto
+
+👉 [Demo live](https://intlayer.org/doc/why) 👉 [Boilerplate del codice](https://github.com/aymericzip/smart_doc_RAG)
+
+## Introduzione
+
+Se ti sei mai perso nella documentazione, scorrendo all'infinito alla ricerca di una risposta, sai quanto può essere frustrante. La documentazione è utile, ma è statica e la ricerca spesso risulta macchinosa.
+
+Ed è qui che entra in gioco **RAG (Retrieval-Augmented Generation)**. Invece di costringere gli utenti a scavare nel testo, possiamo combinare **retrieval** (trovare le parti giuste della documentazione) con **generation** (permettendo a un LLM di spiegarla in modo naturale).
+
+In questo post, ti guiderò attraverso il modo in cui ho costruito un chatbot per la documentazione alimentato da RAG e come questo non solo aiuta gli utenti a trovare risposte più velocemente, ma offre anche ai team di prodotto un nuovo modo per comprendere i punti dolenti degli utenti.
+
+## Perché usare RAG per la documentazione?
+
+RAG è diventato un approccio popolare per una ragione: è uno dei modi più pratici per rendere i modelli di linguaggio di grandi dimensioni realmente utili.
+
+Per la documentazione, i vantaggi sono chiari:
+
+- Risposte istantanee: gli utenti chiedono in linguaggio naturale e ricevono risposte pertinenti.
+- Contesto migliore: il modello vede solo le sezioni della documentazione più rilevanti, riducendo le allucinazioni.
+- Ricerca che sembra umana: più simile a una combinazione di Algolia + FAQ + chatbot.
+- Ciclo di feedback: memorizzando le query, si scopre ciò con cui gli utenti hanno davvero difficoltà.
+
+Quel ultimo punto è cruciale. Un sistema RAG non si limita a rispondere alle domande, ma ti dice cosa le persone stanno chiedendo. Questo significa:
+
+- Scopri informazioni mancanti nella tua documentazione.
+- Vedi emergere richieste di funzionalità.
+- Individui schemi che possono persino guidare la strategia di prodotto.
+
+Quindi, RAG non è solo uno strumento di supporto. È anche un **motore di scoperta del prodotto**.
+
+## Come funziona la pipeline RAG
+
+![RAG Pipeline](https://github.com/aymericzip/intlayer/blob/main/docs/assets/rag_flow.svg)
+
+Ad alto livello, ecco la ricetta che ho usato:
+
+1.  **Suddivisione della documentazione in chunk** Grandi file Markdown vengono divisi in chunk. La suddivisione permette di fornire come contesto solo le parti rilevanti della documentazione.
+2.  **Generazione degli embeddings** Ogni chunk viene trasformato in un vettore usando l’API di embedding di OpenAI (text-embedding-3-large) o un database vettoriale (Chroma, Qdrant, Pinecone).
+3.  **Indicizzazione e memorizzazione** Gli embeddings vengono memorizzati in un semplice file JSON (per la mia demo), ma in produzione probabilmente useresti un database vettoriale.
+4.  **Recupero (R in RAG)** La query dell’utente viene trasformata in embedding, si calcola la similarità coseno e si recuperano i chunk più pertinenti.
+5.  **Aumento + Generazione (AG in RAG)** Quei chunk vengono inseriti nel prompt per ChatGPT, così il modello risponde con il contesto reale della documentazione.
+6.  **Registrazione delle query per feedback** Ogni query utente viene memorizzata. Questo è prezioso per capire i punti critici, la documentazione mancante o nuove opportunità.
+
+## Passo 1: Lettura della Documentazione
+
+Il primo passo è stato semplice: avevo bisogno di un modo per scansionare una cartella docs/ per tutti i file .md. Usando Node.js e glob, ho recuperato il contenuto di ogni file Markdown in memoria.
+
+Questo mantiene la pipeline flessibile: invece di Markdown, potresti recuperare la documentazione da un database, un CMS o anche un'API.
+
+## Passo 2: Suddividere la Documentazione in Chunk
+
+Perché suddividere in chunk? Perché i modelli linguistici hanno **limiti di contesto**. Fornire loro un intero libro di documentazione non funzionerà.
+
+Quindi l'idea è di spezzare il testo in chunk gestibili (ad esempio 500 token ciascuno) con sovrapposizione (ad esempio 100 token). La sovrapposizione garantisce continuità così da non perdere il significato ai confini dei chunk.
+
+**Esempio:**
+
+- Chunk 1 → “…la vecchia biblioteca che molti avevano dimenticato. Le sue scaffalature imponenti erano piene di libri…”
+- Chunk 2 → “…le scaffalature erano piene di libri di ogni genere immaginabile, ognuno sussurrando storie…”
+
+La sovrapposizione assicura che entrambi i chunk contengano un contesto condiviso, così il recupero rimane coerente.
+
+Questo compromesso (dimensione del chunk vs sovrapposizione) è fondamentale per l’efficienza di RAG:
+
+- Troppo piccolo → si genera rumore.
+- Troppo grande → si satura la dimensione del contesto.
+
+## Passo 3: Generazione degli Embeddings
+
+Una volta che i documenti sono stati suddivisi in chunk, generiamo gli **embeddings** — vettori ad alta dimensione che rappresentano ogni chunk.
+
+Ho utilizzato il modello text-embedding-3-large di OpenAI, ma potresti usare qualsiasi modello moderno di embedding.
+
+**Esempio di embedding:**
+
+```js
+[
+  -0.0002630692, -0.029749284, 0.010225477, -0.009224428, -0.0065269712,
+  -0.002665544, 0.003214777, 0.04235309, -0.033162255, -0.00080789323,
+  //...+1533 elementi
+];
+```
+
+Ogni vettore è un’impronta matematica del testo, che permette la ricerca per similarità.
+
+## Passo 4: Indicizzazione e Memorizzazione degli Embeddings
+
+Per evitare di rigenerare gli embeddings più volte, li ho memorizzati in embeddings.json.
+
+In produzione, probabilmente vorresti un database vettoriale come:
+
+- Chroma
+- Qdrant
+- Pinecone
+- FAISS, Weaviate, Milvus, ecc.
+
+I database vettoriali gestiscono indicizzazione, scalabilità e ricerca veloce. Ma per il mio prototipo, un JSON locale ha funzionato bene.
+
+## Passo 5: Recupero con Similarità Coseno
+
+Quando un utente fa una domanda:
+
+1. Genera un embedding per la query.
+2. Confrontalo con tutti gli embedding dei documenti usando la **similarità coseno**.
+3. Conserva solo i primi N chunk più simili.
+
+La similarità coseno misura l'angolo tra due vettori. Una corrispondenza perfetta ottiene un punteggio di **1.0**.
+
+In questo modo, il sistema trova i passaggi del documento più vicini alla query.
+
+## Passo 6: Aggiunta + Generazione
+
+Ora arriva la magia. Prendiamo i chunk migliori e li inseriamo nel **prompt di sistema** per ChatGPT.
+
+Ciò significa che il modello risponde come se quei frammenti facessero parte della conversazione.
+
+Il risultato: risposte accurate e **basate sulla documentazione**.
+
+## Passo 7: Registrazione delle Query degli Utenti
+
+Questa è la superpotenza nascosta.
+
+Ogni domanda posta viene memorizzata. Nel tempo, si costruisce un dataset di:
+
+- Domande più frequenti (ottimo per le FAQ)
+- Domande senza risposta (documentazione mancante o poco chiara)
+- Richieste di funzionalità mascherate da domande (“Si integra con X?”)
+- Casi d’uso emergenti che non avevi previsto
+
+Questo trasforma il tuo assistente RAG in uno **strumento continuo di ricerca utenti**.
+
+## Quanto Costa?
+
+Una comune obiezione al RAG è il costo. In pratica, è sorprendentemente economico:
+
+- Generare embedding per circa 200 documenti richiede circa **5 minuti** e costa **1–2 euro**.
+- La funzione di ricerca nei documenti è completamente gratuita.
+- Per le query, utilizziamo gpt-4o-latest senza la modalità “thinking”. Su Intlayer, registriamo circa **300 query chat al mese**, e la fattura dell’API OpenAI raramente supera i **10$**.
+
+Oltre a questo, puoi includere il costo dell’hosting.
+
+## Dettagli di Implementazione
+
+Stack:
+
+- Monorepo: workspace pnpm
+- Pacchetto Doc: Node.js / TypeScript / OpenAI API
+- Frontend: Next.js / React / Tailwind CSS
+- Backend: route API Node.js / OpenAI API
+
+Il pacchetto `@smart-doc/docs` è un pacchetto TypeScript che gestisce l’elaborazione della documentazione. Quando un file markdown viene aggiunto o modificato, il pacchetto include uno script `build` che ricostruisce la lista della documentazione in ogni lingua, genera gli embeddings e li memorizza in un file `embeddings.json`.
+
+Per il frontend, utilizziamo un’applicazione Next.js che fornisce:
+
+- Rendering da Markdown a HTML
+- Una barra di ricerca per trovare la documentazione rilevante
+- Un'interfaccia chatbot per porre domande sulla documentazione
+
+Per eseguire una ricerca nella documentazione, l'applicazione Next.js include una route API che chiama una funzione nel pacchetto `@smart-doc/docs` per recuperare i frammenti di documentazione corrispondenti alla query. Utilizzando questi frammenti, possiamo restituire una lista di pagine della documentazione rilevanti per la ricerca dell'utente.
+
+Per la funzionalità chatbot, seguiamo lo stesso processo di ricerca ma in aggiunta iniettiamo i frammenti di documentazione recuperati nel prompt inviato a ChatGPT.
+
+Ecco un esempio di prompt inviato a ChatGPT:
+
+Prompt di sistema:
+
+```txt
+Sei un assistente utile che può rispondere a domande sulla documentazione di Intlayer.
+
+Frammenti correlati:
+
+-----
+docName: "getting-started"
+docChunk: "1/3"
+docUrl: "https://example.com/docs/it/getting-started"
+---
+
+# Come iniziare
+
+...
+
+-----
+docName: "another-doc"
+docChunk: "1/5"
+docUrl: "https://example.com/docs/it/another-doc"
+---
+
+# Un altro documento
+
+...
+```
+
+Query utente :
+
+```txt
+Come iniziare?
+```
+
+Usiamo SSE per trasmettere la risposta dalla route API.
+
+Come accennato, utilizziamo gpt-4-turbo senza la modalità "thinking". Le risposte sono pertinenti e la latenza è bassa.
+Abbiamo sperimentato con gpt-5, ma la latenza era troppo alta (a volte fino a 15 secondi per una risposta). Tuttavia, lo rivaluteremo in futuro.
+
+👉 [Prova la demo qui](https://intlayer.org/doc/why) 👉 [Controlla il modello di codice su GitHub](https://github.com/aymericzip/smart_doc_RAG)
+
+## Andare oltre
+
+Questo progetto è una implementazione minima. Ma puoi estenderlo in molti modi:
+
+- Server MCP → la funzione di ricerca nella documentazione verso un server MCP per connettere la documentazione a qualsiasi assistente AI
+
+- Database vettoriali → scalare a milioni di frammenti di documenti
+- LangChain / LlamaIndex → framework pronti all'uso per pipeline RAG
+- Cruscotti di analisi → visualizzare le query degli utenti e i punti critici
+- Recupero multi-sorgente → estrarre non solo documenti, ma anche voci di database, post di blog, ticket, ecc.
+- Prompting migliorato → riordinamento, filtraggio e ricerca ibrida (parola chiave + semantica)
+
+## Limitazioni che abbiamo incontrato
+
+- La suddivisione in frammenti e la sovrapposizione sono empiriche. Il giusto equilibrio (dimensione del frammento, percentuale di sovrapposizione, numero di frammenti recuperati) richiede iterazione e test.
+- Gli embeddings non vengono rigenerati automaticamente quando i documenti cambiano. Il nostro sistema resetta gli embeddings per un file solo se il numero di frammenti differisce da quello memorizzato.
+- In questo prototipo, gli embeddings sono memorizzati in JSON. Questo funziona per le demo ma inquina Git. In produzione, è meglio utilizzare un database o un archivio vettoriale dedicato.
+
+## Perché Questo È Importante Oltre la Documentazione
+
+La parte interessante non è solo il chatbot. È il **ciclo di feedback**.
+
+Con RAG, non ti limiti a rispondere:
+
+- Impari cosa confonde gli utenti.
+- Scopri quali funzionalità si aspettano.
+- Adatti la tua strategia di prodotto basandoti sulle query reali.
+
+**Esempio:**
+
+Immagina di lanciare una nuova funzionalità e vedere immediatamente:
+
+- Il 50% delle domande riguarda lo stesso passaggio di configurazione poco chiaro
+- Gli utenti chiedono ripetutamente un’integrazione che ancora non supporti
+- Le persone cercano termini che rivelano un nuovo caso d’uso
+
+Questa è **intelligenza di prodotto** direttamente dai tuoi utenti.
+
+## Conclusione
+
+RAG è uno dei modi più semplici e potenti per rendere pratici i LLM. Combinando **recupero + generazione**, puoi trasformare documenti statici in un **assistente intelligente** e, allo stesso tempo, ottenere un flusso continuo di approfondimenti sul prodotto.
+
+Per me, questo progetto ha dimostrato che RAG non è solo un trucco tecnico. È un modo per trasformare la documentazione in:
+
+- un sistema di supporto interattivo
+- un canale di feedback
+- uno strumento di strategia di prodotto
+
+👉 [Prova la demo qui](https://intlayer.org/doc/why) 👉 [Controlla il modello di codice su GitHub](https://github.com/aymericzip/smart_doc_RAG)
+
+E se anche tu stai sperimentando con RAG, mi piacerebbe sapere come lo stai usando.