AIProxyServer - Guida

Per iniziare

1. Avvia l'app

Apri AIProxyServer. Al primo avvio il proxy si attiva automaticamente e resta in ascolto sulla porta 8421 della tua macchina locale. La finestra principale mostra tre sezioni:

• Proxy Server — stato corrente, URL di base e un pulsante per avviare o fermare il listener
• Bearer Token — interruttore di autenticazione opzionale e visualizzazione del token
• Providers — ogni provider AI in cloud supportato, con un pulsante Set API Key per ciascuna riga

2. Aggiungi la tua prima chiave API

1. Scegli un provider qualsiasi dalla lista Providers (ad esempio OpenAI (ChatGPT))
2. Fai clic su Get API key per aprire la console del provider nel browser, poi crea o copia una chiave
3. Fai clic su Set API Key sulla stessa riga e incolla il valore nella finestra di dialogo
4. Fai clic su Save. L'etichetta di stato diventa Configured in verde

3. Connetti un'app client

Punta qualsiasi client compatibile con OpenAI al proxy. L'URL di base è http://localhost:8421/<provider>/v1. Il segmento provider sceglie quale cloud riceverà la richiesta.

# Esempio: OpenAI Python SDK puntato al 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)

Il client non vede mai la chiave reale. AIProxyServer aggiunge le credenziali upstream quando inoltra la richiesta.

Panoramica dell'interfaccia

Pannello Proxy Server

Pannello Bearer Token

• Require Bearer Token authentication — casella di controllo che attiva o disattiva l'autenticazione. Disattivata di default per un uso locale senza complicazioni.
• Token field — visualizzazione in sola lettura del token corrente. Mostrato come punti; usa Copy per ottenerlo.
• Regenerate — emette un nuovo token casuale. I client esistenti devono essere aggiornati con il nuovo valore.

Pannello Providers

Una riga per ciascun provider cloud supportato. Ogni riga mostra:

• Il nome visualizzato (ad esempio Claude (Anthropic))
• Stato di configurazione — verde Configured quando una chiave API è salvata, grigio Not configured altrimenti
• Il percorso URL che i tuoi client utilizzano, es. /anthropic/v1/chat/completions
• Set API Key — apre una finestra di dialogo per inserire le credenziali
• Get API key — apre la console del provider nel tuo browser

Provider supportati

Sono inclusi undici servizi AI in cloud. La maggior parte utilizza nativamente il formato OpenAI Chat Completions ed è proxata così com'è. Tre (Anthropic, Gemini, ERNIE) parlano i propri protocolli; AIProxyServer traduce richieste e risposte al volo in modo che il tuo client veda sempre solo formati OpenAI.

Note specifiche per provider

• Azure OpenAI — incolla l'endpoint completo del deployment nel campo Endpoint Base URL, ad esempio https://my-resource.openai.azure.com/openai/deployments/gpt-4o. Il proxy aggiunge /chat/completions?api-version=2024-02-01 automaticamente.
• ERNIE — Baidu Qianfan utilizza OAuth, quindi sono richiesti sia API Key che Secret Key. AIProxyServer richiede e memorizza nella cache i token di accesso dietro le quinte.
• Gemini — l'autenticazione avviene tramite parametro di query nell'URL; il proxy lo aggiunge per te. Le quote per minuto del piano gratuito restano applicabili.

Riferimento API

Endpoint

Streaming

Quando il client invia "stream": true, il proxy risponde con Server-Sent Events nel formato 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]

Gli stream nativi di Anthropic e Gemini vengono tradotti in questo formato in modo che tutti i client possano usare un singolo parser.

Intestazione di autenticazione

Quando Require Bearer Token authentication è attivo, invia il token mostrato nella finestra principale con ogni richiesta:

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

Impostazioni

Apri la finestra delle impostazioni dall'icona dell'ingranaggio nella barra degli strumenti inferiore.

Esempi di client

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 tramite lo stesso formato 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",  # ignorato quando Bearer Token è disattivato
)
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

// Usando un qualsiasi client Dart compatibile con OpenAI
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // non utilizzato quando Bearer Token è disattivato
);

Consigli

• Lascia il Bearer Token disattivato mentre stai sviluppando in locale; attivalo nel momento in cui abiliti l'accesso LAN.
• Usa Base URL distinti per provider nel codice client in modo da poter cambiare provider modificando una sola costante.
• Il proxy si avvia automaticamente ma puoi fermarlo temporaneamente dalla finestra principale se si verifica un conflitto di porte.
• Se il piano gratuito di un provider ti limita la frequenza, il messaggio di errore upstream viene inoltrato testualmente. Nessuna logica di retry è nascosta al client.
• L'endpoint /v1/providers è utile per scoprire quali provider sono configurati a runtime.

Risoluzione dei problemi

Il proxy non si avvia

• Un altro processo potrebbe già utilizzare la porta 8421. Cambia la porta nelle impostazioni e riavvia il proxy.
• Controlla il log di sistema per il messaggio di errore mostrato all'avvio.

Una richiesta restituisce 401 Unauthorized

• Il requisito Bearer Token è attivo ma il client non ha inviato un'intestazione Authorization: Bearer ... corrispondente.
• La chiave API del provider potrebbe essere non valida — l'errore upstream viene inoltrato, quindi controlla il corpo del messaggio.

Una richiesta restituisce "API key is not configured"

• Apri l'elenco Providers e fai clic su Set API Key per il provider in questione.
• Per ERNIE, devono essere compilati sia API Key che Secret Key. Per Azure OpenAI, è richiesto anche l'Endpoint Base URL.

Il dispositivo mobile non riesce a raggiungere il proxy

• Attiva Allow LAN Access nelle impostazioni.
• Usa l'IP LAN mostrato nel campo Base URL, non localhost.
• Assicurati che entrambi i dispositivi siano sulla stessa rete Wi-Fi e che il tuo firewall consenta connessioni in entrata sulla porta del proxy.

Le risposte in streaming arrivano tutte insieme

• Assicurati che il tuo client invii "stream": true nel corpo JSON.
• Alcune librerie HTTP bufferizzano SSE di default — disabilita il buffering della risposta sul lato client.

Privacy

• Le chiavi API sono memorizzate cifrate con Fernet in ~/Library/Application Support/AIProxyServer/credentials.enc. La chiave di cifratura in master.key ha permessi 0600.
• Il Bearer Token, quando abilitato, viene memorizzato anch'esso solo nella cassaforte cifrata e mai scritto nel file di impostazioni regolare.
• Il proxy inoltra le richieste solo ai provider che hai esplicitamente configurato. Non effettua altre chiamate in uscita.
• Nessuna telemetria, nessuna analitica, nessun crash reporting.
• Il binding di rete predefinito è solo 127.0.0.1. L'esposizione LAN è opt-in.
• I contenuti delle conversazioni non vengono memorizzati. AIProxyServer inoltra i byte e li dimentica immediatamente.