2026 DeepSeek Harness 自訂模型服務接入指南

DeepSeek Harness 的內置路由、目錄 Provider 與自訂 Provider 解決的是不同問題。官方 Web UI 指南說明，直接輸入 DeepSeek API 憑據後，模型路由即可在下一次請求使用，通常不需要重新啟動服務；而自訂 Provider 則針對公司網關、自託管伺服器，或尚未納入已安裝目錄的服務。官方 Web UI 指南可作為第一層核對依據。

這個判斷能避免三類隱性成本。第一，重複建立配置會讓同一個模型出現多個名稱，日後難以分辨實際請求走哪條路由。第二，公司網關可能使用不同的認證標頭、模型命名或路徑，表面上「能連線」不代表工具呼叫和串流回應也能工作。第三，開發者預覽期間存在相容性變更，直接複製舊文章中的欄位名稱，可能會把過時配置保存到錯誤位置。

自訂 Provider 第一次保存前，至少要準備 5 類資料：小寫 Provider ID、Base URL、API 協議、憑據，以及至少 1 個模型。這些要求來自官方模型設定指南，而非一般 OpenAI 兼容服務的推測。官方自訂 Provider 說明亦指出，Provider ID 會被請求、已保存會話、模型預設值與憑據引用使用，因此不能把它當成可隨意修改的顯示名稱。

Provider ID 為何要在首次保存前確定？ 因為官方規則將它視為永久身份；若日後需要更名，做法是建立新 Provider、驗證新路由，再刪除舊 Provider，而不是直接修改原身份。顯示名稱、Base URL、協議、憑據與模型可以調整，但 Provider ID 不應用來承載短期版本號或不穩定的供應商別名。

憑據也不應直接貼進專案檔案。官方指南說明，金鑰以只寫方式保存，設定頁只保留遮罩後的憑據描述；相關憑據會保存於 $DSH_HOME/.credentials.yaml，而設定只引用該憑據。這代表團隊應把金鑰生命週期交給環境或憑據管理流程，而不是把秘密值放進 Git、工作區或會話記錄。

配置保存成功，只能證明表單資料被接受，不能證明模型真的可呼叫。第一輪驗證應先測試「憑據是否有效」和「模型目錄是否能查詢」，再決定使用自動獲取或手工填寫模型。

官方指南指出，模型發現會呼叫 OpenAI 兼容 API 的 GET /models；官方 API 文件也將模型 ID 定義為後續請求使用的識別值。模型列表 API 文件可用來理解這條發現鏈路的預期形態。

自訂 Provider 保存後為何找不到模型？ 常見原因不是「模型不存在」，而是模型發現端點沒有回應、模型 ID 只存在於網關內部別名，或模型仍停留在未保存的草稿中。官方流程是先以目前表單中的 Base URL 與憑據查詢模型，選取候選後才更新草稿；若端點沒有模型目錄，就必須手工輸入模型，不能把保存成功視為發現成功。

取得模型列表返回 401 時怎樣處理？ 先確認憑據是否屬於目前 Base URL 的服務、網關是否要求不同的標頭，以及該金鑰是否有模型查詢權限。只有在認證確認無誤、端點仍不提供模型目錄時，才回退到手工模型 ID；如果直接改模型名稱，通常無法解決 401。

完成模型發現後，不要直接在重要程式碼庫啟動長任務。應建立隔離工作區和新會話，按照由低風險到高風險的順序驗證。

1. 建立隔離工作區。 放入一個不含秘密的測試檔案，避免首次請求讀取正式原始碼、環境變數或部署憑據。
2. 新建會話並選定模型。 記錄畫面顯示的 Provider、模型 ID 與會話建立時間，後續不要只依賴模型名稱判斷路由。
3. 執行最小文字任務。 例如要求模型讀取測試檔案並列出兩項內容，確認請求能完成、回應內容正常、錯誤訊息沒有被網關吞掉。
4. 加入一個受控工具呼叫。 工具只允許讀取測試目錄或輸出固定字串，先確認模型能產生工具請求，再確認 Harness 能接收工具結果並完成下一輪回應。
5. 保存驗收紀錄。 至少記錄實際 Provider、模型 ID、HTTP 狀態、請求時間、網關追蹤 ID 與失敗訊息；不要只截取「成功」畫面。
6. 執行回退測試。 暫時切回已驗證的內置或既有路由，以相同文字任務重跑，確認問題屬於自訂端點而非工作區、權限或工具本身。

注意： OpenAI 兼容 API 只描述一部分傳輸格式，並不自動保證工具呼叫、串流、模型能力或錯誤語意完全一致；是否兼容，應以文字請求與受控工具呼叫的實際驗收結果為準。

如果工具請求失敗，不要立即判定模型不可用。先分辨是模型沒有輸出工具呼叫、網關剝離了工具欄位、協議選錯，還是 Harness 收到結果後無法繼續會話。必要時可參考 NUKCLOUD 的支援頁面，把連線、權限與遠端環境問題分開排查。

模型切換最容易被誤判的地方，是「新預設值」與「既有會話模型」並不是同一件事。官方指南明確說明，選取模型會成為新會話的預設值；已經送出請求的會話，則會保留其自身記錄的模型。

因此，修改模型服務後，舊會話不會自動切換。正確流程如下：

• 先保留舊 Provider，不要在故障期間立即刪除，避免失去對照路由。
• 建立新 Provider 或修正模型後，開啟新會話。
• 在新會話中重做最小文字任務與工具呼叫。
• 對比新舊會話的 Provider、模型 ID、回應狀態與網關日誌。
• 確認新路由穩定後，再把它設為新會話預設值。
• 若舊會話因 Provider 被刪除而無法輸入，重新選擇有效模型或建立新會話，不要反覆修改原會話掩蓋配置問題。

修改模型服務後舊會話會否自動切換？ 不會。舊會話保留已記錄的模型，新預設值主要影響新會話；這也是為何路由切換必須以新會話驗證，而不是拿舊對話中的一次成功回應作為新配置證據。

自訂模型服務一旦進入日常使用，平台工程師應建立一份簡短的變更紀錄，至少包含端點、憑據引用、模型 ID、API 協議、修改者、修改原因與驗收結果。這份紀錄的價值不在於格式漂亮，而在於出現「昨日可用、今日失敗」時，能迅速判斷是網關升級、金鑰輪換、模型別名變更，還是 DeepSeek Harness 本身更新。

建議把回退條件寫成明確規則：

• GET /models 連續失敗，但既有模型請求仍可用：先保留手工模型清單，暫不改動生產路由。
• 憑據返回 401：停用新變更，恢復上一個已驗證憑據引用。
• 模型 ID 被服務端拒絕：回退到上一個有效模型，不要在同一會話中反覆重試。
• 文字請求成功但工具呼叫失敗：標記為「部分兼容」，不可直接宣稱整條路由支援 Agent 工作流。
• DeepSeek Harness 或公司網關升級後：重新執行隔離文字任務、受控工具呼叫與回退測試。

官方儲存庫目前明確標示 DeepSeek Harness 為開發者預覽，並提醒可能出現相容性破壞變更；因此，團隊不應只在首次接入時驗證一次。每次升級後都應重新核對官方根 README、使用者配置指南及本地實際設定介面。

對多數團隊而言，最穩妥的做法不是追求「所有模型都能塞進同一個 Provider」，而是讓每條路由都有固定身份、清楚能力邊界和可用回退。若公司模型網關需要在隔離、持續在線的 macOS 環境中驗證，直接使用現有 Windows 或 Linux 主機往往會遇到環境差異、遠端桌面不穩定、權限配置分散及長時間在線維護成本；自建 Mac 亦需要自行處理硬體採購、更新與閒置資源。此時可按專案準備一套 NUKCLOUD 遠端 Mac 測試環境，例如先查看 美國東部 Mac 方案，用本文的最小驗收流程確認模型網關，再決定是否值得長期部署。對短期整合、版本升級或故障回退測試而言，租用已可連線的 Mac 通常比為一次驗證建立完整本地環境更容易控制變更範圍；但若需要長期滿載、特殊實體介面或固定硬體保留，購置自有 Mac 仍可能更合適。