Быстрый старт

Пройдя регистрацию, создание базы знаний, настройку модели, загрузку документа и вопрос, вы выполните первый цикл вопросов и ответов по базе знаний и сможете увидеть исходные цитаты в ответе. Шаги ниже описывают веб-интерфейс, а в конце приведён соответствующий пример через API.

Перед началом нужно выполнить установку и развёртывание и подготовить рабочую модель диалога и векторную модель.

Перед началом

Запустите сервисы: после запуска по инструкции по установке и развёртыванию фронтенд доступен по http://localhost, а бэкенд — по http://localhost:8080;
Подготовьте данные подключения к моделям: локальный Ollama (адрес по умолчанию внутри контейнера — http://host.docker.internal:11434) либо base_url + api_key любого OpenAI-совместимого сервиса. Нужны как минимум одна модель диалога и одна векторная (embedding) модель;
Проверьте работоспособность бэкенда: curl http://localhost:8080/health возвращает {"status":"ok"}.

Регистрация и вход

При первом обращении открывается страница входа. Если развёртывание допускает публичную регистрацию (self_serve), на странице отображается вкладка регистрации; учётных записей по умолчанию нет. При конфигурации по умолчанию регистрация создаёт личное рабочее пространство и назначает нового пользователя его Owner.

Требования к регистрации и различия между развёртываниями:

Имя пользователя — 2–50 символов; пароль — 8–32 символа и содержит минимум буквы и цифры. При включённой политике сложных паролей он также должен содержать заглавные и строчные буквы и специальные символы; интерфейс и API используют одну и ту же политику;
Когда командному развёртыванию нужно, чтобы новые участники регистрировались по ссылке-приглашению, системный администратор задаёт auth.registration_mode равным invite_register в разделе «Настройки → Системные настройки» (вступает в силу немедленно). invite_only / DISABLE_REGISTRATION=true означают запрет регистрации по паролю: даже приглашение не может создать новую учётную запись, разрешён только вход уже существующих учётных записей с последующим присоединением;
Если в развёртывании политика пространства по умолчанию — tenantless (auth.default_tenant_mode), после регистрации пространство не создаётся автоматически: пользователь попадает на /onboarding/workspace и должен сам создать пространство или принять приглашение, чтобы продолжить;
Настольное приложение обходится без регистрации: при запуске оно автоматически создаёт локальную учётную запись и выполняет вход; при доступе к одиночному бинарнику Lite через браузер регистрация и вход по-прежнему нужны.

Права пространства и платформы

Owner пространства управляет участниками, моделями и базами знаний своего пространства. Глобальные системные настройки, очередь платформенных задач и аудит между пространствами требуют прав системного администратора; эти два вида прав выдаются независимо.

При первой настройке системного администратора сначала зарегистрируйте учётную запись, затем задайте для сервиса app переменную WEKNORA_BOOTSTRAP_SYSTEM_ADMIN_EMAIL=<email этой учётной записи> и перезапустите. Этот порядок действует только пока в развёртывании нет системного администратора. Полные шаги и ограничения — в разделе Управление платформой и системный администратор.

Создание базы знаний и настройка модели

После создания базы знаний на странице «Базы знаний» мастер инициализации поможет настроить модели, используемые этой базой. Для каждой базы знаний модели выбираются отдельно.

На странице «Базы знаний» нажмите «Создать», укажите имя и выберите тип: document (обычная база документов) или faq (база пар вопрос-ответ);
В открывшемся мастере инициализации выберите модели:

Модель диалога (LLM): генерирует ответы;
Векторная модель (Embedding): преобразует документы в векторы; после замены требуется перестроить индекс;
Переранжирование Rerank, понимание изображений VLM, расшифровка речи ASR, извлечение графа знаний и генерация вопросов настраиваются по типу материалов и потребностям;

Кнопкой «Проверить» в мастере убедитесь, что подключение к модели работает, и сохраните.

Подключение к Ollama из контейнера

localhost внутри контейнера бэкенда указывает на сам контейнер. Для подключения к Ollama на хосте используйте http://host.docker.internal:11434.

Загрузка документов

Войдите в базу знаний и перетащите файл или вставьте URL веб-страницы. В диалоге подтверждения загрузки можно задать метки и параметры разбора для этой партии файлов.

Поддерживаются форматы PDF, Word, Excel, PPT, Markdown, HTML, EPUB, изображения и аудио и др.; полный список — в разделе Сервис разбора документов.

После загрузки документы разбираются асинхронно, статусы сменяются по порядку pending → processing → finalizing → completed. Сканы PDF и большие файлы обрабатываются дольше; на странице списка прогресс обновляется в реальном времени.

Вопросы

Перейдите на страницу диалога и выберите базу знаний — можно задавать вопросы. Встроенный агент «Быстрые ответы» по умолчанию извлекает релевантные фрагменты и генерирует ответ; щёлкните по цитате, чтобы открыть исходный текст.

Если ответ отображается корректно и цитаты открываются, значит цикл индексации документов и вопросов-ответов пройден.

Дальнейшая настройка

Настроить агента: использовать умное рассуждение для многошаговых задач, при необходимости включить веб-поиск и инструменты MCP.
Настроить разбиение на блоки и параметры поиска: подстроить конфигурацию под структуру документов и результаты поиска.
Подключить источники данных: постоянно синхронизировать контент Feishu, Notion, Yuque или RSS.
Подключить IM или веб-встраивание: дать пользователям возможность задавать вопросы через привычные каналы.

Первый цикл вопросов и ответов через API

Пример ниже вызывает API в порядке: регистрация, вход, создание базы, инициализация модели, загрузка и вопрос-ответ. Пути используют единый префикс /api/v1; нужны Bash, curl и jq. Учётная запись для входа должна уже входить в рабочее пространство; если в ответе на вход нет active_tenant, сначала создайте пространство или вступите в него и войдите заново.

bash

BASE=http://localhost:8080/api/v1

# 1) Регистрация (при первом развёртывании; имя пользователя 2–50 символов; пароль 8–32 символа и содержит буквы и цифры, при сложной политике — дополнительные требования)
curl -s -X POST $BASE/auth/register -H "Content-Type: application/json" \
  -d '{"username":"admin","email":"admin@example.com","password":"pass123456"}'

# 2) Вход: сохраняем JWT и ID текущего рабочего пространства (пригодится при создании API Key)
LOGIN_RESPONSE=$(curl -s -X POST $BASE/auth/login -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"pass123456"}')
TOKEN=$(printf '%s\n' "$LOGIN_RESPONSE" | jq -r '.token')
TENANT_ID=$(printf '%s\n' "$LOGIN_RESPONSE" | jq -r '.active_tenant.id')
AUTH="Authorization: Bearer $TOKEN"

# 3) Создание базы знаний
KB_ID=$(curl -s -X POST $BASE/knowledge-bases -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name":"Моя база знаний","description":"demo","type":"document"}' | jq -r '.data.id')

# 4) Инициализация базы знаний (пример с локальным Ollama; для удалённой модели измените source/baseUrl/apiKey)
curl -s -X POST $BASE/initialization/initialize/$KB_ID -H "$AUTH" -H "Content-Type: application/json" -d '{
  "llm":       {"source":"local","modelName":"qwen3:8b"},
  "embedding": {"source":"local","modelName":"bge-m3","dimension":1024},
  "rerank":    {"enabled":false},
  "multimodal":{"enabled":false},
  "documentSplitting":{"chunkSize":512,"chunkOverlap":50,"separators":["\n\n","\n","。"]},
  "nodeExtract":{"enabled":false},
  "questionGeneration":{"enabled":false}}'

# 5) Загрузка документа (multipart, имя поля file)
curl -s -X POST $BASE/knowledge-bases/$KB_ID/knowledge/file -H "$AUTH" \
  -F "file=@./demo.pdf"
# Опрос статуса разбора: GET /knowledge-bases/$KB_ID/knowledge до parse_status=completed

# 6) Создание сессии
SESSION_ID=$(curl -s -X POST $BASE/sessions -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"title":"Первый диалог"}' | jq -r '.data.id')

# 7) Вопрос по базе знаний (потоковый вывод SSE)
curl -N -X POST $BASE/knowledge-chat/$SESSION_ID -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"query":"О чём этот документ?","knowledge_base_ids":["'$KB_ID'"]}'

# 7b) Диалог с Agent (тоже SSE; в agent_id можно указать встроенный builtin-smart-reasoning)
curl -N -X POST $BASE/agent-chat/$SESSION_ID -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"query":"Изложи ключевые тезисы документа и приведи обоснования","agent_enabled":true,"agent_id":"builtin-smart-reasoning","knowledge_base_ids":["'$KB_ID'"]}'

# 8) Только поиск без генерации (структурированный результат JSON)
curl -s -X POST $BASE/knowledge-search -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"query":"ключевое слово","knowledge_base_ids":["'$KB_ID'"]}'

Тело запроса вопрос-ответ также поддерживает поля knowledge_ids (ограничение одним документом), web_search_enabled, summary_model_id, mcp_service_ids, skill_names, images / attachment_uploads (мультимодальные вложения) и др.; полное описание — в Справочнике API: сессии и чат.

Три способа аутентификации

Способ	Заголовок запроса	Когда применять
JWT	`Authorization: Bearer <token>`	Браузер / интерактивные вызовы, выдаётся эндпоинтом входа
API Key	`X-API-Key: <key>`	Серверная интеграция; создаётся в «Настройках пространства» или через `POST /api/v1/tenants/:id/api-keys`, поддерживает тонкие возможности (`retrieve`/`chat`/`ingest`/`manage_kbs` и др.)
Указание пространства	`X-Tenant-ID: <id>`	Переключение текущего рабочего пространства для пользователей с несколькими пространствами

Для серверной интеграции рекомендуется API Key, а не JWT:

bash

# Создание API Key от имени Owner текущего рабочего пространства (TENANT_ID уже получен на шаге входа)
curl -s -X POST $BASE/tenants/$TENANT_ID/api-keys -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name":"ci-bot","full_access":true}'
# Далее во всех запросах используйте:
curl -s $BASE/knowledge-bases -H "X-API-Key: <ключ, возвращённый при создании>"

Эндпоинты, соответствующие мастеру инициализации

У каждого шага мастера в интерфейсе есть отдельный эндпоинт; его можно напрямую переиспользовать при создании собственной панели администратора:

Шаг	Эндпоинт	Описание
Чтение текущей конфигурации	`GET /api/v1/initialization/config/:kbId`	Возвращает секции llm / embedding / rerank / multimodal / documentSplitting / nodeExtract / questionGeneration и `hasFiles` (при наличии файлов изменение embedding ограничено)
Проверка Ollama	`GET /api/v1/initialization/ollama/status`, `GET /api/v1/initialization/ollama/models`	Проверяет доступность Ollama и установленные модели
Загрузка моделей Ollama	`POST /api/v1/initialization/ollama/models/download` → `GET /api/v1/initialization/ollama/download/progress/:taskId`	Асинхронная загрузка и опрос прогресса
Проверка удалённой модели	`POST /api/v1/initialization/remote/check`, `/initialization/embedding/test`, `/initialization/rerank/check`, `/initialization/asr/check`, `/initialization/multimodal/test`	Проверка соединения перед сохранением
Пробное извлечение графа знаний	`POST /api/v1/initialization/extract/text-relation` (с `fabri-text` / `fabri-tag` генерируются примеры)	Предпросмотр извлечения сущностей/отношений
Сохранение конфигурации	`POST /api/v1/initialization/initialize/:kbId` (первый раз) / `PUT /api/v1/initialization/config/:kbId` (обновление)	Запись в БД: создание/обновление записи Model и запись конфигурации KnowledgeBase

source принимает значение local (Ollama) или идентификатор удалённого провайдера (openai, deepseek, aliyun, zhipu, siliconflow и др.). Допустимый диапазон chunkSize — 100–10000.

Что происходит на всём пути

Если что-то не работает

Симптом	Что проверить
После загрузки статус долго остаётся `processing`	`docker logs WeKnora-docreader`; на большие файлы действуют ограничения `MAX_FILE_SIZE_MB` (по умолчанию 50) и `WEKNORA_DOCUMENT_PROCESS_TIMEOUT` (по умолчанию 2 ч)
При инициализации не проходит проверка Ollama	Адрес по умолчанию внутри контейнера — `http://host.docker.internal:11434` (`OLLAMA_BASE_URL`); в Linux убедитесь, что работает `extra_hosts: host.docker.internal:host-gateway`
В ответе нет цитат / выборка пуста	Убедитесь, что знание в статусе `completed`; уменьшите `vector_threshold`; проверьте, что модель embedding совпадает с использованной при создании базы
Пропала вкладка регистрации	Проверьте `registration_mode` в `GET /auth/config`. Значение может приходить из настроек БД в «Настройки → Система», а не только из `DISABLE_REGISTRATION`; ссылки-приглашения и первый вход через OIDC — отдельные пути, на них это не влияет
Запрос с API Key возвращает 403	В capabilities ключа нет нужной возможности либо белый список `knowledge_base_ids` не содержит целевую базу

Дальше: за деталями настройки — в Подробную конфигурацию, а чтобы понять, как устроена система, — в Обзор архитектуры.

Быстрый старт ​

Перед началом ​

Регистрация и вход ​

Создание базы знаний и настройка модели ​

Загрузка документов ​

Вопросы ​

Дальнейшая настройка ​

Первый цикл вопросов и ответов через API ​

Три способа аутентификации ​

Эндпоинты, соответствующие мастеру инициализации ​

Что происходит на всём пути ​

Если что-то не работает ​