زمینه URL

ابزار زمینه URL به شما امکان می‌دهد زمینه‌های اضافی را در قالب URLها به مدل ارائه دهید. مدل می‌تواند به محتوای آن URLها دسترسی پیدا کند تا پاسخ خود را بهبود بخشد و از آن مطلع شود.

متن URL مزایای زیر را دارد:

  • استخراج داده‌ها : اطلاعات خاصی مانند قیمت‌ها، نام‌ها یا یافته‌های کلیدی را از یک مقاله یا چندین URL ارائه دهید.

  • مقایسه اطلاعات : چندین گزارش، مقاله یا PDF را تجزیه و تحلیل کنید تا تفاوت‌ها را شناسایی کرده و روندها را پیگیری کنید.

  • ترکیب و ایجاد محتوا : اطلاعات را از چندین آدرس اینترنتی منبع ترکیب کنید تا خلاصه‌های دقیق، پست‌های وبلاگ، گزارش‌ها یا سوالات آزمون تولید کنید.

  • تحلیل کد و محتوای فنی : ارائه آدرس اینترنتی (URL) به مخزن گیت‌هاب یا مستندات فنی برای توضیح کد، ایجاد دستورالعمل‌های راه‌اندازی یا پاسخ به سوالات.

هنگام استفاده از ابزار URL context، مطمئن شوید که بهترین شیوه‌ها و محدودیت‌ها را بررسی می‌کنید.

مدل‌های پشتیبانی‌شده

  • gemini-3-pro-preview
  • gemini-3-flash-preview
  • gemini-2.5-pro
  • gemini-2.5-flash
  • gemini-2.5-flash-lite

زبان‌های پشتیبانی‌شده

زبان‌های پشتیبانی‌شده برای مدل‌های Gemini را ببینید.

از ابزار زمینه URL استفاده کنید

شما می‌توانید از ابزار متن URL به دو روش اصلی استفاده کنید:

فقط ابزار زمینه URL

برای مشاهده محتوا و کد مخصوص ارائه‌دهنده در این صفحه، روی ارائه‌دهنده API Gemini خود کلیک کنید.

وقتی نمونه‌ی GenerativeModel را ایجاد می‌کنید، UrlContext به عنوان یک ابزار ارائه دهید. سپس، مستقیماً در اعلان خود، URL های خاصی را که می‌خواهید مدل به آنها دسترسی داشته باشد و آنها را تجزیه و تحلیل کند، ارائه دهید.

مثال زیر نحوه مقایسه دو دستور غذا از وب‌سایت‌های مختلف را نشان می‌دهد:

سویفت


import FirebaseAILogic

// Initialize the Gemini Developer API backend service
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Create a `GenerativeModel` instance with a model that supports your use case
let model = ai.generativeModel(
    modelName: "GEMINI_MODEL_NAME",
    // Enable the URL context tool.
    tools: [Tool.urlContext()]
)

// Specify one or more URLs for the tool to access.
let url1 = "FIRST_RECIPE_URL"
let url2 = "SECOND_RECIPE_URL"

// Provide the URLs in the prompt sent in the request.
let prompt = "Compare the ingredients and cooking times from the recipes at \(url1) and \(url2)"

// Get and handle the model's response.
let response = try await model.generateContent(prompt)
print(response.text ?? "No text in response.")

Kotlin


// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
val model = Firebase.ai(backend = GenerativeBackend.googleAI()).generativeModel(
    modelName = "GEMINI_MODEL_NAME",
    // Enable the URL context tool.
    tools = listOf(Tool.urlContext())
)

// Specify one or more URLs for the tool to access.
val url1 = "FIRST_RECIPE_URL"
val url2 = "SECOND_RECIPE_URL"

// Provide the URLs in the prompt sent in the request.
val prompt = "Compare the ingredients and cooking times from the recipes at $url1 and $url2"

// Get and handle the model's response.
val response = model.generateContent(prompt)
print(response.text)

Java


// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
                .generativeModel("GEMINI_MODEL_NAME",
                        null,
                        null,
                        // Enable the URL context tool.
                        List.of(Tool.urlContext(new UrlContext())));

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

// Specify one or more URLs for the tool to access.
String url1 = "FIRST_RECIPE_URL";
String url2 = "SECOND_RECIPE_URL";

// Provide the URLs in the prompt sent in the request.
String prompt = "Compare the ingredients and cooking times from the recipes at " + url1 + " and " + url2 + "";

ListenableFuture response = model.generateContent(prompt);
  Futures.addCallback(response, new FutureCallback() {
      @Override
      public void onSuccess(GenerateContentResponse result) {
          String resultText = result.getText();
          System.out.println(resultText);
      }

      @Override
      public void onFailure(Throwable t) {
          t.printStackTrace();
      }
  }, executor);

Web


import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance with a model that supports your use case
const model = getGenerativeModel(
  ai,
  {
    model: "GEMINI_MODEL_NAME",
    // Enable the URL context tool.
    tools: [{ urlContext: {} }]
  }
);

// Specify one or more URLs for the tool to access.
const url1 = "FIRST_RECIPE_URL"
const url2 = "SECOND_RECIPE_URL"

// Provide the URLs in the prompt sent in the request.
const prompt = `Compare the ingredients and cooking times from the recipes at ${url1} and ${url2}`

// Get and handle the model's response.
const result = await model.generateContent(prompt);
console.log(result.response.text());

Dart


import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_ai/firebase_ai.dart';
import 'firebase_options.dart';

// Initialize FirebaseApp
await Firebase.initializeApp(
  options: DefaultFirebaseOptions.currentPlatform,
);

// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
final model = FirebaseAI.googleAI().generativeModel(
  model: 'GEMINI_MODEL_NAME',
  // Enable the URL context tool.
  tools: [
    Tool.urlContext(),
  ],
);

// Specify one or more URLs for the tool to access.
final url1 = "FIRST_RECIPE_URL";
final url2 = "SECOND_RECIPE_URL";

// Provide the URLs in the prompt sent in the request.
final prompt = "Compare the ingredients and cooking times from the recipes at $url1 and $url2";

// Get and handle the model's response.
final response = await model.generateContent([Content.text(prompt)]);
print(response.text);

وحدت


using Firebase;
using Firebase.AI;

// Initialize the Gemini Developer API backend service
var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// Create a `GenerativeModel` instance with a model that supports your use case
var model = ai.GetGenerativeModel(
  modelName: "GEMINI_MODEL_NAME",
  // Enable the URL context tool.
  tools: new[] { new Tool(new UrlContext()) }
);

// Specify one or more URLs for the tool to access.
var url1 = "FIRST_RECIPE_URL";
var url2 = "SECOND_RECIPE_URL";

// Provide the URLs in the prompt sent in the request.
var prompt = $"Compare the ingredients and cooking times from the recipes at {url1} and {url2}";

// Get and handle the model's response.
var response = await model.GenerateContentAsync(prompt);
UnityEngine.Debug.Log(response.Text ?? "No text in response.");

یاد بگیرید که چگونه یک مدل را انتخاب کنیدمناسب برای مورد استفاده و برنامه شما.

برای مشاهده محتوا و کد مخصوص ارائه‌دهنده در این صفحه، روی ارائه‌دهنده API Gemini خود کلیک کنید.

شما می‌توانید هم زمینه URL و هم زمینه‌سازی را با جستجوی گوگل فعال کنید. با این پیکربندی، می‌توانید درخواست‌ها را با یا بدون URLهای خاص بنویسید.

وقتی قابلیت Grounding with Google Search نیز فعال باشد، مدل ممکن است ابتدا از Google Search برای یافتن اطلاعات مرتبط استفاده کند و سپس از ابزار URL context برای خواندن محتوای نتایج جستجو جهت درک عمیق‌تر اطلاعات استفاده کند. این رویکرد برای درخواست‌هایی که نیاز به جستجوی گسترده و تحلیل عمیق صفحات خاص دارند، قدرتمند است.

در اینجا چند مورد استفاده وجود دارد:

  • شما در اعلان، یک URL ارائه می‌دهید تا به برخی از پاسخ‌های تولید شده کمک کند. با این حال، برای تولید یک پاسخ مناسب، مدل هنوز به اطلاعات بیشتری در مورد موضوعات دیگر نیاز دارد، بنابراین از ابزار جستجوی پایه گوگل استفاده می‌کند.

    مثال:
    Give me a three day event schedule based on YOUR_URL . Also what do I need to pack according to the weather?

  • شما اصلاً آدرس اینترنتی (URL) را در اعلان ارائه نمی‌دهید. بنابراین، برای تولید پاسخ مناسب، مدل از ابزار جستجوی گوگل برای یافتن آدرس‌های اینترنتی مرتبط استفاده می‌کند و سپس از ابزار متن URL برای تجزیه و تحلیل محتوای آنها استفاده می‌کند.

    مثال:
    Recommend 3 beginner-level books to learn about the latest YOUR_SUBJECT .

مثال زیر نحوه فعال‌سازی و استفاده از هر دو ابزار - زمینه URL و زمینه‌سازی با جستجوی گوگل - را نشان می‌دهد:


import FirebaseAILogic

// Initialize the Gemini Developer API backend service
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Create a `GenerativeModel` instance with a model that supports your use case
let model = ai.generativeModel(
    modelName: "GEMINI_MODEL_NAME",
    // Enable both the URL context tool and Google Search tool.
    tools: [
      Tool.urlContex(),
      Tool.googleSearch()
    ]
)

// Specify one or more URLs for the tool to access.
let url = "YOUR_URL"

// Provide the URLs in the prompt sent in the request.
// If the model can't generate a response using its own knowledge or the content in the specified URL,
// then the model will use the grounding with Google Search tool.
let prompt = "Give me a three day event schedule based on \(url). Also what do I need to pack according to the weather?"

// Get and handle the model's response.
let response = try await model.generateContent(prompt)
print(response.text ?? "No text in response.")

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result


// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
val model = Firebase.ai(backend = GenerativeBackend.googleAI()).generativeModel(
    modelName = "GEMINI_MODEL_NAME",
    // Enable both the URL context tool and Google Search tool.
    tools = listOf(Tool.urlContext(), Tool.googleSearch())
)

// Specify one or more URLs for the tool to access.
val url = "YOUR_URL"

// Provide the URLs in the prompt sent in the request.
// If the model can't generate a response using its own knowledge or the content in the specified URL,
// then the model will use the grounding with Google Search tool.
val prompt = "Give me a three day event schedule based on $url. Also what do I need to pack according to the weather?"

// Get and handle the model's response.
val response = model.generateContent(prompt)
print(response.text)

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result


// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
                .generativeModel("GEMINI_MODEL_NAME",
                        null,
                        null,
                        // Enable both the URL context tool and Google Search tool.
                        List.of(Tool.urlContext(new UrlContext()), Tool.googleSearch(new GoogleSearch())));

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

// Specify one or more URLs for the tool to access.
String url = "YOUR_URL";

// Provide the URLs in the prompt sent in the request.
// If the model can't generate a response using its own knowledge or the content in the specified URL,
// then the model will use the grounding with Google Search tool.
String prompt = "Give me a three day event schedule based on " + url + ". Also what do I need to pack according to the weather?";

ListenableFuture response = model.generateContent(prompt);
  Futures.addCallback(response, new FutureCallback() {
      @Override
      public void onSuccess(GenerateContentResponse result) {
          String resultText = result.getText();
          System.out.println(resultText);
      }

      @Override
      public void onFailure(Throwable t) {
          t.printStackTrace();
      }
  }, executor);

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result


import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance with a model that supports your use case
const model = getGenerativeModel(
  ai,
  {
    model: "GEMINI_MODEL_NAME",
    // Enable both the URL context tool and Google Search tool.
    tools: [{ urlContext: {} }, { googleSearch: {} }],
  }
);

// Specify one or more URLs for the tool to access.
const url = "YOUR_URL"

// Provide the URLs in the prompt sent in the request.
// If the model can't generate a response using its own knowledge or the content in the specified URL,
// then the model will use the grounding with Google Search tool.
const prompt = `Give me a three day event schedule based on ${url}. Also what do I need to pack according to the weather?`

// Get and handle the model's response.
const result = await model.generateContent(prompt);
console.log(result.response.text());

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result


import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_ai/firebase_ai.dart';
import 'firebase_options.dart';

// Initialize FirebaseApp
await Firebase.initializeApp(
  options: DefaultFirebaseOptions.currentPlatform,
);

// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
final model = FirebaseAI.googleAI().generativeModel(
  model: 'GEMINI_MODEL_NAME',
  // Enable both the URL context tool and Google Search tool.
  tools: [
    Tool.urlContext(),
    Tool.googleSearch(),
  ],
);

// Specify one or more URLs for the tool to access.
final url = "YOUR_URL";

// Provide the URLs in the prompt sent in the request.
// If the model can't generate a response using its own knowledge or the content in the specified URL,
// then the model will use the grounding with Google Search tool.
final prompt = "Give me a three day event schedule based on $url. Also what do I need to pack according to the weather?";

final response = await model.generateContent([Content.text(prompt)]);
print(response.text);

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result


using Firebase;
using Firebase.AI;

// Initialize the Gemini Developer API backend service
var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// Create a `GenerativeModel` instance with a model that supports your use case
var model = ai.GetGenerativeModel(
  modelName: "GEMINI_MODEL_NAME",
  // Enable both the URL context tool and Google Search tool.
  tools: new[] { new Tool(new GoogleSearch()), new Tool(new UrlContext()) }
);

// Specify one or more URLs for the tool to access.
var url = "YOUR_URL";

// Provide the URLs in the prompt sent in the request.
// If the model can't generate a response using its own knowledge or the content in the specified URL,
// then the model will use the grounding with Google Search tool.
var prompt = $"Give me a three day event schedule based on {url}. Also what do I need to pack according to the weather?";

// Get and handle the model's response.
var response = await model.GenerateContentAsync(prompt);
UnityEngine.Debug.Log(response.Text ?? "No text in response.");

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result

یاد بگیرید که چگونه یک مدل را انتخاب کنیدمناسب برای مورد استفاده و برنامه شما.

نحوه کار ابزار زمینه URL

ابزار زمینه URL از یک فرآیند بازیابی دو مرحله‌ای برای ایجاد تعادل بین سرعت، هزینه و دسترسی به داده‌های تازه استفاده می‌کند.

مرحله ۱ : وقتی یک URL خاص ارائه می‌دهید، ابزار ابتدا تلاش می‌کند محتوا را از یک حافظه پنهان داخلی دریافت کند. این به عنوان یک حافظه پنهان بسیار بهینه عمل می‌کند.

مرحله ۲ : اگر یک URL در فهرست موجود نباشد (برای مثال، اگر صفحه بسیار جدیدی باشد)، ابزار به طور خودکار برای انجام یک واکشی زنده به عقب برمی‌گردد. این کار مستقیماً به URL دسترسی پیدا می‌کند تا محتوای آن را به صورت بلادرنگ بازیابی کند.

بهترین شیوه‌ها

  • ارائه URL های خاص : برای بهترین نتیجه، URL های مستقیم به محتوایی که می خواهید مدل آن را تجزیه و تحلیل کند، ارائه دهید. مدل فقط محتوا را از URL هایی که ارائه می دهید بازیابی می کند، نه هیچ محتوایی از لینک های تو در تو.

  • بررسی دسترسی‌پذیری : مطمئن شوید که URLهایی که ارائه می‌دهید به صفحاتی که نیاز به ورود دارند یا پشت دیوار پرداخت هستند، منتهی نمی‌شوند.

  • از آدرس کامل URL استفاده کنید : آدرس کامل URL، شامل پروتکل را ارائه دهید (برای مثال، به جای فقط example.com ، https://www.example.com ).

پاسخ را درک کنید

پاسخ مدل بر اساس محتوایی خواهد بود که از URLها بازیابی کرده است.

اگر مدل، محتوا را از URLها بازیابی کند، پاسخ شامل url_context_metadata خواهد بود. چنین پاسخی ممکن است چیزی شبیه به موارد زیر باشد (بخش‌هایی از پاسخ برای اختصار حذف شده‌اند):

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata":
      {
          "url_metadata":
          [
            {
              "retrieved_url": "https://www.example.com",
              "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
            },
            {
              "retrieved_url": "https://www.example.org",
              "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
            },
          ]
        }
    }
  ]
}

بررسی‌های ایمنی

سیستم، بررسی تعدیل محتوا را روی URL انجام می‌دهد تا تأیید کند که استانداردهای ایمنی را رعایت می‌کند. اگر URL ارائه شده توسط شما در این بررسی رد شود، url_retrieval_status به صورت URL_RETRIEVAL_STATUS_UNSAFE دریافت خواهید کرد.

محدودیت‌ها

در اینجا برخی از محدودیت‌های ابزار URL context آورده شده است:

  • ترکیب با فراخوانی تابع : ابزار زمینه URL را نمی‌توان در درخواستی که از فراخوانی تابع نیز استفاده می‌کند، استفاده کرد.

  • محدودیت آدرس‌های اینترنتی به ازای هر درخواست : حداکثر تعداد آدرس‌های اینترنتی به ازای هر درخواست، ۲۰ آدرس اینترنتی است.

  • محدودیت اندازه محتوای URL : حداکثر اندازه محتوای بازیابی شده از یک URL واحد ۳۴ مگابایت است.

  • تازگی : این ابزار نسخه‌های زنده صفحات وب را دریافت نمی‌کند ، بنابراین ممکن است مشکلاتی در مورد تازگی یا احتمالاً اطلاعات قدیمی وجود داشته باشد.

  • دسترسی عمومی به URL : URL های ارائه شده باید به صورت عمومی در وب قابل دسترسی باشند. موارد زیر پشتیبانی نمی‌شوند : محتوای پولی، محتوایی که نیاز به ورود کاربر دارد، شبکه‌های خصوصی، آدرس‌های میزبان محلی (مانند localhost یا 127.0.0.1 ) و سرویس‌های تونلینگ (مانند ngrok یا pingggy).

انواع محتوای پشتیبانی‌شده و پشتیبانی‌نشده

پشتیبانی‌شده : این ابزار می‌تواند محتوا را از 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 )

  • پی‌دی‌اف ( application/pdf )

پشتیبانی نمی‌شود : این ابزار از انواع محتوای زیر پشتیبانی نمی‌کند :

  • ویدیوهای یوتیوب (به جای آن، به بخش «ویدیوهای تحلیلی » مراجعه کنید)

  • فایل‌های ویدیویی و صوتی (به جای آن، به بخش «آنالیز ویدیوها» یا «آنالیز صدا» مراجعه کنید)

  • فایل‌های فضای کاری گوگل، مانند اسناد گوگل یا صفحات گسترده

  • (در صورت استفاده از Vertex AI Gemini API ) آدرس‌های اینترنتی Cloud Storage
    این نوع URLها توسط رابط برنامه‌نویسی Gemini Developer پشتیبانی نمی‌شوند، فرقی نمی‌کند از چه طریقی به آن دسترسی پیدا کنید.

  • محتوایی که به صورت عمومی قابل دسترسی نیست. موارد زیر پشتیبانی نمی‌شوند : محتوای دارای دیوار پرداخت، محتوایی که نیاز به ورود کاربر دارد، شبکه‌های خصوصی، آدرس‌های میزبان محلی (مانند localhost یا 127.0.0.1 ) و سرویس‌های تونل‌زنی (مانند ngrok یا pingggy).

توکن‌های ابزار قیمت‌گذاری و شمارش

محتوای بازیابی شده از 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، به مستندات ارائه‌دهنده API Gemini انتخابی خود مراجعه کنید: Gemini Developer API |Vertex AI Gemini API .