> 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/evaluate-retrieval.md).

# Evaluate retrieval

Evaluate searches a knowledge base directly. Use it to inspect which source passages a query retrieves and how search settings affect the results.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2Fj3F04vpioCvuNyF6V1PS%2FG043.mp4?alt=media&token=9bea87bf-0e03-4f26-b85f-503611ebffd3>" %}

## Before you start

Open a knowledge base containing **Indexed** documents. Choose a question with an answer you can locate in an original source. Follow [Create a knowledge base](https://docs.stackai.com/guides-and-quickstarts/knowledge-and-retrieval/create-a-knowledge-base.md) if the collection is not ready.

## Start with a search question

In Evaluate, enter a question and inspect a returned passage and its source.

![Knowledge base query and results](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/W4E73dbXbrq0uTbJsUXO/assets/g043-g043-01-baseline.png)

Start with information you can locate in the documents so you can judge relevance directly.

## Set the result limit

Open Advanced Settings and adjust Top K while retaining the search method.

![Retrieval result limit setting](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/OIEieaKMrtNZfmb31NAo/assets/g043-g043-02-top-k.png)

Top K sets the maximum number of results. It does not guarantee that many results.

## Choose a search method

Choose Keyword when you need to compare literal term matching.

![Retrieval search method selection](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/3JL1l3GbOaM4Cn7zPfsM/assets/g043-g043-03-keyword.png)

Apply the setting and inspect the passages returned for the exact term.

Switch to Hybrid and run the same query to compare results.

![Retrieval search method selection](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/0NvG5xdrvgll9FwsciLS/assets/g043-g043-04-hybrid.png)

Evaluate the usefulness of the passages rather than treating scores from different methods as interchangeable.

## Choose the retrieval unit and order

Choose Documents as the retrieval unit when comparing document-level results.

![Retrieval unit and sorting options](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/RAPhsPY44fPD8sw8mhYU/assets/g043-g043-05-documents.png)

Use sources with enough content to understand how this differs from returning individual chunks.

Open Filters to inspect sorting by score or chunk.

![Retrieval unit and sorting options](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/WKRQsDQDLbaru8ZeI9lr/assets/g043-g043-06-sort.png)

The order can change what you see first without changing the question you submitted.

Choose Pages to inspect page-based retrieval results.

![Retrieval unit and sorting options](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/IxwBYO6rta5qq3gmYL2w/assets/g043-g043-07-pages.png)

Check the page labels against the source, especially when a document has several pages.

## Reset evaluator settings

Select Reset, then Apply to return the evaluator to its default settings.

![Retrieval evaluator reset controls](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/5G8qnTPh7bTJU1FaqORf/assets/g043-g043-08-reset.png)

Run the query again to see results with those settings.

## Important behavior

Top K is a maximum result count. The search may return fewer results.

Scores from different search methods are not directly interchangeable. Compare the relevance of the returned content.

Evaluate settings apply to the evaluator. Configure workflow search parameters separately.

## Continue

* [Metadata filters](https://docs.stackai.com/guides-and-quickstarts/knowledge-and-retrieval/metadata-filters.md)
* [Inspect knowledge base references](https://docs.stackai.com/guides-and-quickstarts/knowledge-and-retrieval/inspect-knowledge-base-references.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/evaluate-retrieval.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.
