RAG Panel

Авторизация

Интеграции (боты, скрипты): заголовок X-API-Key — только выданный ключ из раздела «Ключи» (создаёт администратор панели).

X-API-Key: <секрет>

Веб-панель: после POST /auth/login передавайте JWT и обязательно X-RAG-Panel: 1 (выбор базы в UI).

Authorization: Bearer <jwt>
X-RAG-Panel: 1

Обязательно задайте JWT_SECRET в окружении (в продакшене — длинная случайная строка). Без неё используется небезопасное значение по умолчанию.

Вход в панель и проверка сессии

POST /auth/login — JSON {"login":"...","password":"..."}. Ответ: token, is_admin, login. Администратор — только пара ADMIN_LOGIN / ADMIN_PASSWORD.

GET /auth/check — те же заголовки, что и для запросов панели (Bearer + X-RAG-Panel) или только X-API-Key. Ответ: ok, is_admin, user, либо для ключа — master, key_id.

Чат

• POST /chat — JSON: обязательное question; опционально session_id (продолжить диалог — сохраняйте session_id из ответа для следующих реплик), variants (1–5), filter, rag_db (можно не передавать: при API-ключе с привязками — поиск по всем привязанным базам OR; одна привязка — та же база), extra_context.
• GET /chat/list — список сессий: id, title, last_used, feedback (true / false / null).
• POST /chat/create — пустая сессия, в ответе id.
• POST /chat/feedback — оценка: session_id, helpful (true / false). Ответ: ok, feedback.
• POST /chat/knowledge/qa — пара для RAG (не fine-tune): question, answer; опционально rag_db (не указывать, если у ключа ровно одна привязанная база — подставится автоматически; при нескольких — обязателен), ticket_id (необязательно — ID тикета из вашей системы поддержки: CRM, Helpdesk, Jira и т.д.; сервер его не выдаёт), metadata. Ответ: status: queued, job_id.

Коды ошибок detail (JSON):

• 400 — empty_question, empty_session_id, empty_qa
• 403 — moderation_blocked
• 404 — session_not_found
• 413 — context_overflow (превышено окно модели даже после обрезки)
• 422 — no_rag_context (нет данных в базе — LLM не вызывается)
• 429 — chat_frozen (+ retry_after_sec)
• 502 — empty_llm_response

Пример из бота (Python, выданный API-ключ, одна база support):

import requests

API = "https://your-host"
KEY = "rk_...."  # выданный секрет

r = requests.post(
    f"{API}/chat",
    headers={"X-API-Key": KEY, "Content-Type": "application/json"},
    json={
        "question": "Как оформить возврат?",
        "session_id": "user-12345",  # опционально: тот же id для цепочки сообщений
        "rag_db": "support",         # опционально: если у ключа несколько баз — лучше указать. Иначе будут использованы те, которые привязаны к апи-ключу
        "extra_context": "...",      # опционально: доп. контекст
    },
    timeout=120,
)
r.raise_for_status()
data = r.json()
print(data["answer"])
print("session_id:", data["session_id"])
print("feedback:", data.get("feedback"))  # true | false | None

Несколько вариантов ответа (variants: 3):

curl -sS -X POST "$API/chat" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"question":"Как вернуть товар?","variants":3,"rag_db":"support"}'
# Ответ: answer (первый вариант), answers[{variant, query_used, rag_query, answer}], feedback

Оценка и Q&A от саппорта:

curl -sS -X POST "$API/chat/feedback" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"session_id":"SESSION_UUID","helpful":true}'

curl -sS -X POST "$API/chat/knowledge/qa" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"question":"Срок возврата?","answer":"14 дней","rag_db":"support"}'
# Ответ API: status "pending_review" + pending_id (модерация в панели → вкладка «На проверке»).
# То же для POST /api/v1/chat/knowledge/qa
# ticket_id — по желанию, например "48291" из вашей CRM:
# -d '{"question":"...","answer":"...","rag_db":"support","ticket_id":"48291"}'

Пример через curl:

curl -sS -X POST "$API/chat" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Привет","rag_db":"support","extra_context":"Баланс: 1000, статус: verified"}'

Ответ POST /chat: session_id, answer, feedback (последняя оценка или null); при variants > 1 — также answers[].

RAG

• POST /rag/add, /rag/add_qa, /rag/add_from_url, /rag/add_from_mongo, /rag/upload
• POST /rag/search — поиск по коллекции
• POST /rag/delete, DELETE /rag/delete_document/{id}, PUT /rag/update
• GET /rag/list, /rag/count, /rag/databases
• GET /rag/queue?page=1&limit=25 — пагинация: jobs, total, pages
• POST /rag/databases — зарегистрировать имя базы; DELETE /rag/databases/{name}
• DELETE /rag/queue/{job_id}, POST /rag/queue/{job_id}/retry
• GET /rag/pending-qa, /rag/pending-qa/count — модерация Q/A из API (только JWT + X-RAG-Panel: 1)
• POST /rag/pending-qa/{id}/approve, /reject — после approve пара уходит в очередь индексации

Конфиг и промпт

• GET / POST /config, POST /config/reset
• GET / POST /prompt (тело — plain text)

Память и логи

• GET / DELETE /memory/{session_id}
• GET /logs?page=1&limit=50&kind=chat — пагинация; kind: chat, moderation, chat_feedback, …

MongoDB

POST /mongo/list — тело skip, limit, опционально rag_db (для импорта в RAG действуют те же правила, что и для записи)