AIProxyServer - Rehber

Başlarken

1. Uygulamayı Başlatın

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

• Proxy Sunucusu — 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
• Sağlayıcılar — desteklenen her bulut AI sağlayıcısı ve her satırda bir API Anahtarını Ayarla düğmesi

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

1. Sağlayıcılar listesinden herhangi bir sağlayıcıyı seçin (örneğin OpenAI (ChatGPT))
2. Tıklayın API anahtarını al sağlayıcının konsolunu tarayıcınızda açın; ardından aynı satırda bir anahtar oluşturun veya kopyalayın
3. Tıklayın API Anahtarını Ayarla ve değeri iletişim kutusuna yapıştırın
4. Tıklayın Kaydet. Durum etiketi şuna dönüşür: Yapılandırıldı yeşil renkte

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

Herhangi bir OpenAI uyumlu istemciyi proxy'ye yönlendirin. Temel URL şudur: http://localhost:8421/<provider>/v1. Sağlayıcı bölümü, isteği hangi bulutun alacağını seçer.

# Proxy'ye yönlendirilmiş OpenAI Python SDK örneği
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 gerçek anahtarı asla görmez. AIProxyServer, isteği iletirken üst akış kimlik bilgilerini ekler.

Arayüze Genel Bakış

Proxy Sunucusu Paneli

Bearer Token Paneli

• Bearer Token kimlik doğrulamasını zorunlu tut — kimlik doğrulamayı açıp kapatan onay kutusu. Sorunsuz yerel kullanım için varsayılan olarak kapalıdır.
• Token alanı — geçerli tokenın salt okunur gösterimi. Noktalarla gösterilir; şunu kullanın: Kopyala almak için.
• Yeniden oluştur — yeni bir rastgele token oluşturur. Mevcut istemciler yeni değerle güncellenmelidir.

Sağlayıcılar 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 — yeşil Yapılandırıldı bir API anahtarı kaydedildiğinde, gri Yapılandırılmadı aksi hâlde
• İstemcilerinizin kullandığı URL yolu, örneğin /anthropic/v1/chat/completions
• API Anahtarını Ayarla — kimlik bilgilerini girmek için bir iletişim kutusu açar
• API anahtarını al — sağlayıcının konsolunu tarayıcınızda açar

Desteklenen Sağlayıcılar

On bir bulut AI hizmeti dahildir. Çoğu OpenAI Chat Completions biçimini yerel olarak kullanır ve olduğu gibi proxy'lenir. Üçü (Anthropic, Gemini, ERNIE) kendi protokollerini kullanır; AIProxyServer istekleri ve yanıtları anında çevirir, böylece istemciniz yalnızca OpenAI biçimlerini görür.

Sağlayıcıya özgü notlar

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

API Başvurusu

Uç Noktalar

Akış

İstemci şunu gönderdiğinde: "stream": true, proxy OpenAI biçiminde 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'nin yerel akışları bu biçime çevrilir; böylece tüm istemciler tek bir ayrıştırıcı kullanabilir.

Kimlik Doğrulama Başlığı

Şu özellik Bearer Token kimlik doğrulamasını zorunlu tut etkin olduğunda, ana penceredeki tokenı her istekle 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çimiyle 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 kapalıyken yok sayılır
)
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

// Herhangi bir OpenAI uyumlu Dart istemcisi kullanarak
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // Bearer Token kapalıyken kullanılmaz
);

İpuçları

• Yerel geliştirme yaparken Bearer Token'ı kapalı bırakın; LAN erişimini etkinleştirdiğiniz anda açın.
• İstemci kodunuzda her sağlayıcı için ayrı Temel URL kullanın; böylece tek bir sabiti değiştirerek sağlayıcı değiştirebilirsiniz.
• Proxy otomatik başlar; ancak bağlantı noktası çakışması olursa ana pencereden geçici olarak durdurabilirsiniz.
• Bir sağlayıcının ücretsiz katmanı hız sınırı uygularsa üst akış hata mesajı aynen iletilir. İstemciden gizlenen bir yeniden deneme mantığı yoktur.
• Şu /v1/providers uç nokta, ç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şlatılamıyor

• Başka bir işlem 8421 bağlantı noktasını zaten kullanıyor olabilir. Ayarlar'dan bağlantı noktasını değiştirin ve proxy'yi yeniden başlatın.
• Başlatma sırasında gösterilen hata mesajı için sistem günlüğünü kontrol edin.

Bir istek 401 Unauthorized döndürüyor

• Bearer Token zorunluluğu 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 — üst akış hatası iletildiğinden mesaj gövdesini kontrol edin.

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

• Sağlayıcılar listesini açıp şuna tıklayın: API Anahtarını Ayarla söz konusu sağlayıcı için.
• ERNIE için hem API Key hem Secret Key doldurulmalıdır. Azure OpenAI için Endpoint Base URL de gereklidir.

Mobil cihaz proxy'ye ulaşamıyor

• Şunu açın: LAN Erişimine İzin Ver Ayarlar'da.
• Base URL alanında gösterilen LAN IP'sini kullanın; şunu kullanmayın: localhost.
• Her iki cihazın da aynı Wi-Fi ağında olduğundan ve güvenlik duvarınızın proxy bağlantı noktasındaki gelen bağlantılara izin verdiğinden emin olun.

Akış yanıtları bir kerede geliyor

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

Gizlilik

• API anahtarları Fernet ile şurada şifrelenerek saklanır: ~/Library/Application Support/AIProxyServer/credentials.enc. Şifreleme anahtarı şurada bulunur: master.key ve 0600 izinlerine sahiptir.
• Etkinleştirildiğinde Bearer Token da yalnızca şifreli kasada saklanır ve normal ayarlar dosyasına asla yazılmaz.
• Proxy yalnızca açıkça yapılandırdığınız sağlayıcılara istek iletir. Başka dış çağrı yapmaz.
• Telemetri, analiz veya çökme raporu yoktur.
• Varsayılan ağ bağlaması şudur: 127.0.0.1 yalnızca. LAN'a açılma isteğe bağlıdır.
• Konuşma içerikleri saklanmaz. AIProxyServer baytları iletir ve hemen unutur.