使用文件 / 疑難排解
金鑰錯誤
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,記錄名稱與鑰匙圈項目的對應關係,同樣不含金鑰。
所以如果你想確認金鑰有沒有存好,看設定檔是看不出來的,要在偏好設定的金鑰管理裡看名稱,或到系統的認證管理員/鑰匙圈確認。
重新輸入金鑰
- 打開偏好設定。
- 找到金鑰欄位(Windows 可從下拉選單選既有金鑰,或開「新增金鑰…」「管理金鑰…」)。
- 輸入或貼上新的金鑰內容;名稱不能與現有的重複。
- 按「套用」或「儲存設定」。
- 按「測試連線」確認兩邊都通。
從偏好設定套用 provider、模型與金鑰不需要重新啟動 ZeroType。只有手動編輯 JSON 或提示詞檔案時才需要重新載入(選單有「重新啟動 ZeroType」可用)。
用測試連線確認
測試連線會顯示 provider 名稱、音訊傳輸格式與實際送出的請求網址,可以一次看出端點與模型對不對。
測試連線不會真的執行工具——不會開網頁、不會開 App、不會執行命令、不會送出按鍵。它用的是停用工具的環境,所以測得過不代表工具設定正確。
部分即時轉錄模型在測試時會實際送出一小段靜音並等伺服器回應,這樣才能在設定階段就抓到部署名稱不存在。這一步的費用接近零。
不要做的事
- 不要把金鑰寫進
USER.md或任何提示詞檔案。ZeroType 會拒絕含明文金鑰的提示詞,學習平台同步也會以literal_api_key拒收。 - 不要把
appsettings.Local.json上傳到公開 repo 或貼進聊天群組。 - 不要把完整金鑰貼在回報訊息裡。要給人看時只留前後幾碼。
還是沒解決時要提供什麼資訊
- 錯誤發生在轉錄、AI 校正,還是測試連線。
- 完整的錯誤訊息文字(不是截圖裁掉一半),以及 HTTP 狀態碼。
- provider 名稱、API base 的 host、模型或部署名稱。
- 錯誤是「一開始就不能用」還是「原本可以、換了設定後才壞」。
zerotype.log中對應時間的片段。log 不會記錄金鑰內容,可以放心提供;但仍請先確認沒有夾帶其他敏感網址參數。
金鑰本身請勿提供,若對方需要確認,請自行重新核發一把新金鑰再測試。
這一頁有錯、或有沒寫到的地方?寫信到 training [at] miniasp.com,我們會依實際行為更新文件。