فراخوانیهای مدل و ابزارها را با اسپنهای OpenTelemetry اختصاصی خودتان ردگیری کنید، توکنها را مستقیماً از گزارش مصرف ارائهدهنده بشمارید و مطمئن شوید تا وقتی فلگ LangSmith فعال نباشد، هیچ دادهای به آن ارسال نمیشود.
مشتری میگوید دستیار در ساعت 10:42 کند بوده و اشتباه جواب داده است. برای بررسی موضوع، به فراخوانیهای مدل در آن اجرا، تعداد توکنهایشان، ابزاری که زمانش تمام شده (Timed out) و خطوط لاگ نیاز دارید؛ همگی با یک شناسهی مشترک. دادههایتان نباید از شبکهی داخلی خارج شوند، پس استفاده از سرویسهای ردگیری محاسبات (Tracing) میزبانیشده منتفی است.
با پایان این بخش، میتوانید سه نوع اسپن (Span) به ایجنت اضافه کنید و آنها را به لاگهایتان پیوند بزنید. همچنین میفهمید کدام فراخوانیهای مدل از دید این اسپنها جا میمانند و اثبات میکنید که هیچ ردگیری محاسباتی به LangSmith ارسال نمیشود.
سه نوع اسپن
اسپن: یک عملیات زماندار با یک نام، مجموعهای از مشخصهها (Attributes)، یک وضعیت (Status) و یک والد. سرویس ما سه نوع اسپن میسازد: agent.run که کل یک اجرا را در وظیفهی (Task) اجرایی بخش 9.1 میپوشاند؛ و یک میانافزار (Middleware) که دور هر فراخوانی مدل یک اسپن model.call و دور هر تلاش برای اجرای ابزار یک اسپن tool.<name> ایجاد میکند.
class Tracing(AgentMiddleware):
async def awrap_model_call(self, request, handler):
with tracer.start_as_current_span("model.call") as span:
span.set_attribute("gen_ai.request.model", model_id(request.model))
span.set_attribute("gen_ai.request.message_count", len(request.messages))
response = await handler(request)
message = response.result[-1]
usage = message.usage_metadata or {}
span.set_attribute("gen_ai.response.model", message.response_metadata.get("model_name", ""))
span.set_attribute("gen_ai.usage.input_tokens", usage.get("input_tokens", 0))
span.set_attribute("gen_ai.usage.output_tokens", usage.get("output_tokens", 0))
span.set_attribute("gen_ai.response.tool_calls", len(message.tool_calls))
return responseنام مشخصهها از قراردادهای OpenTelemetry برای هوش مصنوعی زایشی پیروی میکند. تعداد توکنها هم دقیقاً همان مقادیر ارائهدهنده است. برای Ollama، این مقادیر prompt_eval_count و eval_count هستند که توکنایزر خود مدل میشمارد. برای Anthropic، همان فیلد usage در پاسخ دریافتی است.
اندازهگیری کردیم که آیا وقتی پرامپت از قبل در حافظهی موقت (Cache) باشد، Ollama روی مک باز هم طول کل پرامپت را گزارش میکند یا نه. سه فراخوانی یکسان به Qwen3 4B هر کدام مقدار prompt_eval_count را 65 اعلام کردند. ارزیابی پرامپت بار اول 1401.9 میلیثانیه طول کشید (که شامل بارگذاری مدل هم میشد)، و در دفعات بعد به 68.6 و 28.7 میلیثانیه رسید. بنابراین این عدد همان طول پرامپت است و برخورد با کش (Cache hit) اثرش را فقط در زمان پاسخ نشان میدهد.
خروجیگیر (Exporter)، هر اسپن را در قالب یک خط JSON در فایل مینویسد. میتوان بدون دست زدن به میانافزار، یک گردآورنده (Collector) یا هر خروجیگیر OTLP دیگری را جایگزین آن کرد.
{"name": "model.call", "context": {"trace_id": "0xc31ff4d300b6481cedfbf16e6295dbf5", "span_id": "0x2d0efd6deeee8df4", "trace_state": "[]"}, "kind": "SpanKind.INTERNAL", "parent_id": "0x37bcefff7e3ac78d", "start_time": "2026-11-15T10:28:39.576564Z", "end_time": "2026-11-15T10:28:42.578468Z", "status": {"status_code": "UNSET"}, "attributes": {"gen_ai.request.model": "qwen3:14b", "gen_ai.request.message_count": 1, "gen_ai.response.model": "qwen3:14b", "gen_ai.usage.input_tokens": 454, "gen_ai.usage.output_tokens": 22, "gen_ai.response.tool_calls": 1}, "events": [], "links": [], "resource": {"attributes": {"telemetry.sdk.language": "python", "telemetry.sdk.name": "opentelemetry", "telemetry.sdk.version": "1.45.2", "service.instance.id": "a07d9619-8c5e-4163-a075-4db5bf1372bf", "service.name": "support-assistant"}, "schema_url": ""}}اولین اسپن model.call فایل، در یک سطر.
داخل اسپنها چه بود؟
اسپنهای اولین اجرای آزمونهای Qwen3 14B روی مک را اندازهگیری کردیم. فایل خروجی شامل 234 اسپن بود: 34 اسپن agent.run، 65 اسپن model.call، 36 اسپن ابزار و 99 اسپن درخواست HTTP. والد همهی 65 اسپن model.call، یک اسپن agent.run بود. هفت اسپن وضعیت ERROR داشتند که هرکدام دقیقاً با یکی از خطاهای تزریقشده در آزمون همخوان بود: یک خطا در search_faq، سه خطای تایماوت در read_order، یکی در create_ticket و دو خطا در فراخوانیهای مدل اصلی.
فریمورک FastAPI نسخهی 0.162.7 نیز از طریق Tracer Provider سراسری، برای هر درخواست اسپن مخصوص خودش را میسازد. سرویس ما اسپنهای عملیاتی داخلی آن را با تنظیم telemetry={"operation_spans": False} غیرفعال میکند، اما اسپنهای درخواست باقی میمانند. این اسپنها به کار میآیند؛ زیرا یک درخواست کندِ POST /threads/{thread_id}/runs و اسپن agent.run مربوط به آن، شناسهی ردگیری (Trace ID) یکسانی دارند.
فراخوانیهایی که از دید اسپنها جا میمانند
میانافزار SummarizationMiddleware مدل را از طریق هوک اختصاصی خودش فراخوانی میکند، یعنی خارج از awrap_model_call. بنابراین هیچ اسپن model.call دور آن تشکیل نمیشود {{code libs/langchain_v1/langchain/agents/middleware/summarization.py:520-557}}، و در نتیجه گزارش هزینهای که صرفاً از روی اسپنها ساخته شود، آن را جا میاندازد.
سرویس ما علاوه بر این، همهی فراخوانیهای مدل را از طریق یک Callback در LangChain لاگ میکند؛ همراه با میزان مصرف اعلامی ارائهدهنده و نام اسپنی که در آن لحظه فعال بوده است. 20 ارزیابی Claude Haiku 5.5 را به همین شیوه و در مقایسه با مصرف ثبتشدهی Anthropic در دفترکل هزینهها اندازهگیری کردیم. در دفترکل، 64 فراخوانی و 76,076 توکن ورودی ثبت شده بود؛ لاگ کالبک هم دقیقاً همین 64 فراخوانی و همین مجموع را نشان داد. اگر سناریوی قطعی سرویس را کنار بگذاریم که فراخوانیهایش به مدل پشتیبان هدایت شدند، اسپنهای model.call در مجموع 60,354 توکن از این مقدار را در خود داشتند.
15,722 توکن باقیمانده از دو جا ناشی میشد: خلاصهساز (Summarizer) در رشتهپیام 6 نوبته (Turn) و در چرخهی بینهایت، در مجموع 3 فراخوانی با 3,966 توکن ورودی داشت. در سناریوی چرخهی بینهایت نیز میانافزار آزمایشی، پاسخ مدل را پس از فراخوانی جایگزین میکرد؛ به همین دلیل اسپنها برای 8 فراخوانی صورتحسابشده با 11,756 توکن ورودی، مقدار 0 توکن را ثبت کردند. این شکاف دوم از خود آزمون میآید، اما شکاف اول در تکتک اجراهای هر ایجنتی که قابلیت خلاصهسازی دارد وجود دارد.
لاگهای حامل شناسهی ردگیری
هر خط لاگ به صورت JSON است و فرمتکننده، شناسهی ردگیری و شناسهی اسپن مربوط به اسپن جاری را به آن اضافه میکند. خطوط زیر مربوط به یک اجرا از سناریوی قفل کردن ابزار (Hung tool) روی Qwen3 14B است. خط لاگ tool.error شناسهی اسپنِ agent.run را دارد، نه شناسهی اسپن ابزار را؛ چرا که ToolErrorMiddleware آن را بیرون از چرخهی تلاش مجدد و پس از پایان آخرین اسپن ابزار مینویسد. برای متصل کردن خطوط لاگ به اسپنهای ابزار، باید از شناسهی ردگیری استفاده کنید.
{"ts": 1794738671.926, "level": "INFO", "event": "run.start", "thread_id": "7d6ee462-aeeb-43be-bdc1-320a22f92ee8", "user_id": "e14", "trace_id": "f3619cebe3ac7755ec6e9392b2581a61", "span_id": "5226b37abac5ab4b"}
{"ts": 1794738678.029, "level": "INFO", "event": "tool.error", "tool": "read_order", "error": "TimeoutError", "trace_id": "f3619cebe3ac7755ec6e9392b2581a61", "span_id": "5226b37abac5ab4b"}خاموش بودن LangSmith
فریمورک LangChain زمانی اجراها را به LangSmith میفرستد که مقدار LANGSMITH_TRACING برابر با true باشد. ما LANGSMITH_ENDPOINT را به سمت یک ضبطکنندهی محلی (Local recorder) هدایت کردیم و یک کلید ساختگی به آن دادیم تا هر تلاشی برای آپلود اطلاعات در قالب یک درخواست دیده شود. سپس یک گفتوگو را با مقدار true، یک بار با false و یک بار هم بدون تنظیم این فلگ اجرا کردیم. در هر گفتوگو، یک سؤال از بخش سؤالات متداول پرسیده شد، درخواست استرداد وجه همراه با مبلغ و دلیل ثبت شد و سپس با تأییدیهی آن مخالفت شد.
این آزمایش را برای هر حالت، یک بار روی مک و با Qwen3 4B اندازهگیری کردیم. مدل در هر سه گفتوگو ابزارهای search_faq و refund_order را فراخوانی کرد.
LANGSMITH_TRACING |
درخواستها به ضبطکننده | بایتها | مسیرها |
|---|---|---|---|
true |
10 | 337,363 | /info، /runs/multipart |
false |
0 | 0 | هیچ |
| تنظیمنشده | 0 | 0 | هیچ |
اجرای کنترلی ثابت میکند که اگر تلاشی برای ارسال میشد، ضبطکننده آن را ثبت میکرد: 10 درخواست و 337,363 بایت برای یک گفتوگوی کوتاه. در دو حالت دیگر هیچ دادهای ارسال نشد. صرفِ وجود کلید در متغیرهای محیطی برای ارسال داده کافی نیست؛ تعیینکننده خودِ این فلگ است.
منابع: capture/lab/prodapp-mac/code/app/middleware.py، capture/lab/prodapp-mac/code/app/telemetry.py، capture/lab/prodapp-mac/code/app/usage.py، capture/lab/prodapp-mac/code/app/server.py، capture/lab/prodapp-mac/code/scripts/service_real.py، capture/lab/prodapp-mac/code/tests/test_smith_off.py، capture/lab/prodapp-mac/runs/suite/qwen3-14b/rep-1/test-spans.jsonl، capture/lab/prodapp-mac/runs/suite/qwen3-14b/rep-1/test-log.jsonl، capture/lab/prodapp-mac/runs/suite/qwen3-14b/rep-1/usage.jsonl، capture/lab/prodapp-mac/runs/service/service-properties.json، capture/lab/prodapp-mac/runs/ollama-cache-probe.txt، capture/lab/prodapp-mac/runs/suite/haiku/rep-1/usage.jsonl، capture/lab/prodapp-mac/code/scripts/cost_real.py، capture/lab/prodapp-mac/summary/cost-mac.json، capture/lab/prodapp-mac/summary/service-mac.json؛ libs/langchain_v1/langchain/agents/middleware/summarization.py در langchain==1.5.0.