> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iblueprint.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Build a Searchable Knowledge Base: A Learning Lab
> A hands-on workshop for turning approved source material into reliable, searchable context for Blueprint workflows and Chatbots.
> **Time required:** 25–40 minutes
**You will build:** a small, focused Knowledge Base that answers policy questions with evidence from approved documents.
This lab teaches the reasoning behind a good Knowledge Base: choosing the right source, preparing content, checking processing, testing retrieval, and deciding what can be shared. The goal is not to upload as much as possible. The goal is to make the right evidence easy to find.
## What you will learn
You will practice how to:
* Choose a clear purpose and boundary for a Knowledge Base.
* Separate source content from instructions.
* Add documents or connected sources in the workspace Knowledge Base area.
* Check vectorization and processing before using the content.
* Test retrieval with questions that should and should not have answers.
* Improve source quality instead of hiding weak retrieval with a larger model.
* Connect approved knowledge to a Blueprint or Chatbot.
* Decide whether a resource should remain private, be shared with an organization, or be published for public reuse.
## Before you start
You need:
* A Blueprint account and permission to create or edit Knowledge Bases in a workspace.
* Two or three synthetic or approved documents about one topic.
* An active AI connection if you plan to test through a Blueprint or Chatbot.
* A short list of questions with known answers.
Do not upload secrets, private customer records, regulated data, or material you do not have permission to share. For this lab, create a tiny practice set such as support-policy.md, account-security.md, and escalation-contacts.md.
## The learning challenge
Build a Knowledge Base that answers these questions:
1. What should a support agent do when a customer asks to delete an account?
2. When must a request be escalated to a human?
3. Which actions require identity verification?
It should also refuse or ask for clarification when the answer is not in the source material.
> **Why this matters:** Retrieval quality is a product decision. A Knowledge Base is trustworthy only when its sources are current, authorized, findable, and clear about what they do not cover.
## Lab 1: Start from the workspace Knowledge Base area
Open the signed-in workspace and select **Org Knowledge** or **Knowledge Base**. You can also use [Open knowledge bases](https://app.iblueprint.ai/my-org/knowledge-base).
Use the workspace Knowledge Base area for content your organization owns or manages. Public Data Sources and Public Libraries are useful for discovery and reuse, but they are not substitutes for a private, controlled source set.
On the Knowledge Bases page, look for:
* Existing Knowledge Bases and their visibility.
* Document set count and document count.
* Processing or vectorization status.
* The **New KB** action.
### Pause and decide the boundary
Write one sentence:
> This Knowledge Base is the approved source for \_\_\_\_\_\_\_\_, and it does not cover \_\_\_\_\_\_\_\_.
If the sentence contains several unrelated subjects, create separate Knowledge Bases or document sets. Narrow boundaries make testing and governance easier.
## Lab 2: Create the Knowledge Base
1. Select **New KB**.
2. Give it a name a teammate can understand, such as **Support Policy — Practice**.
3. Add a description that says who should use it and what it contains.
4. Choose the narrowest visibility that supports the lab.
5. Create the Knowledge Base.
Use organization visibility only when the source is approved for organization-wide access. Keep a practice or draft resource private until its content and retrieval behavior are reviewed.
## Lab 3: Add a document set
Open the new Knowledge Base and find **Document Sets**.
1. Select the plus button.
2. Create a focused folder or document set if that helps you separate policies from reference material.
3. Add one source at a time.
4. Record the source name, owner, last-reviewed date, and intended audience.
The source options available in the workspace may include:
* **Upload Files** for documents you already have.
* **Add Text** for a small, controlled piece of content.
* **Add JSON** for structured records.
* **Add API Endpoint** for a source maintained elsewhere.
* **Connect Git Repo** for versioned documentation.
* **Add SQLite DB** for an approved local data source.
* **Link Cloud Storage** for an approved storage location.
* **Spider Website** when a website is the maintained source.
Only use a source type that is visible and approved in your workspace. Connected sources introduce another permission, retention, and freshness boundary.
## Lab 4: Prepare content that retrieves well
Before you upload, improve the source:
* Use descriptive headings.
* Put one decision or procedure in each section.
* Define acronyms the first time they appear.
* Keep policy language direct and consistent.
* Put exceptions next to the rule they qualify.
* Include an owner and review date.
* Remove navigation menus, repeated footers, tracked changes, and stale copies.
* Remove secrets and personal data that the model should never see.
For a practice file, use a structure like this:
```markdown theme={null}
# Account deletion requests
## Standard handling
Verify the requester using the approved account-security procedure.
Do not claim that an account has been deleted until the authorized system confirms completion.
## Human escalation
Escalate when the requester cannot complete verification, asks for an exception,
or the request involves legal hold, fraud, or a security incident.
## Last reviewed
2026-01-15
Owner: Support Operations
```
> **Learning check:** If a reader can understand the rule without seeing the rest of the file, retrieval is more likely to return a useful passage.
## Lab 5: Wait for processing and vectorization
After adding content, wait for processing to finish. Documents are extracted, split into searchable chunks, and embedded for retrieval.
Check:
* The document appears in the intended document set.
* Processing completes successfully.
* The Knowledge Base reports a usable or vectorized state.
* Failed documents have a useful error message.
* The source permissions still match the intended audience.
Do not connect an unfinished Knowledge Base to a production Chatbot. A successful upload is not the same as a searchable source.
## Lab 6: Test retrieval before using an AI answer
Use questions whose answers you can locate in the source. Start with exact questions, then try natural variations.
### Question set
```text theme={null}
What should an agent do if the customer cannot complete identity verification?
Can an agent promise that an account was deleted before the authorized system confirms it?
What is the escalation path for a request involving fraud?
What is the office lunch menu next Tuesday?
```
The first three should retrieve evidence. The last question should produce no supported answer.
For every test, record:
* The question.
* The passage or source returned.
* Whether the passage actually supports the answer.
* Whether the source name or citation is available.
* Whether the result exposes content the user should not see.
> **Do not reward a confident guess.** A polished answer without supporting source content is a retrieval failure, not a success.
## Lab 7: Improve retrieval one variable at a time
If results are weak, change one thing and rerun the same questions:
* Rewrite a vague heading.
* Split an oversized document into focused sections.
* Remove duplicated or stale versions.
* Add missing terms and synonyms.
* Fix malformed JSON or unreadable scanned text.
* Review document-set chunk settings when the workspace exposes them.
* Check that the executing user or deployment can access the source.
* Re-index after changing the embedding model or provider.
Do not change the model, source content, chunking, and permissions all at once. You want to know which change improved retrieval.
## Lab 8: Connect the source to a Blueprint or Chatbot
Once retrieval is reliable:
1. Open the Blueprint or Chatbot that needs the source.
2. Select the Knowledge Base or document set in the relevant configuration.
3. Pass only the user question and necessary context into retrieval.
4. Instruct the answer step to cite supported material and refuse unsupported claims.
5. Keep writes, messages, and other external actions behind a human checkpoint.
6. Test with the same question set again in the actual workflow.
A Knowledge Base provides context; it does not automatically grant permission to perform an action. Keep tool access and Knowledge Base access separate in your review.
## Lab 9: Decide how to share the resource
Use the smallest audience that supports the outcome:
* **Private:** draft content, sensitive material, or a source under review.
* **Organization:** approved content for teammates who need it.
* **Public reuse:** content intentionally prepared for Public Libraries or a public-facing asset.
Before sharing or publishing, confirm:
* You own or are allowed to redistribute every source.
* The source contains no secrets or unnecessary personal information.
* The owner and review date are clear.
* The intended audience understands the limits.
* A stale-source or deletion process exists.
* A Chatbot or Blueprint will not reveal restricted context through citations or summaries.
Publicly reusable content should be a curated derivative, not a raw export of an internal drive.
## Lab 10: Test the failure modes
Try these controlled failures:
* Ask a question outside the source boundary.
* Use a synonym that does not appear in the document.
* Remove one source and rerun a question that depended on it.
* Ask for a secret or private record that should not be returned.
* Change the active version or permission and compare results.
* Add a document with an intentionally unreadable or unsupported format.
For each failure, decide whether the right response is:
* A grounded answer with a citation.
* A refusal because no evidence exists.
* A request for clarification.
* A permission or ingestion fix.
* A human escalation.
## Completion check
You are finished when:
* The Knowledge Base has a clear purpose and owner.
* The source set is small enough to review.
* Processing and vectorization complete successfully.
* Known-answer questions retrieve the right evidence.
* An out-of-scope question does not produce an invented answer.
* The connected Blueprint or Chatbot cites approved context.
* Access, retention, and sharing decisions are documented.
* You know how to replace stale content and re-index safely.
## If your result is not what you expected
* **No results:** check processing status, source permissions, indexing, query wording, and document-set filters.
* **Wrong results:** remove duplicates, sharpen headings, split unrelated topics, and test one source at a time.
* **Outdated answers:** identify the stale source, remove or replace it, and re-index before retesting.
* **No citation:** verify that source metadata is passed into the answer step and that the prompt requires evidence-backed citations.
* **Private content appears:** stop the deployment, review permissions and document-set membership, and remove the content from the response path.
* **A connected source fails:** inspect credentials, endpoint access, rate limits, source format, and the last successful sync.
## Next practice
Use this Knowledge Base in [Build and Publish a Grounded Chatbot: A Learning Lab](https://docs.iblueprint.ai/guides-and-learning/build-and-publish-a-grounded-chatbot) or connect it to [Blueprint Workshop: Build, Test, and Improve a Workflow](https://docs.iblueprint.ai/guides-and-learning/blueprint-workshop-build-test-and-improve).