محلي أو مستضاف: اختر حسب القيود التي تؤثر عليك
عادةً ما يبحث الأشخاص عن LangChain مع نموذج محلي عن أحد ثلاثة أشياء: الخصوصية، عدم وجود فواتير لكل رمز، أو الاستقلال عن مورد. يقدم نموذج على جهازك، الذي تديره أدوات مثل Ollama أو llama.cpp، هذه الميزات الثلاث إذا كان لديك عتاد يمكنه تشغيله بسرعة قابلة للاستخدام. المقابل هو وقت الإعداد، حدود الذاكرة وسرعة بطاقة الرسومات أو المعالج التي تمتلكها.
تتبادل نقطة النهاية المستضافة هذه الميزات مقابل تكلفة استخدام صغيرة. ترسل الموجّهات عبر الشبكة، ويعمل النموذج على عتاد شخص آخر. هنا يعني ذلك نموذج مفتوح الأوزان، مضبوط للإجابة بدون رفض المحتوى للاستخدام القانوني للبالغين، مُقدّم عبر واجهة برمجة تطبيقات متوافقة مع OpenAI. لا تُستخدم الموجّهات للتدريب، لكنها تترك جهازك، لذا فإن الخدمة المستضافة هي الخيار الخاطئ إذا كانت قاعدتك أن البيانات يجب ألا تترك جهازك أبداً.
الجزء المفيد لمطوّر LangChain هو أن الكود لا يختلف تقريبًا. خوادم محلية مثل Ollama وllama.cpp تعرض نقاط نهاية على نمط OpenAI، ونقطة النهاية المستضافة تتحدث نفس البروتوكول. إذا كتبت تطبيقك باستخدام ChatOpenAI مع عنوان URL أساسي قابل للتكوين، يمكنك التطوير محليًا والتبديل إلى نموذج مستضاف عبر متغير بيئة. هذا يمنحك هجينًا عمليًا: كرر على نموذج محلي صغير، واستخدم المستضاف عندما تريد سلوك نموذج أكبر دون امتلاك بطاقة GPU.
ربط ChatOpenAI بنقطة النهاية
ثبّت حزمة التكامل، ثم أنشئ كائن النموذج بالإعدادات الثلاث المهمة.
pip install langchain-openai langchain-core
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.llmproxyapi.com/v1",
api_key=os.environ["LLMPROXY_API_KEY"],
temperature=0.7,
)
print(llm.invoke("Give me three names for a fantasy tavern.").content)
إذا نجحت هذه الخطوة، فكل شيء آخر يعمل بنفس الطريقة. احصل على مفتاحك من صفحة مفتاح API؛ يمكن للمستخدمين الجدد الحصول على رصيد تجريبي بقيمة $0.50 بنقرة واحدة هناك بعد إنشاء حساب، دون الحاجة إلى بطاقة. مرر عنوان URL الأساسي صراحةً في الكود بدلاً من الاعتماد على متغير البيئة، لأن إصدارات المكتبات المختلفة تقرأ أسماء متغيرات مختلفة، وقد يؤدي الرجوع الصامت إلى المضيف الافتراضي لـ OpenAI إلى إرسال مفتاحك إلى المكان الخطأ.
اسم النموذج هو المكان الوحيد الذي قد يسبب الارتباك. المعرف الوحيد هنا هو uncensored. لن يتم التعرف على أسماء مثل llama3 أو gpt-4o.
سلسلة مع قالب موجّه
خط الأنابيب القياسي للموجّه والنموذج ومحلل المخرجات يعمل دون تغيير. يوضح هذا المثال تلخيص نص بنبرة مختارة.
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
prompt = ChatPromptTemplate.from_messages([
("system", "You are a writing assistant. Answer in a {tone} tone."),
("human", "Summarize in two sentences:\n\n{text}"),
])
chain = prompt | llm | StrOutputParser()
print(chain.invoke({"tone": "dry", "text": "Long article text goes here..."}))
لإدخالات متعددة، استخدم batch وحدّ التوازي. يسمح المفتاح الكامل بـ 8 طلبات متزامنة و300 طلب في الدقيقة، لذا اجعل الإعداد عند 8 أو أقل:
results = chain.batch(
[{"tone": "dry", "text": t} for t in documents],
config={"max_concurrency": 6},
)
يسمح مفتاح التجربة بطلبين متزامنين فقط و60 في الدقيقة، لذا استخدم max_concurrency بقيمة 2 أثناء الاختبار.
البث المتدفق
تُبث الـ API عبر أحداث الإرسال من الخادم (Server-Sent Events)، وتكشف LangChain عن ذلك عبر stream. استخدمه لواجهات الدردشة حيث يراقب شخص ما تشكل الإجابة.
for chunk in llm.stream("Write a short scene set in a lighthouse."):
print(chunk.content, end="", flush=True)
تفاصيل عملية: يحجز الطلب المتدفق (streamed) شريحة التزامن الخاصة به حتى انتهاء البث. إذا تخلت واجهة المستخدم عن البث في منتصف الطريق، فتأكد من إغلاق المولّد (generator)، وإلا فإن هامش التزامن الخاص بك سينخفض. يستخدم الكود غير المتزامن (async) astream بنفس الطريقة.
الأدوات والوكلاء
استدعاء الأدوات (tool calling) مدعوم: تقبل الـ API tools و tool_choice، وتُبث tool_calls وتأخذ النتائج مرة أخرى كرسائل role: "tool". تغلف LangChain هذا في bind_tools.
from langchain_core.tools import tool
@tool
def dice(sides: int) -> int:
"Roll a die with the given number of sides."
import random
return random.randint(1, sides)
llm_tools = llm.bind_tools([dice])
msg = llm_tools.invoke("Roll a twenty-sided die for the goblin attack.")
print(msg.tool_calls)
تعرض القائمة الاستدعاءات التي يريد النموذج إجراؤها، مع الأسماء والحجج. قم بتشغيلها، وألصق النتائج كرسائل أدوات واستدعِ النموذج مرة أخرى، أو اترك إطار عمل وكيل مثل LangGraph يشغل تلك الحلقة. يقوم الوكلاء بإجراء العديد من الاستدعاءات لكل طلب مستخدم، لذا سيصلون إلى الحد في الدقيقة أسرع من السلاسل البسيطة. احسب الاستدعاءات لكل تشغيل قبل اختيار مستوى التوازي.
نافذة السياق هي 100,000 رمز (token) للموجّه (prompt) بالإضافة إلى الإكمال (completion)، وهو نطاق سخِيّ لذاكرة المحادثة. ومع ذلك، قم بتقليص المحادثات القديمة: فأنت تدفع مقابل السجل الكامل في كل استدعاء بسعر $0.15 لكل مليون رمز إدخال.
إخراج JSON
وضع JSON متاح عبر response_format. في LangChain يمكنك تمريره عبر model_kwargs أو استخدام مساعد المخرجات المهيكلة في وضع JSON، ووصف الحقول في الموجّه الخاص بك.
from pydantic import BaseModel
class Character(BaseModel):
name: str
role: str
secret: str
structured = llm.with_structured_output(Character, method="json_mode")
out = structured.invoke(
"Invent a character for a mystery story. Reply in JSON with keys name, role, secret."
)
print(out)
مع method="json_mode" يجب أن يخبر الموجّه النموذج بالمفاتيح التي يجب إنتاجها؛ ثم تتحقق فئة Pydantic من النتيجة المُحللة. أضف آلية لإعادة المحاولة تحسبًا للردود المشوهة النادرة.
ما لا يتم دعمه
يحتاج عنصران أساسيان في LangChain إلى مصدر مختلف. لا تحتوي هذه الواجهة البرمجية على نقطة نهاية للتضمين، لذا فإن OpenAIEmbeddings الموجهة إلى هنا ستفشل. للاسترجاع عبر مستنداتك، استخدم نموذج تضمين محلي أو مزود تضمين آخر، واستخدم نقطة النهاية هذه فقط لخطوة الدردشة. كما لا يحتوي على إدخال صورة أو توليد، ولا صوت ولا ضبط دقيق، لذا فإن سلاسل الرؤية ومحمّلات الوسائط المتعددة خارج نطاق الخدمة.
يتعلق التعامل مع الأخطاء في الغالب باستجابات 429. تعني القيمة rate_limited أنك تجاوزت الحد الأقصى في الدقيقة، وconcurrency يعني وجود الكثير من الطلبات المتزامنة، بينما تشير استجابة 429 مع Retry-After: 5 إلى زيادة مؤقتة في الحمل. اضبط max_retries على ChatOpenAI ليتمكّن العميل من الانتظار وإعادة المحاولة. الطلبات الفاشلة والمرفوضة لا تُحسب.
تساعد رؤوس الاستجابة في المراقبة: يُظهر X-Balance-USD رصيدك المتبقي ويحدد X-Request-Id استدعاءً للدعم.
التبديل بين المحلي والمستضاف بمتغير واحد
إذا كنت تريد الإعداد الهجين، ضع الإعدادات الثلاث في متغيرات البيئة وابنِ النموذج في دالة واحدة. تستورد سلاسلك هذه الدالة ولا تذكر موردًا أبدًا.
import os
from langchain_openai import ChatOpenAI
def make_llm():
if os.environ.get("LLM_MODE") == "local":
return ChatOpenAI(
model=os.environ["LOCAL_MODEL"],
base_url="http://localhost:11434/v1",
api_key="not-needed",
)
return ChatOpenAI(
model="uncensored",
base_url="https://api.llmproxyapi.com/v1",
api_key=os.environ["LLMPROXY_API_KEY"],
)
يفترض الفرع المحلي وجود خادم Ollama على المنفذ الافتراضي، والذي يكشف عن مسار على طراز OpenAI تحت /v1؛ تحقق من وثائق خادمك الخاص للحصول على العنوان الصحيح واسم النموذج. يختلف السلوك من نموذج إلى آخر، لذا أعد تشغيل الموجّهات الخاصة بك بعد التبديل. قد يتصرف الموجّه الذي تم ضبطه على عادات نموذج معين بشكل مختلف على نموذج آخر، وتختلف جودة استدعاء الأداة مع النموذج، لذا اختبر تلك المسارات أولاً.
سير عمل معقول هو تطوير الموجّهات ضد النموذج المستضاف بينما لا تتوفر لديك بطاقة GPU متاحة، ثم قرر أي أجزاء من التطبيق يجب أن تبقى على جهازك الخاص. يمكن للمستندات الحساسة استخدام الفرع المحلي، ويمكن للميزات الإبداعية الموجهة للجمهور استخدام النسخة المستضافة.
التكلفة والخطوات التالية
التسعير هو $0.15 لكل مليون رمز إدخال و$0.50 لكل مليون رمز إخراج، من رصيد مسبق الدفع بدون اشتراك. تكلفة استدعاء سلسلة يحتوي على 2,000 رمز إدخال و500 رمز إخراج هي 2,000 × $0.15 / 1M + 500 × $0.50 / 1M = $0.0003 + $0.00025 = $0.00055. تكلفة ألف استدعاء من هذا القبيل هي $0.55. تعمل شحنات الرصيد من $20 إلى $500 عبر العملات المشفرة فقط (USDT على TRC20، USDC على Base)، مع مكافأة بنسبة 5% من $50، و10% من $100 و15% من $200. التفاصيل موجودة في صفحة التسعير.
لمشاهدة واجهة برمجة التطبيقات (API) نفسها عبر HTTP عادي، اطّلِع على دليل البدء السريع. كما يتضمن الموقع نظرة عامة موجزة على خدمة الدفع حسب الاستخدام.
