AIProxyServer - Průvodce

Začínáme

1. Spusťte aplikaci

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

• Proxy Server — aktuální stav, základní URL a tlačítko pro spuštění nebo zastavení posluchače
• Bearer Token — volitelný přepínač autentizace a zobrazení tokenu
• Providers — všichni podporovaní cloudoví AI poskytovatelé, s tlačítkem Set API Key v každém řádku

2. Přidejte svůj první API klíč

1. Vyberte libovolného poskytovatele ze seznamu Providers (například OpenAI (ChatGPT))
2. Klikněte na Get API key pro otevření konzole poskytovatele v prohlížeči, poté klíč vytvořte nebo zkopírujte
3. Klikněte na Set API Key ve stejném řádku a vložte hodnotu do dialogu
4. Klikněte na Save. Štítek stavu se přepne na zelené Configured

3. Připojte klientskou aplikaci

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

# 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 nevidí skutečný klíč. AIProxyServer připojí přihlašovací údaje upstream při přeposlání požadavku.

Přehled rozhraní

Panel Proxy Server

Panel Bearer Token

• Require Bearer Token authentication — zaškrtávací políčko zapínající nebo vypínající autentizaci. Ve výchozím nastavení vypnuto pro pohodlné lokální použití.
• Pole tokenu — zobrazení aktuálního tokenu pouze pro čtení. Zobrazeno jako tečky; pomocí Copy jej získáte.
• Regenerate — vydá nový náhodný token. Existující klienti musí být aktualizováni novou hodnotou.

Panel Providers

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

• Zobrazované jméno (například Claude (Anthropic))
• Stav konfigurace — zelený Configured, když je API klíč uložen, jinak šedý Not configured
• URL cesta, kterou vaši klienti používají, např. /anthropic/v1/chat/completions
• Set API Key — otevře dialog pro zadání přihlašovacích údajů
• Get API key — otevře konzoli poskytovatele v prohlížeči

Podporovaní Providers

Je zahrnuto jedenáct cloudových AI služeb. Většina nativně používá formát OpenAI Chat Completions a je proxována tak, jak je. Tři (Anthropic, Gemini, ERNIE) mluví vlastními protokoly; AIProxyServer překládá požadavky a odpovědi za běhu, takže váš klient vidí jen tvary OpenAI.

Poznámky specifické pro poskytovatele

• Azure OpenAI — vložte úplný 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, takže jsou vyžadovány jak API Key, tak Secret Key. AIProxyServer si vyžádá a v zákulisí ukládá přístupové tokeny.
• Gemini — autentizace probíhá pomocí URL parametru dotazu; proxy jej za vás přidá. Minutové kvóty bezplatné úrovně stále platí.

Referenční dokumentace API

Koncové body

Streaming

Když klient pošle "stream": true, proxy odpovídá 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řeloženy do tohoto tvaru, takže všichni klienti mohou používat jediný parser.

Autentizační hlavička

Když je Require Bearer Token authentication zapnuto, posílejte s každým požadavkem token z hlavního okna:

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

Nastavení

Otevřete okno Nastavení z ikony ozubeného kola na spodním panelu nástrojů.

Příklady klientů

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 přes stejný tvar 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",  # ignorováno, 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 Dart klienta kompatibilního s OpenAI
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // nepoužito, když je Bearer Token vypnut
);

Tipy

• Bearer Token nechte vypnutý, dokud vyvíjíte lokálně; zapněte jej ve chvíli, kdy povolíte přístup z LAN.
• Používejte ve svém klientském kódu odlišné Base URL pro jednotlivé poskytovatele, abyste mohli mezi poskytovateli přepínat změnou jedné konstanty.
• Proxy se spouští automaticky, ale můžete jej dočasně zastavit z hlavního okna, pokud dojde ke konfliktu portů.
• Pokud vás bezplatná úroveň poskytovatele omezí rychlostí, chybová zpráva upstream je předána doslovně. Klientovi není skryta žádná logika opakování.
• Koncový bod /v1/providers je užitečný pro zjištění, kteří poskytovatelé jsou nakonfigurováni za běhu.

Řešení problémů

Proxy se nespustí

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

Požadavek vrací 401 Unauthorized

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

Požadavek vrací "API key is not configured"

• Otevřete seznam Providers a klikněte na Set API Key pro daného poskytovatele.
• Pro ERNIE musí být vyplněny jak API Key, tak Secret Key. Pro Azure OpenAI je také vyžadována Endpoint Base URL.

Mobilní zařízení nedosáhne na proxy

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

Streamované odpovědi přicházejí najednou

• Ujistěte se, že váš klient posílá "stream": true v JSON těle.
• Některé HTTP knihovny ve výchozím nastavení bufferují SSE — vypněte buffering odpovědí na straně klienta.

Soukromí

• API klíče jsou šifrovány pomocí Fernet v ~/Library/Application Support/AIProxyServer/credentials.enc. Šifrovací klíč v master.key má oprávnění 0600.
• Bearer Token, je-li povolen, je rovněž uložen pouze v šifrovaném trezoru a nikdy se nezapisuje do běžného souboru nastavení.
• Proxy předává požadavky pouze poskytovatelům, které jste explicitně nakonfigurovali. Neuskutečňuje žádná další odchozí volání.
• Žádná telemetrie, žádná analytika, žádné hlášení pádů.
• Výchozí síťová vazba je pouze 127.0.0.1. Vystavení do LAN je opt-in.
• Obsah konverzací není ukládán. AIProxyServer předává bajty a okamžitě na ně zapomíná.