AIProxyServer - Panduan

Memulai

1. Jalankan Aplikasi

Buka AIProxyServer. Saat pertama kali dijalankan, proxy langsung aktif dan mendengarkan pada port 8421 di komputer lokal Anda. Jendela utama menampilkan tiga bagian:

• Proxy Server — status saat ini, base URL, dan tombol untuk memulai atau menghentikan listener
• Bearer Token — sakelar autentikasi opsional dan tampilan token
• Penyedia — semua penyedia AI cloud yang didukung, lengkap dengan tombol Atur Kunci API di setiap baris

2. Tambahkan Kunci API Pertama Anda

1. Pilih penyedia mana pun dari daftar Penyedia (misalnya OpenAI (ChatGPT))
2. Klik Dapatkan kunci API untuk membuka konsol penyedia di peramban Anda, lalu buat atau salin sebuah kunci
3. Klik Atur Kunci API pada baris yang sama, lalu tempel nilainya ke dalam dialog
4. Klik Simpan. Label status akan berubah menjadi Terkonfigurasi berwarna hijau

3. Hubungkan Aplikasi Klien

Arahkan klien apa pun yang kompatibel dengan OpenAI ke proxy. Base URL-nya adalah http://localhost:8421/<provider>/v1. Segmen penyedia menentukan cloud mana yang menerima permintaan.

# Example: OpenAI Python SDK pointed at the 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)

Klien tidak pernah melihat kunci yang sebenarnya. AIProxyServer melampirkan kredensial upstream saat meneruskan permintaan.

Sekilas Antarmuka

Panel Proxy Server

Panel Bearer Token

• Wajibkan autentikasi Bearer Token — kotak centang untuk mengaktifkan atau menonaktifkan autentikasi. Nonaktif secara default agar penggunaan lokal bebas repot.
• Kolom token — tampilan hanya-baca dari token saat ini. Ditampilkan sebagai titik-titik; gunakan Salin untuk mengambilnya.
• Buat Ulang — menerbitkan token acak yang baru. Klien yang sudah ada harus diperbarui dengan nilai baru tersebut.

Panel Penyedia

Satu baris untuk setiap penyedia cloud yang didukung. Setiap baris menampilkan:

• Nama tampilan (misalnya Claude (Anthropic))
• Status konfigurasi — hijau Terkonfigurasi bila kunci API sudah tersimpan, abu-abu Belum dikonfigurasi bila belum
• Jalur URL yang dipakai klien Anda, mis. /anthropic/v1/chat/completions
• Atur Kunci API — membuka dialog untuk memasukkan kredensial
• Dapatkan kunci API — membuka konsol penyedia di peramban Anda

Penyedia yang Didukung

Sebelas layanan AI cloud sudah disertakan. Sebagian besar memakai format OpenAI Chat Completions secara native dan diteruskan apa adanya. Tiga di antaranya (Anthropic, Gemini, ERNIE) memakai protokol sendiri; AIProxyServer menerjemahkan permintaan dan respons secara langsung sehingga klien Anda selalu hanya melihat format OpenAI.

Catatan khusus tiap penyedia

• Azure OpenAI — tempel endpoint deployment lengkap ke kolom Endpoint Base URL , misalnya https://my-resource.openai.azure.com/openai/deployments/gpt-4o. Proxy akan menambahkan /chat/completions?api-version=2024-02-01 secara otomatis.
• ERNIE — Baidu Qianfan memakai OAuth, sehingga baik API Key maupun Secret Key keduanya wajib diisi. AIProxyServer meminta dan menyimpan token akses di balik layar.
• Gemini — autentikasi dilakukan lewat parameter kueri URL; proxy menambahkannya untuk Anda. Kuota per menit pada paket gratis tetap berlaku.

Referensi API

Endpoint

Streaming

Ketika klien mengirim "stream": true, proxy merespons 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]

Stream native Anthropic dan Gemini diterjemahkan ke bentuk ini sehingga semua klien cukup memakai satu parser.

Header autentikasi

Ketika Wajibkan autentikasi Bearer Token aktif, kirimkan token dari jendela utama pada setiap permintaan:

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

Pengaturan

Buka jendela Pengaturan lewat ikon roda gigi di bilah alat bawah.

Contoh Klien

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 via the same OpenAI shape
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
);

Tips

• Biarkan Bearer Token nonaktif selama Anda mengembangkan secara lokal; aktifkan begitu Anda mengizinkan akses LAN.
• Gunakan Base URL yang berbeda untuk tiap penyedia di kode klien Anda agar Anda bisa berganti penyedia hanya dengan mengubah satu konstanta.
• Proxy dimulai otomatis, tetapi Anda dapat menghentikannya sementara dari jendela utama jika terjadi konflik port.
• Jika paket gratis suatu penyedia membatasi laju permintaan Anda, pesan kesalahan upstream diteruskan apa adanya. Tidak ada logika percobaan ulang yang disembunyikan dari klien.
• Endpoint /v1/providers berguna untuk mengetahui penyedia mana saja yang terkonfigurasi saat runtime.

Pemecahan Masalah

Proxy tidak mau dijalankan

• Proses lain mungkin sudah memakai port 8421. Ubah port di Pengaturan lalu jalankan ulang proxy.
• Periksa log sistem untuk melihat pesan kesalahan yang muncul saat proxy dimulai.

Permintaan mengembalikan 401 Unauthorized

• Kewajiban Bearer Token sedang aktif, tetapi klien tidak mengirimkan header Authorization: Bearer ... yang cocok.
• Kunci API milik penyedia itu sendiri mungkin tidak valid — kesalahan upstream diteruskan, jadi periksa isi pesannya.

Permintaan mengembalikan "API key is not configured"

• Buka daftar Penyedia lalu klik Atur Kunci API untuk penyedia yang bersangkutan.
• Untuk ERNIE, API Key dan Secret Key keduanya harus diisi. Untuk Azure OpenAI, Endpoint Base URL juga wajib diisi.

Perangkat seluler tidak dapat menjangkau proxy

• Aktifkan Izinkan Akses LAN di Pengaturan.
• Gunakan IP LAN yang ditampilkan di kolom Base URL, bukan localhost.
• Pastikan kedua perangkat berada di jaringan Wi-Fi yang sama dan firewall Anda mengizinkan koneksi masuk pada port proxy.

Respons streaming datang sekaligus

• Pastikan klien Anda mengirimkan "stream": true di dalam body JSON.
• Sebagian pustaka HTTP menyangga SSE secara default — matikan buffering respons di sisi klien.

Privasi

• Kunci API disimpan dalam bentuk terenkripsi dengan Fernet di ~/Library/Application Support/AIProxyServer/credentials.enc. Kunci enkripsi di master.key memiliki izin 0600.
• Bearer Token, bila diaktifkan, juga hanya disimpan di brankas terenkripsi dan tidak pernah ditulis ke berkas pengaturan biasa.
• Proxy hanya meneruskan permintaan ke penyedia yang Anda konfigurasikan secara eksplisit. Tidak ada panggilan keluar lainnya.
• Tanpa telemetri, tanpa analitik, tanpa pelaporan kerusakan.
• Pengikatan jaringan default hanyalah 127.0.0.1 saja. Paparan ke LAN sepenuhnya opsional dan harus Anda aktifkan sendiri.
• Isi percakapan tidak disimpan. AIProxyServer meneruskan byte lalu langsung melupakannya.