Install & Compatibility
Where this runs
tested against v0.31.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
build_error
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 1.9s · import 0.000s · 37MB
34MB installed
● package 34MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TextSplitter
✓ from semantic_text_splitter import TextSplitter
✗ from semantic_text_splitter import EmbeddingTextSplitter
CodeSplitter
✓ from semantic_text_splitter import CodeSplitter
MarkdownSplitter
✓ from semantic_text_splitter import MarkdownSplitter
This quickstart demonstrates how to use `EmbeddingTextSplitter` to divide a long document into semantically related chunks using a pre-trained embedding model and its corresponding tokenizer. It also shows `CharacterTextSplitter` for comparison.
import os
from semantic_text_splitter import EmbeddingTextSplitter
from transformers import AutoTokenizer
# Example text, often a full document
long_document_text = (
"The quick brown fox jumps over the lazy dog. "
"This sentence is a classic example used for typing practice. "
"However, its semantic content is rather limited. "
"In natural language processing, we often deal with much longer texts, "
"requiring sophisticated methods to break them into manageable pieces. "
"Semantic text splitting aims to keep related ideas together, "
"even if they are separated by punctuation or line breaks. "
"This is crucial for retrieval augmented generation (RAG) systems. "
"By using embeddings, the splitter can understand the meaning of the text "
"and make informed decisions about where to cut."
* 5 # Repeat to make it long enough for splitting
)
# Choose an embedding model (e.g., from Hugging Face Hub)
# Ensure this model is suitable for your language and task
model_name = "BAAI/bge-small-en-v1.5"
# Initialize the tokenizer for the chosen model
# This is crucial for accurate token counting
tokenizer = AutoTokenizer.from_pretrained(model_name)
# Initialize the EmbeddingTextSplitter
# 'threshold' controls semantic similarity: higher = more similar chunks
# 'max_tokens' defines the maximum size of each chunk
embedding_splitter = EmbeddingTextSplitter(
tokenizer=tokenizer,
model_name=model_name,
threshold=0.5,
max_tokens=256
)
# Split the document into semantically coherent chunks
embedding_chunks = embedding_splitter.chunks(long_document_text)
print(f"Original text length: {len(long_document_text)} characters")
print(f"Number of chunks created: {len(embedding_chunks)}")
if embedding_chunks:
print(f"First chunk (length {len(embedding_chunks[0])} chars):\n---\n{embedding_chunks[0]}\n---")
print(f"Last chunk (length {len(embedding_chunks[-1])} chars):\n---\n{embedding_chunks[-1]}\n---")
# Example of CharacterTextSplitter (simpler, non-semantic)
from semantic_text_splitter import CharacterTextSplitter
character_splitter = CharacterTextSplitter(
tokenizer=tokenizer,
chunk_size=256,
chunk_overlap=30
)
char_chunks = character_splitter.chunks(long_document_text)
print(f"\nNumber of character chunks created: {len(char_chunks)}")
if char_chunks:
print(f"First char chunk (length {len(char_chunks[0])} chars):\n---\n{char_chunks[0]}\n---")
Debug
Known issues
gotchaPrior to version 0.14.0, `EmbeddingTextSplitter` might have implicitly handled tokenizer loading. Since v0.14.0, a `tokenizer` argument (from `transformers.AutoTokenizer`) is explicitly required during initialization, which is a common source of `TypeError` if not provided.fixAlways initialize your `EmbeddingTextSplitter` with `tokenizer=AutoTokenizer.from_pretrained(model_name)` alongside `model_name`.
affects: <0.14.0 to >=0.14.0
breakingVersion 0.28.0 refactored how embedding models are loaded, primarily relying on `sentence-transformers` for robustness and direct compatibility. Custom embedding functions or older integration patterns that bypassed `model_name` might no longer work as expected.fixEnsure you are passing a `model_name` compatible with `sentence-transformers` (e.g., from Hugging Face Hub). If using custom embedding logic, review the library's `_get_embeddings` method for current expected inputs.
affects: <0.28.0 to >=0.28.0
gotchaProcessing very large documents or using large `max_tokens` with GPU-enabled embedding models can lead to `RuntimeError: CUDA error: out of memory`. This is especially true if running on a limited VRAM GPU.fixReduce `max_tokens`, process text in smaller batches before passing to the splitter, or upgrade your GPU memory. Consider using CPU-only models or smaller models if memory is a significant constraint.
affects: All versions
gotchaThe `threshold` parameter in `EmbeddingTextSplitter` significantly impacts chunking behavior. A very high `threshold` can lead to many small chunks or even single-sentence chunks, while a very low `threshold` might result in excessively large chunks or not splitting at all, depending on the text's semantic density.fixExperiment with `threshold` values (e.g., 0.3 to 0.7 for common models like BGE) and `max_tokens` on a representative sample of your data to find an optimal balance for your use case.
affects: All versions
Upgrade
Version history
0.31.0latest on PyPI · released Jun 4, 2026
Audit
Dependencies
transformersrequiredRequired for tokenization (e.g., AutoTokenizer).
sentence-transformersrequiredRequired for embedding generation.
torchoptionalOften a dependency of sentence-transformers, required for GPU acceleration.