Công cụ bối cảnh URL cho phép bạn cung cấp thêm bối cảnh cho các mô hình dưới dạng URL. Bằng cách đưa URL vào yêu cầu, mô hình sẽ truy cập vào nội dung của những trang đó (miễn là đó không phải là loại URL được liệt kê trong phần hạn chế) để cung cấp thông tin và nâng cao phản hồi của mô hình.
Công cụ ngữ cảnh URL rất hữu ích cho những tác vụ như sau:
- Trích xuất dữ liệu: Lấy thông tin cụ thể như giá, tên hoặc phát hiện chính từ nhiều URL.
- So sánh tài liệu: Phân tích nhiều báo cáo, bài viết hoặc tệp PDF để xác định điểm khác biệt và theo dõi xu hướng.
- Tổng hợp và tạo nội dung: Kết hợp thông tin từ nhiều URL nguồn để tạo bản tóm tắt, bài đăng trên blog hoặc báo cáo chính xác.
- Phân tích mã và tài liệu: Chỉ đến một kho lưu trữ trên GitHub hoặc tài liệu kỹ thuật để giải thích mã, tạo hướng dẫn thiết lập hoặc trả lời câu hỏi.
Ví dụ sau đây cho thấy cách so sánh hai công thức nấu ăn từ các trang web khác nhau.
Python
from google import genai
from google.genai.types import Tool, GenerateContentConfig
client = genai.Client()
model_id = "gemini-2.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-2.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-2.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
Cách hoạt động
Công cụ Bối cảnh URL sử dụng quy trình truy xuất gồm hai bước để cân bằng tốc độ, chi phí và quyền truy cập vào dữ liệu mới. Khi bạn cung cấp một URL, công cụ này sẽ cố gắng tìm nạp nội dung từ bộ nhớ đệm chỉ mục nội bộ trước tiên. Đây là một bộ nhớ đệm được tối ưu hoá cao. Nếu một URL không có trong chỉ mục (ví dụ: nếu đó là một trang rất mới), thì công cụ này sẽ tự động quay lại để thực hiện một lượt tìm nạp trực tiếp. Thao tác này truy cập trực tiếp vào URL để truy xuất nội dung theo thời gian thực.
Kết hợp với các công cụ khác
Bạn có thể kết hợp công cụ bối cảnh URL với các công cụ khác để tạo quy trình làm việc hiệu quả hơn.
Liên kết thực tế bằng tính năng tìm kiếm
Khi cả ngữ cảnh URL và tính năng Căn cứ vào Google Tìm kiếm đều được bật, mô hình có thể sử dụng các chức năng tìm kiếm của mình để tìm thông tin liên quan trên mạng, sau đó sử dụng công cụ ngữ cảnh URL để hiểu rõ hơn về những trang mà mô hình tìm thấy. Phương pháp này rất hiệu quả đối với những câu lệnh yêu cầu cả tìm kiếm trên diện rộng và phân tích chuyên sâu các trang cụ thể.
Python
from google import genai
from google.genai.types import Tool, GenerateContentConfig, GoogleSearch, UrlContext
client = genai.Client()
model_id = "gemini-2.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-2.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-2.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
Hiểu rõ câu trả lời
Khi mô hình sử dụng công cụ ngữ cảnh URL, phản hồi sẽ bao gồm một đối tượng url_context_metadata. Đối tượng này liệt kê các URL mà mô hình đã truy xuất nội dung và trạng thái của từng lần truy xuất. Điều này rất hữu ích cho việc xác minh và gỡ lỗi.
Sau đây là ví dụ về phần đó trong phản hồi (một số phần của phản hồi đã bị bỏ qua để cho ngắn gọn):
{
"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"
}
]
}
}
}
Để biết thông tin chi tiết đầy đủ về đối tượng này , hãy xem tài liệu tham khảo về API UrlContextMetadata.
Kiểm tra an toàn
Hệ thống sẽ kiểm tra nội dung của URL để xác nhận rằng URL đó đáp ứng các tiêu chuẩn an toàn. Nếu URL bạn cung cấp không vượt qua được bước kiểm tra này, bạn sẽ nhận được url_retrieval_status trong số URL_RETRIEVAL_STATUS_UNSAFE.
Số lượng mã thông báo
Nội dung được truy xuất từ các URL mà bạn chỉ định trong câu lệnh sẽ được tính là một phần của mã thông báo đầu vào. Bạn có thể xem số lượng mã thông báo cho câu lệnh và mức sử dụng công cụ trong đối tượng usage_metadata của đầu ra mô hình. Sau đây là một ví dụ về kết quả đầu ra:
'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
}
Giá mỗi mã thông báo phụ thuộc vào mô hình được dùng, hãy xem trang định giá để biết thông tin chi tiết.
Mô hình được hỗ trợ
- gemini-2.5-pro
- gemini-2.5-flash
- gemini-2.5-flash-lite
- gemini-live-2.5-flash-preview
- gemini-2.0-flash-live-001
Các phương pháp hay nhất
- Cung cấp URL cụ thể: Để có kết quả tốt nhất, hãy cung cấp URL trực tiếp đến nội dung mà bạn muốn mô hình phân tích. Mô hình này sẽ chỉ truy xuất nội dung từ những URL mà bạn cung cấp, chứ không phải nội dung từ các đường liên kết lồng nhau.
- Kiểm tra khả năng tiếp cận: Xác minh rằng các URL bạn cung cấp không dẫn đến những trang yêu cầu đăng nhập hoặc nằm sau tường phí.
- Sử dụng URL đầy đủ: Cung cấp URL đầy đủ, bao gồm cả giao thức (ví dụ: https://www.google.com thay vì chỉ google.com).
Các điểm hạn chế
- Giá: Nội dung được truy xuất từ URL được tính là mã thông báo đầu vào. Hạn mức và giá dựa trên mô hình được sử dụng. Hãy xem trang giới hạn tốc độ và định giá để biết thông tin chi tiết.
- Hạn mức yêu cầu: Công cụ này có thể xử lý tối đa 20 URL cho mỗi yêu cầu.
- Kích thước nội dung URL: Kích thước tối đa cho nội dung được truy xuất từ một URL duy nhất là 34 MB.
Các loại nội dung được hỗ trợ và không được hỗ trợ
Công cụ này có thể trích xuất nội dung từ các URL có những loại nội dung sau:
- Văn bản (text/html, application/json, text/plain, text/xml, text/css, text/javascript , text/csv, text/rtf)
- Hình ảnh (image/png, image/jpeg, image/bmp, image/webp)
- PDF (application/pdf)
Các loại nội dung sau đây không được hỗ trợ:
- Nội dung có tường phí
- Video trên YouTube (Xem phần hiểu video để tìm hiểu cách xử lý URL của YouTube)
- Các tệp trên Google Workspace như tài liệu hoặc bảng tính trên Google
- Tệp video và âm thanh
Bước tiếp theo
- Khám phá sổ tay về ngữ cảnh URL để xem thêm ví dụ.