הגדרת מעקב

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

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

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

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

מעקב מורכב מיחידות לוגיות למעקב נפרדות, שמייצגות יחידת עבודה אחת, כמו בקשה להפעלת פונקציה או אינטראקציה עם LLM, כשהיחידה הלוגית למעקב הראשונה מייצגת את הבקשה הכוללת. כל span מספק פרטים על פעולה ספציפית, כמו שם הפעולה, זמני ההתחלה והסיום וכל מאפיין רלוונטי בבקשה. לדוגמה, קוד ה-JSON הבא מציג span יחיד שמייצג קריאה למודל שפה גדול (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.

  • כדי להטמיע יומנים, צריך להפעיל את Cloud 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. במסוף Google Cloud , נכנסים לדף Deployments ב-Agent Platform.

    מעבר אל Deployments

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

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

  3. לוחצים על הכרטיסייה Traces.

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

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

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

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

תמחור

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