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

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

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

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

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

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

1. Выберите любого провайдера из списка «Провайдеры» (например, OpenAI (ChatGPT))
2. Нажмите Получить API-ключ , чтобы открыть консоль провайдера в браузере, затем создайте или скопируйте ключ
3. Нажмите Задать API-ключ в той же строке и вставьте значение в диалоговом окне
4. Нажмите Сохранить. Метка статуса меняется на Настроено зелёного цвета

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

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

# Пример: OpenAI Python SDK, направленный на прокси
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 подставляет учётные данные вышестоящего сервиса при пересылке запроса.

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

Панель «Прокси-сервер»

Панель «Bearer Token»

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

Панель «Провайдеры»

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

• Отображаемое имя (например, Claude (Anthropic))
• Статус настройки — зелёное Настроено когда API-ключ сохранён, серое Не настроено в остальных случаях
• Путь URL, который используют ваши клиенты, например /anthropic/v1/chat/completions
• Задать API-ключ — открывает диалог для ввода учётных данных
• Получить API-ключ — открывает консоль провайдера в вашем браузере

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

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

Замечания по отдельным провайдерам

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

Справочник по API

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

Потоковая передача

Когда клиент отправляет "stream": true, прокси отвечает событиями 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 преобразуются к этому виду, чтобы все клиенты могли использовать один парсер.

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

Когда Требовать аутентификацию Bearer Token включён, отправляйте токен из главного окна с каждым запросом:

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

Настройки

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

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

cURL

# OpenAI (прямая передача)
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 выключенным, пока разрабатываете локально; включайте его сразу же, как только откроете доступ по локальной сети.
• Используйте в коде клиента отдельный базовый URL для каждого провайдера — тогда провайдера можно сменить, изменив одну константу.
• Прокси запускается автоматически, но при конфликте портов его можно временно остановить из главного окна.
• Если бесплатный тариф провайдера ограничивает частоту запросов, сообщение об ошибке передаётся дословно. Никакая логика повторов от клиента не скрывается.
• Конечная точка /v1/providers полезна, чтобы во время работы узнать, какие провайдеры настроены.

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

Прокси не запускается

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

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

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

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

• Откройте список провайдеров и нажмите Задать API-ключ для нужного провайдера.
• Для ERNIE нужно заполнить и API Key, и Secret Key. Для Azure OpenAI дополнительно требуется базовый URL конечной точки.

Мобильное устройство не может подключиться к прокси

• Включите Разрешить доступ по локальной сети в настройках.
• Используйте локальный IP-адрес, показанный в поле «Базовый URL», а не localhost.
• Убедитесь, что оба устройства подключены к одной сети Wi-Fi, а брандмауэр разрешает входящие подключения на порт прокси.

Потоковые ответы приходят целиком сразу

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

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

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