Chunking
Split documents into smaller pieces for effective vector search.
Chunking divides content into smaller pieces before embedding and storing in a vector database. The strategy you choose affects search quality and retrieval accuracy.
For this semantic/PDF configuration, follow the semantic chunking setup, including its reader and embedding dependencies.
from agno.knowledge.chunking.semantic import SemanticChunking
from agno.knowledge.reader.pdf_reader import PDFReader
reader = PDFReader(
chunking_strategy=SemanticChunking(),
)Why Chunking Matters
Consider processing a recipe book with different strategies:
| Strategy | Result |
|---|---|
| Fixed Size (5000 chars) | May split recipes mid-instruction |
| Semantic | Groups text by semantic similarity; complete recipes are not guaranteed |
| Document | Splits paragraphs and, when needed, sentences |
Compare retrieved chunks against representative questions to choose useful boundaries.
Available Strategies
Fixed Size
Split into uniform chunks by character count
Semantic
Split at natural breakpoints based on meaning
Recursive
Split using multiple separators hierarchically
Document
Split at paragraph and sentence boundaries
Markdown
Optionally split at headings with split_on_headings
CSV Row
Each row becomes a chunk
Agentic
AI determines optimal boundaries
Code
Split at function and class boundaries using AST analysis
Custom
Build your own strategy
Using with Readers
Pass a chunking strategy to any reader:
from agno.knowledge.knowledge import Knowledge
from agno.knowledge.chunking.fixed import FixedSizeChunking
from agno.knowledge.reader.pdf_reader import PDFReader
from agno.vectordb.pgvector import PgVector
reader = PDFReader(
chunking_strategy=FixedSizeChunking(chunk_size=3000),
)
knowledge = Knowledge(
vector_db=PgVector(table_name="docs", db_url=db_url),
)
knowledge.insert(path="documents/", reader=reader)Choosing a Strategy
| Content Type | Recommended Strategy | Why |
|---|---|---|
| General text | Semantic | Groups semantically similar text; evaluate the boundaries |
| Structured docs | Document | Uses paragraph and sentence boundaries |
| Markdown files | Markdown | Enable heading-based splitting when needed |
| CSV/tabular data | CSV Row | Each row is a logical unit |
| Source code | Code | Splits at function and class boundaries |
| Mixed content | Recursive | Handles multiple separator types |
| Need consistency | Fixed Size | Predictable chunk dimensions |
Each reader has a sensible default, but you can override it based on your content and retrieval needs.
Configuration
Most strategies accept configuration options:
from agno.knowledge.chunking.fixed import FixedSizeChunking
from agno.knowledge.chunking.recursive import RecursiveChunking
from agno.knowledge.chunking.semantic import SemanticChunking
# Fixed size with overlap
FixedSizeChunking(
chunk_size=5000, # Characters per chunk
overlap=200, # Overlap between chunks
)
# Semantic with threshold
SemanticChunking(
similarity_threshold=0.7, # Higher = more splits
)
# Recursive with smaller chunks
RecursiveChunking(
chunk_size=4000,
overlap=100,
)Chunk Size Guidelines
These are starting points for character-sized strategies, not universal defaults. Semantic and code chunking use their configured tokenizer; consult each strategy’s units and defaults. Document and Markdown chunk sizes are targets and may be exceeded.
| Chunk Size | Trade-off |
|---|---|
| Small (1000-3000 chars) | More precise retrieval, may lose context |
| Medium (5000 chars) | Balanced precision and context |
| Large (8000+ chars) | More context, less targeted results |
Smaller chunks work better for specific questions. Larger chunks work better when context matters.