شخصی‌سازی موتور جستجوی گوگل

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

# © Mehdi Rezghi — نصب کتابخانهٔ درخواست‌های وب
pip install requests

این برنامه هر جستجو را انجام می‌دهد و نتیجه‌اش را در یک فایل CSV ذخیره می‌کند تا بعداً بتوانیم تحلیلش کنیم:

# © 2026 Mehdi Rezghi — https://t.me/Mehdirezghi
# جستجوگر لاگ‌گیر گراول
import requests, csv, time
from datetime import datetime

API_KEY = "YOUR_API_KEY"
CX_ID   = "YOUR_CX_ID"
ENDPOINT = "https://www.googleapis.com/customsearch/v1"

def search(query, **filters):
    params = {"key": API_KEY, "cx": CX_ID, "q": query}
    params.update(filters)          # مثلاً fileType="pdf", dateRestrict="m1"
    r = requests.get(ENDPOINT, params=params, timeout=15)
    r.raise_for_status()
    return r.json()

def log_search(query, **filters):
    data  = search(query, **filters)
    total = data.get("searchInformation", {}).get("totalResults", "0")
    items = data.get("items", [])
    top3  = " | ".join(i.get("link", "") for i in items[:3])

    with open("search_log.csv", "a", newline="", encoding="utf-8") as f:
        w = csv.writer(f)
        w.writerow([
            datetime.now().isoformat(timespec="seconds"),
            query, str(filters), total, len(items), top3
        ])
    print(f"✔ '{query}' → کل نتایج: {total} | برگشتی: {len(items)}")

if __name__ == "__main__":
    log_search("یادگیری ماشین", fileType="pdf", dateRestrict="y1")

یک لاگ خوب باید بعداً به پرسش‌هایمان جواب بدهد. برای هر جستجو دست‌کم این‌ها را نگه دارید:

برای سنجش کیفیت، دو معیار سادهٔ حرفه‌ای کافی است:

• دقت (Precision): از ده نتیجهٔ اول، چند تا واقعاً به کار آمدند؟ اگر ۸ تا مفید بود، دقت شما ۸۰٪ است.
• نرخ نتیجهٔ خالی: چند درصد جستجوها هیچ نتیجه‌ای برنگرداندند؟ این‌ها را باید بازطراحی کنید.

«بهینه‌سازی بازگشتی» یعنی یک چرخهٔ تکرارشونده که هر دور، موتور را کمی بهتر می‌کند:

و بعد دوباره از قدم ۱ شروع می‌کنید. چند نمونه از «اصلاح» در قدم ۴:

پایش: در Google Cloud Console به بخش API Dashboard بروید تا مصرف روزانه‌تان را ببینید. برای پایش دقیق‌تر می‌توانید در Cloud Operations روی سرویس customsearch.googleapis.com هشدار (Alert) تنظیم کنید.

خطای فشار (Rate limit): اگر زیادی سریع درخواست بفرستید، گوگل خطای 429 می‌دهد. راه درست، «عقب‌نشینی نمایی» است: کمی صبر کن، اگر باز خطا داد صبر را دو برابر کن.

# © Mehdi Rezghi — عقب‌نشینی نمایی هنگام خطای فشار
import time, requests

def safe_search(query, **filters):
    delay = 1
    for attempt in range(5):
        try:
            return search(query, **filters)
        except requests.HTTPError as e:
            if e.response.status_code == 429:
                print(f"⏳ فشار زیاد؛ {delay} ثانیه صبر…")
                time.sleep(delay)
                delay *= 2        # 1 → 2 → 4 → 8 …
            else:
                raise
    raise RuntimeError("بعد از چند تلاش، همچنان خطای فشار.")