DeepSeek 11 月 13 日開放應用工具之後,deepseek-flash 的 JSON 該如何宣告 deepseek_web_search、deepseek_read_url 和 safety_check,並把 tool_search 與 token 分開記帳?

只改模型名不會開啟搜尋。tools、thinking 和 safety_check 決定 JSON。計費次數是 tool_search。

把 model 寫成 deepseek-flash 並不會開啟搜尋。 2026 年 11 月 13 日,DeepSeek 把聊天應用背後的工具放到了 API 上。模型名 deepseek-flash 對應 DeepSeek-V4.1-Flash-1017。舊名 deepseek-v4-flash 和 deepseek-v4-flash-vision-exp 仍會轉到這裡,並按 Flash 價格計費。上下文 100 萬 token。最大輸出 38.4 萬。思考模式是預設值。

本文寫於 2026 年 11 月 16 日,依據 11 月 13 日的更新日誌、網頁工具指南、Search 與 Fetch 指南、安全指南和價格頁。三天前我們寫過 Gemini 4 Carbon 的 usage。這裡會改請求和帳單的欄位是 tools、thinking、safety_check 和 usage.server_tool_use。

11 月 13 日開放了什麼

同一個模型在三個端點接受這些工具。Messages 是 POST https://api.deepseek.com/anthropic/v1/messages,頭為 x-api-key。Responses 是 POST https://api.deepseek.com/responses。Chat Completions 是 POST https://api.deepseek.com/chat/completions。後兩個用 Authorization: Bearer。Search、Fetch、OCR、ASR、TTS 也可以單獨呼叫。搜圖不在 POST /v1/tools/search,只在 deepseek_web_search 裡面。

能力開啟它的 JSON返回什麼
網頁搜尋deepseek_web_search,思考關閉模型自行決定是否搜尋,並給出引用
深度思考搜尋deepseek_web_search,思考開啟search、open_page、find_in_page,大約 20 次呼叫
讀連結deepseek_read_url只看最後一條使用者訊息,最多前 10 個不同 URL
安全safety_check.level = high審查輸入和輸出。面向公眾的服務需要開啟
檔案Files API 的 file_idPDF、Office 和圖片先解析,再進入對話

三個端點的請求 JSON

Messages 要把工具名寫兩遍:type 和 name。Responses 和 Chat 只寫 type。tool_choice 不能點名這些工具,否則 400,deepseek_web_search cannot be forced。tool_choice 為 none 會關掉全部已宣告的網頁工具,包括讀連結。Responses 和 Chat 裡,required 被當成 auto。

不要傳 allowed_domains、blocked_domains 或 user_location。不要把同一個工具宣告兩次。不要再混入別的服務端工具。錯誤資訊寫明,其他工具目前不能與 deepseek_web_search、deepseek_read_url、safety_check 或 title 一起用。Responses 上,web_search 工具以及非 text 的 text.format 都會 400。Chat 上,web_search_options 以及非 text 的 response_format 都會 400。結構化 JSON 和這些網頁工具不能放在同一次請求裡。把你自己的 schema 放到下一次呼叫。見 什麼是結構化輸出。

關閉思考是帶引用的搜尋。開啟思考是深度思考搜尋。兩者同時開啟時,這一輪不會再跑 deepseek_read_url。讀連結發生在思考關閉時,或只宣告了 deepseek_read_url 時。Messages 和 Chat 用 thinking.type 的 disabled 或 enabled。Responses 文件裡,深度思考搜尋的示例把 reasoning.effort 設為 high。

{
  "model": "deepseek-flash",
  "thinking": {
    "type": "disabled"
  },
  "safety_check": {
    "level": "high"
  },
  "tools": [
    {
      "type": "deepseek_web_search",
      "name": "deepseek_web_search"
    },
    {
      "type": "deepseek_read_url",
      "name": "deepseek_read_url"
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "What changed in the DeepSeek API on 13 November 2026?"
    }
  ]
}

Responses,深度思考搜尋:

{
  "model": "deepseek-flash",
  "reasoning": {
    "effort": "high"
  },
  "safety_check": {
    "level": "high"
  },
  "tools": [
    {
      "type": "deepseek_web_search"
    },
    {
      "type": "deepseek_read_url"
    }
  ],
  "input": "Which official page states the height of Tokyo Tower?"
}

塊、kind 和引用

Messages 裡,每次呼叫是一個 server_tool_use 塊加一個結果塊。用 tool_use_id 配對。串流回應裡,兩種塊都在 content_block_start 一次到齊。最終 usage 讀 message_delta。message_start 裡的 usage 只覆蓋第一步推理。

input.actionnamekind結果
searchdeepseek_web_search思考時為 deep_search,否則 searchweb_search_tool_result
open_pagedeepseek_web_searchdeep_searchweb_fetch_tool_result。data 是空字串。沒有 signature
find_in_pagedeepseek_web_searchdeep_search形狀相同。title 為 null。不計費
read_linkdeepseek_read_urlread_linkweb_fetch_tool_result,另有 signature

搜圖把 kind 設為 image_search 或 deep_image_search。queries 是空陣列。結果裡可能多一個僅供展示的 image_url。Messages 的引用在 text 塊上,型別為 web_search_result_location。cited_text 是該塊的答案文字,不是網頁原文。encrypted_index 始終是空字串。一個塊裡同一個 URL 最多出現一次。流式裡以 citations_delta 到達。

Responses 把呼叫放在 web_search_call,帶 kind 和 action。答案是帶 url_citation 標註的 output_text。start_index 和 end_index 按 Unicode 碼位計數。Chat 把呼叫放在 message.server_tool_calls。每一步有 reasoning_content 和 calls。message.content 裡沒有引用標記。引用在 message.annotations。message.reasoning_content 只有最後一步。

用過這些工具的回覆不能續寫,API 返回 400,並要求重發上一次請求。下一輪要把助手內容原樣傳回,包括 kind 和 signature。搜尋摘要和更早的思考不會進入後續上下文,只有答案文字會。讀到的頁面從 signature 恢復。read_link 的 data 始終是空字串。丟掉 signature 請求仍會成功,但頁面不在了。抓取失敗的 error_code 是 url_not_accessible、url_not_allowed、unavailable。url_not_allowed 也包括沒透過安全審查的頁面。

一條 Responses 搜尋項:

{
  "type": "web_search_call",
  "id": "srvtoolu_s_00_3f2a9c",
  "status": "completed",
  "kind": "search",
  "action": {
    "type": "search",
    "queries": [
      "DeepSeek API 13 November 2026"
    ],
    "sources": [
      {
        "type": "url",
        "url": "https://example.com/news",
        "title": "Change log",
        "snippet": "Web search and URL reading are now API tools.",
        "published_at": "2026-11-13T00:00:00+00:00"
      }
    ]
  }
}

獨立的 Search 與 Fetch JSON

由程式碼而不是模型決定何時搜尋時,呼叫原始 JSON API。Search 是 POST https://api.deepseek.com/v1/tools/search。query 必填,1 到 128 個字元,不能全是空白。count 為 1 到 50,預設 10。ori_question 可選,同樣 1 到 128 個字元。localization 是可選 IP。need_content 預設 false。未知欄位會被忽略。可以原樣傳過去的運算子:site:、-site:、-、-"..."、"..."、lang:、after:、before:。

{
  "query": "DeepSeek site:api-docs.deepseek.com after:2026-11-01",
  "count": 10,
  "need_content": false
}

Fetch 是 POST https://api.deepseek.com/v1/tools/fetch。唯一欄位是 url,最長 8,192 個字元,必須是帶主機的 HTTP 或 HTTPS,不能帶使用者名稱或密碼。響應是 title 和 Markdown 的 content。沒有標題時 title 是空字串。

{
  "url": "https://api-docs.deepseek.com/updates"
}
欄位要存下來的含義
rerank_score0 到 3。指南把 1.5 及以上視為高質量
authority0 到 4。−1 表示未知。3 及以上為高權威
snippet / summary短的給介面,長的給模型
contentneed_content 不為 true,或頁面沒有內容時,為空字串
dateRFC 3339 的 UTC 時間,或 null

file_id、OCR 和語音 JSON

檔案輸入分兩步。POST https://api.deepseek.com/files,purpose 必須寫在 file 前面。text_recognition 丟掉圖表。rich_layout_recognition 把圖裁進正文,並消耗影象 token。檔案物件只在解析完成後返回。id 形如 file-api-...。客戶端斷開不會取消隨後成功的解析:檔案會被儲存並計費。原文和解析結果都不能下載。Chat Completions 這樣引用:

{
  "role": "user",
  "content": [
    {
      "type": "file",
      "file_id": "file-api-xxxxxxxxxxxxxxxx"
    },
    {
      "type": "text",
      "text": "Summarize the revenue chart."
    }
  ]
}

Messages 需要頭 anthropic-beta: files-api-2025-04-14,以及 source.type 為 file 的 document 塊。Responses 用 input_file 和 file_id。解析過的文件不能當成圖片塊。也不能在對話請求裡直接貼檔案位元組或檔案 URL。一次請求最多引用 20 個文件,正文合計最多 8 MiB。後續輪次會保留完整解析結果。太長則 400。不會悄悄截斷。

限制:PDF、Word、PowerPoint 和常見圖片,按檔案內容識別格式。100 MiB,更大返回 413。1,000 頁。上傳 120 秒,否則 408。解析 120 秒,否則 504。每個帳號同時進行的文件上傳為 15 個。加密檔案返回 400。純文字、csv、json、原始碼、xlsx、xls、epub、mobi 用 purpose user_data,不按頁計費。這些檔案最大 32 MiB,文字最大 8 MiB。不支援 AZW3 和帶 DRM 的電子書。

解析成功才按頁計費,每 1,000 頁 0.225 美元,只收一次。之後的對話按輸入 token 計費,不再按頁。OCR 同樣是這個頁價,端點 POST /v1/tools/ocr,不進入 Files API。它是 multipart,欄位為 file 和 purpose,不是 JSON 體。ASR 是 multipart 音訊,不是 JSON。TTS 是 JSON,POST /v1/tools/tts:

TTS 標價為每 1 萬字元 0.45 美元,公佈的限時價為 0.225 美元。一個漢字算 2 個字元,其他字元算 1。聲音為 stella(預設)和 tide。沒有語言欄位。ASR 標價為每小時音訊 0.116 美元,限時 0.058 美元,按秒計費,不足 1 秒按 1 秒。價格頁沒有寫半價的結束日期。

{
  "text": "Hello from DeepSeek.",
  "voice_id": "stella",
  "format": "wav",
  "filter_markdown": true
}

safety_check 和拒絕 JSON

對外開放的服務要把 safety_check 設為 {"level":"high"}。low 等於省略該欄位。其他 level 返回 400。這個參數不代替你自己的內容審查、備案和標識義務。輸入未透過返回 400 Content Exists Risk。這些輸入 token 仍會計費,按快取命中價。模型生成結束後連線不會馬上關掉,服務端還要審查完整輸出。已經流出的文字收不回來。把已展示的答案換成你自己的拒絕提示。拒絕前消耗的 token 會計費。審查 token 含在輸出 token 裡,並單獨出現在 Messages 和 Responses 的 usage.output_tokens_details.safety_tokens,或 Chat 的 usage.completion_tokens_details.safety_tokens。被攔截的圖片可能給出路徑,例如 messages.1.content.0,位置在 stop_details.explanation、refusal 內容項或 message.refusal。宣告了網頁工具但沒寫 safety_check 的請求,仍可能以拒絕結束。

API拒絕時的 JSON
Messagesstop_reason 為 refusal,stop_details.type 為 refusal。非流式會去掉思考和答案文字,保留工具塊和一個空的 text 塊
Responsesstatus 為 incomplete,incomplete_details.reason 為 content_filter。output 只保留已執行的 web_search_call
Chatfinish_reason 為 content_filter。content 是空字串。annotations 省略。server_tool_calls 保留,每一步的思考被清空

記 tool_search,不要記 web_search_requests

token 和工具分開記帳。Flash 價格按每 100 萬 token。尖峰時段是週一到週五 UTC 01:00–04:00 和 06:00–10:00,不含中國法定節假日。其餘時間都是離峰,週末和中國法定節假日全天離峰。離峰是尖峰的一半。cache_creation_input_tokens 始終為 0。

時段快取命中 / 100 萬快取未命中 / 100 萬輸出 / 100 萬
離峰$0.003$0.15$0.60
尖峰$0.006$0.30$1.20

搜尋和網頁抓取都是每 1,000 次成功呼叫 0.75 美元,無論是模型呼叫工具,還是你自己呼叫 /v1/tools/search 或 /v1/tools/fetch。有結果的工具搜尋按 query 計費,三條 query 算三次。count 不改變 Search API 的單價。HTTP 200 且 results 為空陣列時不計費。Fetch 只有在返回頁面內容時才計費。安全審查隨後把頁面換成 url_not_allowed 或 unavailable 的,這次抓取已經發生,仍要計費。深度思考搜尋裡再次開啟同一頁不計費。find_in_page 不計費。

Search 每個帳號每秒 100 次。Fetch 為 25 次,另外還有每個域名的上限。上限按帳號而不是按金鑰,並且與 Flash 的 2,500 併發分開。網頁工具指南里,一次帶兩條 query 的引用搜尋報告 web_search_requests 為 1、tool_search 為 2。要存的是 tool_search、tool_fetch、tool_image_search。不要再把 web_search_requests 加進去。Responses 和 Chat 在這三項都是 0 時會省略 server_tool_use 裡的這一組。thinking_tokens 在開啟思考時出現。safety_tokens 在 safety_check 為 high 時出現。兩者都已經包含在輸出 token 總數里。

如果 HTTP 狀態已經是 200,生成中途失敗,響應體是錯誤加 usage。Messages 流式以 error 事件結束,後面沒有 message_delta。要檢查響應體。SDK 不會因為狀態 200 拋異常。下面是那次兩條 query 的公開示例。thinking_tokens 和 safety_tokens 不在這個物件裡。思考開啟時,或 safety_check 為 high 時,它們會單獨出現,並且已經含在 output_tokens 裡:

{
  "input_tokens": 1905,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 0,
  "output_tokens": 72,
  "service_tier": "standard",
  "server_tool_use": {
    "web_search_requests": 1,
    "web_fetch_requests": 0,
    "tool_search": 2,
    "tool_fetch": 0,
    "tool_image_search": 0
  }
}

上線前要核對的 JSON

  1. 請求體是 deepseek-flash。Messages 的工具同時有 type 和 name。想要帶引用的搜尋時,思考為 disabled。
  2. 面向公眾的應用傳送 safety_check.level high。這些呼叫的 response_format 和 text.format 保持 text。
  3. 解析器用 tool_use_id 和 kind 配對,並把 signature 留到下一輪。
  4. 帳單使用 tool_search、tool_fetch、tool_image_search,加上快取未命中輸入、快取命中輸入和輸出。不要把 web_search_requests 加進去。
  5. 獨立介面的 query 為 1 到 128 個字元。count 為 1 到 50。空結果不是一筆費用。

在本地用 JSON 校驗、JSONPath($.usage.server_tool_use.tool_search)和 JSON 對比 核對上一份請求。資料不會上傳。

常見問題

開啟 thinking 會改變搜尋嗎?

會。thinking.type 為 disabled 時是一次帶引用的網頁搜尋,kind 為 search。enabled 是深度思考搜尋:search、open_page、find_in_page,大約 20 次呼叫,kind 為 deep_search。思考模式是預設值。思考和 deepseek_web_search 同時開啟時,這一輪不會再跑 deepseek_read_url。

tool_choice 能強制 deepseek_web_search 嗎?

不能。點名這個工具會返回 400,deepseek_web_search cannot be forced。是否搜尋由模型決定。tool_choice 為 none 會關掉已宣告的網頁工具,包括讀連結。Responses 和 Chat 裡,required 被當成 auto。

帳單該用 web_search_requests 嗎?

不該。這個數包含錯誤,只用於展示。計費欄位是 tool_search、tool_fetch、tool_image_search。網頁工具指南里,一次搜尋塊帶兩條 query,報告 web_search_requests 為 1、tool_search 為 2。有結果的搜尋按 query 條數計費。空結果或失敗不計費。

POST /v1/tools/search 能搜圖嗎?

不能。搜圖只在 deepseek_web_search 裡。kind 為 image_search 或 deep_image_search,queries 是空陣列。每張圖算 1 次搜尋,模型在圖上圈出的每個區域再算 1 次。

面向公眾的服務該怎麼寫安全檢查?

DeepSeek 寫明面向公眾的服務要開啟 safety_check,level 為 high。low 等於不寫這個欄位。輸入未透過返回 400 Content Exists Risk,這些輸入 token 仍按快取命中價計費。拒絕的答案是 stop_reason 為 refusal,Responses 為 incomplete 且 content_filter,Chat 為 finish_reason content_filter。

搜過的回覆能續寫嗎?

不能。用過 deepseek_web_search 或 deepseek_read_url 的回覆會返回 400。請重發上一次請求。下一輪要把助手塊原樣傳回,包括 kind 和 signature。沒有有效 signature 時請求仍會成功,但頁面不會回到上下文。

小結

11 月 13 日的工具改的是請求、你必須存下的塊,以及帳單上的另一行。 在 deepseek-flash 上宣告 deepseek_web_search 和 deepseek_read_url。帶引用的搜尋關掉思考,深度思考搜尋開啟思考。面向公眾的應用把 safety_check.level 設為 high。記 tool_search,不要記 web_search_requests。