Инструменты и ресурсы

API и инструменты моделей DeepSeek: модели, параметры и веб-поиск

Справка по DeepSeek API: модели flash и pro, ключевые параметры запроса, тарификация токенов и поиска, схема ответа с источниками и чек-лист перед запуском.

Редакция DeepMe
· Обновлено · 8 мин чтения
Приложение, языковая модель и веб-поиск, соединённые через API

DeepSeek API — программный доступ к языковым моделям DeepSeek: приложение отправляет запрос на сервер, получает ответ и само решает, что с ним делать. Возможности не сводятся к генерации текста: в документации описаны вызов инструментов, включая серверный веб-поиск и чтение страниц, а также отдельные Search и Fetch API. Ниже — разбор моделей, параметров, тарификации и рабочая схема «поиск → контекст → ответ с источниками».

Названия моделей, цены и лимиты у провайдера меняются, и сам провайдер оговаривает право их пересматривать. Всё фактическое ниже опирается на официальную документацию DeepSeek; перед запуском сверяйте значения на странице тарифов на дату публикации.

Чем API отличается от чата

Чат в браузере — готовый интерфейс с историей диалога и настройками по умолчанию. API — конструктор: вы формируете входные сообщения, выбираете модель, задаёте параметры и обрабатываете ответ. Отсюда два следствия.

  • Контроль над контекстом. API не хранит состояние: ответы и диалоги на сервере не сохраняются. Для многошаговой беседы историю нужно отправлять заново при каждом запросе.
  • Ответственность за безопасность. Ключ — секрет. Если он попадёт в клиентский JavaScript, он окажется в исходниках страницы и в сетевых запросах браузера, то есть станет доступен посторонним.

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

Модели и критерии выбора

В документации указаны два имени модели: deepseek-flash и deepseek-v4-pro. Устаревшие имена вроде deepseek-v4-flash и deepseek-v4-flash-vision-exp ещё принимаются, но соответствующие модели выведены: запросы обслуживает DeepSeek-V4.1-Flash-1017 и тарифицирует по цене Flash. Это наглядная причина не брать имя модели из старого туториала.

Обе модели поддерживают режимы с рассуждением и без него, JSON-вывод, вызов инструментов, Responses API и Anthropic-совместимый формат. Различие существеннее в инструментах: серверный web_search доступен только deepseek-v4-pro, тогда как deepseek_web_search и deepseek_read_url — это отдельные веб-инструменты, которые нельзя объявлять вместе с web_search.

КритерийКогда критиченЧто проверить
Задержка ответаЧат, автодополнение, ботыЗамер на ваших типичных запросах
Стоимость токеновБольшие объёмы, длинный контекстЦены за 1M входных и выходных токенов, пиковые и непиковые ставки
Длина контекстаДокументы, RAG, длинные диалогиЛимит модели и фактический размер промпта
Структурированный выводПарсинг ответа кодомJSON-режим и схема ответа
Серверный поискОтветы о свежих событияхДоступность web_search у выбранной модели

Практическое правило: начинайте с более быстрой и дешёвой модели, а на сложные случаи переключайтесь по результатам собственных замеров.

Ключевые параметры запроса

Параметры определяют не только содержание ответа, но и счёт за него. Полные таблицы совместимости — в справочнике Responses API; ниже смысл основных полей, подтверждённых документацией.

  • model — имя модели. Опечатка или устаревшее имя дают ошибку либо неожиданную тарификацию.
  • input — строка (одно сообщение пользователя) или список элементов: сообщения, результаты вызовов функций, элементы рассуждения, веб-поиска. Хотя бы одно из полей input и instructions обязательно.
  • instructions — системная инструкция, вставляется первым системным сообщением.
  • thinking — режим рассуждения: none выключает его, low, high, max включают с разной глубиной. Если не задан, действует поведение модели по умолчанию.
  • temperature — от 0 до 2, выше значение — случайнее вывод; в режиме рассуждения не действует. Документация даёт ориентиры: 0.0 для кода и математики, 1.0 для анализа данных, 1.3 для перевода и обычной беседы, 1.5 для творческого письма.
  • max_output_tokens — верхняя граница сгенерированных токенов, включая рассуждение.
  • stream — потоковая выдача событиями; финальное событие — response.completed, response.incomplete или response.failed.
  • tools и tool_choice — список доступных инструментов и правило выбора: none, auto или required.

Вывод: параметры — часть бюджета и надёжности, а не косметика. Меняйте их по одному и фиксируйте, что изменилось.

Веб-поиск через API

Знания модели ограничены датой обучения. Для вопросов о свежих событиях, ценах или изменениях в документации нужен внешний источник. В документации описан эндпоинт /v1/tools/search: он принимает поисковый запрос и возвращает ранжированный список результатов.

Параметры запроса:

  • поисковая строка длиной от 1 до 128 символов, поддерживаются операторы site:, -site: и фразы в кавычках;
  • число результатов от 1 до 50, по умолчанию 10;
  • исходный вопрос пользователя — помогает лучше понять запрос;
  • необязательный IP для локализации выдачи;
  • флаг возврата содержимого страницы, по умолчанию выключен.

В ответе есть оценка релевантности от 0 до 3 (значения от 1,5 считаются качественными), короткое и длинное резюме, содержимое страницы, время публикации в UTC и уровень авторитетности источника от 0 до 4, где 3 и выше — высокоавторитетные, а −1 означает «неизвестно». Это даёт основу для отбора: например, отбрасывать результаты с низкой оценкой и без даты публикации.

Отдельно о тарификации: поиск и загрузка страниц оплачиваются за использование — и при прямом вызове Search и Fetch API, и когда модель обращается к ним через инструменты. «Бесплатного» веб-поиска внутри запроса нет.

Схема собственного RAG

Нативный поиск через API — не единственный путь. Цепочку можно построить самостоятельно:

  1. Сформулировать поисковый запрос из вопроса пользователя.
  2. Получить результаты и отобрать источники по оценке релевантности и авторитетности.
  3. Извлечь текст страниц и уложить его в лимит контекста.
  4. Передать модели вопрос и фрагменты источников с указанием, откуда взят каждый.
  5. Потребовать ответ со ссылками на фрагменты и явной пометкой, если данных не хватило.
КритерийНативный поиск через APIСобственный RAG
Скорость запускаВыше: один вызов инструментаНиже: нужна своя логика
Контроль над источникамиОграничен правилами провайдераПолный: свои фильтры и белый список
СтоимостьОплата за использование поискаЗависит от выбранного поискового сервиса
ПрозрачностьЗависит от возвращаемых полейМаксимальная: видно каждый шаг

Сквозной пример: бот с веб-поиском

Ниже — схема шагов, а не готовый к запуску код. Конкретные имена полей и адреса сверяйте с документацией.

1. Пользователь пишет боту вопрос.
2. Сервер формирует поисковый запрос (1–128 символов).
3. Сервер вызывает поисковый API и получает список результатов.
4. Сервер отбирает 3–5 источников с высокой оценкой релевантности.
5. Сервер собирает контекст: вопрос + фрагменты + пометки об источниках.
6. Сервер вызывает модель DeepSeek с системной инструкцией:
   «Отвечай только по фрагментам. Если данных нет — скажи об этом.
    В конце перечисли использованные источники».
7. Ответ проходит проверку длины и разметки, затем уходит пользователю.
8. В журнал пишутся: запрос, число токенов, задержка, статус.

Почему так: шаг 6 снижает риск выдуманных фактов, шаг 7 защищает от слишком длинных сообщений, шаг 8 даёт данные для расчёта стоимости и поиска узких мест. Ключи хранятся только на сервере, в переменных окружения.

Учебный пример (вымышленные числа, не результат исследования). Допустим, бот за сутки обработал 200 вопросов, и в среднем на запрос ушло 4000 входных токенов (вопрос, фрагменты страниц, инструкция) и 500 выходных, а поиск вызывался один раз. Тогда расход токенов за сутки — 200 × 4000 = 800 000 входных и 200 × 500 = 100 000 выходных, плюс 200 обращений к поиску. Подставив актуальные цены за 1M токенов и цену за обращение, вы получите оценку бюджета. Такой расчёт показывает главное: входные токены из найденных страниц обычно весят больше выходных, поэтому отбор источников экономит деньги не меньше, чем выбор модели.

Расчёт стоимости и лимиты

По документации цены указаны за 1M токенов, а оплата считается по сумме входных и выходных токенов модели. Поиск и загрузка страниц тарифицируются отдельно, за использование. Также указано, что непиковые ставки вдвое ниже пиковых, а пиковые часы — 01:00–04:00 и 06:00–10:00 UTC по будням, кроме китайских государственных праздников; всё остальное время, включая выходные и праздники целиком, — непиковое. Эти значения сверяйте на странице тарифов на дату публикации: провайдер оговаривает право их менять.

Проверяемая формула для одного запроса с поиском:

стоимость = (входные_токены / 1_000_000 × цена_входа)
          + (выходные_токены / 1_000_000 × цена_выхода)
          + (число_обращений_к_поиску × цена_за_обращение)

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

Типичные ошибки и безопасность ключа

Разберём одну ошибку пошагово: ключ оказался в клиентском JavaScript.

  1. Обнаружение. Ключ виден в исходниках страницы или в сетевых запросах браузера.
  2. Немедленные действия. Отозвать ключ и выпустить новый; проверить журналы на необычные запросы и расход.
  3. Исправление. Перенести вызовы на серверный endpoint, который проверяет пользователя и сам обращается к API.
  4. Профилактика. Хранить секреты в переменных окружения, ограничить права ключа, настроить оповещения о расходе.

Другие частые проблемы: превышение лимита контекста при большом RAG-наборе, неверный базовый адрес при использовании совместимого клиента и отсутствие повторных попыток с паузой при временных ошибках. Отдельно стоит помнить, что модель не всегда генерирует валидный JSON в аргументах вызова функции — аргументы нужно проверять в коде до вызова. Каждую из этих проблем лучше закрывать до продакшена, а не после инцидента.

Чек-лист перед запуском

  • Имя модели и цены сверены с официальной страницей тарифов на дату запуска.
  • Ключи только на сервере; настроена ротация и оповещения о расходе.
  • Задан лимит выходных токенов и проверено поведение при обрыве ответа.
  • Есть таймауты и повторные попытки с паузой.
  • Логируются токены, задержка и статус — иначе стоимость не посчитать.
  • Для ответов с поиском сохраняются источники и дата получения данных.
  • Проверено поведение при пустой выдаче поиска: модель должна сказать, что данных нет.

Смежные темы: обзор API для интеграции ИИ и библиотеки Python для работы с ИИ. Официальные источники: страница моделей и цен DeepSeek и справочник Search API.

Источники