API 相容的模型服務有一項不起眼但關鍵的工作：將多種公開請求格式轉換為模型確切期待的提示詞，然後將生成的 Token 轉回客戶端期待的回應形狀。deepseek-recipe 為 DeepSeek V4 和 V4.1 封裝了該轉換層。

它不運行模型。它不開啟 HTTP 端口、執行工具、搜尋網頁或儲存對話。在本教學中明確保持該界線可見將節省時間：輸出是一個渲染後的提示詞，可由推論後端使用，而非模型答案。

安裝 Python 綁定

官方套件需要 Python 3.10 或更新版本：

python3 -m pip install deepseek-recipe

為了可重現的專案，請在虛擬環境內安裝，並在首次驗證運行後固定版本。儲存庫於 2026 年 9 月新發布，其 API 可能仍在演變。記錄 Python 套件版本以及應用程式選取的 V4/V4.1 編碼。

該套件由一系列 Rust crates 支援。Python 用戶無需將服務重寫為 Rust；綁定提供正常整合所需的轉換和編碼類型。

渲染最小化 V4.1 對話

基於官方範例建立一個小型腳本：

from deepseek_recipe import (
    ChatCompletionRequest,
    ConversionOptions,
    DeepseekV41Encoding,
)

request = ChatCompletionRequest({
    "model": "deepseek-flash",
    "messages": [
        {"role": "system", "content": "Answer with one short paragraph."},
        {"role": "user", "content": "Explain sparse attention to a Python developer."},
    ],
    "temperature": 0.2,
})

converted = request.convert(ConversionOptions())
encoding = DeepseekV41Encoding()
rendered = encoding.render_conversation(converted.conversation)

print(rendered.prompt)

這裡有兩個刻意分離的階段。request.convert(...) 將 Chat Completions 負載映射到函式庫的共享 Conversation 表示。render_conversation(...) 應用 V4.1 提示詞編碼。保持它們分離允許 API 服務在確定使用模型特定的 Token 佈局之前標準化不同的外部協議。

請求中的模型字串是面向客戶端負載的一部分；選取的編碼物件控制標準化對話如何渲染。不要推斷任何任意模型名稱會自動下載或選取權重。周邊服務必須驗證請求的模型並將提示詞路由到適當的後端。

Try DeepSeek on MidassAI

在連接推論前檢查

僅在本地開發測試案例中列印提示詞，切勿在包含用戶數據的生產環境日誌中列印。確認系統和用戶消息以預期順序表示。添加 Unicode、空內容和多行範例。如果您的服務支援圖片或工具，請為每種情況建立單獨的測試案例，而不是假設僅文字案例證明相容性。

這也是進行基準測試的正確時機。儲存一組小型的非敏感輸入負載和批准的結構預期。exact encoded output 可能會跨套件版本正常變更，所以決定版本升級是否應更新快照或失敗直到審查。

至少測試：

一個系統和一個用戶消息；
包含助手回應的多輪對話；
思考模式和您公開的每個支援的 reasoning-effort 值；
temperature、top_p 和輸出 Token 限制在其允許極限；
帶有參數的客戶端函數工具；
格式錯誤的角色、內容類型和不支援的選項。

最後一組很重要，因為協議相容性也是拒絕相容性。靜默丟棄不支援欄位的服務比返回精確錯誤的服務更難除錯。

了解函式庫可轉換的內容

當前範圍涵蓋 Messages、Chat Completions 和 Responses 風格請求，包括串流和完整回應。共享表示支援文字、圖片、思考和客戶端工具呼叫。輸出解析涵蓋思考內容、工具呼叫、JSON 物件和停止序列。

對於 Responses 請求，支援工具命名空間和 apply_patch 自定義工具。這並不意味著函式庫應用 patches。它表示並解析工具呼叫；宿主應用程式仍然決定工具是否存在、請求許可、運行它並將結果返回給模型。

V4.1 圖片預處理可通過圖片組件和 OpenCV 使用。圖片可以作為 base64 數據或外部 URL 到達。生產服務應在將遠程內容交給預處理代碼之前設置大小限制、媒體類型檢查、下載超時和網路限制。

明確處理不支援的欄位

截至檢查發布版，logprobs 和 top_logprobs 不支援。文件內容、音頻或影片、通過 file_id 檢索文件、通過 n > 1 的多個完成，或加密思考內容也不支援。

結構化輸出預期需要小心。函式庫可以解析 JSON 物件輸出，但不強制執行 JSON Schema、正則表達式或嚴格工具定義。如果您的 API 宣傳這些保證，驗證必須發生在其他地方。解析的 JSON 物件仍然可能違反呼叫者的 schema。

對話儲存也在套件之外。previous_response_id 不檢索早期上下文。您的 HTTP 服務必須解析儲存的對話狀態並將結果消息傳遞到轉換，或明確拒絕該欄位。

像 web_search 這樣的伺服器工具不支援，因為 recipe 層不執行工具。如果客戶端發送此類請求，不要在未記錄語義差異的情況下將其轉換為客戶端函數呼叫。

將其添加到 API 服務而不模糊責任

乾淨的服務管道有四個界線：

認證、速率限制、請求體大小限制和公共 API 驗證。
deepseek-recipe 標準化和 V4/V4.1 編碼。
消耗 Token 並生成 Token 的推論後端。
Recipe 解析、應用程式擁有的工具編排和 HTTP 串流。

圍繞每個界線保持指標。請求轉換時間、首個生成 Token 時間、工具等待時間和回應序列化時間回答不同的營運問題。將它們合併為一個延遲數字使回歸難以定位。

不要預設通過日誌或追蹤系統傳遞渲染的提示詞。記錄安全的元數據，如消息計數、內容類型、編碼版本、Token 計數和轉換錯誤。如果採樣負載日誌記錄不可避免，使其成為可選、脫敏、訪問控制和短壽命。

當本教學是錯誤路徑時

當您建立或調整推論服務並需要 DeepSeek 特定協議轉換時使用 deepseek-recipe。如果您只想呼叫現有的 DeepSeek 相容端點，使用該服務的客戶端 SDK 或 HTTP API。向應用程式客戶端添加提示詞編碼器會複製伺服器行為並使升級更困難。

該套件最有價值之處在於它不是一體化伺服器。它為基礎設施團隊提供共享、可測試的轉換層，同時將部署、調度、安全和工具留在他們控制之下。成功的首次整合以驗證的提示詞和不支援欄位列表結束——而不是宣稱整個服務堆疊已完成。

來源檢查：deepseek-recipe 官方儲存庫，訪問於 2026 年 9 月 14 日。

使用 Python 轉換 DeepSeek V4.1 API 請求