Konteks URL

Anda dapat menggunakan alat konteks URL untuk memberikan URL ke Gemini sebagai konteks tambahan untuk perintah Anda. Model ini kemudian dapat mengambil konten dari URL dan menggunakan konten tersebut untuk menginformasikan dan membentuk responsnya.

Alat ini berguna untuk tugas seperti berikut:

  • Mengekstrak poin data utama atau poin pembicaraan dari artikel
  • Membandingkan informasi di beberapa link
  • Mensintesis data dari beberapa sumber
  • Menjawab pertanyaan berdasarkan konten halaman tertentu
  • Menganalisis konten untuk tujuan tertentu (seperti menulis deskripsi pekerjaan atau membuat pertanyaan pengujian)

Perhatikan bahwa indeks yang digunakan untuk menarik data mungkin tidak selalu terbaru, sehingga beberapa informasi mungkin sudah tidak berlaku.

Panduan ini menjelaskan cara menggunakan alat konteks URL di Gemini API di Vertex AI.

Model yang didukung

Model berikut memberikan dukungan untuk Konteks URL:

Menggunakan konteks URL

Anda dapat menggunakan alat konteks URL dengan dua cara utama, yaitu secara terpisah atau bersama dengan Grounding dengan Google Penelusuran.

Konteks URL saja

Anda dapat memberikan URL tertentu yang ingin dianalisis oleh model langsung di perintah Anda:

Summarize this document: YOUR_URLs

Extract the key features from the product description on this page: YOUR_URLs

Python

from google import genai
from google.genai.types import Tool, GenerateContentConfig, HttpOptions, UrlContext

client = genai.Client(http_options=HttpOptions(api_version="v1"))
model_id = "gemini-2.5-flash"

url_context_tool = Tool(
    url_context = UrlContext
)

response = client.models.generate_content(
    model=model_id,
    contents="Compare recipes from YOUR_URL1 and YOUR_URL2",
    config=GenerateContentConfig(
        tools=[url_context_tool],
        response_modalities=["TEXT"],
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)
# get URLs retrieved for context
print(response.candidates[0].url_context_metadata)

JavaScript

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION,
  apiVersion: 'v1',
});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
        "Compare recipes from YOUR_URL1 and YOUR_URL2",
    ],
    config: {
      tools: [{urlContext: {}}],
    },
  });
  console.log(response.text);
  // To get URLs retrieved for context
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-2.5-flash:generateContent \
  -d '{
      "contents": [
          {
              "role": "user",
              "parts": [
                  {"text": "Compare recipes from YOUR_URL1 and YOUR_URL2"}
              ]
          }
      ],
      "tools": [
          {
              "url_context": {}
          }
      ]
  }' > result.json

cat result.json

Grounding dengan Google Penelusuran dengan konteks URL

Anda juga dapat mengaktifkan konteks URL dan Grounding dengan Google Penelusuran, menggunakan perintah dengan atau tanpa URL. Model ini mungkin akan menelusuri informasi yang relevan terlebih dahulu, lalu menggunakan alat konteks URL untuk membaca konten hasil penelusuran guna mendapatkan pemahaman yang lebih mendalam.

Fitur ini bersifat eksperimental dan tersedia dalam versi API v1beta1.

Contoh perintah:

Give me a three day event schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.

Recommend 3 books for beginners to read to learn more about the latest YOUR_SUBJECT.

Python

from google import genai
from google.genai.types import Tool, GenerateContentConfig, HttpOptions, UrlContext, GoogleSearch

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
model_id = "gemini-2.5-flash"

tools = []
tools.append(Tool(url_context=UrlContext))
tools.append(Tool(google_search=GoogleSearch))

response = client.models.generate_content(
    model=model_id,
    contents="Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
    config=GenerateContentConfig(
        tools=tools,
        response_modalities=["TEXT"],
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)
# get URLs retrieved for context
print(response.candidates[0].url_context_metadata)

JavaScript

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION,
  apiVersion: 'v1beta1',
});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
        "Give me a three day event schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
    ],
    config: {
      tools: [{urlContext: {}}, {googleSearch: {}}],
    },
  });
  console.log(response.text);
  // To get URLs retrieved for context
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-2.5-flash:generateContent \
  -d '{
      "contents": [
          {
              "role": "user",
              "parts": [
                  {"text": "Give me a three day event schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute."}
              ]
          }
      ],
      "tools": [
          {
              "url_context": {}
          },
          {
              "google_search": {}
          }
      ]
  }' > result.json

cat result.json

Untuk mengetahui detail selengkapnya tentang Grounding dengan Google Penelusuran, lihat halaman ringkasan.

Grounding Web untuk Perusahaan dengan konteks URL

Anda dapat mengaktifkan konteks URL dan Grounding Web untuk Perusahaan jika memiliki kebutuhan kepatuhan tertentu atau berada dalam industri yang diatur seperti kesehatan, keuangan, atau sektor publik. Indeks web yang digunakan dalam Grounding Web untuk Perusahaan lebih terbatas daripada indeks Grounding dengan Google Penelusuran standar, karena menggunakan subset dari apa yang tersedia di Google Penelusuran.

Untuk mengetahui detail selengkapnya tentang Grounding Web untuk Perusahaan, lihat halaman Grounding Web untuk Perusahaan.

Respons kontekstual

Respons model didasarkan pada konten yang diambil dari URL. Jika model mengambil konten dari URL, respons akan menyertakan url_context_metadata. Respons tersebut mungkin terlihat seperti berikut (bagian respons telah dihilangkan untuk mempersingkat):

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata":
      {
          "url_metadata":
          [
            {
              "retrieved_url": "https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/code-execution",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "https://cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-search",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
          ]
        }
    }
  ]
}

Untuk mengetahui informasi selengkapnya tentang objek ini, lihat referensi API UrlContextMetadata.

Pengambilan langsung

Alat konteks URL mengambil versi langsung halaman web untuk menjaga informasi Anda tetap terbaru.

Untuk mengambil konten halaman web secara efisien, alat konteks URL menggunakan proses dua tahap yang dirancang untuk menyeimbangkan kecepatan, biaya, dan akses ke informasi terbaru:

  1. Pengambilan konten yang diindeks: Ini adalah tahap pertama. Saat Anda memberikan a URL, alat ini pertama-tama akan mencoba mengambil konten dari Google's indeks web yang luas dan sangat dioptimalkan. Metode ini memberikan akses cepat ke koleksi besar halaman web yang di-crawl.

  2. Pengambilan langsung sebagai pengganti: Ini adalah tahap kedua. Jika konten untuk URL tertentu tidak tersedia di indeks (misalnya, jika halaman tersebut sangat baru dan belum diindeks), alat akan otomatis melakukan pengambilan langsung. Mekanisme penggantian ini dapat langsung mengakses URL, dan mengambil versi konten terbaru secara real time.

Pemeriksaan keamanan

Sistem melakukan pemeriksaan moderasi konten pada URL untuk mengonfirmasi bahwa URL tersebut memenuhi standar keamanan. Jika URL yang Anda berikan gagal dalam pemeriksaan ini, Anda akan mendapatkan url_retrieval_status dari URL_RETRIEVAL_STATUS_UNSAFE.

Jumlah token

Jumlah token input mencakup konten yang diambil dari URL yang Anda tentukan dalam perintah Anda. Dari output model, Anda dapat melihat jumlah token untuk penggunaan perintah dan alat Anda di objek usage_metadata. Berikut adalah contoh output:

'usage_metadata': {
  'candidates_token_count': 45,
  'prompt_token_count': 27,
  'prompt_tokens_details': [{'modality': <MediaModality.TEXT: 'TEXT'>,
    'token_count': 27}],
  'thoughts_token_count': 31,
  'tool_use_prompt_token_count': 10309,
  'tool_use_prompt_tokens_details': [{'modality': <MediaModality.TEXT: 'TEXT'>,
    'token_count': 10309}],
  'total_token_count': 10412
  }

Harga per token bergantung pada model yang Anda gunakan. Untuk mengetahui informasi selengkapnya, lihat Biaya pembuatan dan deployment model AI di Vertex AI.

Jenis konten yang didukung dan tidak didukung

Alat konteks URL dapat mengekstrak konten dari URL dengan jenis konten berikut:

Konten Jenis
Teks text/html
application/json
text/plain
text/xml
text/css
text/javascript
text/csv
text/rtf
Gambar image/png
image/jpeg
image/bmp
image/webp
PDF application/pdf

Alat konteks URL tidak mendukung jenis konten berikut:

  • Konten berbayar berpenghalang
  • Video YouTube (Untuk mengetahui informasi selengkapnya, lihat Pemahaman video.)
  • File Google Workspace seperti Google Dokumen atau Google Spreadsheet
  • File video dan audio

Batasan

  • Alat konteks URL menggunakan hingga 20 URL per permintaan untuk analisis.
  • Untuk mendapatkan hasil terbaik selama fase eksperimental, gunakan alat ini di halaman web standar, bukan konten multimedia seperti video YouTube.