بخش 7.7 · اکوسیستم

ارزیابی با LangSmith

Evaluation with LangSmith

فهرست مطالب
  1. اجزای یک ارزیابی
  2. اجرای evaluate بدون حساب کاربری
  3. ارسال اجراها توسط ایجنت هدف
  4. اجرای evaluate روی یک حساب واقعی
  5. مواردی که upload_results=False همچنان ارسال می‌کند
  6. اجراهای یتیم روی سرور
  7. آفلاین نگه‌داشتن ایجنت هدف
  8. پلاگین pytest
  9. فعال بودن ثبت تست نیازمند LANGSMITH_TRACING است
  10. رفتار پلاگین بدون حساب کاربری
  11. هاب پرامپت در پلن رایگان
  12. مباحث باز

تابع evaluate در langsmith 0.14.17 از روی یک مجموعه داده و ارزیاب‌های شما یک آزمایش می‌سازد، و حتی با upload_results=False هم تمام اجراهای ایجنت را ارسال می‌کند.

پرامپت سیستمِ (system prompt) یک ایجنت را تغییر داده‌اید و می‌خواهید بدانید آیا هنوز به بیست پرسش آزمایشی شما پاسخ می‌دهد یا نه. مستندات، شما را به سمت LangSmith هدایت می‌کنند که نیازمند حساب کاربری و کلید دسترسی است. اما ترجیح می‌دهید ابتدا همین بررسی را روی لپ‌تاپ خودتان اجرا کنید و سپس آن را در قالب یک آزمایش درون حساب کاربری به راه بیندازید.

پس از پایان این بخش، می‌توانید evaluate را همراه با ارزیاب‌های محلی و بدون نیاز به حساب کاربری اجرا کرده و ردیف‌های خروجی آن را بخوانید. همچنین می‌توانید پیش‌بینی کنید که هر یک از حالت‌های evaluate چه مواردی را در حساب کاربری می‌سازد و پلاگین pytest به چه پیش‌نیازهایی وابسته است.

اجزای یک ارزیابی

نمونه (Example): یک ورودی به‌همراه خروجی مرجع آن. یک شیء langsmith.schemas.Example دارای inputs، outputs، شناسه (id) و شناسه‌ی مجموعه داده‌ی مربوط به خود است.

هدف (Target): تابعی که آن را آزمایش می‌کنید. evaluate این تابع را با ورودی‌های هر نمونه فراخوانی کرده و مقادیر بازگردانده‌شده را ثبت می‌کند.

ارزیاب (Evaluator): تابعی که به یک ردیف امتیاز می‌دهد. این تابع دیکشنری‌ای با یک key و یک score برمی‌گرداند.

ارزیاب خلاصه‌ساز (Summary evaluator): تابعی که تمام ردیف‌های یک آزمایش را یک‌جا امتیازدهی می‌کند، مانند محاسبه‌ی دقت کلی (accuracy).

آزمایش (Experiment): یک بار فراخوانی evaluate روی مجموعه‌ای از نمونه‌ها. طبق مستندات، هر بار فراخوانی دقیقاً یک آزمایش ایجاد می‌کند {{docs langsmith/evaluate-llm-application}}.

امضای این تابع به‌صورت evaluate(target, /, data=None, evaluators=None, summary_evaluators=None, ...) است {{code src/langsmith/evaluation/_runner.py}}. پارامتر data می‌تواند نام یک مجموعه داده در LangSmith، فهرستی از نمونه‌ها، یا یک مولد (generator) از نمونه‌ها باشد. مقدار پیش‌فرض max_concurrency برابر 0 است که ردیف‌ها را یکی‌یکی اجرا می‌کند. با num_repetitions می‌توان هر نمونه را بیش از یک بار اجرا کرد. مقدار پیش‌فرض upload_results برابر True است. برای کارهای حجیم، مستندات پیشنهاد می‌کنند از aevaluate با مقدار بالاتری از max_concurrency استفاده شود {{docs langsmith/evaluate-llm-application}}.

یک ارزیاب، آرگومان‌های خود را با نام دریافت می‌کند. نام‌هایی که مجاز به استفاده از آن‌هاست عبارت‌اند از run، example، inputs، outputs، reference_outputs و attachments {{code src/langsmith/evaluation/evaluator.py}}. یک ارزیاب خلاصه‌ساز نیز فهرستی از همین مقادیر را برای تمامی ردیف‌ها دریافت می‌کند.

اجرای evaluate بدون حساب کاربری

با تنظیم upload_results=False، تابع evaluate هیچ آزمایشی در LangSmith نمی‌سازد و هیچ نتیجه‌ای هم نمی‌فرستد. بسته‌ی آموزشی ما آن را با فهرستی از سه نمونه و کلاینت اختصاصی خودش اجرا می‌کند. این کلاینت ویژگی auto_batch_tracing=False دارد و نشستِ (session) HTTP آن تک‌تک درخواست‌ها را ثبت می‌کند. تابع هدف، دو عدد را جمع می‌زند و از روی قصد، هر جا a برابر 4 باشد پاسخ نادرست می‌دهد:

یک تارگت و دو ارزیاب محلی capture/s_integrations.py
    def adder(inputs: dict) -> dict:
        return {"sum": inputs["a"] + inputs["b"] + (1 if inputs["a"] == 4 else 0)}

    def exact(outputs: dict, reference_outputs: dict) -> dict:
        return {"key": "exact", "score": outputs["sum"] == reference_outputs["sum"]}

    def accuracy(outputs: list, reference_outputs: list) -> dict:
        hits = sum(o["sum"] == r["sum"] for o, r in zip(outputs, reference_outputs))
        return {"key": "accuracy", "score": hits / len(outputs)}

تابع evaluate ردیف‌ها را حین پیمایش برمی‌گرداند. هر ردیف شامل نمونه، اجرای هدف و نتیجه‌ی هر ارزیاب است. ردیف دوم ناموفق بود و ارزیاب خلاصه‌ساز به دو مورد از سه مورد امتیاز داد:

سطر ناموفق، خلاصه و درخواست‌ها capture/out/42-langsmith.txt
  {
    "inputs": {
      "a": 4,
      "b": 4
    },
    "outputs": {
      "sum": 9
    },
    "reference": {
      "sum": 8
    },
    "scores": {
      "exact": false
    }
  },
…
summary evaluators:
{
  "accuracy": 0.6666666666666666
}

HTTP requests the client received:
{}

دومین سطر از سه سطر، سپس ارزیاب خلاصه و تعداد درخواست‌ها.

کلاینت بسته‌ی آموزشی هیچ درخواستی دریافت نکرد. evaluate هشدار داد که ویژگی upload_results در فاز بتا قرار دارد. همچنین عبارت Starting evaluation of experiment: %s را همراه با یک نام تصادفی در ادامه‌ی آن چاپ کرد. در کد منبع، رشته‌ی قالب‌بندی و نام به‌عنوان دو آرگومان جداگانه به print داده می‌شوند {{code src/langsmith/evaluation/_runner.py}}. بسته‌ی آموزشی ما این نام تصادفی را پنهان می‌کند.

آن شمارنده‌ی صفر درخواست، متعلق به کلاینت بسته‌ی آموزشی است. وقتی کلاینتی ارسال نکنید، evaluate از کلاینت کش‌شده‌ی پیش‌فرض استفاده می‌کند {{code src/langsmith/evaluation/_runner.py:1084}}. آن کلاینت پیش‌فرض درخواست اختصاصی خودش را می‌فرستد، همان‌طور که اجرای آزمایشگاهی زیر نشان می‌دهد.

ارسال اجراها توسط ایجنت هدف

تابع evaluate هدف را درون tracing_context اجرا می‌کند؛ حالتی که در صورت نادرست بودن upload_results، مقدار enabled آن روی "local" تنظیم می‌شود {{code src/langsmith/evaluation/_runner.py:1945}}. بخش 7.6 نشان می‌دهد که "local" چه اثری روی کد LangChain می‌گذارد: مدیر کال‌بک آن را روشن تلقی کرده و تک‌تک اجراها را ارسال می‌کند. بنابراین، ایجنت هدف حتی با upload_results=False هم اجراهای خود را می‌فرستد. کلاینت بسته‌ی آموزشی هر اجرا را بدون دسته‌بندی (unbatched)، در قالب یک درخواست POST و یک PATCH ارسال می‌کند:

یک تارگت create_agent با upload_results=False و کلاینت کیت capture/out/42-langsmith.txt
HTTP requests the client received:
{
  "PATCH /runs/<run-id>": 7,
  "POST /runs": 7
}

تعداد درخواست‌ها پس از یک سطر از تارگت ایجنت.

ردیف امتیاز false گرفت. مدل Qwen3 4B پاسخ داد 2 + 3 = 5.، و ارزیاب same_answer متن خروجی را با مرجع The sum is 5. مقایسه کرد. تطابق دقیق (exact match) در برابر یک مدل واقعی که پاسخ درستی داده شکست می‌خورد؛ بنابراین یا فقط عدد را امتیازدهی کنید، یا از یک مدل داور (judge) بهره بگیرید.

تصویر این دو هدف را با استفاده از کلاینت بسته‌ی آموزشی کنار هم قرار داده است.

اجرای evaluate با upload_results=False روی دو تارگتبا upload_results=False و کلاینت کیت، یک تابع معمولی هیچ‌چیز ارسال نمی‌کند، در حالی که تارگت create_agent هفت run مربوط به LangChain خود را می‌فرستد.
اجرای evaluate با upload_results=False روی دو تارگت دو ستون، هر کدام یک فراخوانی evaluate، هر دو با upload_results روی False و یک کلاینت ثبت‌کننده. در سمت چپ تارگت یک تابع معمولی است که دو عدد را جمع می‌زند، روی سه مثال، با ارزیاب exact و ارزیاب خلاصه‌ی accuracy. سطرها امتیازهای true، false و true گرفتند، دقت 0.667 شد و کلاینت هیچ درخواستی دریافت نکرد. در سمت راست تارگت یک اجرای create_agent روی Qwen3 4B روی یک مثال است، با ارزیاب same_answer. پاسخ .2 + 3 = 5 با مرجع .The sum is 5 همخوانی نداشت، بنابراین سطر امتیاز false گرفت و کلاینت 7 بار POST /runs و 7 بار PATCH دریافت کرد، زیرا evaluate تارگت را درون tracing_context با enabled تنظیم‌شده روی local اجرا می‌کند. تارگتِ تابع معمولی A CREATE_AGENT TARGET 3 مثال: a + b adder(), one answer wrong on purpose target in tracing_context enabled="local", set by evaluate exact، سپس accuracy true، false، true دقت 0.667 کلاینت 0 درخواست دریافت کرد چیزی از فرایند خارج نشد درخواست‌ها 1 مثال: ?What is 2 + 3 create_agent on Qwen3 4B target in tracing_context enabled="local", set by evaluate same_answer false: 2 + 3 = 5. POST /runs 7, PATCH 7 اجراهای LangChain مربوط به ایجنت درخواست‌ها از کیت، langsmith 0.14.17، همراه با کلاینتی که هر درخواست را ثبت می‌کند.
هر ستون را از مثال‌های بالا تا آنچه کلاینت دریافت کرده بخوانید. کادر صورتی درخواست‌هایی است که تارگت ایجنت ارسال کرده است. کلاینت کیت برای هر run یک POST و یک PATCH می‌فرستد. برگرفته از capture/out/42-langsmith.txt.

ما همین فراخوانی را با کلاینت پیش‌فرض روی ماشین مجازی سرور x86 با ایجنت Qwen3 4B، در برابر یک ثبت‌کننده‌ی محلی سنجیدیم. هیچ کلاینتی پاس ندادیم و متغیر LANGSMITH_TRACING را نیز خالی گذاشتیم. هر حالت در 5 فرایند جدید اجرا شد که هر کدام یک نمونه داشتند. ایجنت 7 اجرای LangChain تولید کرد. تمام فرایندهای یک حالت درخواست‌های یکسانی فرستادند:

هدف متغیرهای محیطی درخواست‌ها در هر یک از 5 فرایند
create_agent LANGSMITH_ENDPOINT متصل به ثبت‌کننده‌ی محلی یک GET /info، سپس سه POST /runs/multipart حامل 7 اجرا و 5 به‌روزرسانی
create_agent داخل tracing_context(enabled=False) مشابه بالا یک GET /info
یک تابع ساده مشابه بالا یک GET /info
create_agent بدون هیچ متغیر LANGSMITH_ یا LANGCHAIN_ همان چهار درخواست، به آدرس api.smith.langchain.com
create_agent داخل tracing_context(enabled=False) بدون متغیر یک GET /info به آدرس api.smith.langchain.com

تمام ردیف‌ها امتیاز true گرفتند. کلاینت پیش‌فرض هیچ درخواست PATCH و هیچ POST /runs تکی ارسال نکرد؛ به‌روزرسانی‌ها در قالب بخش‌های پچ درون درخواست‌های multipart ارسال شدند. در حالتی که متغیر محیطی تنظیم نشده بود، لایه‌ی HTTP فرایند فرزند را جایگزین کردیم تا هیچ درخواستی به هاست پیش‌فرض نرسد:

درخواست‌های یک تارگت ایجنت بدون متغیر محیطی، در یک فرایند capture/lab/summary/evaluate-x86.json
   "requests": [
    [
     "GET https://api.smith.langchain.com/info",
     "POST https://api.smith.langchain.com/runs/multipart",
     "POST https://api.smith.langchain.com/runs/multipart",
     "POST https://api.smith.langchain.com/runs/multipart"
    ],

درخواست GET /info از سوی ترد دسته (batch thread) کلاینت پیش‌فرض ارسال می‌شود که تنظیمات را از اندپوینت استعلام می‌کند {{code src/langsmith/_internal/_background_thread.py:553}}. این درخواست برای تابع ساده هم فرستاده شد؛ بنابراین ربطی به نوع تابع هدف ندارد.

اجراهای ارسال‌شده دو ایراد داشتند. در تمام 10 فرایند ایجنت، اجرای LangGraph دارای شناسه‌ی والد (parent id) بود، اما کلاینت هرگز آن والد را نفرستاد. نام پروژه‌ی ثبت‌شده روی اجراهای ارسالی نیز با نامی که evaluate چاپ کرد فرق داشت. در بخش بعدی می‌بینیم که سرور واقعی با هر دوی این موارد چگونه برخورد می‌کند.

اجرای evaluate روی یک حساب واقعی

ما سه فراخوانی را روی سیستم Mac در برابر API اصلی و با یک حساب جدید در پلن رایگان سنجیدیم. مجموعه داده شامل 10 عمل جمع بود و هدف، یک ایجنت Qwen3 4B قرار گرفت. ارزیاب‌ها شامل exact (یک بررسی کدی) و judge (یک پرامپت پایپ‌شده به ChatOllama و یک پارسر) بودند:

فراخوانی محتویات حساب پس از اجرا اجراهای ایجنت
evaluate همراه با upload_results=True یک آزمایش پیوندخورده به مجموعه داده، 10 ریشه‌ی Target که هر کدام به نمونه‌ی خود اشاره دارند، و 20 ردیف بازخورد 70، ذیل ریشه‌ها
evaluate همراه با upload_results=False بدون هیچ آزمایش، و یک پروژه‌ی جدید با نام خودکار 70، بدون ریشه
aevaluate همراه با upload_results=True و max_concurrency=2 یک آزمایش پیوندخورده به مجموعه داده، 10 ریشه‌ی AsyncTarget، و 20 ردیف بازخورد 70، ذیل ریشه‌ها

هر دو امتیاز در تمام فراخوانی‌ها 10 از 10 بودند. ردیف‌های بازخورد کلیدهای exact و judge را داشتند و نوع منبع آن‌ها model بود. مدل داور روی تمام ردیف‌ها مقدار CORRECT داد و تمام پاسخ‌ها درست بودند؛ بنابراین، این اجرا نشان نمی‌دهد که آیا داور توانایی تشخیص پاسخ اشتباه را هم دارد یا خیر.

دو فراخوانی آپلودکننده، پروژه‌ای به نام evaluators بدون هیچ پیشوندی هم ساختند. این پروژه برای هر فراخوانی ارزیاب، یک اجرای ریشه نگه‌داری می‌کند: 20 مورد برای exact و 20 مورد برای judge. نام این پروژه توسط خود evaluate تعیین می‌شود و نمی‌توان آن را از طریق فراخوانی تنظیم کرد.

مواردی که upload_results=False همچنان ارسال می‌کند

با upload_results=False، کلاینت هیچ POST /sessions نفرستاد؛ در نتیجه آزمایشی ایجاد نشد. با این حال همچنان مجموعه داده را خواند و 31 درخواست multipart post ارسال کرد:

درخواست‌های evaluate با upload_results=False روی API میزبانی‌شده capture/lab/summary/langsmith-account-mac.json
   "requests": {
    "GET /datasets 200": 2,
    "GET /examples 200": 1,
    "GET /info 200": 2,
    "GET /sessions 200": 5,
    "POST /runs/multipart 202": 31
   },

این پست‌ها حامل 70 اجرای ایجنت بودند. سرور آن‌ها را در پروژه‌ای ذخیره کرد که هیچ‌کس نامی برایش نگذاشته بود. علاوه بر این، فراخوانی به یک آزمایش واحد سه نام مختلف داد:

سه نام برای یک فراخوانی evaluate با upload_results=False capture/lab/summary/langsmith-account-mac.json
  "false_names": {
   "experiment_name_returned": "healthy-coast-30",
   "printed": "Starting evaluation of experiment: %s aiefs-lc101-eval-false-3afa8db2",
   "project_with_the_runs": "abandoned-drink-3"
  },
  • نام چاپ‌شده: از پیشوند مشخص‌شده در فراخوانی استفاده کرد، درست پس از عبارت لفظی %s.
  • نام بازگردانده‌شده: در ویژگی experiment_name از نتایج خروجی آمد، اما به هیچ پروژه‌ای در حساب کاربری اشاره نمی‌کند.
  • پروژه‌ی حامل اجراها: نامی تصادفی دارد که سرور به آن اختصاص داده است. این نام پیشوندی ندارد؛ بنابراین جست‌وجو بر اساس پیشوند شما آن را پیدا نخواهد کرد.

ما این نام‌ها و متن چاپ‌شده را ذیل issue شماره‌ی #106 در مخزن langchain-ai/langsmith-python ثبت کردیم. ارسال این اجراها ناشی از حالت "local" است که در بخش 7.6 توضیح داده شده و در #41870 گزارش شده است.

اجراهای یتیم روی سرور

ما محل ذخیره‌سازی اجراهای فراخوانی upload_results=False را سنجیدیم. در تمام 10 ردگیری محاسبات (trace)، اجرای LangGraph شناسه‌ی والد داشت. آن والد همان اجرای Target است که کلاینت هرگز آن را ارسال نکرد:

runهای یتیمِ evaluate با upload_results=False capture/lab/summary/langsmith-account-mac.json
  "false_orphans": {
   "is_root_count": 0,
   "langgraph_runs_with_unsent_parent": 10,
   "project_runs": 70,

تلاش برای خواندن ریشه‌ی ردگیری محاسبات خطای LangSmithNotFoundError داد. گرفتن فهرست پروژه‌ها با فیلتر is_root=True نیز 0 اجرا برگرداند. بنابراین، نمای ریشه‌ی پروژه کاملاً خالی است و این 70 اجرا فقط به‌صورت اجراهای فرزند ظاهر می‌شوند. مدل داور هم اجراهای خودش را با یک والد ارسال‌نشده به پروژه‌ی evaluators فرستاد؛ به‌طوری که آن پروژه به ازای 20 ریشه‌ی داور، میزبان 30 اجرای RunnableSequence است.

نتیجه اینکه upload_results=False مانع از نفوذ اجرای ایجنت به حساب کاربری شما نمی‌شود؛ بلکه فقط این اجراها را در جایی ذخیره می‌کند که نمای ردگیری محاسبات آن‌ها را نشان نمی‌دهد. همان‌طور که در بخش بعد می‌بینید، هر زمان که نباید هیچ اجرایی خارج شود، تابع هدف را درون tracing_context(enabled=False) بپیچید. فراخوانی مدل درون ارزیاب داور را هم به همین صورت بپیچید، چرا که داور هم اجراهای خودش را جداگانه می‌فرستد.

آفلاین نگه‌داشتن ایجنت هدف

برای نگه‌داشتن اجراهای ایجنت هدف درون خود فرایند، باید ردگیری محاسبات (tracing) را در داخل تابع هدف خاموش کنید. بسته‌ی آموزشی ما ایجنت را درون tracing_context(enabled=False) می‌پیچد. پس از آن کلاینت بسته‌ی آموزشی هیچ درخواستی دریافت نکرد و امتیاز ردیف نیز مثل قبل محاسبه شد:

تارگت ایجنت با ردگیری محاسبات خاموش درون آن capture/s_integrations.py
    def quiet_target(inputs: dict) -> dict:
        with tracing_context(enabled=False):
            return agent_target(inputs)

با کلاینت پیش‌فرض و ثبت‌کننده‌ی محلی، همین پوشش مانع از ارسال اجراها شد، ولی درخواست GET /info همچنان در تمام 5 فرایند ارسال گردید. بدون متغیرهای محیطی، این درخواست مستقیماً به api.smith.langchain.com رفت. بنابراین اگر قرار است هیچ درخواستی دستگاه را ترک نکند، فقط این پوشش کافی نیست؛ باید کلاینت اختصاصی خودتان را هم به evaluate بدهید. کلاینتی که auto_batch_tracing=False دارد هیچ ترد دسته‌ای را اجرا نمی‌کند و کلاینت بسته‌ی آموزشی ما برای تابع ساده هیچ درخواستی دریافت نکرد.

پلاگین pytest

کتابخانه‌ی langsmith از طریق نقطه‌ی ورودیِ (entry point) pytest11 یک پلاگین ثبت می‌کند؛ بنابراین هر زمان که هر دو نصب باشند، pytest آن را به‌طور خودکار بارگذاری می‌کند {{code pyproject.toml}}. این پلاگین نشانه‌ی (marker) langsmith را اضافه می‌کند. تستی که با @pytest.mark.langsmith مشخص شود، از طریق تابع test در langsmith.testing._internal اجرا می‌شود؛ یعنی همان تابعی که در پسِ متد عمومی langsmith.test قرار دارد. این تابع ورودی‌ها، خروجی‌ها و بازخوردها را در قالب یک آزمایش درون LangSmith ذخیره می‌کند {{code src/langsmith/pytest_plugin.py}}. درون چنین تستی، توابع log_inputs، log_outputs، log_reference_outputs و log_feedback از ماژول langsmith.testing داده‌ها را به آن رکورد اضافه می‌کنند.

این ثبت داده همیشه فعال است، مگر اینکه مقدار متغیر LANGSMITH_TEST_TRACKING دقیقاً برابر با false باشد {{code src/langsmith/utils.py:143-145}}. با مقدار false، تست نشانه‌گذاری‌شده تابع شما را مستقیماً فراخوانی می‌کند و هر تابع log_* فقط پیامی لاگ کرده و برمی‌گردد {{code src/langsmith/testing/_internal.py}}. صفحه‌ی مربوط به pytest در مستندات نیز همین سوییچ را برای اجرا بدون ارتباط با LangSmith معرفی کرده است {{docs langsmith/pytest}}. گزینه‌ی --langsmith-output برای استفاده از کتابخانه‌ی rich نیازمند بسته‌ی تکمیلی langsmith[pytest] است و در صورت غیرفعال بودن ردگیری، اجرا نخواهد شد {{code src/langsmith/pytest_plugin.py:311-317}}. همچنین کش حاصل از LANGSMITH_TEST_CACHE به بسته‌ی تکمیلی langsmith[vcr] وابسته است.

فایل تست حاوی پنج تست بود: سه تست با نشانه‌ی @pytest.mark.langsmith، یک تست با @langsmith.test و یک تست بدون نشانه که log_outputs را فراخوانی می‌کرد. یکی از تست‌های نشانه‌گذاری‌شده عمداً رد می‌شد و تست دیگری create_agent را با Qwen3 4B روی Ollama اجرا می‌کرد. در بخش هدر خروجی pytest، نام langsmith-0.14.17 به‌عنوان پلاگین درج شده بود، بدون اینکه هیچ فلگی داده باشیم یا خطی در فایل conftest اضافه کرده باشیم.

فعال بودن ثبت تست نیازمند LANGSMITH_TRACING است

ما رفتار این پلاگین را روی سیستم Mac در برابر API اصلی، با pytest 8.4.2 در یک محیط تست ایزوله سنجیدیم. کلید دسترسی همراه با نام مجموعه و نام آزمایش تنظیم شده بود:

  • ثبت تست فعال، LANGSMITH_TRACING خالی. در تمام 3 اجرا، هر پنج تست با خطا مواجه شدند. هر فراخوانی log_* خطای ValueError داد که خواستار یک تست نشانه‌گذاری‌شده و فعال بودن ردگیری محاسبات است. با وجود این، هر اجرا یک آزمایش خالی ایجاد کرد و اجرای اول، مجموعه داده را هم ساخت.
  • حالت قبل همراه با --langsmith-output. جدول خروجی 3 ردیف را نشان داد که تست @langsmith.test در میان آن‌ها نبود. هر ردیف وضعیت failed با ورودی‌های {} داشت و ردیف میانگین‌ها مقدار 0% را نشان می‌داد. اجرای pytest با کد خروج 1 به پایان رسید.
  • ثبت تست فعال و LANGSMITH_TRACING=true. در هر 2 اجرا، سه تست قبول شدند و دو تستی که انتظار می‌رفت رد شدند؛ یعنی همان تستی که عمداً ناموفق نوشته شده بود و فراخوانی log_outputs در تست بدون نشانه.

پیام خطا هر دو شرط را نام می‌برد. کد منبع، فعال بودن ردگیری محاسبات را داخل هر فراخوانی log_* بررسی می‌کند {{code src/langsmith/testing/_internal.py:1166-1168}}:

خطای log_inputs با tracking روشن و ردگیری محاسبات نامشخص capture/lab/summary/langsmith-account-mac.json
  "errors_with_tracing_unset": [
   "ValueError: log_inputs should only be called within a pytest test decorated with @pytest.mark.langsmith, and with tracing enabled (by setting the LANGSMITH_TRACING environment variable to 'true').",

با فعال بودن ردگیری محاسبات، هر اجرا یک آزمایش متشکل از 11 اجرا پدید آورد. چهار مورد آن‌ها ریشه‌های تستی بودند که هر یک به یک نمونه اشاره می‌کردند. 7 اجرای ایجنت نیز ذیل test_marked_agent قرار گرفتند. بازخوردها شامل pass با مقدار 1 برای سه تست و 0 برای تست ناموفق، و دو بار بازخورد exact بودند.

پلاگین متغیر LANGSMITH_PROJECT را کاملاً نادیده گرفت و پروژه‌ای با آن نام وجود ندارد؛ تست‌ها ردگیری‌های خود را مستقیماً درون خود آزمایش ثبت می‌کنند. پس از اجرای این 8 فرایند، حساب کاربری شامل یک مجموعه داده به نام aiefs-lc101-pytest با 3 نمونه و توضیحات Test suite بود. همچنین 8 آزمایش ثبت شد: 2 آزمایش دارای اجرا و 6 آزمایش کاملاً خالی. ما ضرورت فعال بودن ردگیری محاسبات را ذیل issue شماره‌ی #107 در langchain-ai/langsmith-python ثبت کردیم.

رفتار پلاگین بدون حساب کاربری

ما پیش‌تر عملکرد پلاگین را روی ماشین مجازی سرور x86 در برابر یک ثبت‌کننده‌ی محلی و در غیاب متغیرهای محیطی سنجیدیم (3 فرایند به ازای هر حالت):

  • ثبت فعال، بدون هیچ متغیر LANGSMITH_. اجرای ساده‌ی pytest درخواست‌های GET /info و GET /datasets را به api.smith.langchain.com فرستاد. ما ارتباط را قطع کردیم؛ چهار تست ردگیری‌شده با خطای LangSmithConnectionError متوقف شدند و تست بدون نشانه خطای ValueError ناشی از log_outputs را داد.
  • ثبت غیرفعال. با تنظیم LANGSMITH_TEST_TRACKING=false، چهار تست قبول شدند و همان تستی که انتظار می‌رفت مردود شد. چه با LANGSMITH_ENDPOINT و چه بدون آن، هیچ درخواستی خارج نشد. فراخوانی‌های log_* پیام‌ها را در سطح INFO ثبت کردند؛ بنابراین فقط در صورت فعال بودن log_cli در آن سطح دیده می‌شوند.
  • سوییچ --langsmith-output با ثبت غیرفعال. پیش از اجرای هر تستی، pytest با خطای INTERNALERROR و کد خروج 3 متوقف شد. بخش خطاها متن این خطا را آورده است.
  • ثبت غیرفعال و LANGSMITH_TRACING=true. اجراهای LangChain مربوط به تست ایجنت همچنان به اندپوینت ارسال شدند (در قالب سه POST /runs/multipart در هر بار اجرا، در هر 3 مورد). خاموش کردن ثبت تست تنها رکورد تستی را متوقف می‌کند؛ ردگیری محاسبات سوییچ کاملاً جداگانه‌ای دارد.
درخواست‌های یک اجرای pytest با tracking روشن، بدون متغیر محیطی و یک محافظ با پاسخ 200 capture/lab/summary/pytest-plugin-x86.json
   "requests": [
    [
     "GET https://api.smith.langchain.com/datasets",
     "GET https://api.smith.langchain.com/info",
     "GET https://api.smith.langchain.com/sessions",
     "GET https://api.smith.langchain.com/datasets",
     "GET https://api.smith.langchain.com/sessions",
     "GET https://api.smith.langchain.com/datasets",
     "GET https://api.smith.langchain.com/sessions",
     "GET https://api.smith.langchain.com/datasets",
     "GET https://api.smith.langchain.com/sessions"
    ],

اولین فرایند از سه فرایند.

بنابراین محیطی که هم pytest و هم langsmith روی آن نصب باشد، از تمام تست‌های نشانه‌گذاری‌شده درخواست ارسال می‌کند، مگر اینکه این متغیر را مشخصاً تنظیم کنید. آن را داخل محیط اجرای تست‌ها و در کنار LANGSMITH_TRACING تنظیم کنید.

هاب پرامپت در پلن رایگان

مستندات کار با هاب را از طریق پکیج langchain_classic آموزش می‌دهند و ثبت وقایع ما آن را با شناسه‌ی D113 ثبت کرده است. کلاینت خودِ langsmith نیز متدهای اختصاصی push_prompt و pull_prompt را دارد.

ما هاب را یک بار در پلن رایگان روی سیستم Mac سنجیدیم. پرامپتی خصوصی را دو بار با تگ‌های v1 و v2 ارسال (push) کردیم:

  • فراخوانی (Pull): هر بار نسخه‌ی درست دریافت شد. ما پرامپت را بر اساس تگ، 8 کاراکتر اول هش، هش کامل، و آخرین نسخه واکشی کردیم.
  • ارسال (Push) بدون تغییر: خطای LangSmithConflictError داد که ناشی از پاسخ 409 با این جزئیات بود: Nothing to commit: prompt has not changed since latest commit.
  • تگ ناموجود: خطای LangSmithNotFoundError داد که ناشی از پاسخ 404 با جزئیات Commit not found بود.
  • کش کلاینت: دومین فراخوانی با هش کامل هیچ درخواست HTTP تولید نکرد. اما هر بار واکشی بر اساس تگ، هر دفعه 2 درخواست فرستاد.

بنابراین در کدهای محیط عملیاتی (production)، پرامپت را با هش کامل آن ثابت (pin) کنید. تگ صرفاً نامی است که ممکن است تغییر کند و کلاینت هر بار وضعیت آن را از سرور استعلام می‌کند.

مباحث باز

بررسی این اجراها نیازمند کارهایی فراتر از این ویرایش بود و بخش 8.8 آن‌ها را فهرست کرده است:

  • نسخه‌ها و بخش‌بندی‌های (splits) یک مجموعه داده که با نام به evaluate داده می‌شوند.
  • مقایسه‌ی دو آزمایش با یکدیگر، که evaluate آن را زمانی اجرا می‌کند که هدف، یک جفت شناسه‌ی آزمایش باشد.
  • ارزیاب‌های برخط (online evaluators) روی ردگیری‌های محاسبات در محیط عملیاتی، و صف‌های بازبینی انسانی (annotation queues).

منابع: capture/s_integrations.py, capture/out/42-langsmith.txt; capture/lab/summary/langsmith-account-mac.json, capture/lab/T21-langsmith-account-mac/06-e2-true.json, capture/lab/T21-langsmith-account-mac/06-e2-false.json, capture/lab/T21-langsmith-account-mac/06-e2-false-stdout.txt, capture/lab/T21-langsmith-account-mac/06-e2-async.json, capture/lab/T21-langsmith-account-mac/06b-e2-false-where.json, capture/lab/T21-langsmith-account-mac/04-e3-pytest-runs.jsonl, capture/lab/T21-langsmith-account-mac/04-e3-inspect.json, فایل‌های stdout از T21, capture/lab/T21-langsmith-account-mac/05-e4-hub.json, capture/lab/T21-langsmith-account-mac/05b-e4-hub-fullhash.json, capture/lab/T21-langsmith-account-mac/_scripts/t21_e2_eval.py, capture/lab/T21-langsmith-account-mac/_scripts/t21_e3_pytest.py, capture/lab/T21-langsmith-account-mac/_scripts/t21_e4_hub.py, capture/lab/T21-langsmith-account-mac/_scripts/t21_tests/test_ls_plugin.py; capture/lab/summary/evaluate-x86.json, capture/lab/T18-evaluate-leak-x86/01-evaluate-requests.jsonl, capture/lab/T18-evaluate-leak-x86/02-evaluate-noflush.jsonl, capture/lab/T18-evaluate-leak-x86/t18_real.py, capture/lab/T18-evaluate-leak-mac/04-info-origin.txt; capture/lab/summary/pytest-plugin-x86.json, capture/lab/T19-pytest-plugin-x86/01-pytest-runs.jsonl, capture/lab/T19-pytest-plugin-x86/t19_tests/test_ls_plugin.py, فایل‌های stdout از T19; src/langsmith/evaluation/_runner.py, src/langsmith/evaluation/evaluator.py, src/langsmith/_internal/_background_thread.py, src/langsmith/pytest_plugin.py, src/langsmith/testing/_internal.py, src/langsmith/testing/init.py, src/langsmith/utils.py, src/langsmith/client.py, و pyproject.toml در langsmith v0.14.17; libs/core/langchain_core/callbacks/manager.py در langchain==1.5.0; docs.langchain.com در docs commit 04d4d4a (langsmith/evaluate-llm-application, langsmith/pytest, langsmith/usage-and-billing, langsmith/evaluation-concepts); موارد langchain-ai/langsmith-python#106 و #107، و langchain-ai/langchain#41870.

ترجمه‌ی فارسی Evaluation with LangSmith از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما