# RAG Nodes

> Applies to: ChengOS v0.2.0+ ｜ Last verified: 2026-09-25 ｜ Source: `crates/cheng-nodes/src/nodes/builtin/rag`, `crates/cheng-nodes/src/nodes/builtin/ai`

A retrieval pipeline is assembled in order: `rag/chunker` splits a document, `rag/document_indexer`
embeds and stores the chunks, `rag/retriever` pulls candidates back at query time, and `rag/formatter`
turns them into the prompt an LLM node consumes. `rag/kb_manager` handles the knowledge base itself
rather than its contents. `ai/embedding_config` and `ai/qdrant_config` are configuration ports shared
by the pipeline. Prefer the `*_artifact` ports over the inline arrays: the inline forms are bounded
previews, and the artifact carries the complete set.

## Document Chunker — `rag/chunker`

Split documents into parent and child chunks, supports structural/fixed/semantic/hybrid modes

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `content` | string | — | `""` | Document text content to chunk (optional if content_artifact is provided) |
| `content_artifact` | object | — | `null` | Artifact holding the document text to chunk (preferred for large documents) |
| `content_artifact_uri` | string | — | `null` | artifact:// URI for the document text to chunk |
| `legacy_inline_chunks` | boolean | — | `false` | Deprecated compatibility: also emit the full `parent_chunks` / `child_chunks` arrays inline. Off by default — normal execution returns only `chunks_artifact` plus bounded previews. |
| `document_id` | string | — | `null` | Document identifier (optional, auto-generated if not provided) |
| `mode` | string | — | `null` | Select document chunking method. Control: `select` |
| `parent_chunk_chars` | integer | — | `null` | Parent chunk size in characters. Control: `select` |
| `child_chunk_chars` | integer | — | `null` | Child chunk size in characters. Control: `select` |
| `max_embedding_chars` | integer | — | `null` | Maximum embedding chunk size - HARD SAFETY LIMIT. Control: `select` |

### Outputs

| Field | Type | Description |
|---|---|---|
| `document_id` | string | Processed document ID |
| `chunks_artifact` | object | Artifact holding the complete parent+child chunk set |
| `parent_preview` | array<object> | Bounded parent-chunk preview |
| `child_preview` | array<object> | Bounded child-chunk preview |
| `preview_truncated` | boolean | True when previews omit chunks or truncate text |
| `parent_chunks` | array<object> | Deprecated inline parent chunks |
| `child_chunks` | array<object> | Deprecated inline child chunks |
| `parent_count` | integer | Total parent chunk count |
| `child_count` | integer | Total child chunk count |
| `mode` | string | Chunking mode used |

## Document Indexer — `rag/document_indexer`

Index documents into vector database (standard/enhanced modes)

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `kb_id` | string | ✅ | — | Target knowledge base (collection resolved from DB, workspace-validated). Control: `dynamic-select` |
| `qdrant_config` | object (port) | ✅ | — | Qdrant configuration object from config node. Connection port, not a form field. Control: `text` |
| `content` | string | — | `null` | Document text content to index (optional if chunks are provided from chunker) |
| `document_id` | string | — | `null` | Document identifier (optional, auto-generated if not provided) |
| `document_title` | string | — | `null` | Readable document title/source label (optional, falls back to workspace name) |
| `version` | integer | — | `null` | Document version number (optional, for idempotency check) |
| `parent_chunks` | array | — | `null` | Parent chunks from chunker node (optional, if provided skips internal chunking) |
| `child_chunks` | array | — | `null` | Child chunks from chunker node (optional) |
| `chunks_artifact` | object | — | `null` | Artifact from rag/chunker holding the full chunk set (preferred input) |
| `chunks_artifact_uri` | string | — | `null` | artifact:// URI for the chunk collection |
| `index_mode` | string | — | `null` | Standard or enhanced mode. Control: `select` |
| `embedding_config` | object (port) | ✅ | — | Embedding configuration object from config node. Connection port, not a form field. Control: `text` |
| `generate_context` | boolean | — | `null` | Use LLM to generate context descriptions for each chunk (enhanced mode) |
| `llm_config` | object (port) | — | `null` | LLM configuration object from config node (optional, for context generation). Connection port, not a form field. Control: `text` |

### Outputs

| Field | Type | Description |
|---|---|---|
| `document_id` | string | Indexed document ID |
| `parent_chunks` | integer | Number of parent chunks created |
| `child_chunks` | integer | Number of child chunks created |
| `vectors_stored` | integer | Total vectors stored |
| `context_generated` | boolean | Whether context descriptions were generated |
| `index_mode` | string | Index mode used |
| `collection_name` | string | Target collection name |
| `skipped` | boolean | Whether skipped due to idempotency check |
| `success` | boolean | Whether indexing succeeded |
| `summary` | string | Execution result summary |
| `error` | string | Error message if any |

## Knowledge Retriever — `rag/retriever`

Retrieve relevant documents from vector database (economy/power/ultimate modes)

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `workspace_scope` | enum | — | `ambient` | Use the runtime workspace, or pin this retriever to one configured workspace. Control: `select`. Options: `ambient`, `pinned` |
| `workspace_id` | string (port) | — | `null` | Workspace identifier used when pinned, or an explicit override when wired. Connection port, not a form field. Control: `text` |
| `kb_id` | string | ✅ | — | Target knowledge base (collection resolved from DB, workspace-validated). Control: `dynamic-select` |
| `qdrant_config` | object (port) | ✅ | — | Qdrant configuration object from config node. Connection port, not a form field. Control: `text` |
| `query` | string | ✅ | — | Query text for retrieval (accepts string or ChatContext) |
| `retrieval_mode` | string | — | `null` | Select retrieval strategy. Control: `select` |
| `limit` | integer | — | `null` | Maximum number of results to return |
| `embedding_config` | object (port) | ✅ | — | Embedding configuration object from config node. Connection port, not a form field. Control: `text` |
| `llm_config` | object (port) | — | `null` | LLM configuration object from config node (optional, for HyDE). Connection port, not a form field. Control: `text` |
| `document_filter` | array | — | `null` | List of document IDs to limit retrieval scope (optional) |

### Outputs

| Field | Type | Description |
|---|---|---|
| `documents` | array<object> | Bounded list of retrieved documents |
| `documents_artifact` | object | Artifact holding the complete retrieved-document set |
| `documents_preview` | string | Bounded preview of retrieved documents |
| `documents_truncated` | boolean | True when the inline documents list omits results |
| `count` | integer | Number of results returned |
| `retrieval_mode` | string | Retrieval mode used |
| `query` | string | Query text used for retrieval |
| `latency_ms` | integer | Retrieval latency in milliseconds |
| `collection_name` | string | Collection name retrieved from |
| `token_usage` | object | Estimated token usage |
| `has_results` | boolean | True when at least one document was retrieved |
| `summary_input` | object | Lean AgentContext for downstream LLM summarization (conditional: absent when no results) |

## RAG Formatter — `rag/formatter`

Format retrieved documents and user query into LLM prompt

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `query` | string | ✅ | — | User question from retriever node query output |
| `documents` | array<object> | — | `[]` | List of retrieved documents (compatibility; prefer documents_artifact) |
| `documents_artifact` | object | — | `null` | Artifact from rag/retriever holding the full document set (preferred input) |
| `documents_artifact_uri` | string | — | `null` | artifact:// URI for the retrieved-document set |
| `template` | string | — | `null` | Select prompt template type. Control: `select` |
| `custom_template` | string | — | `null` | Custom prompt template. Available placeholders: {query}, {documents}, {count}. Control: `textarea` |
| `include_scores` | boolean | — | `null` | Include document relevance scores in formatted output |
| `include_sources` | boolean | — | `null` | Include document IDs and source information in formatted output |
| `max_doc_chars` | integer | — | `null` | Maximum characters per document chunk (0 = unlimited) |

### Outputs

| Field | Type | Description |
|---|---|---|
| `prompt` | string | Formatted prompt ready for LLM input (bounded) |
| `prompt_artifact` | object | Artifact holding the complete formatted prompt when large |
| `prompt_truncated` | boolean | True when the inline prompt is bounded and the full text is in prompt_artifact |
| `query` | string | Original query text |
| `document_count` | integer | Number of documents included |
| `total_chars` | integer | Total characters in formatted output |

## Knowledge Base Manager — `rag/kb_manager`

Manage knowledge bases (list, delete, view details)

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `qdrant_config` | object (port) | ✅ | — | Qdrant configuration object from config node. Connection port, not a form field. Control: `text` |
| `operation` | string | — | `list` | Operation to perform. Control: `select` |
| `kb_id` | string | — | `null` | Target knowledge base (required for delete and info operations). Control: `dynamic-select` |

### Outputs

| Field | Type | Description |
|---|---|---|
| `operation` | string | Operation performed |
| `success` | boolean | Whether operation succeeded |
| `collections` | array | List of knowledge bases |
| `collection_info` | object | Knowledge base details |
| `message` | string | Operation message |
| `error` | string | Error message if any |
| `data` | any | Generic result data |

## Embedding Config — `ai/embedding_config`

Select connected Embedding model, output complete configuration

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `embedding_model` | string | ✅ | — | Select a connected Embedding model. Supports credential_id::model_name or model_name (requires CHENG_DEFAULT_EMBEDDING_CREDENTIAL_ID). Control: `llm-model-select` |
| `dimension` | integer | — | `1024` | 向量维度. Control: `select` |
| `batch_size` | integer | — | `null` | 批量处理大小. Control: `select` |
| `reranker_model` | string | — | `null` | Select a reranker model (optional, for post-processing optimization). Control: `llm-model-select` |
| `reranker_top_k` | integer | — | `null` | Reranker Top K. Control: `select` |

### Outputs

| Field | Type | Description |
|---|---|---|
| `embedding_config` | object (port) | Complete Embedding configuration. Connection port, not a form field. |
| `reranker_config` | object (port) | Reranker configuration (if a reranker model is configured). Connection port, not a form field. |

## Qdrant Config — `ai/qdrant_config`

Configure a Qdrant vector database connection (local/cloud/self-hosted)

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `mode` | string | — | `local` | Select how Qdrant is deployed. Control: `select` |
| `url` | string | — | `null` | Qdrant gRPC endpoint URL (default for local mode: http://localhost:6334) |
| `credential_id` | string | — | `null` | Credential for Qdrant Cloud or an authenticated self-hosted server. Control: `credential-select` |
| `collection_name` | string | — | `null` | Name of the Qdrant collection (optional, auto-derived from knowledge base if not set) |
| `enable_fulltext` | boolean | — | `null` | Whether to enable a BM25 full-text search index on the collection |

### Outputs

| Field | Type | Description |
|---|---|---|
| `mode` | string | Qdrant deployment mode |
| `url` | string | Qdrant gRPC endpoint URL |
| `api_key` | string | API key (used in cloud/authenticated modes) |
| `collection_name` | string | Qdrant collection name |
| `enable_fulltext` | boolean | Whether full-text search is enabled |
| `credential_id` | string | Credential ID used, if any |
| `qdrant_config` | object (port) | Complete Qdrant configuration (JSON object). Connection port, not a form field. |

## Next steps

- [RAG Pipeline Design](/docs/data-rag-pipeline)
- [Workspace Nodes](/docs/nodes-workspace)
- [Knowledge Bases & Workspace Context](/docs/data-knowledge-base)