Демо API¶

Публичная неаутентифицированная конечная точка для функции «Попробуйте сами» на лендинге. Ограничение запросов по IP, доступен только сценарий onboarding.

Конечные точки¶

POST /api/v1/demo/chat¶

Отправка запроса на естественном языке о демонстрационной кодовой базе (PostgreSQL 17.6).

Аутентификация: не требуется (публичная конечная точка) Ограничение: 30 запросов/минуту на IP

Запрос¶

{
  "query": "Где определена главная функция?",
  "language": "ru"
}

Поле	Тип	Обязательно	По умолчанию	Описание
`query`	string	Да	—	Вопрос на естественном языке (1-500 символов)
`language`	string	Нет	`"ru"`	Язык ответа (`"en"` или `"ru"`)

Ответ (200)¶

{
  "answer": "Главная функция определена в src/backend/main/main.c на строке 53...",
  "scenario_id": "onboarding",
  "processing_time_ms": 234.5
}

Поле	Тип	Описание
`answer`	string	Ответ, сгенерированный LLM
`scenario_id`	string	Всегда `"onboarding"` в демо-режиме
`processing_time_ms`	float	Время обработки на сервере

Ошибки¶

Статус	Причина	Тело ответа
400	Запрос слишком длинный (>500 символов)	`{"detail": "Запрос превышает максимальную длину"}`
403	Запрос не по теме или заблокирован	`{"detail": "...", "examples": [...]}`
429	Превышено ограничение на число запросов	`{"detail": "Слишком много запросов"}`
503	Демо-режим отключён	`{"detail": "Демонстрационная конечная точка отключена"}`

Ответ при нерелевантном запросе (403)¶

При отклонении нерелевантного запроса ответ содержит примеры:

{
  "detail": "Этот запрос выходит за рамки демонстрации. Попробуйте вопросы о кодовой базе.",
  "examples": [
    "Где определена heap_insert?",
    "Покажи граф вызовов ExecProcNode",
    "Как работает MVCC в PostgreSQL?"
  ]
}

GET /api/v1/demo/status¶

Проверка доступности и конфигурации демонстрационной конечной точки.

Аутентификация: не требуется

Ответ (200)¶

{
  "enabled": true,
  "rate_limit": "30/minute",
  "max_query_length": 500,
  "allowed_scenarios": ["onboarding"]
}

Конвейер валидации запросов¶

Входящие запросы проходят 4-этапную валидацию:

1. ЖЁСТКИЙ ОТКАЗ — явно вредоносное содержимое (регулярные выражения)
   └─ Возврат 403 с причиной blocked_content

2. НЕВЕРНЫЙ СЦЕНАРИЙ — легитимный запрос за пределами onboarding
   └─ Возврат 403 с именем сценария + примерами

3. БЫСТРОЕ ПРИНЯТИЕ — обнаружены ключевые слова домена
   └─ Если оценка ≥ порога → запрос принят

4. LLM-СУДЬЯ — неоднозначные запросы отправляются в YandexGPT Lite
   └─ Возвращает is_relevant + оценку достоверности
   └─ Кешируется по MD5(запрос) на 1 час

Кеширование¶

Демонстрационная конечная точка кеширует ответы для снижения нагрузки на LLM:

Кеш	Размер	TTL	Ключ
Кеш ответов	100 записей (LRU)	30 минут	`normalize(query).lower()`
Кеш LLM-судьи	1000 записей (LRU)	1 час	`MD5(query.lower())`

Конфигурация¶

config.yaml¶

api:
  demo:
    enabled: true                  # Включить/отключить демонстрационную конечную точку

Переменные окружения¶

Переменная	По умолчанию	Описание
`DEMO_ENABLED`	`true`	Включить/отключить демонстрационную конечную точку
`DEMO_RATE_LIMIT`	`30/minute`	Ограничение запросов на IP

Настройки LLM-судьи¶

# Внутренняя конфигурация (demo.py)
llm_judge:
  temperature: 0.1         # Низкая температура для стабильных решений
  max_tokens: 50           # Короткий ответ да/нет
  model: yandexgpt-lite    # Облегчённая модель для быстрых решений

Примеры использования¶

curl¶

# Корректный запрос
curl -X POST http://localhost:8000/api/v1/demo/chat \
  -H "Content-Type: application/json" \
  -d '{"query": "Как работает MVCC?", "language": "ru"}'

# Проверка статуса
curl http://localhost:8000/api/v1/demo/status

JavaScript (лендинг)¶

const response = await fetch('/api/v1/demo/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: document.getElementById('demo-input').value,
    language: 'ru'
  })
});

if (response.ok) {
  const data = await response.json();
  showAnswer(data.answer);
} else if (response.status === 403) {
  const error = await response.json();
  showExamples(error.examples);
} else if (response.status === 429) {
  showRateLimit();
}

Безопасность¶

Без аутентификации — конечная точка публично доступна
Ограничение запросов — 30 запросов/минуту на IP предотвращает злоупотребление
Ограничение сценария — доступен только onboarding (без анализа безопасности, редактирования файлов и т.д.)
Валидация запросов — 4-этапный конвейер блокирует вредоносные и нерелевантные запросы
Только чтение — операции записи невозможны через демонстрационную конечную точку
Ключевые слова домена — загружаются из доменного плагина, не зашиты в код

Связанная документация¶

REST API — полный справочник API
Конфигурация — настройка окружения
Сценарии — сценарий S01 Онбординг

Модуль: src/api/routers/demo.py Последнее обновление: февраль 2026