AIProxyServer - Sprievodca

Začíname

1. Spustite aplikáciu

Otvorte AIProxyServer. Pri prvom spustení sa proxy server automaticky spustí a začne počúvať na porte 8421 vášho lokálneho počítača. Hlavné okno obsahuje tri časti:

• Proxy server — aktuálny stav, základná adresa URL a tlačidlo na spustenie alebo zastavenie prijímača
• Nosný token — voliteľný prepínač overovania a zobrazenie tokenu
• Poskytovatelia — všetci podporovaní poskytovatelia cloudovej AI s tlačidlom Nastaviť kľúč API v každom riadku

2. Pridajte prvý kľúč API

1. Vyberte ľubovoľného poskytovateľa zo zoznamu poskytovateľov (napríklad OpenAI (ChatGPT))
2. Kliknite na Získať kľúč API na otvorenie konzoly poskytovateľa v prehliadači a potom vytvorte alebo skopírujte kľúč
3. Kliknite na Nastaviť kľúč API v rovnakom riadku a vložte hodnotu do dialógového okna
4. Kliknite na Uložiť. Označenie stavu sa zmení na Nakonfigurované zelenou farbou

3. Pripojte klientsku aplikáciu

Nasmerujte ľubovoľného klienta kompatibilného s OpenAI na proxy server. Základná adresa URL je http://localhost:8421/<provider>/v1. Segment poskytovateľa určuje, ktorý cloud prijme požiadavku.

# Example: OpenAI Python SDK pointed at the 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í skutočný kľúč. AIProxyServer pri preposielaní požiadavky pripojí prihlasovacie údaje nadradenej služby.

Prehľad rozhrania

Panel proxy servera

Panel nosného tokenu

• Vyžadovať overenie nosným tokenom — začiarkavacie políčko, ktoré zapína alebo vypína overovanie. Predvolene je vypnuté, aby bolo lokálne používanie bezproblémové.
• Pole tokenu — zobrazenie aktuálneho tokenu iba na čítanie. Zobrazuje sa ako bodky; použite Kopírovať na jeho získanie.
• Vygenerovať znova — vytvorí nový náhodný token. Existujúcich klientov je potrebné aktualizovať novou hodnotou.

Panel poskytovateľov

Každému podporovanému cloudovému poskytovateľovi patrí jeden riadok. Každý riadok zobrazuje:

• Zobrazovaný názov (napríklad Claude (Anthropic))
• Stav konfigurácie — zelený Nakonfigurované keď je kľúč API uložený, sivý Nenakonfigurované v opačnom prípade
• Cestu URL, ktorú používajú klienti, napríklad /anthropic/v1/chat/completions
• Nastaviť kľúč API — otvorí dialógové okno na zadanie prihlasovacích údajov
• Získať kľúč API — otvorí konzolu poskytovateľa v prehliadači

Podporovaní poskytovatelia

Súčasťou je jedenásť cloudových služieb AI. Väčšina natívne používa formát OpenAI Chat Completions a požiadavky sa preposielajú bez zmien. Tri služby (Anthropic, Gemini, ERNIE) používajú vlastné protokoly; AIProxyServer priebežne prekladá požiadavky a odpovede, takže klient vždy pracuje iba s formátom OpenAI.

Poznámky ku konkrétnym poskytovateľom

• Azure OpenAI — vložte úplný koncový bod nasadenia do poľa Základná URL koncového bodu napríklad https://my-resource.openai.azure.com/openai/deployments/gpt-4o. Proxy server automaticky pripojí /chat/completions?api-version=2024-02-01 .
• ERNIE — Baidu Qianfan používa OAuth, preto sa vyžaduje Kľúč API aj Tajný kľúč . AIProxyServer na pozadí vyžiada a uloží prístupové tokeny do vyrovnávacej pamäte.
• Gemini — overovanie prebieha parametrom dotazu v adrese URL; proxy server ho pridá za vás. Naďalej platia limity počtu požiadaviek za minútu v bezplatnej úrovni.

Referencia API

Koncové body

Streamovanie

Keď klient odošle "stream": true, proxy server odpovie udalosťami Server-Sent Events vo formáte 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]

Natívne streamy Anthropic a Gemini sa prevedú do tohto formátu, aby mohli všetci klienti používať jediný analyzátor.

Hlavička overenia

Keď je Vyžadovať overenie nosným tokenom zapnuté, odosielajte s každou požiadavkou token z hlavného okna:

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

Nastavenia

Otvorte okno nastavení pomocou ikony ozubeného kolieska na spodnom paneli nástrojov.

Príklady klientov

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 via the same OpenAI shape
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",  # ignored when Bearer Token is off
)
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

// Using any OpenAI-compatible Dart client
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // unused when Bearer Token is off
);

Tipy

• Pri lokálnom vývoji ponechajte nosný token vypnutý; zapnite ho hneď, ako povolíte prístup zo siete LAN.
• V klientskom kóde používajte pre každého poskytovateľa odlišnú základnú adresu URL, aby ste mohli poskytovateľa zmeniť úpravou jedinej konštanty.
• Proxy server sa spúšťa automaticky, ale v prípade konfliktu portov ho môžete dočasne zastaviť v hlavnom okne.
• Ak vás obmedzí limit požiadaviek bezplatnej úrovne poskytovateľa, chybové hlásenie nadradenej služby sa prepošle doslovne. Pred klientom nie je skrytá žiadna logika opakovania.
• Koncový bod /v1/providers je užitočný na zisťovanie poskytovateľov nakonfigurovaných počas behu.

Riešenie problémov

Proxy server sa nespustí

• Port 8421 už môže používať iný proces. Zmeňte port v nastaveniach a reštartujte proxy server.
• V systémovom protokole vyhľadajte chybové hlásenie zobrazené pri spustení.

Požiadavka vráti 401 Unauthorized

• Požiadavka na nosný token je zapnutá, ale klient neodoslal zhodnú hlavičku Authorization: Bearer ... .
• Vlastný kľúč API poskytovateľa môže byť neplatný — chyba nadradenej služby sa prepošle, preto skontrolujte telo správy.

Požiadavka vráti „Kľúč API nie je nakonfigurovaný“

• Otvorte zoznam poskytovateľov a kliknite na Nastaviť kľúč API pri príslušnom poskytovateľovi.
• Pre ERNIE je potrebné vyplniť kľúč API aj tajný kľúč. Pre Azure OpenAI sa vyžaduje aj základná adresa URL koncového bodu.

Mobilné zariadenie sa nemôže pripojiť k proxy serveru

• Zapnite Povoliť prístup zo siete LAN v nastaveniach.
• Použite adresu IP siete LAN zobrazenú v poli základnej adresy URL, nie localhost.
• Uistite sa, že sú obe zariadenia pripojené k rovnakej sieti Wi-Fi a že brána firewall povoľuje prichádzajúce pripojenia na porte proxy servera.

Streamované odpovede prídu všetky naraz

• Uistite sa, že klient odosiela "stream": true v tele JSON.
• Niektoré knižnice HTTP predvolene ukladajú SSE do vyrovnávacej pamäte — vypnite ukladanie odpovede do vyrovnávacej pamäte na strane klienta.

Súkromie

• Kľúče API sa ukladajú šifrované pomocou Fernet v súbore ~/Library/Application Support/AIProxyServer/credentials.enc. Šifrovací kľúč v súbore master.key má povolenia 0600.
• Ak je nosný token povolený, tiež sa ukladá iba v šifrovanom trezore a nikdy sa nezapisuje do bežného súboru nastavení.
• Proxy server preposiela požiadavky iba poskytovateľom, ktorých ste výslovne nakonfigurovali. Nevykonáva žiadne iné odchádzajúce volania.
• Žiadna telemetria, analytika ani hlásenia o zlyhaniach.
• Predvolené sieťové viazanie je iba na 127.0.0.1 . Sprístupnenie v sieti LAN je voliteľné.
• Obsah konverzácií sa neukladá. AIProxyServer prepošle bajty a okamžite ich zabudne.