ChonkieSemanticDocumentSplitter

Split documents into semantically coherent chunks using the Chonkie chunking library. This splitter groups sentences with similar semantic content together, creating chunks that are thematically consistent rather than just size-limited.

Key Features

• Groups sentences by semantic similarity using an embedding model.
• Creates chunks that are semantically coherent rather than just fixed-size.
• Configurable similarity threshold to control how aggressively sentences are grouped.
• Uses a Savitzky-Golay filter to smooth semantic similarity signals and detect topic boundaries.
• Loads the embedding model lazily on the first run() call.

Configuration

Add Workspace-Level Integration

1. Click your profile icon and choose Settings.
2. Go to Workspace>Integrations.
3. Find the provider you want to connect and click Connect next to them.
4. Enter the API key and any other required details.
5. Click Connect. You can use this integration in pipelines and indexes in the current workspace.

Add Organization-Level Integration

1. Click your profile icon and choose Settings.
2. Go to Organization>Integrations.
3. Find the provider you want to connect and click Connect next to them.
4. Enter the API key and any other required details.
5. Click Connect. You can use this integration in pipelines and indexes in all workspaces in the current organization.

1. Drag the ChonkieSemanticDocumentSplitter component onto the canvas from the Component Library.
2. Configure the embedding_model to the model you want to use for computing sentence similarity.
3. Adjust the threshold to control how similar adjacent sentences must be to remain in the same chunk. Lower values create more, smaller chunks; higher values create fewer, larger chunks.

Connections

ChonkieSemanticDocumentSplitter receives a list of Document objects as input. It outputs a list of smaller Document objects (chunks) you can connect to a document embedder.

Source Code

To check this component's source code, open semantic_splitter.py in the Haystack Core Integrations repository.

Usage Examples

Basic Configuration

  ChonkieSemanticDocumentSplitter:
    type: haystack_integrations.components.preprocessors.chonkie.semantic_splitter.ChonkieSemanticDocumentSplitter
    init_parameters:
      embedding_model: minishlab/potion-base-32M
      threshold: 0.8
      chunk_size: 512

Parameters

Inputs

Parameter	Type	Description
documents	List[Document]	A list of documents to split into semantically coherent chunks.

Outputs

Parameter	Type	Description
documents	List[Document]	A list of semantically grouped document chunks with updated metadata.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
embedding_model	Any	minishlab/potion-base-32M	The embedding model to use for computing sentence similarity. Can be a model name string or a model instance.
threshold	float	0.8	The cosine similarity threshold for grouping sentences. Sentences with similarity above this value are kept in the same chunk.
chunk_size	int	2048	The maximum number of tokens per chunk.
similarity_window	int	3	The number of adjacent sentences to compare when computing similarity.
min_sentences_per_chunk	int	1	The minimum number of sentences to include in each chunk.
min_characters_per_sentence	int	24	The minimum number of characters a sentence must have to be included.
delim	Any	None	Custom sentence delimiters. If None, uses default sentence-ending punctuation.
include_delim	str	prev	Where to include the delimiter in the chunk. One of prev or next.
skip_window	int	0	The window size for skipping sentences with low similarity.
filter_window	int	5	The window size for the Savitzky-Golay smoothing filter.
filter_polyorder	int	3	The polynomial order for the Savitzky-Golay smoothing filter.
filter_tolerance	float	0.2	The tolerance for detecting topic boundary peaks after smoothing.
skip_empty_documents	bool	True	Whether to skip documents with no content.
page_break_character	str	\f	The character used to represent page breaks in document text.

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Default	Description
documents	List[Document]		The documents to split.

Related Information

• ChonkieSentenceDocumentSplitter
• ChonkieTokenDocumentSplitter
• ChonkieRecursiveDocumentSplitter
• Pipeline Components