Skip to main content

Knowledge Base

Overview​

Knowledge Base is the repository of documents and question-answer pairs that administrators feed to the AI as reference material when answering users. The repository does not reply to chats itself; it is referenced from Workflow, where a node whose response mode is set to knowledge-based selects which base the AI should search.

An important structural point up front: AI configuration and the knowledge base live in different places. The AI provider, model, and API key are configured once at the LINE OA level. A knowledge base is purely a source of material that a workflow can point at — it does not choose a model of its own.

A base consists of a name, a description, a base-level system instruction, usage statistics, and a set of documents in three kinds: text documents, question-answer pairs, and uploaded files. Every document carries an index status (pending, processing, completed, or failed).

Business Flow​

Base list​

  1. The list loads all bases sorted by most recently created. There is no search box or filter here — only pagination.
  2. The table shows the row number, base name, a truncated description with a tooltip, the document count, the status, the last-indexed timestamp, and edit and delete actions.
  3. Creating a base asks only for a name, through a small modal that auto-focuses the input and accepts Enter to confirm. On success the user is taken straight to the new base's detail page to fill in the rest.
  4. Deletion requires confirmation and reports its outcome through a success or failure dialog.

Base detail​

  1. The detail page reads the base ID from the URL and loads two datasets in parallel: the base header with its statistics, and the full document list.
  2. The basic information card is a form covering the name (required), description, and base-level system instruction. Saving reloads the header data.
  3. The statistics card shows four figures — total documents, total question-answer pairs, total retrieval chunks, and the last-indexed time — plus a button to reindex the whole base.
  4. Indexing is a background job. Triggering it reports that the job has started and reloads the data, but progress is not tracked continuously; the user must revisit to see the resulting document statuses.
  5. All documents are fetched in one request and split into three tabs on the client according to their kind.
  6. The Documents tab adds and edits text entries through a modal with a title and body, both required. The table shows the title, a truncated body, the index status as a coloured tag, and edit and delete actions.
  7. The Q&A tab mirrors that structure with question and answer fields, and reuses the same delete operation.
  8. The Files tab is currently disabled, even though the upload, table, and delete logic are all written and support PDF, DOCX, and TXT files.
  9. A back button in the header returns to the list.

Putting a base to work with AI​

  1. The Workflow form fetches the base list in option form and passes it down to the node configuration panel.
  2. When a node's response mode is set to knowledge-based, a base selector appears alongside a reload button. Choosing a base stores both its ID and its name in the node's data.
  3. The actual AI configuration — provider, model, and API key — is set on the LINE OA management screen, which requires an API key the first time and clears the key field from the screen after a successful save.
  4. That same AI configuration also powers the AI-assisted Flex Message builder inside Workflow.

Key Screens & Components​

List screen (src/app/knowledge-base/page.tsx with src/components/knowledge-base/list/knowledge-base-list.container.tsx) — the table, the name-only create modal, and deletion.

Detail screen (src/app/knowledge-base/detail/page.tsx) — everything in one file with no separate container: the header form, the statistics card, the reindex button, all three tabs, and both document modals.

Shared service (src/services/knowledge-base.service.ts) — list, select-options list, read, create, update, delete, document management (add, update, delete), reindex, and file upload. The service tolerates both response shapes the API can return: a bare array and a wrapped payload.

AI configuration service (src/services/ai-config.service.ts) — reads and writes the AI settings and generates Flex Messages from a prompt. It is never called from the knowledge base screens; its real callers are the LINE OA management form and the Workflow Flex builder.

Dependencies​

  • Permissions — the subject knowledge-base is unlocked by the backend system module. In practice the check is currently applied at the side menu and quick-access palette.
  • Workflow — the module's primary consumer, pulling the base list as options for nodes that answer from a knowledge base.
  • LINE OA Management — where the AI provider, model, and API key are configured. These must be set before a knowledge base can actually be used to answer.
  • AI Flex builder — shares the same AI configuration.
  • Background systems — chunking and embedding generation happen on the server and worker. The web layer only triggers a reindex and reads back the statuses and statistics the server writes.
  • Shared CMS components — the section header, confirmation dialog, result dialogs, loading state, empty state, and table scroll area.

Backend Details (CMS API)​

The module lives in internal/modules/knowledgebase/, registered under the /api/knowledge-base group.

A three-layer data model​

The database does not store documents as one blob; it splits them across three layers.

  • Base (knowledge_base) — one LINE OA can own several bases.
  • Document (knowledge_document) — an individual document inside a base; this is what users see and edit in the UI.
  • Chunk (knowledge_chunk) — documents sliced into pieces with embedding vectors for semantic search. Users never edit this layer directly, but it is the layer the bot actually searches.

Indexing is handed to the worker, not done in-request​

  • When a document is added (POST /api/knowledge-base/:id/documents) or updated (PUT .../documents/:docId), the backend does not generate embeddings inline. It publishes a job to the knowledge_index RabbitMQ queue and returns immediately.
  • The worker picks the job up, generates embeddings, writes the chunk rows, and pushes them into the search engine.
  • POST /api/knowledge-base/:id/reindex requeues the entire base, used when the embedding model changes or chunk data is corrupted.
  • Consequence worth knowing: a 200 from the API means "job accepted", not "indexing complete". A freshly added document is not immediately findable by the bot, and if the worker is down or the queue is backed up, the CMS surfaces no error at all — the statuses and statistics the worker writes back are the only signal.
  • The published payload is byte-for-byte pinned to the legacy shape because the original worker still consumes it, so changing the message structure is a cross-service contract change.

Permissions and a security note​

  • The main routes sit on the group requiring the global JwtAuth. Policy metadata is declared against the line-oa module but is not enforced, and there is no ModuleGate.
  • GET /api/knowledge-base/select-options is protected more weakly than the rest. It sits on the public group and is checked only by a login-level token. The reason is that the Workflow configuration screen must be able to pick a base before the token is bound to an OA. The side effect is that the list of bases is reachable at a lower privilege level than the base details themselves.

Deletion happens in two passes​

DELETE /api/knowledge-base/:id and document deletion perform a two-stage soft delete: the record's status is first flipped to a deleted state, then a deleted_date timestamp is stamped. The behaviour is carried over from the previous system. The record remains in the database with both a status and a timestamp as evidence, but every read must filter on both by hand.

Error handling​

Errors the backend raises deliberately (base not found, invalid input) pass through with their intended status and message. Unexpected database errors are flattened into a 500 with a generic error code, so an error message should not be assumed to explain the real cause.

Tables and external systems​

Tables knowledge_base, knowledge_document, knowledge_chunk, and line_oa. External systems are RabbitMQ (the knowledge_index queue), the embedding service, and the full-text search engine the worker writes into during indexing.