بناء الاسترجاع الوكيلي على قاعدة معرفة مُدارة في Amazon Bedrock باستخدام CDK

تبني هذه التدوينة استرجاعًا الوكيلي للمؤسسات على قاعدة معرفة مُدارة في Amazon Bedrock باستخدام AWS Cloud Development Kit (AWS CDK). ولكي نرى لماذا يستحق ذلك البناء، من المفيد البدء من حيث تفشل أنظمة التوليد المعزز بالاسترجاع (RAG) العادية. تبدأ معظم أنظمة RAG بالطريقة نفسها: تُحوِّل السؤال إلى تضمينات، وتجلب المقاطع الأقرب من فهرس واحد، وتسلّمها إلى نموذج، ثم تُرجع الإجابة. استرجاع واحد، وتوليد واحد. بالنسبة لفئة واسعة من الأسئلة، هذا هو التصميم الصحيح، ولا داعي لبناء شيء أكثر تعقيدًا.

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

يجيب الاسترجاع الوكيل المؤسسي على الأسئلة الثلاثة جميعها من خلال وضع وكيل استدلالي في الحلقة. يقرر الوكيل ما إذا كان سيقوم بالاسترجاع، وأي قاعدة معرفية سيستشير، وما إذا كان سيعود للمزيد قبل أن يصيغ إجابة. هذا هو الاتجاه قواعد المعرفة في Amazon Bedrock قد تطورت. مع إطلاق قاعدة المعار المُدارة (Managed Knowledge Base)، لم يعد الاسترجاع مجرد استدعاء واحد لتضمين البيانات وجلبها. فقد أصبح قدرة وكية (agentic): تخطيط متعدد الأدوار، واسترجاع مدفوع بالأدوات، وإجابات مسندة ومُوثقة بمصادرها. توفر واجهة AgenticRetrieveStream API هذه الإمكانية كخاصية من الدرجة الأولى في الخدمة بدلاً من أن تضطر إلى تجميعها بنفسك. هذا يعمل جيداً، لكنه يقدم أيضاً مشكلة تشغيلية أصعب فعلاً. خط المعالجة ذو اللمحة الواحدة هو دالة يمكنك فهمها بمجرد قراءتها. أما الوكيل الذي يستدل ويسترجع في حلقة متكررة فيسلك مساراً مختلفاً مع كل سؤال. وبشكل افتراضي، لا يمكنك رؤية المسار الذي سلكه ولا معرفة ما إذا كانت الإجابة التي أنتجها جيدة أصلاً. وهكذا يتوقف متابعة الرصد (Observability) عن كونها ميزة تكميلية لطيفة ليصبح الوسيلة الوحيدة لمعرفة أن النظام يعمل.

في أغسطس 2024، أنشئ حلاً متكاملاً لـ RAG باستخدام Knowledge Bases for Amazon Bedrock و AWS CDK نشر التصميم ذا الطلقة الواحدة كتطبيق CDK: خدمة Amazon Simple Storage Service (Amazon S3) مجموعة نصية، و Amazon OpenSearch Serverless مجموعة وفهرس، وقاعدة معرفة، ومصدر بيانات، مُوفَّرة كأكواد CDK يتم ترتيب تسلسلها يدويًا. ثلاثة أشياء تغيّرت منذ نشرها.

1. Amazon Bedrock يقدم الآن قاعدة معرفة مُدارة (النوع: MANAGED)، الذي يمتلك عمليات الاستيعاب والتخزين والفهرسة والاسترجاع نفسها. مجموعة OpenSearch Serverless والفهرس اللذان ينشئهما post لم يعدا شيئًا تحتاج إلى إنشائهما أو توسيعهما أو الدفع مقابلهما بوحدات OpenSearch Compute Units (OCUs).
2. Amazon Bedrock AgentCore يوفّر النصف الوكيل، وبوابة (Gateway) تعرض كل قاعدة معرفة كأداة Model Context Protocol (MCP)، ووقت تشغيل (Runtime) يستضيف وكيل الاستدلال، وAgenticRetrieveStream، الذي يعيد الترتيب داخليًا ويعيد إجابة مُركّبة مدعومة بالاستشهادات. الاسترجاع الوكيلي متاح فقط على قاعدة المعارف المُدارة.
3. أصبح موضوع المراقبة والتقييم شيئًا يمكنك توفيره الآن، وليست شيئًا يُضاف لاحقًا كملحق. يأتي هذا الحل مزودًا باثنين Amazon CloudWatch لوحات معلومات تمتد على سبع طبقات من القياسات عن بُعد، إضافة إلى شكلين من التقييم، عند الطلب والمستمر، من النشر نفسه.

تقدم هذه التدوينة ذلك النظام: وكيل يوجّه الطلبات عبر قاعدتي معرفة، ويسترجع المعلومات من خلال الـGateway، ويعيد إجابة مُسندة وموثقة بالاستشهادات، مع تزويد كل طبقة من طبقات سلوكه بأدوات القياس، ك AWS CDK تطبيق بلغة Python. أمر واحد ينشر كل شيء، ويستنتج CDK الترتيب.

إذا كنت قد قرأت منشور 2024فسيبدو لك المسار من حاوية Amazon S3 إلى قاعدة المعرفة مألوفًا، وكل ما يأتي بعده جديد: مخزن المتجهات لم يعد موجودًا، والاسترجاع أصبح وكيليًا، ونحو نصف ما يوفّره التطبيق موجود لإخبارك بما فعله الوكيل. وإن لم تكن قد قرأته، فهذه التدوينة قائمة بذاتها.

الخدمات المعنية والمسار الذي تسلكه السؤال الواحد عبرها: يقرر الوكيل (agent) ما إذا كان سيجري استرجاعًا وأي قاعدة معرفية يرجع إليها، وتعرّف البوابة (Gateway) كل قاعدة معرفية كأداة يمكنها استدعاؤها، وتقوم قواعد المعرفة المُدارة بالبحث والاستشهاد، وتتكرر الحلقة بعدد المرات التي يحتاجها السؤال. وكل ما يفعله الوكيل على طول الطريق يُسجَّل في Amazon CloudWatch.

الشكل 1: الخدمات المعنية والمسار الذي يسلكه سؤال واحد عبرها

خلفية

قبل الاستعراض العملي، من المفيد توضيح ثلاثة أمور: ما الذي يجعل الاسترجاع وكيليًا (agentic)، ولماذا تُعدّ قاعدة المعرفة المُدارة الأساس المناسب لها، ولماذا تنتمي المراقبة والتقييم إلى التصميم نفسه بدلًا من إضافتهما لاحقًا.

من RAG إلى الاسترجاع الوكيلي المؤسسي

التوليد المعزز بالاسترجاع (RAG) الكلاسيكي يجري استرجاعًا واحدًا وتوليدًا واحدًا. الاسترجاع الوكيلي المؤسسي يضع وكيلًا استدلاليًا في الحلقة: فهو يقرر ما إذا كان سيجري استرجاعًا و ما ما يجب استرجاعه، ويمكنه الاسترجاع عدة مرات للتحسين، ويختار أي قاعدة معرفية ذات صلة (توجيه دلالي)، وعندها فقط يصوغ إجابة مُسنَدة بالاستشهادات. مع قاعدة المعرفة المُدارة، هذه قديمة من الخدمة من الطراز الأول، إذ تؤدّي واجهة AgenticRetrieveStream التخطيط متعدد الأدوار، وتنفّذ الاسترجاع، وتعيد إجابة مدعومة بالاستشهادات، بدلًا من طبقة تنسيق تبنيها وتصونها بنفسك فوق بحث متجهي خام. وهذا ينتج إجابات أفضل في الأسئلة المعقدة، لكنه ينتج أيضًا نظامًا أكثر تعقيدًا في التشغيل، وهو بالضبط سبب بناء المراقبة والتقييم من البداية.

المُقارَن مقابل قواعد المعرفة ذاتية الإدارة

يقدّم Amazon Bedrock الآن قاعدة معرفة مُدارة (النوع: MANAGED): يدير Amazon Bedrock الاستيعاب والتخزين والفهرسة والاسترجاع بالنيابة عنك، بما في ذلك التضمين وإعادة الترتيب باستخدام نماذج تديرها الخدمة افتراضيًا، فلا يوجد قاعدة بيانات متجهية لتوفيرها أو توسيعها أو ترقيعها. يختلف هذا عن قاعدة المعرفة ذاتية الإدارة من قِبل العميل (DIY)، حيث تختار وتشغّل مخزن المتجهات بنفسك (على سبيل المثال، Amazon OpenSearch Serverless).

يلفت الانتباه في هذا الحل فرقان رئيسيان:

نظرًا لأن الاسترجاع الوكيل وموصل AgentCore Gateway متاحان فقط على قاعدة المعرفة المُدارة، فهي الأساس الطبيعي للاسترجاع الوكيل المؤسسي. كما يعني هذا أن Amazon Bedrock يدير التخزين والفهرسة نيابة عنك، لذا لا توجد حاجة لتوفير مجموعة OpenSearch Serverless أو سعة OCU في هذا التصميم. يظل الخيار المُدار من قِبل العميل هو الاختيار الصحيح عندما ترغب في اختيار وتشغيل مخزن المتجهات الخاص بك، على سبيل المثال لإعادة استخدام مجموعة OpenSearch Serverless موجودة أو لتلبية متطلبات محددة تتعلق بموطن البيانات أو الضبط أو الامتثال. بالنسبة للاسترجاع الوكيل المؤسسي، فإن قاعدة المعرفة المُدارة هي ما يجعل هذه القدرة ممكنة.

لماذا المراقبة والتقييم

النظام الوكيل الذي يُرجع إجابة لا يكفي للإنتاج. تحتاج إلى معرفة كيف يتصرف (زمن الاستجابة، حجم الطلبات، استخدام الرموز)، ومدى جودة الاسترجاع والإجابات، وتحتاج إلى تلك الإشارات بشكل مستمر. هذا الحل يأتي مع لوحتي معلومات CloudWatch تغطيان سبع طبقات من القياسات، بالإضافة إلى شكلين من التقييم (عند الطلب والمستمر)، وكلها مُوفَّرة بواسطة تطبيق CDK نفسه. طبقات الارتكاز والاستشهاد والتقييم تدعم أيضًا الاستخدام المسؤول. الإجابات المستشهد بها يمكن تتبعها إلى مقاطعها المصدرية بحيث تبقى الاستجابات قابلة للتدقيق، وتتيح لك درجات الدقة والصحة اكتشاف الإجابات التي تنحرف عن مصادرها بدلاً من اكتشاف ذلك في بيئة الإنتاج.

لماذا CDK لهذا الحل تحديدًا

أي أداة بنية تحتية كتعليمات برمجية يمكنها إنشاء هذه الموارد. لكن CDK يثبت جدارته هنا لسبب يتعلق بهذه البنية تحديدًا: الحزم الأربع مترابطة إشارةً بعضها مع بعض بإحكام. يحتاج الـ Gateway إلى معرّفي قاعدة المعرفة كليهما. يحتاج الوكيل إلى عنوان URL وARN الخاصين بالـ Gateway. تحتاج لوحات المعلومات إلى معرّفات KB، وARN الخاص بالـ Gateway، و معرّف بيئة تشغيل الوكيل، أي سبع قيم تعبر حدود الحزم، كل واحدة منها بُعد على مقياس أو هدف على موصل.

إذا كُتبت كقوالب خام، فهي مجموعة من عمليات تصدير المكدسات (stack exports) وعمليات البحث بين المكدسات تُبقى متسقة يدويًا، إضافة إلى سكربت ينشر بالترتيب الصحيح ويمرر المخرجات إلى الأمام، وكلاهما ينحرف فور إعادة تسمية أي شيء. في CDK تمرر الكونستركت (construct)، فيُشتق التصدير وحافة الاعتمادية من ذلك الفعل الواحد المتمثل في تمريره. كان حل عام 2024 يتكون من ثلاثة مكدسات وسلسلة اعتمادية شبه خطية. عند أربعة مكدسات مع سبع قيم تعبر بينها، يتوقف الفرق عن كونه اختلافًا في الأسلوب فقط.

نظرة عامة على الحل

إليك المسار الذي تسلكه سؤال واحد عبر النظام من البداية إلى النهاية. يستحق نظرة متأنية، لأن بقية المقال تستعرضه من اليسار إلى اليمين.

يتتبع المخطط التالي سير عمل الاسترجاع الوكيلي من البداية إلى النهاية. يدخل سؤال المستخدم إلى الوكيل على AgentCore Runtime، الذي يوجهه عبر AgentCore Gateway إلى إحدى أداتي AgenticRetrieveStream، واحدة لكل قاعدة معرفية مُدارة، مالية وأخرى للأرصاد الجوية، كل منهما مُستوعَبة من Amazon S3. تُرجع الأداة المختارة إجابة مُسنَدة ومدعومة بالاستشهادات، وتُبَث كل خطوة إلى Amazon CloudWatch وAWS X-Ray. تتوافق الشارات المرقمة مع الشرح التفصيلي التالي.

الشكل 2: سير العمل الوكيلي للاسترجاع من البداية إلى النهاية لسؤال واحد

تتوافق الخطوات المرقمة في المخطط مع سير العمل، الذي هو كالآتي.

الخطوة 0 — لمرة واحدة، عند النشر. قبل طرح أي سؤال، يُستوعب كل محتوى نصي (corpus) في Amazon S3 في قاعدة معرفية مُدارة خاصة به: حيث يقوم Amazon Bedrock تلقائيًا بالتحليل والتقسيم إلى أجزاء والتضمين والفهرسة. يحدث هذا مرة واحدة عند نشر المكدسات، وليس جزءًا من مسار كل سؤال، لذا يُرسم كسهم متقطع ويُشار إليه بالخطوة 0. ثم يتبع كل سؤال الخطوات 1–6:

1. يرسل المستخدم سؤالًا إلى الوكيل المستضاف على Amazon Bedrock AgentCore Runtime. يقوم Runtime بقيادة السبب والفعل loop بالكامل تلقائيًا باستخدام نطاقات OpenTelemetry (OTEL)، بحيث يكون النظام قابلاً للرصد من أول استدعاء.
2. يخطط نموذج الاستدلال لدى الوكيل ويوجه الاستعلام عبر قواعد المعرفة. نظرًا لأن كل قاعدة معرفية مكشوفة كأداة استرجاع خاصة بها، يختار الوكيل الأداة التي يتطابق موضوعها مع السؤال، المالية أو الجوية، بدلاً من البحث في فهرس مدمج واحد.
3. يتم توسط الاستدعاء للأداة المختارة بواسطة AgentCore Gateway عبر MCP، مصرحًا به من خلال دور مهمة IAM الخاص بالوكيل وموقّعًا بـ SigV4، والذي يستدعي واجهة AgenticRetrieveStream الخاصة بتلك القاعدة المعرفية على القاعدة المعرفية المُدارة.
4. تقوم AgenticRetrieveStream بالعمل داخل القاعدة المعرفية: حيث تُفكك السؤال إلى استعلامات فرعية، وتسترجع بشكل تكراري من مخزن البيانات الذي يديره Amazon Bedrock (المستوعَب من المحتويات النصية في Amazon S3)، وتولّف إجابة مُسنَدة ومدعومة بالاستشهادات تُبَث مرة أخرى عبر الـ Gateway.
5. يتحقق الوكيل مما إذا كان السياق المُرجَع كافيًا. إن لم يكن كافيًا، فسيكرر العملية، ويوجه ويسترجع مرة أخرى، قبل صياغة إجابته النهائية. وإن كان كافيًا، فيُرجع الإجابة المدعومة بالاستشهادات إلى المستخدم.
6. على مدار العملية، يُصدر Runtime نطاقات (spans) وعدادات رموز (token counts) ومقاييس إلى Amazon CloudWatch وAWS X-Ray، مما يملأ طبقات الرصد السبع ويغذي درجات التقييم كلاهما عند الطلب والمستمر.

داخليًا، سير العمل هذا هو تطبيق CDK واحد، app.pyيعلن عن أربعة مكدسات. أنت لا تختار الترتيب؛ بل يشتقه CDK من مراجع الكونستركت التي تمررها:

kb_stack = KnowledgeBasesStack(app, f"{project}-kb", env=env)

gateway_stack = AgenticGatewayStack(
    app, f"{project}-gateway", env=env,
    financial_kb=kb_stack.financial_kb,  # ← the reference creates the dependency
    weather_kb=kb_stack.weather_kb,
)

agent_stack = AgentRuntimeStack(
    app, f"{project}-agent", env=env,
    gateway=gateway_stack.gateway,
)

DashboardsStack(
    app, f"{project}-dashboards", env=env,
    financial_kb=kb_stack.financial_kb,
    weather_kb=kb_stack.weather_kb,
    gateway=gateway_stack.gateway,
    agent_runtime=agent_stack.agent_runtime,
)

هذا هو التوصيل كله. تلك الاستدعاءات الإنشائية الأربعة هي ما يستبدل بجداول التصدير/الاستيراد وسكربت النشر.

يعمل الوكيل في حلقة تفكير وتصرّف: يفكر (استدعاء لنموذج لغوي كبير (LLM))، ويقرر أي أداة KB يستدعي، ويقرأ ما عاد عبر Gateway، وكثيرًا ما يسترجع مرة أخرى قبل صياغة إجابته النهائية مع الاستشهادات. تُقاس كل خطوة تلقائيًا بواسطة Runtime، فتمتلئ طبقات المراقبة السبع من حركة مرور حقيقية.

الطبقات السبع. L1 مقاييس KB الأصلية، L2 الاستيعاب، L3 جودة الاسترجاع الوكيلي، L4 مقاييس Gateway/MCP، L5 شجرة نطاقات OTEL ، L6 استخدام الرموز (tokens)، وL7 درجات التقييم. تُصدر الطبقات 1 و4 و5 تلقائيًا. أما الطبقات 3 و6 و7 فتُنشر كمقاييس مخصصة بواسطة دفتر الملاحظات (notebook) المشغّل.

كل ما يمكن ضبطه يقع في ملف واحد، config.py:

تغيير PROJECT_NAME يمنحك نسخة مستقلة الاسم من الحل بأكمله، بحيث يمكن لعمليتي نشر أن تتعايشا في حساب واحد. يقرأ دفتر الملاحظات المشغّل (driver notebook) الثابت نفسه، لذا يتبع إعادة التسمية تلقائيًا، ولا توجد أسماء حزم يجب مزامنتها يدويًا.

وصف مجموعة البيانات

يأتي الحل مع مجموعتي بيانات نصيتين صغيرتين، مرفقتين في المستودع ضمن data/:

• المالية — نموذج تقديري 10-K مركّب لشركة Octank المالية (octank_financial_10K.pdf، بحجم ~198 كيلوبايت).
• الطقس — تقرير حقيقي ومتاح للعموم صادر عن خدمة أبحاث الكونغرس الأمريكي حول الأعاصير المارية (IF12695، tornadoes_report.pdf، بحجم ~560 كيلوبايت).

عن البيانات: المجموعة النصية المالية اصطناعية؛ فشركة Octank شركة خيالية وتقرير الـ 10-K بيانات نموذجية مولّدة بالنموذج (مرخصة بموجب CC0). إنهاليست بيانات مالية حقيقية. كتلة بيانات الطقس هي عمل حقيقي للولايات المتحدة الحكومي في الملكية العامة وهو تقرير من هيئة خدمة أبحاث الكونغرس، متاح للعموم على الرابط sgp.fas.org/crs/misc/IF12695.pdf (أعمال الحكومة الأمريكية لا تخضع لحقوق النشر). لاستخدام بياناتك الخاصة، ضع الملفات تحت data/ وعدّل البادئات في config.py، ولا يلزم أي تغيير آخر.

كتلتا البيانات مختلفتان عمداً، بحيث يجب على الوكيل توجيه كل سؤال إلى قاعدة المعرفة الصحيحة، وهذه هي فكرة التوجيه الدلالي. ولأن هاتين قاعدتي معرفة مُدارَتين (Managed Knowledge Bases)، لا نقوم بتكوين التقسيم إلى مقاطع (chunking) أو التضمين أو الفهرسة: عند الإدخال، يقوم Amazon Bedrock بتحليل كل ملف PDF وتقسيمه وتضمينه باستخدام نموذجه المُدار وفهرسته تلقائياً.

نستخدم قاعدتي معرفة منفصلتين، تتعرض كل منهما عبر الـ Gateway كأداة استرجاع خاصة بها، بدلاً من قاعدة معرفة واحدة تحتفظ بكلتا كتلتَي البيانات، وهذا الخيار مقصود. منح الوكيل أداتين مسمّاتين يجعل التوجيه عملاً صريحاً من أعمال الاستدلال يمكن ملاحظته: تُظهر شجرة المقتطفات (span tree) أي أداة اختارها لسؤال معين، كما تبقى مقاييس جودة الاسترجاع في الطبقة 3 قابلة للفصل لكل قاعدة معرفة، فلا يختلط أدقّ الطقس والمالية أبداً في رقم واحد. أداة واحدة تغطي كلتا الكتلتَين ستُسقط هذا التمييز، إذ ينتقل قرار التوجيه إلى داخل ترتيب فهرس واحد بعيداً عن الأنظار، وتصبح كل إشارة جودة متوسطاً عبر نطاقين غير مترابطين. الحفاظ على الكتلتين وأدواتهما منفصلتين هو ما يجعل سلوك الوكيل مقروءاً، وهذا هو الهدف الكلي من التمرين.

في CDK، يتم وضع الكتلتين في S3 عبر BucketDeployment:

s3deploy.BucketDeployment(
    self, "FinancialCorpus",
    sources=[s3deploy.Source.asset(str(ROOT / "data" / "financial"))],
    destination_bucket=self.source_bucket,
    destination_key_prefix=KbConfig.FINANCIAL_PREFIX,
)

تستحق BucketDeployment المعرفة تحديداً لأن البديل مغري جداً: بدونها، يميل المورد المخصص الذي يطلق الإدخال إلى أن ينمّي عليه خطوة رفع، فيصبح مورد واحد مسؤولاً عن مهمتين غير مترابطتين. هنا لا يتعين عليه سوى ingest.

الإدخال المُدار يمسح كل مستند ويقسّمه ويضمّنه ويفهرسه تلقائياً: مستند واحد مفهرس لكل قاعدة معرفة، وبلا أي إخفاقات.

الشكل 3: نتائج الإدخال المُدار، مستند واحد مفهرس لكل قاعدة معرفة وبلا أي إخفاقات

نشر الحل

يتناول هذا القسم شرح نشر الحل كاملاً بأمر واحد. بعد استيفاء المتطلبات المسبقة، cdk deploy --all يوفر الحزم الأربع جميعها بالترتيب الاعتمادي المشتق في CDK ويمرر كل قيمة عابرة للحزم تلقائياً.

المتطلبات الأساسية

• حساب AWS له أذونات لـ Amazon Bedrock و AgentCore (Runtime + Gateway)، AWS Identity and Access Management (IAM)، و CloudWatch، AWS X-Ray, Amazon Elastic Container Registry (Amazon ECR), AWS CodeBuild، و Amazon S3، AWS Lambda، و AWS CloudFormation.
• توفر نموذج الوكيل في الحساب (الافتراضي us.anthropic.claude-haiku-4-5-20251001-v1:0).
• تمكين CloudWatch Transaction Search، بحيث تصل نطاقات OTEL إلى aws/spans للطبقتين 5–7.
• Node.js 18+ وواجهة سطر أوامر CDK (npm install -g aws-cdk)، بالإضافة إلى Python 3.13+.
• إعداد الحساب والمنطقة (bootstrapping) لـ CDK (cdk bootstrap)، مرة واحدة لكل حساب/منطقة.
• لا حاجة إلى Docker محليًا؛ يتم بناء صورة الوكيل بواسطة CodeBuild (ARM64).

أمر واحد

لنشر الحل، استنسخ المستودع، وأنشئ بيئة افتراضية، وثبّت الاعتماديات، ثم شغّل cdk deploy --all. شغّل الأوامر التالية من جهازك الطرفي:

git clone https://github.com/aws-samples/amazon-bedrock-samples.git
cd rag/managed-knowledge-bases/07-IaaC/managed-kb-observability-cdk/
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cdk bootstrap  # once per account/region
cdk deploy --all

يقوم الأمران الأولان باستنساخ النموذج والانتقال إلى دليل المشروع. ويقوم الأمران التاليان بإنشاء بيئة Python افتراضية وتنشيطها وتثبيت اعتماديات تطبيق CDK. cdk bootstrap يُعدّ الحساب والمنطقة لـ CDK (تحتاج إليه مرة واحدة فقط لكل حساب/منطقة)، بينما cdk deploy --all يوفر الحزم الأربع جميعها.

يتم الحصول على الحساب والمنطقة من ملف تعريف AWS الخاص بك (CDK_DEFAULT_ACCOUNT / CDK_DEFAULT_REGION)، لذلك يتم نشر التطبيق دون أي تعديلات.

توفر المناطق: قاعدة المعرفة المُدارة، والاسترجاع الوكيل (AgenticRetrieveStream)، و Amazon Bedrock AgentCore (Runtime و Gateway) غير متوفرة في كل منطقة AWS. قبل النشر، تأكد من أن جميع هذه الخدمات متاحة في منطقتك المستهدفة، واضبط ACCOUNT_REGION في config.py وفقًا لذلك. الافتراضي هو us-west-2. للاطلاع على التوفر الحالي، راجع وثائق Amazon Bedrock و Amazon Bedrock AgentCore وقائمة خدمات AWS الإقليمية.

لا يوجد سكربت نشر في هذه النسخة، وذلك هو الغرض من الأمر: cdk deploy --all يتنقل في مخطط التبعيات الذي اشتقّه من app.pyوينشر الأربع مكدسات بالترتيب، ويمرر كل قيمة عابرة للمكدسات تلقائيًا. تعرض الوحدة الطرفية كل مكدس أثناء اكتماله: bmkb-obs-cdk-kb [1/4] (وهو PROJECT_NAME الافتراضي)، ثم gateway [2/4]، ثم agent [3/4]، ثم dashboards [4/4]، وهذا الترتيب مُشتق لا معلَن عنه: فهو ينبع من مراجع البنى بين المكدسات، لذا فإن إضافة مكدس خامس يستهلك مخرجًا قائمًا تعيد ترتيب النشر من تلقاء نفسها.

يقوم المكدس -agent ببناء حاوية الوكيل باستخدام CodeBuild، لذا اسمح بنحو 8–10 دقائق لتلك المرحلة. أما المكدسات الثلاثة الأخرى فسريعة. يطبع كل مكدس مخرجاته عند الاكتمال، وهي حيث تحصل على معرفات قاعدة المعرفة، ورابط URL للبوابة، وARN لبيئة التشغيل، وكلتي رابط URL للوحات المعلومات. عند انتهاء النشر تكون المكستات الأربعة قد اكتملت جميعها. تُظهر لقطة الشاشة التالية وحدة تحكم AWS CloudFormation بعد نجاح cdk deploy --all.

الشكل 4: وحدة تحكم AWS CloudFormation بعد نشر ناجح، مع جميع المكدسات الأربعة في حالة CREATE_COMPLETE

في وحدة التحكم، تُظهر المكدسات الأربعة جميعها، kb وgateway وagent وdashboards، الحالة CREATE_COMPLETE، ويعرض كل منها موضعه [n/4] في ترتيب التبعيات المشتق ضمن وصفه.

ملاحظة حول الموارد طويلة الأمد

شيئان في هذا الحل يستغرقان وقتًا أطول بكثير من السقف البالغ 15 دقيقة الذي تسمح به دالة AWS Lambda للاستقصاء البسيط: مزامنة استيعاب KB وبناء صورة CodeBuild. يتعامل إطار AWS CDK Provider مع ذلك باستخدام تقسيم on_event / is_complete حيث يبدأ معالج واحد العمل ويُستقصى معالج ثانٍ حتى يبلّغ عن الانتهاء.

cr.Provider(
    self, "IngestSyncProvider",
    on_event_handler=on_event,        # StartIngestionJob, return the job id
    is_complete_handler=is_complete,  # GetIngestionJob, report IsComplete
    query_interval=Duration.seconds(30),
    total_timeout=Duration.minutes(30),
)

لا شيء يتعطل، وبروتوكول الاستجابة العائد إلى CloudFormation تملؤه المنصة بدلًا من كتابته يدويًا في كل معالج، والميزانية البالغة 30 دقيقة هي خاصية جاهزة وليست شيئًا يتطلب هندسة للالتفاف حوله.

التشغيل والاختبار

افتح notebooks/01-drive-and-observe.ipynb وشغّله من الأعلى إلى الأسفل (pip install -r requirements-notebook.txt أولًا). يقرأ مخرجات المكدسات، ثم يرسل مطالبات خاصة بكل موضوع إلى الوكيل المنشور، جلسة واحدة لكل KBحتى تتمكن من رؤية الإجابات والتوجيه الدلالي معًا في مكان واحد: تُجاب الأسئلة المالية من تقرير Octank 10-K وأسئلة الطقس من تقرير الأعاصير القمعية، ويوجَّه كل منها تلقائيًا إلى أداة AgenticRetrieveStream المطابقة.

يكتشف الدفتر كل شيء من مخرجات المكدسات، فلا شيء يحتاج إلى لصقه يدويًا:

# Stack names are derived from the same PROJECT_NAME the CDK app uses, so renaming the
# project in config.py cannot leave this notebook pointing at stale stacks.
from config import EnvSettings

PROJECT = EnvSettings.PROJECT_NAME
STACKS = {suffix: f'{PROJECT}-{suffix}'
          for suffix in ('kb', 'gateway', 'agent', 'dashboards')}

def outputs(stack_name):
    s = cfn.describe_stacks(StackName=stack_name)['Stacks'][0]
    return {o['OutputKey']: o['OutputValue'] for o in s.get('Outputs', [])}

يستورد الدفتر نفس config.py ما يستورده التطبيق، بحيث لا يمكن للاثنين أن يختلفا أبدًا بشأن أسماء المكدسات.

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

الشكل 5: مطالبات لكل قاعدة معرفة توجَّه إلى قاعدة المعرفة المطابقة، وكل منها تعيد إجابة مدعومة وموثقة بمصادر

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

الشكل 6: إشارات جودة الاسترجاع الخالية من المرجع من الطبقة 3 لكل قاعدة معرفة

لاحظ: لوحات المعلومات ذات الطبقات السبع

لوحتا المعلومات هما المكان الذي تصبح فيه الطبقات السبع مرئية. يقوم الـ stack بإنشاء كلتيهما، ويؤدي توجيه حركة المرور إلى ملئهما. تُظهر لقطة الشاشة التالية لوحتي المعلومات كما تظهران في وحدة تحكم CloudWatch.

الشكل 7: لوحتا المعلومات في وحدة تحكم CloudWatch، المراقبة الوكيلية من طرف إلى طرف ومراقبة كل KB

تظهر لوحتا المعلومات في وحدة تحكم CloudWatch: إحداهما للمراقبة الوكيلية من طرف إلى طرف والأخرى لمراقبة كل KB (BMKB، Bedrock Managed Knowledge Base). يتناول بقية هذا القسم ما تعرضه كل طبقة.

في هذا الإصدار، تُبنى لوحات المعلومات من كائنات مُنمّطة (typed objects) بدلاً من سلسلة JSON. فالمقياس هو Metric، والأداة هي GraphWidget، والتخطيط عبارة عن قائمة من Rows:

cw.GraphWidget(
    title="L4 — Gateway metrics (MCP)",
    width=12, height=6, period=PERIOD, statistic="Sum",
    left=[
        self._gateway_metric("Invocations", gateway_arn, "tools/call Invocations"),
        self._gateway_metric("SystemErrors", gateway_arn, "SystemErrors"),
        self._gateway_metric("UserErrors", gateway_arn, "UserErrors"),
        self._gateway_metric("Throttles", gateway_arn, "Throttles"),
    ],
)

الفائدة العملية ليست أسطراً أقل، dashboards_stack.py حيث يصل إلى 400 سطر، أي أكثر من ما يكافئه DashboardBody بصيغة JSON. بل إن الفائدة هي أن الخاصية المكتوبة بشكل خاطئ أو توليفة أدوات غير صالحة تفشل عند cdk synth، على حاسوبك المحمول، في حوالي ثانية. أما الخطأ نفسه داخل سلسلة DashboardBody فيتم نشره بنجاح ويظهر كأداة معطّلة في AWS Management Console، حيث تكتشه بالنظر إليه.

لأن Row يقبل أي أداة، فإن التوثيق يصبح جزءاً من التخطيط بدلاً من كونه صفحة wiki مندثرة. تتداخل كل لوحة معلومات بين TextWidgets والرسوم البيانية:

[cw.TextWidget(width=24, height=7, markdown=self._l3_explainer())],
[
    self._quality_widget("L3 · Financial KB — agentic quality (reference-free, 0–1)", fin_id),
    self._quality_widget("L3 · Weather KB — agentic quality (reference-free, 0–1)", wx_id),
],

تُرجع _l3_explainer() جدول markdown يعرّف كل نسبة وكيفية قراءتها، بحيث تُشحن الأداة التي تشرح grounded_coverage في نفس الـ commit مع الأداة التي ترسمها بيانياً، ولا يحتاج القارئ الذي يفتح لوحة المعلومات دون خلفية مسبقة إلى تخمين معنى مقياس خالٍ من المرجع.

اللوحة A — المراقبة الوكيلية (من طرف إلى طرف). تفتح اللوحة بشرح لكيفية قياس كل طبقة لشيء مختلف (فعند N استعلامات سترى نحوN استدعاءات وكيل، ونحو 2N عمليات استرجاع، ونحو 3N استدعاءات LLM، ونحو 5N عمليات Gateway MCP، أي حلقة الوكالة مرئية على أرض الواقع)، ثم تعرض مقاييس KB (L1)، ومقاييس Gateway وزمن الاستجابة (L4)، واستخدام الرموز (L6)، ولأن الوكيل يستخدم AgenticRetrieveStream التي تُرجع إجابة مُركّبة ومُوثّقة بالمراجع بدلاً من درجات لكل جزء، تُعرض إشارات الجودة المرجعية للطبقة 3 الخالية من المرجع، والمُعرّفة داخلياً ومرسومة بيانياً لكل KB.

في اللوحة A، تُرسم إشارات الجودة الخالية من المرجع للطبقة 3 لكل قاعدة معرفة على حدة. أولاً، قاعدة المعرفة المالية. يرسم المخطط التالي كلًا من retrieval_utilization وgrounded_coverage وduplicate_rate الخاصة بها.

الشكل 8: جودة الطبقة 3 لقاعدة المعرفة المالية، مع رسم استخدام الاسترجاع والتغطية المُسنَدة ومعدل التكرار

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

الشكل 9: جودة الطبقة 3 لقاعدة المعرفة الجوية، يتم تتبعها بشكل منفصل عن قاعدة المعرفة المالية

يرسم المخططان retrieval_utilization وgrounded_coverage وduplicate_rate لقاعدة المعرفة المالية (يسار) وقاعدة المعرفة الجوية (يمين)، بحيث تظل جودة الاسترجاع لكل قاعدة معرفة قابلة للفصل بدلاً من متوسطتها في رقم واحد.

اللوحة B — مراقبة كل KB (BMKB). الإشارات التشغيلية التي تحدد الإنفاق أيضاً، لكل KB: حجم الفهرس (من بايتات مصدر S3)، وحجم الاسترجاع، واستدعاءات الأدوات الوكيلية، واستخدام رموز الجلسة، واستخدام رموز التوليد حسب النموذج، مع شرح داخلي لكل منها.

تُظهر لقطات الشاشة التالية أدوات المقاييس الأربع في اللوحة B، ممتلئة بعد تشغيل واحد. تُبلغ الأداة الأولى عن حجم الفهرس، المشتق من بايتات مصدر S3، لكل قاعدة معرفة.

الشكل 10: حجم الفهرس في اللوحة B لكل قاعدة معرفة، مشتق من بايتات مصدر Amazon S3

تحصي الأداة الثانية استدعاءات الاسترجاع لكل قاعدة معرفة.

الشكل 11: عدد استدعاءات الاسترجاع (retrieve-call) في لوحة المعلومات B لكل قاعدة معرفية

تُحتسب الأداة الثالثة استدعاءات الأدوات الوكيلية (agentic tool-calls) عبر الـ Gateway. وهذه مشتركة بين قاعدتي المعرفة بدلاً من أن تكون مقسمة.

الشكل 12: عدد الاستدعاءات الوكيلية للأدوات (agentic tool-call) عبر الـ AgentCore Gateway في لوحة المعلومات B، وهي مشتركة بين قاعدتي المعرفة

تُبلّغ الأداة الرابعة عن استهلاك رموز الجلسة (session token usage) لكل قاعدة معرفية.

الشكل 13: استهلاك رموز الجلسة لكل قاعدة معرفية في لوحة المعلومات B

تُظهر الأدوات الأربع حجم الفهرس (من بايتات مصدر S3)، وحجم استدعاءات الاسترجاع، والاستدعاءات الوكيلية للأدوات عبر الـ Gateway، واستهلاك رموز الجلسة. وكل منها مفصّل لكل قاعدة معرفية باستثناء عدد استدعاءات الأدوات عبر الـ Gateway، وهو مشترك بين القاعدتين.

ثمّة تفصيل بُعدي يستحق التنبيه إليه، لأن الـ API المكتوب بالأنواع (typed API) لن يلتقطه عنك: فالـ AWS/Bedrock/KnowledgeBases namespace يتوقع معرّف id مسبوقًا ببادئة، knowledge-base/<id>بينما الـ namespaces الخاصة بالحل نفسه BMKB/* تستخدم المعرّف id المجرد. وكلاهما مجرد سلاسل نصية بالنسبة إلى CDK.

# L1 — AWS/Bedrock/KnowledgeBases wants the prefixed form.
dimensions_map={"Operation": "Retrieve", "KnowledgeBaseId": f"knowledge-base/{kb_id}"}

# BMKB/* — our own namespaces use the bare id.
dimensions_map={"KnowledgeBaseId": kb_id}

الطبقة 5: شجرة الفترات (span tree)

الطبقة 5 هي شجرة فترات OTEL الخام في aws/spans، وهي الطبقة التي تُظهر لك حلقة العمل الوكيلية (agentic loop) مباشرة. ويستحق قراءتها بعناية، لأن التداخل ليس بديهيًا: استدعاء LLM واحد يُنتج ثلاثة فترات (spans). فالـ Strands invoke_agent span يغلّف الدور (turn)، وفترة داخلية chat span تغلّف استدعاء النموذج، وفترة chat <model> span من نوع CLIENT هي الاستدعاء الفعلي، وجميعها الثلاث تكرر نفس gen_ai.usage.* سمات الرموز (token attributes).

تُظهر لقطة الشاشة التالية شجرة الفترات في aws/spans، مع ظهور التداخل ذي الفترات الثلاث في الصفوف العلوية.

الشكل 14: شجرة الفترات في الطبقة 5 في aws/spans، تُظهر تداخل الفترات الثلاث لاستدعاء LLM واحد

قراءة الصفوف الثلاثة العلوية: فترة invoke_agent من Strands Agents تجميعية، ثم فترة chat داخلية، ثم فترة chat من نوع CLIENT، وجميعها تُبلغ عن 7,299 رمز إدخال و268 رمز إخراج بشكل متطابق. ذلك هو استدعاء LLM نفسه وهو يظهر على ثلاثة مستويات من الشجرة، ولهذا السبب يحتاج التجميع إلى عناية.

تكتسب هذه البنية أهميتها لحظة التجميع. ولحساب كل استدعاء LLM مرة واحدة، رشّح إلى CLIENT الورقة (leaf):

fields attributes.gen_ai.request.model as model,
       attributes.gen_ai.usage.input_tokens as in_tok,
       attributes.gen_ai.usage.output_tokens as out_tok
| filter ispresent(in_tok) and kind = 'CLIENT' and name like /^chat /
| stats sum(in_tok) as input_tokens, sum(out_tok) as output_tokens,
        count(*) as llm_calls by model

من دون ذلك التصفية، يُبلغ الاستعلام نفسه عن ثلاثة أضعاف الرموز وثلاثة أضعاف الاستدعاءات.

بتطبيق فلتر CLIENT-leaf، تُظهر لقطة الشاشة التالية استخدام رموز التوليد حسب النموذج مع احتساب كل استدعاء لـ LLM مرة واحدة.

الشكل 15: استخدام رموز التوليد حسب النموذج، مع احتساب كل استدعاء لـ LLM مرة واحدة

مع تفعيل الفلتر، يُظهر التشغيل 14 استدعاءً لـ LLM بإجمالي 60,472 رمز إدخال و2,709 رمز إخراج. بدونه، سيعرض الاستعلام نفسه ثلاثة أضعاف الاستدعاءات وثلاثة أضعاف الرموز.

التقييم: عند الطلب والمستمر

تُقاس الجودة بطريقتين، وكلتاهما مُهيّأتان من قبل التطبيق.

عند الطلب: يستدعي دفتر الملاحظات المشغّل AgentCore لا يوجد نص برمجي للنشر في هذه النسخة، وهذا هو الغرض: (LLM-as-judge) على امتدادات كل جلسة للمقيّمات المدمجة، Correctness وFaithfulness وTool-Selection Accuracy، وينشر الدرجات إلى CloudWatch، حيث تظهر كطبقة Layer 7 على اللوحة A.

تُظهر لقطة الشاشة التالية Layer 7 على اللوحة A: درجات التقييم عند الطلب لكل قاعدة معرفة، مع جدول امتدادات OTEL الخاص بـ Layer 5 على اللوحة نفسها.

الشكل 16: درجات التقييم عند الطلب للطبقة Layer 7 لكل قاعدة معرفة، بجانب جدول الامتدادات للطبقة Layer 5

تُظهر الطبقة Layer 7 درجات التقييم عند الطلب لكل قاعدة معرفة، مع جدول امتدادات OTEL الخاص بالطبقة Layer 5 إلى جانبها، بحيث تُقرأ الدرجات والامتدادات التي أنتجتها معًا على لوحة واحدة.

المستمر (عبر الإنترنت): كما تهيّئ حزمة الوكيل AWS::BedrockAgentCore::OnlineEvaluationConfig التي تأخذ عينات من الجلسات المباشرة وتقيّمها تلقائيًا، دون الحاجة إلى تشغيل دفتر ملاحظات. وتكون الإعدادات نفسها مرئية في وحدة تحكم Bedrock AgentCore تحت Assess ← Evaluations ← Evaluation configurations. تصل النتائج إلى مجموعة السجلات /aws/bedrock-agentcore/evaluations/results/<config-id>، ويُنشر كل درج أيضًا كمقياس CloudWatch في Bedrock-AgentCore/Evaluations مساحة الأسماء، مفتاحًا باسم المقيّم ومعرّف الإعدادات، بحيث يمكنك رسم الدرجات بيانيًا أو إعداد إنذارات عليها دون تحليل السجلات.

تُظهر لقطة الشاشة التالية إعدادات التقييم عبر الإنترنت في وحدة تحكم AgentCore، تحت Assess، ثم Evaluations، ثم Evaluation configurations.

الشكل 17: إعدادات التقييم عبر الإنترنت في وحدة تحكم AgentCore، مع أربعة مقيّمات مدمجة بعيّنة 100 بالمئة

تدرج الإعدادات أربعة مقيّمات مدمجة، وهي Tool-Selection Accuracy وFaithfulness وCorrectness وResponse Relevance، مضبوطة على عيّنة 100 بالمئة وتظهر كـ ACTIVE ومُمكّنة.

ولأن الدرجات مقاييس CloudWatch عادية، تُرسم بيانيًا كأي شيء آخر، دون تحليل سجلات، ويمكن للأداة نفسها أن تحمل إنذارًا. تُظهر لقطة الشاشة التالية درجات المقيّمات الأربعة مرسومة كعناصر مقاييس CloudWatch عادية.

الشكل 18: درجات المقيّمات الأربعة المستمرة مرسومة كعناصر مقاييس CloudWatch عادية

تظهر درجات المقيّمات الأربعة كمقاييس في Bedrock-AgentCore/Evaluations مساحة الأسماء، كل منها مفتاح إلى معرّف إعدادات التقييم واسم خدمة الوكيل، بحيث يمكنك رسمها بيانيًا أو إعداد إنذارات عليها دون تحليل السجلات.

نتائج التقييم عبر الإنترنت لا تصل إلا بعد إغلاق الجلسة. يعمل التقييم على الجلسة المكتملة، لذا تبقى مجموعة سجلات النتائج فارغة لمدة تقارب مهلة خمول الجلسة (حوالي 30 دقيقة) بعد توجيه حركة المرور. والمجموعة الفارغة مباشرة بعد التشغيل أمر متوقع، وليس خطأ في الإعدادات. تحمل كل حدث نتيجة session.id، لذا ترتبط بكل الطبقات الأخرى. أما مسار التقييم عند الطلب في دفتر الملاحظات فلا يتطلب مثل هذا الانتظار، ولهذا السبب كلاهما موجود هنا.

عبر المقيّمات الأربعة المدمجة في هذا التشغيل، سجّل المسار المستمر 1.00 في Correctness وFaithfulness وResponse Relevance وTool-Selection Accuracy، بخمس تتبعات مقيَّمة لكل مقيّم، وكل نتيجة تحمل شرحًا مكتوبًا.

أخذ العينات والتكلفة. يضبط هذا التطبيق SAMPLING_PERCENTAGE = 100 خلال تجربة المدونة فقطلذلك يتم تقييم كل جلسة وتظهر النتائج فورًا. هذه ليست توصية إنتاجية. يستدعي التقييم عبر الإنترنت نموذج LLM-as-judge لكل جلسة تم أخذ عينة منها، لذا تتزايد التكلفة مع معدل أخذ العينات وحجم حركة المرور. بالنسبة لنشر فعلي، اختر نسبة أخذ عينات تناسب احتياجاتك في مراقبة الجودة وميزانيتك، وتأكد من مواءمة الإعداد مع سياسات مؤسستك ومتطلباتها الخاصة بحوكمة التكاليف قبل تمكينه. المعدل هو قيمة ثابتة واحدة، EvalConfig.SAMPLING_PERCENTAGE، في config.py.

تنظيف

عند الانتهاء، قم بإزالة الحل حتى يتوقف عن تكبّد التكاليف، نظرًا لأن بيانات قاعدة المعرفة المخزنة وصورة الوكيل في ECR والتقييم الإلكتروني الذي لا يزال نشطًا تكل المال جميعًا بينما تظل الـ stacks خاملة. أمر واحد يزيل كل شيء:

cdk destroy --all

يحذف CDK الحزم (stacks) بترتيب عكسي للتبعيات من تلقاء نفسه: لوحات المعلومات أولاً، ثم الـ agent، ثم الـ gateway، ثم الـ kb؛ وهي نفس مخطط التبعيات الذي اشتققه لعملية النشر، لكن يُمشى في الاتجاه المعاكس. لا يوجد سكربت تفكيك (teardown) يحتاج إلى إبقائه متوافقًا مع سكربت النشر، وهذه واحدة من الخصائص القيّمة بصورة هادئة لعملية تمثيل التبعيات مرة واحدة فقط.

يستحق سلوكا الإزالة هذان أن تتعرف عليهما، لأن كليهما يحل محل كود التنظيف المكتوب يدويًا:

self.source_bucket = s3.Bucket(
    self, "SourceBucket",
    removal_policy=RemovalPolicy.DESTROY,
    auto_delete_objects=True,  # replaces a list_object_versions delete loop
)

self.repository = ecr.Repository(
    self, "AgentImageRepo",
    removal_policy=RemovalPolicy.DESTROY,
    empty_on_delete=True,  # replaces an image-delete loop
)

كلاهما مضبوط على نظافة العينة، وأي شيء تهتم به، حوّل الدلو إلى RemovalPolicy.RETAIN.

حزمة CDK bootstrap (CDKToolkit) ودلو التجهيز (staging bucket) الخاص بها لا يتم إزالتهما. فهما بنية تحتية مشتركة على مستوى الحساب قد تعتمد عليها تطبيقات CDK أخرى.

ما الذي تغيّر منذ الحل أحادي الجرعة

كلا هذا المنشور و حل 2024 تطبيقات CDK المكتوبة بلغة Python، ويتم نشرها باستخدام cdk deploy. الأداة التأليفية هي الثابت هنا، وما تغيّر هو البنية التحتية تحتها، ومعظم التغيير هو طرح:

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

بنيات CDK التي تقوم بالعمل

أربع بنيات (constructs) تحمل معظم العبء في هذا التطبيق، ومن الجدير ذكرها لأن كل واحدة منها تحل محل شيء كان الناس يكتبونه يدوياً:

• المزوّد – للموارد المخصصة التي تتجاوز السقف البالغ 15 دقيقة لدالة AWS Lambda. و on_event / is_complete يعني هذا التقسيم أنه لا يوجد ما ينام في حلقة استقصاء (poll loop)، وأن بروتوكول الاستجابة العائدة إلى CloudFormation هو مسؤولية الإطار نفسه بدلاً من urllib استدعاء رجعي (callback) مُدرَج في كل معالِج.
• BucketDeployment – يرفع مجموعات البيانات (corpora)، بحيث يكتفي مورد الـ ingestion المخصص بالاستيعاب فقط.
• auto_delete_objects=True و empty_on_delete=True، وتستبدلان حلقات الحذف اليدوية list_object_versions وحلقات حذف الصور التي يحتاجها الـ stack لكي يكون قابلاً للتدمير أصلاً.
• repository.grant_pull_push(project) – سطر واحد للأعمال الثمانية ecr:* التي يحتاجها CodeBuild، ومكتوبة بشكل صحيح بحكم البناء ذاته.

والوحلات المكتوبة بأنواع، من قسم Observe: كائنات Metric / GraphWidget / Row بدلاً من سلسلة JSON لنوع DashboardBody، وهو ما ينقل تركيبة الويدجت غير الصالحة من «تظهر معطوبة في وحدة التحكم» إلى «تفشل عند cdk synth.”

أمران لا يغيّرهما CDK، وكلاهما يستحق المعرفة قبل أن تبدأ:

• JSON الحر يبقى بصيغة camelCase. connector_parameters و parameter_values يُمرَّران كما حرفياً دون تغيير، لذا فإن التحويل من snake_case إلى PascalCase في AWS CDK لا ينطبق داخلهما. المفاتيح مثل bucketName و inclusionPrefixes يجب كتابتها تماماً كما تتوقعها الـ API، ولن يخبرك شيء بخلاف ذلك حتى يفشل المورد.
• القيم ذات النوع النصي تبقى نصوصاً. فرق البُعد بين knowledge-base/<id> والمجردة <id> من قسم Observe هو غير مرئي لنظام الأنواع. التراكيب المكتوبة بأنواع تتحقق من البنيةوليس من الدلالات.

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

الخاتمة

بنينا حلاً كاملاً للاسترجاع الوكيل على مستوى المؤسسات قائماً على Managed Amazon Bedrock Knowledge Base و AgentCore: توجيه دلالي متعدد قواعد المعرفة، ووكيل استدلالي، وسبع طبقات من المراقبة، وتقييم عند الطلب ومستمر، ونشرنا كل ذلك كتطبيق AWS CDK واحد.

هناك أمران يستحقان التذكر. قاعدة المعرفة المُدارة أزالت بنية تحتية بدلاً من إضافتها: لا مخزن متجهات لتوفيره، ولا فهرس لإنشائه وانتظاره، ولا بند OCU يتراكم بينما النظام خامد. وهي أيضاً نوع قاعدة المعرفة الوحيد الذي يدعم الاسترجاع الوكيل وموصل AgentCore Gateway، كما هو موضح في وثائق Amazon Bedrock. ومتى صار الاسترجاع وكيلاً، توقفت المراقبة عن كونها اختيارية. نحو نصف ما يوفره هذا التطبيق موجود للإجابة عمّا فعله الوكيل فعلياً وهل كانت الإجابة جيدة، وهو ما ليس عبئاً إضافياً على نظام وكيل. إنه الجزء الذي يجعله قابلاً للتشغيل.

أثبت نموذج التأليف في CDK جدارته عند الفواصل. سبع قيم تعبر حدود الـ stack في هذه البنية، وكل واحدة منها مرجع تركيب (construct reference) وليست زوج تصدير/استيراد، ولهذا لا يوجد سكربت نشر، ولا سكربت تفكيك، ولا ترتيب ثابت يجب تذكّره.

من هنا يمكنك توجيه مصادر البيانات إلى مجموعاتك الخاصة، أو وضع الوكيل داخل شبكة افتراضية خاصة (VPC)، أو ضبط معدل أخذ عينات التقييم الفوري وفق ميزانيتك وسياساتك، أو إضافة المزيد من قواعد المعرفة إلى الموجّه. لمعرفة المزيد، راجع Amazon Bedrock صفحة التفاصيل و وثائق Amazon Bedrock. التطبيق ودفتر الملاحظات الخاص ببرنامج التشغيل والأدوات المساعدة المستقلة موجودة كلها في مستودع GitHub المرفق، بحيث يمكنك استنساخه ونشر نسختك الخاصة بأمر واحد.

عن المؤلفين