AIProxyServer - Guia

Primers passos

1. Inicieu l’aplicació

Obriu AIProxyServer. En iniciar-lo per primera vegada, el servidor intermediari s’engega automàticament i escolta al port 8421 de l’ordinador local. La finestra principal mostra tres seccions:

• Servidor intermediari — estat actual, URL base i un botó per iniciar o aturar el servei d’escolta
• Bearer Token — commutador d’autenticació opcional i visualització del token
• Proveïdors — tots els proveïdors d’IA al núvol compatibles, amb un botó Set API Key a cada fila

2. Afegiu la primera clau d’API

1. Trieu qualsevol proveïdor de la llista Proveïdors (per exemple, OpenAI (ChatGPT))
2. Feu clic a Get API key per obrir la consola del proveïdor al navegador i, a continuació, creeu o copieu una clau
3. Feu clic a Set API Key a la mateixa fila i enganxeu el valor al quadre de diàleg
4. Feu clic a Desa. L’etiqueta d’estat canvia a Configurat en verd

3. Connecteu una aplicació client

Adreceu qualsevol client compatible amb OpenAI al servidor intermediari. La URL base és http://localhost:8421/<provider>/v1. El segment del proveïdor determina quin servei al núvol rep la sol·licitud.

# Exemple: SDK d’OpenAI per a Python adreçat al servidor intermediari
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)

El client no veu mai la clau real. AIProxyServer afegeix les credencials del servei de destinació quan reenvia la sol·licitud.

Descripció general de la interfície

Tauler del servidor intermediari

Tauler de Bearer Token

• Requereix autenticació amb Bearer Token — casella que activa o desactiva l’autenticació. Està desactivada per defecte per facilitar l’ús local.
• Camp del token — visualització de només lectura del token actual. Es mostra amb punts; utilitzeu Copia per obtenir-lo.
• Regenera — genera un token aleatori nou. Cal actualitzar els clients existents amb el valor nou.

Tauler de proveïdors

Hi ha una fila per cada proveïdor al núvol compatible. Cada fila mostra:

• El nom visible (per exemple, Claude (Anthropic))
• Estat de configuració — verd Configurat quan hi ha una clau d’API desada; gris i Sense configurar en cas contrari
• La ruta de l’URL que utilitzen els clients, p. ex. /anthropic/v1/chat/completions
• Set API Key — obre un quadre de diàleg per introduir les credencials
• Get API key — obre la consola del proveïdor al navegador

Proveïdors compatibles

S’hi inclouen onze serveis d’IA al núvol. La majoria utilitzen de manera nativa el format Chat Completions d’OpenAI i es transmeten sense canvis. Tres (Anthropic, Gemini i ERNIE) utilitzen protocols propis; AIProxyServer tradueix les sol·licituds i les respostes al moment perquè el client només vegi formats d’OpenAI.

Notes específiques de cada proveïdor

• Azure OpenAI — enganxeu l’endpoint complet del desplegament al camp Endpoint Base URL , per exemple, https://my-resource.openai.azure.com/openai/deployments/gpt-4o. El servidor intermediari afegeix /chat/completions?api-version=2024-02-01 automàticament.
• ERNIE — Baidu Qianfan utilitza OAuth, de manera que calen tant API Key com Secret Key . AIProxyServer sol·licita i desa a la memòria cau els tokens d’accés en segon pla.
• Gemini — l’autenticació es fa mitjançant un paràmetre de consulta de l’URL; el servidor intermediari l’afegeix automàticament. Es continuen aplicant les quotes per minut del nivell gratuït.

Referència de l’API

Endpoints

Transmissió en temps real

Quan el client envia "stream": true, el servidor intermediari respon amb Server-Sent Events en el format d’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]

Els fluxos natius d’Anthropic i Gemini es tradueixen a aquest format perquè tots els clients puguin utilitzar un únic analitzador.

Capçalera d’autenticació

Quan Requereix autenticació amb Bearer Token està activat, envieu el token que es mostra a la finestra principal amb cada sol·licitud:

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

Configuració

Obriu la finestra Configuració mitjançant la icona d’engranatge de la barra d’eines inferior.

Exemples de clients

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 utilitzant el mateix format d’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
  }'

SDK d’OpenAI per a Python

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/gemini/v1",
    api_key="placeholder",  # s’ignora quan Bearer Token està desactivat
)
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

// Amb qualsevol client Dart compatible amb OpenAI
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // no s’utilitza quan Bearer Token està desactivat
);

Consells

• Deixeu el Bearer Token desactivat mentre desenvolupeu en local; activeu-lo tan bon punt habiliteu l’accés LAN.
• Utilitzeu URL base diferents per a cada proveïdor al codi del client, de manera que pugueu canviar de proveïdor modificant una sola constant.
• El servidor intermediari s’inicia automàticament, però podeu aturar-lo temporalment des de la finestra principal si hi ha un conflicte de ports.
• Si el nivell gratuït d’un proveïdor limita la freqüència de les sol·licituds, el missatge d’error del servei de destinació es reenvia literalment. No s’oculta al client cap lògica de reintent.
• L’endpoint /v1/providers és útil per descobrir quins proveïdors estan configurats durant l’execució.

Resolució de problemes

El servidor intermediari no s’inicia

• És possible que un altre procés ja utilitzi el port 8421. Canvieu el port a Configuració i reinicieu el servidor intermediari.
• Consulteu el registre del sistema per veure el missatge d’error que es mostra en iniciar-lo.

Una sol·licitud retorna 401 Unauthorized

• El requisit de Bearer Token està activat, però el client no ha enviat una capçalera Authorization: Bearer ... coincident.
• És possible que la clau d’API del proveïdor no sigui vàlida. L’error del servei de destinació es reenvia, així que consulteu el cos del missatge.

Una sol·licitud retorna "API key is not configured"

• Obriu la llista Proveïdors i feu clic a Set API Key per al proveïdor en qüestió.
• Per a ERNIE, cal emplenar tant API Key com Secret Key. Per a Azure OpenAI, també cal Endpoint Base URL.

El dispositiu mòbil no pot accedir al servidor intermediari

• Activeu Allow LAN Access a Configuració.
• Utilitzeu l’adreça IP LAN que es mostra al camp URL base, no pas localhost.
• Assegureu-vos que tots dos dispositius siguin a la mateixa xarxa Wi-Fi i que el tallafoc permeti connexions entrants al port del servidor intermediari.

Les respostes en temps real arriben totes alhora

• Assegureu-vos que el client enviï "stream": true al cos JSON.
• Algunes biblioteques HTTP emmagatzemen SSE a la memòria intermèdia per defecte; desactiveu la memòria intermèdia de resposta al client.

Privadesa

• Les claus d’API es desen xifrades amb Fernet a ~/Library/Application Support/AIProxyServer/credentials.enc. La clau de xifratge de master.key té permisos 0600.
• Quan està activat, el Bearer Token també es desa exclusivament al magatzem xifrat i mai no s’escriu al fitxer de configuració habitual.
• El servidor intermediari només reenvia sol·licituds als proveïdors que heu configurat explícitament. No fa cap altra connexió sortint.
• Sense telemetria, analítiques ni informes d’errors.
• L’enllaç de xarxa predeterminat és només 127.0.0.1 . L’exposició a la xarxa LAN és opcional.
• El contingut de les converses no s’emmagatzema. AIProxyServer reenvia els bytes i els descarta immediatament.