توثيق LangChain للذكاء الاصطناعي الوكيل: الأدوات ووضع JSON
تفترض معظم وثائق LangChain للوكلاء استخدام فئة نموذج خاصة بالمورد نفسه، لكن أي نقطة نهاية متوافقة مع OpenAI تعمل مع ChatOpenAI بمجرد ضبط عنوان URL الأساسي. يربط هذا الدليل LangChain بـ API ويبني وكيلًا يدعم استدعاء الدوال خطوة بخطوة.
تم التحديث
نقاط رئيسية
- استخدم ChatOpenAI مع ضبط base_url إلى هذا الـ API والنموذج إلى
uncensored. - يدعم استدعاء الدوال ووضع JSON، لذا تعمل bind_tools و response_format كما هو موثق.
- حدّ حلقات الوكلاء، وحقّق صحة حجج الأدوات، واحتفظ بـ max_concurrency عند 8 أو أقل باستخدام المفتاح الكامل.
- يُعيد البث عبر SSE بيانات استخدام الرموز في النهاية، مما يساعدك على تتبع تكلفة كل تشغيل للوكيل.

ما تحتاجه قبل البدء
إذا كنت تقرأ وثائق LangChain للذكاء الاصطناعي الوكيل وتتساءل عن التغييرات عند استخدام نموذج غير تابع للمورد المذكور في الأمثلة، فالجواب هو أن التغيير ضئيل جداً. يتألف الوكيل في LangChain من حلقة: يقرأ النموذج المحادثة، ويقرر ما إذا كان يجب استدعاء أداة، ثم يشغّل رمزك الأداة، وتعود النتيجة إلى النموذج حتى ينتج إجابة نهائية. يجب أن تدعم نقطة النهاية للنموذج فقط إكمالات الدردشة مع استدعاء الدوال، وهذه الـ API تدعم ذلك.
تحتاج إلى ثلاثة أشياء: مفتاح API من صفحة المفاتيح، وPython 3.10 أو أحدث، والحزم أدناه. عنوان URL الأساسي هو https://api.unlimitedaiapi.com/v1 ومعرف النموذج هو uncensored. إنه نموذج واحد مفتوح الأوزان تشغله جهة مستقلة، لذا لا توجد قائمة نماذج للاختيار من بينها؛ ويعيد GET /v1/models هذا النموذج لاكتشاف العميل.
pip install -U langchain langchain-openai
export UNLIMITED_API_KEY="your-key-here"الخطوة 1: ربط ChatOpenAI بنقطة النهاية
تأخذ فئة ChatOpenAI الخاصة بـ LangChain base_url مخصصًا. كل شيء آخر يبقى كما هو، بما في ذلك invoke و stream و batch ومتغيرات async.
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0.2,
)
print(llm.invoke("Reply with one short sentence.").content)
إذا طُبعت جملة، فهذا يعني أن المصادقة والتوجيه واسم النموذج جميعها صحيحة. المصادقة هي رأس Authorization: Bearer القياسي، الذي تضيفه الفئة لك. خطأ شائع هو ترك /v1 من عنوان URL الأساسي، مما يؤدي عادةً إلى فشل أول طلب.
الخطوة 2: تعريف الأدوات وربطها
الأدوات هي دوال Python عادية تحتوي على docstring. يصبح الـ docstring والتلميحات النوعية المخطط الذي يراه النموذج، لذا اكتبها كما لو كنت تشرح الدالة لزميل جديد.
import os
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
@tool
def get_order_status(order_id: str) -> str:
'''Look up the status of an order by its ID, for example A100.'''
return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0,
)
llm_with_tools = llm.bind_tools([get_order_status])
ai = llm_with_tools.invoke("Where is order A100?")
print(ai.tool_calls)
تحتوي القائمة المطبوعة على استدعاء بالاسم get_order_status وحجج مثل {"order_id": "A100"}. من الداخل، ترسل LangChain دالتك كعنصر في مصفوفة tools لطلب إكمال الدردشة، وتدعم واجهة برمجة التطبيقات tools و tool_choice و tool_calls المتدفقة. لفرض استدعاء الأداة، مرر tool_choice إلى bind_tools.
لماذا تكون درجة الحرارة منخفضة
تربط الوكلاء عدة استدعاءات للنموذج، لذا يمكن لحجة واحدة غير صحيحة أن تعطل التنفيذ. درجة حرارة 0 إلى 0.2 تجعل اختيار الأداة أكثر قابلية للتكرار. ارفعها فقط لخطوة الإجابة النهائية إذا كنت تريد نثرًا أكثر تنوعًا.
الخطوة 3: تشغيل حلقة الوكيل
كتابة الحلقة بنفسك تأخذ خمسة عشر سطرًا وتوضح بالضبط ما يحدث في كل خطوة، مما يساعد عندما يحدث خطأ. تذهب نتائج الأداة مرة أخرى إلى النموذج ككائنات ToolMessage، والتي تصبح رسائل role: "tool" على السلك.
import os
from langchain_core.messages import HumanMessage, ToolMessage
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
@tool
def get_order_status(order_id: str) -> str:
'''Look up the status of an order by its ID, for example A100.'''
return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0,
)
tools = {"get_order_status": get_order_status}
llm_with_tools = llm.bind_tools(list(tools.values()))
messages = [HumanMessage("Where is order A100, and what about A101?")]
for _ in range(5): # hard cap on loop length
ai = llm_with_tools.invoke(messages)
messages.append(ai)
if not ai.tool_calls:
break
for call in ai.tool_calls:
result = tools[call["name"]].invoke(call["args"])
messages.append(ToolMessage(content=str(result), tool_call_id=call["id"]))
print(ai.content)
لاحظ range(5). يمكن أن يتكرر الوكيل إلى الأبد في حلقة نتيجة أداة محيرة بدون حد خطوة، وكل دورة تكلّف رموز الإدخال للحديث بأكمله حتى الآن. خمسة هو سقف معقول للمهام البسيطة؛ ارفعه عمدًا.
استخدام مساعد الوكيل الجاهز
توفر إصدارات LangChain الحديثة مساعدًا يشغل هذه الحلقة لك. الاسم ومسار الاستيراد تغيرا بين الإصدارات، لذا تأكد منهما مقابل وثائق الإصدار المثبت. في خط 1.x الحالي يبدو هذا:
import os
from langchain.agents import create_agent
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
@tool
def get_order_status(order_id: str) -> str:
'''Look up the status of an order by its ID, for example A100.'''
return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0,
)
agent = create_agent(llm, tools=[get_order_status], system_prompt="You are a concise support assistant.")
result = agent.invoke({"messages": [{"role": "user", "content": "Where is order A100?"}]})
print(result["messages"][-1].content)
استخدم المساعد عندما تريد النمط القياسي، والحلقة المكتوبة يدوياً عندما تحتاج إلى قواعد توقف مخصصة، أو تسجيل لكل خطوة، أو نتائج أدوات تريد تصفيتها قبل أن يراها النموذج.
المخرجات المهيكلة بوضع JSON
غالبًا ما تحتاج الوكلاء إلى تسليم البيانات إلى كود آخر، مثل خطة أو تصنيف أو قائمة بالحقول المستخرجة. يجبر وضع JSON الرد ليكون كائن JSON صالح. في LangChain يمكنك تمريره من خلال bind:
import json
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0,
)
json_llm = llm.bind(response_format={"type": "json_object"})
msg = json_llm.invoke(
"Extract the city and country from: 'I moved to Lyon, France last spring.' "
"Answer as JSON with the keys city and country."
)
print(json.loads(msg.content))
اذكر كلمة JSON في الموجّه ووصف المفاتيح التي تتوقعها، كما في المثال. يضمن وضع JSON البنية، وليس المخطط الخاص بك، لذا لا يزال عليك التحقق من صحة الكائن المفسر (باستخدام Pydantic على سبيل المثال) ومعالجة المفتاح المفقود.
الحدود، البث المتدفق والتكلفة لتشغيل الوكلاء
يجري الوكلاء العديد من الطلبات في وقت قصير، لذا تصبح حدود الحساب أكثر أهمية من روبوت الدردشة البسيط. يسمح المفتاح الكامل بـ 8 طلبات متزامنة و 300 طلب في الدقيقة. يسمح مفتاح التجربة بـ 2 و 60. إذا وزّعت الطلبات باستخدام batch أو شغّلت عدة وكلاء في وقت واحد، قم بتقييد التوازي في التكوين:
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
)
prompts = ["Name one prime number.", "Name one even number.", "Name one square number."]
answers = llm.batch(prompts, config={"max_concurrency": 8})
for a in answers:
print(a.content)
استخدم 2 بدلاً من 8 على مفتاح التجربة. بالنسبة للوكلاء التفاعليين، يعيد llm.stream(...) الرموز عبر SSE كما يتم إنشاؤها، وتصل أرقام الاستخدام في نهاية البث.
من السهل تقدير التكلفة. تشغيل من 5 خطوات يتوسط 4,000 رمز إدخال و 300 رمز إخراج لكل خطوة يستخدم 20,000 رمز إدخال و 1,500 رمز إخراج في المجموع، وهو $0.003 + $0.00075 = $0.00375 لكل تشغيل بسعر $0.15 و $0.50 لكل مليون رمز. يحتوي صفحة الأسعار على المعدلات، ويحتوي المستندات على معاملات الطلب و الرؤوس، بما في ذلك X-Request-Id لتتبع استدعاء فاشل واحد.
تصميم أدوات يمكن للنموذج استخدامها
معظم فشل الوكلاء يعود إلى الأدوات، وليس الحلقة. تساعدك بعض القواعد مع أي نموذج:
- اجعل كل أداة ضيقة. تعمل الأداة المسماة
get_order_statusبشكل أفضل من واحدة مسماةdatabase_queryتأخذ نصًا حرًا. - استخدم أنواع وسائط بسيطة: سلاسل نصية، أعداد صحيحة، وقيم Enum قصيرة. تعطي الكائنات المتداخلة بعمق النموذج طرقًا أكثر للخطأ في أحد الحقول.
- أعد نتائج بسيطة ومباشرة. أداة تفرغ 50000 حرف في المحادثة تملأ نافذة السياق وترفع تكلفة كل خطوة لاحقة.
- أعد الأخطاء كنص، مثل "order_id يجب أن يشبه A100"، بدلاً من رفع الاستثناءات التي تُنهي التنفيذ.
اختبر الوكيل على مجموعة من الموجّهات الحقيقية باستخدام رصيد تجريبي بقيمة $0.50 قبل التوسع. يحصل المستخدمون الجدد عليه بنقرة واحدة في صفحة المفاتيح، وهو صالح لمدة 7 أيام.
أخطاء شائعة يجب التحقق منها أولاً
- لا يظهر استدعاء الأداة أبدًا. اجعل نص التوثيق محددًا، أو خفّض درجة الحرارة، أو افرض الاستدعاء بـ
tool_choice. - حجج غير صالحة. قم بالتحقق من الصحة داخل الأداة وأرجع سلسلة خطأ واضحة، حتى يتمكن النموذج من تصحيح نفسه في الخطوة التالية.
- نمو السياق. نافذة السياق هي 100,000 رمز بما في ذلك الرد. قم بتقليص مخرجات الأداة القديمة قبل أن تملأ النافذة.
المزيد من الأدلة
أسئلة وأجوبة
أي فئة LangChain تتوافق مع هذا الـ API؟
ChatOpenAI من langchain-openai. اضبط base_url إلى https://api.unlimitedaiapi.com/v1 وmodel إلى uncensored ومرر مفتاحك كـ api_key.
هل يدعم API استدعاء الدوال للوكلاء؟
نعم. يقبل معاملات tools وtool_choice، ويعيد tool_calls (حتى عند البث المتدفق)، ويقبل النتائج كرسائل مع role: tool.
هل يمكن لـ LangChain تحليل المخرجات المهيكلة عبر هذا الـ API؟
نعم، من خلال وضع JSON: اضبط response_format إلى نوع json_object. يضمن صحة بناء الجملة JSON، لذا تحقق من الحقول بنفسك.
كم عدد الوكلاء الذين يمكنني تشغيلهم بالتوازي؟
المفتاح الكامل يسمح بـ 8 طلبات متزامنة و300 في الدقيقة. يسمح مفتاح التجربة بـ 2 متزامن و60 في الدقيقة.
مفتاحك على بُعد استمارة واحدة
أنشئ حساباً، وانسخ المفتاح، ثم غيّر URL الأساسي. هذه هي الإعدادات الكاملة.