Tracing and Execution Debugging
توسعه عاملهای هوشمند (Agentic Ai) با Langchain و Langgraph
- Capture traces for model calls, retrieval, tools, graph nodes, and latency.
- Inspect state updates and streamed graph events.
- Locate failures in prompts, routing, retrieval, tools, and state transitions.
ردیابی برای یافتن علت
**ایده اصلی**
خروجی نهایی وجود مشکل را نشان میدهد؛ trace محل و علت احتمالی آن را آشکار میکند.
```mermaid
flowchart LR
A["Input"] --> B["Router"]
B --> C["Retriever"]
C --> D["Model"]
D --> E["Tool"]
E --> F["State update"]
B -.-> T["Execution trace"]
C -.-> T
D -.-> T
E -.-> T
F -.-> T
```
چه چیزی را ثبت کنیم؟
**فیلدهای ضروری**
- شناسه اجرا و thread، نام node، ورودی و خروجی
- prompt، query، اسناد، scoreها، ابزار و نتیجه آن
- زمان شروع، زمان پایان، latency و خطا
**محاسبه latency**
با زمان شروع 10.000 و زمان پایان 10.240، تفریق را مرحلهبهمرحله انجام میدهیم: 10.240 − 10.000 = 0.240 ثانیه، و 0.240 × 1000 = 240 میلیثانیه.
خواندن رویدادها و state
**دو نمای مکمل**
- stream events: ترتیب زنده رخدادها و tokenها
- state history: snapshotهای state در نقاط مختلف یک thread
**ردیابی اجرای ناقص**
query برابر weather است؛ retriever مقدار docs برابر [] میدهد؛ model با context خالی اجرا میشود و answer برابر No evidence میشود. بنابراین نخستین نشانه خطا پیش از model دیده شده است.
یک trace را کامل تشخیص بده
**نخستین divergence**
Retriever سند doc_7 را میدهد، اما node کلید documents را برمیگرداند و graph کلید retrieved_docs را میخواند. نتیجه: state خالی، context خالی و پاسخ بدون شواهد.
**اصلاح کمینه**
نام کلید خروجی را از documents به retrieved_docs تغییر بده؛ سپس اجرای دوباره را با trace جدید بررسی کن.
از نشانه تا اصلاح پایدار
```mermaid
flowchart TD
A["پاسخ ناموفق"] --> B{"خطا در event یا exception؟"}
B -->|بله| C["بررسی node و ورودی همان event"]
B -->|خیر| D{"routing درست است؟"}
D -->|خیر| E["اصلاح decision یا conditional edge"]
D -->|بله| F{"docs مناسب و غیرخالیاند؟"}
F -->|خیر| G["اصلاح query یا retrieval"]
F -->|بله| H{"prompt context درست دارد؟"}
H -->|خیر| I["اصلاح state update یا prompt"]
H -->|بله| J["بررسی model و tool output"]
```
**مثال مرزی**
اگر routing درست باشد، docs شامل doc_7 باشد و context متن ساعات کاری را داشته باشد، بررسی را از model output و سپس tool output ادامه بده؛ query را بیدلیل تغییر نده.
**قانون سهگانه**
مشاهده: نخستین event نادرست را پیدا کن. فرضیه: یک علت محتمل پیشنهاد بده. آزمون: با trace جدید همان نقطه را دوباره بررسی کن.
Back to course