Konteks URL

Anda dapat menggunakan alat konteks URL untuk memberikan URL kepada Gemini sebagai konteks tambahan untuk perintah Anda. Kemudian, model dapat mengambil konten dari URL dan menggunakan konten tersebut untuk menginformasikan dan membentuk responsnya.

Alat ini berguna untuk tugas seperti berikut:

  • Mengekstrak poin data atau poin pembicaraan penting 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 ujian)

Perhatikan bahwa indeks yang digunakan untuk menarik data mungkin belum tentu terbaru, sehingga beberapa informasi mungkin 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 dalam dua cara utama, dengan sendirinya atau bersamaan dengan Perujukan dengan Google Penelusuran.

Hanya konteks URL

Anda dapat memberikan URL spesifik yang ingin dianalisis model langsung dalam 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

Melakukan grounding dengan Google Penelusuran menggunakan konteks URL

Anda juga dapat mengaktifkan konteks URL dan Perujukan dengan Google Penelusuran, menggunakan perintah dengan atau tanpa URL. Model dapat terlebih dahulu menelusuri informasi yang relevan, lalu menggunakan alat konteks URL untuk membaca konten hasil penelusuran agar lebih memahami konteksnya.

Fitur ini bersifat eksperimental dan tersedia di API versi 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 Perujukan Web untuk Perusahaan jika Anda memiliki kebutuhan kepatuhan tertentu atau berada di industri yang diatur seperti kesehatan, keuangan, atau sektor publik. Indeks web yang digunakan dalam Web Grounding untuk Perusahaan lebih terbatas daripada indeks Grounding dengan Google Penelusuran standar, karena menggunakan sebagian kecil dari apa yang tersedia di Google Penelusuran.

Untuk mengetahui detail selengkapnya tentang Penyiapan Web untuk Perusahaan, lihat halaman Penyiapan 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 (sebagian respons telah dihilangkan agar lebih singkat):

{
  "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 data langsung

Alat konteks URL mengambil versi aktif halaman web agar 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 URL, alat ini akan mencoba mengambil konten dari indeks web Googleyang ekstensif dan sangat dioptimalkan terlebih dahulu. Metode ini memberikan akses cepat ke koleksi besar halaman web yang di-crawl.

  2. Penggantian pengambilan live: Ini adalah tahap kedua. Jika konten untuk URL tertentu tidak tersedia di indeks (misalnya, jika halaman sangat baru dan belum diindeks), alat akan otomatis melakukan pengambilan langsung. Mekanisme penggantian ini dapat langsung mengakses URL, dan mengambil versi terbaru konten 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 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 perintah dan penggunaan alat 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 membangun dan men-deploy 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 hasil terbaik selama fase eksperimental, gunakan alat ini di halaman web standar, bukan konten multimedia seperti video YouTube.