DeepSeek Harness 接入 B.AI API 官方配置指南
- 核心觀點：本文提供了一份技術教學，詳細介紹了如何在 Windows、macOS 和 Linux 系統中啟動開源 AI 工作區應用 DeepSeek Harness，並透過自訂 Provider 機制將其與 B.AI 大模型服務平台整合，實現本地工作區到大模型的呼叫閉環。
- 關鍵要素：
- 環境準備要求 Node.js LTS 版本，透過
node -v、npm -v、npx -v指令驗證安裝是否完成，三系統安裝方式略有差異。 - 推薦使用
npx @deepseek-ai/dsh web快速啟動，首次執行需確認下載依賴，成功啟動後本地存取位址為 http://127.0.0.1:3080。 - 進階開發可透過 GitHub 倉庫取得原始碼，提供 ZIP 下載和 Git 克隆兩種方式，皆需安裝 pnpm 並執行建置指令。
- B.AI Provider 設定需跳過官方預設 API Key 彈窗，在設定頁面新增自訂提供方，填寫 Provider ID 為 bai、API 位址 https://api.b.ai/v1、協定選擇 openai-completions。
- 模型目錄建議透過「取得可用模型」自動拉取，模型 ID 必須與 B.AI 回傳結果完全一致，避免手動修改導致 model not found 錯誤。
- 鏈路驗證包含基礎對話測試和工具呼叫測試（唯讀指令），需同時監控終端日誌確認無 401、404 等異常報錯。
- 常見問題涵蓋連接埠佔用、鑑權失敗、模型 ID 不匹配等七類典型故障，文末附有官方參考連結資源。
- 環境準備要求 Node.js LTS 版本，透過
DeepSeek Harness 是一款備受矚目的開源 AI 工作區應用，目前正處於開發者預覽階段。它不僅能深入本地工作區協助程式碼與檔案分析，還透過開放的自訂 Provider 機制，賦予開發者極大的靈活性。而 B.AI 作為先進的 AI 基礎設施，打造了集高可用、低延遲於一體的全端式大模型服務平台，致力於為開發者與企業建構強大、穩定且極具彈性的智慧算力網路。
本指南將為您詳細示範，如何在 Windows、macOS 和 Linux 環境中從零啟動 DeepSeek Harness，並成功地將其與 B.AI API 進行整合。跟隨本教學，您將打通從本地工作區到大模型的全鏈路呼叫閉環，全面釋放 AI 驅動的生產與創新潛力。
最終實現的呼叫鏈路： DeepSeek Harness → B.AI API → B.AI 提供的模型
1. 準備環境
DeepSeek Harness 透過 Node.js 自帶的 npx 啟動。請確保您的系統已安裝目前可用的 Node.js LTS 版本。
官方下載位址： https://nodejs.org/en/download
- Windows
可直接下載 .msi 安裝套件，也可以在開始選單中搜尋 PowerShell，開啟後執行 WinGet 安裝指令。
winget --version winget install --id OpenJS.NodeJS.LTS -e --source winget
- macOS
在 Node.js 官方下載頁面選擇 macOS Installer，下載 .pkg 檔案並依提示完成安裝。安裝結束後，按 Command + Space 開啟聚焦搜尋，輸入 Terminal，進入終端機。
- Linux
請在 Node.js 官方下載頁面選擇您所使用的 Linux 發行版與系統架構，並依照頁面提供的套件管理器指令安裝 LTS 版本。由於 Ubuntu、Debian、Fedora 等不同發行版的安裝指令存在差異，建議以官方頁面動態產生的指令為準，以確保安裝過程穩妥無誤。
安裝結束後，關閉目前所有已開啟的終端機視窗，並重新開啟一個新的終端機（Windows 使用者請使用 PowerShell，macOS 使用者使用 Terminal，Linux 使用者使用系統終端機）。
在三個系統中，均執行以下同一組檢查指令：
node -v npm -v npx -v
三條指令皆回傳版本號即代表環境準備就緒。
Node.js v24.19.0 npm 11.17.0 npx 11.17.0
若您準備透過 GitHub 原始碼建置並執行專案，則需依賴 Git 環境。請先在終端機執行 git --version 檢查是否已安裝。如未安裝，請根據您的作業系統執行以下指令：
Windows
winget install --id Git.Git -e --source winget
macOS
xcode-select --install
Ubuntu 或 Debian
sudo apt update sudo apt install git
註：如果您僅計劃使用 npx 方式快速體驗並設定 B.AI，可直接跳過 Git。
2. 使用 npx 啟動 DeepSeek Harness (推薦)
對於常規使用及設定 B.AI API 的開發者，建議直接使用 npx 啟動。
在終端機中執行以下指令（三端系統通用）：
npx @deepseek-ai/dsh web
首次執行提示： 系統會詢問是否下載所需軟體套件，輸入 y 並按 Enter 確認。
Need to install the following packages @deepseek-ai/dsh@... Ok to proceed? (y)
啟動過程中若出現依賴棄用警告，屬於正常現象，無需干預。
npm warn deprecated node-domexception@1.0.0
當終端機輸出本地位址時，表示 DeepSeek Harness 的 Web 服務已成功啟動。
dsh web: http://127.0.0.1:3080
保持終端機視窗開啟，然後在瀏覽器網址列輸入：
http://127.0.0.1:3080
該位址僅限本機存取。若關閉終端機視窗或在視窗中按下 Ctrl+C，本機服務將隨之停止。如果瀏覽器無法開啟 127.0.0.1:3080，請首先檢查終端機是否仍在執行，並確認終端機內是否已輸出上述 dsh web 位址。必要時，請重新執行啟動指令。
npx @deepseek-ai/dsh web
3. 原始碼建置方式（進階）
若您計劃開發外掛、修改原始碼，或者參與專案開發，也可以從官方 GitHub 儲存庫取得原始碼。
官方儲存庫： https://github.com/deepseek-ai/deepseek-harness
請注意，GitHub 提供的是專案原始碼，下載後必須透過終端機完成依賴安裝與專案建置，無法透過雙擊檔案直接執行。您可以透過以下兩種方式取得並執行原始碼：
方式一：下載 ZIP 原始碼套件 在儲存庫頁面點擊綠色的 Code 按鈕，選擇 Download ZIP。下載並解壓縮後，開啟終端機，使用 cd 指令進入解壓縮後的專案目錄，依序執行以下指令：
npm install -g pnpm pnpm install pnpm run build pnpm dsh web
方式二：使用 Git 複製 建議先執行 git --version 檢查 Git 環境是否存在。如未安裝，請參考前文「準備環境」部分完成相應系統的 Git 安裝。確認環境無誤後，重新開啟終端機，執行以下指令：
git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness npm install -g pnpm pnpm install pnpm run build pnpm dsh web
無論使用 ZIP 或 Git 方式，建置並啟動成功後，存取位址同樣為 http://127.0.0.1:3080。
4. B.AI 自訂 Provider 設定
步驟一、跳過官方預設設定
首次進入 DeepSeek Harness 時，系統會彈出官方模型的 API Key 填寫視窗。請務必點擊「稍後設定」。若此處填入 B.AI 的 Key，系統將無法正確辨識。
步驟二、進入自訂設定頁
點擊頁面左下角的「設定」，在左側選單選擇「模型」，點擊右側的「新增自訂提供方」。註：此時官方 Provider 顯示紅點屬於正常狀態，不影響後續操作。
步驟三、填寫 B.AI 介面資訊
開啟自訂提供方以後，按下面的內容填寫。
Provider ID bai 顯示名稱 B.AI API 位址 https://api.b.ai/v1 API 協定 openai-completions API 金鑰 從 B.AI 後台建立的有效 API Key
步驟四、取得模型目錄並完成 Provider 建立
基礎資訊填寫完畢後，請向下捲動至「模型目錄」區域。系統提供兩種新增方式：點擊「新增模型」手動填寫模型 ID，或點擊右上角的「取得可用模型」。
推薦操作： 首選點擊「取得可用模型」。 讓 DeepSeek Harness 直接向 B.AI 請求目前帳號可用的模型目錄。若模型清單能正常回傳，即證明 B.AI API Key、https://api.b.ai/v1、openai-completions 協定，以及模型目錄介面等設定已成功連通。
模型選擇與新增注意：
- 在回傳的清單中，勾選 B.AI 目前可用的 DeepSeek 模型（範例可見 deepseek-v4-flash 或 deepseek-v4-pro，請注意：具體可用模型會隨帳號權限和時間動態變化，請以實際回傳結果為準）。
- 請勿修改模型 ID： 模型 ID 必須與 B.AI 實際回傳的目錄完全一致。請勿擅自更改任何大小寫、連字號或版本號，否則在後續呼叫時極易觸發 model not found 錯誤。
確認模型新增無誤後，捲動至表單底部，點擊「建立提供方」。
建立成功後，設定頁面將新增一個名為 B.AI 的自訂 Provider，且旁邊顯示綠色圓點。這代表 B.AI 自訂 Provider 已成功儲存並處於可用狀態。 註：此時 DeepSeek 官方 Provider 若仍顯示紅點，係未填寫 DeepSeek 官方 API Key 所致，這不影響綠點對應的 B.AI 介面正常使用。
步驟五、 鏈路連通性驗證
關閉設定視窗，返回主介面新建一個會話。在模型選擇器中選擇 B.AI Provider，再選擇剛剛新增的 DeepSeek 模型，進行以下測試：
基礎對話測試： 在模型選擇器中選定 B.AI 及對應模型，發送指令：
請介紹一下你自己，並說明目前正在使用的模型。
觀察它能不能正常回傳內容，是否有串流輸出，同時確認目前 Provider 是 B.AI，模型 ID 也和你選擇的一致。
工具呼叫測試： 發送唯讀指令驗證工具鏈路：
請查看目前工作區的檔案，並總結目錄結構。不要修改或刪除任何檔案。
指令中特別強調「不要修改或刪除任何檔案」，是為了在不改動目前工作區的前提下，安全、快速地驗證 Harness 的工具呼叫鏈路是否暢通。
在執行上述兩項測試時，請回頭查看執行 DeepSeek Harness 的終端機視窗，確認主控台未出現 401、404、model not found 或其他請求報錯資訊。若終端機執行平穩，至此您已成功完成所有接入與驗證工作。
💡常見問題 Q&A
Q1：終端機提示找不到 node、npm 或 npx 指令？
A： 這通常是 Node.js 尚未安裝完成，或者新安裝的指令路徑還沒有被目前終端機讀取。關閉所有終端機視窗，重新開啟，再執行。
node -v npm -v npx -v
依然找不到指令時，回到 Node.js 官方下載頁面，確認已經安裝目前的 LTS 版本。Windows 使用者還可以在系統的「已安裝的應用」中檢查 Node.js，macOS 和 Linux 使用者可以執行 which node 查看指令路徑。
Q2：啟動時出現 npm warn deprecated，需要處理嗎？
請優先確認後面有沒有出現下面這個位址：
dsh web: http://127.0.0.1:3080
若該位址正常顯示，則代表 Web 服務已成功啟動。deprecated 在這次實測中屬於依賴棄用警告，可以繼續使用。若終端機隨後異常退出或未輸出本地位址，請再根據終端機末尾的具體報錯資訊進行排查。
Q3：瀏覽器無法開啟 127.0.0.1:3080，怎麼辦？
A：請首先檢查執行 dsh web 的終端機視窗是否仍處於開啟狀態。關閉該終端機或使用 Ctrl+C 快捷鍵均會終止本機服務。
若服務已停止，請重新執行啟動指令：
npx @deepseek-ai/dsh web
若終端機提示「連接埠被佔用」：請先結束之前殘留的 DeepSeek Harness 程序，而後重試。
Q4：呼叫模型時遇到 401 Unauthorized 報錯，如何排查？
A： 401 錯誤通常指向 API Key 身分驗證失敗。請檢查：
- API Key 是否完整複製，首尾有無多餘空格。
- 確認該 API Key 在 B.AI 控制台中是否處於有效（未停用）狀態。
- 確認 Key 填入了正確的設定項中：請勿將其填入首次彈窗的「DeepSeek 官方 Provider」中，而必須填入「設定 → 模型 → 新增自訂提供方」對應的 B.AI 介面內。
Q5：呼叫模型時遇到 404 Not Found ，是哪裡填寫有誤？
A： 請檢查 API 位址是否填寫完整。
https://api.b.ai/v1
Q6：提示 model not found，如何解決？
A： 請返回 B.AI 自訂 Provider 的編輯頁面，重新點擊「取得可用模型」。請確保所選擇或填寫的模型 ID 與系統回傳的結果完全一致，嚴格保留所有大小寫、連字號和版本號。此外，帳號權限更新或官方模型目錄調整也可能導致舊模型不可用，如遇報錯，請一律以目前重新取得到的模型清單為準。
Q7：B.AI 狀態顯示綠點，但依舊無法對話？&
