Vector Search

Vector search enables semantic search across your data sources using Cloudflare Vectorize.

Overview

Features:

• Semantic similarity matching
• Fast nearest-neighbor search
• Automatic embedding generation
• Cross-source search

How It Works

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│    Query     │────▶│   Generate   │────▶│   Search     │
│    Input     │     │  Embedding   │     │  Vectorize   │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                  │
                                                  ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Return     │◀────│   Retrieve   │◀────│   Find Top   │
│   Results    │     │   Content    │     │   Matches    │
└──────────────┘     └──────────────┘     └──────────────┘

Searching

Via Dashboard

1. Navigate to Context
2. Enter search query
3. View ranked results

Via API

curl "https://your-domain.com/api/agents/{id}/sources/search?query=how+to+reset+password"

Response:

{
  "results": [
    {
      "id": "chunk-123",
      "source_id": "source-456",
      "content": "To reset your password, go to Settings...",
      "score": 0.92,
      "metadata": {
        "source_name": "User Guide",
        "page": 15
      }
    },
    {
      "id": "chunk-124",
      "content": "Password reset emails are sent within 5 minutes...",
      "score": 0.85
    }
  ]
}

Search Parameters

Basic Search

{
  "query": "how to integrate API",
  "limit": 10
}

Filtered Search

{
  "query": "installation guide",
  "filter": {
    "source_id": "source-123",
    "metadata.category": "technical"
  },
  "limit": 5
}

Threshold Search

{
  "query": "error handling",
  "min_score": 0.7,
  "limit": 20
}

Embeddings

Model

Using Cloudflare Workers AI:

• Model: @cf/baai/bge-base-en-v1.5
• Dimensions: 768
• Metric: Cosine similarity

Generation

Embeddings are generated automatically:

const embedding = await env.AI.run(
  '@cf/baai/bge-base-en-v1.5',
  { text: content }
)

Vectorize Configuration

Index Settings

[[vectorize]]
binding = "VECTORIZE"
index_name = "agents-dashboard-embeddings"

Index properties:

• Dimensions: 768
• Metric: cosine
• Max vectors: Based on plan

Search Strategies

Semantic Search

Natural language queries:

"How do I cancel my subscription?"
"What are the payment options?"

Keyword + Semantic

Combine exact and semantic:

{
  "query": "refund policy",
  "keywords": ["cancel", "money back"],
  "boost_keywords": 0.3
}

Multi-Query

Search with variations:

{
  "queries": [
    "password reset",
    "forgot password",
    "change password"
  ],
  "merge": "union"
}

Integration

With Chat

Automatic RAG in conversations:

// Agent automatically searches relevant context
const context = await searchSources(query)
const response = await generateWithContext(query, context)

With Workflows

{
  "type": "search-sources",
  "data": {
    "query": "{{input.question}}",
    "limit": 3
  },
  "output": "search_results"
}

With Tools

Enable as an agent tool:

{
  "name": "search_knowledge",
  "description": "Search the knowledge base",
  "parameters": {
    "query": {
      "type": "string",
      "description": "Search query"
    }
  }
}

Performance

Optimization Tips

1. Limit results: Request only needed results
2. Use filters: Narrow search scope
3. Cache common queries: Store frequent searches
4. Batch queries: Combine related searches

Metrics

Monitor search performance:

• Query latency
• Result relevance
• Cache hit rate

Best Practices

1. Quality Content

Better content = better results:

• Clear, well-written text
• Proper structure
• Consistent terminology

2. Appropriate Chunk Size

Balance context and precision:

{
  "chunking": {
    "max_size": 500,
    "overlap": 50
  }
}

3. Metadata Filtering

Use metadata for precision:

{
  "filter": {
    "metadata.product": "pro",
    "metadata.version": "2.0"
  }
}

4. Score Thresholds

Filter low-quality matches:

{
  "min_score": 0.75
}

5. Regular Updates

Keep embeddings current:

• Refresh on content changes
• Re-index periodically

Troubleshooting

Poor Results

1. Check source content quality
2. Verify chunking settings
3. Adjust score thresholds
4. Review search queries

Slow Searches

1. Reduce result limit
2. Add filters
3. Check index health
4. Consider caching

Missing Content

1. Verify source is indexed
2. Check processing status
3. Ensure content is chunked
4. Validate embeddings exist

API Reference

See Sources API for complete endpoint documentation.