AIProxyServer - Rehber

Başlarken

1. Uygulamayı Başlatın

AIProxyServer'ı açın. İlk başlatmada proxy otomatik olarak başlar ve yerel makinenizin 8421 portunu dinler. Ana pencere üç bölüm gösterir:

• Proxy Server — mevcut durum, temel URL ve dinleyiciyi başlatma veya durdurma düğmesi
• Bearer Token — isteğe bağlı kimlik doğrulama anahtarı ve token gösterimi
• Providers — her satırda Set API Key düğmesi olan tüm desteklenen bulut AI sağlayıcıları

2. İlk API Anahtarınızı Ekleyin

1. Providers listesinden herhangi bir sağlayıcı seçin (örneğin OpenAI (ChatGPT))
2. Sağlayıcının konsolunu tarayıcınızda açmak için Get API key düğmesine tıklayın, ardından bir anahtar oluşturun veya kopyalayın
3. Aynı satırda Set API Key düğmesine tıklayın ve değeri iletişim kutusuna yapıştırın
4. Save düğmesine tıklayın. Durum etiketi yeşil Configured olarak değişir

3. Bir İstemci Uygulamasını Bağlayın

OpenAI uyumlu herhangi bir istemciyi proxy'ye yönlendirin. Temel URL http://localhost:8421/<provider>/v1 şeklindedir. Provider segmenti hangi bulutun isteği aldığını seçer.

# Örnek: Proxy'ye yönlendirilmiş 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)

İstemci asla gerçek anahtarı görmez. AIProxyServer, isteği iletirken upstream kimlik bilgilerini ekler.

Arayüz Genel Bakış

Proxy Server Paneli

Bearer Token Paneli

• Require Bearer Token authentication — kimlik doğrulamayı açan veya kapatan onay kutusu. Sorunsuz yerel kullanım için varsayılan olarak kapalıdır.
• Token alanı — mevcut tokenin salt okunur görüntüsü. Noktalar olarak gösterilir; almak için Copy kullanın.
• Regenerate — yeni rastgele bir token oluşturur. Mevcut istemcilerin yeni değerle güncellenmesi gerekir.

Providers Paneli

Desteklenen her bulut sağlayıcısı için bir satır. Her satır şunları gösterir:

• Görünen ad (örneğin Claude (Anthropic))
• Yapılandırma durumu — bir API anahtarı kaydedildiğinde yeşil Configured, aksi halde gri Not configured
• İstemcilerinizin kullandığı URL yolu, örn. /anthropic/v1/chat/completions
• Set API Key — kimlik bilgilerini girmek için bir iletişim kutusu açar
• Get API key — sağlayıcının konsolunu tarayıcınızda açar

Desteklenen Sağlayıcılar

On bir bulut AI hizmeti birlikte sunulur. Çoğu OpenAI Chat Completions formatını yerel olarak kullanır ve olduğu gibi proxy üzerinden iletilir. Üçü (Anthropic, Gemini, ERNIE) kendi protokollerini konuşur; AIProxyServer istekleri ve yanıtları anında çevirir, böylece istemciniz yalnızca OpenAI biçimlerini görür.

Sağlayıcıya özel notlar

• Azure OpenAI — tam dağıtım uç noktasını Endpoint Base URL alanına yapıştırın, örneğin https://my-resource.openai.azure.com/openai/deployments/gpt-4o. Proxy otomatik olarak /chat/completions?api-version=2024-02-01 ekler.
• ERNIE — Baidu Qianfan OAuth kullanır, bu nedenle hem API Key hem de Secret Key gereklidir. AIProxyServer arka planda erişim tokenlarını ister ve önbelleğe alır.
• Gemini — kimlik doğrulama URL sorgu parametresi ile yapılır; proxy bunu sizin için ekler. Ücretsiz katman dakika başına kotaları yine de geçerlidir.

API Referansı

Uç Noktalar

Akış

İstemci "stream": true gönderdiğinde, proxy OpenAI formatında Server-Sent Events ile yanıt verir:

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 ve Gemini yerel akışları bu biçime çevrilir, böylece tüm istemciler tek bir ayrıştırıcı kullanabilir.

Kimlik doğrulama başlığı

Require Bearer Token authentication açıkken, her istekte ana penceredeki tokeni gönderin:

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

Ayarlar

Alt araç çubuğundaki dişli simgesinden Ayarlar penceresini açın.

İstemci Örnekleri

cURL

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

# Aynı OpenAI biçimi üzerinden 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",  # 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
);

İpuçları

• Yerel olarak geliştirme yaparken Bearer Token'ı kapalı bırakın; LAN erişimini etkinleştirdiğiniz anda açın.
• İstemci kodunuzda sağlayıcı başına farklı Base URL'ler kullanın, böylece tek bir sabiti değiştirerek sağlayıcıları değiştirebilirsiniz.
• Proxy otomatik başlar, ancak port çakışması olduğunda ana pencereden geçici olarak durdurabilirsiniz.
• Bir sağlayıcının ücretsiz katmanı sizi hız sınırlandırırsa, upstream hata mesajı olduğu gibi iletilir. İstemciden hiçbir yeniden deneme mantığı gizlenmez.
• /v1/providers uç noktası, çalışma zamanında hangi sağlayıcıların yapılandırıldığını keşfetmek için kullanışlıdır.

Sorun Giderme

Proxy başlamıyor

• Başka bir işlem 8421 portunu zaten kullanıyor olabilir. Ayarlarda portu değiştirin ve proxy'yi yeniden başlatın.
• Başlatma sırasında görüntülenen hata mesajı için sistem günlüğünü kontrol edin.

Bir istek 401 Unauthorized döndürüyor

• Bearer Token gerekliliği açık ancak istemci eşleşen bir Authorization: Bearer ... başlığı göndermedi.
• Sağlayıcının kendi API anahtarı geçersiz olabilir — upstream hatası iletilir, bu yüzden mesaj gövdesini kontrol edin.

Bir istek "API key is not configured" döndürüyor

• Providers listesini açın ve söz konusu sağlayıcı için Set API Key düğmesine tıklayın.
• ERNIE için hem API Key hem de Secret Key doldurulmalıdır. Azure OpenAI için Endpoint Base URL de gereklidir.

Mobil cihaz proxy'ye ulaşamıyor

• Ayarlarda Allow LAN Access seçeneğini açın.
• localhost yerine Base URL alanında gösterilen LAN IP'sini kullanın.
• Her iki cihazın da aynı Wi-Fi ağında olduğundan ve güvenlik duvarınızın proxy portunda gelen bağlantılara izin verdiğinden emin olun.

Akış yanıtları hepsi bir anda geliyor

• İstemcinizin JSON gövdesinde "stream": true gönderdiğinden emin olun.
• Bazı HTTP kitaplıkları varsayılan olarak SSE'yi tamponlar — istemci tarafında yanıt tamponlamayı devre dışı bırakın.

Gizlilik

• API anahtarları, ~/Library/Application Support/AIProxyServer/credentials.enc içinde Fernet ile şifrelenmiş olarak saklanır. master.key içindeki şifreleme anahtarı 0600 izinlerine sahiptir.
• Bearer Token, etkinleştirildiğinde yalnızca şifrelenmiş kasada saklanır ve normal ayar dosyasına asla yazılmaz.
• Proxy yalnızca açıkça yapılandırdığınız sağlayıcılara istekleri iletir. Başka hiçbir giden çağrı yapmaz.
• Telemetri, analitik veya çökme raporlaması yok.
• Varsayılan ağ bağlaması yalnızca 127.0.0.1. LAN'a açma isteğe bağlıdır.
• Konuşma içerikleri saklanmaz. AIProxyServer baytları iletir ve hemen unutur.