Skip to main content
UltraRAG provides two lightweight integration methods — ToolCall and PipelineCall — allowing you to invoke UltraRAG capabilities directly from your own Python code.

​
ToolCall

If you only need a specific UltraRAG feature such as data loading, embedding, or retrieval — without running a full RAG pipeline — you can call UltraRAG tools just like regular Python functions using ToolCall.
Before using ToolCall, you must call initialize to specify which UltraRAG servers to activate.
It is recommended to set server_root to the absolute path of the UltraRAG servers directory, such as /home/user/project/UltraRAG/servers.
script/api_usage_example.py
from ultrarag.api import initialize, ToolCall

initialize(["benchmark"], server_root="servers")

benchmark_param_dict = {
    "key_map": {
        "gt_ls": "golden_answers",
        "q_ls": "question"
    },
    "limit": -1,
    "seed": 42,
    "name": "nq",
    "path": "data/sample_nq_10.jsonl",
}

benchmark = ToolCall.benchmark.get_data(benchmark_param_dict)
You can call the tool exactly like a normal Python function — simply pass the required arguments.
script/api_usage_example.py
from ultrarag.api import initialize, ToolCall

initialize(["benchmark", "retriever"], server_root="servers")

benchmark_param_dict = {
    "key_map": {
        "gt_ls": "golden_answers",
        "q_ls": "question"
    },
    "limit": -1,
    "seed": 42,
    "name": "nq",
    "path": "data/sample_nq_10.jsonl",
}

benchmark = ToolCall.benchmark.get_data(benchmark_param_dict)
query_list = benchmark["q_ls"]

retriever_init_param_dict = {
    "model_name_or_path": "Qwen/Qwen3-Embedding-0.6B",
}

ToolCall.retriever.retriever_init(**retriever_init_param_dict)

result = ToolCall.retriever.retriever_search(
    query_list=query_list,
    top_k=5,
)

retrieve_passages = result["ret_psg"]
You only need to provide parameters that you want to override. Other fields will be automatically filled using defaults from the server’s parameter file.

​
PipelineCall

If you want to run an entire UltraRAG Pipeline programmatically and obtain the output of each step, you can use PipelineCall.
You must first generate pipeline_parameter.yaml and related configuration files using UR‑v2’s build command.
script/api_usage_example.py
from ultrarag.api import PipelineCall

result = PipelineCall(
    pipeline_file="examples/rag_deploy.yaml",
    parameter_file="examples/parameter/rag_deploy_parameter.yaml",
)

final_step_result = result["final_result"]
all_steps_result = result["all_results"]
final_result contains the output of the pipeline’s last step, while all_results includes every step’s result.