Max Router 入門
選擇模型、建立 API 金鑰,並透過 Max Router 發出第一個請求。

選擇模型與端點
開啟模型廣場,比較可用模型、支援的端點與目前價格。選擇符合應用程式輸入及輸出的模型,記下正確的模型 ID 與端點;不同模型和協定的能力可能不同。
剛接入時,最容易遇到的問題不是不會寫程式碼,而是不知道失敗發生在哪一層。先選一個支援對話介面的模型,讓它回答一句簡單問題。暫時不要同時加入圖片、工具呼叫、流式輸出和複雜系統提示詞。把目標縮小之後,介面地址、金鑰、模型名稱和請求格式都更容易逐項檢查。等基礎請求穩定,再把業務需要的能力一項項加回去。
在模型廣場檢視模型的準確 ID、支援的介面和當前價格。模型展示名便於閱讀,但程式碼通常需要準確的模型 ID;不要自行猜測連字元、斜槓或版本號。不同模型可能走不同介面:能處理文字的介面不一定適合圖片或影片任務。以模型詳情和文件列出的能力為準,並在切換模型後重新驗證關鍵引數。
建立 API 金鑰
登入後開啟 API 金鑰頁面,為應用程式建立金鑰,並儲存在環境變數或密鑰管理服務中。不要把真實金鑰放入瀏覽器程式碼、公開儲存庫或截圖。
為開發和生產分別建立憑據,便於控制使用範圍和排查問題。服務端從環境變數或金鑰管理服務讀取金鑰,再由自己的後端呼叫 API。前端頁面、瀏覽器外掛和公開程式碼都不是保密位置,即使變數名裡包含 SECRET,打包進瀏覽器後仍可能被看到。截圖或日誌洩露金鑰時,應先輪換並檢查使用記錄。
應用程式透過閘道連接文字、圖片與影片模型。傳送請求
下方範例使用聊天補全端點。請將 YOUR_MODEL_ID 換成支援該端點的模型,並設定 MAX_ROUTER_API_KEY 環境變數。圖片及影片生成請使用模型文件列出的對應端點。
curl https://maxrouterai.com/v1/chat/completions \
-H "Authorization: Bearer $MAX_ROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"Hello!"}]}'
檢查結果
檢查回應與錯誤訊息,再到控制台查看用量。先以小型請求驗證所需模型和參數,再參考文件接入串流或工具呼叫。
第一次請求失敗怎麼辦
先核對模型 ID 與端點是否與模型廣場一致。驗證錯誤應檢查金鑰與權限;參數不受支援則需要修改請求。不要在公開求助訊息中貼上金鑰,提供請求識別碼與去識別化的錯誤通常更有幫助。
成功的 HTTP 響應也需要檢查正文:應用真正需要的欄位是否存在,輸出是否符合預期,是否有結束狀態。失敗時先保留請求標識和脫敏後的錯誤資訊。認證錯誤通常要檢查金鑰和許可權,引數錯誤需要修改請求;限流或暫時性故障則要按介面規則決定是否等待重試。不要把所有錯誤都變成無限迴圈。
把一次呼叫拆成三段
當使用者在頁面裡輸入問題後,瀏覽器應該先把請求傳送給你自己的服務端。服務端確認使用者身份,檢查輸入是否符合產品規則,再使用儲存在伺服器上的金鑰呼叫模型介面。收到響應後,只把使用者需要的結果返回頁面。這樣即使有人檢視瀏覽器網路請求,也不會因此拿到平臺金鑰。
排查時可以沿著同一條路徑倒著找:頁面有沒有成功聯絡自己的服務端?服務端是否發出了請求?模型介面返回了狀態碼還是連線錯誤?如果第一段已經失敗,反覆更換模型並不會解決問題。為每次呼叫生成內部請求標識,並在允許的範圍內記錄狀態和耗時,會比儲存整段對話更有幫助。
開發階段還可以先用命令列直接傳送最小請求,再讓服務端程式傳送同樣的請求。兩者的模型 ID、請求地址、請求頭和必要欄位應當一致。如果命令列成功而程式失敗,優先檢查環境變數讀取、執行環境和請求序列化;如果兩者都失敗,再核對賬戶狀態和介面文件。
從結果裡讀出真正的問題
第一次看到成功狀態時,不妨多看一步:返回的內容在哪裡?應用有沒有正確處理空內容、結束原因或模型拒絕?不同介面的響應結構可能不同,讀取欄位時應以實際使用的協議為準。不要把一個示例裡的欄位路徑當作所有模型都通用的約定。
遇到認證錯誤,檢查金鑰是否屬於當前環境、是否被停用,以及請求頭格式是否正確;遇到引數錯誤,先刪去非必需欄位,保留最小請求,再逐項加回。對暫時性限流,按照響應和文件提示等待;對明顯的輸入錯誤,修改請求比重複提交更有效。
在分享問題時,保留請求時間、請求標識、模型 ID 和脫敏後的錯誤型別即可。金鑰、完整使用者輸入、私人圖片連結以及內部服務地址都不應出現在公開帖子裡。如果懷疑憑據已經洩露,先停用或輪換,再檢視相關用量,不能只依賴刪除訊息。
上線前做一輪小範圍驗證
把測試分成幾組:正常短問題、較長輸入、缺少必填欄位、無效金鑰,以及客戶端主動取消。觀察頁面是否有清楚的載入、完成和失敗狀態;服務端是否設定了合理的等待時間;使用者重複點選時是否會產生多次請求。測試環境應使用專門的憑據和不含真實客戶資訊的樣本。
接下來選少量真實使用場景,先讓團隊試用,記錄回答質量、響應時間和實際用量。遇到偶發錯誤時,保留足夠的脫敏上下文以便復現,而不是馬上把所有失敗都設定成自動重試。上線範圍可以逐步擴大,每次調整後比較錯誤率和使用成本。
最後把模型名稱、介面、依賴版本和測試日期寫進專案自己的執行記錄。模型或客戶端升級以後,用相同樣本重新驗證。這個小習慣能幫助你區分程式碼改動、配置變化和上游能力變化,也讓下一位接手的人知道該從哪裡開始。
如果測試結果與文件不一致,先記錄具體模型、介面和輸入條件,再檢查近期的配置變化。可以把問題縮小到一條不含金鑰的請求,向支援團隊提供請求標識和發生時間。這樣既保護使用者資訊,也能減少雙方來回確認的次數。
下一步穩一點
小型請求成功後,再用接近真實業務的輸入檢查結果是否符合需求。一次接入一項能力,把憑證留在伺服器端,並在增加流量前查看用量。模型目前的限制和支援選項應以對應文件為準。
用一組接近真實業務、但不含真實敏感資訊的樣本試執行,記錄質量、耗時、用量和錯誤。再測試金鑰失效、網路中斷以及使用者取消操作,確保頁面能給出明確反饋。確認結果後逐步增加流量,並持續檢視控制檯中的實際用量。價格、模型能力和速率限制可能變化,上線前和後續調整時都應重新核對。
把第一次成功請求使用的模型 ID、介面、非敏感引數和驗證日期記下來。以後更換依賴或模型時,可以用同一份小樣本比較變化。記錄中不要儲存金鑰、使用者輸入或完整客戶資料;需要團隊協作時,分享可以復現問題的最小請求結構和脫敏錯誤,比轉發整個生產日誌更安全也更容易討論。