AIProxyServer - Przewodnik

Pierwsze kroki

1. Uruchom aplikację

Otwórz AIProxyServer. Przy pierwszym uruchomieniu proxy startuje automatycznie i nasłuchuje na porcie 8421 komputera lokalnego. Okno główne zawiera trzy sekcje:

• Serwer proxy — bieżący status, bazowy adres URL oraz przycisk uruchamiania i zatrzymywania nasłuchu
• Token Bearer — opcjonalny przełącznik uwierzytelniania i podgląd tokena
• Dostawcy — wszyscy obsługiwani dostawcy AI w chmurze, z przyciskiem Ustaw klucz API w każdym wierszu

2. Dodaj pierwszy klucz API

1. Wybierz dowolnego dostawcę z listy Dostawcy (na przykład OpenAI (ChatGPT))
2. Kliknij Pobierz klucz API , aby otworzyć konsolę dostawcy w przeglądarce, a następnie utwórz lub skopiuj klucz
3. Kliknij Ustaw klucz API w tym samym wierszu i wklej wartość w oknie dialogowym
4. Kliknij Zapisz. Etykieta statusu zmieni się na Skonfigurowano w kolorze zielonym

3. Podłącz aplikację kliencką

Skieruj dowolnego klienta zgodnego z OpenAI na proxy. Bazowy adres URL to http://localhost:8421/<provider>/v1. Segment z nazwą dostawcy decyduje, która chmura otrzyma żądanie.

# Przykład: SDK OpenAI dla Pythona skierowany 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 dane uwierzytelniające dostawcy dopiero przy przekazywaniu żądania.

Przegląd interfejsu

Panel serwera proxy

Panel tokena Bearer

• Wymagaj uwierzytelniania tokenem Bearer — pole wyboru włączające lub wyłączające uwierzytelnianie. Domyślnie wyłączone, aby ułatwić pracę lokalną.
• Pole tokena — podgląd bieżącego tokena tylko do odczytu. Wyświetlany jako kropki; użyj Kopiuj , aby go pobrać.
• Wygeneruj ponownie — tworzy nowy losowy token. Istniejących klientów trzeba zaktualizować nową wartością.

Panel dostawców

Jeden wiersz na każdego obsługiwanego dostawcę chmurowego. W każdym wierszu widoczne są:

• Nazwa wyświetlana (na przykład Claude (Anthropic))
• Status konfiguracji — zielone Skonfigurowano gdy klucz API jest zapisany, szare Nie skonfigurowano w przeciwnym razie
• Ścieżka URL używana przez klientów, np. /anthropic/v1/chat/completions
• Ustaw klucz API — otwiera okno wprowadzania danych uwierzytelniających
• Pobierz klucz API — otwiera konsolę dostawcy w przeglądarce

Obsługiwani dostawcy

W komplecie znajduje się jedenaście chmurowych usług AI. Większość natywnie korzysta z formatu OpenAI Chat Completions i jest przekazywana bez zmian. Trzy z nich (Anthropic, Gemini, ERNIE) mówią własnymi protokołami; AIProxyServer tłumaczy żądania i odpowiedzi w locie, więc Twój klient widzi wyłącznie struktury OpenAI.

Uwagi dotyczące poszczególnych dostawców

• Azure OpenAI — wklej pełny adres punktu końcowego wdrożenia w pole Endpoint Base URL , na przykład https://my-resource.openai.azure.com/openai/deployments/gpt-4o. Proxy dopisuje /chat/completions?api-version=2024-02-01 automatycznie.
• ERNIE — Baidu Qianfan korzysta z OAuth, więc wymagane są zarówno API Key jak i Secret Key . AIProxyServer pobiera i buforuje tokeny dostępu w tle.
• Gemini — uwierzytelnianie odbywa się przez parametr zapytania w adresie URL; proxy dodaje go za Ciebie. Limity minutowe darmowego planu nadal obowiązują.

Dokumentacja API

Punkty końcowe

Strumieniowanie

Gdy klient wysyła "stream": true, proxy odpowiada zdarzeniami 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 tę postać, dzięki czemu wszyscy klienci mogą używać jednego parsera.

Nagłówek uwierzytelniania

Gdy Wymagaj uwierzytelniania tokenem Bearer jest włączone, wysyłaj token z okna głównego 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 (przekazywanie bezpośrednie)
curl http://localhost:8421/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# Claude w tej samej strukturze 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 token Bearer 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

// Dowolny klient Dart zgodny z OpenAI
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // nieużywane, gdy token Bearer jest wyłączony
);

Wskazówki

• Podczas pracy lokalnej pozostaw token Bearer wyłączony; włącz go w chwili udostępnienia proxy w sieci LAN.
• W kodzie klienta używaj osobnych bazowych adresów URL dla każdego dostawcy, aby zmieniać dostawcę przez podmianę jednej stałej.
• Proxy uruchamia się automatycznie, ale w razie konfliktu portów możesz je tymczasowo zatrzymać z okna głównego.
• Jeśli darmowy plan dostawcy ograniczy liczbę żądań, komunikat błędu zostanie przekazany dosłownie. Żadna logika ponawiania nie jest ukryta przed klientem.
• Punkt końcowy /v1/providers przydaje się do sprawdzenia w czasie działania, którzy dostawcy są skonfigurowani.

Rozwiązywanie problemów

Proxy nie uruchamia się

• Port 8421 może być już zajęty przez inny proces. Zmień port w Ustawieniach i uruchom proxy ponownie.
• Sprawdź dziennik systemowy pod kątem komunikatu błędu wyświetlonego przy starcie.

Żądanie zwraca 401 Unauthorized

• Wymaganie tokena Bearer jest włączone, ale klient nie wysłał pasującego nagłówka Authorization: Bearer ... .
• Klucz API dostawcy może być nieprawidłowy — błąd z serwera źródłowego jest przekazywany, więc sprawdź treść komunikatu.

Żądanie zwraca „API key is not configured”

• Otwórz listę Dostawcy i kliknij Ustaw klucz API przy danym dostawcy.
• W przypadku ERNIE trzeba wypełnić zarówno API Key, jak i Secret Key. W przypadku Azure OpenAI wymagany jest także Endpoint Base URL.

Urządzenie mobilne nie może połączyć się z proxy

• Włącz Zezwalaj na dostęp z sieci LAN w Ustawieniach.
• Użyj adresu IP w sieci LAN widocznego w polu Bazowy adres URL, a nie localhost.
• Upewnij się, że oba urządzenia są w tej samej sieci Wi-Fi, a zapora sieciowa zezwala na połączenia przychodzące na porcie proxy.

Odpowiedzi strumieniowe przychodzą wszystkie naraz

• Upewnij się, że 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ą przechowywane w postaci zaszyfrowanej algorytmem Fernet w pliku ~/Library/Application Support/AIProxyServer/credentials.enc. Klucz szyfrowania w pliku master.key ma uprawnienia 0600.
• Token Bearer, gdy jest włączony, również jest przechowywany wyłącznie w zaszyfrowanym magazynie i nigdy nie trafia do zwykłego pliku ustawień.
• Proxy przekazuje żądania tylko do dostawców, których jawnie skonfigurowano. Nie wykonuje żadnych innych połączeń wychodzących.
• Bez telemetrii, bez analityki, bez raportowania awarii.
• Domyślnie serwer nasłuchuje wyłącznie na 127.0.0.1 . Udostępnienie w sieci LAN wymaga świadomego włączenia.
• Treść rozmów nie jest zapisywana. AIProxyServer przekazuje bajty i natychmiast o nich zapomina.