OpenAI SDK

瓜瓜AI 提供 OpenAI 相容介面，因此可以直接使用 OpenAI 官方 SDK，只需更換 base_url 與 api_key。

安裝

Python

pip install openai

Node.js

npm install openai

基本設定

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GUAGUA_API_KEY"],          # 建議用環境變數
    base_url="https://api.guagua5487.xyz/v1",      # 只到 /v1
)

resp = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "你好，請用一句話自我介紹。"}],
)

print(resp.choices[0].message.content)

Node.js

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.GUAGUA_API_KEY,
  baseURL: 'https://api.guagua5487.xyz/v1'
})

const resp = await client.chat.completions.create({
  model: 'MODEL_ID',
  messages: [{ role: 'user', content: '你好，請用一句話自我介紹。' }]
})

console.log(resp.choices[0].message.content)

不要硬編碼金鑰

請勿把 api_key="sk-..." 之類的真實字串寫進原始碼。範例中的 YOUR_API_KEY、MODEL_ID 皆為佔位字串。

多輪對話

API 是無狀態的，多輪對話需自行帶上先前的訊息：

messages = [
    {"role": "system", "content": "你是一位技術文件助理，請用繁體中文回答。"},
]

def ask(text: str) -> str:
    messages.append({"role": "user", "content": text})
    resp = client.chat.completions.create(model="MODEL_ID", messages=messages)
    answer = resp.choices[0].message.content or ""
    messages.append({"role": "assistant", "content": answer})
    return answer

print(ask("什麼是 Base URL？"))
print(ask("那 /v1 可以省略嗎？"))

串流輸出

stream = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "請用 200 字介紹串流輸出。"}],
    stream=True,
)

for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)

const stream = await client.chat.completions.create({
  model: 'MODEL_ID',
  messages: [{ role: 'user', content: '請用 200 字介紹串流輸出。' }],
  stream: true
})

for await (const chunk of stream) {
  process.stdout.write(chunk.choices?.[0]?.delta?.content ?? '')
}

詳細格式與注意事項見 串流輸出。

逾時與重試

長時間或串流請求建議明確設定逾時；429 與 5xx 可搭配指數退避重試：

from openai import OpenAI, APIStatusError, APIConnectionError
import time

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.guagua5487.xyz/v1",
    timeout=60.0,      # 秒
    max_retries=2,     # SDK 內建重試次數
)

def chat(prompt: str, attempts: int = 3) -> str:
    for i in range(attempts):
        try:
            resp = client.chat.completions.create(
                model="MODEL_ID",
                messages=[{"role": "user", "content": prompt}],
            )
            return resp.choices[0].message.content or ""
        except APIStatusError as e:
            # 429 / 5xx 可重試，其餘直接拋出
            if e.status_code not in (429, 500, 502, 503, 504) or i == attempts - 1:
                raise
            time.sleep(2 ** i)
        except APIConnectionError:
            if i == attempts - 1:
                raise
            time.sleep(2 ** i)
    return ""

串流不要盲目重試

串流中斷時，已輸出的內容無法續傳，重試會讓使用者看到重複內容。請依產品需求決定是否重試。

常見錯誤對照

例外／狀態碼	意義	文件
400	請求格式或參數錯誤	400 Bad Request
401	金鑰無效或缺失	401 Unauthorized
403	無使用權限	403 Forbidden
429	超過速率限制	429 Too Many Requests
500 / 502 / 503 / 504	上游服務異常	5xx 上游錯誤
連線逾時 / APIConnectionError	網路或 Proxy 問題	先用 curl 驗證

檢查清單

• [ ] base_url 為 https://api.guagua5487.xyz/v1（不多不少）
• [ ] api_key 由環境變數讀取
• [ ] model 使用實際存在的模型代號
• [ ] 已針對 429 / 5xx 設計重試與退避
• [ ] 已在日誌中記錄回應的 id 與 model，方便回報問題

相關頁面

• Chat Completions
• OpenAI 相容性
• 模型選擇