AIProxyServer - Panduan

Memulai

1. Luncurkan Aplikasi

Buka AIProxyServer. Pada peluncuran pertama, proxy mulai secara otomatis dan mendengarkan pada port 8421 mesin lokal Anda. Jendela utama menampilkan tiga bagian:

• Proxy Server — status saat ini, URL dasar, dan tombol untuk memulai atau menghentikan pendengar
• Bearer Token — sakelar autentikasi opsional dan tampilan token
• Providers — setiap penyedia AI cloud yang didukung, dengan tombol Set API Key per baris

2. Tambahkan Kunci API Pertama Anda

1. Pilih penyedia apa pun dari daftar Providers (misalnya OpenAI (ChatGPT))
2. Klik Get API key untuk membuka konsol penyedia di browser Anda, lalu buat atau salin kunci
3. Klik Set API Key di baris yang sama dan tempelkan nilainya ke dalam dialog
4. Klik Save. Label status berubah menjadi Configured 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 provider memilih cloud mana yang menerima permintaan.

# Contoh: OpenAI Python SDK diarahkan 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)

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

Ikhtisar Antarmuka

Panel Proxy Server

Panel Bearer Token

• Require Bearer Token authentication — kotak centang yang mengaktifkan atau menonaktifkan autentikasi. Nonaktif secara default untuk penggunaan lokal tanpa hambatan.
• Field token — tampilan token saat ini yang hanya bisa dibaca. Ditampilkan sebagai titik; gunakan Copy untuk mengambilnya.
• Regenerate — menerbitkan token acak baru. Klien yang ada harus diperbarui dengan nilai baru.

Panel Providers

Satu baris per penyedia cloud yang didukung. Setiap baris menampilkan:

• Nama tampilan (misalnya Claude (Anthropic))
• Status konfigurasi — Configured berwarna hijau saat kunci API disimpan, Not configured berwarna abu-abu jika tidak
• Jalur URL yang digunakan klien Anda, misalnya /anthropic/v1/chat/completions
• Set API Key — membuka dialog untuk memasukkan kredensial
• Get API key — membuka konsol penyedia di browser Anda

Penyedia yang Didukung

Sebelas layanan AI cloud disertakan. Sebagian besar menggunakan format OpenAI Chat Completions secara native dan diteruskan apa adanya. Tiga (Anthropic, Gemini, ERNIE) berbicara dengan protokol mereka sendiri; AIProxyServer menerjemahkan permintaan dan respons secara langsung sehingga klien Anda hanya melihat bentuk OpenAI.

Catatan khusus penyedia

• Azure OpenAI — tempelkan endpoint deployment lengkap ke dalam field Endpoint Base URL, misalnya https://my-resource.openai.azure.com/openai/deployments/gpt-4o. Proxy secara otomatis menambahkan /chat/completions?api-version=2024-02-01.
• ERNIE — Baidu Qianfan menggunakan OAuth, sehingga baik API Key maupun Secret Key diperlukan. AIProxyServer meminta dan menyimpan token akses di belakang layar.
• Gemini — autentikasi dilakukan melalui parameter kueri URL; proxy menambahkannya untuk Anda. Kuota per menit tingkat gratis tetap berlaku.

Referensi API

Endpoint

Streaming

Saat 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]

Aliran native Anthropic dan Gemini diterjemahkan ke bentuk ini sehingga semua klien dapat menggunakan satu parser.

Header autentikasi

Saat Require Bearer Token authentication aktif, kirim token dari jendela utama dengan setiap permintaan:

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

Pengaturan

Buka jendela Settings dari ikon roda gigi di toolbar 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 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
);

Tips

• Biarkan Bearer Token nonaktif saat Anda mengembangkan secara lokal; aktifkan saat Anda mengaktifkan akses LAN.
• Gunakan Base URL yang berbeda per penyedia dalam kode klien Anda sehingga Anda dapat mengganti penyedia dengan mengubah satu konstanta.
• Proxy mulai otomatis tetapi Anda dapat menghentikannya sementara dari jendela utama jika terjadi konflik port.
• Jika tingkat gratis penyedia membatasi kecepatan Anda, pesan kesalahan upstream diteruskan apa adanya. Tidak ada logika percobaan ulang yang disembunyikan dari klien.
• Endpoint /v1/providers berguna untuk menemukan penyedia mana yang dikonfigurasi saat runtime.

Pemecahan Masalah

Proxy tidak mau dijalankan

• Proses lain mungkin sudah menggunakan port 8421. Ubah port di Settings dan restart proxy.
• Periksa log sistem untuk pesan kesalahan yang ditampilkan saat start.

Permintaan mengembalikan 401 Unauthorized

• Persyaratan Bearer Token aktif tetapi klien tidak mengirim header Authorization: Bearer ... yang cocok.
• Kunci API penyedia mungkin tidak valid — kesalahan upstream diteruskan jadi periksa isi pesan.

Permintaan mengembalikan "API key is not configured"

• Buka daftar Providers dan klik Set API Key untuk penyedia yang bersangkutan.
• Untuk ERNIE, baik API Key maupun Secret Key harus diisi. Untuk Azure OpenAI, Endpoint Base URL juga diperlukan.

Perangkat seluler tidak dapat menjangkau proxy

• Aktifkan Allow LAN Access di Settings.
• Gunakan IP LAN yang ditampilkan di field 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 tiba sekaligus

• Pastikan klien Anda mengirim "stream": true dalam isi JSON.
• Beberapa library HTTP melakukan buffering SSE secara default — nonaktifkan buffering respons di sisi klien.

Privasi

• Kunci API disimpan terenkripsi dengan Fernet di ~/Library/Application Support/AIProxyServer/credentials.enc. Kunci enkripsi di master.key memiliki izin 0600.
• Bearer Token, saat diaktifkan, juga hanya disimpan di vault terenkripsi dan tidak pernah ditulis ke file pengaturan biasa.
• Proxy hanya meneruskan permintaan ke penyedia yang telah Anda konfigurasi secara eksplisit. Tidak ada panggilan keluar lainnya.
• Tidak ada telemetri, tidak ada analitik, tidak ada pelaporan crash.
• Pengikatan jaringan default hanya 127.0.0.1. Eksposur LAN bersifat opt-in.
• Konten percakapan tidak disimpan. AIProxyServer meneruskan byte dan langsung melupakannya.