AIProxyServer - Руководство

Начало работы

1. Запустите приложение

Откройте AIProxyServer. При первом запуске proxy запускается автоматически и слушает на порту 8421 вашей локальной машины. Главное окно содержит три раздела:

• Proxy Server — текущий статус, базовый URL и кнопка для запуска или остановки слушателя
• Bearer Token — необязательный переключатель аутентификации и отображение токена
• Providers — каждый поддерживаемый облачный AI-провайдер с кнопкой Set API Key для каждой строки

2. Добавьте свой первый API-ключ

1. Выберите любого провайдера из списка Providers (например, OpenAI (ChatGPT))
2. Нажмите Get API key, чтобы открыть консоль провайдера в браузере, затем создайте или скопируйте ключ
3. Нажмите Set API Key в той же строке и вставьте значение в диалоговое окно
4. Нажмите Save. Метка статуса меняется на Configured зелёного цвета

3. Подключите клиентское приложение

Направьте любой OpenAI-совместимый клиент на proxy. Базовый URL: http://localhost:8421/<provider>/v1. Сегмент provider определяет, какому облаку отправится запрос.

# Пример: OpenAI Python SDK, направленный на 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)

Клиент никогда не видит реальный ключ. AIProxyServer прикрепляет учётные данные upstream при пересылке запроса.

Обзор интерфейса

Панель Proxy Server

Панель Bearer Token

• Require Bearer Token authentication — флажок, включающий или отключающий аутентификацию. По умолчанию выключен для беспроблемного локального использования.
• Token field — отображение текущего токена только для чтения. Показан в виде точек; используйте Copy для его получения.
• Regenerate — выпустить новый случайный токен. Существующие клиенты должны быть обновлены новым значением.

Панель Providers

По одной строке на каждого поддерживаемого облачного провайдера. В каждой строке отображается:

• Отображаемое имя (например, Claude (Anthropic))
• Статус конфигурации — зелёный Configured, когда API-ключ сохранён, иначе серый Not configured
• URL-путь, который используют ваши клиенты, например /anthropic/v1/chat/completions
• Set API Key — открывает диалог для ввода учётных данных
• Get API key — открывает консоль провайдера в браузере

Поддерживаемые провайдеры

В комплект входят одиннадцать облачных AI-сервисов. Большинство нативно используют формат OpenAI Chat Completions и проксируются без изменений. Три (Anthropic, Gemini, ERNIE) используют собственные протоколы; AIProxyServer переводит запросы и ответы на лету, так что ваш клиент всегда видит только формат OpenAI.

Заметки по конкретным провайдерам

• Azure OpenAI — вставьте полную конечную точку развёртывания в поле Endpoint Base URL, например https://my-resource.openai.azure.com/openai/deployments/gpt-4o. Proxy автоматически добавляет /chat/completions?api-version=2024-02-01.
• ERNIE — Baidu Qianfan использует OAuth, поэтому требуются и API Key, и Secret Key. AIProxyServer запрашивает и кэширует токены доступа в фоновом режиме.
• Gemini — аутентификация осуществляется через параметр URL-запроса; proxy добавляет его за вас. Квоты бесплатного уровня на минуту по-прежнему действуют.

Справочник API

Конечные точки

Стриминг

Когда клиент отправляет "stream": true, proxy отвечает с помощью Server-Sent Events в формате 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]

Нативные потоки Anthropic и Gemini переводятся в этот формат, поэтому все клиенты могут использовать единый парсер.

Заголовок аутентификации

Когда Require Bearer Token authentication включён, отправляйте токен из главного окна с каждым запросом:

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

Настройки

Откройте окно настроек значком шестерёнки в нижней панели инструментов.

Примеры клиентов

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 через тот же формат 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",  # игнорируется, когда Bearer Token выключен
)
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

// Используя любой OpenAI-совместимый Dart-клиент
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // не используется, когда Bearer Token выключен
);

Советы

• Оставляйте Bearer Token выключенным, пока вы разрабатываете локально; включите его в тот момент, когда разрешите доступ по LAN.
• Используйте разные Base URL для каждого провайдера в коде клиента, чтобы можно было переключать провайдеров изменением одной константы.
• Proxy запускается автоматически, но вы можете временно остановить его из главного окна, если возникает конфликт портов.
• Если бесплатный уровень провайдера ограничивает вас по частоте, сообщение об ошибке upstream передаётся дословно. Никакой логики повторных попыток от клиента не скрыто.
• Конечная точка /v1/providers полезна для обнаружения того, какие провайдеры настроены во время выполнения.

Устранение неполадок

Proxy не запускается

• Другой процесс уже может использовать порт 8421. Измените порт в настройках и перезапустите proxy.
• Проверьте системный журнал для сообщения об ошибке, отображённого при запуске.

Запрос возвращает 401 Unauthorized

• Требование Bearer Token включено, но клиент не отправил соответствующий заголовок Authorization: Bearer ....
• Собственный API-ключ провайдера может быть недействителен — ошибка upstream передаётся, поэтому проверьте тело сообщения.

Запрос возвращает "API key is not configured"

• Откройте список Providers и нажмите Set API Key для соответствующего провайдера.
• Для ERNIE необходимо заполнить и API Key, и Secret Key. Для Azure OpenAI также требуется Endpoint Base URL.

Мобильное устройство не может достичь proxy

• Включите Allow LAN Access в настройках.
• Используйте LAN IP, отображаемый в поле Base URL, а не localhost.
• Убедитесь, что оба устройства находятся в одной сети Wi-Fi и что ваш межсетевой экран разрешает входящие подключения к порту proxy.

Стриминговые ответы приходят все сразу

• Убедитесь, что ваш клиент отправляет "stream": true в JSON-теле.
• Некоторые HTTP-библиотеки по умолчанию буферизуют SSE — отключите буферизацию ответа на стороне клиента.

Конфиденциальность

• API-ключи хранятся зашифрованными с помощью Fernet в ~/Library/Application Support/AIProxyServer/credentials.enc. Ключ шифрования в master.key имеет права 0600.
• Bearer Token, когда включён, также хранится только в зашифрованном хранилище и никогда не записывается в обычный файл настроек.
• Proxy пересылает запросы только тем провайдерам, которых вы явно настроили. Никаких других исходящих вызовов не выполняется.
• Никакой телеметрии, никакой аналитики, никаких отчётов о сбоях.
• Сетевая привязка по умолчанию — только 127.0.0.1. Открытие LAN осуществляется по согласию.
• Содержимое разговоров не сохраняется. AIProxyServer пересылает байты и немедленно их забывает.