標籤

從 404 到正常運行：Hindsight × MiniMax 串接疑難排解

從 404 到正常運行：Hindsight × MiniMax 串接疑難排解

噩夢的開始

一切看起來都設定好了——你已經安裝完 Hindsight、填好了 API Key、啟動了服務器興沖沖地測試了第一筆記憶萃取功能，然後看到這個錯誤：

NotFoundError: <html>
<head><title>404 Not Found</title></head>
<body><h1>404 Not Found</h1></body>
</html>

你的心沈了下去。明明按照官方文件設定的，為什麼會得到 404？

這不是你的問題。這是我在串接 Hindsight 與 MiniMax API 時實際遇到的困境，以及我如何一步步解決它的故事。

重要觀念：MiniMax 有兩個 API 版本

在開始解決問題之前，必須先澄清一個關鍵概念。MiniMax API 有兩個完全不同的版本，適用於不同地區的用戶：

版本API 端點適用用戶
國際版https://api.minimaxi.io海外用戶、中國大陸以外的地區
中國國內版https://api.minimaxi.com中國大陸境內用戶

這兩個端點是完全獨立的系統，不能混用。

如果你在臺灣、日本、美國等地區，應該使用 api.minimaxi.io。

如果你在中國大陸境內，應該使用 api.minimaxi.com。

用錯端點會導致 404 錯誤，因為你的 API Key 根本沒有在那個端點上註冊。

問題回顧

確認你的錯誤症狀是否符合以下情況：

症狀 1：所有 API 呼叫都返回 404

當你嘗試執行 /memories/retain 或 /memories/recall 時，伺服器回應 404。但健康檢查端點 /health 正常運作。

症狀 2：日誌出現奇怪的 URL

你的錯誤日誌顯示的路徑，與你預期的完全不符。例如你設定了國際版 URL，但系統卻使用了國內版的位址。

症狀 3：認證失敗（401 或 403）

API 返回「Unauthorized」或「Forbidden」錯誤，雖然你確定 API Key 是正確的。

如果你的情況符合以上任何一種，這篇文章也許能幫到你。

問題一：選錯了 API 端點

發生了什麼事

這是最常見的錯誤。

我在串接時一開始設定了：

HINDSIGHT_API_LLM_BASE_URL=https://api.minimaxi.com/v1

但我身在臺灣，使用的是國際版的 API Key。國際版的端點是 api.minimaxi.io，不是 api.minimaxi.com。

當我把 API Key送到錯誤的端點，自然就收到了 404 錯誤。

如何確認你應該用哪個端點

方法 1：看你的 API Key 前綴

  • 如果你的 Key 以 sk-cp- 開頭，且是從國外的 MiniMax 開發者平臺取得的 → 使用 api.minimaxi.io
  • 如果你的 Key 是中國大陸的平臺帳號取得的 → 使用 api.minimaxi.com

方法 2：看 MiniMax 的官方文件來源

如果你是在 MiniMax 海外官網（api.minimaxi.com）或文件中看到 URL，那應該是錯的。真正的國際版文件應該顯示 api.minimaxi.io。

如何修復

確認你的 .env 檔案中使用了正確的端點：

# 臺灣/海外用戶（國際版）
HINDSIGHT_API_LLM_BASE_URL=https://api.minimaxi.io/v1

# 中國大陸用戶（國內版）
HINDSIGHT_API_LLM_BASE_URL=https://api.minimaxi.com/v1

然後重新啟動 Hindsight。

為什麼文件容易讓人混淆

我懷疑 MiniMax 的文件和 SDK 有時候會把兩個端點搞混。國際版的文件可能偶爾會錯誤地顯示 .com 的 URL，而國內版又可能顯示 .io。這個混淆是很多開發者遇到問題的根源。

問題二：缺少 /v1 後綴

發生了什麼事

這是我花最久時間才發現的問題，特別是因為我同時要搞清楚應該用 .io 還是 .com，加上這個 /v1 前綴的問題，三者結合在一起讓人頭昏腦脹。

在 OpenAI 相容的 API 規範中，SDK 會自動將路徑附加到 baseurl 的結尾。如果你的 baseurl 是：

https://api.minimaxi.io

SDK 會自動變成：

https://api.minimaxi.io/chat/completions

但 MiniMax 的 API 端點需要 /v1 前綴，正確的應該是：

https://api.minimaxi.io/v1/chat/completions

差別就在於 /v1！沒有這個前綴，你的請求會被送到一個不存在的端點，然後得到 404。

這個問題在國際版和國內版都存在。

如何修復

確認你的 HINDSIGHTAPILLMBASEURL 環境變數包含 /v1 後綴：

# 錯誤（缺少 /v1）
export HINDSIGHT_API_LLM_BASE_URL=https://api.minimaxi.io

# 正確
export HINDSIGHT_API_LLM_BASE_URL=https://api.minimaxi.io/v1

# 或是中國大陸版本
export HINDSIGHT_API_LLM_BASE_URL=https://api.minimaxi.com/v1

然後重新啟動 Hindsight。

問題三：API Key 格式不正確

發生了什麼事

MiniMax 的 API Key 有兩種主要格式：

  1. 普通按量付費的 Key：以標準格式開頭
  2. Plus 月費方案的 Key：以 sk-cp- 開頭

如果你使用的是 Plus 月費方案，你需要確保：

  • 你使用的是正確的端點（.io 或 .com）
  • 你的 API Key 格式正確

如何確認

登入 MiniMax 開發者平臺，檢查你的 API Key 管理頁面。確認你的 Key 與你選擇的端點是匹配的。

如何修復

在 Hindsight 的 .env 檔案中，確保你使用的是正確的 API Key：

HINDSIGHT_API_LLM_API_KEY=your_key_here

如果 Key 正確但仍然失敗，嘗試以下幾個可能的原因：

  • Key 已經過期或是被撤銷
  • 當月的 API 用量配額已經用完
  • 你的方案不支援該模型

問題四：網路與防火牆

發生了什麼事

有時候問題根本不在 API Key 或 URL，而是網路連線。

如果你的 Hindsight 運行在本地環境，但 MiniMax API 需要對外連線，你可能會遇到暫時性的網路問題，特別是在中國大陸境內或是有嚴格網路管制的環境中。

如何確認

嘗試用 curl 測試 MiniMax API 是否可以正常連線。根據你的版本選擇正確的端點：

國際版測試：

curl -v https://api.minimaxi.io/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"model": "MiniMax-M2.7", "messages": [{"role": "user", "content": "hi"}]}'

中國大陸版測試：

curl -v https://api.minimaxi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"model": "MiniMax-M2.7", "messages": [{"role": "user", "content": "hi"}]}'

如果 curl 也失敗（超時或連線被拒），問題可能在網路層面。

如何修復

  1. 檢查防火牆設定：確保本地端可以對外連線到正確的端點
  2. 設定代理：如果你的網路需要代理，在環境變數中設定 HTTPPROXY 和 HTTPSPROXY
  3. 檢查 DNS：嘗試用 ping api.minimaxi.io 或 ping api.minimaxi.com 確認 DNS 解析正常

實用除錯技巧

技巧 1：查看詳細日誌

Hindsight 的日誌可以幫你定位問題。啟動時加入更詳細的日誌輸出：

hindsight-api --log-level DEBUG

這樣可以看到每一個 API 請求的詳細資訊，包括實際發送的 URL 和收到的回應。

技巧 2：先在官方頁面測試

在確認 API 串接是否正確時，先用 MiniMax 官方提供的測試工具或 API 文件頁面中的「Try it out」功能。確認你的 API Key 在官方頁面可以正常呼叫後，再回來排查 Hindsight 的問題。

技巧 3：逐步測試

不要一次修改太多設定。每次只改一個地方（端點、/v1 前綴、Key），然後測試。這樣你能準確知道是哪個改動解決了問題。

技巧 4：檢查環境變數是否真的生效

有時候我們以為設定了環境變數，但系統可能沒有正確讀取。可以用以下指令確認：

echo $HINDSIGHT_API_LLM_BASE_URL

如果輸出是空的或是舊值，表示環境變數沒有生效。你可能需要重新設定或 source 你的 .env 檔案。

經驗總結

學到的教訓

  1. 先確認你的地理位置和 API 版本：國際版和國內版是完全不同的系統，用錯端點是 404 最常見的原因
  2. 不要忘記 /v1 前綴：這是 OpenAI 相容 API 的標準做法，但很容易被忽略
  3. 文件可能會誤導：MiniMax 的文件有時會把兩個端點搞混，信賴不如實際測試
  4. 日誌是你的好朋友：不要忽視錯誤訊息，它們通常會告訴你問題在哪裡

給新手建議

如果你剛開始使用 Hindsight 和 MiniMax，遇到問題時不要慌張。按照以下順序檢查：

  1. 先確認你使用的是正確的端點（.io 還是 .com）
  2. 確認 API Key 與端點是匹配的
  3. 再確認 API URL 包含 /v1 後綴
  4. 檢查網路連線是否正常
  5. 查看詳細日誌找出具體錯誤點

常見錯誤對照表

錯誤訊息可能原因解決方法
404 Not Found用錯端點（.io vs .com）或缺少 /v1確認正確端點並加上 /v1
401 UnauthorizedAPI Key 錯誤或過期檢查或更新 API Key
403 Forbidden權限不足或配額用完確認方案權限或用量
Connection refused網路問題或防火牆檢查網路設定
fetch failedHindsight API 未啟動或網路問題先啟動 Hindsight 再檢查網路

總結

串接 Hindsight 與 MiniMax API 的過程中，我遇到了不少陷阱。首先要搞清楚國際版和國內版的差異，接著是 /v1 前綴的問題，再加上令人困惑的文件說明，三者結合在一起讓人頭昏腦脹。

但透過逐步排查和仔細檢查錯誤訊息，最終還是找到了所有問題的解決方法。

希望這篇文章能幫你節省一些時間。記住最重要的一點：先確認你使用的是正確的端點！

如果你嘗試了所有方法仍然無法解決，歡迎在留言區提問。

相關文章：

  • 《讓 AI 記得你：Hindsight 記憶系統完整解析》
  • 《從零開始：Hindsight 記憶系統安裝教學》
電子郵件發布
標籤：

留言

張貼留言

歡迎留下您的心靈足跡👍