AIProxyServer - Przewodnik

Pierwsze kroki

1. Uruchom aplikację

Otwórz AIProxyServer. Przy pierwszym uruchomieniu proxy startuje automatycznie i nasłuchuje na porcie 8421 Twojego lokalnego komputera. Główne okno wyświetla trzy sekcje:

• Proxy Server — bieżący status, podstawowy URL i przycisk uruchamiania lub zatrzymywania nasłuchu
• Bearer Token — opcjonalny przełącznik uwierzytelniania i wyświetlanie tokenu
• Providers — wszyscy obsługiwani dostawcy AI w chmurze, z przyciskiem Set API Key w każdym wierszu

2. Dodaj swój pierwszy klucz API

1. Wybierz dowolnego dostawcę z listy Providers (na przykład OpenAI (ChatGPT))
2. Kliknij Get API key, aby otworzyć konsolę dostawcy w przeglądarce, a następnie utwórz lub skopiuj klucz
3. Kliknij Set API Key w tym samym wierszu i wklej wartość do okna dialogowego
4. Kliknij Save. Etykieta statusu zmieni się na zielone Configured

3. Podłącz aplikację kliencką

Skieruj dowolnego klienta zgodnego z OpenAI na proxy. Podstawowy URL to http://localhost:8421/<provider>/v1. Segment provider wybiera, do której chmury trafia żądanie.

# Przykład: OpenAI Python SDK skierowane na 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)

Klient nigdy nie widzi prawdziwego klucza. AIProxyServer dołącza poświadczenia upstream przy przekazywaniu żądania.

Przegląd interfejsu

Panel Proxy Server

Panel Bearer Token

• Require Bearer Token authentication — pole wyboru włączające lub wyłączające uwierzytelnianie. Domyślnie wyłączone dla wygodnego użytku lokalnego.
• Pole tokenu — wyświetla aktualny token tylko do odczytu. Pokazywane jako kropki; użyj Copy, aby go pobrać.
• Regenerate — generuje nowy losowy token. Istniejący klienci muszą zostać zaktualizowani o nową wartość.

Panel Providers

Jeden wiersz na każdego obsługiwanego dostawcę chmury. Każdy wiersz pokazuje:

• Nazwę wyświetlaną (na przykład Claude (Anthropic))
• Status konfiguracji — zielony Configured, gdy klucz API jest zapisany, szary Not configured w przeciwnym razie
• Ścieżka URL, której używają Twoi klienci, np. /anthropic/v1/chat/completions
• Set API Key — otwiera okno dialogowe do wprowadzenia poświadczeń
• Get API key — otwiera konsolę dostawcy w przeglądarce

Obsługiwani Providers

Dołączonych jest jedenaście usług AI w chmurze. Większość natywnie używa formatu OpenAI Chat Completions i jest przekazywana bez zmian. Trzy (Anthropic, Gemini, ERNIE) używają własnych protokołów; AIProxyServer w locie tłumaczy żądania i odpowiedzi, dzięki czemu Twój klient widzi wyłącznie kształty OpenAI.

Uwagi dotyczące poszczególnych dostawców

• Azure OpenAI — wklej pełny punkt końcowy wdrożenia w polu Endpoint Base URL, na przykład https://my-resource.openai.azure.com/openai/deployments/gpt-4o. Proxy automatycznie dołącza /chat/completions?api-version=2024-02-01.
• ERNIE — Baidu Qianfan używa OAuth, więc wymagane są zarówno API Key, jak i Secret Key. AIProxyServer w tle żąda tokenów dostępu i je buforuje.
• Gemini — uwierzytelnianie odbywa się przez parametr zapytania URL; proxy dodaje go za Ciebie. Limity na minutę w darmowym planie nadal obowiązują.

Dokumentacja API

Punkty końcowe

Streaming

Gdy klient wysyła "stream": true, proxy odpowiada Server-Sent Events w formacie 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]

Natywne strumienie Anthropic i Gemini są tłumaczone na ten kształt, dzięki czemu wszyscy klienci mogą używać jednego parsera.

Nagłówek uwierzytelniania

Gdy Require Bearer Token authentication jest włączone, wyślij token z głównego okna przy każdym żądaniu:

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

Ustawienia

Otwórz okno Ustawień, klikając ikonę koła zębatego na dolnym pasku narzędzi.

Przykłady klientów

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 przez ten sam kształt OpenAI
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",  # ignorowane, gdy Bearer Token jest wyłączony
)
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

// Z dowolnym klientem Dart zgodnym z OpenAI
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // nieużywane, gdy Bearer Token jest wyłączony
);

Wskazówki

• Pozostaw Bearer Token wyłączony podczas lokalnego rozwoju; włącz go w momencie, gdy włączysz dostęp LAN.
• Używaj odrębnych podstawowych URL dla każdego dostawcy w kodzie klienta, aby móc przełączać dostawców zmieniając jedną stałą.
• Proxy uruchamia się automatycznie, ale możesz tymczasowo zatrzymać je z głównego okna, jeśli wystąpi konflikt portów.
• Jeśli darmowy plan dostawcy nakłada limity, komunikat błędu upstream jest przekazywany dosłownie. Żadna logika ponawiania nie jest ukryta przed klientem.
• Punkt końcowy /v1/providers jest przydatny do wykrywania w czasie wykonania, którzy dostawcy są skonfigurowani.

Rozwiązywanie problemów

Proxy nie uruchamia się

• Inny proces może już używać portu 8421. Zmień port w Ustawieniach i uruchom proxy ponownie.
• Sprawdź dziennik systemu pod kątem komunikatu błędu wyświetlonego przy starcie.

Żądanie zwraca 401 Unauthorized

• Wymóg Bearer Token jest włączony, ale klient nie wysłał pasującego nagłówka Authorization: Bearer ....
• Klucz API danego dostawcy może być nieprawidłowy — błąd upstream jest przekazywany, więc sprawdź treść komunikatu.

Żądanie zwraca "API key is not configured"

• Otwórz listę Providers i kliknij Set API Key dla danego dostawcy.
• Dla ERNIE wymagane są zarówno API Key, jak i Secret Key. Dla Azure OpenAI wymagany jest też Endpoint Base URL.

Urządzenie mobilne nie może dotrzeć do proxy

• Włącz Allow LAN Access w Ustawieniach.
• Użyj adresu IP LAN pokazywanego w polu Base URL, a nie localhost.
• Upewnij się, że oba urządzenia są w tej samej sieci Wi-Fi i że Twoja zapora pozwala na połączenia przychodzące na porcie proxy.

Odpowiedzi streamingowe przychodzą wszystkie naraz

• Upewnij się, że Twój klient wysyła "stream": true w treści JSON.
• Niektóre biblioteki HTTP domyślnie buforują SSE — wyłącz buforowanie odpowiedzi po stronie klienta.

Prywatność

• Klucze API są szyfrowane przy użyciu Fernet i przechowywane w ~/Library/Application Support/AIProxyServer/credentials.enc. Klucz szyfrowania w master.key ma uprawnienia 0600.
• Bearer Token, gdy włączony, jest również przechowywany wyłącznie w zaszyfrowanym sejfie i nigdy nie jest zapisywany w zwykłym pliku ustawień.
• Proxy przekazuje żądania wyłącznie do dostawców, których jawnie skonfigurowałeś. Nie wykonuje żadnych innych wywołań wychodzących.
• Żadnej telemetrii, żadnej analityki, żadnego raportowania awarii.
• Domyślne wiązanie sieciowe to wyłącznie 127.0.0.1. Ekspozycja w sieci LAN jest opt-in.
• Treści rozmów nie są przechowywane. AIProxyServer przekazuje bajty i natychmiast o nich zapomina.