Refactor Qdrant monitoring and performance skills: flatten architecture - #88
Refactor Qdrant monitoring and performance skills: flatten architecture#88chadha-sridi wants to merge 4 commits into
Conversation
✅ Deploy Preview for qdrant-skills ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Thank you for this PR, I think this is a valuable improvement.
I think flattening these skills surfaces an overlap the hub previously hid. Both qdrant-search-speed and qdrant-scaling (this PR in its current form does not touch it) lists throughput issues in the description:
search-speed:low QPSandthroughput too lowscaling:need more throughput,cluster is slow
As the PR flattens the skill hierarchy, now these are on the same level, so they will likely compete. Also the body ofsearch-speedsays "Add replicas to distribute read load." (line 50), but I think it belongs rather toscalingthansearch-speed.
To fix this, I think we should make the distinction clear between tune and scale in a way that tune comes first and then scale when tuning is exhausted.
To do that:
-
We should get rid of "need more throughput" and "cluster is slow" from the description of
scalingand add something like:Guides Qdrant capacity and topology decisions: adding nodes, shards, or replicas, or splitting data across machines once a single node is already optimized and still can't keep up. Use when someone asks 'how many nodes do I need', 'data doesn't fit on one node', 'too many tenants', 'vertical or horizontal', 'how to shard', or 'need to add capacity'. For tuning an under-optimized node, see qdrant-search-speed.Or something along these lines. This suggestion is based on the current description and keeps everything that is relevant.
-
Delete the "Add replicas..." bullet in
search-speed. Replace it with something like: "If the node is already optimized (segments merged, quantization on, batching) and CPU is still saturated, that's a capacity limit: refer to qdrant-scaling."
If that's out-of-the-scope for this PR, then I think we need to open an issue and address that as soon as possible. However, I think these changes can fit into this PR as it would harmonize the skills' scopes according to the flattening effort.
I'd be curious to hear other people opinions, too, as I might miss some context.
| - OS page cache - memory used for caching disk reads, which can be released when needed. Original vectors are normally stored in page cache, so the service won't crash if RAM is full, but performance may degrade. | ||
|
|
||
| It is normal for the OS page cache to occupy all available RAM, but if resident memory is above 80% of total RAM, it is a sign of a problem. | ||
| [Memory article](https://qdrant.tech/articles/memory-consumption/) |
There was a problem hiding this comment.
You might want to add a more descriptive anchor text, so the agent will know why to follow it.
| [Memory article](https://qdrant.tech/articles/memory-consumption/) | |
| Refer to the [Memory consumption model](https://qdrant.tech/articles/memory-consumption/) for the full breakdown. |
Or something along these lines.
There was a problem hiding this comment.
Thanks for the detailed review and suggestions! I agree that flattening the skills makes this overlap more visible. I’ll take a closer look at the current qdrant-scaling and qdrant-search-speed scopes and think through the best separation between tuning vs scaling. I’ll come back with an update.
Co-authored-by: István Zoltán Szabó <istvan.zoltan.szabo@qdrant.com>
|
this PR has been inactive for 14 days. it will be closed in 7 days unless there is new activity. if you're still working on it, push an update or leave a comment. |
|
@chadha-sridi do you have additional changes you'd like to make to this? |
|
@kanungle Yes |
What this PR does
Restructures the performance and monitoring skill hierarchy: merges the diagnostic content from qdrant-monitoring/debugging into the three performance optimization sub-skills, so each skill covers both diagnosis and optimization in one place. Eliminates the redundancy and observed double-fetch pattern where agents loaded both monitoring/debugging and a performance skill for the same query.
Type
Checklist
python3 scripts/validate_skills.pypassesUse whenwith 5+ trigger phrasesallowed-tools, hub skills declare them## What NOT to Dosectionskills.qdrant.tech/md/documentation/Test prompt
Tested against a 16-prompt evaluation set across Opus 4.8, Sonnet, and Haiku 4.5, comparing v1 vs v2 routing behavior. Summary: Opus and Sonnet showed fewer turns on 15/16 and 12/16 prompts.
Example prompt