Table of Contents

Creating Knowledge Units

Learn how to create and manage knowledge units in the Management Portal.

Overview

A knowledge unit links indexed content to the vector database that stores it. Data pipeline embedding and indexing stages reference a knowledge unit, and knowledge sources group knowledge units so agents and the Knowledge Explorer can query them.

A knowledge unit defines:

  • The vector database that stores the text embeddings. The vector database holds the embedding model, dimensions, and index schema. See Creating Vector Databases.
  • Optionally, the vector store ID: the logical partition within that vector database.
  • Optionally, a knowledge graph and the vector database that stores its embeddings.

Prerequisites

  • The Knowledge Units Contributor role at the instance scope, so the Create Knowledge Unit button is shown.
  • At least one vector database.

Knowledge Units List

In the sidebar, select Data > Knowledge Units.

Column Description
Name The knowledge unit name.
Description The description.
Actions View JSON definition ({}), Edit (pencil), and Delete (trash).

Use Search knowledge units to filter by name or description, and the refresh button to reload the list. The list shows ten items per page by default.

Create a Knowledge Unit

  1. On the Knowledge Units page, select Create Knowledge Unit.

  2. Fill in the form:

    Field Description
    Knowledge Unit name Letters, numbers, dashes, and underscores only. A check or x icon shows whether the name is available.
    Description Helps others understand the knowledge unit's purpose.
    Vector Database Required. The vector database associated with this knowledge unit.
    Vector Store ID Optional. The identifier of the vector store within the selected vector database. If not specified, queries must provide it explicitly. When you enter a value, the portal checks it against the selected vector database and shows a check or x icon.
    Has Knowledge Graph Turn on if this knowledge unit also has an associated knowledge graph.
    Knowledge Graph Vector Database Shown when Has Knowledge Graph is on. The vector database used to store knowledge graph embeddings. The vector store within it is always named after the knowledge unit.

  3. Select Create Knowledge Unit.

If the name or vector database is missing, or the name or vector store ID is invalid, a warning explains what to fix. After saving, you return to the list. Select Cancel to return to the list without saving.

Use a Knowledge Unit in a Data Pipeline

Embedding and indexing stage plugins have a KnowledgeUnitObjectId parameter. On the pipeline canvas, select the stage and choose the knowledge unit from the parameter's dropdown. For example:

Stage plugin Knowledge unit parameter Other parameters
Gateway Text Embedding Data Pipeline Stage (FoundationaLLM) KnowledgeUnitObjectId: provides the embedding configuration. EmbeddingRequestSizeTokens
Azure AI Search Indexing Data Pipeline Stage (FoundationaLLM) KnowledgeUnitObjectId VectorStoreId: the logical partition of the Azure AI Search index.
Knowledge graph embedding, indexing, and publishing stages KnowledgeUnitObjectId None

Use the same knowledge unit for the embedding and indexing stages of a pipeline so the embeddings match the target index.

See Creating Data Pipelines.

Edit a Knowledge Unit

  1. Select the Edit (pencil) icon in the list.
  2. The Edit Knowledge Unit page opens. The name cannot be changed after creation.
  3. Update the settings and select Save Changes.

When editing, select Access Control at the top right to manage role assignments on the knowledge unit.

Delete a Knowledge Unit

Select the Delete (trash) icon, then select Yes in the Delete Knowledge Unit dialog.

Warning: Knowledge sources and pipeline stages that reference the knowledge unit can no longer use it after it is deleted. Check those references first.

Troubleshooting

  • The Vector Store ID shows an x icon: The vector store ID isn't valid for the selected vector database. Hover over the icon for the reason.
  • Embedding dimension mismatch errors in a pipeline: The embedding model and dimensions come from the vector database. Check the vector database settings and that the embedding and indexing stages use the same knowledge unit.
  • Knowledge graph options are disabled in Knowledge Explorer: Turn on Has Knowledge Graph and select a Knowledge Graph Vector Database.