> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/guides-and-quickstarts/knowledge-and-retrieval/create-a-knowledge-base.md).

# Create a knowledge base

A knowledge base stores indexed source content for retrieval. Agents and workflows can search it for passages relevant to a request.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FPhB5k5Try0w9lzz5988E%2FG036.mp4?alt=media&token=75440233-5e23-4111-87d7-02530648dd42>" %}

## Before you start

Have permission to create a knowledge base and a small, representative set of source files you are allowed to use. Start with a few documents whose answers you can check before importing the whole collection. For files maintained in another service, use [Import selected Google Drive files](/guides-and-quickstarts/knowledge-and-retrieval/import-selected-google-drive-files.md) or [Import from an external source](/guides-and-quickstarts/knowledge-and-retrieval/import-from-an-external-source.md) as appropriate.

Keep the preselected processing values for an initial configuration unless your organization specifies a configuration. Enable OCR if important text appears only in scans or images. Read [Chunking, OCR, and embedding settings](/guides-and-quickstarts/knowledge-and-retrieval/chunking-ocr-and-embedding-settings.md) before the first upload: chunking algorithm, length, overlap, OCR, embedding provider, and embedding model become read-only once the base contains files.

## Create the knowledge base

Open Knowledge Bases and select New Knowledge Base.

![New knowledge base creation](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/gf2oWvjmIQVCSLomFWJ6/assets/g036-g036-01-create.png)

Enter a descriptive name, then create the base so you can add and manage its sources together.

## Choose processing settings

Before uploading, open More Options → Update Settings.

![Knowledge base processing settings](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/ALSe0878yTKFSqN9aRAl/assets/g036-g036-02-settings.png)

Review chunking, OCR, and the embedding model. Confirm the selected model is available in your organization before uploading. These upload settings can be configured only while the knowledge base is empty.

## Upload and process documents

Select Upload files and choose the documents you want to make searchable.

![File upload and processing status](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/e7FDe45Ddaf32mrDxlEt/assets/g036-g036-03-upload.png)

Check the filenames in the document list and allow processing to complete.

Use All Statuses to find Indexed documents and inspect any processing errors.

![File upload and processing status](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/WZ2P3r2thC5fBMtKFgFG/assets/g036-g036-04-indexed.png)

Upload completion alone does not mean that a document is ready for retrieval.

## Inspect document content

Open a document and select Parsed to inspect the extracted text.

![Document content inspection tabs](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/mXek9ioGs8jbUcUKJks5/assets/g036-g036-05-parsed.png)

Compare it with the original file, especially where tables or scanned pages contain important information.

Select Chunks to inspect the passages stored for retrieval.

![Document content inspection tabs](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/vNdRjniD8T4UBHfx40B4/assets/g036-g036-06-chunks.png)

Chunk length and overlap affect how source text is divided and how much surrounding context each passage contains.

Select Metadata to inspect the document's properties.

![Document content inspection tabs](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/9cD637RcUIYt4yCmI7zi/assets/g036-g036-07-metadata.png)

These properties can help identify the source and narrow retrieval when metadata filters are used.

## Search the indexed content

Open Evaluate, enter a question, and select Execute.

![Indexed document retrieval results](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/aj2uTmSdZUG6TGCI7105/assets/g036-g036-08-query.png)

This searches the indexed passages without generating an agent's final answer.

Expand a returned passage and check its source filename.

![Indexed document retrieval results](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/YOQrXVpYpmrLk5igJ9QU/assets/g036-g036-09-result.png)

Confirm that the passage contains the information needed to answer the question.

## If a file is not ready

For **Error**, read the error information for the file or operation and correct the reported cause before retrying. For **Pending**, allow processing to finish before running retrieval checks. Follow the [status and recovery guide](/guides-and-quickstarts/knowledge-and-retrieval/sync-and-ingestion-lifecycle.md) to distinguish a failed upload, a stale provider copy, and a retrieval problem. Use [Reindex](/guides-and-quickstarts/knowledge-and-retrieval/knowledge-base-maintenance.md) only when retrying content already present in the base.

## Important behavior

A document is ready for retrieval after indexing finishes. If its status is Error, inspect the reported processing issue.

Evaluate searches the indexed content. It does not generate an agent’s final answer.

## Continue

* [Ground an agent using a knowledge base](/guides-and-quickstarts/agent-builder-and-skills/ground-an-agent-using-a-knowledge-base.md)
* [Evaluate retrieval](/guides-and-quickstarts/knowledge-and-retrieval/evaluate-retrieval.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/guides-and-quickstarts/knowledge-and-retrieval/create-a-knowledge-base.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.