Skip to content

SDK التتبّع (potato_trace)

زوّد أي وكيل بأدوات القياس عبر SDK التتبّع الخفيف potato_trace لالتقاط تشغيلاته داخل Potato لأجل التقييم. زيّن الدوال بـ @traceable (متزامنة أو غير متزامنة) فتُلتقط التشغيلات المتداخلة وتُرسَل إلى webhook الاستيعاب في Potato، مع تصدير اختياري عبر OpenTelemetry.

potato_trace هو SDK خفيف يلتقط تشغيلات وكيلك ويرسلها إلى Potato لأجل التقييم. يقع Potato في مسار التشغيل، فتقيّم التشغيلات الحقيقية وقت حدوثها بدل الاكتفاء باستيراد تفريغات غير متصلة. وهو قليل التبعيات (المكتبة القياسية إضافةً إلى requests وقت الإرسال) وحزمة عليا، فاستيراده لا يجرّ معه أي إطار ويب.

البداية السريعة

python
import potato_trace
 
potato_trace.configure(
    potato_url="http://localhost:8000",   # or env POTATO_TRACE_URL
    api_key="",                            # or env POTATO_TRACE_API_KEY
    project_name="my-agent",
)
 
@potato_trace.traceable(run_type="tool")
def search(query):
    return run_search(query)
 
@potato_trace.traceable(run_type="llm")
def summarize(text):
    potato_trace.add_metadata(prompt_tokens=120, completion_tokens=40)
    return call_llm(text)
 
@potato_trace.traceable            # the outermost call is the trace root
def agent(task):
    return summarize(search(task))
 
agent("weather in NYC")
potato_trace.flush()               # ensure sends finish before a short script exits

تشكّل استدعاءات @traceable المتداخلة شجرة تشغيل؛ وعند عودة الجذر تُرسَل الشجرة كاملة بطلب POST إلى /api/traces/webhook في خيط خلفي (فالتتبّع لا يحجب وكيلك ولا يعطّله أبدًا). وإن لم يُضبط potato_url، صار التتبّع عملية لا أثر لها وآمنة.

API

الرمزالغرض
configure(potato_url=, api_key=, project_name=)ضبط العميل العام
@traceable / @traceable(run_type=, name=, tags=)تتبّع دالة (متزامنة أو غير متزامنة)؛ run_type: chain (الافتراضي)، llm، tool، retriever
trace(name, run_type=...)صيغة مدير السياق: with trace("step"): ...
set_outputs({...}) / add_metadata(**kw)إرفاق المخرجات أو استهلاك الرموز بالتشغيل الحالي
flush(timeout=30)الانتظار حتى تنتهي عمليات الإرسال الخلفية المعلّقة

التشغيل البيني مع OpenTelemetry (اختياري)

إن كانت منظومتك تصدر مقاطع OpenTelemetry (وفق اصطلاحات GenAI الدلالية)، فصدّرها إلى Potato مباشرة. وopentelemetry-sdk إضافة اختيارية:

python
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from potato_trace.otel_exporter import build_exporter
 
provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(build_exporter(project_name="my-agent")))

استقبال المسارات

على جانب Potato، فعّل استيعاب المسارات ليقبل الـ webhook التشغيلات الواردة:

yaml
trace_ingestion:
  enabled: true
  api_key: ""    # set a key in production; the SDK sends it as a Bearer token

تصبح المسارات الملتقطة عناصر يمكنك تقييمها، أو توجيهها بـقواعد الأتمتة، أو انتقاؤها ضمن مجموعات بيانات.

مواضيع ذات صلة