บริบท URL

เครื่องมือบริบท URL ช่วยให้คุณระบุบริบทเพิ่มเติมให้กับโมเดลใน รูปแบบ URL ได้ การใส่ URL ในคำขอจะช่วยให้โมเดลเข้าถึง เนื้อหาจากหน้าเว็บเหล่านั้นได้ (ตราบใดที่เป็น URL ประเภทที่ไม่ได้ระบุไว้ในส่วน ข้อจำกัด) เพื่อให้ข้อมูล และปรับปรุงการตอบกลับ

เครื่องมือบริบท URL มีประโยชน์สำหรับงานต่างๆ เช่น

  • ดึงข้อมูล: ดึงข้อมูลที่เฉพาะเจาะจง เช่น ราคา ชื่อ หรือข้อมูลสำคัญ จาก URL หลายรายการ
  • เปรียบเทียบเอกสาร: วิเคราะห์รายงาน บทความ หรือ PDF หลายรายการเพื่อ ระบุความแตกต่างและติดตามแนวโน้ม
  • สังเคราะห์และสร้างเนื้อหา: รวมข้อมูลจาก URL แหล่งที่มาหลายรายการเพื่อสร้างสรุปที่ถูกต้อง โพสต์ในบล็อก หรือรายงาน
  • วิเคราะห์โค้ดและเอกสาร: ชี้ไปยังที่เก็บ GitHub หรือเอกสารทางเทคนิคเพื่ออธิบายโค้ด สร้างวิธีการตั้งค่า หรือตอบคำถาม

ตัวอย่างต่อไปนี้แสดงวิธีเปรียบเทียบสูตรอาหาร 2 สูตรจากเว็บไซต์ต่างๆ

Python

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

client = genai.Client()
model_id = "gemini-3.5-flash"

tools = [
  {"url_context": {}},
]

url1 = "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"
url2 = "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"

response = client.models.generate_content(
    model=model_id,
    contents=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",
    config=GenerateContentConfig(
        tools=tools,
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)

# For verification, you can inspect the metadata to see which URLs the model retrieved
print(response.candidates[0].url_context_metadata)

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: [
        "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
    ],
    config: {
      tools: [{urlContext: {}}],
    },
  });
  console.log(response.text);

  // For verification, you can inspect the metadata to see which URLs the model retrieved
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "contents": [
          {
              "parts": [
                  {"text": "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"}
              ]
          }
      ],
      "tools": [
          {
              "url_context": {}
          }
      ]
  }' > result.json

cat result.json

วิธีการทำงาน

เครื่องมือบริบท URL ใช้กระบวนการดึงข้อมูล 2 ขั้นตอนเพื่อสร้างสมดุลระหว่างความเร็ว ต้นทุน และการเข้าถึงข้อมูลล่าสุด เมื่อคุณระบุ URL เครื่องมือจะพยายามดึงข้อมูลเนื้อหาจากแคชดัชนีภายในก่อน ซึ่งทำหน้าที่เป็นแคชที่ได้รับการเพิ่มประสิทธิภาพอย่างสูง หาก URL ไม่พร้อมใช้งานในดัชนี (เช่น หากเป็นหน้าเว็บใหม่มาก) เครื่องมือจะย้อนกลับไปดึงข้อมูลแบบสดโดยอัตโนมัติ ซึ่งจะเข้าถึง URL โดยตรงเพื่อดึงข้อมูลเนื้อหาแบบเรียลไทม์

คุณสามารถใช้เครื่องมือบริบท URL ร่วมกับเครื่องมืออื่นๆ เพื่อสร้างเวิร์กโฟลว์ที่มีประสิทธิภาพมากขึ้น

โมเดล Gemini 3 รองรับการใช้เครื่องมือในตัว (เช่น บริบท URL) ร่วมกับเครื่องมือที่กำหนดเอง (การเรียกใช้ฟังก์ชัน) ดูข้อมูลเพิ่มเติมได้ในหน้าการใช้เครื่องมือร่วมกัน

เมื่อเปิดใช้ทั้งบริบท URL และ การเชื่อมต่อแหล่งข้อมูลกับ Google Search โมเดลจะใช้ความสามารถในการค้นหาเพื่อค้นหา ข้อมูลที่เกี่ยวข้องทางออนไลน์ แล้วใช้เครื่องมือบริบท URL เพื่อทำความเข้าใจหน้าเว็บที่พบในเชิงลึกมากขึ้น แนวทางนี้มีประสิทธิภาพสำหรับพรอมต์ที่ต้องมีการค้นหาในวงกว้างและการวิเคราะห์หน้าเว็บที่เฉพาะเจาะจงในเชิงลึก

Python

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

client = genai.Client()
model_id = "gemini-3.5-flash"

tools = [
      {"url_context": {}},
      {"google_search": {}}
  ]

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,
    )
)

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

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    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: {
      tools: [
        {urlContext: {}},
        {googleSearch: {}}
        ],
    },
  });
  console.log(response.text);
  // To get URLs retrieved for context
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "contents": [
          {
              "parts": [
                  {"text": "Give me three day events 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

การทำความเข้าใจการตอบกลับ

เมื่อโมเดลใช้เครื่องมือบริบท URL การตอบกลับจะมีออบเจ็กต์ url_context_metadata ออบเจ็กต์นี้จะแสดง URL ที่โมเดลดึงข้อมูลเนื้อหามาและสถานะของความพยายามในการดึงข้อมูลแต่ละครั้ง ซึ่งมีประโยชน์สำหรับการยืนยันและการแก้ไขข้อบกพร่อง

ตัวอย่างส่วนหนึ่งของการตอบกลับ (เราได้ละเว้นบางส่วนของการตอบกลับเพื่อความกระชับ)

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata": {
        "url_metadata": [
          {
            "retrieved_url": "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592",
            "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
          },
          {
            "retrieved_url": "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
            "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
          }
        ]
      }
    }
  ]
}

ดูรายละเอียดทั้งหมดเกี่ยวกับออบเจ็กต์นี้ได้ที่เอกสารอ้างอิง API ของ UrlContextMetadata

การตรวจสอบความปลอดภัย

ระบบจะตรวจสอบการกลั่นกรองเนื้อหาใน URL เพื่อยืนยันว่า URL เป็นไปตามมาตรฐานความปลอดภัย หาก URL ที่คุณระบุไม่ผ่านการตรวจสอบนี้ คุณจะได้รับ url_retrieval_status เป็น URL_RETRIEVAL_STATUS_UNSAFE

จำนวนโทเค็น

ระบบจะนับเนื้อหาที่ดึงข้อมูลจาก URL ที่คุณระบุในพรอมต์เป็นส่วนหนึ่งของโทเค็นอินพุต คุณดูจำนวนโทเค็นสำหรับพรอมต์และ การใช้เครื่องมือได้ใน usage_metadata ออบเจ็กต์ของเอาต์พุตโมเดล ตัวอย่างเอาต์พุตมีดังนี้

'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
  }

ราคาต่อโทเค็นจะขึ้นอยู่กับโมเดลที่ใช้ โปรดดูรายละเอียดในหน้าราคา

โมเดลที่รองรับ

โมเดล บริบท URL
Gemini 3.5 Flash ✔️
Gemini 3.1 Pro (เวอร์ชันตัวอย่าง) ✔️
Gemini 3.1 Flash-Lite ✔️
Gemini 3.1 Flash-Lite (เวอร์ชันตัวอย่าง) ✔️
Gemini 3 Flash (เวอร์ชันตัวอย่าง) ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️

แนวทางปฏิบัติแนะนำ

  • ระบุ URL ที่เฉพาะเจาะจง: เพื่อให้ได้ผลลัพธ์ที่ดีที่สุด ให้ระบุ URL โดยตรงไปยัง เนื้อหาที่ต้องการให้โมเดลวิเคราะห์ โมเดลจะดึงข้อมูลเนื้อหาจาก URL ที่คุณระบุเท่านั้น ไม่ดึงข้อมูลเนื้อหาจากลิงก์ที่ซ้อนกัน
  • ตรวจสอบการเข้าถึง: ตรวจสอบว่า URL ที่คุณระบุไม่ได้นำไปยัง หน้าเว็บที่ต้องเข้าสู่ระบบหรืออยู่หลังเพย์วอลล์
  • ใช้ URL ที่สมบูรณ์: ระบุ URL แบบเต็ม รวมถึงโปรโตคอล (เช่น https://www.google.com แทนที่จะเป็น google.com)

ข้อจำกัด

  • การเรียกใช้ฟังก์ชัน: ปัจจุบันระบบไม่รองรับการใช้เครื่องมือ (บริบท URL, การเชื่อมต่อแหล่งข้อมูลกับ Google Search ฯลฯ) ร่วมกับการเรียกใช้ฟังก์ชัน
  • ขีดจำกัดคำขอ: เครื่องมือสามารถประมวลผล URL ได้สูงสุด 20 รายการต่อคำขอ
  • ขนาดเนื้อหา URL: ขนาดสูงสุดของเนื้อหาที่ดึงข้อมูลจาก URL เดียวคือ 34 MB
  • การเข้าถึงแบบสาธารณะ: URL ต้องเข้าถึงได้แบบสาธารณะบนเว็บ ระบบไม่รองรับที่อยู่ localhost (เช่น localhost, 127.0.0.1), เครือข่ายส่วนตัว และบริการทันเนลลิง (เช่น ngrok, pinggy)
  • Gemini API เท่านั้น: บริบท URL ใช้ได้ใน Gemini API เท่านั้น ไม่สามารถใช้ผ่านแพลตฟอร์ม Agent ของ Gemini Enterprise

ประเภทเนื้อหาที่รองรับและไม่รองรับ

เครื่องมือสามารถดึงข้อมูลเนื้อหาจาก URL ที่มีเนื้อหาประเภทต่อไปนี้

  • ข้อความ (text/html, application/json, text/plain, text/xml, text/css, text/javascript , text/csv, text/rtf)
  • รูปภาพ (image/png, image/jpeg, image/bmp, image/webp)
  • PDF (application/pdf)

ระบบไม่ รองรับเนื้อหาประเภทต่อไปนี้

  • เนื้อหาเพย์วอลล์
  • วิดีโอ YouTube (ดู การทำความเข้าใจวิดีโอเพื่อเรียนรู้วิธีประมวลผล URL ของ YouTube )
  • ไฟล์ Google Workspace เช่น Google เอกสารหรือชีต
  • ไฟล์วิดีโอและไฟล์เสียง

ขั้นตอนถัดไป

  • ดูตัวอย่างเพิ่มเติมได้ที่คู่มือการใช้งานบริบท URL