کالبک در لنگچین چیست و چه مشکلی را حل میکند؟
کالبک یعنی «به من خبر بده وقتی اتفاقی افتاد». لنگچین در طول اجرای یک run — از فراخوانی مدل تا اجرای ابزار — در نقاط مشخص رویداد منتشر میکند و هر تابعی که برای آن رویداد ثبت شده باشد اجرا میشود. این توابع در یک کلاس به نام «هندلر کالبک» (Callback Handler) جمع میشوند: شما کلاس را مینویسید و لنگچین در لحظهٔ درست، متد درست را صدا میزند. نکتهٔ کلیدی این است که شما اجرای زنجیره را کنترل نمیکنید؛ فقط ناظر رویدادهایش هستید و همین، کالبک را به ابزاری کمریسک برای اضافهکردن observability تبدیل میکند.
نقشهٔ کامل رویدادها: کدام متد کِی صدا زده میشود؟
کلاس BaseCallbackHandler در پایتون حدود ۱۸ متد رویداد دارد و در جاوااسکریپت همان رویدادها با نام handle* میآیند. لازم نیست همه را بازتعریف کنید؛ متدهایی که بازتعریف نکنید، پیادهسازی پیشفرض خالی کلاس پایه را به ارث میبرند و عملاً کاری نمیکنند. همین «اختیاری بودن» است که هندلرهای مینیمال را ممکن میسازد. [S1][S3]
| خانواده | متدهای اصلی | کِی رخ میدهد |
|---|---|---|
| مدل گفتگو | on_chat_model_start، on_llm_new_token، on_llm_end | اجرای ChatOpenAI و کلاسهای مشابه؛ از شروع فراخوانی تا پایان پاسخ |
| زنجیره / Runnable | on_chain_start، on_chain_end | شروع و پایان هر گام LCEL؛ حتی prompt و parser هر کدام یک run جدید دارند |
| ابزار (Tool) | on_tool_start، on_tool_end | اجرای هر tool داخل ایجنت |
| بازیاب (Retriever) | on_retriever_start، on_retriever_end | جستجو در vector store در سناریوهای RAG |
| خطاها | on_llm_error، on_chain_error، on_tool_error، on_retriever_error | بهجای نسخهٔ end، هر گاه استثنایی رخ دهد |
| متنی و ایجنت | on_text، on_agent_action، on_agent_finish، on_retry | خروجی متنی جانبی، چرخهٔ ایجنت و تلاش مجدد |
یک تلهٔ ظریف اما پرتکرار: در مدلهای گفتگو (Chat Models)، رویداد شروع on_chat_model_start است نه on_llm_start. اگر هر دو را در هندلر بنویسید، هنگام کار با ChatOpenAI معمولاً فقط نسخهٔ chat اجرا میشود؛ on_llm_start برای LLMهای متنی کلاسیک است. برای شمارش هزینه و لاگ، به on_llm_end تکیه کنید که در هر دو حالت مشترک است. [S1]
- raise_error: اگر True باشد، استثنای داخل هندلر اجرای زنجیره را میشکند؛ پیشفرض False است و خطای هندلر بیصدا نادیده گرفته میشود — دلیل رایج «گم شدن» لاگها.
- ignore_llm / ignore_chat_model / ignore_chain / ignore_tool / ignore_retriever: با True کردن هر فلگ، آن خانوادهٔ رویداد برای این هندلر خاموش میشود.
- run_inline: با True، هندلر همزمان با جریان اصلی اجرا میشود؛ مفید برای تست، اما در production اجرای پسزمینهای بهتر است.
چطور لنگچین را به اپکس۲۴ وصل کنم و اولین هندلر را بنویسم؟
- 1
نصب بستهها
لنگچین هسته + ادپتور OpenAI که با هر endpoint سازگار با OpenAI کار میکند.
- 2
گرفتن کلید API
از پنل اپکس۲۴ کلید با قالب sk-apx-... بگیرید و در متغیر محیطی ذخیره کنید.
- 3
اجرای اولین invoke با هندلر
هندلر را با config به invoke بدهید تا رویدادها ثبت شوند؛ کد کامل در بلاک بعدی.
کالبک را کجا وصل کنم: سازندهٔ شیء یا درخواست؟
لنگچین دو نقطهٔ اتصال هندلر دارد و انتخاب بین آنها مشخص میکند کدام رویدادها را میبینید. کالبکِ سازنده (constructor) فقط برای فراخوانیهای همان شیء فعال است؛ اگر هندلر را به سازندهٔ مدل بدهید، رویدادهای زنجیرهٔ والد را نخواهید دید. کالبکِ درخواست (request) با config به invoke/with_config داده میشود و به تمام زیرفراخوانیهای همان run منتقل میشود: زنجیره، مدل، پارسر و هر ابزار داخلش. [S4]
کالبکهای سازنده برای همهٔ فراخوانیهای همان شیء به کار میروند و کالبکهای request به همان درخواست و تمام زیردرخواستهایش منتقل میشوند.
— بلاگ رسمی LangChain — Callbacks Improvements (برگردان آزاد تحریریه)
چطور هزینهٔ هر درخواست را با کالبک محاسبه کنم؟
پایش هزینه ترکیب دو داده است: مصرف توکن از رویداد on_llm_end و قیمت هر ۱M توکن از جدول رسمی اپکس۲۴. تصور رایج این است که محاسبهٔ هزینه به ابزار جداگانه نیاز دارد؛ در عمل یک هندلر بیستخطی کافی است که در پایان هر فراخوانی، هزینهٔ همان درخواست را به تومان گزارش کند. این همان الگویی است که تیمهای مالی برای «بودجه به ازای هر مشتری» استفاده میکنند.
استریم توکنها: on_llm_new_token چطور کار میکند؟
طبیعیترین راه استریم در لنگچین، رویداد on_llm_new_token است: با رسیدن هر تکه از پاسخ، این متد صدا زده میشود و شما توکن را به UI، WebSocket یا لاگ میفرستید. شرط فعالشدن آن یک چیز است: پاسخ باید streaming باشد؛ یعنی از llm.stream() در لنگچین استفاده کنید یا در درخواست خام stream=True بدهید. با invoke معمولی، این رویداد هرگز اجرا نمیشود.
در جاوااسکریپت و TypeScript چه تفاوتی دارد؟
معماری کالبک در جاوااسکریپت یکسان است اما سه تفاوت جزئی دارد: کلاس پایه از @langchain/core/callbacks ایمپورت میشود، نام متدها با پیشوند handle میآید (handleLLMEnd بهجای on_llm_end) و هر هندلر باید پراپرتی name داشته باشد. فیلد usage هم در llmOutput.tokenUsage با کلیدهای camelCase میآید. اگر Next.js یا Node کار میکنید، همین الگو را مستقیم روی اپ خود بگذارید. [S3]
یک تفاوت رفتاری هم بدانید: در نسخهٔ JS، رویدادهای استریم به handleLLMNewToken(token, idx, runId, ...) میآیند و ترتیب پارامترها متفاوت است؛ اگر از ایندکس توکن استفاده میکنید، امضا را دقیق چک کنید. برای مهاجرت پروژههای Node به endpoint اپکس۲۴، فقط configuration.baseURL و کلید عوض میشود — بقیهٔ کد بیلمس میماند.
هندلرم صدا زده نمیشود یا خطاها گم میشوند؛ چرا؟
نکتهٔ ظریف دربارهٔ run_id: در امضای کامل متدها، run_id پارامتر keyword-only است و در پارامترهای اضافی (**kwargs) هم قابلخواندن؛ برای گروهبندی لاگها (مثلاً فیلد trace_id در لاگر) از همان مقدار استفاده کنید تا همهٔ رویدادهای یک درخواست کاربر، کنار هم بنشینند.
کاربردهای واقعی: از چتبات استریم تا مانیتورینگ هزینه
اگر روزی خواستید tracing حرفهای داشته باشید — درخت کامل اجرا، ورودی/خروجی هر گام و تأخیر هر جزء — LangSmith دقیقاً همین رویدادها را به سرور ردیابی میفرستد. یعنی مهاجرت به آن فقط «افزودن یک هندلر آماده» است، نه بازنویسی اپ؛ و اگر فردا ابزار دیگری ترجیح دادید، چون داده از کالبک میآید، جای ابزار بهراحتی عوض میشود. [S4]




