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.

RAG Nodes

Document Chunker — rag/chunker

Inputs

Outputs

Document Indexer — rag/document_indexer

Inputs

Outputs

Knowledge Retriever — rag/retriever

Inputs

Outputs

RAG Formatter — rag/formatter

Inputs

Outputs

Knowledge Base Manager — rag/kb_manager

Inputs

Outputs

Embedding Config — ai/embedding_config

Inputs

Outputs

Qdrant Config — ai/qdrant_config

Inputs

Outputs

Next steps

Document Chunker — `rag/chunker`

Document Indexer — `rag/document_indexer`

Knowledge Retriever — `rag/retriever`

RAG Formatter — `rag/formatter`

Knowledge Base Manager — `rag/kb_manager`

Embedding Config — `ai/embedding_config`

Qdrant Config — `ai/qdrant_config`