Используйте Claude с OpenAI SDK без переписывания клиента

Вы можете направить официальный OpenAI SDK для Python или TypeScript на Claude, изменив base_url, API-ключ и ID модели, а затем продолжить использовать chat.completions. Anthropic описывает этот путь в руководстве по совместимости OpenAI SDK. Ту же форму клиента можно направить на OpenAI-совместимый API-шлюз, который хранит учётные данные Anthropic на сервере и преобразует OpenAI-запросы в нативные Claude Messages для upstream.

Эти два пути не равнозначны. Прямая совместимость предназначена для оценки. Production-шлюз, говорящий с клиентами на языке OpenAI, а с Anthropic — через Claude Messages, обеспечивает иной уровень надёжности.

Путь оценки и путь production

Anthropic указывает, что его слой совместимости с OpenAI предназначен главным образом для тестирования и сравнения моделей и не является долгосрочным или production-ready решением для большинства сценариев. Считайте это продуктовой политикой, а не мелким маркетинговым примечанием.

Путь	Клиент	Upstream	Лучше всего подходит для
Прямая совместимость Anthropic	OpenAI SDK → https://api.anthropic.com/v1/	OpenAI-образная поверхность Anthropic	Локальная оценка, сравнение промптов, короткие эксперименты
OpenAI-вход шлюза	OpenAI SDK → /v1 вашего шлюза	Шлюз преобразует запрос в нативные Claude Messages	Общие ключи, квоты, failover, мультипровайдерные продукты
Нативный Anthropic SDK / Messages API	Клиент Anthropic	Полный набор функций Claude	Prompt caching, цитаты, детали extended thinking, гарантированные структурированные ответы

Первый путь отвечает на вопрос «достаточно ли хорош Claude на нашем фиксированном наборе?». Второй нужен, когда нескольким сервисам требуется Claude без отдельного ключа Anthropic в каждом. Третий выбирают для нативных возможностей Claude, которые слой совместимости пропускает или игнорирует.

Claude-канал этого репозитория преобразует OpenAI Chat Completions в Claude Messages (RequestOpenAI2ClaudeMessage и связанные адаптеры). Это не простое проксирование совместимого endpoint Anthropic без изменений. Клиенты по-прежнему отправляют OpenAI JSON, а control plane владеет отображением, учётными данными и журналами использования.

Важные ограничения слоя совместимости Anthropic с OpenAI

При вызове api.anthropic.com через OpenAI SDK актуальная документация Anthropic перечисляет конкретные пробелы. Учтите их до заявления о «полной drop-in совместимости».

1. strict у tools игнорируется. JSON аргументов не гарантированно соответствует переданной схеме. Проверяйте его в runtime или используйте нативные структурированные ответы Claude, когда нужны серверные гарантии.
2. Аудиоввод удаляется. Мультимодальные аудиочасти игнорируются, а не отклоняются явной ошибкой.
3. Prompt caching не поддерживается на пути совместимости. Кэширование доступно через собственные SDK и нативный API Anthropic.
4. Сообщения system и developer поднимаются в начало и объединяются в одно ведущее system-сообщение. Anthropic поддерживает одно начальное system-сообщение; OpenAI-совместимые system/developer-тёрны внутри диалога объединяются с переводами строк.
5. Большинство неподдерживаемых полей молча игнорируется. В staging используйте fail-closed для полей, исчезновение которых меняет поведение продукта.
6. Тела ошибок сохраняют OpenAI-образную оболочку, но текст деталей не эквивалентен OpenAI. Логируйте его для отладки, но не разбирайте прозу как стабильный контракт.

Полные возможности Claude — обработка PDF, цитаты, extended thinking с подробным доступом к рассуждению и prompt caching — относятся к нативному Claude API или пути шлюза, который отображает эти нативные поля. Для переносимых между брендами циклов инструментов см. переносимый tool calling между провайдерами.

Прямой base URL Anthropic (оценка)

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    base_url="https://api.anthropic.com/v1/",
)

response = client.chat.completions.create(
    model="claude-sonnet-5",  # or claude-opus-4-8; verify on Anthropic model docs
    messages=[
        {"role": "system", "content": "You are a precise API integration assistant."},
        {"role": "user", "content": "Summarize three risks of hardcoding provider SDKs."},
    ],
    max_tokens=800,
)

print(response.choices[0].message.content)

TypeScript:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ANTHROPIC_API_KEY,
  baseURL: "https://api.anthropic.com/v1/",
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-5",
  messages: [
    { role: "system", content: "You are a precise API integration assistant." },
    { role: "user", content: "Summarize three risks of hardcoding provider SDKs." },
  ],
  max_tokens: 800,
});

console.log(response.choices[0]?.message?.content);

В официальных примерах часто используется claude-opus-4-8. Актуальная таблица моделей Anthropic также перечисляет Claude Sonnet 5 и Claude Haiku 4.5. Всегда предпочитайте живую таблицу моделей любому снимку в статье, включая этот.

Base URL шлюза (production-форма для нескольких сервисов)

Когда Claude — один из нескольких каналов, направьте тот же SDK на шлюз, а учётные данные Anthropic оставьте только на сервере:

client = OpenAI(
    api_key="GATEWAY_API_KEY",
    base_url="https://your-gateway.example.com/v1",
)

response = client.chat.completions.create(
    model="claude-sonnet",  # stable gateway alias mapped to a current Claude ID
    messages=[
        {
            "role": "user",
            "content": "Draft a migration checklist for SDK consolidation.",
        }
    ],
    max_tokens=800,
)

Операторы отображают alias вроде claude-sonnet или claude-opus на реальные upstream-ID (claude-sonnet-5, claude-opus-4-8, при необходимости датированные снимки). Конфигурации приложений должны зависеть от alias, чтобы переименование upstream стало правкой канала, а не инцидентом во множестве репозиториев. Это control plane, описанный в мультипровайдерном LLM-шлюзе.

Что обычно переносится по общему пути

Сообщения

• Обычная история system / user / assistant работает для оценки и большинства продуктовых чатов.
• System- или developer-тёрны внутри диалога не сохраняются как отдельные OpenAI-роли на слое совместимости Anthropic; ожидайте объединения.
• Формулируйте политику явно. Не предполагайте, что Claude унаследует скрытые инструкции, настроенные только для моделей OpenAI.

Tools

OpenAI-образные определения tools часто работают при первых переносах агентов. Пример:

tools = [
    {
        "type": "function",
        "function": {
            "name": "lookup_order",
            "description": "Fetch an order by ID from the shop system",
            "parameters": {
                "type": "object",
                "properties": {"order_id": {"type": "string"}},
                "required": ["order_id"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Where is order A-100?"}],
    tools=tools,
    tool_choice="auto",
)

message = response.choices[0].message
if message.tool_calls:
    for call in message.tool_calls:
        print(call.function.name, call.function.arguments)

Поскольку strict игнорируется на поверхности совместимости Anthropic, разбирайте и валидируйте arguments по схеме до любого побочного эффекта. На пути через шлюз также продолжайте проверку в исполнителе tools; никогда не доверяйте одному лишь JSON, выданному моделью.

Streaming

SSE streaming соответствует формату, который уже потребляет большинство OpenAI chat UI. Проверьте задержку до первого токена, обработку ошибок посреди потока и нормализует ли шлюз события Claude в стабильную форму для клиента. Автоматическая смена провайдера после частичного вывода сложнее failover до начала потока; сочетайте это со стратегией failover LLM API.

Пробелы в структурированном выводе, безопасности и наблюдаемости

Если пайплайн зависит от строгого применения JSON Schema, протестируйте точную схему на Claude до заявления о паритете. Там, где strict-режим неполон, проверяйте данные в коде приложения или используйте нативные структурированные ответы Claude.

Даже при одинаковых JSON-ключах провайдеры различаются отказами, заголовками rate limit и учётом токенов. Если клиенты ожидают один контракт, нормализуйте классы ошибок на шлюзе. Не повторяйте постоянные ошибки аутентификации или политики как временные 5xx.

Прямые ключи Anthropic и ключи шлюза формируют разные audit trail. Командам обычно нужна история использования рядом со здоровьем каналов, а не только в консоли одного провайдера. Публичные страницы цен и каталога моделей полезны участникам процесса; не вставляйте аутентифицированные операторские URL в каждый абзац.

Контролируемая последовательность переключения

1. Инвентаризируйте сервисы, уже зависящие от OpenAI SDK или сырого /v1/chat/completions.
2. Запустите фиксированный набор оценки против совместимого endpoint Anthropic с одним ID модели Claude.
3. Зарегистрируйте учётные данные Anthropic как канал шлюза и опубликуйте стабильный alias.
4. Направьте на alias один низкорисковый внутренний job; не переключайте клиентский чат первым.
5. Сравните валидность схем, долю отказов, задержку и стоимость успешной задачи.
6. Добавляйте tools и streaming только после стабилизации обычного чата.
7. Задокументируйте rollback и оставьте прежний alias модели активным.

HTTP smoke test

curl https://your-gateway.example.com/v1/chat/completions \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet",
    "messages": [
      {"role": "user", "content": "Reply with the single word ready."}
    ],
    "max_tokens": 32
  }'

Ожидайте JSON тела Chat Completions с choices[0].message.content. Если форма расходится — чините mapping шлюза до product-кода.

Production checklist (путь через шлюз)

• Оценка доказала качество на фиксированном наборе; production-трафик не использует слой совместимости Anthropic как долгосрочный hop.
• Alias модели отображается на актуальный Claude ID из документации Anthropic или поддерживаемого каталога.
• Секреты находятся в шлюзе или secret manager, а не в браузерах и мобильных приложениях.
• max_tokens задан явно; молчаливые значения по умолчанию могут обрезать длинные ответы.
• Аргументы tools валидируются по схеме на сервере; система не полагается на игнорируемый strict.
• Streaming-клиенты обрабатывают неполные завершения и ошибки посреди потока.
• Дашборды стоимости и ошибок отделяют Claude от других провайдеров.
• Политика failover указывает, является ли Claude основным, резервным или закреплённым.

Когда шлюз лучше прямого Anthropic base URL

Триггер	Польза шлюза
Несколько провайдеров в одном продукте	Одна конфигурация клиента, много каналов
Учётные данные всей команды	Scoped-ключи шлюза вместо общих ключей Anthropic
Обзоры расходов	Единая история использования и контекст цен
Цели надёжности	Retry и failover без переписывания каждого сервиса
Флоты агентов	Центральная политика tools и маршрутизации моделей

AveMujica API построен как такой control plane: OpenAI-совместимый ingress, каналы провайдеров, каталог моделей и операционная история. Он не отменяет необходимость читать примечания Anthropic о совместимости, но не даёт им превратиться в пять расходящихся веток клиента.

Официальные источники

• Anthropic OpenAI SDK compatibility
• Обзор моделей Anthropic
• Справочник OpenAI Chat Completions
• OpenAI Python SDK

Последняя проверка: 2026-07-15. Перед фиксацией production-конфигурации перепроверьте ID моделей и ограничения совместимости в документации Anthropic.

Частые вопросы

Готов ли путь Anthropic через OpenAI SDK для production?

Anthropic описывает его как путь прежде всего для тестирования и сравнения, а не как долгосрочное production-решение для большинства сценариев. Для production-флотов предпочитайте шлюз, преобразующий OpenAI-вход в нативные Claude Messages, либо нативный API Anthropic там, где нужны возможности только Claude.

Можно ли без изменений использовать на Claude каждое поле OpenAI Chat Completions?

Нет. strict игнорируется, аудио удаляется, prompt caching недоступен на слое совместимости, а system/developer-тёрны объединяются. Тестируйте точную форму запроса, которую выпускаете.

Какую строку модели помещать в конфигурацию приложения?

Предпочитайте alias шлюза (claude-sonnet), который операторы отображают на актуальный ID вроде claude-sonnet-5 или claude-opus-4-8. Не хардкодьте вчерашний snapshot во всех сервисах.

Нужен ли мне по-прежнему Anthropic SDK?

Да, когда вам намеренно нужны нативные возможности: маркеры prompt caching, полный доступ к extended thinking, нативные структурированные ответы. Сохраняйте OpenAI SDK, когда OpenAI-образной поверхности достаточно, а разнообразием провайдеров управляет шлюз.

Выпустите первое переключение на Claude

Выберите один сервис, уже использующий OpenAI SDK. Докажите качество на совместимом endpoint Anthropic, затем переведите сервис на alias шлюза, который маршрутизирует запросы в Claude Messages. Расширяйте tools и streaming только после успешной проверки обычного чата и сравните трафик первого дня с прежним базовым уровнем OpenAI.