AIProxyServer - Guía

Primeros pasos

1. Inicie la aplicación

Abra AIProxyServer. En el primer inicio, el proxy arranca automáticamente y escucha en el puerto 8421 de su equipo local. La ventana principal muestra tres secciones:

• Servidor proxy — estado actual, URL base y un botón para iniciar o detener el escucha
• Bearer Token — interruptor de autenticación opcional y visualización del token
• Proveedores — todos los proveedores de IA en la nube compatibles, con un botón Set API Key en cada fila

2. Añada su primera clave de API

1. Elija cualquier proveedor de la lista Proveedores (por ejemplo, OpenAI (ChatGPT))
2. Haga clic en Get API key para abrir la consola del proveedor en su navegador y, a continuación, cree o copie una clave
3. Haga clic en Set API Key en la misma fila y pegue el valor en el cuadro de diálogo
4. Haga clic en Guardar. La etiqueta de estado cambia a Configurado en verde

3. Conecte una aplicación cliente

Apunte cualquier cliente compatible con OpenAI al proxy. La URL base es http://localhost:8421/<provider>/v1. El segmento del proveedor determina qué nube recibe la solicitud.

# Ejemplo: SDK de OpenAI para Python apuntando 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)

El cliente nunca ve la clave real. AIProxyServer añade las credenciales del servicio de destino al reenviar la solicitud.

Descripción de la interfaz

Panel del servidor proxy

Panel de Bearer Token

• Requerir autenticación con Bearer Token — casilla que activa o desactiva la autenticación. Desactivada de forma predeterminada para un uso local sin complicaciones.
• Campo del token — visualización de solo lectura del token actual. Se muestra con puntos; use Copiar para obtenerlo.
• Regenerar — genera un token aleatorio nuevo. Los clientes existentes deben actualizarse con el nuevo valor.

Panel de proveedores

Una fila por cada proveedor en la nube compatible. Cada fila muestra:

• El nombre visible (por ejemplo, Claude (Anthropic))
• Estado de configuración — verde Configurado cuando hay una clave de API guardada, gris Sin configurar en caso contrario
• La ruta de URL que usan sus clientes, p. ej. /anthropic/v1/chat/completions
• Set API Key — abre un cuadro de diálogo para introducir las credenciales
• Get API key — abre la consola del proveedor en su navegador

Proveedores compatibles

Se incluyen once servicios de IA en la nube. La mayoría utiliza de forma nativa el formato Chat Completions de OpenAI y se retransmite tal cual. Tres de ellos (Anthropic, Gemini, ERNIE) hablan sus propios protocolos; AIProxyServer traduce solicitudes y respuestas sobre la marcha para que su cliente solo vea formatos de OpenAI.

Notas específicas de cada proveedor

• Azure OpenAI — pegue el endpoint completo de la implementación en el campo Endpoint Base URL , por ejemplo https://my-resource.openai.azure.com/openai/deployments/gpt-4o. El proxy añade /chat/completions?api-version=2024-02-01 automáticamente.
• ERNIE — Baidu Qianfan usa OAuth, por lo que se requieren tanto API Key como Secret Key . AIProxyServer solicita y almacena en caché los tokens de acceso en segundo plano.
• Gemini — la autenticación se realiza mediante un parámetro de consulta en la URL; el proxy lo añade por usted. Las cuotas por minuto del nivel gratuito siguen aplicándose.

Referencia de la API

Endpoints

Streaming

Cuando el cliente envía "stream": true, el proxy responde con Server-Sent Events en el formato de 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]

Los flujos nativos de Anthropic y Gemini se traducen a este formato para que todos los clientes puedan usar un único analizador.

Cabecera de autenticación

Cuando Requerir autenticación con Bearer Token está activado, envíe el token que se muestra en la ventana principal con cada solicitud:

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

Ajustes

Abra la ventana de Ajustes desde el icono de engranaje de la barra de herramientas inferior.

Ejemplos de cliente

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 usando el mismo formato de 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 de OpenAI para Python

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/gemini/v1",
    api_key="placeholder",  # se ignora cuando Bearer Token está desactivado
)
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 cualquier cliente Dart compatible con OpenAI
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // sin uso cuando Bearer Token está desactivado
);

Consejos

• Deje el Bearer Token desactivado mientras desarrolla en local; actívelo en cuanto habilite el acceso desde la red LAN.
• Use URLs base distintas por proveedor en el código de su cliente para poder cambiar de proveedor modificando una sola constante.
• El proxy se inicia automáticamente, pero puede detenerlo temporalmente desde la ventana principal si se produce un conflicto de puertos.
• Si el nivel gratuito de un proveedor limita su tasa de solicitudes, el mensaje de error original se reenvía tal cual. No se oculta al cliente ninguna lógica de reintento.
• El endpoint /v1/providers resulta útil para descubrir qué proveedores están configurados en tiempo de ejecución.

Resolución de problemas

El proxy no se inicia

• Puede que otro proceso ya esté usando el puerto 8421. Cambie el puerto en Ajustes y reinicie el proxy.
• Consulte el registro del sistema para ver el mensaje de error mostrado al iniciar.

Una solicitud devuelve 401 Unauthorized

• El requisito de Bearer Token está activado, pero el cliente no envió una cabecera Authorization: Bearer ... válida.
• La clave de API del propio proveedor puede no ser válida: el error original se reenvía, así que revise el cuerpo del mensaje.

Una solicitud devuelve "API key is not configured"

• Abra la lista de Proveedores y haga clic en Set API Key para el proveedor en cuestión.
• Para ERNIE deben rellenarse tanto la API Key como la Secret Key. Para Azure OpenAI también se requiere la Endpoint Base URL.

El dispositivo móvil no consigue acceder al proxy

• Active Allow LAN Access en Ajustes.
• Use la IP LAN que se muestra en el campo URL base, no localhost.
• Asegúrese de que ambos dispositivos estén en la misma red Wi-Fi y de que su firewall permita conexiones entrantes en el puerto del proxy.

Las respuestas en streaming llegan todas de golpe

• Asegúrese de que su cliente envía "stream": true en el cuerpo JSON.
• Algunas bibliotecas HTTP almacenan SSE en búfer de forma predeterminada: desactive el búfer de respuesta en el lado del cliente.

Privacidad

• Las claves de API se guardan cifradas con Fernet en ~/Library/Application Support/AIProxyServer/credentials.enc. La clave de cifrado de master.key tiene permisos 0600.
• El Bearer Token, cuando está activado, también se guarda únicamente en el almacén cifrado y nunca se escribe en el archivo de ajustes normal.
• El proxy solo reenvía solicitudes a los proveedores que usted haya configurado explícitamente. No realiza ninguna otra conexión saliente.
• Sin telemetría, sin analíticas, sin informes de fallos.
• La vinculación de red predeterminada es solo 127.0.0.1 . La exposición a la red LAN es opcional.
• El contenido de las conversaciones no se almacena. AIProxyServer reenvía los bytes y los olvida de inmediato.