Knowledge Bases

A Package carries how a Knowledge Base indexes and searches, and never the documents. The author's files are theirs, and the installer brings their own.

name: Product Docs
embedding:
  slot: embedding
  modelPreference: text-embedding-3-small
searchMode: hybrid
hybridAlpha: 0.6
indexConfig:
  metadata:
    use_builtin: true
    fields:
      - name: product
        type: text
        required: true
        description: The product the document is about.
dataMode: schema-only

Run npx @elizon/cli@<cliVersion> example knowledge-base for a complete project with a file like this one. validate and build both check the file against the rules on this page.

Search modes

searchMode takes exactly one of three values. Any other value, including a different capitalisation, is refused by validate and build with PORTABLE_DEFINITION_INVALID, and the message lists the three. The platform refuses the same values when a Knowledge Base is created, edited or imported. A value stored before this check existed was normalised to hybrid, which is how it was already searched.

Index settings

indexConfig is the Knowledge Base's knowledge_base_config, in the shape Studio stores and exports: { hnsw, bm25, metadata: { use_builtin, fields } }. null, an empty object, or any section or key left out means the default below. The settings are fixed when the index is created; the installer can change them later in Studio, which re-indexes.

Only the keys below are honoured. A key not listed here, at any level, is accepted and carried but ignored, and validate and build warn KB_INDEX_CONFIG_KEY_IGNORED naming it (for example indexConfig.hnsw.efConstruction), so check the spelling. The warning does not fail the command. A listed key with a value of the wrong type, or an enum value not listed, is refused with PORTABLE_DEFINITION_INVALID.

name: Product Docs
embedding:
  slot: embedding
  modelPreference: null
searchMode: vector
hybridAlpha: 0.5
indexConfig:
  hnsw:
    distance_metric: cosine
    ef_construction: 128
    max_connections: 16
    ef: 64
  bm25:
    bm25_k1: 1.2
    bm25_b: 0.75
  metadata:
    use_builtin: false
    fields:
      - name: product
        type: text
        required: true
        description: The product the document is about.
      - name: released
        type: date
        required: false
        description: null
dataMode: schema-only

hnsw: the vector index

bm25: the keyword index

bm25 is read in keyword and hybrid mode, hnsw in vector and hybrid mode; both indexes are always built.

metadata: fields per document

Each entry of fields:

A field name is refused with PORTABLE_DEFINITION_INVALID by validate and build, naming the field (for example fields[0].name), when it:

• breaks the rule above, such as 2nd-field or _private;
• is one the platform writes itself: document_id, kb_id, source_id, chunk_index, document_name and text, which every chunk carries, or uploader, upload_date, last_update_date and source, which use_builtin adds (reserved even when it is off);
• is one Weaviate keeps for itself: id, _id, _additional and vector;
• repeats another field's name.

Names are compared ignoring case. Weaviate, which stores the index, treats two property names that differ only in case as the same property, so Text clashes with text, and region and Region are the same field. Weaviate's own names it compares exactly; refusing ID or Vector too is deliberately stricter, so that no field has a name easily confused with one of them.

The platform applies the same rule when a field is added to a Knowledge Base: on create and edit it answers 422, and on import it answers 400.

A field stored before this check existed is left as it is:

• It stays editable. Saving the Knowledge Base's settings in Studio resends every stored field unchanged, and that save is accepted. Only a newly added field is checked, and it must not clash with any stored one.
• A Knowledge Base that holds such a field cannot be carried in a Package. Exporting it from Studio into a Package fails with PORTABLE_DEFINITION_INVALID, naming the field.
• A Knowledge Base export file that holds such a field cannot be imported. Remove or rename the field in the file first.

Chunking is not part of the definition

Chunking strategy, chunk_size and overlap are chosen per document, at upload, by whoever uploads it. A Knowledge Base has no chunking settings of its own, and because a Package carries no documents, there is nothing to put them on. See Chunking strategies in the user guide.

The Slots it needs

slots:
  - id: embedding
    type: llm
    required: true
    description: The model used to index and search your documents.
    boundTo: [knowledgeBases.product-docs]
  - id: product-documents
    type: knowledge-source
    required: true
    description: Your own product documentation.
    boundTo: [knowledgeBases.product-docs]

At install

• The installer chooses the embedding model, then uploads files, connects a source (for example, a web page crawled with the pages under it), or skips.
• A skipped Knowledge Base is created empty and listed as outstanding. An empty Knowledge Base answers nothing, which looks like a broken Package, so the warning stays on the Package's page until it has content.
• Packages with Knowledge Bases install into a project, not the Organization level.

Link it to Agents with config.knowledge.knowledge_bases: [knowledgeBases.<name>] in the Agent's definition. See Knowledge Bases for a walkthrough.