模型選擇

瓜瓜AI 以單一 API 提供多個模型，透過請求中的 model 參數切換。

{
  "model": "MODEL_ID",
  "messages": [{ "role": "user", "content": "你好" }]
}

model 參數規則

項目	說明
型別	字串
必填	是（多數 OpenAI 相容實作要求明確指定）
內容	模型代號（model ID），例如 MODEL_ID 這種識別字串
大小寫	待補充（建議完全照抄服務端回傳的代號）
預設值	待補充（請勿依賴預設值，建議一律明確指定）

待補充

瓜瓜AI 實際開放的模型代號尚未確認，因此本文件一律以 MODEL_ID 佔位，不會憑空列出模型名稱。取得正確代號的方式請見 支援模型。

如何取得可用模型

方式一：查詢模型端點（待確認）

若瓜瓜AI 開放 OpenAI 相容的模型列表端點，可這樣查：

curl https://api.guagua5487.xyz/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

預期的回應結構（示意）：

{
  "object": "list",
  "data": [
    { "id": "MODEL_ID", "object": "model", "created": 1735689600, "owned_by": "guagua" }
  ]
}

待補充

GET /v1/models 是否開放尚待官方確認。若該端點不存在，請改用下方方式二。

方式二：官方公告或後台

以官方文件、公告或管理後台顯示的模型代號為準。

方式三：客戶端內建清單

部分客戶端（如 Cherry Studio）在填好 Base URL 與 API Key 後，可自動抓取模型清單；若抓不到，通常代表該端點未開放或設定有誤。

模型代號寫錯會怎樣

情況	可能的回應	處理
代號不存在或拼錯	400 或 404（依實作而定）	確認代號來源，見 400 Bad Request
代號存在但你無權限	403	見 403 Forbidden
代號已下線	錯誤回應或自動對應其他模型	改用現行代號

待補充

瓜瓜AI 對「無效模型代號」的實際狀態碼與錯誤訊息格式尚待確認。除錯時請直接檢視回應主體內容。

切換模型的實務建議

1. 不要把模型代號散落在程式各處：集中在設定檔或環境變數，切換時只改一處。
2. 區分用途：輕量任務與複雜任務用不同模型，詳見 模型選擇指南。
3. 上線前實測：不同模型對提示詞（prompt）的反應不同，切換後請重跑測試案例。
4. 保留降級路徑：主要模型失敗時可改呼叫備援模型，但請確認該模型確實存在。
5. 記錄使用中的模型：把回應中的 model 欄位寫進日誌，方便追查行為差異。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GUAGUA_API_KEY"],
    base_url="https://api.guagua5487.xyz/v1",
)

MODEL = os.environ.get("GUAGUA_MODEL", "MODEL_ID")

resp = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "你好"}],
)

print("used model:", resp.model)
print(resp.choices[0].message.content)

別名與版本

許多服務會同時提供「指向最新版的別名」與「固定版本代號」。固定版本可讓行為穩定，別名則會自動獲得更新。

待補充

瓜瓜AI 是否提供模型別名、版本後綴或快照（snapshot）機制，尚待官方確認。

相關頁面

• 支援模型 — 模型清單（待補充）
• 模型選擇指南 — 依用途挑選模型
• OpenAI 相容性
• Chat Completions