> For the complete documentation index, see [llms.txt](https://docs.blockbrain.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockbrain.ai/for-users/all-about-knowledge-management/quality-tiers-and-advanced-settings.md). # Quality tiers and advanced settings Pick a whole processing configuration in one click, or tune every individual setting yourself. What each tier is for, what it costs, and what every advanced setting does. A Smart knowledge base lets you decide how much effort goes into reading and indexing your documents. You can do that in one click with a **quality tier**, or field by field in **advanced settings**. This page covers both. If you read only one section, read the first one: the tier control is all most people need. {% hint style="info" %} Quality tiers are available where enabled for your organisation. If you do not see the control, your knowledge bases use the standard configuration, which is close to the Balanced tier described below. {% endhint %} ## Quality tiers **Where to find it:** the **Quality tier** control at the top of the knowledge base create and edit form, above the embedding model. A tier is a complete, pre-tested configuration. Pick one and every setting below is chosen for you. ### What each tier is for | Tier | In one sentence | Pick it when | | ------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Fast** | Reads and indexes your documents with no AI analysis of each passage. | You have a lot of documents, or they are mostly ordinary text, and you want them searchable quickly and cheaply. | | **Balanced** | Adds AI summaries, tags and document context to every passage. | You want the general purpose choice, and your documents include scanned PDFs, reports or contracts. | | **Precision** | Adds a knowledge graph, reads tables from an image of the page, and splits passages by meaning. | Your documents are full of complex tables and figures, or answer quality on a smaller high value collection is worth a slower and more expensive indexing run. | | **Custom** | Your own mix. You are moved here automatically as soon as you change any advanced setting. | You have a specific reason and you know which setting you are changing. | ### What you get | | Fast | Balanced | Precision | | -------------------------------------- | ------------------ | ------------------ | ---------------------------- | | AI summary and tags per passage | No | Yes | Yes | | Document context added to each passage | No | Yes | Yes | | Passage boundaries follow meaning | No, fixed size | Yes, rule based | Yes, meaning based (slowest) | | Table processing | Standard | Enhanced | Maximum | | Image and scan reading | Same on every tier | Same on every tier | Same on every tier | | Knowledge graph | No | No | Yes | | Folder scoped retrieval | No | Yes | Yes | | Reranking at query time | Yes | Yes | Yes | ### What the tiers cost The numbers below are **measured**, not estimated: the same fourteen documents were indexed on each tier, with every model held identical across the three, so the only thing that differs is the tier's settings. That is exactly how the product behaves, because **a tier changes settings, not models**. Your organisation's embedding, enrichment, vision and OCR models are used on every tier. **Your documents decide the bill far more than the tier does.** Reading a page and understanding a page are separate steps, and the reading steps (text recognition, picture reading, table reading) only run when there is something to read. **A realistic mixed collection**: two image heavy PDFs, a slide deck, two scanned pages, a photographed sign and seven wiki style text pages, 6.4 MB in all. Figures in compute blocks. | Tier | Reading images and scans | Understanding passages | Embedding | Total | Against Fast | | ------------- | ------------------------ | ---------------------- | --------- | ---------- | ------------ | | **Fast** | 9 900 | 0 | 260 | **10 200** | 1x | | **Balanced** | 9 900 | 2 200 | 520 | **13 200** | **1.3x** | | **Precision** | 11 400 | 4 200 | 1 200 | **16 700** | **1.6x** | On documents like these the three tiers land within a factor of two of each other, because **reading the images is the bulk of the bill on every tier**. On Fast it is effectively the whole bill: 97 percent went to picture and scan reading and under 3 percent to embedding. **A plain text collection**: Word files, wiki pages, emails, text only PDFs. Nothing to read visually, so those steps cost nothing and the tiers separate. | Tier | Understanding passages | Embedding | Total for the seven text pages | Against Fast | | ------------- | ---------------------- | --------- | ------------------------------ | ------------ | | **Fast** | 0 | 260 | **260** | 1x | | **Balanced** | 2 200 | 520 | **2 700** | **10x** | | **Precision** | 4 200 | 1 200 | **5 400** | **21x** | Ten times sounds dramatic, and in absolute terms it is a few thousand compute blocks for a dozen documents. The ratio is large because Fast runs no AI model over a passage at all on text, so there is almost nothing to be a multiple of. **Why Precision is not far above Balanced.** It runs one more AI call per passage (four against three) plus entity merging, and it embeds more because its chunker samples the text. At the same models that is roughly 1.3x to 2x Balanced, which is what was measured. **The model matters as much as the tier.** The figures above use a lightweight enrichment model that answers briefly. If your organisation's enrichment model is a reasoning model, one that thinks before it answers, the thinking is billed as output, and on Precision's fact extraction step it thinks at length. Measured with such a model, Balanced came out at 2.5x Fast and Precision at 9x, with 98 percent of Precision's passage cost being the model's reasoning rather than its answers. Choose a lightweight, non reasoning model for enrichment unless you have a reason not to. {% hint style="info" %} **Testing the tiers on a folder of plain text files will not tell you what they cost on your real documents.** It exercises one of the three stages and skips the two that dominate anything with images in it. Test on a sample that looks like your collection, then read the figure off your Consumption dashboard. {% endhint %} Indexing speed follows the cost. Fast indexed several thousand text documents in well under two hours, while Precision ran at roughly two documents per minute. Image heavy or scanned files are slower on every tier. **Asking questions costs the same on all three tiers.** Reranking runs on every query on every tier. Balanced and Precision add folder scoped retrieval, which is one extra search and no AI call. ### Does the most expensive tier give the best answers? Not always, and it is worth knowing this before you pay for Precision across a large collection. Measured across several public benchmarks: * **No tier wins everywhere.** Each one wins on some document types and loses on others. * **On clean, machine readable text the tiers are level.** On the easiest benchmarks all three land within a point or two of each other, and the tier control is not what decides your result. * **Precision is the stronger choice for complex tables**, because of its table reading rather than its knowledge graph. * **The knowledge graph helps precise, narrow questions and can hurt broad ones.** It improves the ordering of results when few results are considered, and can worsen it when many are. {% hint style="warning" %} **One important caveat, and it points in Precision's favour.** Those public benchmarks are built mostly from clean, machine readable text, which is exactly the material Precision's advantages cannot show up on. Reading tables from an image of the page and splitting passages by meaning have nothing to do on a tidy digital document, so it pays full cost and lands level with the cheaper tiers. If your documents are scanned, photographed, or full of complex tables and figures, the gap on **your** data can be considerably larger than the published numbers suggest. See Retrieval quality and benchmarks for why, and for how to test it on a sample of your own documents. {% endhint %} **Practical advice:** start on Balanced. Move to Fast if indexing cost or speed is the problem. Move to Precision when your documents are hard to read, or when they are full of complex tables. If you are unsure, compare Balanced and Precision on a sample of your own most awkward documents rather than relying on the benchmark tables. ### Switching tiers * **A tier changes settings, not models.** Your organisation's embedding, enrichment, vision and OCR models are used on every tier, so the tiers differ only in how much work runs over your documents. * **Changing any advanced setting moves you to Custom.** Your knowledge base keeps working exactly as configured, it is simply no longer described by a named tier. Picking a tier again replaces the settings the tier owns and leaves the rest alone. * **Switching tier does not reprocess anything by itself.** Existing documents keep their current index until you reindex or re-embed. New uploads use the new settings. ## Advanced settings reference Open **Advanced settings** on the create or edit form. While a tier is selected, these show that tier's values. The defaults work well out of the box, so it is safe to skip this section and come back later. The form has two groups, and they behave very differently. **Ingestion settings** change how documents are read, so they apply to documents added afterwards. **Retrieval settings** apply at query time, so they take effect on your very next question with no reprocessing at all. ### Ingestion settings How documents are processed when they are added. #### Chunk size and chunk overlap **Chunk size** is roughly how long each passage is, in characters. The default is 2 000, and the three quality tiers use 4 000. **Chunk overlap** is how much text is repeated between one passage and the next, so a sentence is not cut in half at a boundary. The default is 200. Smaller passages give sharper, more focused results. Larger passages give the assistant more context around each hit. Overlap must be smaller than chunk size, and the form refuses to save otherwise. #### Semantic chunking On by default. Splits passages at natural breaks in meaning, such as the end of a section or a change of topic, instead of at a fixed character count. Passages that end mid argument retrieve badly, so this is usually worth keeping on. #### Embedding based semantic chunking Off by default, and it cannot be combined with the setting above. Instead of using sentence and paragraph rules, it measures where the meaning actually shifts. More accurate boundaries, noticeably slower and more expensive. One thing to know: some embedding models can only handle one piece of text per request, and this option would then need one request per sentence. Blockbrain refuses that combination rather than letting a large document never finish. If you see that message, pick a different chunking option or a different embedding model. #### Contextual chunking On by default. Writes a short description of the whole document and puts it in front of every passage before indexing. A passage that says "the figure rose to 12 percent" is hard to find on its own. With document context it becomes findable as part of the 2024 revenue report. Costs one AI call per document, so it is cheap and usually worth it. #### Generate AI tags and summaries On by default, and this is the big one. Runs an AI model over every passage to write a summary, note what question it answers, and tag it. Those summaries then form a second way to search your documents, which helps broad questions the most. It costs three AI calls per passage. This is the single largest cost in the whole pipeline and the main difference between the Fast and Balanced tiers. If your documents are ordinary text, it is worth trying Fast first and comparing. #### Custom AI tagging prompt The instruction sent to the model when it tags a passage. Leave it empty to use the tuned default. Useful when you want tags drawn from your own vocabulary, for example your product names or your department names. #### Enrichment LLM The model that writes the summaries and tags. Pick **System default** unless you have a reason, because it affects both indexing cost and quality. Applies to documents indexed after the change, and existing documents keep the summaries the previous model wrote until you reindex. #### Vision model Reads images that sit inside your documents: charts, screenshots, diagrams and photos. It transcribes the text it can see, including table rows and numbers exactly as printed, then describes the picture, so a chart contributes its real content and not just the words "a bar chart". Set it to **Off** to run no vision model. The image is still stored and shown, it simply contributes no text to search. #### OCR model Reads page sized images: scanned pages, pages with almost no selectable text, and image files you upload such as a photographed receipt. Set it to **Off** and the vision model reads those pages instead, so their text is still extracted. Set both to Off if you want such pages stored without being read at all. #### Ingest near duplicate threshold How similar two passages have to be before one is dropped as a duplicate during indexing. `0`, the default, removes only exact duplicates. Raise it if your documents carry a lot of boilerplate, for example a legal footer on every page. #### Build knowledge graph Off by default. Extracts the facts in your documents and merges the things they mention into one entity each, so "Apple", "Apple Inc." and "AAPL" become one thing rather than three. This powers entity search and the graph view. Three things catch people out: 1. **It needs Generate AI tags and summaries switched on.** With that off no facts are extracted at all, so you would get an empty graph. 2. **Turning it on reprocesses existing documents.** Documents indexed before you enabled it have no graph until they are reindexed. 3. **It costs one extra AI call per passage**, plus entity merging per document, which makes it the second most expensive setting on this page. #### Knowledge graph LLM Shown only when **Build knowledge graph** is on. The model that extracts the facts and merges the entities, so it is the setting that decides graph quality. Because it runs once per passage it also drives cost. **Do not pick a lightweight model here.** Measured on a public benchmark, a small model produced almost no graph at all, three entities across 185 passages, and reported no error. The graph looked built and was empty. #### Table processing How much effort goes into understanding tables: **Off**, **Standard** (the default), **Enhanced** or **Maximum**. Each option does everything the one before it does and adds more, and a higher setting falls back safely, so results are never worse than the level below. This is covered in full, with a per step comparison, under **Table processing** on Smart Knowledge Bases. **A measured note, and a correction.** On a benchmark of tables in financial reports, the tier using Enhanced scored below the tiers using Standard and Maximum, and we first read that as Enhanced being the weak setting. **A direct test refuted it:** running that tier with Standard tables, everything else held identical, scored the same as it did with Enhanced. So the table setting was not what produced that gap. What stands: **Maximum leads on tables**, Standard is a sound default, and Enhanced is worth it when your documents genuinely repeat the same table layout. If tables are not your bottleneck, changing this setting alone is unlikely to move your results. ### Retrieval settings How search results are ranked at query time. **None of these require reprocessing your documents**, so they are safe to experiment with. #### Folder scoped retrieval Off by default. Ranks your folders by how well their summary and your folder description match the question, then boosts results from the best matching folders. The whole knowledge base is still searched, so files elsewhere are never excluded, only ranked lower. Turn it on when your folder structure means something, for example one folder per customer or per year. Leave it off when folders are arbitrary. An AI assistant can still override it for a single query. #### Reranker model After the first search returns candidates, a reranking model re-reads them against the question and re-orders them. Reranking is on by default and is the highest value single retrieval setting we have measured: enabling it for the cheapest tier improved direct search results on one benchmark by 26 percentage points. This setting chooses which model does that work. Pick **System default** unless you have a reason. It takes effect on the next question with no reprocessing, and if a chosen model is later withdrawn, search falls back to the system default on its own. #### Search near duplicate threshold How similar two results have to be before one is hidden as a near duplicate. The default is 0.95, and `0` disables it. #### Use knowledge graph triples in retrieval Off by default, and only useful when **Build knowledge graph** is on and your documents have been indexed with it. Lets the facts in your knowledge graph take part in ranking, and enables entity search. Measured behaviour cuts both ways, on the same documents and the same questions: * For **narrow, precise questions** it clearly helped, improving the ranking of the right answer by about 16 percentage points. * For **broad questions where an assistant considers many passages** it clearly hurt, worsening the ranking by up to 13 percentage points. It almost never changes whether the right passage is found. It changes where in the list it appears. Turn it on for a knowledge base of precise, entity heavy documents such as contracts, and leave it off for general collections. #### Triple boost vector and overlap weight How much of the ranking comes from meaning similarity against fact overlap. The two must add up to 1.0, and they are only active when the setting above is on. **Leave these at their defaults** of 0.7 and 0.3 unless you are running your own comparison. ## What a change reprocesses The practical question when editing an existing knowledge base. | Change | What happens | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Any **retrieval** setting: folder scoping, reranker model, triples, the two weights, search duplicates | **Nothing to reprocess.** Takes effect on your next question. | | **Embedding model** | **Re-embed.** Blockbrain recomputes only the vectors and keeps all extracted text, summaries, tags and graph. Much faster and cheaper than a full reindex. | | **Embedding dimensions** | **Index rebuild.** Heavier than a re-embed, and the knowledge base is briefly unsearchable. Requires the knowledge base to be idle. | | Chunk size or overlap, either semantic chunking option, contextual chunking, AI tags and summaries, the tagging prompt, table processing, build knowledge graph, or any of the enrichment, vision, OCR or graph models | **Full reindex.** The stored passages are stale and have to be regenerated. | The form warns you before saving a change that needs reprocessing, and confirms with an **Apply new settings** prompt when the quicker re-embed path is enough. ## Three recipes **"I have 5 000 mixed documents and I want them searchable this week."** Fast, and leave everything else alone. If broad questions disappoint later, put a copy on Balanced and compare. **"I have a few hundred contracts and people ask precise questions about clauses."** Balanced, plus **Build knowledge graph** and **Use knowledge graph triples in retrieval**. Choose a full size model for the graph and accept the slower indexing. **"My documents are full of complex tables and figures, or they are scans."** This is the case Precision was built for, and the one public benchmarks are worst at predicting. Trial Precision against Balanced on a sample of your most awkward documents before committing a large collection to it, and remember that on documents like these the two tiers cost within a factor of two of each other. If tables are the whole problem, Balanced with **Table processing** set to **Maximum** gets you much of the benefit for less money. --- # 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.blockbrain.ai/for-users/all-about-knowledge-management/quality-tiers-and-advanced-settings.md?ask=&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.