qdrant-advanced
Advanced Qdrant vector database operations for AI agents. Semantic search, contextual document ingestion with chunking, collection management, snapshots, and migration tools. Production-ready scripts for the complete Qdrant lifecycle. Use when: (1) Implementing semantic search across collections, (2) Ingesting documents with intelligent chunking, (3) Managing collections programmatically, (4) Creating backups and migrations.
- License 许可
- MIT
- 最近更新
- 2026-06-07
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- qdrant-advanced
- version
- 1.0.0
- metadata
- { "author": "yoder-bawt", "homepage": "https://github.com/yoder-bawt", "openclaw": { "requires": { "env": [ "QDRANT_HOST", "QDRANT_PORT", "OPENAI_API_KEY" ], "bins": [ "curl", "python3", "bash" ], "config": [] }, "user-invocable": true } }
- description
- Advanced Qdrant vector database operations for AI agents. Semantic search, contextual document ingestion with chunking, collection management, snapshots, and migration tools. Production-ready scripts for the complete Qdrant lifecycle. Use when: (1) Implementing semantic search across collections, (2) Ingesting documents with intelligent chunking, (3) Managing collections programmatically, (4) Creating backups and migrations.
03 SKILL.md 正文
Qdrant Advanced
Production-ready Qdrant vector database operations for AI agents. Complete toolkit for semantic search, document ingestion, collection management, backups, and migrations.
Quick Start
# Set environment variables
export QDRANT_HOST="localhost"
export QDRANT_PORT="6333"
export OPENAI_API_KEY="sk-..."
# List collections
bash manage.sh list
# Create a collection
bash manage.sh create my_collection 1536 cosine
# Ingest a document
bash ingest.sh /path/to/document.txt my_collection paragraph
# Search
bash search.sh "my search query" my_collection 5
Scripts Overview
| Script | Purpose | Key Features |
|---|---|---|
search.sh |
Semantic search | Multi-collection, filters, score thresholds |
ingest.sh |
Document ingestion | Contextual chunking, batch upload, progress |
manage.sh |
Collection management | Create, delete, list, info, optimize |
backup.sh |
Snapshots | Full collection snapshots, restore, list |
migrate.sh |
Migrations | Collection-to-collection, embedding model upgrades |
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
QDRANT_HOST |
No | localhost |
Qdrant server hostname |
QDRANT_PORT |
No | 6333 |
Qdrant server port |
OPENAI_API_KEY |
Yes* | - | OpenAI API key for embeddings |
QDRANT_API_KEY |
No | - | Qdrant API key (if auth enabled) |
*Required for ingest and search operations
Detailed Usage
Semantic Search
bash search.sh <query> <collection> [limit] [filter_json]
Examples:
# Basic search
bash search.sh "machine learning tutorials" my_docs 10
# With metadata filter
bash search.sh "deployment guide" my_docs 5 '{"must": [{"key": "category", "match": {"value": "devops"}}]}'
# Score threshold
bash search.sh "error handling" my_docs 10 "" 0.8
Output:
{
"results": [
{
"id": "doc-001",
"score": 0.92,
"text": "When handling errors in production...",
"metadata": {"source": "docs/error-handling.md"}
}
]
}
Document Ingestion
bash ingest.sh <file_path> <collection> [chunk_strategy] [metadata_json]
Chunk Strategies:
| Strategy | Description | Best For |
|---|---|---|
paragraph |
Split by paragraphs (\n\n) | Articles, docs |
sentence |
Split by sentences | Short content |
fixed |
Fixed 1000 char chunks | Code, logs |
semantic |
Semantic boundaries | Long documents |
Examples:
# Ingest with paragraph chunking
bash ingest.sh article.md my_collection paragraph
# With custom metadata
bash ingest.sh api.md my_collection paragraph '{"category": "api", "version": "2.0"}'
# Ingest multiple files
for f in docs/*.md; do
bash ingest.sh "$f" my_collection paragraph
done
Collection Management
bash manage.sh <command> [args...]
Commands:
| Command | Arguments | Description |
|---|---|---|
list |
- | List all collections |
create |
name dim distance |
Create new collection |
delete |
name |
Delete collection |
info |
name |
Get collection info |
optimize |
name |
Optimize collection |
Examples:
bash manage.sh list
bash manage.sh create my_vectors 1536 cosine
bash manage.sh create my_vectors 768 euclid
bash manage.sh info my_vectors
bash manage.sh optimize my_vectors
bash manage.sh delete my_vectors
Backup & Restore
bash backup.sh <command> [args...]
Commands:
| Command | Arguments | Description |
|---|---|---|
snapshot |
collection [snapshot_name] |
Create snapshot |
restore |
collection snapshot_name |
Restore from snapshot |
list |
collection |
List snapshots |
delete |
collection snapshot_name |
Delete snapshot |
Examples:
# Create snapshot
bash backup.sh snapshot my_collection
bash backup.sh snapshot my_collection backup_2026_02_10
# List snapshots
bash backup.sh list my_collection
# Restore
bash backup.sh restore my_collection backup_2026_02_10
# Delete old snapshot
bash backup.sh delete my_collection old_backup
Migration
bash migrate.sh <source_collection> <target_collection> [options]
Migration Types:
- Copy Collection: Same embedding model, different name
- Model Upgrade: Upgrade to new embedding model (re-embeds)
- Filter Migration: Migrate subset with filter
Examples:
# Simple copy
bash migrate.sh old_collection new_collection
# With model upgrade (re-embeds all content)
bash migrate.sh old_collection new_collection --upgrade-model
# Filtered migration
bash migrate.sh old_collection new_collection --filter '{"category": "public"}'
# Batch size for large collections
bash migrate.sh old_collection new_collection --batch-size 50
Chunking Deep Dive
The ingest script provides intelligent chunking to preserve context:
Paragraph Chunking
- Splits on double newlines
- Preserves paragraph structure
- Adds overlap of 2 sentences between chunks
- Best for: Articles, documentation, blogs
Sentence Chunking
- Splits on sentence boundaries
- Minimal overlap
- Best for: Short content, tweets, quotes
Fixed Chunking
- Fixed 1000 character chunks
- 200 character overlap
- Best for: Code files, logs, unstructured text
Semantic Chunking
- Uses paragraph + header detection
- Preserves document structure
- Best for: Long documents with headers
API Reference
All scripts use Qdrant REST API:
GET /collections # List collections
PUT /collections/{name} # Create collection
DELETE /collections/{name} # Delete collection
GET /collections/{name} # Collection info
POST /collections/{name}/points/search # Search
PUT /collections/{name}/points # Upsert points
POST /snapshots # Create snapshot
GET /collections/{name}/snapshots # List snapshots
Full docs: https://qdrant.tech/documentation/
Performance Tips
- Batch uploads: ingest.sh automatically batches uploads (default 100)
- Optimize after bulk insert:
bash manage.sh optimize my_collection - Use filters: Narrow search scope with metadata filters
- Set score thresholds: Filter low-quality matches
- Index metadata: Add payload indexes for faster filtering
Troubleshooting
"Connection refused"
- Check Qdrant is running:
curl http://$QDRANT_HOST:$QDRANT_PORT/healthz - Verify host/port environment variables
"Collection not found"
- List collections:
bash manage.sh list - Check collection name spelling
"No search results"
- Verify documents were ingested:
bash manage.sh info my_collection - Check vector dimensions match (e.g., 1536 for text-embedding-3-small)
- Try lowering score threshold
Embedding errors
- Verify OPENAI_API_KEY is set
- Check API key has quota available
- Verify network access to OpenAI API
Snapshot fails
- Check disk space available
- Verify Qdrant has snapshot permissions
- For large collections, try during low-traffic periods
Requirements
- Qdrant server v1.0+
- curl, python3, bash
- OpenAI API key (for embeddings)
- Network access to Qdrant and OpenAI
See Also
- Qdrant Docs: https://qdrant.tech/documentation/
- OpenAI Embeddings: https://platform.openai.com/docs/guides/embeddings
- Vector Search Guide: https://qdrant.tech/documentation/concepts/search/
04 同仓库更多 Skills
crowd-prompting
A marketplace where AI agents improve prompts, system instructions, tool descriptions, and other text-based content with domain expertise from real-world operations — and earn tokens for valuable contributions.
ceaser
Interact with the Ceaser privacy protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- shield, unshield, note management, and protocol queries. All ceaser tool calls use CLI subcommands (npx -y ceaser-mcp <subcommand>). Ceaser is a privacy-preserving ETH wrapper using Noir/UltraHonk zero-knowledge proofs on Base L2 (chain ID 8453).
ceaser-send
Fully automated private ETH transfer via Ceaser Protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- all ceaser tool calls use CLI subcommands (npx -y ceaser-mcp <subcommand>). WARNING -- creates observable on-chain links between user wallet and hot wallet (see Privacy Warning). Generates an ephemeral hot wallet with BIP-39 mnemonic recovery, user funds it, agent signs and broadcasts the Shield TX automatically. Exactly one manual step required (funding the hot wallet with ETH). Uses Noir/UltraHonk zero-knowledge proofs.
dilemm-ai
Compete in DilemmAI, the prisoner's dilemma AI arena at dilemm.ai. Use when an OpenClaw agent wants to create an account, design and submit strategy prompts for their bot, enter matchmaking, analyze historical matches and leaderboards, and iterate on bot strategy. Requires headless browser automation (no API available yet).
moldium
Post and manage content on the Moldium blog platform. Triggered by "post to Moldium", "write a blog post", "publish an article", etc.
arxiv-paper-reviews
Interact with arXiv Crawler API to fetch papers, read reviews, submit comments, search papers, and import papers. Use when working with arXiv papers, fetching paper lists by date/category/interest, viewing paper details with comments, submitting paper reviews, searching papers by title, or importing papers from arXiv URLs via API at http://weakaccept.top:8000/.