### Verifying UltraRAG Installation

Source: https://github.com/openbmb/ultrarag/blob/main/docs/README-English.md

Command to run a simple example pipeline to verify that UltraRAG has been installed correctly. On success, it should output 'Hello, UltraRAG 2.0!'.

```shell
ultrarag run examples/sayhello.yaml
```

--------------------------------

### Conda Virtual Environment Setup for UltraRAG

Source: https://github.com/openbmb/ultrarag/blob/main/docs/README-English.md

Commands to create and activate a Conda virtual environment for UltraRAG. This isolates project dependencies and ensures a clean development environment. Requires Conda to be installed.

```shell
conda create -n ultrarag python=3.11
conda activate ultrarag
```

--------------------------------

### Cloning and Installing UltraRAG with uv

Source: https://github.com/openbmb/ultrarag/blob/main/docs/README-English.md

Steps to clone the UltraRAG repository and install its dependencies using uv for faster and more reliable package management. uv is a modern Python package installer and resolver.

```shell
git clone https://github.com/OpenBMB/UltraRAG.git --depth 1
cd UltraRAG
pip install uv
uv pip install -e .
```

--------------------------------

### UltraRAG CLI Commands

Source: https://context7.com/openbmb/ultrarag/llms.txt

Command-line interface commands for building and running RAG pipelines, launching the web UI, and setting logging levels. These commands automate the setup and execution of RAG experiments using YAML configurations.

```bash
ultrarag build examples/rag.yaml

ultrarag run examples/rag.yaml

ultrarag run examples/rag.yaml --param custom_params.yaml

ultrarag show ui --host 127.0.0.1 --port 5050

ultrarag run examples/rag.yaml --log_level debug
```

--------------------------------

### Installing Retriever/Reranker Server Dependencies

Source: https://github.com/openbmb/ultrarag/blob/main/docs/README-English.md

Optional command to install specific dependencies for Retriever/Reranker Server components using uv. This is useful for extending RAG capabilities with specific embedding models like infinity_emb.

```shell
# Retriever/Reranker Server dependencies:
# infinity
uv pip install infinity_emb
```

--------------------------------

### Installing UltraRAG with pip

Source: https://github.com/openbmb/ultrarag/blob/main/docs/README-English.md

Alternative method to install UltraRAG using pip, suitable for environments where uv is not used. This command installs the project in editable mode, allowing for direct code modifications.

```shell
pip install -e .
```

--------------------------------

### Define Generation Pipeline Step (YAML)

Source: https://context7.com/openbmb/ultrarag/llms.txt

This YAML snippet outlines a step in a generation pipeline. It specifies the sequence of operations, starting with initialization and prompt handling, and culminating in the actual text generation. The 'generation.generate' step takes prompt messages and a system prompt as input, producing answers as output.

```yaml
pipeline:
- generation.generation_init
- prompt.qa_rag_boxed
- generation.generate:
    input:
      prompt_ls: messages
      system_prompt: "You are a helpful assistant."
    output:
      ans_ls: answers
```

--------------------------------

### Configure Multimodal Generation Pipeline (YAML)

Source: https://context7.com/openbmb/ultrarag/llms.txt

This YAML configuration sets up a multimodal Retrieval Augmented Generation (RAG) pipeline. It utilizes servers for generation and retrieval, first performing a search to get image passages, and then using 'multimodal_generate' to answer questions based on these passages and a system prompt. Dependencies include image processing capabilities.

```yaml
# Multimodal RAG pipeline
servers:
  generation: servers/generation
  retriever: servers/retriever

pipeline:
- retriever.retriever_search:
    output:
      ret_psg: image_passages

- generation.multimodal_generate:
    input:
      multimodal_path: image_passages
      prompt_ls: questions
      system_prompt: "Analyze the images and answer."
      image_tag: "<image>"
    output:
      ans_ls: multimodal_answers
```

--------------------------------

### Build and Run Docker Image for UltraRAG (Bash)

Source: https://context7.com/openbmb/ultrarag/llms.txt

This bash script provides commands for building and deploying the UltraRAG application using Docker. It includes steps to build a Docker image, run a container with GPU support, execute the 'ultrarag run' command inside the container, and pull a pre-built image from a Docker registry. These commands are essential for setting up the environment for UltraRAG.

```bash
# Build Docker image
docker build -t ultrarag:v0.2.1 .

# Run container with GPU support
docker run -it --gpus all ultrarag:v0.2.1 /bin/bash

# Inside container - verify installation
ultrarag run examples/sayhello.yaml

# Pull pre-built image
docker pull hdxin2002/ultrarag:v0.2.1
docker run -it --gpus all hdxin2002/ultrarag:v0.2.1 /bin/bash
```

--------------------------------

### Configure Corpus Building Pipeline (YAML)

Source: https://context7.com/openbmb/ultrarag/llms.txt

This YAML configuration sets up a pipeline for building a text corpus and then chunking it. It specifies server paths and defines pipeline steps for building the corpus from raw documents and then chunking the corpus into smaller segments for further processing. Input and output paths are clearly defined.

```yaml
# Corpus building pipeline
servers:
  corpus: servers/corpus

pipeline:
- corpus.build_text_corpus:
    input:
      parse_file_path: "./raw_docs"
      text_corpus_save_path: "./data/corpus.jsonl"

- corpus.corpus_chunk:
    input:
      corpus_path: "./data/corpus.jsonl"
      chunked_corpus_path: "./data/chunked_corpus.jsonl"
      chunk_size: 512
      chunk_overlap: 128
```

--------------------------------

### Configure Generation Backend and Sampling Parameters (YAML)

Source: https://context7.com/openbmb/ultrarag/llms.txt

This YAML configuration defines the backend for text generation, specifying model details, GPU usage, and data types. It also sets sampling parameters like temperature, top_p, and maximum tokens for controlling the generation process. Dependencies include the 'vllm' or 'openai' backend libraries.

```yaml
generation:
  backend: "vllm"
  backend_configs:
    vllm:
      model_name_or_path: "meta-llama/Llama-3.1-8B-Instruct"
      gpu_ids: "0,1"
      trust_remote_code: true
      dtype: "bfloat16"
    openai:
      base_url: "https://api.openai.com/v1"
      api_key: "${OPENAI_API_KEY}"
      model_name: "gpt-4o-mini"
  sampling_params:
    temperature: 0.7
    top_p: 0.9
    max_tokens: 512
    chat_template_kwargs:
      add_generation_prompt: true
```

--------------------------------

### Configure Benchmark Parameters (YAML)

Source: https://context7.com/openbmb/ultrarag/llms.txt

This YAML configuration specifies parameters for a benchmarking process. It defines the benchmark dataset to be used (e.g., 'nq'), the data split ('test'), and the sample size for evaluation. It also points to the location of the benchmark data file.

```yaml
# parameter.yaml for benchmark
benchmark:
  benchmark:
    name: "nq"
    split: "test"
    sample_size: 1000
  data_path: "data/benchmarks/nq.jsonl"
```

--------------------------------

### Python API - Direct Tool Invocation

Source: https://context7.com/openbmb/ultrarag/llms.txt

Direct invocation of server tools using the UltraRAG Python API. This allows for fine-grained control over RAG components, such as initializing servers and performing retrieval searches programmatically. Requires server initialization before use.

```python
from ultrarag.client import initialize, ToolCall

# Initialize servers
initialize(
    servers=["retriever", "generation", "corpus"],
    server_root="./servers",
    log_level="info"
)

# Call server tools directly
await ToolCall.retriever.retriever_init(
    model_name_or_path="BAAI/bge-base-en-v1.5",
    backend="sentence_transformers",
    backend_configs={"sentence_transformers": {}},
    batch_size=128,
    corpus_path="data/corpus.jsonl",
    gpu_ids="0"
)

# Perform retrieval search
results = await ToolCall.retriever.retriever_search(
    q_ls=["What is RAG?"],
    top_k=5,
    query_instruction=""
)
```

--------------------------------

### Integrate Web Search with External APIs (YAML)

Source: https://context7.com/openbmb/ultrarag/llms.txt

This YAML configures a pipeline that integrates web search capabilities using external APIs like Tavily and Exa. It defines server paths for the retriever and outlines pipeline steps for performing searches using 'retriever_tavily_search' and 'retriever_exa_search'. Input queries are processed, and search results are stored.

```yaml
# Web search with external APIs
servers:
  retriever: servers/retriever

pipeline:
- retriever.retriever_tavily_search:
    input:
      q_ls: queries
      top_k: 5
      retrieve_thread_num: 4
    output:
      ret_psg: web_results

- retriever.retriever_exa_search:
    input:
      q_ls: queries
      top_k: 5
    output:
      ret_psg: exa_results
```

--------------------------------

### Register Custom Server Tools (Python)

Source: https://context7.com/openbmb/ultrarag/llms.txt

This Python code registers custom tools for an UltraRAG server. It initializes the server and defines asynchronous functions ('preprocess', 'merge_passages') decorated with '@app.tool' to expose them as callable tools. The decorators specify the input and output mappings for each tool, facilitating custom data processing within the server environment.

```python
from ultrarag.server import UltraRAG_MCP_Server

app = UltraRAG_MCP_Server("custom")

@app.tool(output="input_text->processed_text")
async def preprocess(input_text: str) -> dict:
    """Custom preprocessing function"""
    processed = input_text.lower().strip()
    return {"processed_text": processed}

@app.tool(output="passages->merged_passages")
async def merge_passages(passages: list) -> dict:
    """Merge retrieved passages"""
    merged = "\n\n".join([p["text"] for p in passages])
    return {"merged_passages": merged}
```

--------------------------------

### Configure BM25 Sparse Retrieval Pipeline (YAML)

Source: https://context7.com/openbmb/ultrarag/llms.txt

This YAML configuration sets up a pipeline for BM25 sparse retrieval, including indexing and searching. It specifies the retriever server path and defines two pipeline steps: 'bm25_index' to create an index from a corpus, and 'bm25_search' to retrieve top-k documents based on input questions. The indexing process can optionally overwrite existing indices.

```yaml
# BM25 indexing and search
servers:
  retriever: servers/retriever

pipeline:
- retriever.bm25_index:
    input:
      corpus_path: "./data/corpus.jsonl"
      overwrite: true

- retriever.bm25_search:
    input:
      q_ls: questions
      top_k: 10
    output:
      ret_psg: bm25_results
```

--------------------------------

### Define Benchmark and Evaluation Pipeline (YAML)

Source: https://context7.com/openbmb/ultrarag/llms.txt

This YAML defines a pipeline for benchmarking and evaluation. It specifies server configurations for benchmarking and evaluation components. The pipeline retrieves questions and gold answers, then evaluates predicted answers against gold answers using specified metrics like 'exact_match' and 'f1'.

```yaml
# Evaluation pipeline
servers:
  benchmark: servers/benchmark
  evaluation: servers/evaluation

pipeline:
- benchmark.get_data:
    output:
      q_ls: questions
      gold_ans: gold_answers

- evaluation.evaluate:
    input:
      pred_ans: predicted_answers
      gold_ans: gold_answers
      metric: "exact_match,f1"
```

--------------------------------

### Retriever Pipeline Step (YAML)

Source: https://context7.com/openbmb/ultrarag/llms.txt

A YAML snippet defining a pipeline step for the retriever. It specifies the initialization and search operations, including input query lists and output for retrieved passages. This is used within the larger pipeline configuration.

```yaml
# Pipeline step for retriever
pipeline:
- retriever.retriever_init
- retriever.retriever_search:
    input:
      query_list: q_ls
      top_k: 10
    output:
      ret_psg: retrieved_passages
```

--------------------------------

### Retriever Server Configuration (YAML)

Source: https://context7.com/openbmb/ultrarag/llms.txt

YAML configuration for the Retriever Server, specifying model paths, backends, batch sizes, corpus paths, GPU usage, and index backend settings. This configuration is used for initializing and setting up the retrieval component of the RAG system.

```yaml
# Server configuration in parameter.yaml
retriever:
  model_name_or_path: "BAAI/bge-base-en-v1.5"
  backend: "sentence_transformers"
  batch_size: 128
  corpus_path: "data/wiki_corpus.jsonl"
  gpu_ids: "0"
  backend_configs:
    sentence_transformers:
      trust_remote_code: true
    infinity:
      engine_kwargs:
        model_warmup: true
    openai:
      base_url: "https://api.openai.com/v1"
      api_key: "${OPENAI_API_KEY}"
      model_name: "text-embedding-3-small"
  index_backend: "faiss"
  index_backend_configs:
    index_type: "Flat"
    metric: "cosine"
```

--------------------------------

### Basic RAG Pipeline (YAML)

Source: https://context7.com/openbmb/ultrarag/llms.txt

A basic RAG pipeline defined in YAML, specifying the sequence of MCP server calls for benchmark, retrieval, prompt processing, generation, and evaluation. This configuration outlines the core components and their execution order for a standard RAG workflow.

```yaml
# examples/rag.yaml
# MCP Server declarations
servers:
  benchmark: servers/benchmark
  retriever: servers/retriever
  prompt: servers/prompt
  generation: servers/generation
  evaluation: servers/evaluation
  custom: servers/custom

# MCP Client Pipeline execution
pipeline:
- benchmark.get_data
- retriever.retriever_init
- retriever.retriever_search
- generation.generation_init
- prompt.qa_rag_boxed
- generation.generate
- custom.output_extract_from_boxed
- evaluation.evaluate
```

--------------------------------

### Implement Conditional Branching with Router (YAML)

Source: https://context7.com/openbmb/ultrarag/llms.txt

This YAML configuration demonstrates a pipeline with conditional branching based on query type classification. It includes steps for data retrieval, generation initialization, and then routes the process to different branches ('simple' or 'complex') based on the output of a 'classify_query_type' router. Each branch has its specific prompt and generation steps.

```yaml
# Branch-based pipeline
pipeline:
- benchmark.get_data
- retriever.retriever_init
- generation.generation_init
- branch:
    router:
    - custom.classify_query_type
    branches:
      simple:
      - prompt.simple_qa
      - generation.generate
      complex:
      - prompt.complex_reasoning
      - generation.generate
      - retriever.retriever_search
      - prompt.rag_answer
      - generation.generate
- evaluation.evaluate
```

--------------------------------

### Loop-based Iterative RAG Pipeline (YAML)

Source: https://context7.com/openbmb/ultrarag/llms.txt

An advanced RAG pipeline configuration in YAML that includes a loop for iterative processing. This allows for multiple rounds of sub-question generation, retrieval, and passage merging before final generation and evaluation, enabling more complex reasoning chains.

```yaml
# examples/rag_loop.yaml
servers:
  benchmark: servers/benchmark
  retriever: servers/retriever
  prompt: servers/prompt
  generation: servers/generation
  evaluation: servers/evaluation
  custom: servers/custom

pipeline:
- benchmark.get_data
- retriever.retriever_init
- generation.generation_init
- retriever.retriever_search
- loop:
    times: 3
    steps:
    - prompt.gen_subq
    - generation.generate:
        output:
          ans_ls: subq_ls
    - retriever.retriever_search:
        input:
          query_list: subq_ls
        output:
          ret_psg: temp_psg
    - custom.merge_passages
- prompt.qa_rag_boxed
- generation.generate
- custom.output_extract_from_boxed
- evaluation.evaluate
```

--------------------------------

### Python API - Programmatic Pipeline Execution

Source: https://context7.com/openbmb/ultrarag/llms.txt

Programmatic execution of a RAG pipeline using the UltraRAG Python API. This snippet demonstrates how to trigger a pipeline defined in a YAML file and retrieve its results, allowing for integration into larger Python applications.

```python
from ultrarag.client import pipeline

# Execute a pipeline and get results
result = pipeline("examples/rag.yaml", log_level="info")

# Result contains the final output from the pipeline
print(result)
```

--------------------------------

### Build Text and Image Corpus (Python)

Source: https://context7.com/openbmb/ultrarag/llms.txt

These Python functions are used to build corpora from documents and PDF files. 'build_text_corpus' processes files from a specified path and saves the resulting text corpus in JSONL format. 'build_image_corpus' does the same for images extracted from PDFs. Dependencies include file system access and JSONL handling.

```python
# Build text corpus from documents
build_text_corpus(
    parse_file_path="./documents",
    text_corpus_save_path="./data/corpus.jsonl"
)

# Build image corpus from PDFs
build_image_corpus(
    parse_file_path="./pdfs",
    image_corpus_save_path="./data/image_corpus.jsonl"
)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.