把 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_id | PDF、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.action | name | kind | 結果 |
|---|---|---|---|
search | deepseek_web_search | 思考時為 deep_search,否則 search | web_search_tool_result |
open_page | deepseek_web_search | deep_search | web_fetch_tool_result。data 是空字串。沒有 signature |
find_in_page | deepseek_web_search | deep_search | 形狀相同。title 為 null。不計費 |
read_link | deepseek_read_url | read_link | web_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_score | 0 到 3。指南把 1.5 及以上視為高質量 |
authority | 0 到 4。−1 表示未知。3 及以上為高權威 |
snippet / summary | 短的給介面,長的給模型 |
content | need_content 不為 true,或頁面沒有內容時,為空字串 |
date | RFC 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 |
|---|---|
| Messages | stop_reason 為 refusal,stop_details.type 為 refusal。非流式會去掉思考和答案文字,保留工具塊和一個空的 text 塊 |
| Responses | status 為 incomplete,incomplete_details.reason 為 content_filter。output 只保留已執行的 web_search_call |
| Chat | finish_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
- 請求體是
deepseek-flash。Messages 的工具同時有type和name。想要帶引用的搜尋時,思考為disabled。 - 面向公眾的應用傳送
safety_check.levelhigh。這些呼叫的response_format和text.format保持text。 - 解析器用
tool_use_id和kind配對,並把signature留到下一輪。 - 帳單使用
tool_search、tool_fetch、tool_image_search,加上快取未命中輸入、快取命中輸入和輸出。不要把web_search_requests加進去。 - 獨立介面的
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。