Trace در LangSmith چیست و چه چیزی در آن ذخیره میشود؟
LangSmith هر درخواست شما را به یک Trace تبدیل میکند: گزارش کامل و سلسلهمراتبی از هر چیزی که در طول آن درخواست اجرا شده است. هر گرهٔ این درخت یک Run است؛ یعنی یک تابع، یک فراخوانی مدل، یک بازیابی سند یا حتی یک prompt نامدار. همین ساختار درختی است که تحلیل را ممکن میکند: میبینید چه چیزی داخل چه چیزی اجرا شد، هر بخش چقدر طول کشید و کجا شکست.
چطور تحلیل Trace را برای APX24 فعال کنیم؟
برای ثبت trace به دو کلید نیاز دارید: کلید LangSmith (از smith.langchain.com) و کلید API اپکس۲۴ (از apx24.ir/account/api-keys). SDK زبان موردنظر را نصب کنید، سه متغیر محیطی را تنظیم کنید و کلاینت OpenAI را با base_url اپکس۲۴ بسازید. از این به بعد هر فراخوانی خودش trace میشود — بدون تغییر در منطق برنامه.
- 1
نصب SDK
در Python یا Node.js:
- 2
تنظیم متغیرهای محیطی
tracing را فعال و مقصد را مشخص کنید:
- 3
ساخت کلاینت اپکس۲۴
کلاینت OpenAI را با base_url اپکس۲۴ بسازید و با wrap_openai بپوشانید تا هر فراخوانی به run نوع llm تبدیل شود.
- 4
اجرای اولین درخواست
یک تابع را با @traceable بپوشانید و اجرا کنید؛ trace در پروژه ظاهر میشود.
آناتومی Trace: کدام فیلدها را باید بخوانیم؟
وقتی اولین trace را در UI باز میکنید با فهرستی از runها روبهرو میشوید. برای اینکه تحلیل سریع شود چند فیلد را باید مثل حروف الفبا بشناسید؛ بقیهٔ فیلدها در صورت نیاز همینها را تکمیل میکنند و در اسکیمای رسمی REST هم همین ساختار برمیگردد.
| فیلد | معنی | کاربرد تحلیلی |
|---|---|---|
| id | شناسهٔ یکتای run | ارجاع دقیق در دیباگ و ثبت feedback |
| trace_id | شناسهٔ مشترک همهٔ runهای یک درخواست | دنبال کردن یک درخواست end-to-end |
| parent_run_id | والد run در درخت | یافتن زمینهٔ اجرای هر گام |
| run_type | نوع گام: chain، llm، tool، retriever، embedding، prompt | فیلتر کردن فقط فراخوانیهای مدل |
| status / error | وضعیت اجرا و متن خطا | ریشهیابی سریع شکستها |
| start_time / end_time | زمان شروع و پایان اجرا | محاسبهٔ latency هر گام و کل trace |
| prompt_tokens / completion_tokens / total_tokens | مصرف توکن | تحلیل هزینه و رفتار prompt |
| first_token_time | زمان دریافت اولین توکن (استریم) | تفکیک زمان واکنش از زمان تولید |
| feedback_stats | خلاصهٔ بازخوردهای ثبتشده | پیوند کیفیت از دید کاربر با trace فنی |
- chain — یک تابع یا زیرشاخهٔ منطقی از برنامه (مثل rag_pipeline).
- llm — فراخوانی مدل زبانی؛ حامل توکن و first_token_time.
- tool — فراخوانی ابزار یا API بیرونی (جستوجو، دیتابیس، ...).
- retriever — بازیابی سند از منبع داده (در RAG).
- embedding — ساخت بردار embedding برای متن.
- prompt — یک prompt نامدار قابلاستفادهٔ مجدد.
همهٔ این runها در یک پروژه (در API: session) ذخیره میشوند؛ فیلد session_id به پروژه اشاره میکند و LANGSMITH_PROJECT همان مقصد است. تفکیک پروژهٔ dev و prod از روز اول، تحلیل را تمیز نگه میدارد و جلوی آلودهشدن آمار production به تستها را میگیرد.
چطور کندترین گام (Latency) را در Trace پیدا کنیم؟
برای یافتن گلوگاه تأخیر دو راه دارید: UI (نمای Waterfall با نوارهای زمانی روی محور مشترک) و SDK/REST برای تحلیل برنامهای. راه دوم وقتی طلایی است که بخواهید روند را در زمان بسازید، آستانهبندی خودکار داشته باشید یا گزارش هفتگی بفرستید.
چطور خطاهای LLM را با SDK و REST API LangSmith دیباگ کنیم؟
خطاها همیشه اول در trace ظاهر میشوند و بعد در تیکتها. LangSmith فیلد status و error هر run را نگه میدارد؛ یعنی بدون دستزدن به سرور، فهرست شکستهای امروز و ورودیهای آنها را میگیرید. برای واکشی تکrun از REST و برای پرسوجوهای گروهی از SDK استفاده کنید.
- فیلتر eq(status, 'error') را بزنید و تعداد و الگوی زمانی خطاها را ببینید.
- عمیقترین run خطادار را باز کنید و فیلد error را کامل بخوانید.
- inputs همان run را بردارید و درخواست را در محیط dev بازتولید کنید.
- مدل و total_tokens را چک کنید: آیا خطا بعد از پاسخ طولانی رخ داده؟
- فیکس را با یک trace جدید در پروژهٔ dev بسنجید و سپس دیپلوی کنید.
تحلیل هزینه: چطور مصرف توکن هر Trace را حساب کنیم؟
بعد از تأخیر و خطا، سؤال سوم همیشه پول است: این trace چقدر خرج داشت؟ LangSmith توکن هر run را نگه میدارد؛ قیمت را شما از جدول اپکس۲۴ میگذارید و فرمول ساده است. اینجا دقیقاً همان جایی است که trace به تصمیم کسبوکار وصل میشود.
تحلیل در سطح پروژه: داشبورد، فیلتر و بازخورد کاربر
تحلیل تک-trace برای دیباگ است؛ برای تصمیم محصول به نمای تجمعی نیاز دارید. داشبورد پروژه در LangSmith روند حجم trace، نرخ خطا، تأخیر و مصرف توکن را در طول زمان نشان میدهد — همان KPIهایی که در استنداپ هفتگی پرسیده میشوند. اگر این اعداد را هفتهای یک بار مرور کنید، رگرسیونها قبل از تیکت کاربر دیده میشوند.
- داشبورد پروژه: روند تعداد trace، نرخ خطا، تأخیر و توکن در زمان (S5).
- فیلترهای ذخیرهشده: مثلاً status=error یا تأخیر بیش از ۵ ثانیه برای مرور سریع.
- مقایسهٔ traceها کنار هم و بازکردن ورودی آنها در Playground برای تست prompt جایگزین.
- Annotation Queue برای مرور انسانی نمونهای از traceها توسط تیم محتوا.
- ثبت feedback روی run برای پیونددادن تجربهٔ کاربر به دادهٔ فنی.
| مورد | ساختار | پرسوجو | توکن و هزینه | همبستگی درخواست | بازخورد کیفیت |
|---|---|---|---|---|---|
| لاگ خام (print/log) | تخت و بدون رابطه | grep دستی | نیازمند پارس دستی | تقریباً ناممکن | ندارد |
| Trace در LangSmith | درخت run با parent/child | فیلتر و API برنامهای | فیلدهای استاندارد | trace_id مشترک | feedback روی run |





