Источники знаний

Data source описывает, откуда берутся документы Knowledge space. Сейчас поддерживается два варианта из коробки — upload файла и URL fetch — а коннекторы (Confluence, Notion, Google Drive) — в roadmap.

Типы источников

Полный enum — KnowledgeSourceType в packages/database/prisma/schema.prisma. Roadmap-значения — заглушки: нет ни DataSource-записей, ни парсеров, ни sync-воркеров.

Поддерживаемые форматы (FILE_UPLOAD)

Лимит размера файла — из тарифа org (MAX_KNOWLEDGE_FILE_SIZE_BYTES). По умолчанию — 25 MB для платных, 5 MB для free.

Lifecycle ingest-а

DataSource ──► IngestionJob (QUEUED)
                    │
                    ▼
            IngestionJob (RUNNING)
                    │
              parse + chunk + embed
                    │
        ┌───────────┴───────────┐
        ▼                       ▼
KnowledgeDocument         (graph build)
        │
        ▼
KnowledgeChunk × N (+ embedding)
                    │
                    ▼
            IngestionJob (SUCCEEDED / FAILED)

Каждая запись IngestionJob:

• status — QUEUED → RUNNING → SUCCEEDED или FAILED.
• totalItems — оценка парсера в единицах работы (страницы / секции).
• processedItems, failedItems — нарастающие счётчики.
• errorMessage — на провал. Видно в дашборде Ingestion Jobs.

Список — knowledge.listIngestionJobs. Для диагностики смотрите inputMeta (имя файла, mime, размер).

Retry-семантика

Провалившиеся job-ы не ретраятся автоматически. Рекомендованный flow:

1. Смотрим errorMessage в дашборде.
2. Чиним источник (перекодируем PDF, расширяем URL, заменяем кривой DOCX) или окружение (квота LLM исчерпана).
3. Повторно запускаем — переуплоадом или повторным ingestFile / ingestUrl. Создаётся новая IngestionJob, существующий DataSource переиспользуется.

Re-ingest заменяет предыдущий KnowledgeDocument по ключу (knowledgeSpaceId, externalId) и пересоздаёт чанки + эмбеддинги. Старые чанки удаляются каскадом по documentId.

Стратегии чанкинга

Реализация — packages/api/modules/knowledge/lib/chunking.ts. Стратегия определяет, как распарсенный текст режется перед эмбеддингом:

Параметризуется per call (или per space, Beta):

{
  strategy: "semantic",
  chunkSize: 350,      // целевое число слов
  minChunkSize: 60,    // слить меньше этого
  maxChunkSize: 600,
  overlap: 50,         // overlapping слов между соседями
}

Правило: 250–400 слов на чанк, 30–50 слов overlap — покрывает большинство прозы. Большие чанки — меньше retrieval-ов, но слабее сигнал; маленькие — лучше relevance, но дороже эмбеддинги.

Эмбеддинги

Каждый embedding — Json массив floats размером под выбранную модель:

KnowledgeSpace.ragConfig.embeddingModel переопределяет дефолт per space. Локальный 128-dim fallback (embedTextLocally в chunking.ts) — только dev: бесполезен для retrieval-а, до продакшена настройте реальную модель.

Смена модели эмбеддингов инвалидирует все существующие эмбеддинги чанков. После смены — full re-ingest каждого источника в space.

Ingest файла

const job = await orpc.knowledge.ingestFile.call({
  spaceId: "ks_…",
  fileName: "handbook.pdf",
  mimeType: "application/pdf",
  bytes: pdfArrayBuffer,
});
// → { ingestionJobId, dataSourceId }

Опрос — knowledge.listIngestionJobs, либо SSE в дашборде.

Ingest URL

await orpc.knowledge.ingestUrl.call({
  spaceId: "ks_…",
  url: "https://example.com/docs/payments",
  cssSelector: "main article",   // опционально — сузить экстракцию
});

Только публичные HTML-URL — без JS-исполнения, без auth-хедеров, без SPA-render-а. Страницы за логином — roadmap (коннекторы).

Удаление source-ов и файлов

Каскады — на уровне Postgres FK (onDelete: Cascade в schema.prisma). Удаление durable и необратимое. Подтверждайте в UI.

Квоты

Per-org квоты — из entitlements:

Исчерпание квоты → 402 Payment Required и активити-эвент quota_warning при 80% месячного бюджета.

Связанные страницы

• Обзор Knowledge RAG
• Evaluation — измерение качества
• GraphRAG entity model — что пишет buildGraphFromChunks
• Plans and limits
• Knowledge module & admin