Build An Assistant That Answers From Your Documents
This guide builds an Assistant that answers staff questions from your own documents, rather than from what the model learned in training. In this example we will build HR Helper, which answers questions about leave, expenses and conduct from a staff handbook. The same steps work for product manuals, IT procedures or any other set of documents.
By the end of this guide you will have a Knowledge Base holding the documents, and an Assistant in Optima Chat that searches it for every question and says when the documents do not cover something.
Before You Start
You will need the following:
- You have the Knowledge Base and Assistants permissions.
- A chat model is running. See Adding Models.
- You have the documents: PDF, Word, Excel, PowerPoint, HTML and Markdown all work.
1. Start An Embedding Model
Searching documents by meaning needs an embedding model running on a Node. Every Node includes Optima Built-in Embeddings, which runs on the CPU: start it in the Node's Executors panel. A dedicated embedding model, downloaded to a Node, finds passages more accurately. You can switch to one later.
See Knowledge Bases.
2. Create The Knowledge Base
The Knowledge Base holds your documents, split into passages that can be searched by meaning.
- Open Knowledge from the menu and click New Knowledge Base.
- Enter a Name — for example, Staff Handbook.
-
Enter a Description, written for the AI. Models read it to decide whether to search this Knowledge Base, so say what is in it and what it answers. For example:
Example Ltd's staff handbook: annual leave, sickness, expenses, onboarding, working from home and the code of conduct, for UK staff. -
Choose the Embedding model and click Create.
- On the Documents tab, click Add documents and choose the files.
Each document will be converted, split into passages and indexed in the background. Wait until every document shows it is done.
Tip
One subject per Knowledge Base works best. A Knowledge Base that mixes HR policy with product manuals will return loosely related passages for both.
3. Check It Finds The Right Passages
Before anyone relies on the Knowledge Base, ask it the questions people will ask.
- Open the Search tab.
- Type a real question — for example, How many days of annual leave do I get? — and search By meaning.
- Check the top results are the passages that answer it.
If a document never comes up, check it indexed without errors, and that its text is not a scanned image. If the right passage is there but scores below the line, tick Show all scores to see where it falls. See Search.
4. Create The Assistant
Next, create the Assistant that people will choose in Optima Chat.
- Open Assistants and click New Assistant.
- Enter a Name — HR Helper. The Reference will fill in as
hr-helper. It cannot be changed later. - Add a Description, written for people choosing an Assistant in Optima Chat: Answers questions about leave, expenses and other HR policies.
- Choose a Model and click Create.
Then work through its tabs, clicking Save on each.
Behaviour
Under Instructions, tell the Assistant what it is for and how to behave. For example:
You are HR Helper for Example Ltd. You answer staff questions about leave,
expenses, onboarding and conduct, using the Staff Handbook.
- Answer only from the handbook passages you are given or find by searching.
If the handbook does not cover the question, say so, and suggest contacting
hr@example.com.
- Name the policy you used, such as "Annual Leave Policy, section 3".
- Give the direct answer first, then any conditions or exceptions.
- Do not give legal advice, and do not discuss individual employees.
Short, direct instructions work better than long ones. Say what to do when the answer is not in the documents. Without that, a model may fill the gap from its general knowledge, which for policy questions is usually wrong.
Under Inference, set Temperature low — 0.3 keeps answers close to the wording of the documents.
Model
Add a Fallback if you have a second chat model, so the Assistant keeps answering while its main model is restarted.
Knowledge
- Tick Staff Handbook.
- Tick Add relevant passages automatically.
With that on, Optima will search the handbook for every message and give the model the closest passages before it answers. That suits an Assistant whose whole job is the documents. Without it, the model searches only when it decides to.
Tools
Under Also allow, leave AI memory off. HR Helper should answer from the handbook, not from what someone said in another conversation.
Access
- Under Available in, tick Chat.
- Give access to the people who should use it: search for them, or click Give everyone access…. Tick Give new users access so that people who join later get it too.
People can use the handbook through HR Helper without being given access to the Knowledge Base itself.
5. Try It In Optima Chat
Open Optima Chat, choose HR Helper on the welcome screen, and ask the questions you tried on the Search tab. Then ask something the handbook does not cover — for example, What is the CEO's salary? — and check it says it does not know.
Making It Better
If the Assistant does not answer as you expect, the table below lists the usual causes.
| Problem | What to do |
|---|---|
| It answers from general knowledge instead of the handbook | Make the instructions firmer: "Answer only from the handbook". Lower the temperature |
| It misses passages that are there | Try the question on the Search tab. If the passage scores low, lower the Auto-inject threshold on the Retrieval tab a little, or rebuild with a better embedding model |
| It brings in passages that do not help | Raise the Auto-inject threshold, or split the documents into Knowledge Bases by subject |
| A policy has changed | Delete the old document and add the new one. The old passages will stop being found straight away |
Going Further
Once the Assistant is working, you can extend it:
- Use it from other applications. Tick API under Available in, and an application can call HR Helper as
assistant:hr-helper. See Connect an OpenAI-Compatible App. - Make it the only way in. Settings → Assistants → Only allow assistants stops people chatting with models directly, so every conversation runs with instructions and knowledge you chose. See Settings for every assistant.
- Let it act, not just answer. Give it tools that look things up or make changes. See Build an Assistant That Acts, With Permission.