Compatibility Layer Open Source

OpenAI API Bridge

Тонкий совместимый слой между Responses API и Chat Completions API, который упрощает работу с разными OpenAI-совместимыми моделями и провайдерами.

OpenAI API Transform

FastAPI-сервис-прокси, который обеспечивает мост между Responses API и Chat Completions API OpenAI, позволяя использовать единый современный клиент для работы с различными моделями и API.

🎯 Основные преимущества

🔄 Универсальность использования

Прямая переадресация: Если ваша модель поддерживает Responses API — запросы переадресовываются напрямую без изменений
Адаптация для Chat Completions: Если модель поддерживает только Chat Completions API — запросы автоматически адаптируются
Единый клиент: Используйте официальный современный клиент Responses API для работы с любыми моделями
Прозрачность: Клиент не знает, какой API использует модель на самом деле

🚀 Возможности

Двунаправленный перевод API: Конвертация между форматами Responses API и Chat Completions API
Поддержка стриминга: Полная поддержка как потоковых, так и обычных ответов
Интеграция с reasoning: Обработка reasoning-контента и структурированных выходов
Tool Calling: Поддержка вызова функций с правильной потоковой передачей событий
Гибкий бэкенд: Настраиваемые удаленные OpenAI-совместимые эндпоинты
Полное тестирование: Комплексный набор тестов с интеграционными проверками

📋 Требования

Python 3.12+
OpenAI-совместимый API эндпоинт (например, vLLM, Ollama, или OpenAI API)

🛠️ Установка

Клонируйте репозиторий:

git clone https://github.com/yourusername/openai-api-bridge.git
cd openai-api-bridge

Установите зависимости с помощью uv (рекомендуется):

uv sync

Или с помощью pip:

pip install -e .

⚙️ Конфигурация

Настройка переменных окружения

Установите следующие переменные окружения:

# Удаленный OpenAI-совместимый эндпоинт
export REMOTE_OPENAI_BASE_URL=http://localhost:8000
export REMOTE_OPENAI_API_KEY=your-api-key

# Модель по умолчанию
export DEFAULT_MODEL=gpt-4

# Конфигурация сервера
export PORT=8099
export HOST=127.0.0.1

Переменные окружения

Переменная	Описание	По умолчанию	Обязательная
`REMOTE_OPENAI_BASE_URL`	URL OpenAI-совместимого эндпоинта	`http://localhost:8000`	Да
`REMOTE_OPENAI_API_KEY`	API ключ для удаленного эндпоинта	`your-api-key`	Да
`DEFAULT_MODEL`	Модель по умолчанию	`gpt-4`	Нет
`PORT`	Порт для запуска сервера	`8099`	Нет
`HOST`	Хост для привязки сервера	`127.0.0.1`	Нет
`LOG_LEVEL`	Уровень логирования	`info`	Нет

Примеры для разных провайдеров

OpenAI API:

export REMOTE_OPENAI_BASE_URL=https://api.openai.com/v1
export REMOTE_OPENAI_API_KEY=sk-your-openai-api-key
export DEFAULT_MODEL=gpt-4

vLLM:

export REMOTE_OPENAI_BASE_URL=http://localhost:8000
export REMOTE_OPENAI_API_KEY=EMPTY
export DEFAULT_MODEL=your-model-name

Ollama:

export REMOTE_OPENAI_BASE_URL=http://localhost:11434/v1
export REMOTE_OPENAI_API_KEY=ollama
export DEFAULT_MODEL=llama2

🚀 Использование

Запуск сервера:

# С помощью uv
uv run python main.py

# Или напрямую
python main.py

Сервер запустится на http://127.0.0.1:8099 по умолчанию.

API Эндпоинты

Responses API Эндпоинт

POST /v1/responses - Основной эндпоинт для запросов Responses API

Тестовый эндпоинт

POST /test - Простой тестовый эндпоинт для проверки подключения

Примеры использования

Использование Responses API через мост:

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8099",
    api_key="test"  # Любой ключ работает для моста
)

# Обычный запрос
response = client.responses.create(
    model="gpt-4",
    input="Привет, как дела?",
)

# Потоковый запрос
with client.responses.stream(
    model="gpt-4",
    input="Расскажи мне историю",
) as stream:
    for event in stream:
        print(f"Событие: {event.type}")
        if hasattr(event, 'response') and event.response:
            print(f"Ответ: {event.response}")

Использование с reasoning:

response = client.responses.create(
    model="gpt-4",
    input="Реши эту математическую задачу: 2x + 5 = 13",
    reasoning={"effort": "medium", "generate_summary": True}
)

🔄 Сценарии использования

Сценарий 1: Модель поддерживает Responses API

# Ваш сервер автоматически переадресует запросы напрямую
# Без каких-либо изменений в коде клиента
client = OpenAI(base_url="http://your-responses-api-server:8099")
response = client.responses.create(model="your-model", input="Hello")

Сценарий 2: Модель поддерживает только Chat Completions API

# Ваш сервер автоматически адаптирует запросы
# Клиент продолжает использовать Responses API
client = OpenAI(base_url="http://your-chat-completions-server:8099")
response = client.responses.create(model="your-model", input="Hello")
# Запрос автоматически конвертируется в Chat Completions формат

💡 Почему это важно?

Проблема: Разные модели и сервисы поддерживают разные API: - Некоторые модели поддерживают только Chat Completions API (старый формат) - Новые модели поддерживают Responses API (современный формат) - Разработчикам приходится писать разный код для разных API

Решение: OpenAI API Transform решает эту проблему: - ✅ Единый клиент: Используйте только Responses API клиент - ✅ Автоматическая адаптация: Сервер сам определяет, какой API нужен - ✅ Прозрачность: Ваш код не меняется при смене модели - ✅ Современность: Всегда используйте последние возможности Responses API

🧪 Тестирование

Запуск набора тестов:

# Запустить все тесты
uv run pytest

# Запустить конкретный файл тестов
uv run pytest tests/test_responses_integration.py -v

# Запустить с покрытием кода
uv run pytest --cov=. --cov-report=html

Категории тестов

Unit Tests: Тестирование отдельных компонентов адаптеров
Integration Tests: Сквозные тесты с реальными API вызовами
Usage Handling: Тестирование различных паттернов использования API
Adapter Validation: Тестирование логики преобразования данных

🏗️ Архитектура

Мост состоит из двух основных адаптеров:

ResponsesToChatAdapter

Конвертирует запросы Responses API в формат Chat Completions
Обрабатывает параметры reasoning, определения инструментов и структурированные выходы
Добавляет рекомендательные заметки для лучшего поведения модели

ChatCompletionsToResponsesAdapter

Конвертирует ответы Chat Completions обратно в формат Responses API
Обрабатывает потоковые события и обычные ответы
Управляет reasoning-контентом и событиями вызова инструментов

📁 Структура проекта

openai-api-transform/
├── adapters/                    # Логика преобразования API
│   ├── __init__.py
│   ├── ResponsesToChatAdapter.py
│   └── ChatCompletionsToResponsesAdapter.py
├── tests/                       # Набор тестов
│   ├── conftest.py
│   ├── test_adapter_validation.py
│   ├── test_adapters_unit.py
│   ├── test_fastapi_direct.py
│   ├── test_responses_integration.py
│   └── test_usage_handling.py
├── old/                         # Старые отладочные файлы
│   ├── debug_httpx_advanced.py
│   ├── debug_nonstream.py
│   ├── debug_openai_headers.py
│   ├── debug_requests.py
│   └── debug_test.py
├── logs/                        # Логи запросов/ответов
├── main.py                      # FastAPI приложение
├── pyproject.toml              # Конфигурация проекта
├── TEST_REPORT.md              # Отчет о тестировании
├── uv.lock                     # Заблокированные зависимости
└── README.md                   # Этот файл

Упрощенная архитектура

Проект был упрощен для фокуса на основной функциональности:

Удалены: Docker, CI/CD конфигурации, Makefile, файлы окружения
Сохранено: Основная логика адаптеров, тесты, FastAPI приложение
Конфигурация: Теперь только через переменные окружения
Тестирование: Все тесты используют переменные окружения для гибкости

🔧 Разработка

Добавление новых функций

Новые параметры API: Добавьте поддержку в соответствующий адаптер
Новые типы ответов: Расширьте логику преобразования ответов
Новые модели: Обновите обработку моделей в адаптерах

Отладка

Включите отладочное логирование:

export LOG_LEVEL="debug"

Проверьте директорию logs/ для подробных логов запросов/ответов.

Тестирование

Все тесты настроены для использования переменных окружения. Убедитесь, что установлены необходимые переменные перед запуском тестов:

# Установите переменные окружения для тестов
export DEFAULT_MODEL=gpt-4
export REMOTE_OPENAI_API_KEY=your-api-key
export REMOTE_OPENAI_BASE_URL=http://localhost:8000

# Запустите тесты
uv run pytest

🤝 Участие в разработке

Форкните репозиторий
Создайте ветку для функции: git checkout -b feature-name
Внесите изменения и добавьте тесты
Установите переменные окружения для тестов
Запустите набор тестов: uv run pytest
Зафиксируйте изменения: git commit -m "Add feature"
Отправьте в ветку: git push origin feature-name
Создайте pull request

📄 Лицензия

Этот проект лицензирован под MIT License - см. файл LICENSE для подробностей.

🙏 Благодарности

OpenAI за спецификации API
FastAPI за отличный веб-фреймворк
Сообщество open-source за различные зависимости

📞 Поддержка

Если у вас возникли проблемы или есть вопросы:

Проверьте страницу Issues
Создайте новый issue с подробной информацией
Включите логи и сообщения об ошибках, когда это возможно

Примечание: Этот мост предназначен для работы с OpenAI-совместимыми API. Убедитесь, что ваш бэкенд-эндпоинт поддерживает необходимые функции (reasoning, tool calling и т.д.) для полной функциональности.