Документация DeepSeek API: путеводитель на русском

На чём основана эта страница (важно прочитать)

Сайт документации api-docs.deepseek.com не открывается из нашей сети (его закрывает прокси), поэтому дословного перевода здесь нет и быть не может. Это путеводитель: карта разделов документации и перевод того, что удалось проверить по открытым источникам.

Что проверено и где (дата проверки — 4 октября 2026 года):

• официальный репозиторий deepseek-ai/deepseek-harness (лицензия MIT, коммит от 3 октября 2026) — пакет packages/llm/llm-deepseek: адрес API, имена моделей, параметры размышления, работа с файлами и картинками, классы ошибок;
• официальный репозиторий deepseek-ai/awesome-deepseek-integration — ссылка на платформу и получение ключа;
• урок курса 8.1.1 «OpenAI-совместимые API», где факты из документации собраны ранее со ссылками на её разделы.

Цены, лимиты запросов и точные квоты здесь не приводятся совсем. Они меняются чаще, чем что-либо другое, и проверить их мы сейчас не можем. Смотрите их только на platform.deepseek.com. Любое число на этой странице сверяйте с оригиналом.

Что это за документация и кому она нужна

DeepSeek API — платный облачный доступ к моделям DeepSeek по HTTP. Для курса он интересен тремя вещами:

1. Это самый дешёвый способ попробовать большую модель, которая не поместится на ваши четыре RTX 4080.
2. Документация короткая и инженерная: её можно прочитать целиком за вечер, в отличие от документации OpenAI или Google.
3. В ней описан кэш контекста на диске — это префикс-кэш из ступени 7, включённый у всех по умолчанию, с видимыми в ответе полями. Редкий случай, когда внутренности сервинга видны клиенту.

Документация существует на китайском (/zh-cn/) и английском. Разделы устроены одинаково.

Карта документации

Структура разделов по состоянию на осень 2026 года (названия даны в переводе; точные заголовки смотрите в оглавлении сайта).

Раздел документации	О чём	К какому уроку	Важность для курса
Быстрый старт / Первый вызов API	получить ключ, адрес, первый запрос curl и Python	8.1.1	обязательно
Модели и цены	какие модели доступны, тарифы, скидки	8.1.1	обязательно, но только в оригинале
Рассуждающая модель	режим размышления, поле с цепочкой рассуждений, что нельзя передавать обратно	6.4.2	важно
Кэш контекста на диске	как работает, как видеть попадания в usage	7.1.2	важно
Function Calling	вызов функций, формат описания инструментов	8.3.2	важно
JSON Output	строгий JSON в ответе	8.1.2	полезно
FIM (fill-in-the-middle)	дописывание кода в середину — бета	—	по желанию
Chat Prefix Completion	«продолжи ответ с этой строки» — бета	8.1.2	полезно
Коды ошибок	400, 401, 402, 422, 429, 500, 503	8.1.1	обязательно
Лимиты запросов	что происходит при превышении	8.4.3	полезно
Журнал изменений (News / Updates)	анонсы моделей, отключение старых имён	9.2.1	читайте первым

Почему журнал изменений — первым

Имена моделей у DeepSeek меняются с каждым поколением, и старые отключают. Например, имена deepseek-chat и deepseek-reasoner, которые вы встретите в коде и статьях 2025 года, отключены 24 июля 2026 года, а режим рассуждений теперь включается отдельным параметром. Любой учебник (включая наш) стареет — журнал изменений не стареет.

Два протокола

У DeepSeek два совместимых интерфейса, и выбирать нужно осознанно.

	OpenAI-совместимый	Anthropic-совместимый (Messages)
Корневой адрес	https://api.deepseek.com	https://api.deepseek.com/anthropic
Путь запроса	/chat/completions	/v1/messages
Заголовок с ключом	Authorization: Bearer <ключ>	x-api-key: <ключ>
Чем пользоваться	SDK openai, LangChain, Ollama-совместимые клиенты	SDK Anthropic, агентные каркасы
Когда брать	обычные приложения, перенос кода с OpenAI	работа с блоками содержимого, файлами, вызовами инструментов в агентах

Адреса и пути проверены по README пакета llm-deepseek официального репозитория deepseek-harness: там официальным корнем Messages-интерфейса названо https://api.deepseek.com/anthropic, а к нему добавляются /v1/messages для запросов к модели и /v1/files для файлов. Переопределить корень можно переменной окружения DEEPSEEK_BASE_URL.

Ключ в обоих случаях берётся с platform.deepseek.com и хранится в переменной окружения — по традиции DEEPSEEK_API_KEY.

Модели

На осень 2026 года в документации и в официальном клиенте фигурируют две модели:

Имя в запросе	Что это	Вход	Контекст
deepseek-flash	DeepSeek-V4.1-Flash	текст и изображения	1 млн токенов
deepseek-v4-pro	DeepSeek-V4-Pro	текст	1 млн токенов

(Каталог по умолчанию в пакете llm-deepseek репозитория deepseek-harness, проверено 04.10.2026. Про сами модели — конспект техотчёта V4 и урок 9.2.1.)

Правило, которое не устаревает: актуальный список моделей отдаёт сам сервер. У OpenAI-совместимого интерфейса это client.models.list() в SDK или GET /models.

Режим размышления

С поколения V4 модели DeepSeek по умолчанию сначала рассуждают, потом отвечают. Управление режимом устроено так:

• Выключить размышление. В OpenAI-совместимом запросе — поле "thinking": {"type": "disabled"}. Это расширение DeepSeek, в формате OpenAI такого поля нет: для других провайдеров строку надо убрать.
• Задать усилие. В Messages-интерфейсе усилие рассуждения передаётся как output_config.effort со значениями low, high, max; отдельное значение off клиент превращает в thinking.type: disabled. (Проверено по README пакета llm-deepseek.)
• Температура. В режиме рассуждений temperature игнорируется — это важно помнить, когда вы подбираете разнообразие ответов.
• Цепочка рассуждений в ответе. В OpenAI-совместимом интерфейсе она приходит отдельным полем reasoning_content рядом с content. Не отправляйте её обратно в следующем запросе как часть истории: документация требует передавать только итоговый ответ.

За размышление вы платите

Токены рассуждений — это обычные выходные токены по обычной цене, даже если вы их не показываете пользователю. Поэтому «усилие» — это буквально ручка «качество против денег». Как на этом экономят, разбирается в уроке 6.4.4.

Кэш контекста на диске

Самая поучительная часть документации. DeepSeek кэширует KV-кэшKV-кэшEN KV cache уже обработанных префиксов запросов на дисках (эту задачу решает файловая система 3FS). Клиенту не нужно ничего включать — кэш работает по умолчанию.

Как это видно в ответе: в поле usage приходят prompt_cache_hit_tokens и prompt_cache_miss_tokens — сколько входных токенов попало в кэш и сколько пришлось считать заново. Попадания тарифицируются в разы дешевле промахов (точные цифры — на странице цен).

Главное правило дизайна промптов, которое отсюда следует:

1. Статичное — в начало. Системный промпт, инструкции, примеры, большие документы — всё, что не меняется от запроса к запросу.

2. Изменчивое — в конец. Текущий вопрос пользователя, время, идентификаторы запроса.

3. Никогда не ставьте в начало то, что меняется каждый раз. Текущее время с секундами в первой строке системного промпта обнуляет кэш полностью: совпадение считается с самого первого токена.

4. Проверяйте по usage. Если prompt_cache_hit_tokens всегда равен нулю — где-то в начале промпта что-то «дышит».

Эта же логика работает у локальных серверов (vLLM, SGLang) — там она называется префикс-кэшем (урок 7.1.2).

Файлы и картинки

В Messages-интерфейсе есть Files API (/v1/files): файл загружается один раз и дальше передаётся в сообщениях по идентификатору, а не вставляется в каждый запрос в base64. По README официального клиента:

• запросы с идентификаторами файлов помечаются заголовком anthropic-beta: files-api-2025-04-14;
• у загрузки задаётся срок жизни (в клиенте DeepSeek по умолчанию семь дней), и идентификатор переиспользуется, пока не истечёт;
• если файловый путь не сработал, клиент пересобирает запрос с картинкой в base64 — это запасной вариант, а не основной.

Как считаются токены картинки (по тому же README): изображение разбивается на участки по 14 пикселей, с понижением в 3 раза по каждой оси, не более 1024 токенов на картинку. Отсюда, например, квадратная картинка передаётся с размером до 1302×1302 пикселей. Смысл для вас простой: картинки стоят токенов, и класть в контекст скриншоты «на всякий случай» — дорого.

Ошибки и повторы

Коды, которые отдаёт API, и что с ними делать (сверено с уроком 8.1.1 и классами ошибок официального клиента):

Код	Что значит	Что делать
400	неверный запрос: лишнее поле, слишком длинный контекст	исправить запрос; повтор не поможет
401 / 403	неверный или отозванный ключ	проверить переменную окружения
402	закончились деньги на балансе	пополнить баланс
422	неверные значения параметров	исправить параметры
429	превышен лимит запросов	подождать и повторить с увеличением паузы
500 / 503	сбой или перегрузка сервера	подождать и повторить

Официальный клиент DeepSeek различает классы ошибок AUTH, QUOTA, RATE_LIMIT, CONTEXT_WINDOW_EXCEEDED, INVALID_REQUEST, SERVER, а отдельно — обрывы соединения и истечение времени ожидания потока. Полезный практический вывод: ошибку «кончился контекст» надо отличать от «кончились деньги» — лечатся они по-разному, а в наивном коде обе выглядят как «запрос не прошёл».

Повторять нужно с экспоненциальной задержкой и случайным разбросом; в SDK openai за это отвечают параметры max_retries и timeout у клиента.

Первый запрос

Код ниже — обычный OpenAI-совместимый вызов; он же разбирается подробно в уроке 8.1.1. Проверьте имя модели по журналу изменений, прежде чем запускать.

import os

from openai import OpenAI  # pip install openai

client = OpenAI(
    base_url="https://api.deepseek.com",          # OpenAI-совместимый корень
    api_key=os.environ["DEEPSEEK_API_KEY"],       # ключ только из переменной окружения
    max_retries=3,                                # повторы при 429 и 5xx
    timeout=60,
)

resp = client.chat.completions.create(
    model="deepseek-flash",                       # сверьте с актуальным списком моделей
    messages=[
        {"role": "system", "content": "Ты — лаконичный помощник. Отвечай по-русски."},
        {"role": "user", "content": "Что такое KV-кэш? Одним предложением."},
    ],
    extra_body={"thinking": {"type": "disabled"}},  # расширение DeepSeek: без размышления
)

print(resp.choices[0].message.content)
print(resp.usage)   # здесь и смотрите prompt_cache_hit_tokens / prompt_cache_miss_tokens

extra_body нужен потому, что поле thinking — расширение DeepSeek, которого нет в схеме SDK OpenAI. Для локальной модели через Ollama достаточно поменять base_url на http://localhost:11434/v1, ключ на любую строку и убрать extra_body.

Как учиться по этой документации

1. Прочитайте журнал изменений за последние полгода — поймёте, какие имена моделей живы.

2. Пройдите «первый вызов» и сразу распечатайте usage целиком: вы увидите, как устроен учёт токенов и кэша.

3. Поставьте эксперимент с кэшем. Отправьте один и тот же длинный системный промпт дважды и сравните prompt_cache_hit_tokens. Потом добавьте в начало промпта текущее время и повторите — попадания исчезнут.

4. Сравните с локальной моделью. Тот же запрос к Ollama и к API: разница в коде — три строки. Это главный практический вывод ступени 8.

5. Function calling читайте вместе с уроком 8.3.2: формат описания инструментов тот же, что у OpenAI, поэтому код агента переносится почти без правок.

Деньги и безопасность

• Ключ, один раз попавший в публичный репозиторий, считайте украденным: GitHub постоянно сканируют боты. Храните ключи в переменных окружения или в .env, добавленном в .gitignore.
• Поставьте себе лимит расходов в личном кабинете, прежде чем запускать цикл в агенте: агент с инструментами легко делает сотни вызовов.
• Для учебных задач курса платный API не обязателен: базовый путь всюду выполним на локальной модели.

Что почитать рядом

• Обзор системы инференса DeepSeek-V3/R1 — что происходит на той стороне, когда вы отправляете запрос: разделение prefill и decode, параллелизм экспертов, экономика сервиса.
• 3FS: проектные заметки — та самая файловая система, на которой лежит кэш контекста.
• Конспект техотчёта V4 — что за модель отвечает на ваш запрос.
• Обзор материалов DeepSeek — в каком порядке читать всё остальное.

Словарик

EN	RU
API key	ключ API
base URL	корневой адрес (базовый URL)
OpenAI-compatible API	OpenAI-совместимый API
Messages API	интерфейс сообщений (Anthropic-совместимый)
context caching (в китайской версии — «кэш контекста на жёстком диске»)	кэш контекста (на диске)
cache hit / miss	попадание / промах кэша
reasoning content	содержимое рассуждения
reasoning effort	усилие рассуждения
function calling	вызов функций (инструментов)
fill-in-the-middle (FIM)	дописывание в середину
chat prefix completion	продолжение ответа с заданного начала
rate limit	ограничение частоты запросов
exponential backoff	экспоненциальная задержка повторов