SDK API DeepSeek: используйте SDK OpenAI и меняйте эндпоинты

Почему SDK OpenAI является SDK для API DeepSeek

Когда люди ищут SDK API DeepSeek, они ожидают пакет с именем поставщика. На практике собственная документация DeepSeek описывает вызов своего API через SDK OpenAI с другим базовым URL, поскольку API следует формату запросов и ответов OpenAI. Проверьте их текущую документацию, чтобы узнать точный базовый URL и названия моделей; именно они — авторитетный источник по своему сервису.

Из этого следует практическая польза. Любой код, написанный с использованием клиентской библиотеки OpenAI, может взаимодействовать с любым сервером, реализующим те же эндпоинты, которые здесь представляют собой POST /v1/chat/completions, POST /v1/responses и GET /v1/models. Переход между поставщиками становится изменением конфигурации, а не переписыванием кода. В остальной части этой статьи показан шаблон на Python, Node и curl, а затем структура, которая делает замену тривиальной.

Настройка Python

Установите официальный пакет и укажите ему эндпоинт:

Copypip install openai

Copyfrom openai import OpenAI

client = OpenAI(
    base_url="https://api.deepseekapi.top/v1",
    api_key="YOUR_KEY",
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Explain idempotency in two sentences."},
    ],
)
print(resp.choices[0].message.content)
print(resp.usage)

Получите ключ на странице API-ключ. Новые пользователи могут получить $0,50 пробного баланса одним кликом без привязки карты. Статья DeepSeek API Python подробнее рассказывает об этом языке, включая обработку ошибок.

Настройка Node.js

Copynpm install openai

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.deepseekapi.top/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "List four uses of a message queue." }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

Шаблон идентичен: базовый URL, ключ, модель. Потоковая передача возвращает Server-Sent Events, а библиотека преобразует их в асинхронный итератор. Вызов функций следует той же схеме, что и в других API, совместимых с OpenAI: передайте tools, прочитайте потоковые tool_calls и верните результаты в виде сообщений role: "tool".

Сделайте эндпоинт заменяемым

Не жестко кодируйте три значения. Считывайте их из окружения и оборачивайте создание клиента в одну функцию. Тогда переход с одного эндпоинта на другой означает редактирование файла .env, а не исходного кода.

Copyimport os
from openai import OpenAI

def make_client():
    return OpenAI(
        base_url=os.environ.get("LLM_BASE_URL", "https://api.deepseekapi.top/v1"),
        api_key=os.environ["LLM_API_KEY"],
    )

MODEL = os.environ.get("LLM_MODEL", "uncensored")

def ask(prompt: str) -> str:
    r = make_client().chat.completions.create(
        model=MODEL,
        messages=[{"role": "user", "content": prompt}],
        temperature=0.7,
    )
    return r.choices[0].message.content

Теперь для другого провайдера нужно всего три переменные окружения. Официальные SDK также считывают OPENAI_API_BASE и OPENAI_API_KEY в некоторых версиях, но явные переменные понятнее и позволяют избежать неожиданностей при запуске нескольких провайдеров одновременно.

Если вы используете TypeScript или другой язык, идея та же: одна функция фабрики, три переменные, без имен поставщиков, разбросанных по кодовой базе. Распространенная ошибка — позволить имени поставщика просачиваться в имена функций, сообщения журнала и имена переменных, что затрудняет последующую замену. Называйте вещи по их назначению (ask, summarise), а не по поставщику.

Сохраните небольшой тест, отправляющий один фиксированный промпт через ask() и проверяющий наличие непустого ответа. Запускайте его после каждого изменения эндпоинта; он выявит неверные URL и ключи за секунды.

Что остается неизменным, а что меняется при замене

Именно последняя строка многих сбивает с толку. Эндпоинт совместим на уровне протокола, а не на уровне поведения. Два поставщика могут принимать идентичные запросы и выдавать очень разные ответы. Модель здесь — это одна модель с открытыми весами от независимого поставщика, настроенная для ответов без отказов по контенту при законном использовании взрослыми, и это не официальное API DeepSeek или любой другой лаборатории. Повторно проверьте промпты, которые вы настраивали для другой модели.

Возможности этого эндпоинта и их отсутствие

• Поддерживается: chat completions, формат Responses, список моделей, потоковая передача, вызов функций, JSON-режим (response_format с json_object), а также передача параметров temperature, top_p, stop, seed и штрафов.
• Не предлагается: генерация изображений, аудио или видео, эмбеддинги, тонкая настройка.
• Ограничения: контекстное окно на 100 000 токенов, максимальный размер тела 8 МБ, 8 параллельных запросов и 300 в минуту для полного ключа (2 и 60 для пробного ключа).
• Ошибки: HTTP 429 с кодом rate_limited или concurrency и заголовок Retry-After: 5 при временной перегрузке.

Если ваш код обращается к эндпоинту эмбеддингов, вам понадобится другой поставщик для этой части, и вы можете оставить чат здесь. Разделение по задачам — распространенная причина использования шаблона переменных окружения выше.

Чек-лист миграции

Когда вы заменяете один эндпоинт на другой в существующем проекте, пройдите короткий список, а не меняйте все сразу.

1. Проверьте эндпоинт. Отправьте один запрос с помощью curl и убедитесь, что вы получили текст в ответ. Вызовите GET /v1/models и проверьте, что идентификатор uncensored указан в списке.
2. Измените три значения. Базовый URL, ключ, имя модели, ничего больше. Пока не трогайте промпты.
3. Запустите существующие тесты. Если у вас есть тесты регрессии промптов, запустите их и отметьте, какие не прошли. Сбои обычно связаны с поведением, например, другим форматом вывода, а не ошибками протокола.
4. Проверьте параметры. Уберите опции, которые не нужны эндпоинту. Оставьте temperature, top_p, stop и seed, если вы их используете.
5. Тестируйте потоковую передачу и инструменты отдельно. Ошибки потоковой передачи часто скрываются в коде клиента, который предполагает определенную структуру чанков. Вызовы инструментов требуют схемы, которой модель хорошо следует, поэтому тестируйте с использованием ваших реальных функций.
6. Измерьте стоимость и задержку на реальном трафике. Сравнивайте запросы за целый день, а не один промпт.

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

Обработка повторных попыток и отслеживание использования

SDK по умолчанию делают повторные попытки при некоторых сбоях, но вам всё равно следует самостоятельно обрабатывать код 429, поскольку ограничения на параллельные запросы в реальных условиях действительно существуют. Перехватывайте исключение лимита запросов, ждите количество секунд из заголовка Retry-After (5 при перегрузке) и повторяйте запрос несколько раз. Неудачные запросы не списываются, поэтому повторные попытки безопасны для вашего баланса.

Логируйте usage.prompt_tokens и usage.completion_tokens при каждом вызове. Тарификация составляет $0,15 за 1M входных токенов и $0,50 за 1M выходных токенов, поэтому вызов с 2000 входными и 600 выходными токенами стоит 2000 × $0,15 / 1M + 600 × $0,50 / 1M = $0,0003 + $0,0003 = $0,0006. Заголовки ответа также включают X-Balance-USD для оставшегося баланса. См. страницу тарифов для пополнений и бонусов, а также документацию для полного списка параметров.

Редакторы и другие инструменты

Три значения переносятся в любой инструмент с настройкой провайдера, совместимого с OpenAI. Статья о использовании API в стиле DeepSeek в Cursor подробно разбирает такой редактор. В каждом инструменте поля помечены немного иначе, но вы всегда вводите базовый URL, заканчивающийся на /v1, ключ и имя модели.

Дополнительные руководства

• Стоимость API DeepSeek по сравнению с API OpenAI: рабочие примеры
• Ключ API DeepSeek: доступ к API LLM без цензуры