הגדרת מעקב

בעזרת Cloud Trace אפשר לנתח את הביצועים של הסוכנים על ידי מעקב אחר ציר הזמן של הפעולות לכל שאילתה. אפשר להשתמש בנתוני מעקב כדי לזהות צווארי בקבוק ולהבין את האינטראקציות עם מודלים גדולים של שפה (LLM) או עם כלים.

במאמר הזה מוסבר איך להפעיל את Trace לסוכנים שלכם ואיך להציג ולנתח עקבות במסוף Google Cloud .

Trace הוא ציר זמן של בקשות בזמן שהסוכן מגיב לכל שאילתה. לדוגמה, בתרשים הבא מוצג מעקב לדוגמה מסוכן של ערכת פיתוח סוכנים (ADK):

דוגמה למעקב אחר שאילתה

‫Trace מורכב מspan בודדים, שמייצגים יחידת עבודה אחת, כמו קריאה לפונקציה או אינטראקציה עם LLM. ה-span הראשון מייצג את הבקשה הכוללת. כל טווח מספק פרטים על פעולה ספציפית, כמו השם של הפעולה, שעת ההתחלה ושעת הסיום, ומאפיינים רלוונטיים, בתוך הבקשה. לדוגמה, קטע ה-JSON הבא מציג טווח יחיד שמייצג קריאה למודל שפה גדול (LLM):

  {
    "name": "llm",
    "context": {
        "trace_id": "ed7b336d-e71a-46f0-a334-5f2e87cb6cfc",
        "span_id": "ad67332a-38bd-428e-9f62-538ba2fa90d4"
    },
    "span_kind": "LLM",
    "parent_id": "f89ebb7c-10f6-4bf8-8a74-57324d2556ef",
    "start_time": "2023-09-07T12:54:47.597121-06:00",
    "end_time": "2023-09-07T12:54:49.321811-06:00",
    "status_code": "OK",
    "status_message": "",
    "attributes": {
        "llm.input_messages": [
            {
                "message.role": "system",
                "message.content": "You are an expert Q&A system that is trusted around the world.\nAlways answer the query using the provided context information, and not prior knowledge.\nSome rules to follow:\n1. Never directly reference the given context in your answer.\n2. Avoid statements like 'Based on the context, ...' or 'The context information ...' or anything along those lines."
            },
            {
                "message.role": "user",
                "message.content": "Hello?"
            }
        ],
        "output.value": "assistant: Yes I am here",
        "output.mime_type": "text/plain"
    },
    "events": [],
  }

פרטים נוספים זמינים במאמרי העזרה של Cloud Trace בנושא עקבות וטווחים והקשר של עקבות.

לפני שמתחילים

כדי לאסוף ולכתוב עקבות, צריך להפעיל ממשקי API ספציפיים ולהתקין תלות. מידע נוסף זמין במאמר בנושא איסוף והצגה של הנחיות ותשובות מרובות מצבים במסמכי התיעוד של Google Cloud Observability.

כתיבת עקבות לסוכן

כדי לכתוב עקבות של סוכן:

ADK

כדי להפעיל את OpenTelemetry עבור AdkApp, מגדירים את משתני הסביבה הבאים כשפורסים את הסוכן אל Agent Runtime:

env_vars = {
  "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY": "true",
  "OTEL_SEMCONV_STABILITY_OPT_IN": "gen_ai_latest_experimental",
  "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "EVENT_ONLY",
}

שימו לב לנקודות הבאות:

  • ‫GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY מאפשרת לראות את העקבות והיומנים של הסוכן, אבל לא כוללת הנחיות ונתוני תגובה.

  • ‫OTEL_SEMCONV_STABILITY_OPT_IN מאפשר שימוש במוסכמות הסמנטיות העדכניות ביותר של AI גנרטיבי.

  • ‫OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT מאפשר רישום ביומן של הנחיות קלט, תשובות פלט ומזהי משתמשים (השדה user.id). תיעוד הפרטים האלה מאפשר לסוכנים לראות את השימוש במערכת ולזהות אנומליות על ידי מעקב אחר השימוש והאינטראקציות לאורך זמן.

  • כדי להשתמש בהעברה של נתוני מעקב, צריך להפעיל את Telemetry API. מידע נוסף זמין במאמר סקירה כללית על Telemetry (OTLP) API.

  • כדי להשתמש בהעברה של יומנים, צריך להפעיל את Logging API. מידע נוסף מופיע במאמר סקירה כללית על Cloud Logging API.

LangchainAgent

כדי להפעיל מעקב אחר LangchainAgent, מציינים את enable_tracing=True כשמפתחים סוכן LangChain. לדוגמה:

from vertexai.agent_engines import LangchainAgent

agent = LangchainAgent(
    model=model,                # Required.
    tools=[get_exchange_rate],  # Optional.
    enable_tracing=True,        # [New] Optional.
)

LanggraphAgent

כדי להפעיל מעקב אחר LanggraphAgent, צריך לציין את enable_tracing=True כשמפתחים סוכן LangGraph. לדוגמה:

from vertexai.agent_engines import LanggraphAgent

agent = LanggraphAgent(
    model=model,                # Required.
    tools=[get_exchange_rate],  # Optional.
    enable_tracing=True,        # [New] Optional.
)

LlamaIndex

כדי להפעיל מעקב אחר LlamaIndexQueryPipelineAgent, מציינים את enable_tracing=True כשמפתחים סוכן LlamaIndex. לדוגמה:

from vertexai.preview import reasoning_engines

  def runnable_with_tools_builder(model, runnable_kwargs=None, **kwargs):
      from llama_index.core.query_pipeline import QueryPipeline
      from llama_index.core.tools import FunctionTool
      from llama_index.core.agent import ReActAgent

      llama_index_tools = []
      for tool in runnable_kwargs.get("tools"):
          llama_index_tools.append(FunctionTool.from_defaults(tool))
      agent = ReActAgent.from_tools(llama_index_tools, llm=model, verbose=True)
      return QueryPipeline(modules = {"agent": agent})

  agent = reasoning_engines.LlamaIndexQueryPipelineAgent(
      model="gemini-3.5-flash",
      runnable_kwargs={"tools": [get_exchange_rate]},
      runnable_builder=runnable_with_tools_builder,
      enable_tracing=True,        # Optional
  )

בהתאמה אישית

כדי להפעיל מעקב עבור סוכנים מותאמים אישית, אפשר לעיין בפרטים במאמר בנושא מעקב באמצעות OpenTelemetry.

הפעולה הזו מייצאת את העקבות אל Cloud Trace בפרויקט שבקטע הגדרת הפרויקט Google Cloud .

הצגת עקבות של סוכן

אם סוכן כבר נפרס, אפשר להשתמש במסוף Google Cloud כדי לראות את העקבות שלו:

  1. נכנסים לדף Deployments של Agent Platform במסוף Google Cloud .

    מעבר לדף Deployments

    מופעים של Agent Platform ששייכים לפרויקט שנבחר יופיעו ברשימה. אפשר להשתמש בשדה Filter כדי לסנן את הרשימה לפי העמודה שצוינה.

  2. לוחצים על השם של מכונת Agent Platform.

  3. לוחצים על הכרטיסייה Traces (עקבות).

  4. אפשר לבחור באפשרות תצוגת סשן או תצוגת טווח.

    לוחצים על סשן או על טווח כדי לבדוק את פרטי העקבות, כולל גרף מכוון לא מחזורי (DAG) של הטווחים, הקלט והפלט והמאפיינים של המטא-נתונים.

מכסות ומגבלות

יכול להיות שערכים של מאפיינים מסוימים יקוצרו כשהם יגיעו למגבלות המכסה. מידע נוסף זמין במאמר בנושא מכסות ב-Cloud Trace.

תמחור

ל-Cloud Trace יש תוכנית בחינם. מידע נוסף זמין במאמר תמחור של Cloud Trace.