使用文件 / 疑難排解

金鑰錯誤

401、403、找不到模型、Azure 部署名稱填錯各有不同解法。先分清是哪一種金鑰,再照順序查。

最後更新

先分清楚兩種金鑰

ZeroType 會用到兩種完全不同的金鑰,混在一起是最常見的錯誤來源:

金鑰 用途 哪裡輸入
License Key 啟用 ZeroType 這套軟體 授權啟用視窗、偏好設定的授權管理
AI 服務金鑰 呼叫語音轉錄與 AI 校正服務,由 provider 核發 偏好設定或提示詞編輯器的金鑰欄位

License Key 長得像 PROD1- 開頭的四段文字,AI 服務金鑰則是各家 provider 的格式(例如 Groq 的 gsk_ 開頭)。把 License Key 填進安裝程式的「服務金鑰」欄位,轉錄會直接回 HTTP 401,而且錯誤訊息完全看不出原因。

常見錯誤訊息怎麼讀

訊息 通常代表什麼
HTTP 401 這個端點不接受這把金鑰:金鑰打錯、金鑰與 API base 屬於不同服務/不同資源,或填成了 License Key
HTTP 403 伺服器收到金鑰但拒絕存取:多半是金鑰與 API base 不是同一個資源,或該金鑰沒有使用這個模型的權限
找不到模型、模型不存在 模型名稱打錯,或你的帳號沒有這個模型
DeploymentNotFound Azure 的模型欄位要填「部署名稱」,不是模型家族名稱;名稱不存在
OperationNotSupported 常見於 Azure 部署名稱大小寫不符——伺服器對部署名稱是分大小寫的
畫面顯示找不到金鑰、金鑰未設定 本機就擋下了,請求根本沒送出,通常是金鑰名稱對不上

依序檢查

1. 錯誤發生在轉錄還是 AI 校正

偏好設定的「測試連線」會分別測兩邊。轉錄失敗代表金鑰或端點有問題;只有 AI 校正失敗,代表轉錄沒問題、是另一組設定要查。兩邊可以各自用不同的 API base 與金鑰。

2. API base 與金鑰是同一個服務嗎

最常見的組合錯誤是:API base 還是 OpenAI,金鑰卻換成 Groq(或反過來)。換 provider 時請整組一起換:API base、模型、金鑰。

Azure 要特別注意:API base 與金鑰必須屬於同一個資源。拿 A 資源的網址配 B 資源的金鑰,會得到 401 或 403。

3. 模型名稱對嗎

  • 一般 provider:填該服務支援的模型 ID。
  • Azure OpenAI:Transcription.Model 與 AiPrompt.Model 要填部署名稱。部署名稱和你自己取的名字一致,不是模型家族名稱。
  • Azure Foundry 的推論網址與 Azure OpenAI 資源網址不是同一個東西,不要互換。

4. 提示詞指定的金鑰名稱存在嗎

如果 USER.md 或 USER-*.md 的 front matter 寫了金鑰名稱,那個名字必須真的存在:

---
ZEROTYPE_AIPROMPT_CREDENTIAL_NAME: 工作 OpenAI
---

請整理文字。

金鑰庫裡沒有一筆叫「工作 OpenAI」的金鑰,就會出現找不到金鑰的錯誤。金鑰改名時,舊名稱會自動變成別名繼續可用,所以不必回頭改提示詞。

5. 金鑰內容有沒有多餘字元

貼上時很容易夾到前後空白、換行,或整段被引號包住。重新貼一次,只留金鑰本身。

6. 是不是把授權碼貼進去了

回到最上面那張表。看到 PROD1- 開頭就代表貼錯了欄位,請到偏好設定重新輸入 provider 給的金鑰。

金鑰存在哪裡

平台 存放位置
Windows Windows 認證管理員
macOS 鑰匙圈(Keychain)

appsettings.Local.json 只保存金鑰名稱,不保存金鑰內容。macOS 另外有一份對照用的 metadata,記錄名稱與鑰匙圈項目的對應關係,同樣不含金鑰。

所以如果你想確認金鑰有沒有存好,看設定檔是看不出來的,要在偏好設定的金鑰管理裡看名稱,或到系統的認證管理員/鑰匙圈確認。

重新輸入金鑰

  1. 打開偏好設定。
  2. 找到金鑰欄位(Windows 可從下拉選單選既有金鑰,或開「新增金鑰…」「管理金鑰…」)。
  3. 輸入或貼上新的金鑰內容;名稱不能與現有的重複。
  4. 按「套用」或「儲存設定」。
  5. 按「測試連線」確認兩邊都通。

從偏好設定套用 provider、模型與金鑰不需要重新啟動 ZeroType。只有手動編輯 JSON 或提示詞檔案時才需要重新載入(選單有「重新啟動 ZeroType」可用)。

用測試連線確認

測試連線會顯示 provider 名稱、音訊傳輸格式與實際送出的請求網址,可以一次看出端點與模型對不對。

測試連線不會真的執行工具——不會開網頁、不會開 App、不會執行命令、不會送出按鍵。它用的是停用工具的環境,所以測得過不代表工具設定正確。

部分即時轉錄模型在測試時會實際送出一小段靜音並等伺服器回應,這樣才能在設定階段就抓到部署名稱不存在。這一步的費用接近零。

不要做的事

  • 不要把金鑰寫進 USER.md 或任何提示詞檔案。ZeroType 會拒絕含明文金鑰的提示詞,學習平台同步也會以 literal_api_key 拒收。
  • 不要把 appsettings.Local.json 上傳到公開 repo 或貼進聊天群組。
  • 不要把完整金鑰貼在回報訊息裡。要給人看時只留前後幾碼。

還是沒解決時要提供什麼資訊

  1. 錯誤發生在轉錄、AI 校正,還是測試連線。
  2. 完整的錯誤訊息文字(不是截圖裁掉一半),以及 HTTP 狀態碼。
  3. provider 名稱、API base 的 host、模型或部署名稱。
  4. 錯誤是「一開始就不能用」還是「原本可以、換了設定後才壞」。
  5. zerotype.log 中對應時間的片段。log 不會記錄金鑰內容,可以放心提供;但仍請先確認沒有夾帶其他敏感網址參數。

金鑰本身請勿提供,若對方需要確認,請自行重新核發一把新金鑰再測試。

這一頁有錯、或有沒寫到的地方?寫信到 training [at] miniasp.com,我們會依實際行為更新文件。