AIProxyServer - Panduan

Bermula

1. Lancarkan Aplikasi

Buka AIProxyServer. Pada pelancaran pertama, proxy bermula secara automatik dan mendengar pada port 8421 mesin tempatan anda. Tetingkap utama memaparkan tiga bahagian:

• Proxy Server — status semasa, URL asas, dan butang untuk memulakan atau menghentikan pendengar
• Bearer Token — suis pengesahan pilihan dan paparan token
• Providers — setiap pembekal AI awan yang disokong, dengan butang Set API Key setiap baris

2. Tambah Kunci API Pertama Anda

1. Pilih mana-mana pembekal daripada senarai Providers (contohnya OpenAI (ChatGPT))
2. Klik Get API key untuk membuka konsol pembekal dalam pelayar anda, kemudian buat atau salin kunci
3. Klik Set API Key pada baris yang sama dan tampal nilainya ke dalam dialog
4. Klik Save. Label status bertukar kepada Configured berwarna hijau

3. Sambungkan Aplikasi Pelanggan

Halakan mana-mana pelanggan yang serasi dengan OpenAI ke proxy. Base URL ialah http://localhost:8421/<provider>/v1. Segmen provider memilih awan mana yang menerima permintaan.

# Contoh: OpenAI Python SDK dihalakan ke proxy
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)

Pelanggan tidak pernah melihat kunci sebenar. AIProxyServer melampirkan kredensial upstream apabila ia memajukan permintaan.

Gambaran Keseluruhan Antara Muka

Panel Proxy Server

Panel Bearer Token

• Require Bearer Token authentication — kotak semak yang menghidupkan atau mematikan pengesahan. Mati secara lalai untuk penggunaan tempatan tanpa kerumitan.
• Medan token — paparan baca sahaja bagi token semasa. Ditunjukkan sebagai titik; gunakan Copy untuk mengambilnya.
• Regenerate — menerbitkan token rawak baharu. Pelanggan sedia ada mesti dikemas kini dengan nilai baharu.

Panel Providers

Satu baris bagi setiap pembekal awan yang disokong. Setiap baris menunjukkan:

• Nama paparan (contohnya Claude (Anthropic))
• Status konfigurasi — Configured berwarna hijau apabila kunci API disimpan, Not configured berwarna kelabu sebaliknya
• Laluan URL yang digunakan oleh pelanggan anda, contohnya /anthropic/v1/chat/completions
• Set API Key — membuka dialog untuk memasukkan kredensial
• Get API key — membuka konsol pembekal dalam pelayar anda

Pembekal yang Disokong

Sebelas perkhidmatan AI awan disertakan. Kebanyakannya menggunakan format OpenAI Chat Completions secara semula jadi dan diproksikan seadanya. Tiga (Anthropic, Gemini, ERNIE) bertutur dengan protokol mereka sendiri; AIProxyServer menterjemah permintaan dan respons secara langsung supaya pelanggan anda hanya melihat bentuk OpenAI sahaja.

Nota khusus pembekal

• Azure OpenAI — tampal endpoint deployment penuh ke dalam medan Endpoint Base URL, contohnya https://my-resource.openai.azure.com/openai/deployments/gpt-4o. Proxy menambah /chat/completions?api-version=2024-02-01 secara automatik.
• ERNIE — Baidu Qianfan menggunakan OAuth, jadi kedua-dua API Key dan Secret Key diperlukan. AIProxyServer meminta dan menyimpan cache token akses di belakang tabir.
• Gemini — pengesahan dilakukan melalui parameter pertanyaan URL; proxy menambahnya untuk anda. Kuota seminit peringkat percuma masih terpakai.

Rujukan API

Endpoint

Streaming

Apabila pelanggan menghantar "stream": true, proxy bertindak balas dengan Server-Sent Events dalam format OpenAI:

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

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

data: [DONE]

Strim asli Anthropic dan Gemini diterjemahkan kepada bentuk ini supaya semua pelanggan boleh menggunakan satu parser tunggal.

Pengepala pengesahan

Apabila Require Bearer Token authentication dihidupkan, hantar token dari tetingkap utama dengan setiap permintaan:

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

Tetapan

Buka tetingkap Settings dari ikon gear di bar alat bawah.

Contoh Pelanggan

cURL

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

# Claude melalui bentuk OpenAI yang sama
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",  # ignored when Bearer Token is off
)
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

// Using any OpenAI-compatible Dart client
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // unused when Bearer Token is off
);

Petua

• Biarkan Bearer Token mati semasa anda membangunkan secara tempatan; hidupkan sebaik sahaja anda mendayakan akses LAN.
• Gunakan Base URL yang berbeza setiap pembekal dalam kod pelanggan anda supaya anda boleh menukar pembekal dengan menukar satu pemalar.
• Proxy bermula automatik tetapi anda boleh menghentikannya sementara dari tetingkap utama jika berlaku konflik port.
• Jika peringkat percuma pembekal menghadkan kadar anda, mesej ralat upstream dimajukan apa adanya. Tiada logik cuba semula disembunyikan daripada pelanggan.
• Endpoint /v1/providers berguna untuk menemui pembekal mana yang dikonfigurasi pada masa larian.

Penyelesaian Masalah

Proxy tidak akan bermula

• Proses lain mungkin sudah menggunakan port 8421. Tukar port dalam Settings dan mulakan semula proxy.
• Semak log sistem untuk mesej ralat yang dipaparkan pada masa mula.

Permintaan mengembalikan 401 Unauthorized

• Keperluan Bearer Token hidup tetapi pelanggan tidak menghantar pengepala Authorization: Bearer ... yang sepadan.
• Kunci API pembekal mungkin tidak sah — ralat upstream dimajukan jadi semak badan mesej.

Permintaan mengembalikan "API key is not configured"

• Buka senarai Providers dan klik Set API Key untuk pembekal yang dimaksudkan.
• Untuk ERNIE, kedua-dua API Key dan Secret Key mesti diisi. Untuk Azure OpenAI, Endpoint Base URL juga diperlukan.

Peranti mudah alih tidak boleh mencapai proxy

• Hidupkan Allow LAN Access dalam Settings.
• Gunakan IP LAN yang ditunjukkan dalam medan Base URL, bukan localhost.
• Pastikan kedua-dua peranti berada pada rangkaian Wi-Fi yang sama dan firewall anda membenarkan sambungan masuk pada port proxy.

Respons streaming tiba sekaligus

• Pastikan pelanggan anda menghantar "stream": true dalam badan JSON.
• Sesetengah perpustakaan HTTP membuat penimbalan SSE secara lalai — lumpuhkan penimbalan respons di sebelah pelanggan.

Privasi

• Kunci API disimpan disulitkan dengan Fernet dalam ~/Library/Application Support/AIProxyServer/credentials.enc. Kunci penyulitan dalam master.key mempunyai keizinan 0600.
• Bearer Token, apabila didayakan, juga disimpan hanya dalam peti besi yang disulitkan dan tidak pernah ditulis ke fail tetapan biasa.
• Proxy hanya memajukan permintaan kepada pembekal yang anda telah konfigurasi secara eksplisit. Ia tidak membuat panggilan keluar lain.
• Tiada telemetri, tiada analitik, tiada pelaporan ranap.
• Pengikatan rangkaian lalai hanya 127.0.0.1. Pendedahan LAN adalah pilihan untuk dimasukkan.
• Kandungan perbualan tidak disimpan. AIProxyServer memajukan bait dan segera melupakannya.