AIProxyServer - 가이드

快速開始

1. 啟動應用程式

開啟 AIProxyServer。首次啟動時 proxy 會自動開始執行,在本機的連接埠 8421 上監聽。主視窗包含三個區域:

• Proxy Server — 目前狀態、基礎 URL,以及啟動或停止監聽器的按鈕
• Bearer Token — 可選的驗證開關以及權杖顯示
• Providers — 所有支援的雲端 AI 提供者,每列都附有 Set API Key 按鈕

2. 新增第一個 API 金鑰

1. 從 Providers 清單中任選一個提供者(例如 OpenAI (ChatGPT))
2. 點擊 Get API key 在瀏覽器中開啟提供者的主控台,然後建立或複製一個金鑰
3. 點擊同一列的 Set API Key,在對話方塊中貼上值
4. 點擊 Save。狀態標籤會變成綠色的 Configured

3. 連接用戶端應用程式

將任何 OpenAI 相容用戶端指向 proxy。基礎 URL 為 http://localhost:8421/<provider>/v1。其中 provider 區段決定請求被傳送到哪個雲端。

# 範例:指向 proxy 的 OpenAI Python SDK
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/openai/v1",
    api_key="not-used-but-required-by-sdk",
)
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

用戶端永遠不會看到真實金鑰。AIProxyServer 在轉送請求時附加上游憑證。

介面概覽

Proxy Server 面板

Bearer Token 面板

• Require Bearer Token authentication — 開關驗證的核取方塊。為方便本機使用,預設為關閉。
• Token field — 以唯讀方式顯示目前的權杖。以圓點呈現,可使用 Copy 取得。
• Regenerate — 產生新的隨機權杖。現有用戶端必須以新值更新。

Providers 面板

每個支援的雲端提供者佔據一列。每列顯示:

• 顯示名稱(例如 Claude (Anthropic))
• 設定狀態 — API 金鑰已保存時顯示綠色 Configured,否則顯示灰色 Not configured
• 用戶端使用的 URL 路徑,例如 /anthropic/v1/chat/completions
• Set API Key — 開啟輸入憑證的對話方塊
• Get API key — 在瀏覽器中開啟提供者的主控台

支援的提供者

內建 11 種雲端 AI 服務。大多數原生使用 OpenAI Chat Completions 格式,因此直接中繼。3 種(Anthropic、Gemini、ERNIE)使用各自的協定,AIProxyServer 會即時翻譯請求與回應,因此用戶端始終看到的都是 OpenAI 格式。

提供者特定備註

• Azure OpenAI — 將完整的部署端點貼到 Endpoint Base URL 欄位中,例如 https://my-resource.openai.azure.com/openai/deployments/gpt-4o。proxy 會自動附加 /chat/completions?api-version=2024-02-01。
• ERNIE — Baidu Qianfan 使用 OAuth,因此同時需要 API Key 與 Secret Key。AIProxyServer 會在背景請求並快取存取權杖。
• Gemini — 透過 URL 查詢參數進行驗證,proxy 會自動新增。免費層級的每分鐘配額仍然適用。

API 參考

端點

串流傳輸

當用戶端傳送 "stream": true 時,proxy 以 OpenAI 格式的 Server-Sent Events 回應:

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},...}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},...}]}

data: [DONE]

Anthropic 與 Gemini 的原生串流也會被轉換為此格式,因此所有用戶端都可以使用單一解析器。

驗證標頭

啟用 Require Bearer Token authentication 時,每個請求都需附上主視窗中顯示的權杖:

Authorization: Bearer <token-shown-in-app>

設定

從底部工具列的齒輪圖示開啟 Settings 視窗。

用戶端範例

cURL

# OpenAI(直通)
curl http://localhost:8421/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# 透過相同的 OpenAI 格式呼叫 Claude
curl http://localhost:8421/anthropic/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1024
  }'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/gemini/v1",
    api_key="placeholder",  # Bearer Token 關閉時被忽略
)
stream = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{"role": "user", "content": "Tell me a joke"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Flutter / Dart

// 使用任何 OpenAI 相容的 Dart 用戶端
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // Bearer Token 關閉時未使用
);

提示

• 本機開發時保持 Bearer Token 關閉,啟用 LAN 存取的瞬間立即開啟。
• 在用戶端程式碼中為每個提供者使用不同的 Base URL,這樣只需更改一個常數即可切換提供者。
• proxy 會自動啟動,但發生連接埠衝突時可從主視窗暫時停止。
• 若提供者的免費層級對您進行速率限制,上游錯誤訊息將原樣轉送。不會對用戶端隱藏任何重試邏輯。
• /v1/providers 端點對於在執行時發現哪些提供者已設定非常有用。

疑難排解

proxy 無法啟動

• 可能有其他程序已在使用連接埠 8421。請在 Settings 中變更連接埠並重新啟動 proxy。
• 請在系統記錄檔中查看啟動時顯示的錯誤訊息。

請求回傳 401 Unauthorized

• Bearer Token 要求已開啟,但用戶端未傳送對應的 Authorization: Bearer ... 標頭。
• 提供者本身的 API 金鑰可能無效 — 上游錯誤會原樣轉送,請檢查訊息主體。

請求回傳 "API key is not configured"

• 開啟 Providers 清單,點擊對應提供者的 Set API Key。
• 對於 ERNIE,必須同時填寫 API Key 與 Secret Key。對於 Azure OpenAI,還需填寫 Endpoint Base URL。

行動裝置無法存取 proxy

• 在 Settings 中開啟 Allow LAN Access。
• 使用 Base URL 欄位中顯示的 LAN IP,而非 localhost。
• 確認兩台裝置位於同一 Wi-Fi 網路,且防火牆允許對 proxy 連接埠的傳入連線。

串流回應一次全部抵達

• 請確認用戶端在 JSON 主體中傳送了 "stream": true。
• 某些 HTTP 函式庫預設會對 SSE 進行緩衝 — 請在用戶端禁用回應緩衝。

隱私

• API 金鑰使用 Fernet 加密儲存在 ~/Library/Application Support/AIProxyServer/credentials.enc 中。master.key 中的加密金鑰具有 0600 權限。
• 啟用時,Bearer Token 也僅儲存在加密保險庫中,不會寫入一般設定檔。
• proxy 僅向您明確設定的提供者轉送請求。不會發起任何其他對外呼叫。
• 沒有遙測、沒有分析、沒有當機回報。
• 預設網路繫結僅為 127.0.0.1。LAN 公開須主動開啟。
• 不儲存對話內容。AIProxyServer 轉送位元組後立即遺忘。