DeepSeek API: первый запрос и проверка интеграции

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

Где API пригодится

Допустим, в рабочую очередь поступают заявки, и оператору нужно распределять их между отделами. В обычном чате он копирует описание, ждёт ответ и переносит метку обратно. API позволяет встроить предложение метки в саму очередь. Исходная заявка остаётся видимой, а оператор подтверждает или меняет вариант. Для первого пилота этого достаточно. Отправку действий клиентам и изменение прав можно оставить за людьми и правилами приложения.

До подключения определите границу результата. Для заявки это категория из списка и короткое объяснение. Для отчёта — черновик заметки с указанием исходной строки. Для карточки — извлечение нескольких полей с возможностью вернуть «не найдено». Чем уже задача, тем проще проверить, зачем ей нужен внешний вызов. Заранее решите, что происходит, если ответ отсутствует или его нельзя разобрать.

Что подготовить для первого вызова

Параметр Где проверить
Ключ доступа Кабинет платформы DeepSeek
Базовый URL Раздел первого вызова в официальных документах
Идентификатор модели Актуальный список в документации
Тайм-аут Настройки клиента и ожидания пользователя
Тестовый вход Короткий нейтральный пример с известным ответом

В документации первого вызова показан интерфейс, совместимый с форматом OpenAI. Совместимость здесь относится к запросу и клиентской библиотеке. Ключ получают на платформе DeepSeek, а базовый адрес задаётся отдельно. Проверьте, что используете токен именно того провайдера, куда отправляете запрос.

Для пробного вызова достаточно выполнить один короткий запрос. Возьмите идентификатор модели из актуального списка. Например, документация указывает deepseek-flash в примере настройки. Перед постоянным запуском зафиксируйте модель в конфигурации и запишите условия, при которых её можно поменять.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
    timeout=30.0,
    max_retries=0,
)
response = client.chat.completions.create(
    model="deepseek-flash",
    messages=[
        {"role": "system", "content": "Отвечай одним коротким предложением."},
        {"role": "user", "content": "Назови следующий день после понедельника."},
    ],
)
print(response.choices[0].message.content)
print(response.usage)

Установите библиотеку openai в среду приложения и задайте переменную DEEPSEEK_API_KEY средствами вашей среды. Не добавляйте значение в код и файл, который попадёт в общий репозиторий. В первом примере отключены автоматические повторные попытки, чтобы увидеть исходную ошибку сразу. Для боевого клиента политику повторов лучше установить после проверки типовых сбоев.

Как использовать ответ в интеграции

Ответ модели удобнее принимать в узкий контракт. Например, верните категорию из набора «доступ», «отчёт», «оплата», «другое». Сравните результат с разрешённым списком на стороне программы. Если в ответе появился новый вариант, оставьте заявку в ручной очереди. Даже если пояснение выглядит разумным, вы сможете избежать ошибки маршрутизации и сохранить список нестандартных примеров для следующего теста.

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

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

Что проверить перед запуском

  1. Отправьте маленький проверочный запрос и сохраните технический результат. Используйте понятную фразу, которую легко отличить от ошибки сервера.
  2. Проверьте несколько реальных примеров после удаления лишних данных. Добавьте один простой запрос, один спорный и один неполный.
  3. Отключите сеть в тестовой среде или подставьте тестовый транспорт с ответом об ошибке. Интерфейс должен показать, что задача осталась доступна для ручной обработки.
  4. Проверьте ограничения по времени. Для фоновой обработки важна видимость очереди, а для интерактивного экрана — предсказуемое время ожидания.
  5. Укажите, кто может сменить модель и кто принимает решение убрать подсказки при сбое. Пройдите этот сценарий до интеграции с рабочей очередью.

Если приложение обрабатывает несколько документов подряд, запускайте пилот на небольшом пакете. Сверяйте результаты с эталоном и отмечайте расход по каждому запросу. В длинном входе часто есть повторяющиеся заголовки, служебная разметка и архивные комментарии. Сократите источник по правилам задачи, прежде чем думать об увеличении лимитов. Например, для категории заявки обычно хватает заголовка и последнего сообщения. История полезна, если от неё зависит риск дублирования.

Как подготовить набор проверки

Соберите небольшой набор входов из одной рабочей очереди. Подойдёт тестовая копия без клиентских данных. Оставьте каждое сообщение в виде, в котором его увидит программа: с заголовком, разделителями и пустыми полями. Для ожидаемого ответа запишите категорию и короткое объяснение, почему она подходит. Если два сотрудника выбирают разные категории, обсудите правило до запуска. Модель не исправит неоднозначный маршрут, который уже существует внутри отдела.

Начните с вопроса о доступе к закрытому разделу. Затем добавьте обращение, где человек просит изменить тариф и сообщает об ошибке интерфейса. Для второго случая полезно вернуть признак ручной проверки. Третий пример пусть состоит из одного слова вроде «помогите». Он проверит, что приложение умеет сохранить заявку без догадки. После каждого изменения инструкции прогоните все три ситуации и сравните результаты.

Как считать расход на пробе

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

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

Как изменить модель без сюрпризов

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

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

Где ИИ ошибается

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

Возвращает уверенный ответ на двусмысленный запрос. Две жалобы могут подходить к разным отделам. Заложите состояние «ручная проверка» и примеры, когда оно ожидается.

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

Неверно объясняет сбой. Если один вызов не прошёл, модель может списать его на ключ. Смотрите исходный HTTP-код и официальную расшифровку ошибок. Например, ошибка авторизации требует проверить параметры доступа, а временный сбой сервера — отдельной политики повторов.

Что делать дальше

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

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

Как сделать первый вызов DeepSeek API?

Получите ключ DeepSeek, задайте базовый адрес и выберите модель из текущей документации. Начните с короткого нейтрального запроса.

Разобрать свою задачу с преподавателем

На личном занятии можно повторить приём на своих материалах.

Посмотреть формат занятий

Обучение команд и внедрение ИИ

Ярослав Сажнев
Ярослав Сажнев — преподаватель ИИ в РАНХиГС, внедрение ИИ в компании. Подробнее об авторе