NoSQL 与搜索 / 知识点

向量数据库操作速查手册

手册条目

配置服务地址、认证信息和连接参数,并验证客户端能够正常访问向量数据库。

连接向量数据库

用于确认服务地址、API Key、TLS 与超时参数是否正确。以下命令以 Qdrant REST API 为基准:REST 默认通过 6333 端口访问,启用鉴权后请求需携带 api-key;生产环境应使用 HTTPS,避免凭据明文传输。:contentReference[oaicite:0]{index=0}

前置配置

将地址和密钥放入环境变量,避免直接写进脚本、Shell 历史或代码仓库。QDRANT_URL 应包含协议和端口,但末尾斜杠可有可无。

bash
export QDRANT_URL='https://<HOST>:<PORT>'
export QDRANT_API_KEY='<API_KEY>'

test -n "$QDRANT_URL" && test -n "$QDRANT_API_KEY"

预期结果:命令无输出且退出码为 0;缺少任一变量时退出码非 0。

连接验证

根路径会返回服务标识和版本信息,可同时验证 DNS、TCP、TLS、认证与 REST 服务。--connect-timeout 限制建连时间,--max-time 限制整个请求时间。

bash
curl --fail-with-body --silent --show-error \
  --connect-timeout 3 \
  --max-time 10 \
  --header "api-key: ${QDRANT_API_KEY}" \
  "${QDRANT_URL%/}"

预期输出

json
{"title":"qdrant - vector search engine","version":"<VERSION>","commit":"<COMMIT>"}

version 与 commit 会随实际部署变化。能收到该 JSON 说明网络、证书、密钥和服务入口均已通过;HTTP 401 或 403 表示认证或权限失败,连接超时通常表示地址、端口、防火墙或代理不可达。

常用连接参数

参数 建议值 作用
--connect-timeout 3~5 秒 控制 DNS、TCP、TLS 建连等待时间
--max-time 10~30 秒 防止请求无限挂起
--retry 2 仅幂等读取 缓解瞬时网络失败
--cacert <PATH> 私有 CA 场景 指定可信 CA 证书

风险与边界

使用 HTTP 发送 API Key 时,链路监听者可能窃取凭据;安全替代方案是启用 HTTPS,或在受控内网通过反向代理终止 TLS。:contentReference[oaicite:1]{index=1}

不要用 -k 或 --insecure 解决证书错误。该选项会跳过服务端身份校验,可能把密钥发送给伪造节点;应改为修复证书域名、完整证书链或通过 --cacert <PATH> 指定可信 CA。

连接成功只证明当前入口可访问,不代表目标集合存在、向量维度匹配或写入权限可用。上线前还应以最小权限密钥读取一个已知集合,必要时再执行隔离的测试写入。

排障清单

  • Could not resolve host:检查主机名、DNS 搜索域和代理变量。
  • Connection refused:检查端口映射、监听地址、安全组和容器状态。
  • SSL certificate problem:核对证书域名、有效期、证书链和本机 CA。
  • 401/403:确认密钥未带多余空格,且权限覆盖目标集群或集合。
  • 404:检查是否把管理 API 地址误当成数据库 REST 地址。

速查:先验证根路径,再验证已知集合;不要用关闭 TLS 校验的方式“修好”连接。

目录与阅读设置

记录一个想法

向量数据库操作速查手册

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通