AIProxyServer - Ghid

Primii pași

1. Lansează aplicația

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

• Proxy Server — starea curentă, URL de bază și un buton pentru pornirea sau oprirea listener-ului
• Bearer Token — comutator opțional de autentificare și afișarea tokenului
• Providers — fiecare furnizor AI cloud suportat, cu un buton Set API Key pe fiecare rând

2. Adaugă prima ta cheie API

1. Alege orice furnizor din lista Providers (de exemplu OpenAI (ChatGPT))
2. Apasă Get API key pentru a deschide consola furnizorului în browser, apoi creează sau copiază o cheie
3. Apasă Set API Key pe același rând și lipește valoarea în dialog
4. Apasă Save. Eticheta de stare se schimbă în Configured verde

3. Conectează o aplicație client

Direcționează orice client compatibil cu OpenAI către proxy. Base URL este http://localhost:8421/<provider>/v1. Segmentul provider alege care cloud primește cererea.

# Exemplu: OpenAI Python SDK direcționat către 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ă credențialele upstream când redirecționează cererea.

Prezentare generală a interfeței

Panoul Proxy Server

Panoul Bearer Token

• Require Bearer Token authentication — bifă care activează sau dezactivează autentificarea. Dezactivată implicit pentru utilizare locală fără bătăi de cap.
• Câmpul de token — afișaj doar pentru citire al tokenului curent. Afișat ca puncte; folosește Copy pentru a-l prelua.
• Regenerate — emite un token aleator nou. Clienții existenți trebuie actualizați cu noua valoare.

Panoul Providers

Un rând pe fiecare furnizor cloud suportat. Fiecare rând afișează:

• Numele afișat (de exemplu Claude (Anthropic))
• Statusul de configurare — Configured verde când o cheie API este salvată, Not configured gri în caz contrar
• Calea URL pe care o folosesc clienții tăi, de exemplu /anthropic/v1/chat/completions
• Set API Key — deschide un dialog pentru introducerea credențialelor
• Get API key — deschide consola furnizorului în browser

Furnizori suportați

Sunt incluse unsprezece servicii AI cloud. Majoritatea utilizează nativ formatul OpenAI Chat Completions și sunt proxy-ate ca atare. Trei (Anthropic, Gemini, ERNIE) vorbesc propriile lor protocoale; AIProxyServer traduce cererile și răspunsurile din mers, astfel încât clientul tău să vadă întotdeauna doar formate OpenAI.

Note specifice pentru furnizori

• Azure OpenAI — lipește endpoint-ul de deployment complet în câmpul Endpoint Base URL, 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, deci atât API Key cât și Secret Key sunt necesare. AIProxyServer solicită și păstrează în cache tokenurile de acces în culise.
• Gemini — autentificarea se face prin parametrul de interogare URL; proxy-ul îl adaugă pentru tine. Cotele pe minut ale nivelului gratuit se aplică totuși.

Referință API

Endpoint-uri

Streaming

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 traduse în această formă astfel încât toți clienții să poată folosi un singur parser.

Header de autentificare

Când Require Bearer Token authentication este activat, trimite tokenul din fereastra principală cu fiecare cerere:

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

Setări

Deschide fereastra Settings de la pictograma roată din bara de instrumente de jos.

Exemple de 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 prin aceeași formă 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",  # 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

• Lasă Bearer Token dezactivat în timp ce dezvolți local; activează-l în momentul în care activezi accesul LAN.
• Folosește Base URL distincte pentru fiecare furnizor în codul tău client, astfel încât să poți schimba furnizorii modificând o singură constantă.
• Proxy-ul pornește automat, dar îl poți opri temporar din fereastra principală dacă apare un conflict de port.
• Dacă nivelul gratuit al unui furnizor îți limitează rata, mesajul de eroare upstream este redirecționat exact. Nicio logică de reîncercare nu este ascunsă de client.
• Endpoint-ul /v1/providers este util pentru a descoperi ce furnizori sunt configurați la runtime.

Depanare

Proxy-ul nu pornește

• Un alt proces ar putea folosi deja portul 8421. Schimbă portul în Settings și repornește proxy-ul.
• Verifică jurnalul de sistem pentru mesajul de eroare afișat la momentul pornirii.

O cerere returnează 401 Unauthorized

• Cerința Bearer Token este activată, dar clientul nu a trimis un header Authorization: Bearer ... corespunzător.
• Cheia API a furnizorului poate fi invalidă — eroarea upstream este redirecționată, deci verifică corpul mesajului.

O cerere returnează "API key is not configured"

• Deschide lista Providers și apasă Set API Key pentru furnizorul în cauză.
• Pentru ERNIE, atât API Key cât și Secret Key trebuie completate. Pentru Azure OpenAI, este necesar și Endpoint Base URL.

Dispozitivul mobil nu poate ajunge la proxy

• Activează Allow LAN Access în Settings.
• Folosește IP-ul LAN afișat în câmpul Base URL, nu localhost.
• Asigură-te că ambele dispozitive sunt în aceeași rețea Wi-Fi și că firewall-ul tău permite conexiunile de intrare pe portul proxy.

Răspunsurile streaming sosesc toate odată

• Asigură-te că clientul tău trimite "stream": true în corpul JSON.
• Unele biblioteci HTTP fac buffering la SSE implicit — dezactivează buffering-ul răspunsului din partea clientului.

Confidențialitate

• Cheile API sunt stocate criptate cu Fernet în ~/Library/Application Support/AIProxyServer/credentials.enc. Cheia de criptare din master.key are permisiuni 0600.
• Bearer Token, când este activat, este de asemenea stocat doar în seiful criptat și nu este niciodată scris în fișierul de setări obișnuit.
• Proxy-ul redirecționează doar cererile către furnizorii pe care i-ai configurat explicit. Nu face alte apeluri de ieșire.
• Fără telemetrie, fără analytics, fără raportare de erori.
• Legarea implicită a rețelei este doar 127.0.0.1. Expunerea LAN este opt-in.
• Conținutul conversațiilor nu este stocat. AIProxyServer redirecționează octeții și îi uită imediat.