AIProxyServer - Guia

Primeiros passos

1. Inicie o aplicativo

Abra o AIProxyServer. Na primeira execução, o proxy inicia automaticamente e escuta na porta 8421 da sua máquina local. A janela principal exibe três seções:

• Servidor Proxy — status atual, URL base e um botão para iniciar ou parar o listener
• Bearer Token — opção de autenticação e exibição do token
• Provedores — todos os provedores de IA na nuvem compatíveis, com um botão Definir chave de API em cada linha

2. Adicione sua primeira chave de API

1. Escolha qualquer provedor da lista Provedores (por exemplo, OpenAI (ChatGPT))
2. Clique em Obter chave de API para abrir o console do provedor no navegador e, em seguida, criar ou copiar uma chave
3. Clique em Definir chave de API na mesma linha e cole o valor na caixa de diálogo
4. Clique em Salvar. O rótulo de status muda para Configurado em verde

3. Conecte um aplicativo cliente

Aponte qualquer cliente compatível com OpenAI para o proxy. A URL base é http://localhost:8421/<provider>/v1. O segmento do provedor determina qual nuvem recebe a requisição.

# Exemplo: SDK Python da OpenAI apontado para o 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)

O cliente nunca vê a chave real. O AIProxyServer anexa as credenciais de origem ao encaminhar a requisição.

Visão geral da interface

Painel Servidor Proxy

Painel Bearer Token

• Exigir autenticação Bearer Token — caixa de seleção que ativa ou desativa a autenticação. Desativada por padrão para um uso local sem complicações.
• Campo Token — exibição somente leitura do token atual. Mostrado como pontos; use Copiar para obtê-lo.
• Regenerar — gera um novo token aleatório. Os clientes existentes precisam ser atualizados com o novo valor.

Painel Provedores

Uma linha para cada provedor de nuvem compatível. Cada linha exibe:

• O nome exibido (por exemplo, Claude (Anthropic))
• Status de configuração — verde Configurado quando uma chave de API está salva; cinza Não configurado caso contrário
• O caminho de URL que seus clientes usam, por exemplo /anthropic/v1/chat/completions
• Definir chave de API — abre uma caixa de diálogo para inserir as credenciais
• Obter chave de API — abre o console do provedor no seu navegador

Provedores compatíveis

Onze serviços de IA na nuvem vêm integrados. A maioria usa nativamente o formato Chat Completions da OpenAI e é encaminhada como está. Três deles (Anthropic, Gemini, ERNIE) falam protocolos próprios; o AIProxyServer traduz requisições e respostas em tempo real, de modo que seu cliente veja apenas os formatos da OpenAI.

Observações específicas por provedor

• Azure OpenAI — cole o endpoint completo da implantação no campo URL base do endpoint , por exemplo https://my-resource.openai.azure.com/openai/deployments/gpt-4o. O proxy acrescenta /chat/completions?api-version=2024-02-01 automaticamente.
• ERNIE — o Baidu Qianfan usa OAuth, portanto tanto a API Key quanto a Secret Key são obrigatórias. O AIProxyServer solicita e mantém em cache os tokens de acesso nos bastidores.
• Gemini — a autenticação é feita por parâmetro de consulta na URL; o proxy o adiciona para você. As cotas por minuto do plano gratuito continuam valendo.

Referência da API

Endpoints

Streaming

Quando o cliente envia "stream": true, o proxy responde com Server-Sent Events no formato da 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]

Os streams nativos da Anthropic e do Gemini são convertidos para esse formato, de modo que todos os clientes possam usar um único parser.

Cabeçalho de autenticação

Quando Exigir autenticação Bearer Token está ativado, envie o token exibido na janela principal em todas as requisições:

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

Configurações

Abra a janela de Configurações pelo ícone de engrenagem na barra de ferramentas inferior.

Exemplos de cliente

cURL

# OpenAI (repasse direto)
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 o mesmo formato da 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",  # ignorado quando o Bearer Token está desativado
)
stream = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{"role": "user", "content": "Me conte uma piada"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Flutter / Dart

// Usando qualquer cliente Dart compatível com OpenAI
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // não usado quando o Bearer Token está desativado
);

Dicas

• Deixe o Bearer Token desativado enquanto estiver desenvolvendo localmente; ative-o assim que liberar o acesso à LAN.
• Use URLs base distintas para cada provedor no código do seu cliente, assim você troca de provedor alterando uma única constante.
• O proxy inicia automaticamente, mas você pode pará-lo temporariamente na janela principal caso ocorra um conflito de porta.
• Se o plano gratuito de um provedor limitar sua taxa de requisições, a mensagem de erro original é repassada na íntegra. Nenhuma lógica de nova tentativa fica oculta do cliente.
• O endpoint /v1/providers é útil para descobrir quais provedores estão configurados em tempo de execução.

Solução de problemas

O proxy não inicia

• Outro processo pode já estar usando a porta 8421. Altere a porta nas Configurações e reinicie o proxy.
• Verifique o log do sistema para ver a mensagem de erro exibida na inicialização.

Uma requisição retorna 401 Unauthorized

• A exigência de Bearer Token está ativada, mas o cliente não enviou um cabeçalho Authorization: Bearer ... correspondente.
• A chave de API do próprio provedor pode ser inválida — o erro de origem é repassado, então verifique o corpo da mensagem.

Uma requisição retorna "API key is not configured"

• Abra a lista Provedores e clique em Definir chave de API para o provedor em questão.
• Para o ERNIE, tanto a API Key quanto a Secret Key devem ser preenchidas. Para o Azure OpenAI, a URL base do endpoint também é obrigatória.

O dispositivo móvel não consegue acessar o proxy

• Ative Permitir acesso à LAN nas Configurações.
• Use o IP de LAN mostrado no campo URL base, e não localhost.
• Verifique se os dois dispositivos estão na mesma rede Wi-Fi e se o firewall permite conexões de entrada na porta do proxy.

As respostas em streaming chegam todas de uma vez

• Verifique se o seu cliente envia "stream": true no corpo JSON.
• Algumas bibliotecas HTTP fazem buffer de SSE por padrão — desative o buffer de resposta no lado do cliente.

Privacidade

• As chaves de API são armazenadas criptografadas com Fernet em ~/Library/Application Support/AIProxyServer/credentials.enc. A chave de criptografia em master.key tem permissões 0600.
• O Bearer Token, quando ativado, também é armazenado apenas no cofre criptografado e nunca é gravado no arquivo de configurações comum.
• O proxy só encaminha requisições para os provedores que você configurou explicitamente. Ele não faz nenhuma outra chamada externa.
• Sem telemetria, sem análises, sem relatórios de falhas.
• A vinculação de rede padrão é 127.0.0.1 apenas. A exposição na LAN é opcional.
• O conteúdo das conversas não é armazenado. O AIProxyServer encaminha os bytes e os esquece imediatamente.