AutoRAGTuner: Declarative RAG Optimizer

Updated 4 July 2026

The paper demonstrates that AutoRAGTuner optimizes both pipeline architecture and hyperparameters through a declarative, configuration-driven framework.
AutoRAGTuner employs a unified Domain-Element Model and modular component registration to decouple pipeline stages and handle heterogeneous data.
The adaptive Bayesian optimization engine significantly reduces manual tuning effort while boosting performance metrics like Recall@5 and F1.

AutoRAGTuner is a declarative, configuration-driven framework for automatic optimization of retrieval-augmented generation pipelines. It is designed to automate the RAG life cycle—construction, execution, evaluation, and optimization—under the premise that RAG performance is highly sensitive to complex architecture designs and hyper-parameter configurations that otherwise rely on manual tuning (Zeng et al., 3 May 2026). The framework combines a modular component registration mechanism, a unified data abstraction called the Domain-Element Model (DEM), and an adaptive Bayesian optimization engine for end-to-end tuning across diverse pipelines, including both vanilla RAG and graph-based RAG such as HippoRAG (Zeng et al., 3 May 2026).

1. Problem setting and design objectives

AutoRAGTuner addresses three closely related difficulties in contemporary RAG engineering. First, the architectural space is combinatorial: practical systems may involve different chunking strategies, multiple retrievers, rerankers, graph-based retrieval structures, and different LLM backends and prompt formats (Zeng et al., 3 May 2026). Second, performance is highly sensitive to interacting hyperparameters such as chunk size and overlap, retrieval top- $k$ , similarity thresholds for graph construction, reranker thresholds, and graph algorithm parameters such as the PageRank damping factor (Zeng et al., 3 May 2026). Third, structural modifications typically create engineering overhead through recoupling, because changing one module often forces upstream and downstream code changes and prolonged debugging (Zeng et al., 3 May 2026).

The framework is therefore positioned not merely as a hyper-parameter tuner, but as a system for jointly handling pipeline structure and configuration. In the formulation given by the paper, AutoRAGTuner makes RAG pipelines declarative and configuration-driven, decouples pipeline stages through modular components, unifies heterogeneous data representations, and performs end-to-end Bayesian optimization over the resulting search space (Zeng et al., 3 May 2026). This differentiates it from earlier automated RAG tuning systems that optimize within a fixed pipeline structure. The paper explicitly contrasts AutoRAGTuner with AutoRAG and AutoRAG-HP, which focus on hyperparameter optimization with greedy or bandit methods and treat the pipeline structure as fixed (Kim et al., 2024, Fu et al., 2024).

A plausible implication is that AutoRAGTuner moves automated RAG optimization from a stage-local or hyperparameter-local setting to a framework-level setting in which architecture, data representation, and optimization are coupled through a common declarative interface.

2. Declarative orchestration and modular pipeline architecture

The framework’s top-level abstraction is a JSON orchestration language through which users specify pipeline stages and component wiring, data domains and relationships, and hyperparameters together with their ranges and optimization strategies (Zeng et al., 3 May 2026). The execution engine reads this configuration and builds the pipeline without hardcoded pipeline logic (Zeng et al., 3 May 2026). The paper characterizes this as an "Edit-and-Run" workflow without recompilation, with the primary purpose of reducing code churn when changing architectures or tuning configurations (Zeng et al., 3 May 2026).

Its modular architecture is organized around a component registry and a pipeline engine. Components implement unified interfaces, can be written in C++ or Python, and cover stages such as preprocessing, indexing, retrieval, graph construction, reranking, generation, and post-processing (Zeng et al., 3 May 2026). Components communicate through a unified data bus carrying DEM elements, which allows stage substitution by configuration change rather than source-level rewiring (Zeng et al., 3 May 2026).

This modularity is central to the framework’s engineering claims. The paper notes that changing from vanilla RAG to a graph-based pipeline like HippoRAG normally requires significant code refactoring, whereas AutoRAGTuner expresses such changes in configuration (Zeng et al., 3 May 2026). That emphasis on declarative specification places AutoRAGTuner in a lineage closer to directive-based or declarative auto-tuning systems than to one-off tuning scripts. In a different domain, ppOpen-AT similarly uses a directive-based language to separate tuning logic from domain logic and reduce developer effort in auto-tuning numerical libraries (Katagiri, 2024). The analogy is not exact, but it suggests a shared systems principle: expose tuning-relevant structure in a machine-readable form and generate or orchestrate the optimization workflow around that description.

3. Domain-Element Model

The Domain-Element Model is the framework’s unifying data abstraction for heterogeneous RAG objects. DEM represents every object manipulated by the pipeline as an atomic element with basic attributes such as id and weight, an extensible property set, and bidirectional pointers to other elements (Zeng et al., 3 May 2026). The model is designed to represent nodes, edges, and hyperedges, allowing the same abstraction to encode text chunks, entities, relations, synonym links, and more complex multi-hop graph structures (Zeng et al., 3 May 2026).

The paper describes a domain $D$ as a logical group of elements,

$D = \{ e_1, e_2, \dots, e_n \},$

where each element $e$ has an identifier $\text{id}(e)$ , a weight $w(e) \in \mathbb{R}$ , a property map, and parent-child pointer sets (Zeng et al., 3 May 2026). Bidirectional pointers enforce reciprocal linkage: if an element has a child, the child has that element as a parent (Zeng et al., 3 May 2026). Because an element may connect to multiple children across domains, the same mechanism can represent ordinary nodes, edges, and hyperedges (Zeng et al., 3 May 2026).

Domains are logical partitions used to organize elements and control indexing and retrieval behavior (Zeng et al., 3 May 2026). The paper’s examples include raw_docs, chunks, and entities, with relationships such as document $\rightarrow$ chunk and chunk $\rightarrow$ entity declared in JSON and materialized as edges or hyperedges in DEM (Zeng et al., 3 May 2026). This uniformity is intended to support both hierarchical data structures and graph topologies, including those used by HippoRAG for synonym relationships, entity linking, and Personalized PageRank-based retrieval (Zeng et al., 3 May 2026).

This suggests that DEM is not only a storage abstraction but also a compatibility layer between heterogeneous retrieval paradigms. By expressing both linear and graph-structured retrieval in one model, the framework reduces the amount of architecture-specific glue code required when moving between pipeline families.

4. Optimization methodology and lifecycle automation

AutoRAGTuner includes an adaptive Bayesian optimization engine that treats the full pipeline as the optimization target (Zeng et al., 3 May 2026). The configuration vector $\theta$ may include parameters from indexing, retrieval, graph construction, graph algorithms, and potentially generation, while the objective is measured after complete pipeline execution on a validation dataset (Zeng et al., 3 May 2026). This is explicitly contrasted with local tuning that optimizes only retrieval or only generation (Zeng et al., 3 May 2026).

The optimization loop consists of initial random exploration, surrogate-model-based iterative search, Expected Improvement acquisition, and stopping through either epsilon-convergence or a maximum iteration limit (Zeng et al., 3 May 2026). The paper gives the acquisition step as

$\theta_{t+1} = \arg\max_{\theta \in \mathcal{X}} a(\theta; \mathcal{D}_t),$

with Expected Improvement

$D$ 0

where $D$ 1 is the best observed configuration so far under the surrogate’s predictive distribution (Zeng et al., 3 May 2026). The framework also supports warm-start using previous runs (Zeng et al., 3 May 2026).

Its objective layer is configurable, but the paper emphasizes Recall@5 and $D$ 2 for QA tasks (Zeng et al., 3 May 2026). Recall@5 is defined over top-5 retrieved items, while $D$ 3 is described as the harmonic mean of precision and recall over token overlap between generated answer and ground truth (Zeng et al., 3 May 2026). The optimizer can in principle maximize a single metric or a composite objective such as

$D$ 4

although the empirical evaluation in the paper focuses on $D$ 5 and $D$ 6 rather than latency or cost (Zeng et al., 3 May 2026).

The framework automates the broader RAG lifecycle as well. It constructs pipelines from JSON, ingests and transforms documents into domains such as raw_docs and chunks, configures indexing and retrieval, evaluates predictions against ground truth, and iterates optimization runs until the stopping criterion is met (Zeng et al., 3 May 2026). This whole-pipeline perspective differs from AutoRAG’s greedy node-wise search, where nodes such as query expansion, retrieval, passage augmentation, reranking, prompt making, and generation are optimized sequentially with node-specific metrics (Kim et al., 2024). It also differs from AutoRAG-HP, which casts online tuning as a multi-armed bandit problem over discrete hyperparameter configurations such as top- $D$ 7, compression ratio, and embedding model (Fu et al., 2024). AutoRAGTuner instead uses Bayesian optimization over a declarative configuration space that includes architecture-level knobs (Zeng et al., 3 May 2026).

5. Supported pipeline variants and empirical evaluation

The paper demonstrates the framework on two representative RAG pipelines: vanilla RAG and graph-based HippoRAG (Zeng et al., 3 May 2026). The vanilla pipeline consists of text chunking, embedding and vector index creation, dense retrieval, and LLM generation, using Kimi-K2-Instruct-0905 as the LLM and Qwen3-Embedding-4B for embeddings and vector retrieval (Zeng et al., 3 May 2026). The tuned hyperparameters are chunk size and overlap ratio during indexing (Zeng et al., 3 May 2026).

The HippoRAG pipeline adds entity and relation extraction, graph construction, graph-based retrieval, and Personalized PageRank for multi-hop reasoning, again with Kimi-K2-Instruct-0905 and Qwen3-Embedding-4B (Zeng et al., 3 May 2026). Its tuned hyperparameters are the cosine similarity threshold for synonym relationship construction during indexing, the cosine similarity threshold for linking similar entities during retrieval, and the damping factor for Personalized PageRank (Zeng et al., 3 May 2026).

Experiments are conducted with 200 HotPotQA samples for tuning and 1000 development samples each from HotPotQA and 2WikiMultiHopQA for evaluation (Zeng et al., 3 May 2026). The compared systems are baseline and optimized variants for both vanilla and graph pipelines, labeled V-Base, V-Opt, G-Base, and G-Opt (Zeng et al., 3 May 2026). The reported aggregate improvements are consistent across both pipeline types: Recall@5 improves by 5%–8%, and $D$ 8 improves by up to 4% (Zeng et al., 3 May 2026). The paper interprets these results as evidence of architectural generality, since the same optimization machinery improves both single-hop-style and graph-based multi-hop pipelines (Zeng et al., 3 May 2026).

The framework also makes an engineering claim through a code-churn and time comparison. For comparable tuning tasks, manual tuning requires at least 1000 lines of code changes and "1 Day + 2 Weeks" for debugging and tuning, whereas AutoRAGTuner requires at most 50 lines of code changes and about 10 hours (Zeng et al., 3 May 2026). The reported interpretation is an up to 95% reduction in code churn enabled by the declarative configuration language (Zeng et al., 3 May 2026).

6. Position in the automated RAG tuning landscape

AutoRAGTuner can be situated among three related lines of work present in the literature summarized here. The first is modular, dataset-specific pipeline search. AutoRAG decomposes a RAG system into nodes—query expansion, retrieval, passage augmentation, reranking, prompt making, and generation—and performs greedy node-wise optimization using metrics such as RAGAS Context Precision and generation metrics including METEOR, ROUGE, SemScore, and G-Eval (Kim et al., 2024). Its central finding is that module quality is dataset-specific and that some modules, including query expansion and certain rerankers, can degrade performance (Kim et al., 2024). AutoRAGTuner shares the concern with modularity and dataset-specific optimization, but extends the search space to include pipeline architecture and unified data representation (Zeng et al., 3 May 2026).

The second line is online hyper-parameter adaptation. AutoRAG-HP formulates tuning as an online multi-armed bandit problem and introduces a two-level Hierarchical MAB for efficient exploration of search spaces over top- $D$ 9, prompt compression ratio, and embedding model (Fu et al., 2024). It shows that MAB-based methods can reach Recall@5 $D = \{ e_1, e_2, \dots, e_n \},$ 0 in scenarios with prominent gradients in the search space using about 20% of the LLM API calls required by grid search, and that the hierarchical method is especially effective in medium-complexity settings (Fu et al., 2024). AutoRAGTuner does not target online adaptation in that sense; rather, it provides an offline, end-to-end, declarative optimization framework using Bayesian optimization (Zeng et al., 3 May 2026). This suggests complementary scopes rather than direct redundancy.

The third line comes from auto-tuning systems outside RAG. The AMBER auto-tuning study shows that complex pipeline tuning can benefit from joint optimization rather than isolated per-stage tuning, using genetic algorithms to search a high-dimensional discrete space more efficiently than brute-force or pure random search (Mikhailov et al., 2018). ppOpen-AT, in turn, illustrates how a directive-based or declarative interface can reduce the amount of tuning logic developers write by separating domain logic from tuning logic and generating the required machinery automatically (Katagiri, 2024). AutoRAGTuner’s declarative JSON layer, modular registry, and end-to-end optimizer are consistent with these broader auto-tuning principles, although the paper’s concrete implementation is specialized to RAG pipelines (Zeng et al., 3 May 2026).

7. Limitations and future directions

The paper’s explicit emphasis is on architectural generality and engineering efficiency, but it also implies several limitations. Bayesian optimization requires multiple full pipeline runs, which can be expensive when LLM calls are costly or datasets are large (Zeng et al., 3 May 2026). The framework mitigates this by using a relatively small tuning set of 200 HotPotQA examples, epsilon-convergence, maximum iteration limits, and warm-start from previous runs (Zeng et al., 3 May 2026). Its empirical objectives are limited to Recall@5 and $D = \{ e_1, e_2, \dots, e_n \},$ 1, while latency and cost are mentioned conceptually rather than evaluated directly (Zeng et al., 3 May 2026).

The experimental scope is also bounded: only two pipeline types, vanilla RAG and HippoRAG, and two multi-hop QA datasets, HotPotQA and 2WikiMultiHopQA, are used in the reported evaluation (Zeng et al., 3 May 2026). The implementation details indicate dependence on strong backend models, specifically Kimi-K2-Instruct-0905 and Qwen3-Embedding-4B (Zeng et al., 3 May 2026). The paper does not explicitly claim open-source release, describing the system as a framework associated with Ant Group (Zeng et al., 3 May 2026).

Several future directions are suggested by comparison with related work. AutoRAG-HP points toward online adaptation and bandit-based control under query streams (Fu et al., 2024). AutoRAG emphasizes module-level negative results and dataset-specific heterogeneity, implying value in richer module libraries and broader validation across domains (Kim et al., 2024). The declarative and unified-data design of AutoRAGTuner suggests natural extensions to multi-objective optimization over accuracy, latency, and cost, and to richer pipeline patterns such as multi-agent or tool-augmented RAG; however, those extensions are not empirically established in the present paper (Zeng et al., 3 May 2026).

Taken together, the framework defines AutoRAGTuner as a systems-level approach to RAG optimization: pipeline structure is declarative, data is unified through DEM, and tuning is treated as end-to-end search over an evolvable configuration space rather than as ad hoc manual adjustment of isolated modules (Zeng et al., 3 May 2026).