دیتاست در LangSmith چیست و از کجا میآید؟
در LangSmith، دیتاست (Dataset) مجموعهای نامدار از مثالها (Example) است و هر مثال، یک جفت ورودی و خروجی مرجع بههمراه metadata اختیاری. دیتاست خودش هیچ منطقی اجرا نمیکند؛ نقشش شبیه ورقهٔ امتحان است: سؤالها ثابتاند تا هر بار که مدل یا پرامپت عوض شد، همه را روی همان سؤالها بسنجید. تفاوت مهمش با trace این است که trace ثبتِ «چه اتفاقی افتاد» است، اما example بیان میکند «جواب درست چه بوده» — و همین تفاوت، ارزیابی را ممکن میکند.
- دستی و کنترلشده: نوشتن لیست inputs/outputs با create_examples — بهترین نقطهٔ شروع برای دیتاست طلایی کوچک.
- از traceهای تولید: فیلتر کردن رانها با list_runs و تبدیل آنها به example — موتور رشد مداوم دیتاست.
- از فایل CSV: آپلود دادهٔ موجود با upload_csv و تعیین ستونهای ورودی/خروجی — برای تیمهایی که اکسل و گزارش دارند.
- از DataFrame پانداس: متد upload_dataframe در SDK پایتون برای دادهٔ parquet/CSV پردازششده [S1].
| روش | ابزار | بهترین زمان استفاده | خروجی مرجع |
|---|---|---|---|
| لیست دستی | create_examples با examples=[...] | راهاندازی دیتاست طلایی کوچک (۱۰-۵۰ مورد) | تأیید انسانی، از روز اول |
| از trace تولید | list_runs + create_examples | رشد مداوم با موارد واقعی و مرزی | نیاز به بازبینی/اصلاح اپراتور |
| آپلود CSV | upload_csv با input_keys/output_keys | مهاجرت دادهٔ موجود (اکسل، تیکتها) | ستون پاسخ درست در همان فایل |
| DataFrame | upload_dataframe (پایتون) | دادهٔ پردازششده در pandas | ستون پاسخ درست پردازششده |
Add real traces to a dataset so a failure you saw once becomes a test you run every time.
— مستندات رسمی LangSmith — بخش Evaluation
چطور با SDK پایتون و جاوااسکریپت دیتاست بسازیم؟
- 1
نصب و احراز هویت
SDK را نصب کنید و کلید LangSmith را در متغیر محیطی بگذارید؛ Client() خودش آن را میخواند.
- 2
ساخت دیتاست
با create_dataset یک دیتاست با نام و توضیح مشخص بسازید؛ نام، کلید جستجوی شما در همهٔ متدهای بعدی است.
- 3
افزودن مثالها بهصورت bulk
لیست exampleها را در یک درخواست با create_examples اضافه کنید؛ به هر example میتوانید metadata بدهید تا بعداً فیلتر کنید.
همین کار با REST API چطور انجام میشود؟
هر کاری که SDK میکند، پشت صحنه یک درخواست REST به api.smith.langchain.com است. دیدن این لایه برای دو موقعیت حیاتی است: وقتی SDK برای زبان شما نیست (مثلاً Go یا PHP) و وقتی میخواهید داخل pipeline بکاند خودتان — بدون وابستگی به پکیج — دیتاست بسازید. طبق مشخصات رسمی OpenAPI، احراز هویت با هدر X-Api-Key یا Authorization: Bearer انجام میشود و ساخت دیتاست دو فیلد الزامی دارد: name و data_type [S2].
یک بخش کوچک اما کلیدی از REST که SDK آن را برایتان مدیریت میکند، نسخهبندی دیتاست است: endpointهای GET /api/v1/datasets/{dataset_id}/versions و GET /api/v1/datasets/{dataset_id}/version با پارامتر as_of یا tag، وضعیت دیتاست را در یک نقطهٔ زمانی خاص برمیگردانند [S2]. این یعنی میتوانید بعداً ثابت کنید امتیاز v1 دقیقاً روی کدام نسخهٔ دیتاست گرفته شده — اصل حیاتی برای مقایسهٔ منصفانهٔ دو پرامپت یا دو مدل.
چطور از لاگهای تولید، دیتاست پالایششده بسازیم؟
اینجا جایی است که «پالایش» از «ساخت» جدا میشود. در traceهای پروژهٔ LangSmith شما هر چیزی هست: سؤالهای بیربط کاربران، پاسخهای نصفه، و آن موارد مرزی که فقط یکبار دیدهاید و در ذهنتان حک شدهاند. استراتژی درست، شکار همان موارد سخت است؛ طبق مستندات رسمی، افزودن traceهای خراب به دیتاست یعنی تبدیل یک حادثه به یک تست دائمی [S4]. مثالهای واقعیِ خطادار، دیتاست شما را از یک نمایشگاه صرفاً موفقها به ابزار واقعی رگرسیون تبدیل میکنند.
- 1
فیلتر رانها با پارامترهای list_runs
فقط رانهای ریشه را بگیرید؛ ران ریشه کل مکالمه را دارد و inputs/outputs نهایی را دربر میگیرد.
- 2
انتخاب موارد ارزشمند
اوّلاً خروجیهای خالی را حذف کنید؛ بعد معیار پالایش خودتان را اعمال کنید: پاسخ خیلی کوتاه، حضور عبارت «نمیدانم»، یا طول توکنی غیرعادی.
- 3
تصحیح انسانی خروجی مرجع
خروجی مرجع را از پاسخ مدل کپی نکنید؛ پاسخ درست را بنویسید یا با صف برچسبگذاری (Annotation Queue) تأیید کنید.
- 4
برچسبگذاری و افزودن bulk
منبع و دستهٔ هر مثال را در metadata ثبت و همه را یکجا اضافه کنید.
- 5
قفل کردن نسخهٔ دیتاست
بعد از هر بار پالایش، تاریخ/تگ نسخه را ثبت کنید تا مقایسههای بعدی قابلدفاع باشند.
چقدر مثال کافی است و کیفیت دیتاست را چطور نگه داریم؟
- حذف تکراریها: قبل از افزودن، ورودیهای یکسان را با یک دیکشنری یا hash فیلتر کنید.
- توازن دستهها: با metadata مثل category مطمئن شوید هر دستهٔ مهم سهمی دارد، نه فقط دستهٔ پرتکرار.
- پاسخ مرجع تأییدشده: هر example جدید باید فیلد metadata reviewed=yes بگیرد؛ بدون بازبینی انسانی وارد دیتاست طلایی نشوید.
- جدا کردن train/test: با پارامتر split در update_example، دیتاست را بشکنید و evaluate را فقط روی split تست اجرا کنید.
- مرور دورهای: هر ماه exampleهای کهنه یا بیربط را حذف/بهروزرسانی کنید تا دیتاست با محصول بماند.
| معیار | پرسش کنترلی | کنش در صورت رد |
|---|---|---|
| واقعی بودن | این ورودی از تعامل واقعی کاربر آمده یا ساختگی است؟ | بهعنوان sandbox جدا نگه دارید، داخل دیتاست طلایی نریزید. |
| پاسخ مرجع درست | پاسخ مرجع را انسان تأیید کرده؟ | به Annotation Queue بروید تا تصحیح شود. |
| تنوع دسته | حداقل ۲ example مشابه از این دسته داریم؟ | یا تکمثال را حذف کنید یا دستهٔ جدید بسازید. |
| پاکسازی داده | دادهٔ شخصی ماسک شده؟ | ماسک کنید؛ سپس اضافه. |
| برچسبگذاری | منبع و دسته در metadata هست؟ | برچسب بزنید؛ example بیبرچسب بعداً پیدا نمیشود. |
چطور دیتاست پالایششده را روی مدلهای APX24 اجرا کنیم؟
دیتاست فقط وقتی ارزش دارد که بهطور دورهای روی مدل واقعی اجرا شود. چون API اپکس۲۴ سازگار با OpenAI است، کافی است در کلاینت OpenAI فقط base_url را به https://api.apx24.ir/v1 و کلید را به sk-apx-... تغییر دهید؛ هیچ چیز دیگری در کد عوض نمیشود و LangSmith هم بهعنوان لایهٔ ارزیابی، از این فراخوانیها بیخبر نمیماند. همین سازگاری است که مهاجرت بین مدلها را به یک تغییر یکخطی تبدیل میکند.
رایجترین خطاها را چطور رفع کنیم؟
در کار روزمره با LangSmith، بیشتر تیکتهای تیمها به دو خانواده برمیگردد: احراز هویت (۴۰۱) و تعارض نام (۴۰۹). هر دو ریشه در فرایند دارند نه در ابزار — کلیدهایی که بین محیطها کپی میشوند و نامهایی که بدون قاعدهٔ نامگذاری انتخاب میشوند. الگوهای زیر را یکبار پیاده کنید تا این دو دسته خطا برای همیشه از گزارش تیم حذف شوند.
مسیر تمرین و قدم بعدی شما
چیزی که ساختید یک اسکریپت یکباره نیست؛ یک حلقهٔ بازخورد است: trace تولید فیلتر میشود، موارد ارزشمند با برچسب و پاسخ مرجع انسانی به دیتاست میپیوندند، evaluate هر تغییر پرامپت یا مدل را میسنجد و خرابیهای experiment بعدی، سوخت دور بعدی پالایش میشوند. تیمهایی که این حلقه را دو هفته اجرا میکنند، معمولاً اولین تصمیم «تعویض مدل» خود را بهجای بحث جلسهای، با یک جدول امتیاز انجام میدهند.
- تمرین P1: دیتاست ۵ مثالهٔ FAQ بسازید و metadata دستهبندی را رعایت کنید.
- تمرین P2: از traceهای خطادار پروژهٔ خودتان دیتاست رگرسیون بسازید.
- تمرین P3: evaluator داوری با Claude Sonnet 5 بنویسید و روی مدل GPT-6 Luna اجرا کنید.
- قدم بعدی: job شبانهٔ پالایش را به CI بچسبانید و گزارش امتیاز را به کانال تیم بفرستید.





