DeepSeek API: JSON-ответ и валидация Pydantic

Короткий ответ: JSON от модели — это входные данные

Относитесь к ответу модели так же, как к JSON из внешнего webhook. Даже когда запрос просит строгую структуру, приложение не должно использовать поле для SQL, доступа, платежа или маршрута без проверки. Первое ограничение — размер и формат: backend принимает только ожидаемый фрагмент, отбрасывает пустой ответ и не пытается угадать смысл произвольного текста. Второе — Pydantic-модель с обязательными полями, enum, лимитами длины и запретом лишних ключей. Третье — domain validation, которая проверяет права, состояние объекта и связь с tenant.

Не выдавайте совместимость одного маршрута за гарантию структурированного вывода для всех моделей. Возможности могут различаться по model ID, версии, endpoint и договорённости. Перед production проверьте актуальный каталог RussiaAPI и выполните обезличенный тестовый запрос. Если ответ не соответствует схеме, возвращайте контролируемый статус invalid_model_output и сохраняйте минимальную диагностическую запись: request_id приложения, версия схемы, код ошибки и длина ответа. Не логируйте Authorization, ключ, полный prompt или пользовательские данные ради одной ошибки парсинга.

Сначала опишите контракт результата

Хорошая Pydantic-модель описывает именно то, что нужно следующему шагу. Если приложению требуется классификация обращения, достаточно category, confidence в допустимом диапазоне и короткого rationale с лимитом длины. Не добавляйте универсальное поле command или свободный URL «на всякий случай». Чем уже контракт, тем проще увидеть изменение поведения модели и тем меньше риск, что неожиданный ключ начнёт управлять системой. Отдельно версионируйте schema_version: новый набор полей вводят рядом со старым, а не молча меняют смысл существующего поля.

Демонстрационный пример не использует реальный model ID и не утверждает, что конкретный endpoint обязательно вернёт JSON. Он показывает защиту приложения после получения текстового фрагмента. Если ваш маршрут поддерживает документированный режим структурированного вывода, подтвердите поля в текущей документации и всё равно оставьте серверную валидацию. Если режима нет, используйте явный договор: модель предлагает данные, Pydantic проверяет форму, а бизнес-слой решает, можно ли применять результат.

Разделите парсинг, schema и бизнес-проверку

Парсинг отвечает только на вопрос, является ли фрагмент корректным JSON. Pydantic отвечает, соответствует ли объект форме: типам, enum, диапазонам, обязательным полям и отсутствию лишних ключей. Бизнес-проверка отвечает на вопрос, разрешено ли действие: принадлежит ли ticket текущему tenant, можно ли изменить его статус и есть ли подтверждение пользователя. Смешивание этих уровней приводит к опасному shortcut: разработчик видит валидный JSON и считает его разрешением. Валидный JSON никогда не заменяет аутентификацию и серверную политику.

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

Обрабатывайте ошибки предсказуемо и без «лечения» ответа

Не исправляйте произвольный JSON регулярным выражением в production, если это меняет смысл результата. Допустим только прозрачный, тестируемый слой извлечения, когда контракт явно определяет контейнер; всё остальное отправляйте в безопасный отказ или ручную проверку. Пользователь получает нейтральное сообщение о невозможности обработать ответ, а наблюдаемость — reason code, версию схемы и request_id. Так команда отличает форматную ошибку от изменения модели, не сохраняя содержимое диалога.

Соберите негативные fixtures: массив вместо объекта, неизвестная категория, лишний ключ, очень длинная строка, неверный Unicode, пустой ответ и JSON с чужим идентификатором. Проверяйте, что Pydantic их отклоняет, а handler не вызывает действие. Добавьте контрактный тест при смене SDK, base URL или model ID. Результаты теста относятся к вашему набору данных и времени запуска; они не доказывают постоянную точность, доступность или безопасность внешней модели.

Подключайте только после server-side smoke test

Создайте отдельный тестовый маршрут с синтетическим входом, allowlist-ом ожидаемых model ID и ограничением частоты. Ключ RussiaAPI хранится в окружении backend, а браузер вызывает только ваш аутентифицированный endpoint. До rollout проверьте, что ответ схемы, JSON-LD статьи и диагностические логи не содержат секретов. При неизвестной модели, невалидной конфигурации или недоступном счётчике откажите безопасно, а не подставляйте неявный provider или открытый ключ пользователя.

RussiaAPI не является официальным сервисом DeepSeek и статья не обещает полную OpenAI-совместимость, JSON-режим, цену или доступность конкретной модели. Начните с небольшого тестового трафика, измерьте долю невалидных ответов и только затем расширяйте сценарий. Если категория влияет на права, финансы, здоровье или другой чувствительный процесс, добавьте отдельный review: техническая схема снижает риск ошибок формата, но не заменяет ответственность продукта за решение.

Server-side пример

Пример показывает локальный контроллер на сервере. Ключи берутся только из окружения; до запуска подтвердите маршрут, model ID и параметры в текущем каталоге RussiaAPI.

from pydantic import BaseModel, ConfigDict, Field, ValidationError
from typing import Literal
import json

class Classification(BaseModel):
    model_config = ConfigDict(extra='forbid')
    category: Literal['question', 'request', 'other']
    confidence: float = Field(ge=0, le=1)
    rationale: str = Field(max_length=280)

def parse_model_output(text: str) -> Classification:
    payload = json.loads(text)  # text comes from a server-side API response
    return Classification.model_validate(payload)

# Catch JSONDecodeError and ValidationError; log only a request ID and schema version.

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