أصبح بناء وكلاء LangGraph من أشيع الطرق لتنسيق النماذج اللغوية الكبيرة (LLM) بلغة Python: تصف خطوات الاستدلال في شكل رسم بياني، مع حالة مشتركة وحلقات واستدعاءات أدوات. وفي ثنائي LangChain/LangGraph توفر LangChain اللبنات الأساسية (النماذج والمطالبات والأدوات والتكاملات) وتتولى LangGraph التنسيق. والمشروعان من أكثر المشاريع متابعةً على GitHub في منظومة وكلاء الذكاء الاصطناعي.
تبدأ المشكلة عند الانتقال إلى الإنتاج. الوكيل ليس دالة تعيد إجابة: إنه سلسلة قرارات واستدعاءات للنموذج واستدعاءات للأدوات يتغير عددها من تنفيذ إلى آخر. وحين تكون الإجابة خاطئة أو بطيئة أو مكلفة، يجب أن تعرف أي خطوة هي المسؤولة. وبدون تتبعات لا تملك إلا التخمين.
في هذا المقال نبني وكيلًا صغيرًا بـ LangGraph موصولًا بنموذج محلي، ثم نتتبعه بـ OpenTelemetry لنرى كل عقدة وكل استدعاء للنموذج وكل استهلاك للرموز (tokens) في واجهة خلفية مثل Dynatrace.
LangChain/LangGraph: من يفعل ماذا؟
- LangChain توحّد الوصول إلى نماذج المحادثة (OpenAI وAnthropic وMistral وOllama وخوادم متوافقة مع OpenAI…) وإلى الأدوات والمستندات وقواعد البيانات المتجهية. وتُنشر التكاملات في حزم منفصلة مثل
langchain-openaiأوlangchain-ollama. - LangGraph تنمذج التطبيق كرسم بياني للحالات: عقد (دوال) تقرأ حالة مكتوبة الأنواع وتعدّلها، وحواف، شرطية أحيانًا، تقرر الخطوة التالية. وتتولى أيضًا حفظ الحالة، والإيقاف لانتظار موافقة بشرية، وبثّ الخطوات.
توجد دوال جاهزة تنشئ وكيلًا من نوع ReAct (يختار النموذج أداة ويلاحظ النتيجة ويعيد المحاولة) في سطر واحد. وقد تغيّر اسمها ووحدتها بين الإصدارات: ارجع إلى الوثائق الرسمية لـ LangChain وLangGraph. ويبقى الرسم البياني الصريح، الذي نستخدمه هنا، أوضح وسيلة لفهم ما يجري.
عمليًا: وكيل LangGraph على نموذج محلي
الخطوة 1: ثبّت الحزم
python3 -m venv .venv && source .venv/bin/activate
pip install langgraph langchain-openai
نستخدم العميل المتوافق مع OpenAI لنتمكن من استهداف Ollama أو vLLM أو llama.cpp دون تمييز. وبالنسبة إلى Ollama يصف دليلنا Ollama محليًا تثبيته؛ وتُقدَّم واجهته المتوافقة مع OpenAI تحت /v1.
الخطوة 2: صِف الحالة والعقد
يتلقى الوكيل عَرَض حادثة، ويضع خطة تشخيص، ثم يكتب إجابة قصيرة:
from typing import TypedDict
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, START, END
llm = ChatOpenAI(model="llama3.2",
base_url="http://localhost:11434/v1",
api_key="non-utilise")
class Etat(TypedDict):
symptome: str
plan: str
reponse: str
def planifier(etat: Etat) -> dict:
msg = llm.invoke(f"Liste 3 vérifications pour : {etat['symptome']}")
return {"plan": msg.content}
def repondre(etat: Etat) -> dict:
msg = llm.invoke(f"Symptôme : {etat['symptome']}\n"
f"Plan : {etat['plan']}\nRésume en 5 lignes.")
return {"reponse": msg.content}
الخطوة 3: اجمع الرسم البياني ونفّذه
graphe = StateGraph(Etat)
graphe.add_node("planifier", planifier)
graphe.add_node("repondre", repondre)
graphe.add_edge(START, "planifier")
graphe.add_edge("planifier", "repondre")
graphe.add_edge("repondre", END)
agent = graphe.compile()
for etape in agent.stream({"symptome": "latence p95 en hausse sur le service paiement"},
stream_mode="updates"):
print(etape)
يعرض الوضع updates تحديث الحالة الناتج عن كل عقدة. وهذا أول شكل من قابلية الملاحظة، مفيد أثناء التطوير لكنه محصور في الطرفية.
الخطوة 4: أضف أدوات
الوكيل الحقيقي يستدعي أدوات: استعلام واجهة مراقبة، أو قراءة دليل تشغيل (runbook)، أو بحث في قاعدة وثائق. تربط الأدوات بالنموذج وتضيف حافة شرطية تعيد الدوران ما دام النموذج يطلب أداة. وهذه الحلقة بالذات هي ما يجعل السلوك غير متوقع، ومن ثمّ هي ما يجب تتبعه. ويمكن أن تأتي الأدوات أيضًا من خوادم MCP، كما يشرح مقال مراقبة وكلاء MCP باستخدام OpenTelemetry.
كيف تتتبع وكلاء LangGraph بـ OpenTelemetry؟
توجد عائلتان من الحلول. LangSmith، منصة الجهة الناشرة لـ LangChain، تُفعَّل بمتغيرات بيئة وتقدم عرضًا مفصلًا جدًا؛ وهي خدمة تجارية، مع عرض مستضاف ذاتيًا مخصص لبعض الباقات. والبديل المفتوح هو OpenTelemetry الذي يرسل التتبعات إلى الواجهة الخلفية التي تختارها.
أداة القياس OpenLLMetry لـ LangChain
ينشر مشروع OpenLLMetry أداة قياس OpenTelemetry لـ LangChain، تغطي LangGraph أيضًا لأن الأخيرة تعتمد على نظام الاستدعاءات الراجعة (callbacks) في LangChain. فيصبح كل تنفيذ للرسم البياني تتبعًا، وكل عقدة span فرعية، وكل استدعاء للنموذج span تحمل النموذج والرموز الداخلة والخارجة والمدة.
pip install opentelemetry-sdk opentelemetry-exporter-otlp \
opentelemetry-instrumentation-langchain
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.langchain import LangchainInstrumentor
provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)
LangchainInstrumentor().instrument()
# ... puis construire et invoquer le graphe comme plus haut
تجمع الحزمة traceloop-sdk من المشروع نفسه هذا الإعداد في استدعاء تهيئة واحد. تحقق من أسماء الحزم والأصناف في مستودع OpenLLMetry؛ ونقارن هذا النهج مع Langfuse في Langfuse وOpenLLMetry.
أضف السياق التجاري
تقول الـ spans التلقائية ما يفعله الوكيل لا لصالح من. أضف سمات على الـ span الحالية: معرّف المحادثة والفريق ونوع الطلب. وتجنب وضع النص الكامل للمطالبات (prompts) فيها إن كانت تحتوي بيانات شخصية؛ وتقترح بعض أدوات القياس خيارًا لتعطيل التقاط المحتوى.
عرض خطوات الوكيل في Dynatrace
يُضبط مصدّر OTLP بالمتغيرات القياسية (OTEL_EXPORTER_OTLP_ENDPOINT وOTEL_EXPORTER_OTLP_HEADERS وOTEL_SERVICE_NAME)، إما نحو OpenTelemetry Collector وإما مباشرة نحو نقطة OTLP في Dynatrace برمز API مميّز مرخّص له باستيعاب التتبعات. وفي عرض التتبعات الموزّعة يظهر تنفيذ الوكيل كشجرة: عقدة planifier واستدعاء للنموذج ثم عقدة repondre واستدعاء جديد. ويمكن فورًا تحديد الخطوة الأبطأ، أو حلقة أدوات خرجت عن السيطرة، أو استدعاء يستهلك رموزًا كثيرة.
ومن هذه الـ spans تُشتق مؤشرات: عدد الخطوات في كل تنفيذ، والرموز في كل تنفيذ، ومعدل أخطاء الأدوات، والزمن من طرف إلى طرف. وإذا كان خادم النماذج متتبَّعًا بدوره فإن نشر سياق W3C يمدّ التتبع حتى الاستدلال، وفق مبادئ مقالنا OpenTelemetry من طرف إلى طرف.
أفضل الممارسات
- ضع حدًا لعدد تكرارات الرسم البياني لتفادي الحلقات اللانهائية والفواتير المفاجئة.
- سمِّ العقد أسماء صريحة: فهي التي ستظهر في التتبعات.
- ثبّت إصدارات
langchainوlanggraphوأدوات القياس، فهي تتطور بسرعة. - تتبّع منذ التطوير: مقارنة التتبعات قبل تغيير المطالبة وبعده مفيدة جدًا.
- أخفِ التقاط محتوى المطالبات أو عطّله حين يكون حساسًا.
الأسئلة الشائعة
هل تلزم LangChain لاستخدام LangGraph؟
تستطيع LangGraph تنسيق أي شيفرة Python، لكنها تتكامل طبيعيًا مع نماذج LangChain وأدواتها، وعادةً ما تُثبَّتان معًا.
هل LangSmith إلزامي لتتبع وكيل؟
لا. أداة قياس OpenTelemetry مثل أداة OpenLLMetry ترسل التتبعات إلى أي واجهة خلفية متوافقة مع OTLP.
هل يمكن استخدام نموذج محلي مع LangGraph؟
نعم، عبر تكامل Ollama أو عميل متوافق مع OpenAI موجَّه إلى Ollama أو vLLM أو llama.cpp.
الخلاصة
تجعل LangGraph الوكلاء صريحين، ويجعلهم OpenTelemetry قابلين للملاحظة. وبالجمع بينهما يتحول سلوك مبهم إلى شجرة خطوات قابلة للقياس، يمكن متابعتها والتنبيه عليها في Dynatrace مثل أي خدمة. ولاختيار بقية الحزمة راجع مقارنتنا لحزم الذكاء الاصطناعي المفتوحة المصدر المستضافة ذاتيًا.
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC ولا للمشاريع المذكورة. العلامات التجارية المذكورة ملك لأصحابها. الأدوات تتطور بسرعة، لذا تحقق دائمًا من الأوامر والخيارات في وثائقها الرسمية.