Menyiapkan pelacakan

Cloud Trace memungkinkan Anda menganalisis performa agen dengan melacak linimasa operasi untuk setiap kueri. Anda dapat menggunakan trace untuk mengidentifikasi bottleneck dan memahami interaksi dengan model bahasa besar (LLM) atau alat.

Dokumen ini menjelaskan cara mengaktifkan Trace untuk agen dan cara melihat serta menganalisis trace di Google Cloud konsol.

Trace adalah linimasa permintaan saat agen Anda merespons setiap kueri. Misalnya, diagram berikut menunjukkan contoh trace dari agen Agent Development Kit (ADK):

Contoh rekaman aktivitas untuk kueri

Trace terdiri dari individual rentang, yang mewakili satu unit kerja, seperti panggilan fungsi atau interaksi dengan LLM, dengan rentang pertama yang mewakili keseluruhan permintaan. Setiap rentang memberikan detail tentang operasi tertentu, seperti nama operasi, waktu mulai dan berakhir, serta atribut relevan apa pun, dalam permintaan. Misalnya, JSON berikut menunjukkan satu rentang yang mewakili panggilan ke model bahasa besar (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": [],
  }

Untuk mengetahui detailnya, lihat dokumentasi Cloud Trace tentang Trace dan rentang serta Konteks trace.

Sebelum memulai

Sebelum dapat mengumpulkan dan menulis trace, Anda harus mengaktifkan API tertentu dan menginstal dependensi. Untuk mengetahui informasi selengkapnya, lihat Mengumpulkan dan melihat multimodal perintah serta respons di dokumentasi Google Cloud Observability.

Menulis trace untuk agen

Untuk menulis trace untuk agen:

ADK

Untuk mengaktifkan OpenTelemetry untuk AdkApp, tetapkan variabel lingkungan berikut saat Anda men-deploy agen ke Runtime Agen:

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",
}

Perhatikan hal berikut:

  • GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY mengaktifkan log dan trace agen, tetapi tidak menyertakan data perintah dan respons.

  • OTEL_SEMCONV_STABILITY_OPT_IN memungkinkan penggunaan konvensi semantik AI generatif terbaru.

  • OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT memungkinkan logging perintah input, respons output, dan ID pengguna (kolom user.id). Merekam detail ini memfasilitasi observabilitas agen dan deteksi anomali dengan melacak penggunaan dan interaksi dari waktu ke waktu.

  • Untuk menggunakan penyerapan trace, Anda harus mengaktifkan Telemetry API. Untuk mengetahui informasi selengkapnya, lihat Ringkasan Telemetry (OTLP) API.

  • Untuk menggunakan penyerapan log, Anda harus mengaktifkan Logging API. Untuk mengetahui informasi selengkapnya, lihat Ringkasan Cloud Logging API.

LangchainAgent

Untuk mengaktifkan tracing untuk LangchainAgent, tentukan enable_tracing=True saat Anda mengembangkan agen LangChain. Contoh:

from vertexai.agent_engines import LangchainAgent

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

LanggraphAgent

Untuk mengaktifkan tracing untuk LanggraphAgent, tentukan enable_tracing=True saat Anda mengembangkan agen LangGraph. Contoh:

from vertexai.agent_engines import LanggraphAgent

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

LlamaIndex

Untuk mengaktifkan tracing untuk LlamaIndexQueryPipelineAgent, tentukan enable_tracing=True saat Anda mengembangkan agen LlamaIndex. Contoh:

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
  )

Kustom

Untuk mengaktifkan tracing untuk agen kustom, lihat Tracing menggunakan OpenTelemetry untuk mengetahui detailnya.

Tindakan ini akan mengekspor trace ke Cloud Trace di project di Menyiapkan project Google Cloud .

Melihat trace untuk agen

Untuk agen yang di-deploy, Anda dapat menggunakan Google Cloud konsol untuk melihat trace agen:

  1. Di Google Cloud konsol, buka halaman Deployment Platform Agen.

    Buka Deployment

    Instance Platform Agen yang merupakan bagian dari project yang dipilih akan muncul dalam daftar. Anda dapat menggunakan kolom Filter untuk memfilter daftar berdasarkan kolom yang Anda tentukan.

  2. Klik nama instance Platform Agen Anda.

  3. Klik tab Trace.

  4. Anda dapat memilih Tampilan sesi atau Tampilan rentang.

    Klik sesi atau rentang untuk memeriksa detail trace, termasuk grafik asiklik terarah (DAG) rentang, input dan output, serta atribut metadata.

Kuota dan batas

Beberapa nilai atribut mungkin akan terpotong saat mencapai batas kuota. Untuk mengetahui informasi selengkapnya, lihat Kuota Cloud Trace.

Harga

Cloud Trace memiliki paket gratis. Untuk mengetahui informasi selengkapnya, lihat Harga Cloud Trace.