使用問題

本文件彙總了 CueMate 功能使用過程中的常見問題和解決方案。

提示

如果你遇到的問題在這裡找不到答案，可以檢視 功能手冊 獲取更詳細的功能說明。

1. macOS 平臺

1.1 語音識別不準確

問題描述：使用語音識別功能時，識別的文字與實際說話內容不符，或者有較多錯誤。

提升識別準確率的關鍵因素

環境 > 裝置 > 發音 > 配置

最重要的是保證安靜的環境和清晰的發音，其次才是裝置和引數調整。

最佳化建議：

1. 環境最佳化：

   • 選擇安靜的環境，避免背景噪音
   • 關閉電風扇、空調等可能產生噪音的裝置
   • 避免在嘈雜的公共場所使用

2. 裝置調整：

   • 調整麥克風位置，距離嘴巴 15-20cm 最佳
   • 使用外接麥克風，音質通常優於內建麥克風
   • 確保麥克風未被遮擋或覆蓋

3. 發音技巧：

   • 清晰發音，避免含糊不清
   • 語速適中，不要過快或過慢
   • 避免使用方言，儘量使用標準普通話

4. 系統設定：

   • 在 語音設定 頁面啟用噪音抑制
   • 新增專業術語到自定義詞庫
   • 先進行 語音測試 確認裝置正常

1.2 語音識別延遲高

問題描述：說話後需要等待較長時間才能看到識別結果，影響使用體驗。

解決方案：

1. 裝置最佳化：

   • 使用有線麥克風代替藍芽麥克風（藍芽有延遲）
   • 確保麥克風連線穩定，避免鬆動

2. 系統資源：

   • 關閉不必要的後臺程式，釋放 CPU 和記憶體
   • 開啟 Docker Desktop 設定，增加分配給 Docker 的資源
   • 建議：記憶體 4GB+，CPU 2 核+

3. 網路檢查：

   • 檢查網路連線是否穩定
   • 確認 cuemate-asr 服務正常執行（埠 10095）
   • 檢視 容器監控 確認服務狀態

4. 服務重啟：

   • 在容器監控頁面重啟 cuemate-asr 服務
   • 完全退出並重新啟動 CueMate 應用

1.3 無法捕獲系統音訊

問題描述：使用揚聲器測試或面試訓練時，無法識別揚聲器播放的音訊內容。

需要系統許可權

捕獲系統音訊需要 macOS"錄屏與系統錄音"許可權。請按照以下步驟檢查並授予許可權。

macOS 解決方案：

1. 檢查許可權：

   • 開啟 系統設定 > 隱私與安全性 > 錄屏與系統錄音
   • 確認 CueMate 已被勾選
   • 如果未勾選，請勾選並重啟 CueMate

2. 許可權說明：

   • "錄屏與系統錄音"許可權僅用於系統音訊捕獲
   • CueMate 不會錄製螢幕畫面
   • 詳見 語音測試 - 錄屏與系統錄音許可權

備選方案：使用虛擬音訊裝置（高階使用者）

適用場景：不想授予錄屏許可權，或系統音訊捕獲不穩定時

操作步驟：

1. 安裝 BlackHole 等虛擬音訊裝置
2. 將揚聲器輸出路由到虛擬裝置
3. 在語音設定中選擇虛擬裝置作為輸入

推薦工具：BlackHole - 開源免費的 macOS 虛擬音訊驅動

1.4 API Key 無效

問題描述：在模型設定中新增 API Key 後，測試連線提示"API Key 無效"或"認證失敗"。

常見 API Key 格式

不同平臺的 API Key 格式不同，請注意區分：

平臺	格式示例	長度
OpenAI	sk-proj-xxxxx...	51 位
Azure OpenAI	a1b2c3d4e5f6...	32 位
智譜 AI	xxxxxx.xxxxxx	包含 .
Moonshot (Kimi)	sk-xxxxx...	56 位
通義千問	sk-xxxxx...	不定長

檢查步驟：

1. 格式檢查：

   • 確認 API Key 格式正確，沒有多餘的空格
   • 複製時避免選中換行符
   • 使用純文字編輯器檢視是否有隱藏字元

2. 有效性檢查：

   • 確認 API Key 未過期
   • 登入對應平臺檢查 API Key 狀態
   • 如已過期，重新生成新的 API Key

3. 賬戶檢查：

   • 確認賬戶餘額充足
   • 某些平臺需要充值後才能使用 API
   • 檢查是否有使用限額或速率限制

4. 服務可用性：

   • 檢查對應 AI 服務是否正常執行
   • 訪問官網確認服務狀態
   • 嘗試更換其他 API Key 測試

詳見 模型設定。

1.5 測試連線失敗

問題描述：在模型設定頁面點選"測試連線"後，提示連線失敗或超時。

排查步驟：

1. 檢查網路連線：

   • 確認網路連線正常
   • 嘗試訪問對應 AI 服務的官網
   • 檢查是否需要科學上網（如 OpenAI）

2. 驗證 API URL 正確：

   • 檢查 API Endpoint 地址是否正確
   • OpenAI: https://api.openai.com/v1
   • Azure OpenAI: 需要填寫完整的資源地址
   • 其他平臺請參考官方文件

3. 確認 API Key 有效：

   • 參考問題 4 檢查 API Key
   • 嘗試在官方 API 工具中測試
   • 確認許可權範圍包含所需的模型

4. 檢視錯誤日誌：

   • 開啟 日誌管理 頁面
   • 檢視 llm-router 服務的錯誤日誌
   • 根據具體錯誤資訊進行排查

1.6 模型響應慢

問題描述：向 AI 提問後，等待很長時間才收到回答，或者回答速度很慢。

模型速度對比（快 → 慢）

最快：GPT-3.5-turbo、DeepSeek、Kimi 較快：GPT-4o-mini、智譜 GLM-4-Flash 較慢：GPT-4、Claude-3-Opus、GPT-4o

日常使用推薦選擇"最快"或"較快"級別的模型。

最佳化方法：

1. 調整模型引數：

   • 降低 max_tokens 引數（預設 2000）
   • 減少 temperature 值以加快生成速度
   • 在 模型設定 中調整

2. 更換模型：

場景	推薦模型	理由
日常對話	GPT-3.5-turbo	速度快，成本低
程式碼生成	DeepSeek Coder	專業且快速
文件分析	Kimi (Moonshot)	長文字能力強
複雜推理	GPT-4	準確度高

3. 啟用快取（如果支援）：

   • 某些模型支援快取機制
   • 相同問題會直接返回快取結果
   • 檢視模型文件確認是否支援

4. 檢查網路速度：

   • 使用網路測速工具檢查頻寬
   • 嘗試切換網路連線（Wi-Fi → 有線）
   • 科學上網時選擇更快的節點

1.7 文件上傳失敗

問題描述：在知識庫中上傳文件時，提示上傳失敗或處理失敗。

IMPORTANT

支援的文件格式和限制：

• 支援格式：.txt, .md, .pdf, .docx, .doc
• 單檔案大小：最大 100MB
• 不支援：圖片、影片、壓縮包等多媒體檔案

可能原因：

1. 檔案格式不支援：

   • 支援格式：.txt, .md, .pdf, .docx, .doc
   • 不支援圖片、影片等多媒體檔案
   • 壓縮檔案需要先解壓

2. 檔案大小超限：

   • 單個檔案最大 100MB
   • 建議將大檔案拆分成多個小檔案
   • 或刪除文件中的多餘內容

3. 磁碟空間不足：

   • 檢查系統磁碟剩餘空間
   • 確保至少有 1GB 可用空間
   • 清理不必要的檔案

4. 文件內容損壞：

   • 嘗試重新生成文件
   • 使用其他工具開啟文件檢查完整性
   • 轉換為其他格式後再上傳

解決方案：

• 轉換檔案格式為支援的格式
• 壓縮或拆分檔案大小
• 清理磁碟空間後重試
• 檢查文件完整性，確保檔案未損壞

詳見 向量知識庫。

1.8 知識庫檢索無結果

問題描述：向 AI 提問時，知識庫中明明有相關內容，但檢索不到結果。

TIP

知識庫檢索效果與文件數量和質量密切相關。建議：

• 上傳 10+ 個相關領域文件
• 文件內容要詳細且結構化
• 使用精確的專業術語提問

最佳化建議：

1. 上傳更多相關文件：

   • 確保知識庫中包含相關領域的文件
   • 文件內容要覆蓋提問的知識點
   • 建議上傳 10+ 個相關文件以提高召回率

2. 最佳化查詢關鍵詞：

   • 使用更精確的關鍵詞
   • 避免使用過於寬泛的詞語
   • 嘗試使用同義詞或相關術語

3. 調整檢索引數：

   • 在知識庫設定中調整 Top-K 引數（預設 5）
   • 增加 Top-K 可以檢索更多相關文件
   • 但也會增加噪音，建議逐步調整

4. 重新索引文件：

   • 在知識庫管理頁面重新索引所有文件
   • 刪除後重新上傳文件
   • 確認向量化過程正常完成

1.9 向量化失敗

問題描述：上傳文件後，顯示"向量化失敗"或"處理失敗"。

檢查項：

1. 文件可讀性：

   • 確認文件可以正常開啟
   • 檢查文件編碼是否正確（建議 UTF-8）
   • 確保文件內容不是純圖片或掃描件

2. 嵌入服務檢查：

   • 檢視 容器監控
   • 確認 cuemate-rag-service 服務正常執行
   • 檢查 cuemate-chroma 向量資料庫狀態

3. 系統資源：

   • 向量化需要一定的 CPU 和記憶體
   • 確保系統資源充足
   • 暫停其他高負載任務

4. 檢視錯誤日誌：

   • 開啟 日誌管理
   • 檢視 rag-service 的錯誤日誌
   • 根據具體錯誤資訊排查

1.10 AI 回答質量差

問題描述：在模擬面試或提問時，AI 的回答質量不高，內容不準確或不相關。

改進方法：

1. 使用更好的模型：

   • 優先選擇 GPT-5、Claude-4.5-Sonnet 等高質量模型
   • 避免使用過時或質量較差的模型
   • 在 模型設定 中配置

2. 最佳化提示詞：

   • 在 提示詞管理 中調整系統提示詞
   • 提供更詳細的上下文資訊
   • 明確回答的格式和要求

3. 完善知識庫：

   • 上傳更多相關領域的文件到 向量知識庫
   • 確保文件內容準確、權威
   • 定期更新知識庫內容

4. 調整模型引數：

   • 降低 temperature（0.3-0.7）使回答更確定
   • 增加 max_tokens 允許更詳細的回答
   • 調整 top_p 控制回答的多樣性

1.11 面試題目不匹配職位

問題描述：在模擬面試中，AI 生成的面試題目與申請的職位關聯性不強。

解決方案：

1. 完善職位資訊：

   • 在 新建崗位 中填寫詳細的 JD
   • 包含崗位職責、技能要求、工作內容
   • 資訊越詳細，生成的題目越精準

2. 更新技能要求：

   • 明確列出需要的技術棧
   • 標註重點考察的能力
   • 補充特殊要求或加分項

3. 手動選擇題目：

   • 在 面試押題 中新增相關題目
   • 標記題目型別和難度
   • 面試時會優先使用押題庫中的題目

4. 新增自定義題目：

   • 根據實際面試經驗新增題目
   • 包含答案和評分標準
   • 持續完善題庫

1.12 面試評分不準確

問題描述：在模擬面試中，AI 對回答的評分與預期不符，或者評價不夠客觀。

可能原因：

1. 回答不完整：

   • 回答過於簡短，缺少關鍵資訊
   • 未涵蓋問題的所有要點
   • 缺少具體案例或資料支撐

2. 模型理解偏差：

   • 使用的模型對專業術語理解有限
   • 某些領域的知識不夠深入
   • 評估標準與人類面試官存在差異

3. 評分標準不合理：

   • 預設評分標準可能不適用所有場景
   • 不同職位的評分側重點不同
   • 需要針對性調整

最佳化建議：

1. 完整回答所有要點：

   • 使用 STAR 法則（情境-任務-行動-結果）
   • 包含技術細節和資料支撐
   • 結構化表達，層次清晰

2. 調整評分提示詞：

   • 在 提示詞管理 中修改面試評估提示詞
   • 明確評分維度和權重
   • 提供評分示例

3. 參考標準答案：

   • 在面試押題中新增標準答案
   • 對比自己的回答與標準答案的差異
   • 不斷最佳化回答方式

1.13 資料丟失

問題描述：面試記錄、對話歷史、知識庫文件等資料突然丟失。

預防措施：

1. 定期備份資料：

   • 在系統設定中啟用自動備份
   • 手動匯出重要資料
   • 建議每週備份一次

2. 啟用自動備份：

   • 配置備份頻率和保留策略
   • 設定備份儲存位置
   • 驗證備份檔案完整性

3. 使用雲端儲存：

   • 將備份檔案同步到雲端（iCloud、OneDrive 等）
   • 啟用版本控制
   • 定期檢查同步狀態

恢復方法：

1. 從備份恢復：

   • 在系統設定中選擇備份檔案
   • 執行資料恢復操作
   • 驗證恢復後的資料完整性

2. 檢視回收站：

   • 某些刪除操作會先移到回收站
   • 檢查是否可以恢復
   • 儘快恢復，避免被徹底刪除

3. 聯絡技術支援：

   • 如果以上方法都無效
   • 提供詳細的問題描述和日誌
   • 聯絡方式見文件底部

1.14 匯入匯出失敗

問題描述：嘗試匯入或匯出資料時，提示失敗或生成的檔案無法使用。

檢查項：

1. 檔案格式檢查：

   • 匯入時確認檔案格式正確
   • 支援的格式：JSON、CSV（根據功能不同）
   • 檔案未損壞或被修改

2. 檔案完整性：

   • 檢查檔案大小是否正常
   • 使用文字編輯器檢視檔案內容
   • 確認 JSON 格式正確，無語法錯誤

3. 許可權檢查：

   • 開啟 系統設定 > 隱私與安全性 > 檔案和資料夾
   • 確認 CueMate 有訪問對應資料夾的許可權
   • 如果沒有，點選"+"新增許可權

4. 磁碟空間：

   • 匯出時確保磁碟空間充足
   • 建議至少 1GB 可用空間
   • 清理臨時檔案

1.15 麥克風/揚聲器無法識別

問題描述：在語音設定或語音測試頁面，看不到麥克風或揚聲器裝置。

解決方案：

1. 檢查裝置連線：

   • 確認裝置已正確連線到電腦
   • 嘗試重新插拔裝置
   • 檢查裝置是否正常工作（在其他應用中測試）

2. 檢查系統設定：

   • 開啟 系統設定 > 聲音
   • 切換到 輸入 標籤檢視麥克風
   • 切換到 輸出 標籤檢視揚聲器
   • 確認裝置在列表中並設為預設裝置

3. 重新整理裝置列表：

   • 點選裝置選擇框的重新整理按鈕
   • 或重啟 CueMate 應用
   • 裝置會自動重新掃描

4. 檢查許可權：

   • 開啟 系統設定 > 隱私與安全性 > 麥克風
   • 確認 CueMate 已被勾選

詳見 語音設定。

1.16 服務啟動失敗

問題描述：在容器監控頁面看到某些服務狀態為"已停止"或"錯誤"。

解決方案：

1. 檢視服務狀態：

   • 開啟 容器監控
   • 檢查所有 6 個服務的狀態
   • 記錄異常服務的名稱

2. 檢視錯誤日誌：

   • 點選異常服務的"日誌"按鈕
   • 檢視最近的錯誤資訊
   • 截圖儲存用於排查

3. 重啟服務：

   • 點選異常服務的"重啟"按鈕
   • 等待服務重啟完成（約 30 秒）
   • 重新整理頁面檢視狀態

4. 檢查依賴服務：

   • 某些服務依賴其他服務
   • 確保 Docker Desktop 正常執行
   • 檢查埠是否被佔用

詳見 容器監控 - 常見問題。

1.17 控制欄無法操作

問題描述：點選懸浮控制欄上的按鈕沒有反應，或者控制欄無法拖動。

解決方案：

1. 檢查互動模式：

   • 點選控制欄上的"互動模式"按鈕
   • 確認處於"互動"模式（圖示高亮）
   • "穿透"模式下控制欄無法點選

2. 重啟應用：

   • 完全退出 CueMate（選單欄 > 退出）
   • 重新啟動應用
   • 檢查控制欄是否恢復正常

3. 檢查服務狀態：

   • 某些按鈕依賴後端服務
   • 開啟 容器監控
   • 確認所有服務正常執行

4. 重置視窗位置：

   • 在系統設定中重置視窗位置
   • 控制欄會回到預設位置
   • 重新拖動到合適位置

1.18 許可證啟用失敗

問題描述：輸入許可證金鑰後，提示啟用失敗或金鑰無效。

解決方案：

1. 檢查金鑰格式：

   • 確認金鑰格式正確，無多餘空格
   • 複製貼上時避免遺漏字元
   • 檢查是否包含特殊字元

2. 檢查有效期：

   • 確認許可證未過期
   • 登入許可證管理後臺檢視狀態
   • 如已過期，需要續費

3. 檢查啟用次數：

   • 許可證可能有裝置數量限制
   • 在許可證管理後臺解綁舊裝置
   • 重新啟用當前裝置

4. 網路連線：

   • 啟用需要連線許可證伺服器
   • 檢查網路連線是否正常
   • 稍後重試或聯絡技術支援

詳見 許可證管理。

1.19 日誌檔案過大

問題描述：日誌檔案佔用大量磁碟空間，導致磁碟空間不足。

解決方案：

1. 清理舊日誌：

   • 開啟 日誌管理
   • 選擇日期範圍
   • 批次刪除舊日誌檔案

2. 調整日誌級別：

   • 在系統設定中降低日誌級別
   • 生產環境建議使用 WARN 或 ERROR 級別
   • 避免長期使用 DEBUG 級別

3. 啟用日誌輪轉：

   • 配置日誌自動輪轉策略
   • 設定單個日誌檔案大小限制
   • 設定日誌保留天數（如 7 天）

4. 定期清理：

   • 建議每週清理一次日誌
   • 或配置自動清理任務
   • 保留最近 3-7 天的日誌即可

1.20 應用更新失敗

問題描述：檢測到新版本後，更新下載失敗或安裝失敗。

解決方案：

1. 檢查網路連線：

   • 確認網路連線穩定
   • 下載大檔案（約 5GB）需要穩定網路
   • 避免使用不穩定的 Wi-Fi

2. 檢查磁碟空間：

   • 確保至少有 10GB 可用空間
   • 更新需要下載新版本並解壓
   • 清理磁碟後重試

3. 手動下載更新：

   • 訪問官網下載最新版本
   • 或從百度網盤/GitHub 下載
   • 手動安裝更新包

4. 檢視更新日誌：

   • 開啟 日誌管理
   • 檢視更新過程中的錯誤資訊
   • 根據錯誤資訊排查

詳見 版本升級。

2. Windows 平臺

開發中

Windows 版本正在開發中，敬請期待。

如果你對 Windows 版本有任何建議或需求，歡迎透過以下方式反饋：

• GitHub Issues：https://github.com/cuemate-chat/cuemate/issues
• 郵箱：nuneatonhydroplane@gmail.com

獲取更多幫助

如果以上方法都無法解決你的問題，可以透過以下方式獲取幫助：

檢視文件

• 功能手冊 - 詳細的功能使用說明
• 模型配置 - 大語言模型配置指南
• 安裝問題 - 安裝相關問題
• 常見問題彙總 - 更多常見問題

聯絡技術支援

• GitHub Issues：https://github.com/cuemate-chat/cuemate/issues
• 郵箱：nuneatonhydroplane@gmail.com

提交問題時，請提供：

1. CueMate 版本號
2. 作業系統版本
3. 詳細的問題描述和截圖
4. 相關的錯誤日誌
5. 已嘗試的解決方法