追蹤服務專員

本頁面說明如何在代理程式上啟用 Cloud Trace，以及如何查看追蹤記錄，分析查詢回應時間和執行的作業。

追蹤記錄：代理程式回應每項查詢時，會產生要求時間軸。舉例來說，下圖顯示 Agent Development Kit (ADK) 代理程式的追蹤記錄範例：

追蹤記錄是由個別範圍組成，代表單一工作單位，例如函式呼叫或與 LLM 的互動，第一個範圍代表整體要求。每個範圍都會提供特定作業的詳細資料，例如作業名稱、開始和結束時間，以及要求中的任何相關屬性。舉例來說，下列 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": [],
  }

注意： 追蹤記錄和 span 的格式取決於您選擇的檢測選項。範例跨度為實驗性質，可能會有所變更，因此目前不應依賴格式的穩定性。詳情請參閱 OpenTelemetry 開發的生成式 AI 系統語意慣例。

詳情請參閱 Cloud Trace 說明文件中的「追蹤記錄和時距」和「追蹤記錄內容」。

為代理程式撰寫追蹤記錄

如要為代理程式編寫追蹤記錄，請按照下列步驟操作：

ADK

如要為 AdkApp 啟用 OpenTelemetry，請在將代理部署至 Vertex AI Agent Engine 執行階段時，設定下列環境變數：

env_vars = {
  "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY": "true",
  "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "true",
}

注意事項：

• GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY 會啟用代理程式追蹤和記錄，但不包含提示和回應資料。

• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 可啟用輸入提示和輸出回覆的記錄功能。

• 如要使用追蹤記錄擷取功能，請啟用 Telemetry API。詳情請參閱「遙測 (OTLP) API 總覽」

• 如要使用記錄檔擷取功能，請啟用 Logging API。詳情請參閱 Cloud Logging API 總覽。

注意： 如果您先前設定了 enable_tracing 旗標，建議改用環境變數。例如，設定 GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true 而不是 enable_tracing=true，並設定 GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=false 而不是 enable_tracing=false。

LangchainAgent

如要為 LangchainAgent 啟用追蹤功能，請在開發 LangChain 代理程式時指定 enable_tracing=True。例如：

from vertexai.agent_engines import LangchainAgent

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

LanggraphAgent

如要啟用 LanggraphAgent 的追蹤功能，請在開發 LangGraph 代理程式時指定 enable_tracing=True。例如：

from vertexai.agent_engines import LanggraphAgent

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

LlamaIndex

預先發布版

這項功能 適用《服務專屬條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

如要為 LlamaIndexQueryPipelineAgent 啟用追蹤功能，請在開發 LlamaIndex 代理程式時指定 enable_tracing=True。例如：

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-2.0-flash",
      runnable_kwargs={"tools": [get_exchange_rate]},
      runnable_builder=runnable_with_tools_builder,
      enable_tracing=True,        # Optional
  )

自訂

如要為自訂代理程式啟用追蹤功能，請參閱「使用 OpenTelemetry 追蹤」一文。

這會將追蹤記錄匯出至「設定專案 Google Cloud 」中專案的 Cloud Trace。

查看代理程式的追蹤記錄

如果是已部署的代理程式，您可以使用 Google Cloud 控制台查看代理程式的追蹤記錄：

1. 前往 Google Cloud 控制台的「Vertex AI Agent Engine」頁面。
   

   前往 Agent Engine

   清單中會顯示所選專案的 Agent Engine 執行個體。您可以使用「篩選」欄位，依指定欄篩選清單。

2. 按一下 Agent Engine 執行個體的名稱。

3. 按一下「追蹤」分頁標籤。

4. 您可以選取「工作階段檢視」或「跨度檢視」。

   點選工作階段或時距，即可查看追蹤記錄詳細資料，包括時距的有向無環圖 (DAG)、輸入和輸出內容，以及中繼資料屬性。

配額與限制

如果屬性值達到配額限制，可能會遭到截斷。詳情請參閱「Cloud Trace 配額」。

定價

Cloud Trace 提供免費方案。詳情請參閱 Cloud Trace 定價。