دليل تكامل Gate.AI مع LangChain و LangGraph

يقدم Gate.AI نقاط نهاية API متوافقة مع OpenAI، يمكن للمطورين من خلالها دمجها مع LangChain و LangGraph لتنفيذ استدعاءات النماذج عبر توجيه Gate.AI. عندما يحتاج تطبيق بايثون إلى استدعاء نماذج مبني على السلاسل، أو تدفقات عمل ذكية تعتمد على الرسوم البيانية، أو يرغب في بناء بوابة نماذج موحدة لا تتطلب إعادة كتابة منطق التطبيق لكل مزود خدمة نموذج، يكون هذا الحل مهمًا جدًا. ستتناول هذه المقالة إعداد البيئة المحلية، اختبار استدعاء LangChain، سلسلة التلميحات في LangChain، وخلق تدفق عمل بسيط باستخدام LangGraph. المحتوى لا يشمل النشر في بيئة الإنتاج، قواعد البيانات الشعاعية، الرصد، تكوين الفواتير، أو سياسات الوصول المؤسسية.

الشروط المسبقة

• تم إنشاء مفتاح API الخاص بـ Gate.AI عبر حساب Gate.AI الخاص بك
• Python 3.10 أو إصدار أعلى، مع صلاحية تثبيت الحزم الاعتمادية

المصدر: وثائق ومنتجات Gate.AI الرسمية، حتى يونيو 2026.

ماذا ستكتسب بعد إتمام هذا الدليل؟

ستتمكن من ربط Gate.AI مع LangChain عبر ChatOpenAI، وإعادة استخدام نفس إعدادات النموذج في تدفقات عمل LangGraph.

سيساعدك هذا الحل على:

• استدعاء Gate.AI من سكربت بايثون محلي
• اختبار إعداد النموذج "auto" الموجه عبر Gate.AI
• استبدال auto بمعرف النموذج المعتمد من Gate.AI عند الحاجة
• تشغيل سلسلة التلميحات في LangChain
• تنفيذ تدفق عمل من خطوتين باستخدام LangGraph

للمزيد من خلفية تكامل API، يرجى مراجعة تكامل API لمطوري Gate.AI.

الخطوة 1: تثبيت حزم الاعتمادية في بايثون

سيتضمن هذا الخطوة تثبيت تكامل OpenAI الخاص بـ LangChain وحزمة LangGraph.

• إنشاء وتفعيل بيئة افتراضية:

  bash python -m venv .venv source .venv/bin/activate

  pip install -U langchain langchain-openai langgraph

• أمر التفعيل في PowerShell على ويندوز:

  powershell .venv\Scripts\Activate.ps1

بعد التثبيت، يجب أن يكون بالإمكان استيراد langchain_openai و langgraph بدون مشاكل.

الخطوة 2: تخزين مفتاح API الخاص بـ Gate.AI

سوف يتم حفظ مفتاح API الخاص بـ Gate.AI خارج الشيفرة المصدرية.

• في بيئة bash، قم بتعيين متغير البيئة:

  bash export GATEAI_API_KEY="YOUR_API_KEY"

• في PowerShell على ويندوز:

  powershell setx GATEAI_API_KEY "YOUR_API_KEY"

بعد استخدام setx، يلزم إعادة تشغيل جلسة PowerShell لتفعيل التغييرات.

لا ترسل المفتاح الحقيقي إلى Git. يُنصح باستخدام مدير المفاتيح، أو إعدادات مفاتيح CI، أو متغيرات بيئة داخلية معتمدة للمشاريع الجماعية.

الخطوة 3: تكوين Gate.AI في LangChain

سوف تنشئ نموذج محادثة في LangChain يرسل طلبات متوافقة مع بروتوكول OpenAI إلى Gate.AI.

• وفقًا لوثائق Gate.AI حتى يونيو 2026، عنوان URL الأساسي المتوافق مع OpenAI هو:

• في LangChain، استخدم هذا العنوان كـ base_url. لا تضف /chat/completions بعده، حيث ستتعامل LangChain مع المسار تلقائيًا.

• مثال:

  python import os from langchain_openai import ChatOpenAI

  llm = ChatOpenAI( model="auto", api_key=os.environ["GATEAI_API_KEY"], base_url="", temperature=0, )

  response = llm.invoke("اكتب جملة واحدة تشرح وظيفة موجه نماذج الذكاء الاصطناعي.") print(response.content)

الناتج المتوقع:

موجه نماذج الذكاء الاصطناعي يوجه الطلبات إلى النموذج المناسب بناءً على المهمة، قواعد التوجيه، أو الإعدادات.

قد يختلف المحتوى الفعلي المسترجع، لأن توجيه Gate.AI يختار النموذج ديناميكيًا استنادًا إلى الاختيار.

الخطوة 4: بناء سلسلة التلميحات في LangChain

سوف تربط بين تلميحات قابلة لإعادة الاستخدام، والنموذج المدعوم من Gate.AI، ومحلل مخرجات النصوص.

• مثال:

  python import os from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser

  llm = ChatOpenAI( model="auto", api_key=os.environ["GATEAI_API_KEY"], base_url="", temperature=0, )

  prompt = ChatPromptTemplate.from_messages( [ ("system", "أنت مساعد تقني مختصر."), ("human", "اشرح {topic} في ثلاث نقاط موجزة."), ] )

  chain = prompt | llm | StrOutputParser()

  result = chain.invoke({"topic": "توجيه API لـ Gate.AI"}) print(result)

ستحصل على شرح موجز يتضمن ثلاث نقاط. إذا حدث خطأ قبل طباعة النص، تحقق من مفتاح API، عنوان URL الأساسي، وتكوين النموذج، قبل تعديل بنية السلسلة مباشرة.

الخطوة 5: تكوين Gate.AI في LangGraph

سوف تستخدم نفس إعداد النموذج من Gate.AI داخل تدفق عمل في LangGraph.

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

• مثال:

  python import os from typing_extensions import TypedDict from langchain_openai import ChatOpenAI from langgraph.graph import StateGraph, START, END

  llm = ChatOpenAI( model="auto", api_key=os.environ["GATEAI_API_KEY"], base_url="", temperature=0, )

  class WorkflowState(TypedDict): topic: str draft: str review: str

  def draft_node(state: WorkflowState) -> dict: response = llm.invoke( [ ("system", "تكتب تفسيرات تقنية قصيرة."), ("human", f"اكتب شرحًا من جملتين عن {state['topic']}."), ] ) return {"draft": response.content}

  def review_node(state: WorkflowState) -> dict: response = llm.invoke( [ ("system", "تراجع الكتابة التقنية من حيث الوضوح."), ("human", f"راجع هذا المسودة واقترح تحسينًا واحدًا:\n\n{state['draft']}"), ] ) return {"review": response.content}

  builder = StateGraph(WorkflowState) builder.add_node("draft", draft_node) builder.add_node("review", review_node)

  builder.add_edge(START, "draft") builder.add_edge("draft", "review") builder.add_edge("review", END)

  app = builder.compile()

  result = app.invoke({"topic": "Gate.AI مع LangGraph"})

  print("المسودة:\n", result["draft"]) print("\nالمراجعة:\n", result["review"])

سترى النص المولد للمسودة وملاحظات المراجعة. إذا كانت التدفقات فقط ترجع المسودة، تأكد من أن الحافة من draft إلى review مهيأة بشكل صحيح.

الخطوة 6: استبدال التوجيه التلقائي بمعرف النموذج المحدد

لتحكم أكثر في سلوك النموذج، يمكن استبدال auto بمعرف نموذج محدد من Gate.AI عند الحاجة:

• إذا قمت بتمكين التوجيه التلقائي من Gate.AI ويدعم حسابك ذلك، يمكنك اختبار باستخدام model="auto"

• إذا كنت بحاجة إلى نتائج قابلة لإعادة الإنتاج، أو تقييم موثوق، أو اختبار زمن استجابة، أو مراجعة إنتاجية، استخدم معرف النموذج من Gate.AI

• مثال:

  python llm = ChatOpenAI( model="YOUR_MODEL_ID", api_key=os.environ["GATEAI_API_KEY"], base_url="", temperature=0, )

يمكنك الحصول على معرف النموذج من دليل نماذج Gate.AI أو من وحدة تحكم Gate.AI. لا تتخيل معرفات نماذج عشوائيًا، حيث أن التوافر يعتمد على حسابك، حالة المنتج، وقواعد مزود الخدمة (حتى يونيو 2026).

ما هي أهم إعدادات التكوين؟

| الإعداد | مثال على القيمة | الاستخدامات | ملاحظات مهمة | | ------------------- | ----------------------------------------------------------- | -------------------------------- | ---------------------------------------------- | | متغير مفتاح API | GATEAI_API_KEY | في shell وبرامج بايثون | لضمان عدم ظهور الاعتمادات في الشيفرة المصدرية | | عنوان URL الأساسي | | ChatOpenAI(base_url=...) | توجيه الطلبات المتوافقة مع OpenAI إلى Gate.AI | | النموذج | auto أو YOUR_MODEL_ID | ChatOpenAI(model=...) | اختيار التوجيه التلقائي أو تحديد النموذج | | درجة الحرارة | 0 | ChatOpenAI(temperature=0) | تقليل تنوع المخرجات في بيئة الاختبار |

للحفاظ على سلوك التوجيه ثابتًا، يُنصح بمشاركة نفس كائن llm بين LangChain و LangGraph. فقط عند التبديل من اختبار التوجيه إلى اختبار النموذج الثابت، قم بتعديل معلمة model.

استكشاف أخطاء تكامل Gate.AI مع LangChain و LangGraph

ملاحظة: إذا استُخدمت رموز الحالة 401، أو خطأ في المفتاح، أو فشل في المصادقة

• السبب: مفتاح API مفقود، منتهي، أو غير صحيح، أو لا يمكن قراءته من الطرفية الحالية
• الحل: نفذ الأمر echo $GATEAI_API_KEY في نفس الطرفية للتحقق من صحة المفتاح، وتأكد من تهيئته في Gate.AI. إذا قمت بتعيينه في جلسة أخرى، أعد تشغيل الطرفية.

ملاحظة: إذا كانت الاستجابة 404 أو فشل الاتصال أو لم يتم العثور على نقطة النهاية

• السبب: خطأ في تكوين عنوان URL الأساسي. العنوان الصحيح هو:
• الحل: تأكد من أن كل كائن ChatOpenAI لديه base_url مضبوط بشكل صحيح.

ملاحظة: إذا ظهرت رسالة ModuleNotFoundError في بايثون

• السبب: لم يتم تثبيت حزم langchain-openai أو langgraph في البيئة الافتراضية الحالية
• الحل: بعد تفعيل البيئة الافتراضية، نفذ:
  pip install -U langchain langchain-openai langgraph

ملاحظة: إذا نجحت المصادقة لكن فشل طلب النموذج

• السبب: النموذج المختار غير متاح، أو مكتوب بشكل خاطئ، أو غير مدعوم حاليًا
• الحل: جرب باستخدام model="auto" أولاً. إذا كنت تريد نموذجًا ثابتًا، انسخ معرف النموذج الصحيح من Gate.AI.

ملاحظة: إذا أعاد تدفق عمل LangGraph حالة غير مكتملة

• السبب: عقدة لم تُرجع المفتاح المتوقع، أو أن بنية الرسم البياني غير مكتملة (مثل عدم وجود حافة من START إلى عقدة معينة أو من عقدة إلى END)
• الحل: تأكد من أن كل عقدة تُرجع قاموسًا يحتوي على المفاتيح الصحيحة، وأن الرسم البياني يتضمن الحواف من START، بين العقد، وEND.

ما الذي يمكنك تكوينه أو بناؤه بعد ذلك؟

• دمج Gate.AI مع API الخاص بالمطورين لتوسيع نطاق تدفقات العمل المحلية إلى نظام Gate.AI الأوسع
• إذا رغبت في دمج Gate.AI في محرر برمجة الذكاء الاصطناعي، راجع دليل تكامل Gate.AI Cursor
• إذا كانت عملية التطوير تتطلب تكامل مع Claude Code أو إعدادات متوافقة مع Anthropic، راجع دليل تكامل Gate.AI مع Claude Code