راهنمای DeepSeek Search و Fetch: جستجوی وب برای ایجنتها با ۰.۷۵ دلار به ازای هر هزار درخواست

TL;DR — DeepSeek دو API عمومی داد: POST /v1/tools/search (جستجوی وب با موتور خودش) و POST /v1/tools/fetch (یک صفحه، خروجی Markdown). هر دو ۰.۷۵ دلار به ازای هر ۱۰۰۰ درخواست موفق، با QPS 5 و احراز هویت bearer همان API عادی. برای ایجنت و RAG که تا حالا دنبال جایگزین ارزان جستجوی وب بود.

چرا این خبر مهمه

تا حالا اگر ایجنت میساختی و به وب نیاز داشتی، انتخابها محدود بود: APIهای جستجو گرون یا محدود، یا scrap کردن دستی. دیپسیک با انتشار مدل DeepSeek-V4.1-Flash-1017 (۱۷ اکتبر ۲۰۲۶) اعلام کرد Search & Fetch «برای همه باز شد» — چیزی که قبلاً فقط از طریق ابزارهای سمت سرور در DeepSeek Harness و Claude Code و Codex در دسترس بود.

نکتهی مهم: اینها API خام JSON هستن، نه wrapper روی یک مدل. یعنی میتونی مستقیم از curl یا هر زبانی صداشون کنی، بدون اینکه مدل وسط باشه. کسی که API خودش رو یکبار صدا زده، در چند دقیقه این هم راه میاندازه.

Search API: جستجو با عملگرها

Endpoint: POST https://api.deepseek.com/v1/tools/search

curl https://api.deepseek.com/v1/tools/search \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "DeepSeek V4 release",
    "count": 5,
    "need_content": true
  }'

پارامترهای اصلی:

• query — الزامی، حداکثر ۱۲۸ کاراکتر یونیکد.
• count — تعداد نتایج، ۱ تا ۵۰ (پیشفرض ۱۰). روی قیمت اثری نداره؛ قیمت per-request است.
• need_content — اگر true باشه محتوای کامل صفحه هم برمیگرده؛ پیشفرض false و فیلد content خالی میمونه.
• localization — یک IP اختیاری برای محلیسازی نتایج.

عملگرهای جستجو که مستقیم در query کار میکنن:

| عملگر | مثال | کار | | --- | --- | --- | | site: / -site: | site:github.com OR site:huggingface.co | محدود/حذف یک دامنه | | - و -"..." | -advertisement -"release notes" | حذف کلمه یا عبارت دقیق | | "..." | "exact phrase" | عبارت دقیق | | lang: | lang:zh,en | محدود به زبانها | | after: / before: | after:2026-01-01 | محدود به بازهی انتشار |

نکتهی کلیدی برای کیفیت: هر نتیجه یک rerank_score از ۰ تا ۳ داره (بالای ۱.۵ یعنی کیفیت خوب) و یک فیلد authority از ۰ تا ۴ که منابع خیلی معتبر ۳ به بالا میگیرن. اگر داری خروجی رو فیلتر میکنی برای RAG، این دو عدد بهترین معیارن.

Fetch API: یک URL، خروجی Markdown

Endpoint: POST https://api.deepseek.com/v1/tools/fetch — درخواست فقط یک فیلد url میخواد (حداکثر ۸۱۹۲ کاراکتر، HTTP/HTTPS، بدون username/password):

پاسخ ساده است:

یعنی دیگه لازم نیست خودت HTML رو پاکسازی کنی تا Markdown بگیری — سرور این کار را میکنه. برای pipeline ایجنت این یعنی یک مرحلهی کمتر.

خطاها و محدودیتها که باید بشناسی

جدول خطاهای HTTP طبق مستندات رسمی:

| کد | معنی | | --- | --- | | 402 | موجودی حساب کافی نیست | | 403 | درخواست Fetch توسط سیاست امنیتی رد شد | | 404 | محتوای قابل استخراج نبود (صفحه در دسترس نبود، بلاک بود، یا Markdown قابل استخراج نداشت) | | 429 | عبور از حد QPS | | 504 | خطای سمت upstream |

محدودیتها: هر دو API مستقل از هم برای هر حساب QPS = 5 دارن (ترافیک یکی دیگری را مصرف نمیکند)، و Fetch علاوه بر آن یک محدودیت QPS per-domain هم دارد — اگر داری ۵۰ صفحهی یک سایت را fetch میکنی، با 429 مواجه میشی؛ بین درخواستها فاصله بگذار یا روی چند دامنه پخش کن.

قیمتمندی و یک پنجرهی رایگان

هر دو endpoint ۰.۷۵ دلار به ازای هر ۱۰۰۰ درخواست موفق هستند — و «موفق» یعنی HTTP 200 با نتیجهی واقعی: Search باید آرایهی غیرخالی برگردونه، Fetch باید محتوا بده. درخواست ناموفق، نتیجهی خالی، و timeout صورت حساب نمیشن. این مدل billing per-request خیلی تمیزتر از پرداخت به ازای توکن برای اسناده.

پنجرهی رایگان: وقتی از DeepSeek API داخل DeepSeek Harness، Claude Code، یا Codex استفاده میکنی، فراخوانیهای ابزار سمت سرور همین الان به این دو API میخورن و فعلاً رایگانن. صورت حسابی شدن از ۱۵:۳۰ UTC روز ۳۱ اکتبر ۲۰۲۶ (۰۰:۰۰ به وقت پکن، ۱ نوامبر) شروع میشه.

چکلیست راهاندازی

• [ ] کلید API دیپسیک آماده کن و در متغیر محیطی بذار (نه هاردکد)
• [ ] یک تابع wrapper بنویس که 429 را با backoff هندل کنه (QPS 5 فراموش نشه)
• [ ] برای Search، need_content را فقط وقتی true کن که واقعاً متن کامل لازم داری
• [ ] نتایج Search را با rerank_score >= 1.5 و authority >= 3 فیلتر کن
• [ ] برای Fetch انبوه از یک دامنه، فاصلهگذاری بین درخواستها بذار (per-domain limit)
• [ ] لاگ کن چند درخواست موفق داشتی — billing per-request است و باید قابل audit باشه
• [ ] اگر تا ۳۱ اکتبر میرسی، پنجرهی رایگان حالت ابزار سمت سرور را برای تست استفاده کن

Q: تفاوت این با web search داخل چت خود دیپسیک چیه؟

اینها API خام و مستقل از مدل هستن برای برنامههای خودت — ایجنت، RAG، pipeline. جستجوی داخل اپ/چت دیپسیک برای کاربر نهایی اون پلتفرمه. اینجا تو مستقیم JSON میگیری و خودت تصمیم میگیری چی باهاش کنی.

Q: اگه فیلد content در نتایج Search خالی بود چی؟

یعنی need_content را false گذاشتی (پیشفرض) یا محتوا در دسترس نبود. برای متن کامل، یا need_content: true بفرست، یا URL نتیجه را با Fetch API بگیر.

Q: خطای 404 Fetch یعنی لینک خرابه؟

نه لزوماً. طبق مستندات 404 یعنی «محتوای قابل استخراج نبود» — ممکنه صفحه در دسترس باشه ولی بلاک شده، content type پشتیبانی نشه، یا اصلاً Markdown قابل استخراج نداشته باشه (مثلاً یک اپ تکصفحهای جاوااسکریپتی).

منابع

• https://api-docs.deepseek.com/guides/search/
• https://api-docs.deepseek.com/news/news261017/
• https://news.ycombinator.com/item?id=50138531
• https://huggingface.co/deepseek-ai/DeepSeek-V4.1-Flash-1017