AIProxyServer - Ghid

Primii pași

1. Lansați aplicația

Deschideți AIProxyServer. La prima lansare, proxy-ul pornește automat și ascultă pe portul 8421 al dispozitivului local. Fereastra principală afișează trei secțiuni:

• Server proxy — starea curentă, adresa URL de bază și un buton pentru pornirea sau oprirea serviciului de ascultare
• Token Bearer — comutator opțional de autentificare și afișarea tokenului
• Furnizori — fiecare furnizor cloud AI acceptat, cu un Setați cheia API buton pe fiecare rând

2. Adăugați prima cheie API

1. Alegeți orice furnizor din lista Furnizori (de exemplu OpenAI (ChatGPT))
2. Faceți clic pe Obțineți cheia API pentru a deschide consola furnizorului în browser, apoi creați sau copiați o cheie
3. Faceți clic pe Setați cheia API pe același rând și lipiți valoarea în caseta de dialog
4. Faceți clic pe Salvați. Eticheta de stare devine Configurat și apare cu verde

3. Conectați o aplicație client

Direcționați orice client compatibil cu OpenAI către proxy. Adresa URL de bază este http://localhost:8421/<provider>/v1. Segmentul furnizorului stabilește serviciul cloud care primește solicitarea.

# 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)

Clientul nu vede niciodată cheia reală. AIProxyServer atașează datele de autentificare pentru serviciul din amonte atunci când redirecționează solicitarea.

Prezentarea interfeței

Panoul serverului proxy

Panoul Token Bearer

• Solicitați autentificarea cu Token Bearer — casetă de selectare care activează sau dezactivează autentificarea. Este dezactivată implicit pentru o utilizare locală fără complicații.
• Câmpul tokenului — afișare doar în citire a tokenului curent. Este afișat sub formă de puncte; folosiți Copiați pentru a-l prelua.
• Regenerați — generați un nou token aleatoriu. Clienții existenți trebuie actualizați cu noua valoare.

Panoul Furnizori

Există câte un rând pentru fiecare furnizor cloud acceptat. Fiecare rând afișează:

• Numele afișat (de exemplu Claude (Anthropic))
• Starea configurării — verde Configurat când este salvată o cheie API, gri Neconfigurat în caz contrar
• Calea URL utilizată de clienți, de exemplu /anthropic/v1/chat/completions
• Setați cheia API — deschide o casetă de dialog pentru introducerea datelor de autentificare
• Obțineți cheia API — deschide consola furnizorului în browser

Furnizori acceptați

Sunt incluse unsprezece servicii cloud AI. Majoritatea folosesc nativ formatul OpenAI Chat Completions și sunt transmise ca atare prin proxy. Trei dintre ele (Anthropic, Gemini, ERNIE) folosesc protocoale proprii; AIProxyServer traduce dinamic solicitările și răspunsurile, astfel încât clientul vede întotdeauna structuri OpenAI.

Note specifice furnizorilor

• Azure OpenAI — lipiți punctul final complet al implementării în câmpul Adresă URL de bază a punctului final , de exemplu https://my-resource.openai.azure.com/openai/deployments/gpt-4o. Proxy-ul adaugă automat /chat/completions?api-version=2024-02-01 .
• ERNIE — Baidu Qianfan folosește OAuth, așadar sunt necesare atât API Key , cât și Secret Key . AIProxyServer solicită și păstrează în cache tokenurile de acces în fundal.
• Gemini — autentificarea se realizează printr-un parametru de interogare URL; proxy-ul îl adaugă automat. Se aplică în continuare limitele pe minut ale nivelului gratuit.

Referință API

Puncte finale

Transmitere în flux

Când clientul trimite "stream": true, proxy-ul răspunde cu Server-Sent Events în formatul 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]

Fluxurile native Anthropic și Gemini sunt convertite în această structură, astfel încât toți clienții să poată folosi un singur parser.

Antet de autentificare

Când Solicitați autentificarea cu Token Bearer este activat, trimiteți tokenul din fereastra principală la fiecare solicitare:

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

Setări

Deschideți fereastra Setări folosind pictograma roată dințată din bara de instrumente inferioară.

Exemple pentru clienți

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
);

Sfaturi

• Lăsați Token Bearer dezactivat cât timp dezvoltați local; activați-l imediat ce permiteți accesul LAN.
• Folosiți adrese URL de bază distincte pentru fiecare furnizor în codul client, pentru a putea schimba furnizorul modificând o singură constantă.
• Proxy-ul pornește automat, dar îl puteți opri temporar din fereastra principală dacă apare un conflict de porturi.
• Dacă nivelul gratuit al unui furnizor vă limitează rata solicitărilor, mesajul de eroare din amonte este redirecționat întocmai. Nicio logică de reîncercare nu este ascunsă clientului.
• Punctul final /v1/providers este util pentru a afla ce furnizori sunt configurați în timpul rulării.

Depanare

Proxy-ul nu pornește

• Este posibil ca un alt proces să folosească deja portul 8421. Schimbați portul în Setări și reporniți proxy-ul.
• Consultați jurnalul de sistem pentru mesajul de eroare afișat la pornire.

O solicitare returnează 401 Unauthorized

• Cerința Token Bearer este activată, dar clientul nu a trimis un antet corespunzător Authorization: Bearer ... .
• Cheia API a furnizorului poate fi nevalidă — eroarea din amonte este redirecționată, așadar verificați corpul mesajului.

O solicitare returnează „Cheia API nu este configurată”

• Deschideți lista Furnizori și faceți clic pe Setați cheia API pentru furnizorul respectiv.
• Pentru ERNIE, trebuie completate atât API Key, cât și Secret Key. Pentru Azure OpenAI, este necesară și Endpoint Base URL.

Dispozitivul mobil nu poate accesa proxy-ul

• Activați Permiteți accesul LAN în Setări.
• Folosiți adresa IP LAN afișată în câmpul Base URL, nu localhost.
• Asigurați-vă că ambele dispozitive sunt conectate la aceeași rețea Wi-Fi și că firewallul permite conexiunile primite pe portul proxy-ului.

Răspunsurile în flux sosesc toate odată

• Asigurați-vă că aplicația client trimite "stream": true în corpul JSON.
• Unele biblioteci HTTP memorează implicit SSE în tampon — dezactivați stocarea răspunsului în tampon în aplicația client.

Confidențialitate

• Cheile API sunt stocate criptat cu Fernet în ~/Library/Application Support/AIProxyServer/credentials.enc. Cheia de criptare din master.key are permisiuni 0600.
• Tokenul Bearer, când este activat, este de asemenea păstrat numai în seiful criptat și nu este scris niciodată în fișierul obișnuit de setări.
• Proxy-ul redirecționează solicitări numai către furnizorii pe care i-ați configurat explicit. Nu efectuează alte apeluri externe.
• Fără telemetrie, analiză sau raportare a blocărilor.
• Asocierea implicită la rețea este 127.0.0.1 doar. Expunerea în LAN este opțională.
• Conținutul conversațiilor nu este stocat. AIProxyServer redirecționează octeții și îi uită imediat.