Back to Details

qdrant-advisor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Qdrant Troubleshooting & Advisory

Qdrant故障排查与咨询

Core principle

核心原则

Do not answer Qdrant questions from memory. Qdrant evolves quickly (new endpoints, metrics, defaults, and deployment patterns land often), and the authoritative, current guidance lives at 
skills.qdrant.tech
as a hierarchy of agent skills. Your job is to load the relevant skill context live, then ground your diagnosis in it — loading only the branch that matches the problem, never the whole tree.
You are consuming these skills as context. You are not installing them and nothing needs to be installed.
不要凭记忆回答Qdrant相关问题。Qdrant的迭代速度很快（新的端点、指标、默认配置和部署模式经常推出），而权威的最新指导内容以Agent技能层级的形式存储在
skills.qdrant.tech
。你的任务是实时加载相关技能上下文，然后基于此进行诊断——仅加载与问题匹配的分支，而非整个技能树。你只是将这些技能作为上下文来使用，无需安装它们，也不需要安装任何东西。

The knowledge source

知识来源

  • Search: 
    https://skills.qdrant.tech/search?query=your+query+here
  • The structure is hierarchical: top-level skill 
    SKILL.md
    → sub-skill 
    SKILL.md
    → linked documentation pages. Each level narrows scope. Traverse it depth-first, following only the branch(es) that match the symptom.
  • 搜索：
    https://skills.qdrant.tech/search?query=your+query+here
  • 结构为层级式：顶级技能
    SKILL.md
    → 子技能
    SKILL.md
    → 关联的文档页面。每一层都会缩小范围。采用深度优先遍历方式，仅跟随与症状匹配的分支。

Workflow

工作流程

1. Frame the problem

1. 梳理问题

Pull out the concrete details before fetching anything:
  • The symptom(s) in the user's words (e.g. "memory keeps climbing", "queries got slow after a bulk upload", "results are irrelevant").
  • The deployment type (local, Docker, self-hosted, Cloud, embedded) and version, if known.
  • What changed recently (upgrade, new index, traffic spike, model swap).
Turn these into 1–3 short search phrases.
在获取任何内容之前，先提取具体细节：
  • 用户描述的症状（例如：“内存持续增长”、“批量上传后查询变慢”、“结果不相关”）。
  • 部署类型（本地、Docker、自托管、云服务、嵌入式）以及已知的版本。
  • 最近发生的变更（版本升级、新建索引、流量峰值、模型更换）。
将这些信息转化为1-3个简短的搜索短语。

2. Find the right skill(s)

2. 找到合适的技能

Use Search (fastest path to the right skill). Fetch 
https://skills.qdrant.tech/search?query=<your query>
, substituting your phrase for 
your+query+here
(encode spaces as 
+
or 
%20
). It returns the single most relevant top-level skill's 
SKILL.md
. Run it more than once for multi-part problems (e.g. one search for the memory symptom, one for the scaling question).
使用搜索（找到合适技能的最快途径）。 获取
https://skills.qdrant.tech/search?query=<your query>
，将你的搜索短语替换
your+query+here
（空格编码为
+
或
%20
）。它会返回单个最相关的顶级技能的
SKILL.md
。对于多部分问题，可多次运行搜索（例如，针对内存症状搜索一次，针对扩容问题再搜索一次）。

3. Traverse the hierarchy (deep and lateral)

3. 遍历层级结构（深度与横向）

Each 
SKILL.md
you load names its sub-skills (and often related skills and docs) as links. The hierarchy is not just two levels — a skill can nest several layers deep, and skills also reference each other laterally. Follow the links, not a fixed depth.
Descend (go deeper). A 
SKILL.md
is not necessarily a leaf just because you fetched it. If its sections themselves point to further 
SKILL.md
files, keep descending along the branch that matches the symptom — top-level → sub-skill → sub-sub-skill → … — until you reach a level whose guidance is concrete enough to act on (ordered diagnostic steps, exact endpoints/metrics, an explicit "what NOT to do" list). Don't stop early at an intermediate skill that only routes you onward.
Move laterally (go sideways). Real problems often span areas. Follow a link to a sibling or related skill when:
  • the current skill explicitly points to another (e.g. a debugging skill that says "if this is actually a capacity problem, see scaling"),
  • the symptom has more than one plausible cause living under different top-level skills (e.g. slow queries could be a monitoring/optimizer issue or a performance-optimization issue or a scaling issue), or
  • you ran multiple searches in step 2 and they surfaced different skills, each covering part of the problem.
Load each relevant branch, then reconcile what they say in step 4.
Stay disciplined about relevance. Going deep and going sideways is encouraged when the problem warrants it — but still load only branches that bear on the symptom. Don't sweep in unrelated siblings, and stop expanding once you can give a complete, grounded answer. The goal is "all the relevant context and nothing else," not "the whole tree."
Documentation pages. Skills link out to canonical docs (e.g. 
…/md/documentation/…
, 
qdrant.tech/documentation/…
, or 
qdrant.tech/articles/…
). Fetch these links exactly as the 
SKILL.md
provides them — they render as clean markdown natively. Pull a doc page only when you need detail a 
SKILL.md
references but does not itself contain.
你加载的每个
SKILL.md
都会将其子技能（通常还包括相关技能和文档）作为链接列出。层级结构不止两层——一个技能可以嵌套多层深度，技能之间也会横向相互引用。跟随链接即可，无需固定深度。
深度遍历（深入）。 你获取的
SKILL.md
不一定是叶子节点。如果其章节指向更多
SKILL.md
文件，请继续沿着与症状匹配的分支深入——顶级→子技能→子子技能→……——直到你达到指导内容足够具体可执行的层级（有序的诊断步骤、明确的端点/指标、清晰的“禁止操作”列表）。不要在仅作为路由的中间技能处过早停止。
横向遍历（跨域）。 实际问题往往涉及多个领域。在以下情况下，跟随链接到同级或相关技能：
  • 当前技能明确指向另一个技能（例如，某个调试技能提到“如果这实际上是容量问题，请查看扩容技能”），
  • 症状有多个可能的原因，分别属于不同的顶级技能（例如，查询缓慢可能是监控/优化器问题，或 性能优化问题，或 扩容问题），或者
  • 你在步骤2中进行了多次搜索，得到了不同的技能，每个技能覆盖问题的一部分。
加载每个相关分支，然后在步骤4中整合它们的内容。
严格保持相关性。 当问题需要时，鼓励进行深度和横向遍历——但仍仅加载与症状相关的分支。不要纳入无关的同级技能，一旦你能给出完整、有依据的答案，就停止扩展。目标是“获取所有相关上下文，无多余内容”，而非“获取整个技能树”。
文档页面。 技能会链接到官方文档（例如
…/md/documentation/…
、
qdrant.tech/documentation/…
或
qdrant.tech/articles/…
）。按照
SKILL.md
提供的链接准确获取这些页面——它们原生呈现为清晰的Markdown格式。仅当你需要
SKILL.md
引用但未包含的详细信息时，才获取文档页面。

4. Diagnose and advise

4. 诊断与建议

Synthesize an answer strictly from the loaded context:
  • State the most likely cause(s) in priority order — the skills often tell you what to check first (e.g. "check optimizer status before blaming search latency"); preserve that ordering.
  • Give concrete, ordered steps: the endpoints to hit, the metrics to read and their thresholds, the config to change.
  • Surface the skill's "what NOT to do" warnings explicitly — they prevent common self-inflicted damage.
  • Cite the canonical Qdrant doc URLs you relied on so the user can go deeper.
  • If the loaded context does not cover the case, say so plainly and either run a different search or fall back to the catalog — do not paper over the gap with remembered guesses.
严格基于加载的上下文整合答案：
  • 按优先级顺序列出最可能的原因——技能通常会告诉你先检查什么（例如“在归咎于搜索延迟之前，先检查优化器状态”）；请保留该顺序。
  • 提供具体、有序的步骤：要访问的端点、要查看的指标及其阈值、要修改的配置。
  • 明确列出技能中的**“禁止操作”**警告——这些警告可避免常见的人为错误。
  • 引用你所依赖的Qdrant官方文档URL，以便用户深入了解。
  • 如果加载的上下文未涵盖该情况，请直接说明，要么进行其他搜索，要么退回至目录——不要用记忆中的猜测来填补空白。

Operating notes

操作注意事项

  • Always fetch fresh every session. Never reuse a previously cached copy of a skill; the registry updates and staleness is exactly what this approach avoids.
  • Do not install anything. You are loading context only.
  • Fetching: every URL you need is either in this skill (root index, search base) or surfaced by a page you already fetched (links inside a 
    SKILL.md
    or the root index), so each is fetchable as-is. If a constructed search-query URL is ever rejected, fall back to fetching the root index and navigate from its absolute links.
  • 每次会话都要获取最新内容。切勿重复使用之前缓存的技能副本；技能注册表会更新，而这种方法正是为了避免内容过时。
  • 不要安装任何东西。你仅需加载上下文。
  • 获取内容：你需要的每个URL要么在此技能中（根索引、搜索基础URL），要么在你已获取的页面中（
    SKILL.md
    或根索引内的链接），因此可直接获取。如果构造的搜索查询URL被拒绝，请退回至获取根索引，并从其绝对链接开始导航。

Example Workflow

示例工作流程

  1. Symptom: "Our Qdrant node's RAM keeps climbing and it OOM-killed last night. Nothing obvious changed."
  2. Search: skills.qdrant.tech/search?query=qdrant+memory+growing+OOM
  3. Follow any sub-skill link on memory or debugging that the returned page names.
  4. Hop laterally to the scaling skill it references, if capacity is a plausible alternative cause.
  5. Synthesize from what you loaded; cite the doc URLs. If nothing loaded covers the case, say so; don't fill from memory.
  1. 症状：“我们的Qdrant节点内存持续增长，昨晚因OOM被终止。没有明显的变更。”
  2. 搜索：skills.qdrant.tech/search?query=qdrant+memory+growing+OOM
  3. 跟随返回页面中列出的任何与内存或调试相关的子技能链接。
  4. 如果容量是可能的替代原因，横向跳转到它引用的扩容技能。
  5. 基于加载的内容整合答案；引用文档URL。如果加载的内容未涵盖该情况，请直接说明；不要凭记忆填补。