OpenAI-совместимый API в FastAPI: серверная интеграция

Короткий ответ: ключ живёт только на сервере

Не передавайте RUSSIAAPI_API_KEY в JavaScript-бандл, мобильное приложение, форму FastAPI или локальное хранилище браузера. Клиент отправляет запрос только в ваш endpoint с собственной аутентификацией; backend определяет пользователя и tenant из доверенного контекста. Так пользователь не может выбрать чужой ключ, base URL, маршрут или тариф. Даже если интерфейс скрывает поле ключа, сетевой запрос из браузера остаётся доступным владельцу сессии, поэтому защита должна находиться до границы клиента.

Отделите публичную схему FastAPI от формата внешнего gateway. Входная модель приложения принимает только нужные поля, ограничивает длину и запрещает лишние ключи. Сервисный слой добавляет system policy, выбранный из allowlist model ID, deadline и request_id приложения. Затем адаптер вызывает только документированный маршрут. Такая граница позволяет заменить SDK или маршрут после контрактного теста, не раскрывая внутреннюю конфигурацию каждому пользователю и не меняя публичный API продукта вслепую.

Начните с малого контракта и allowlist моделей

Публичный endpoint должен иметь узкое назначение: например, подготовить краткий безопасный черновик для текущего объекта, а не передавать произвольный request body «как в OpenAI». Не принимайте от клиента model, provider, api_key или base_url. Backend выбирает допустимый model ID по версии продукта и policy tenant. Перед добавлением модели выполните обезличенный smoke test, подтвердите её наличие в актуальном каталоге RussiaAPI и зафиксируйте результат. Название модели в чужой документации не подтверждает её доступность в вашем маршруте.

Храните версию адаптера и контракта рядом с кодом. При обновлении SDK проверяйте формы успешного ответа, ошибок, streaming и tool-вызовов на небольшом тестовом наборе. Если новый вариант не проходит проверку, rollback возвращает прошлый проверенный adapter, а не незаметно меняет параметры в production. Это особенно важно для сценариев, где текст модели идёт дальше по автоматическому pipeline: результат модели остаётся недоверенным вводом и проходит отдельную schema, авторизацию и бизнес-проверку.

Задайте timeout, отмену и ограниченные повторы

Timeout FastAPI — это не предположение о фиксированной задержке AI API. Приложение задаёт собственный deadline на уровне операции и передаёт отмену вниз, когда клиент отключился или окно истекло. Для чтения можно рассмотреть ограниченный повтор только для временных сетевых ошибок. Для создания ресурса, списания внутреннего budget или асинхронной видео-задачи сначала нужна собственная идемпотентность: повтор не должен породить второй эффект. Условия конкретного endpoint подтверждают по актуальной документации, а не выводят из похожего SDK-вызова.

Возвращайте наружу стабильный код приложения, например upstream_unavailable, invalid_input или operation_pending, без полного тела supplier-ошибки. В лог включайте request_id, длительность, HTTP-класс статуса и безопасный тип операции. Не записывайте Authorization, ключ, prompt, cookie, полное сообщение модели или внутренний base URL. Поддержка сможет сопоставить incident по request_id, а пользователь не получит информацию, пригодную для обхода вашей политики или доступа к другому tenant.

Проверьте аутентификацию, tenant и расходы

Перед вызовом gateway FastAPI должен получить аутентифицированного субъекта и определить tenant на сервере. Не доверяйте tenant_id, price_limit или role из JSON браузера: эти данные либо извлекаются из сессии, либо перепроверяются в базе. Добавьте внутреннюю квоту, очередь и budget для класса операции; это политика вашего продукта, а не заявленный лимит RussiaAPI. Если счётчик недоступен, безопаснее отложить операцию или вернуть понятный временный отказ, чем пропустить неконтролируемую нагрузку.

Для диагностики подготовьте негативные тесты: чужой tenant, пустой вход, сверхдлинный текст, неизвестная модель, повтор request_id, отменённая сессия и недоступный адаптер. Убедитесь, что ни один путь не раскрывает переменную окружения, стек с URL или полный внешний ответ. Тесты на реальном ключе проводят только с синтетическими обезличенными данными. Не используйте в примере или тесте ключи upstream-поставщиков: RussiaAPI принимает только ключ, созданный для вашего собственного server-side доступа.

Выпустите адаптер через test tenant и наблюдаемость

Начните с test tenant, минимального входа и подтверждённой модели. Отслеживайте долю ошибок по классу, время до ответа, отмены, невалидные ответы и расходы по внутренним агрегатам. Не интерпретируйте краткий тест как постоянный SLA, цену или гарантию модели. Если свойства меняются, приостановите rollout, сохраните безопасные идентификаторы наблюдаемости и вернитесь к последнему проверенному adapter. Пользователь должен видеть честный статус, а не бесконечный spinner или ложное сообщение об успешной генерации.

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

Server-side пример

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

from dataclasses import dataclass
from fastapi import Depends, FastAPI, HTTPException
from pydantic import BaseModel, Field
import os

app = FastAPI()
ALLOWED_MODELS = {'approved-model-id'}  # Confirm against the current catalog.

@dataclass
class Session:
    tenant_id: str

async def require_session() -> Session:
    # Replace with verified application authentication in production.
    return Session(tenant_id='test-tenant')

class DraftInput(BaseModel):
    text: str = Field(min_length=1, max_length=4000)

@app.post('/api/draft')
async def create_draft(payload: DraftInput, session = Depends(require_session)):
    model = 'approved-model-id'
    if model not in ALLOWED_MODELS or not os.environ.get('RUSSIAAPI_API_KEY'):
        raise HTTPException(503, 'service_not_ready')
    # Call a documented RussiaAPI route here with a server-side timeout and request ID.
    return {'state': 'accepted', 'tenant': session.tenant_id}

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