ما تحتاجه قبل البدء
تتصل LangChain بأي خادم يطبق بروتوكول إكمال المحادثات الخاص بـ OpenAI، لذا لا توجد حاجة لتثبيت تكامل خاص. نقطة البداية الخاصة بك هي نفس الحزمة التي تستخدمها لـ OpenAI نفسها: langchain-openai لـ Python أو @langchain/openai لـ Node. تتغير ثلاث قيم فقط.
- عنوان الواجهة الأساسي:
https://api.deepseekapipricing.com/v1 - النموذج:
uncensored - المفتاح (Key): يُرسل بصيغة
Authorization: Bearer <key>، وهو ما يقوم به العميل نيابةً عنك.
توضيح بشأن التسمية. نقطة النهاية هذه خدمة مستقلة تشغل نموذجًا مفتوح الأوزان مضبوطًا للإجابة بدون رفض المحتوى للاستخدام القانوني للبالغين. إنها ليست واجهة برمجة التطبيقات الرسمية لـ DeepSeek وليست وسيطًا بين موردين، لذا فإن اسم النموذج هو دائمًا uncensored، وليس معرف نموذج من مورد. إذا كنت بحاجة إلى مفتاح، يعرض صفحة مفتاح API خطوات التسجيل وتجربة القيمة $0.50 بنقرة واحدة.
التثبيت وإجراء أول طلب في Python
قم بتثبيت الحزم:
pip install -U langchain-openai langchain-core
# then use base_url https://api.deepseekapipricing.com/v1 and model "uncensored"
ثم أنشئ كائن النموذج. مرر المفتاح صراحةً بدلاً من الاعتماد على متغير البيئة OPENAI_API_KEY، الذي قد يحتوي على مفتاح OpenAI حقيقي لا تريد إرساله إلى مضيف مختلف.
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.deepseekapipricing.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
temperature=0.7,
max_retries=2,
)
print(llm.invoke("Say hello in five words.").content)
إذا طُبعت تحية، فإن الاتصال والمفتاح واسم النموذج جميعها صحيحة. الخطأ الشائع في هذه المرحلة هو نسيان إضافة /v1 إلى عنوان URL الأساسي، مما ينتج عادةً خطأ "غير موجود".
الموجّهات (Prompts) والسلاسل (Chains) والبث المتدفق
من هنا، تعمل LangChain كالمعتاد. يتألف قالب الموجّه، والنموذج، ومحلل المخرجات من سلسلة باستخدام عامل الأنبوب (pipe operator):
# llm = ChatOpenAI(model="uncensored", base_url="https://api.deepseekapipricing.com/v1", ...)
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
prompt = ChatPromptTemplate.from_messages([
("system", "You write tight, vivid scene descriptions for adult fiction."),
("human", "Describe this setting in under 80 words: {setting}"),
])
chain = prompt | llm | StrOutputParser()
print(chain.invoke({"setting": "a flooded subway station at night"}))
يتم البث المتدفق عبر الأحداث المرسلة من الخادم (SSE). في LangChain، تستدعي stream، وتحمل كل قطعة جزءًا من النص. اضبط stream_usage=True على النموذج إذا كنت تريد عدّ الرموز (tokens) في نهاية البث؛ ترسل واجهة برمجة التطبيقات استخدام الرموز في الحدث الأخير.
llm_stream = ChatOpenAI(
model="uncensored",
base_url="https://api.deepseekapipricing.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
stream_usage=True,
)
for chunk in llm_stream.stream("Write a four-line poem about a night train."):
print(chunk.content, end="", flush=True)
يحتفظ الطلب المتدفق بمكانه في الطلبات المتزامنة حتى ينتهي البث، لذا إذا تركت البث دون إغلاقه، سيظل هذا المكان مشغولاً لفترة أطول مما تتوقع.
Node وTypeScript
تأخذ حزمة JavaScript عنوان الأساس داخل كائن configuration:
import { ChatOpenAI } from "@langchain/openai";
const llm = new ChatOpenAI({
model: "uncensored",
apiKey: process.env.UNCENSORED_API_KEY,
configuration: { baseURL: "https://api.deepseekapipricing.com/v1" },
maxRetries: 2,
});
const res = await llm.invoke("Say hello in five words.");
console.log(res.content);
const stream = await llm.stream("Write a four-line poem about a night train.");
for await (const chunk of stream) {
process.stdout.write(chunk.content);
}
شغّله كوحدة ES ("type": "module" في package.json، أو ملف .mjs). يتصرف كل شيء آخر في واجهة برمجة تطبيقات Node، بما في ذلك قوالب الموجّهات (prompt templates) وRunnables، كما هو الحال مع أي نموذج محادثة آخر.
استدعاء الدوال (Tool calling) والوكلاء (Agents)
تدعم واجهة برمجة التطبيقات تنسيق أدوات OpenAI: المعلمة tools وtool_choice، وtool_calls المتدفق، ونتائج الأدوات التي تُعاد كرسائل مع role: "tool". في LangChain، تُعلن عن الأدوات باستخدام زخرفة (decorator) وتلصقها بـ bind_tools:
# llm = ChatOpenAI(model="uncensored", base_url="https://api.deepseekapipricing.com/v1", ...)
from langchain_core.tools import tool
from langchain_core.messages import HumanMessage, ToolMessage
@tool
def order_status(order_id: str) -> str:
"""Return the shipping status of an order."""
return f"Order {order_id} left the warehouse yesterday."
llm_tools = llm.bind_tools([order_status])
messages = [HumanMessage("Where is order 1042?")]
ai = llm_tools.invoke(messages)
messages.append(ai)
for call in ai.tool_calls:
result = order_status.invoke(call["args"])
messages.append(ToolMessage(content=result, tool_call_id=call["id"]))
print(llm_tools.invoke(messages).content)
كتابة الحلقة يدويًا مرة واحدة تستحق عشر دقائق. فهي تظهر لك بالضبط ما الذي أرجعه النموذج، وأي وسائط اختارها لكل استدعاء، وأين يؤدي وصف الأداة السيئ إلى تخمين خاطئ. بمجرد أن يصبح ذلك واضحًا، انتقل إلى وكيل جاهز واستخدم النسخة المكتوبة يدويًا كمرجع لتصحيح الأخطاء.
هذه هي الحلقة كاملةً مكتوبةً يدويًا: يطلب النموذج أداة، وتشغّلها أنت، وتعيد النتيجة، ويكتب النموذج الإجابة النهائية. إذا كنت تفضل حلقة وكيل جاهزة، فإن حزمة langgraph تقدم create_react_agent(llm, [order_status])، وتستدعيها بـ {"messages": [("user", "Where is order 1042?")]}.
تعتمد جودة اختيار النموذج للأدوات على النموذج نفسه، لذا اختبره بمخططات أدواتك الحقيقية. تساعد أوصاف الأدوات القصيرة والمحددة ودرجة حرارة منخفضة. وكيل يقوم بست استدعاءات مع سجل متنامٍ يبلغ إجماليه حوالي 27,000 رمز مدخل و1,800 رمز مخرج يكلف تقريباً $0.00405 بالإضافة إلى $0.0009، أي ما يعادل نصف سنت تقريباً.
المخرجات المهيكلة بوضع JSON
وضع JSON مدعوم عبر response_format. اربطه بالنموذج واذكر أيضًا في الموجّه أنك تريد JSON بمفاتيح محددة، لأن خيار التنسيق يتحكم في البنية وليس المخطط الخاص بك:
# llm = ChatOpenAI(model="uncensored", base_url="https://api.deepseekapipricing.com/v1", ...)
import json
json_llm = llm.bind(response_format={"type": "json_object"})
msg = json_llm.invoke(
"Return a JSON object with keys title (string) and tags (list of 3 strings) "
"for a short story about a lighthouse keeper."
)
data = json.loads(msg.content)
print(data["title"], data["tags"])
تحقق من صحة النتيجة المُحللة باستخدام Pydantic أو فحوصاتك الخاصة قبل الوثوق بها، وتعامل مع json.JSONDecodeError بمحاولة إعادة واحدة. بالنسبة لمهام الاستخراج الكبيرة، قم بتحليل كل استجابة بشكل دفاعي بدلاً من افتراض أن الاستجابة الأولى نظيفة.
الاسترجاع (Retrieval)، الذاكرة (Memory)، والاستدعاءات (Callbacks)
لا تحتوي هذه واجهة برمجة التطبيقات على نقطة نهاية للتمثيل المتجهي (embeddings)، لذا يحتاج خط أنابيب الاسترجاع إلى مصدر منفصل للتمثيل المتجهي. كل شيء بعد الاسترجاع هو محادثة عادية. تسحب سلسلة الاسترجاع النموذجية أفضل المقاطع من متجر المتجهات الخاص بك، وتلصقها في الموجّه، وتطلب من النموذج الإجابة بناءً على ذلك النص. نظرًا لأن نافذة السياق هي 100,000 رمز، يمكنك تخصيص مقاطع سخية، لكن تذكر الفاتورة: كل رمز من سياق الاسترجاع هو مدخل بسعر $0.15 لكل مليون رمز، لذا فإن 20,000 رمز من السياق تكلف $0.003 لكل سؤال.
لذاكرة المحادثة، فإن أبسط نهج هو قائمة رسائل تقوم بتقليصها حسب عدد الرموز قبل كل استدعاء. تقدم LangChain أدوات مساعدة مثل trim_messages لهذا الغرض. احتفظ برسالة النظام وآخر الأدوار، واحذف أو لخص الأدوار الوسطى بمجرد وصول السجل إلى حد تختاره. يؤدي السجل الأصغر أيضاً إلى تركيز الإجابات، ويخفض تكلفة كل دور، لأن السجل بأكمله يُعاد إرساله كمدخل في كل مرة.
تُعد نقاط الاستدعاء (Callbacks) المكان لتسجيل تكلفة الاستدعاء. يتضمن كل رد كتلة usage تحتوي على رموز الموجّه وإكمال النص، وفي LangChain تحمل الرسالة المرتجعة هذه البيانات في usage_metadata:
# llm = ChatOpenAI(model="uncensored", base_url="https://api.deepseekapipricing.com/v1", ...)
msg = llm.invoke("Name three rivers.")
u = msg.usage_metadata
cost = u["input_tokens"] * 0.15 / 1_000_000 + u["output_tokens"] * 0.50 / 1_000_000
print(u, f"${cost:.6f}")
سجّل التكلفة مع معرف الطلب لتتبع الفاتورة المفاجئة إلى سلسلة واحدة.
موجّهات النظام والنبرة
لا يحتوي النموذج على رفضات مدمجة للمحتوى، لذا فإن رسالة النظام هي المكان الذي تضبط فيه سلوك منتجك: الشخصية، والنبرة، والمواضيع التي يجب تجنبها، وتنسيق الرد. اكتبها كما لو كنت تكتب ملخصاً لزميل جديد. يعمل النص القصير والمحدد بشكل أفضل من النص الطويل والغامض. يعد المحتوى الذي يتضمن قاصرين قيداً صارماً على هذه الخدمة، لذا لا تبني موجّهات تقترب من ذلك.
قائمة مراجعة قصيرة قبل النشر
- يعيش المفتاح في متغير بيئة أو متجر أسرار، وليس في المستودع.
- يُضبط
max_concurrencyعلى حد المفتاح الخاص بك، أو أقل منه إذا كانت خدمات أخرى تشارك المفتاح. - تستخدم عمليات إعادة المحاولة تراجع (back-off) قصير، ويتم احترام استجابات 429 مع
Retry-After: 5. - تُغلق التدفقات عند انقطاع اتصال العميل لتحرير الخانات.
- يتم تحليل مخرجات JSON بشكل دفاعي والتحقق من صحتها.
- يتم تسجيل التكاليف لكل سلسلة من كتلة usage.
- يوجد حل بديل للحالة التي تكون فيها نقطة النهاية غير متاحة، حتى لو كان الحل البديل رسالة خطأ.
اتبع تلك القائمة وستتصرف التكامل مثل أي نموذج دردشة آخر في LangChain. الفرق هو من جانب المحتوى، حيث تتم الإجابة عن الطلبات التي ترفضها النماذج الأخرى للاستخدام البالغ القانوني.
حدود المعدل، والطلبات المتزامنة، والأخطاء الشائعة
يسمح المفتاح الكامل بـ 8 طلبات متزامنة و300 طلب في الدقيقة. يسمح مفتاح التجربة بـ 2 طلب متزامن و60 طلب في الدقيقة. يمكن أن يصل جسم الطلب إلى 8 ميجابايت، ونافذة السياق هي 100,000 رمز تغطي الموجّه وإكمال النص معاً.
توزع أدوات الدُفعات في LangChain الطلبات، لذا اضبط سقفًا يتطابق مع مفتاحك:
# llm = ChatOpenAI(model="uncensored", base_url="https://api.deepseekapipricing.com/v1", ...)
inputs = [{"setting": s} for s in ["a rooftop garden", "a desert diner", "a quiet harbor"]]
results = chain.batch(inputs, config={"max_concurrency": 8})
استخدم 2 بدلاً من 8 على مفتاح تجريبي. عند تجاوزك لحد، تُعيد واجهة برمجة التطبيقات استجابة HTTP 429 مع رمز الخطأ rate_limited (طلبات كثيرة جداً في الدقيقة) أو concurrency (طلبات كثيرة جداً في آن واحد). في حالة الحمل الزائد المؤقت، تُعيد أيضاً 429، مع رأس Retry-After: 5. يتعامل إعداد max_retries في العميل مع الحالات العابرة، ولكن إذا رأيت رمز الخطأ concurrency بشكل متكرر، فقلل من max_concurrency بدلاً من إضافة عمليات إعادة محاولة.
- أخطاء "غير موجود" في كل استدعاء: تحقق من أن عنوان URL الأساسي ينتهي بـ
/v1. - خطأ المصادقة: المفتاح مفقود أو يحتوي على خطأ مطبعي؛ تأكد من تمريره عبر
api_key. - أخطاء النموذج: يجب أن يكون اسم النموذج بالضبط
uncensored. - تشغيل الدُفعات ببطء: تحتجز التدفقات العالقة خانات الطلب المتزامن، لذا أغلقها أو اضبط مهلة زمنية.
التسعير هو $0.15 لكل مليون رمز مدخل و$0.50 لكل مليون رمز مخرج، ولا يتم احتساب الطلبات الفاشلة أو المرفوضة. تُدرج صفحة التسعير عمليات الشحن، وتغطي الوثائق كل معلمة ورؤوس الاستجابة، بما في ذلك X-Request-Id وX-Balance-USD، وهي مفيدة لتسجيلها في استدعاء LangChain.
