Home

Awesome

dsRAG

Discord

Note: If you’re using (or planning to use) dsRAG in production, please fill out this short form telling us about your use case. This helps us prioritize new features. In return I’ll give you my personal email address, which you can use for priority email support.

What is dsRAG?

dsRAG is a retrieval engine for unstructured data. It is especially good at handling challenging queries over dense text, like financial reports, legal documents, and academic papers. dsRAG achieves substantially higher accuracy than vanilla RAG baselines on complex open-book question answering tasks. On one especially challenging benchmark, FinanceBench, dsRAG gets accurate answers 83% of the time, compared to the vanilla RAG baseline which only gets 19% of questions correct.

There are three key methods used to improve performance over vanilla RAG systems:

  1. Semantic sectioning
  2. AutoContext
  3. Relevant Segment Extraction (RSE)

Semantic sectioning

Semantic sectioning uses an LLM to break a document into sections. It works by annotating the document with line numbers and then prompting an LLM to identify the starting and ending lines for each “semantically cohesive section.” These sections should be anywhere from a few paragraphs to a few pages long. The sections then get broken into smaller chunks if needed. The LLM is also prompted to generate descriptive titles for each section. These section titles get used in the contextual chunk headers created by AutoContext, which provides additional context to the ranking models (embeddings and reranker), enabling better retrieval.

AutoContext (contextual chunk headers)

AutoContext creates contextual chunk headers that contain document-level and section-level context, and prepends those chunk headers to the chunks prior to embedding them. This gives the embeddings a much more accurate and complete representation of the content and meaning of the text. In our testing, this feature leads to a dramatic improvement in retrieval quality. In addition to increasing the rate at which the correct information is retrieved, AutoContext also substantially reduces the rate at which irrelevant results show up in the search results. This reduces the rate at which the LLM misinterprets a piece of text in downstream chat and generation applications.

Relevant Segment Extraction

Relevant Segment Extraction (RSE) is a query-time post-processing step that takes clusters of relevant chunks and intelligently combines them into longer sections of text that we call segments. These segments provide better context to the LLM than any individual chunk can. For simple factual questions, the answer is usually contained in a single chunk; but for more complex questions, the answer usually spans a longer section of text. The goal of RSE is to intelligently identify the section(s) of text that provide the most relevant information, without being constrained to fixed length chunks.

For example, suppose you have a bunch of SEC filings in a knowledge base and you ask “What were Apple’s key financial results in the most recent fiscal year?” RSE will identify the most relevant segment as the entire “Consolidated Statement of Operations” section, which will be 5-10 chunks long. Whereas if you ask “Who is Apple’s CEO?” the most relevant segment will be identified as a single chunk that mentions “Tim Cook, CEO.”

Eval results

We've evaluated dsRAG on a couple of end-to-end RAG benchmarks.

FinanceBench

First, we have FinanceBench. This benchmark uses a corpus of a few hundred 10-Ks and 10-Qs. The queries are challenging, and often require combining multiple pieces of information. Ground truth answers are provided. Answers are graded manually on a pass/fail basis. Minor allowances for rounding errors are allowed, but other than that the answer must exactly match the ground truth answer to be considered correct.

The baseline retrieval pipeline, which uses standard chunking and top-k retrieval, achieves a score of 19% according to the paper. dsRAG, using default parameters and AutoQuery for query generation, achieves a score of 83%.

KITE

We couldn't find any other suitable end-to-end RAG benchmarks, so we decided to create our own, called KITE (Knowledge-Intensive Task Evaluation).

KITE currently consists of 4 datasets and a total of 50 questions.

Ground truth answers are included with each sample. Most samples also include grading rubrics. Grading is done on a scale of 0-10 for each question, with a strong LLM doing the grading.

We tested four configurations:

Testing RSE and CCH on their own, in addition to testing them together, lets us see the individual contributions of those two features.

Cohere English embeddings and the Cohere 3 English reranker were used for all configurations. LLM responses were generated with GPT-4o, and grading was also done with GPT-4o.

Top-kRSECCH+Top-kCCH+RSE
AI Papers4.57.94.77.9
BVP Cloud2.64.46.37.8
Sourcegraph5.76.65.89.4
Supreme Court Opinions6.18.07.48.5
Average4.726.736.048.42

Using CCH and RSE together leads to a dramatic improvement in performance, from 4.72 -> 8.42. Looking at the RSE and CCH+Top-k results, we can see that using each of those features individually leads to a large improvement over the baseline, with RSE appearing to be slightly more important than CCH.

To put these results in perspective, we also tested the CCH+RSE configuration with a smaller model, GPT-4o Mini. As expected, this led to a decrease in performance compared to using GPT-4o, but the difference was surprisingly small (7.95 vs. 8.42). Using CCH+RSE with GPT-4o Mini dramatically outperforms the baseline RAG pipeline even though the baseline uses a 17x more expensive LLM. This suggests that the LLM plays a much smaller role in end-to-end RAG system accuracy than the retrieval pipeline does.

CCH+RSE (GPT-4o)CCH+RSE (GPT-4o Mini)
AI Papers7.97.0
BVP Cloud7.87.9
Sourcegraph9.48.5
Supreme Court Opinions8.58.4
Average8.427.95

Note: we did not use semantic sectioning for any of the configurations tested here. We'll evaluate that one separately once we finish some of the improvements we're working on for it. We also did not use AutoQuery, as the KITE questions are all suitable for direct use as search queries.

Tutorial

Installation

To install the python package, run

pip install dsrag

Quickstart

By default, dsRAG uses OpenAI for embeddings and AutoContext, and Cohere for reranking, so to run the code below you'll need to make sure you have API keys for those providers set as environmental variables with the following names: OPENAI_API_KEY and CO_API_KEY. If you want to run dsRAG with different models, take a look at the "Basic customization" section below.

You can create a new KnowledgeBase directly from a file using the create_kb_from_file helper function:

from dsrag.create_kb import create_kb_from_file

file_path = "dsRAG/tests/data/levels_of_agi.pdf"
kb_id = "levels_of_agi"
kb = create_kb_from_file(kb_id, file_path)

KnowledgeBase objects persist to disk automatically, so you don't need to explicitly save it at this point.

Now you can load the KnowledgeBase by its kb_id (only necessary if you run this from a separate script) and query it using the query method:

from dsrag.knowledge_base import KnowledgeBase

kb = KnowledgeBase("levels_of_agi")
search_queries = ["What are the levels of AGI?", "What is the highest level of AGI?"]
results = kb.query(search_queries)
for segment in results:
    print(segment)

Basic customization

Now let's look at an example of how we can customize the configuration of a KnowledgeBase. In this case, we'll customize it so that it only uses OpenAI (useful if you don't have API keys for Anthropic and Cohere). To do so, we need to pass in a subclass of LLM and a subclass of Reranker. We'll use gpt-4o-mini for the LLM (this is what gets used for document and section summarization in AutoContext) and since OpenAI doesn't offer a reranker, we'll use the NoReranker class for that.

from dsrag.llm import OpenAIChatAPI
from dsrag.reranker import NoReranker

llm = OpenAIChatAPI(model='gpt-4o-mini')
reranker = NoReranker()

kb = KnowledgeBase(kb_id="levels_of_agi", reranker=reranker, auto_context_model=llm)

Now we can add documents to this KnowledgeBase using the add_document method. Note that the add_document method takes in raw text, not files, so we'll have to extract the text from our file first. There are some utility functions for doing this in the document_parsing.py file.

from dsrag.document_parsing import extract_text_from_pdf

file_path = "dsRAG/tests/data/levels_of_agi.pdf"
text = extract_text_from_pdf(file_path)
kb.add_document(doc_id=file_path, text=text)

Architecture

KnowledgeBase object

A KnowledgeBase object takes in documents (in the form of raw text) and does chunking and embedding on them, along with a few other preprocessing operations. Then at query time you feed in queries and it returns the most relevant segments of text.

KnowledgeBase objects are persistent by default. The full configuration needed to reconstruct the object gets saved as a JSON file upon creation and updating.

Components

There are five key components that define the configuration of a KnowledgeBase, each of which are customizable:

  1. VectorDB
  2. ChunkDB
  3. Embedding
  4. Reranker
  5. LLM
  6. FileSystem

There are defaults for each of these components, as well as alternative options included in the repo. You can also define fully custom components by subclassing the base classes and passing in an instance of that subclass to the KnowledgeBase constructor.

VectorDB

The VectorDB component stores the embedding vectors, as well as a small amount of metadata.

The currently available options are:

ChunkDB

The ChunkDB stores the content of text chunks in a nested dictionary format, keyed on doc_id and chunk_index. This is used by RSE to retrieve the full text associated with specific chunks.

The currently available options are:

Embedding

The Embedding component defines the embedding model.

The currently available options are:

Reranker

The Reranker components define the reranker. This is used after the vector database search (and before RSE) to provide a more accurate ranking of chunks.

The currently available options are:

LLM

This defines the LLM to be used for document title generation, document summarization, and section summarization in AutoContext.

The currently available options are:

FileSystem

This defines the file system to be used for saving PDF images.

For backwards compatibility, if an existing KnowledgeBase is loaded in, a LocalFileSystem will be created by default using the storage_directory. This is also the behavior if no FileSystem is defined when creating a new KnowledgeBase.

The currently available options are:

Usage: For the LocalFileSystem, only a base_path needs to be passed in. This defines where the files will be stored on the system For the S3FileSystem, the following parameters are needed:

The base_path is used when downloading files from S3. The files have to be stored locally in order to be used in the retrieval system.

Config dictionaries

Since there are a lot of configuration parameters available, they're organized into a few config dictionaries. There are four config dictionaries that can be passed in to add_document (auto_context_config, file_parsing_config, semantic_sectioning_config, and chunking_config) and one that can be passed in to query (rse_params).

Default values will be used for any parameters not provided in these dictionaries, so if you just want to alter one or two parameters there's no need to send in the full dictionary.

auto_context_config

file_parsing_config

semantic_sectioning_config

chunking_config

rse_params

Metadata query filters

Certain vector DBs support metadata filtering when running a query (currently only ChromaDB). This allows you to have more control over what document(s) get searched. A common use case for this would be asking questions over a single document in a knowledge base, in which case you would supply the doc_id as a metadata filter.

The format of the metadata filtering is an object with the following keys:

Example

# Filter with the "equals" operator
metadata_filter = {
    "field": "doc_id",
    "operator": "equals",
    "value": "test_id_1"
}

# Filter with the "in" operator
metadata_filter = {
    "field": "doc_id",
    "operator": "in",
    "value": ["test_id_1", "test_id_2"]
}

Document upload flow

Documents -> semantic sectioning -> chunking -> AutoContext -> embedding -> chunk and vector database upsert

Query flow

Queries -> vector database search -> reranking -> RSE -> results

Community and support

You can join our Discord to ask questions, make suggestions, and discuss contributions.

If you’re using (or planning to use) dsRAG in production, please fill out this short form telling us about your use case. This helps us prioritize new features. In return I’ll give you my personal email address, which you can use for priority email support.

Private cloud deployment

If you want to run dsRAG in production with minimal effort, reach out to us about our commercial offering, which is a managed private cloud deployment of dsRAG.

Here are the high-level details of the offering:

Private cloud deployment (i.e. in your own AWS, Azure, or GCP account) of dsRAG.

Support

If this is something you’d like to learn more about, fill out this short form and we’ll reach out ASAP.