بناء مساعد توثيق مدعوم بـ RAG (التقسيم، التضمينات، والبحث)

ما ستحصل عليه

لقد قمت ببناء مساعد توثيق مدعوم بـ RAG وقمت بتغليفه في قالب يمكنك استخدامه فورًا.

• يأتي مع تطبيق جاهز للاستخدام (Next.js + OpenAI API)
• يتضمن خط أنابيب RAG يعمل (التقسيم، التضمينات، تشابه جيب التمام)
• يوفر واجهة مستخدم كاملة للدردشة مبنية باستخدام React
• جميع مكونات واجهة المستخدم قابلة للتحرير بالكامل باستخدام Tailwind CSS
• يسجل كل استعلام من المستخدم لمساعدة في تحديد الوثائق المفقودة، نقاط الألم لدى المستخدمين، وفرص المنتج

👉 عرض مباشر 👉 قالب الكود

المقدمة

إذا شعرت يومًا بالضياع في الوثائق، تتصفح بلا نهاية بحثًا عن إجابة واحدة، فأنت تعلم مدى صعوبة ذلك. الوثائق مفيدة، لكنها ثابتة والبحث فيها غالبًا ما يكون غير سلس.

هنا يأتي دور RAG (التوليد المعزز بالاسترجاع). بدلاً من إجبار المستخدمين على التنقيب في النصوص، يمكننا دمج الاسترجاع (إيجاد الأجزاء الصحيحة من الوثيقة) مع التوليد (السماح لنموذج اللغة الكبير بشرحها بشكل طبيعي).

في هذا المنشور، سأرشدك خلال كيفية بناء روبوت دردشة للوثائق مدعوم بتقنية RAG، وكيف أنه لا يساعد المستخدمين فقط في العثور على الإجابات بشكل أسرع، بل يمنح فرق المنتج أيضًا طريقة جديدة لفهم نقاط الألم لدى المستخدمين.

لماذا نستخدم RAG للوثائق؟

أصبحت تقنية RAG نهجًا شائعًا لسبب وجيه: فهي واحدة من أكثر الطرق العملية لجعل نماذج اللغة الكبيرة مفيدة بالفعل.

بالنسبة للوثائق، الفوائد واضحة:

• إجابات فورية: يطرح المستخدمون أسئلتهم بلغة طبيعية ويحصلون على ردود ذات صلة.
• سياق أفضل: يرى النموذج فقط أقسام الوثائق الأكثر صلة، مما يقلل من الهلوسة.
• بحث بشعور بشري: أشبه بـ Algolia + الأسئلة الشائعة + روبوت الدردشة، مدمجة في واحد.
• حلقة تغذية راجعة: من خلال تخزين الاستفسارات، تكشف ما يعاني منه المستخدمون حقًا.

هذه النقطة الأخيرة حاسمة. نظام RAG لا يجيب فقط على الأسئلة، بل يخبرك بما يسأله الناس. هذا يعني:

• تكتشف المعلومات المفقودة في وثائقك.
• ترى طلبات الميزات تظهر.
• تلاحظ أنماطًا يمكن أن توجه حتى استراتيجية المنتج.

لذا، RAG ليس مجرد أداة دعم. إنه أيضًا محرك اكتشاف المنتج.

كيف يعمل خط أنابيب RAG

على مستوى عالٍ، هذه هي الوصفة التي استخدمتها:

1. تقسيم الوثائق يتم تقسيم ملفات Markdown الكبيرة إلى أجزاء. يسمح التقسيم بتوفير كجزء من السياق فقط الأجزاء ذات الصلة من الوثائق.
2. توليد التضمينات يتم تحويل كل جزء إلى متجه باستخدام واجهة برمجة تطبيقات التضمين من OpenAI (text-embedding-3-large) أو قاعدة بيانات متجهات (Chroma، Qdrant، Pinecone).
3. الفهرسة والتخزين يتم تخزين التضمينات في ملف JSON بسيط (لعرضي التوضيحي)، ولكن في الإنتاج، من المحتمل أن تستخدم قاعدة بيانات متجهات.
4. الاسترجاع (R في RAG) يتم تضمين استعلام المستخدم، ويتم حساب تشابه جيب التمام، ويتم استرجاع الأجزاء الأعلى تطابقًا.
5. التعزيز + التوليد (AG في RAG) يتم حقن تلك الأجزاء في الموجه لـ ChatGPT، بحيث يجيب النموذج بسياق الوثائق الفعلي.
6. تسجيل الاستعلامات للتغذية الراجعة يتم تخزين كل استعلام مستخدم. هذا أمر ثمين لفهم نقاط الألم، الوثائق المفقودة، أو الفرص الجديدة.

الخطوة 1: قراءة الوثائق

كانت الخطوة الأولى بسيطة: كنت بحاجة إلى طريقة لمسح مجلد docs/ لجميع ملفات .md. باستخدام Node.js و glob، قمت بجلب محتوى كل ملف Markdown إلى الذاكرة.

هذا يحافظ على مرونة خط المعالجة: بدلاً من Markdown، يمكنك جلب الوثائق من قاعدة بيانات، أو نظام إدارة محتوى، أو حتى من API.

الخطوة 2: تقسيم الوثائق إلى أجزاء

لماذا التقسيم؟ لأن نماذج اللغة لها حدود سياقية. تغذيتهم بكتاب كامل من الوثائق لن تنجح.

لذا الفكرة هي تقسيم النص إلى أجزاء قابلة للإدارة (مثلًا 500 رمز لكل جزء) مع تداخل (مثلًا 100 رمز). يضمن التداخل الاستمرارية حتى لا تفقد المعنى عند حدود الأجزاء.

مثال:

• الجزء 1 → "...المكتبة القديمة التي نسيها الكثيرون. كانت رفوفها الشاهقة مليئة بالكتب..."
• الجزء 2 → "...كانت الرفوف مليئة بالكتب من كل نوع يمكن تخيله، كل منها يهمس بقصص..."

يضمن التداخل أن يحتوي كلا الجزأين على سياق مشترك، بحيث يظل الاسترجاع متماسكًا.

هذا التوازن (حجم الجزء مقابل التداخل) هو المفتاح لكفاءة RAG:

• صغير جدًا → تحصل على ضوضاء.
• كبير جدًا → يتضخم حجم السياق.

الخطوة 3: توليد التضمينات

بمجرد تقسيم الوثائق إلى أجزاء، نقوم بتوليد التضمينات — وهي متجهات عالية الأبعاد تمثل كل جزء.

استخدمت نموذج OpenAI المسمى text-embedding-3-large، لكن يمكنك استخدام أي نموذج تضمين حديث.

مثال على تضمين:

[  -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: الاسترجاع باستخدام تشابه جيب التمام (Cosine Similarity)

عندما يطرح المستخدم سؤالاً:

1. توليد تضمين (embedding) للاستعلام.
2. مقارنته مع جميع تضمينات الوثائق باستخدام تشابه جيب التمام.
3. الاحتفاظ فقط بأفضل N قطع نصية متشابهة.

يقيس تشابه جيب التمام الزاوية بين متجهين. التطابق الكامل يحصل على درجة 1.0.

بهذه الطريقة، يجد النظام أقرب مقاطع من الوثائق للاستعلام.

الخطوة 6: التعزيز + التوليد

هنا تأتي السحر. نأخذ أفضل القطع النصية وندمجها في موجه النظام الخاص بـ ChatGPT.

هذا يعني أن النموذج يجيب كما لو أن تلك القطع النصية كانت جزءًا من المحادثة.

النتيجة: ردود دقيقة ومرتكزة على الوثائق.

الخطوة 7: تسجيل استعلامات المستخدم

هذه هي القوة الخفية.

يتم تخزين كل سؤال يُطرح. مع مرور الوقت، تبني مجموعة بيانات من:

• أكثر الأسئلة تكرارًا (مفيد جدًا لصفحات الأسئلة الشائعة)
• الأسئلة التي لم يتم الإجابة عليها (الوثائق مفقودة أو غير واضحة)
• طلبات الميزات التي تتنكر في شكل أسئلة ("هل يتكامل مع X؟")
• حالات استخدام ناشئة لم تكن مخططًا لها

هذا يحول مساعد RAG الخاص بك إلى أداة بحث مستخدم مستمرة.

ما هي التكلفة؟

أحد الاعتراضات الشائعة على RAG هو التكلفة. في الواقع، هي رخيصة بشكل مدهش:

• توليد التضمينات لحوالي 200 وثيقة يستغرق حوالي 5 دقائق ويكلف 1–2 يورو.
• ميزة البحث في الوثائق مجانية 100٪.
• بالنسبة للاستعلامات، نستخدم gpt-4o-latest بدون وضع "التفكير". في Intlayer، نرى حوالي 300 استعلام دردشة شهريًا، وفاتورة OpenAI API نادرًا ما تتجاوز 10 دولارات.

بالإضافة إلى ذلك، يمكنك تضمين تكلفة الاستضافة.

تفاصيل التنفيذ

التقنيات المستخدمة:

• Monorepo: مساحة عمل pnpm
• حزمة الوثائق: Node.js / TypeScript / OpenAI API
• الواجهة الأمامية: Next.js / React / Tailwind CSS
• الواجهة الخلفية: مسار API في Node.js / OpenAI API

حزمة @smart-doc/docs هي حزمة TypeScript تتعامل مع معالجة الوثائق. عند إضافة أو تعديل ملف ماركداون، تتضمن الحزمة سكريبت build يعيد بناء قائمة الوثائق بكل لغة، وينشئ التضمينات، ويخزنها في ملف embeddings.json.

بالنسبة للواجهة الأمامية، نستخدم تطبيق Next.js الذي يوفر:

• تحويل ماركداون إلى HTML
• شريط بحث للعثور على الوثائق ذات الصلة
• واجهة دردشة لطرح الأسئلة حول الوثائق

لإجراء بحث في الوثائق، يتضمن تطبيق Next.js مسار API يستدعي دالة في حزمة @smart-doc/docs لاسترجاع أجزاء الوثائق التي تطابق الاستعلام. باستخدام هذه الأجزاء، يمكننا إرجاع قائمة بصفحات الوثائق ذات الصلة ببحث المستخدم.

بالنسبة لوظيفة الدردشة الآلية، نتبع نفس عملية البحث ولكن نحقن أيضًا أجزاء الوثائق المسترجعة في الموجه المرسل إلى ChatGPT.

إليك مثال على موجه يُرسل إلى ChatGPT:

موجه النظام:

أنت مساعد مفيد يمكنه الإجابة على الأسئلة حول وثائق Intlayer.الأجزاء ذات الصلة:-----docName: "getting-started"docChunk: "1/3"docUrl: "https://example.com/docs/ar/getting-started"---# كيفية البدء...-----docName: "another-doc"docChunk: "1/5"docUrl: "https://example.com/docs/ar/another-doc"---# مستند آخر...

استعلام المستخدم:

كيف أبدأ؟

نستخدم SSE لبث الاستجابة من مسار API.

كما ذُكر، نستخدم gpt-4-turbo بدون وضع "التفكير". الردود ذات صلة، والزمن المستغرق منخفض. قمنا بتجربة gpt-5، لكن زمن الاستجابة كان مرتفعًا جدًا (أحيانًا يصل إلى 15 ثانية للرد). لكننا سنعيد النظر في ذلك في المستقبل.

👉 جرّب العرض التوضيحي هنا 👉 تحقق من قالب الكود على GitHub

التوسع أكثر

هذا المشروع هو تنفيذ بسيط. لكن يمكنك توسيعه بطرق عديدة:

• خادم MCP → وظيفة البحث في الوثائق إلى خادم MCP لربط الوثائق بأي مساعد ذكاء اصطناعي

• قواعد بيانات المتجهات → التوسع إلى ملايين أجزاء الوثائق
• LangChain / LlamaIndex → أُطُر جاهزة لأنابيب RAG
• لوحات تحليلات → تصور استفسارات المستخدمين ونقاط الألم
• استرجاع متعدد المصادر → سحب ليس فقط الوثائق، بل أيضًا إدخالات قواعد البيانات، منشورات المدونات، التذاكر، إلخ.
• تحسين التوجيه → إعادة الترتيب، التصفية، والبحث الهجين (الكلمة المفتاحية + الدلالي)

القيود التي واجهناها

• التقسيم والتداخل تجريبيان. التوازن الصحيح (حجم الجزء، نسبة التداخل، عدد الأجزاء المسترجعة) يتطلب التكرار والاختبار.
• لا يتم إعادة توليد التضمينات تلقائيًا عند تغيير الوثائق. يقوم نظامنا بإعادة تعيين التضمينات لملف فقط إذا اختلف عدد الأجزاء عن المخزن.
• في هذا النموذج الأولي، يتم تخزين التضمينات في JSON. هذا يعمل للعروض التوضيحية ولكنه يلوث Git. في الإنتاج، من الأفضل استخدام قاعدة بيانات أو مخزن متجهات مخصص.

لماذا هذا مهم يتجاوز الوثائق

الجزء المثير للاهتمام ليس فقط الدردشة الآلية. إنه حلقة التغذية الراجعة.

مع RAG، أنت لا تجيب فقط:

• تتعلم ما يربك المستخدمين.
• تكتشف الميزات التي يتوقعونها.
• تعدل استراتيجية منتجك بناءً على الاستفسارات الحقيقية.

مثال:

تخيل إطلاق ميزة جديدة ورؤية على الفور:

• 50% من الأسئلة تدور حول نفس خطوة الإعداد غير الواضحة
• يطلب المستخدمون مرارًا وتكرارًا تكاملًا لا تدعمه بعد
• يبحث الناس عن مصطلحات تكشف عن حالة استخدام جديدة

هذا هو ذكاء المنتج مباشرة من مستخدميك.

الخلاصة

RAG هي واحدة من أبسط وأقوى الطرق لجعل نماذج اللغة الكبيرة (LLMs) عملية. من خلال الجمع بين الاستخراج + التوليد، يمكنك تحويل الوثائق الثابتة إلى مساعد ذكي وفي نفس الوقت الحصول على تدفق مستمر من رؤى المنتج.

بالنسبة لي، أظهر هذا المشروع أن RAG ليست مجرد خدعة تقنية. إنها طريقة لتحويل الوثائق إلى:

• نظام دعم تفاعلي
• قناة تغذية راجعة
• أداة لاستراتيجية المنتج

👉 جرب العرض التوضيحي هنا 👉 تحقق من قالب الكود على GitHub

وإذا كنت تجرب RAG أيضًا، أود أن أسمع كيف تستخدمها.