Orchestration

MariaDB AI RAG orchestration endpoints coordinate multi-step RAG workflows in one request, covering ingestion, chunking, retrieval, streaming generation, and an end-to-end pipeline call.

Overview

The orchestration module provides high-level endpoints that coordinate multiple steps of the RAG (Retrieval Augmented Generation) workflow. These endpoints simplify integration by handling complex workflows in a single request.

Orchestration Endpoints

Ingestion Orchestration

POST /orchestrate/ingestion

Purpose: Orchestrates the complete ingestion workflow: document upload, processing, chunking, and embedding. This endpoint handles the entire pipeline from files to searchable chunks.

Request: multipart/form-data with files and optional configuration

Form Parameters:

• files: One or more files to upload (optional if using file_paths)

• file_paths: JSON array of server-side file paths (optional if using files)

• config: JSON string with chunking configuration (optional)

Configuration JSON Structure:

{
  "chunking_method": "semantic",
  "chunk_size": 512,
  "cloud_storage_sources": [
    {
      "integration_id": "int_abc123",
      "prefix": "financial_reports/Q3/",
      "recursive": true,
      "file_extensions": [".pdf"]
    }
  ],
  "document_processing": {
    "processor_type": "layout_aware_standard",
    "enable_ocr": true,
    "ocr_provider": "rapidocr",
    "enable_table_extraction": true,
    "table_structure_mode": "accurate"
  }
}

Parameters:

• chunking_method

  • recursive: Recursive text splitting (default)

  • sentence: Sentence-based chunking

  • token: Token-based chunking

  • semantic: Semantic similarity-based chunking (requires threshold)

• chunk_size: Number of tokens/characters per chunk (default: 512).

• cloud_storage_sources (optional): A JSON array used to ingest from an external integration (S3, GCS, or MinIO). Requires an integration_id and a prefix.

• document_processing (optional): A stringified JSON object defining the extraction tier:

  • processor_type: "base", "layout_aware_standard" (Docling), or "layout_aware_advanced" (LlamaParse).

  • enable_ocr: Boolean to turn on OCR for scanned documents.

Response:

{
  "message": "Successfully ingested and chunked 2 documents",
  "document_ids": [42, 43],
  "chunk_count": 25,
  "processing_time_seconds": 15.2
}

Usage Example: Upload and process documents in a single request.

# Upload files with custom chunking config
curl -X POST "http://localhost:8000/orchestrate/ingestion" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "files=@/path/to/document1.pdf" \
  -F "files=@/path/to/document2.docx" \
  -F 'config={"chunking_method":"semantic","chunk_size":512,"threshold":0.8}'

# Use server-side file paths
curl -X POST "http://localhost:8000/orchestrate/ingestion" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F 'file_paths=["./docs/file1.pdf","./docs/file2.pdf"]' \
  -F 'config={"chunking_method":"recursive","chunk_size":512}'

Generation Orchestration

POST /orchestrate/generation

Purpose: Orchestrates the complete RAG workflow: retrieval and text generation in a single request. Automatically retrieves relevant chunks and generates a response.

Request body (with a reranking object):

{
  "query": "What are the key findings?",
  "document_ids": [1, 2, 3],
  "retrieval_method": "hybrid",
  "top_k": 5,
  "reranking": {
    "enabled": true,
    "model_type": "flashrank",
    "model_name": "ms-marco-MiniLM-L-12-v2",
    "top_k": 5
  },
  "llm_provider": "openai",
  "llm_model": "gpt-4"
}

Request Parameters:

• query (required): The user's question or prompt

• document_ids (optional): Filter retrieval to specific documents (default: all documents)

• retrieval_method (optional): semantic, fulltext, or hybrid (default: hybrid)

• model_type (optional): The backend library to use. Valid values: "flashrank", "sentence-transformers", "cohere", "hybrid" (default: "flashrank").

• model_name (optional): The specific reranker model to load (default: "ms-marco-MiniLM-L-12-v2")

• top_k (optional): Number of chunks to retrieve (default: 5)

• reranking (optional): A JSON object to enable a high-accuracy second pass.

  • enabled (optional): Set to true to activate reranking (default: false).

  • model_type (optional): The backend library (flashrank, sentence-transformers, cohere, hybrid) (default: "flashrank").

  • model_name (optional): The specific reranker model to load (default: "ms-marco-MiniLM-L-12-v2").

  • top_k (optional): Number of reranked results to return to the LLM.

• llm_provider (optional): LLM provider - openai, anthropic, gemini, cohere, ollama, azure, bedrock

• temperature (optional): Controls randomness (0.0-2.0, default: 0.7)

• top_p (optional): Nucleus sampling (0.0-1.0, default: 0.9)

• max_tokens (optional): Maximum tokens to generate (1-8192, default: 500)

• stream (optional): Enable streaming (default: false)

Response:

{
  "query": "What are the key features?",
  "response": "The key features include document processing, semantic search, and AI-powered generation...",
  "chunks_used": 5,
  "retrieval_method": "hybrid",
  "processing_time_seconds": 2.5,
  "retrieval_time_ms": 150.3,
  "generation_time_ms": 2350.7
}

Response Fields:

• query: The original query

• response: The generated response

• chunks_used: Number of chunks used for generation

• retrieval_method: The retrieval method used

• processing_time_seconds: Total processing time

• retrieval_time_ms: Time spent on retrieval (optional)

• generation_time_ms: Time spent on generation (optional)

Usage Example: Query documents and get an AI-generated response in one call.

curl -X POST "http://localhost:8000/orchestrate/generation" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the key features?",
    "document_ids": [42, 43],
    "retrieval_method": "hybrid",
    "top_k": 5,
    "llm_provider": "openai",
    "llm_model": "gpt-4"
  }'

Streaming Generation Orchestration

POST /orchestrate/generation-stream

Purpose: Same as the generation endpoint but returns the response as a Server-Sent Events (SSE) stream for real-time display.

Request body: Same as /orchestrate/generation

Response: Server-Sent Events (SSE) stream with the following event types:

// Start event
{"type": "start", "query": "What are the key features?"}

// Retrieval complete event
{"type": "retrieval_complete", "chunks_retrieved": 5, "retrieval_time_ms": 150.3}

// Token events (streamed as generated)
{"type": "token", "content": "The", "chunk_index": 1}
{"type": "token", "content": " key", "chunk_index": 2}
{"type": "token", "content": " features", "chunk_index": 3}

// Completion event
{"type": "complete", "total_time_seconds": 2.5, "tokens_generated": 150}

// Error event (if error occurs)
{"type": "error", "message": "Error description"}

Usage Example: Use this endpoint for real-time user interfaces with progressive response display.

curl -X POST "http://localhost:8000/orchestrate/generation-stream" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the key features?",
    "document_ids": [42, 43],
    "retrieval_method": "hybrid",
    "top_k": 5
  }'

Full Pipeline

POST /orchestrate/full-pipeline

Purpose: Executes the complete RAG pipeline in a single request: document ingestion, chunking, embedding, retrieval, and generation. This is the ultimate one-call solution for processing new documents and getting an AI-generated answer.

Request: multipart/form-data with files and configuration

Form Parameters:

• files: One or more files to upload (optional if using file_paths)

• file_paths: JSON array of server-side file paths (optional if using files)

• query: The query string (required)

• config: JSON string with pipeline configuration (optional)

Configuration JSON Structure:

{
  "chunking_method": "recursive",
  "chunk_size": 512,
  "chunk_overlap": 128,
  "retrieval_method": "hybrid",
  "top_k": 5,
  "embedding_provider": "openai",
  "embedding_model": "text-embedding-3-small",
  "llm_provider": "openai",
  "llm_model": "gpt-4",
  "temperature": 0.7,
  "top_p": 0.9,
  "max_tokens": 1000
}

Response:

{
  "message": "Full pipeline completed successfully",
  "document_ids": [42, 43],
  "chunk_count": 25,
  "query": "What are the key features?",
  "response": "The key features include document processing, semantic search, and AI-powered generation...",
  "chunks_used": 5,
  "total_processing_time_seconds": 20.5
}

Response Fields:

• message: Status message

• document_ids: IDs of ingested documents

• chunk_count: Total chunks created

• query: The original query

• response: The AI-generated response

• chunks_used: Number of chunks used for generation

• total_processing_time_seconds: Total pipeline execution time

Usage Example: Process new documents and get an answer in one request.

# Upload files and query
curl -X POST "http://localhost:8000/orchestrate/full-pipeline" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "files=@/path/to/document1.pdf" \
  -F "files=@/path/to/document2.docx" \
  -F "query=What are the key features?" \
  -F 'config={"chunking_method":"semantic","retrieval_method":"hybrid","top_k":5}'

# Use server-side file paths
curl -X POST "http://localhost:8000/orchestrate/full-pipeline" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F 'file_paths=["./docs/file1.pdf","./docs/file2.pdf"]' \
  -F "query=Summarize the main points" \
  -F 'config={"chunking_method":"recursive","llm_model":"gpt-4"}'

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}