Само подключение DeepSeek API несложное. Застрять чаще всего можно на трёх вещах: к какой платформе относится ключ, полностью ли указан Base URL и актуально ли имя модели. Многие случаи «не работает» связаны не с возможностями модели, а с рассогласованием учётных данных и адреса.
Ниже по порядку: регистрация, пополнение, создание ключа, первый вызов curl и Python, затем потоковый вывод, режим thinking, max_tokens и типичные ошибки. Если пройти всё по шагам, цепочка подключения заработает.
Примечание: DeepSeek — товарный знак его правообладателя; статья не связана с DeepSeek официально. Имена моделей, параметры и лимиты могут меняться; примеры отражают распространённую ситуацию на октябрь 2026 года. Приоритет — официальная документация и страница тарифов.
1. Перед подключением: четыре объекта
Сбой подключения чаще вызван не моделью, а несогласованностью четырёх объектов:
| Объект | Назначение | Где чаще всего ошибаются |
|---|---|---|
| Аккаунт | Определяет баланс, счёт и принадлежность ключа | Ключ платформы A ставят к адресу платформы B |
| API-ключ | Удостоверение личности | При копировании попали пробел, перевод строки или кавычка |
| Base URL | Куда отправляется запрос | Пропущен /v1 или смешаны официальный адрес и адрес шлюза |
| Имя модели | Поле model в запросе |
Используется устаревшее имя из старой статьи |
Простое правило: ключ и Base URL должны быть парой. Официальный ключ — только с официальным входом, ключ шлюза — только со входом шлюза; смешение обычно даёт 401.
2. Регистрация, пополнение, создание ключа
На примере официальной открытой платформы:
- Откройте открытую платформу DeepSeek, зарегистрируйтесь и войдите.
- Пройдите необходимую проверку по подсказкам страницы и перейдите к пополнению.
- Сначала пополните небольшую сумму, убедитесь в зачислении и только потом запускайте пакетные задачи.
- Перейдите на страницу API Keys, создайте ключ и укажите назначение, например
deepseek-testилиdeepseek-prod. - Сразу сохраните ключ в менеджер паролей или серверную переменную окружения: после закрытия страницы полное значение обычно больше не показывается.
- Заведите отдельные ключи для теста и production и настройте напоминания о бюджете и расходе.
При использовании ZSQH AI Gateway порядок похож: создайте аккаунт на странице регистрации, в консоли создайте ключ и пополните баланс, затем вызывайте API OpenAI-совместимым способом, описанным ниже. Не используйте один и тот же ключ на обеих сторонах, иначе при сбое трудно понять, дело в балансе, лимите или конфигурации.
3. Base URL и имя модели: сначала проверьте, потом пишите код
Официальная документация указывает OpenAI-совместимый вход https://api.deepseek.com с путём чата /chat/completions. В некоторых старых руководствах встречается https://api.deepseek.com/v1; доступность сверяйте с текущей документацией. Если не уверены, сначала пройдите запрос по официальному примеру.
| Параметр | Официальное подключение | ZSQH AI Gateway |
|---|---|---|
| Base URL | https://api.deepseek.com |
https://ai.zhongshangqihang.com/v1 |
| Путь чата | /chat/completions |
/v1/chat/completions |
| Источник ключа | Официальная платформа | Консоль шлюза |
| Имя модели | По официальной документации | По странице тарифов |
| Кому подходит | Только DeepSeek, прямой доступ и оплата работают | Нужны единый вход, несколько моделей или счета в юанях |
По состоянию на октябрь 2026 года официальная документация перечисляет модели deepseek-flash и deepseek-v4-pro; имена deepseek-chat и deepseek-reasoner из старых статей могут быть уже недоступны. Не вписывайте имя модели по памяти — сверяйтесь с документацией или страницей тарифов перед вызовом.
4. Первый curl: минимальный запрос
Сначала отключите thinking, чтобы уменьшить число переменных. Пример для официального входа:
export DEEPSEEK_API_KEY="sk-ваш-ключ"
curl "https://api.deepseek.com/chat/completions" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-flash",
"messages": [{"role": "user", "content": "Ответь только OK"}],
"thinking": {"type": "disabled"},
"max_tokens": 32
}'
Если вернулся 200 и в choices[0].message.content есть текст, значит ключ, Base URL и имя модели верны. При использовании шлюза замените URL на https://ai.zhongshangqihang.com/v1/chat/completions и возьмите ключ шлюза.
Учтите: thinking — расширенный параметр DeepSeek, его поддерживают не все OpenAI-совместимые сервисы. Если шлюз его не поддерживает, уберите поле или используйте аналог из документации шлюза.
5. Первый вызов из Python: OpenAI SDK
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DEEPSEEK_API_KEY"],
base_url="https://api.deepseek.com", # для шлюза: https://ai.zhongshangqihang.com/v1
)
resp = client.chat.completions.create(
model="deepseek-flash",
messages=[
{"role": "system", "content": "Ты технический ассистент, отвечай кратко."},
{"role": "user", "content": "Объясни в трёх предложениях, что такое векторная база данных."},
],
max_tokens=512,
extra_body={"thinking": {"type": "disabled"}},
)
print(resp.choices[0].message.content)
print(resp.usage)
OpenAI SDK не знает поле thinking, поэтому его передают через extra_body. После успешного вызова посмотрите usage: сколько токенов на входе и выходе, возвращается ли попадание в кэш, считается ли reasoning отдельно. Эти данные полезнее субъективного «быстро или нет» для настройки стоимости и тайм-аутов.
6. Потоковый вывод и reasoning_content
Thinking включён по умолчанию с уровнем high. При включении в ответе появляется reasoning_content на одном уровне с итоговым content; в потоковом ответе он приходит по частям в delta.reasoning_content.
stream = client.chat.completions.create(
model="deepseek-flash",
messages=[{"role": "user", "content": "Напиши пример Python для чтения CSV"}],
stream=True,
max_tokens=4096,
reasoning_effort="high",
extra_body={"thinking": {"type": "enabled"}},
)
reasoning, answer = [], []
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
if getattr(delta, "reasoning_content", None):
reasoning.append(delta.reasoning_content)
if delta.content:
answer.append(delta.content)
print("Размышления:", "".join(reasoning))
print("Ответ:", "".join(answer))
В многошаговом диалоге при передаче tools предыдущий reasoning_content нужно вернуть полностью, иначе возможен 400; без tools его можно не передавать — сервер проигнорирует. Для конечных пользователей размышления лучше сворачивать, а не показывать полностью по умолчанию.
7. Как настроить max_tokens, temperature и thinking
| Задача | thinking | Рекомендуемая отправная точка | Пояснение |
|---|---|---|---|
| Проверка связи | Выключен | max_tokens 32–128 | Нужен лишь короткий ответ |
| Классификация, извлечение | Выключен | 256–1024 | Структурированный вывод, меньше расходов на размышление |
| Поддержка, тексты | Включён | 1024–4096 | Уровень effort подбирается по результату |
| Код, сложные рассуждения | Включён | От 4096 | Оставьте запас на размышления |
Текущая документация указывает контекст 1M токенов и диапазон max_tokens от 1 до 384K; без указания значения по умолчанию 8K для без thinking и 64K для thinking, а при reasoning_effort = max — 128K. Эти числа могут меняться, сверяйтесь с документацией.
В режиме thinking temperature, presence_penalty и frequency_penalty не действуют: их изменение не вызовет ошибку, но и не повлияет на результат. max_tokens тоже нельзя занижать: размышления занимают бюджет вывода, и при слишком малом лимите ответ обрежется, не дойдя до основного текста.
8. Как разбирать 401, 402, 429 и тайм-ауты
| Симптом | Частая причина | Что делать |
|---|---|---|
| 401 | Неверный ключ, нет Bearer, ключ и Base URL от разных платформ | Скопируйте ключ заново, проверьте заголовок и соответствие входа |
| 402 | Недостаточно средств | Пополните баланс и повторите, сначала проверьте баланс, потом код |
| 429 | Слишком частые запросы, превышены параллелизм или QPS | Снизьте параллелизм, используйте экспоненциальную задержку, разделите ключи по проектам |
| 400/422 | Некорректные параметры, имя модели или контекст | Читайте сообщение, сверьте имя модели и max_tokens |
| Тайм-аут | Сеть, длинный вывод, время thinking | Настройте отдельно тайм-аут соединения и чтения, ограничьте вывод |
| 500/503 | Ошибка или перегрузка upstream | Небольшая пауза и повтор с задержкой |
Лимит параллелизма 429 считается по аккаунту, а не делится поровну между ключами. Несколько ключей одного аккаунта используют общую квоту, поэтому «создать побольше ключей» не обойдёт ограничение. Документация также отмечает: если генерация не началась в течение 10 минут, соединение разрывается; клиент должен распознавать это и повторять запрос.
9. Безопасность ключа: минимум пять действий перед запуском
- Храните ключ только в серверных переменных окружения или менеджере секретов, не во фронтенде, репозитории и журналах.
- Для теста, предпродакшена и production — отдельные ключи, чтобы быстро локализовать и отключить проблему.
- Настройте напоминание о балансе или лимит расходов, чтобы остановить потери при аномальных вызовах.
- В журналах фиксируйте только префикс или отпечаток ключа, не полное значение.
- При смене персонала или подозрении на утечку сразу ротируйте ключ и проверяйте недавний расход.
10. Переход с официального входа на шлюз: меняются два места
При миграции сначала измените base_url и api_key, имя модели заново сверьте на странице тарифов шлюза, остальное тело запроса по возможности не трогайте. Сравните вывод, время и usage на одном наборе реальных промптов, наблюдайте 3–7 дней и только потом переводите production. Сохраните официальное подключение как резервный канал для быстрого отката.
Если нужен единый вход или единый счёт по нескольким моделям, создайте тестовый ключ в ZSQH AI Gateway; цены и доступные модели — на странице тарифов.
Читайте также:
Частые вопросы
Нужно ли добавлять /v1 к Base URL?
Ориентируйтесь на текущий пример официальной документации. Официальный OpenAI-совместимый вход записан как https://api.deepseek.com, путь чата — /chat/completions; шлюзы обычно используют префикс /v1. Не угадывайте по старым руководствам — один раз проверьте полный адрес через curl.
401 — это неверный ключ или нехватка средств?
401 — сбой аутентификации: проверьте правильность ключа, наличие Bearer и принадлежность ключа и Base URL одной платформе. Нехватка средств обычно возвращает 402; не путайте эти случаи.
Включать ли thinking при первом вызове?
Рекомендуется сначала выключить и подтвердить связь самым коротким запросом. Убедившись в ключе, адресе и имени модели, включайте по необходимости и начинайте с невысокого reasoning_effort.
Какое значение max_tokens выбрать?
Сначала задайте достаточное для задачи, после успешного запуска уточните. Для классификации и извлечения можно начать с нескольких сотен, для длинных текстов и кода оставить несколько тысяч; в режиме thinking нужен запас на размышления, иначе основной текст обрежется.
Можно ли использовать официальный ключ с адресом шлюза?
Нет. Официальный ключ соответствует только официальному входу, ключ шлюза — только входу шлюза; смешение обычно даёт 401. При смене входа ключ и Base URL меняются парой.
