AIProxyServer - Průvodce

Začínáme

1. Spusťte aplikaci

Otevřete AIProxyServer. Při prvním spuštění se proxy automaticky spustí a naslouchá na portu 8421 vašeho místního počítače. Hlavní okno zobrazuje tři části:

• Proxy server — aktuální stav, základní URL a tlačítko pro spuštění nebo zastavení naslouchání
• Bearer Token — volitelné přepnutí ověřování a zobrazení tokenu
• Poskytovatelé — každý podporovaný cloudový poskytovatel s tlačítkem Nastavit klíč API v každém řádku

2. Přidejte první klíč API

1. Vyberte libovolného poskytovatele ze seznamu Providers (například OpenAI (ChatGPT))
2. Klikněte na Získat klíč API otevřete konzoli poskytovatele v prohlížeči a pak vytvořte nebo zkopírujte klíč
3. Klikněte na Nastavit klíč API ve stejném řádku a vložte hodnotu do dialogového okna
4. Klikněte na Uložit. Štítek stavu se změní na Nakonfigurováno zeleně

3. Připojte klientskou aplikaci

Nasměrujte libovolného klienta kompatibilního s OpenAI na proxy. Base URL je http://localhost:8421/<provider>/v1. Segment poskytovatele určuje, který cloud požadavek přijme.

# Příklad: OpenAI Python SDK nasměrované 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 nikdy neuvidí skutečný klíč. AIProxyServer při přeposílání požadavku připojí přihlašovací údaje pro upstream.

Přehled rozhraní

Panel Proxy Server

Panel Bearer Token

• Vyžadovat ověřování pomocí Bearer Tokenu — zaškrtávací políčko, které zapíná nebo vypíná ověřování. Ve výchozím nastavení vypnuto pro snadné místní použití.
• Pole tokenu — zobrazení aktuálního tokenu jen pro čtení. Zobrazuje se jako tečky; použijte Kopírovat pro jeho získání.
• Znovu vygenerovat — vydá nový náhodný token. Stávající klienty je nutné aktualizovat novou hodnotou.

Panel Providers

Jeden řádek pro každého podporovaného cloudového poskytovatele. Každý řádek zobrazuje:

• Zobrazovaný název (například Claude (Anthropic))
• Stav konfigurace — zelený Nakonfigurováno když je klíč API uložen, šedý Nenakonfigurováno jinak
• Cesta URL, kterou vaši klienti používají, např. /anthropic/v1/chat/completions
• Nastavit klíč API — otevře dialog pro zadání přihlašovacích údajů
• Získat klíč API — otevře konzoli poskytovatele v prohlížeči

Podporovaní poskytovatelé

Je součástí jedenáct cloudových služeb AI. Většina nativně používá formát OpenAI Chat Completions a je proxyována beze změny. Tři (Anthropic, Gemini, ERNIE) používají vlastní protokoly; AIProxyServer převádí požadavky a odpovědi za běhu, takže klient vždy vidí jen formát OpenAI.

Poznámky pro jednotlivé poskytovatele

• Azure OpenAI — vložte celý koncový bod nasazení do pole Endpoint Base URL , například https://my-resource.openai.azure.com/openai/deployments/gpt-4o. Proxy automaticky připojí /chat/completions?api-version=2024-02-01 .
• ERNIE — Baidu Qianfan používá OAuth, proto jsou vyžadovány oba klíče API Key a Secret Key . AIProxyServer na pozadí vyžádá tokeny přístupu a uloží je do mezipaměti.
• Gemini — ověřování probíhá pomocí parametru dotazu URL; proxy jej přidá za vás. Nadále platí minutové kvóty bezplatné úrovně.

Referenční dokumentace API

Koncové body

Streamování

Když klient odešle "stream": true, proxy odpoví událostmi Server-Sent Events ve formátu 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]

Nativní streamy Anthropic a Gemini jsou převedeny do tohoto tvaru, takže všichni klienti mohou používat jediný parser.

Hlavička ověřování

Když je Vyžadovat ověřování pomocí Bearer Tokenu zapnuto, odešlete s každým požadavkem token z hlavního okna:

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

Nastavení

Otevřete okno Settings pomocí ikony ozubeného kola na spodní liště nástrojů.

Příklady klientů

cURL

# OpenAI (přímé předání)
curl http://localhost:8421/openai/v1/chat/completions \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# Claude ve stejném formátu 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",  # ignoruje se, když je Bearer Token vypnutý
)
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

// Použití libovolného klienta Dart kompatibilního s OpenAI
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // nepoužívá se, když je Bearer Token vypnutý
);

Tipy

• Při místním vývoji nechte Bearer Token vypnutý; zapněte jej hned, jak povolíte přístup přes LAN.
• V kódu klienta používejte pro každého poskytovatele odlišné Base URL, abyste mohli poskytovatele změnit úpravou jedné konstanty.
• Proxy se spouští automaticky, ale pokud dojde ke konfliktu portů, můžete ji dočasně zastavit z hlavního okna.
• Pokud vás bezplatná úroveň poskytovatele omezuje rychlostí, upstreamová chybová zpráva se přepošle doslovně. Před klientem není skryta žádná logika opakování.
• Koncový bod /v1/providers je užitečný k zjištění, kteří poskytovatelé jsou za běhu nakonfigurováni.

Řešení potíží

Proxy se nespustí

• Port 8421 možná již používá jiný proces. Změňte port v Settings a restartujte proxy.
• Zkontrolujte systémový protokol, kde najdete chybovou zprávu zobrazenou při spuštění.

Požadavek vrátí 401 Unauthorized

• Požadavek na Bearer Token je zapnutý, ale klient neodeslal odpovídající Authorization: Bearer ... hlavičku.
• Vlastní klíč API poskytovatele může být neplatný — upstreamová chyba je přeposlána, proto zkontrolujte tělo zprávy.

Požadavek vrátí „API key is not configured“

• Otevřete seznam Providers a klikněte na Nastavit klíč API pro příslušného poskytovatele.
• Pro ERNIE musí být vyplněny API Key i Secret Key. Pro Azure OpenAI je také vyžadováno Endpoint Base URL.

Mobilní zařízení nemůže dosáhnout proxy

• Zapněte Povolit přístup k LAN v Settings.
• Použijte IP adresu LAN zobrazenou v poli Base URL, nikoli localhost.
• Ujistěte se, že jsou obě zařízení ve stejné síti Wi-Fi a firewall povoluje příchozí připojení na port proxy.

Odpovědi streamování přicházejí všechny najednou

• Ujistěte se, že klient odesílá "stream": true v těle JSON.
• Některé knihovny HTTP ve výchozím nastavení ukládají SSE do vyrovnávací paměti — vypněte ukládání odpovědí do vyrovnávací paměti na straně klienta.

Soukromí

• Klíče API jsou uloženy zašifrovaně pomocí Fernet v ~/Library/Application Support/AIProxyServer/credentials.enc. Šifrovací klíč v master.key má oprávnění 0600.
• Bearer Token je po zapnutí také uložen pouze v zašifrovaném trezoru a nikdy není zapsán do běžného souboru nastavení.
• Proxy přeposílá požadavky pouze poskytovatelům, které jste výslovně nakonfigurovali. Neprovádí žádná jiná odchozí volání.
• Žádná telemetrie, žádná analytika, žádné hlášení pádů.
• Výchozí síťové vazby jsou 127.0.0.1 pouze. Vystavení do LAN je volitelné.
• Obsah konverzace se neukládá. AIProxyServer přepošle bajty a okamžitě na ně zapomene.