Техническое руководство по интеграции с API DeepSeek-R1 и DeepSeek-V3 на Python

Интеграция с языковыми моделями DeepSeek через программный интерфейс требует понимания структуры HTTP-запросов, методов аутентификации и особенностей работы с потоковыми ответами. Данное руководство описывает процесс вызова API для моделей DeepSeek-R1 (reasoner) и DeepSeek-V3 (chat) с использованием библиотеки requests в Python.

Предварительные требования и настройка окружения

Для начала работы необходимо получить API-ключ в личном кабинете платформы DeepSeek. Ключ генерируется в разделе управления API и представляет собой строку формата sk-{хеш-значение}. Важно сохранить ключ после создания, так как платформа не предоставляет возможность его повторного просмотра.

Минимальные требования к программному обеспечению:

• Python 3.8 или новее: Языковая среда должна быть установлена и доступна через переменную окружения PATH.
• Библиотека requests: Устанавливается через пакетный менеджер pip командой pip install requests.
• Активный баланс: Для функционирования API требуется положительный баланс на счете в платформе DeepSeek.

Архитектура базового запроса к Chat Completions API

Основной эндпоинт для взаимодействия: https://api.deepseek.com/chat/completions. Запрос выполняется методом POST с заголовками:

Content-Type: application/json
Authorization: Bearer {API_KEY}

Тело запроса представляет собой JSON-объект со следующими обязательными полями:

model: Идентификатор модели: "deepseek-reasoner" для R1 или "deepseek-chat" для V3.
messages: Массив объектов сообщений, где каждый объект содержит поля role (system, user, assistant) и content (текст сообщения).
stream: Булево значение, определяющее режим ответа: false для единовременного получения полного ответа, true для потокового вывода.

Реализация базового вызова с синхронным ответом

Ниже представлен минимальный рабочий пример кода для вызова DeepSeek-R1 с отключенным потоковым режимом:

import requests

API_KEY = "sk-ваш_ключ"
url = "https://api.deepseek.com/chat/completions"

headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}"
}

data = {
    "model": "deepseek-reasoner",
    "messages": [
        {"role": "user", "content": "Кто ты?"}
    ],
    "stream": False
}

response = requests.post(url, headers=headers, json=data)
if response.status_code == 200:
    result = response.json()
    print(result['choices'][0]['message']['content'])
else:
    print("Ошибка:", response.status_code)

Организация многораундового диалога

Для поддержания контекста разговора необходимо последовательно накапливать сообщения в массиве messages. Каждый новый запрос должен включать всю историю взаимодействия:

messages = [
    {"role": "system", "content": "Ты эксперт по программированию"},
    {"role": "user", "content": "Объясни принцип работы RSA"},
    {"role": "assistant", "content": "RSA — асимметричный криптографический алгоритм..."},
    {"role": "user", "content": "Какие у него слабые места?"}
]

Реализация потокового вывода (Streaming)

Потоковый режим активируется установкой "stream": True. В этом случае сервер возвращает данные в формате Server-Sent Events (SSE), где каждое событие содержит часть сгенерированного текста. Для обработки требуется итерация по строковым чанкам:

data["stream"] = True
response = requests.post(url, headers=headers, json=data, stream=True)

for line in response.iter_lines():
    if line:
        decoded_line = line.decode('utf-8')
        print(decoded_line)

Каждая строка ответа представляет собой JSON-объект, содержащий поле delta.content с фрагментом сгенерированного текста. Поток завершается событием [DONE].

Обработка ошибок и диагностика

При взаимодействии с API могут возникать следующие типичные ошибки:

401 Unauthorized: Неверный или просроченный API-ключ. Требуется проверить корректность ключа и баланс счета.
429 Too Many Requests: Превышены лимиты запросов. Необходимо снизить частоту вызовов или обратиться к документации по тарифам.
500 Internal Server Error: Внутренняя ошибка сервера DeepSeek. Рекомендуется повторить запрос через некоторое время.
JSONDecodeError: Сервер возвращает невалидный JSON, часто из-за временной перегрузки. Следует реализовать повторные попытки (retry logic) с экспоненциальной задержкой.

Сравнение моделей DeepSeek-R1 и DeepSeek-V3

DeepSeek-R1 (reasoner): Специализирована на задачах, требующих расширенного логического вывода и пошаговых рассуждений. Генерирует более длинные цепочки "размышлений", что отражается на времени ответа и объеме выходных токенов.

DeepSeek-V3 (chat): Оптимизирована для диалоговых сценариев общего назначения, обеспечивает быстрые и контекстуально релевантные ответы. Рекомендуется для большинства прикладных задач, не требующих глубокого аналитического вывода.

Выбор модели зависит от конкретной задачи: R1 для сложных аналитических запросов, V3 — для интерактивных чат-интерфейсов и автоматизации рутинных операций.

DeepSeek на русском